Skip to content

MIGRATING.md

Latest commit

 

History

History
77 lines (55 loc) · 4.82 KB

MIGRATING.md

File metadata and controls

77 lines (55 loc) · 4.82 KB

Migrating from v0.x to v1.x

This guide covers the API and packaging changes between v0.x and v1.x.

Initialization and import

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"

Class-based constructors

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(…)

Automatic memory cleanup

Instead of manually calling .destroy(), WASM objects are now reclaimed automatically using FinalizationRegistry. There are no longer any .destroy() methods.

String/number arguments replaced with enums

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

Renames

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() removed

The 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 undefined

null 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