This guide covers the API and packaging changes between v0.x and v1.x.
The package is now an ES module. WASM initialization happens at module load time via top-level await.
| v0.x | v1.x |
|---|---|
require("harfbuzzjs").then((hb) => …) |
import { Blob, Face, … } from "harfbuzzjs" |
Instead of using factory functions, we now export classes with constructors.
| v0.x | v1.x |
|---|---|
hb.createBlob(…) |
new hb.Blob(…) |
hb.createFace(…) |
new hb.Face(…) |
hb.createFont(…) |
new hb.Font(…) |
hb.createFontFuncs(…) |
new hb.FontFuncs(…) |
hb.createBuffer(…) |
new hb.Buffer(…) |
Instead of manually calling .destroy(), WASM objects are now reclaimed automatically using FinalizationRegistry. There are no longer any .destroy() methods.
Several APIs that took string codes or magic numbers now take typed enum values exported from the package.
| API | v0.x | v1.x |
|---|---|---|
Buffer.setDirection |
setDirection("ltr") |
setDirection(Direction.LTR) |
Buffer.setFlags |
["BOT", "PRODUCE_UNSAFE_TO_CONCAT"] |
BufferFlag.BOT | BufferFlag.PRODUCE_UNSAFE_TO_CONCAT |
Buffer.serialize format |
"JSON" |
BufferSerializeFormat.JSON |
Buffer.serialize flags |
["NO_GLYPH_NAMES", "NO_ADVANCES"] |
BufferSerializeFlag.NO_GLYPH_NAMES | BufferSerializeFlag.NO_ADVANCES |
Face.getGlyphClass return |
"BASE_GLYPH" |
GlyphClass.BASE_GLYPH |
shapeWithTrace stop_phase |
1 |
TracePhase.GSUB |
| v0.x | v1.x |
|---|---|
face.reference_table(tag) |
face.referenceTable(tag) |
hb.version_string() |
hb.versionString() |
GlyphPosition.x_advance |
GlyphPosition.xAdvance |
GlyphPosition.y_advance |
GlyphPosition.yAdvance |
GlyphPosition.x_offset |
GlyphPosition.xOffset |
GlyphPosition.y_offset |
GlyphPosition.yOffset |
Buffer.json() removedThe Buffer.json() shortcut has been removed. Use the typed accessors instead:
Buffer.getGlyphInfos() for glyph IDs, clusters, and flags.Buffer.getGlyphPositions() for advances and offsets.Buffer.getGlyphInfosAndPositions() for both combined.When you need the raw HarfBuzz JSON output (e.g. to capture all fields including glyph names), call Buffer.serialize() with BufferSerializeFormat.JSON and JSON.parse() the result yourself.
null replaced with undefinednull is no longer used anywhere in the API. Anything that previously returned, accepted, or held null now uses undefined instead.
Affected APIs:
Buffer.serialize now takes a single options object: { font, start, end, format, flags } (all optional). The previous positional signature is gone.shape and shapeWithTrace now take Feature[] instead of a comma-separated string. Use the new Feature class (e.g. new Feature("liga", 0) or Feature.fromString("-liga")).Font.setVariations now takes Variation[] instead of Record<string, number>. Use the new Variation class (e.g. font.setVariations([new Variation("wght", 700)]) or Variation.fromString("wght=700")).Buffer.addText / Buffer.addCodePoints: itemLength accepts undefined (or omission), instead of null.Face.getFeatureNameIds: returns undefined on failure, instead of null.Font.glyphHOrigin / glyphVOrigin / glyphExtents / glyphFromName: return undefined on failure, instead of null.FontFuncs.set*Func callbacks: return undefined on failure, instead of null.FeatureNameIds fields uiLabelNameId, uiTooltipTextNameId, sampleTextNameId: are now optional