@cantoo/fontkit 2.0.5 → 2.0.6

package/src/tables/WOFF2Directory.js

@@ -1,6 +1,19 @@
 import * as r from 'restructure';
 
+/** @typedef {import('restructure').BaseType} BaseType */
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('../../types/fontkit').TableEntry} TableEntry */
+
+/**
+ * WOFF2 variable-length unsigned integer (Base128).
+ * @type {BaseType}
+ */
 const Base128 = {
+  /**
+   * @param {DecodeStream} stream
+   * @returns {number}
+   */
   decode(stream) {
     let result = 0;
     let iterable = [0, 1, 2, 3, 4];
@@ -34,14 +47,46 @@ let knownTags = [
 
 let WOFF2DirectoryEntry = new r.Struct({
   flags: r.uint8,
-  customTag: new r.Optional(new r.String(4), t => (t.flags & 0x3f) === 0x3f),
-  tag: t => t.customTag || knownTags[t.flags & 0x3f], // || (() => { throw new Error(`Bad tag: ${flags & 0x3f}`); })(); },
+  customTag: new r.Optional(
+    new r.String(4),
+    /** @param {StructValue} t @returns {boolean} */
+    t => (/** @type {number} */ (t.flags) & 0x3f) === 0x3f
+  ),
+  /**
+   * @param {StructValue} t
+   * @returns {string}
+   */
+  tag: (t) => {
+    let flags = /** @type {number} */ (t.flags);
+    return /** @type {string} */ (t.customTag) || knownTags[flags & 0x3f];
+  },
   length: Base128,
-  transformVersion: t => (t.flags >>> 6) & 0x03,
-  transformed: t => (t.tag === 'glyf' || t.tag === 'loca') ? t.transformVersion === 0 : t.transformVersion !== 0,
-  transformLength: new r.Optional(Base128, t => t.transformed)
+  /**
+   * @param {StructValue} t
+   * @returns {number}
+   */
+  transformVersion: t => (/** @type {number} */ (t.flags) >>> 6) & 0x03,
+  /**
+   * @param {StructValue} t
+   * @returns {boolean}
+   */
+  transformed: t => (t.tag === 'glyf' || t.tag === 'loca')
+    ? t.transformVersion === 0
+    : t.transformVersion !== 0,
+  transformLength: new r.Optional(
+    Base128,
+    /** @param {StructValue} t @returns {boolean} */
+    t => !!t.transformed
+  )
 });
 
+/**
+ * @typedef {StructValue & {
+ *   tables: TableEntry[] | Record<string, TableEntry>
+ * }} WOFF2DirectoryValue
+ */
+
+/** @type {import('restructure').Struct} */
 let WOFF2Directory = new r.Struct({
   tag: new r.String(4), // should be 'wOF2'
   flavor: r.uint32,
@@ -61,13 +106,16 @@ let WOFF2Directory = new r.Struct({
 });
 
 WOFF2Directory.process = function () {
+  let self = /** @type {WOFF2DirectoryValue} */ (this);
+  /** @type {Record<string, TableEntry>} */
   let tables = {};
-  for (let i = 0; i < this.tables.length; i++) {
-    let table = this.tables[i];
+  let list = /** @type {TableEntry[]} */ (self.tables);
+  for (let i = 0; i < list.length; i++) {
+    let table = list[i];
     tables[table.tag] = table;
   }
 
-  return this.tables = tables;
+  self.tables = tables;
 };
 
 export default WOFF2Directory;

package/src/tables/WOFFDirectory.js

@@ -1,5 +1,14 @@
 import * as r from 'restructure';
 
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('../../types/fontkit').TableEntry} TableEntry */
+
+/**
+ * @typedef {StructValue & {
+ *   tables: TableEntry[] | Record<string, TableEntry>
+ * }} WOFFDirectoryValue
+ */
+
 let WOFFDirectoryEntry = new r.Struct({
   tag: new r.String(4),
   offset: new r.Pointer(r.uint32, 'void', { type: 'global' }),
@@ -8,6 +17,7 @@ let WOFFDirectoryEntry = new r.Struct({
   origChecksum: r.uint32
 });
 
+/** @type {import('restructure').Struct} */
 let WOFFDirectory = new r.Struct({
   tag: new r.String(4), // should be 'wOFF'
   flavor: r.uint32,
@@ -26,12 +36,14 @@ let WOFFDirectory = new r.Struct({
 });
 
 WOFFDirectory.process = function () {
+  let self = /** @type {WOFFDirectoryValue} */ (this);
+  /** @type {Record<string, TableEntry>} */
   let tables = {};
-  for (let table of this.tables) {
+  for (let table of /** @type {TableEntry[]} */ (self.tables)) {
     tables[table.tag] = table;
   }
 
-  this.tables = tables;
+  self.tables = tables;
 };
 
 export default WOFFDirectory;

package/src/tables/aat.js

@@ -1,64 +1,135 @@
 import * as r from 'restructure';
 
+/** @typedef {import('restructure').BaseType} BaseType */
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').EncodeStream} EncodeStream */
+/** @typedef {import('restructure').StructFields} StructFields */
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('restructure').VersionedStruct} VersionedStruct */
+
+/**
+ * Lazy random-access view over an unbounded run of encoded items.
+ */
 class UnboundedArrayAccessor {
+  /**
+   * @param {BaseType} type
+   * @param {DecodeStream} stream
+   * @param {StructValue | null | undefined} parent
+   */
   constructor(type, stream, parent) {
+    /** @type {BaseType} */
     this.type = type;
+    /** @type {DecodeStream} */
     this.stream = stream;
+    /** @type {StructValue | null | undefined} */
     this.parent = parent;
+    /** @type {number} */
     this.base = this.stream.pos;
+    /** @type {unknown[]} */
     this._items = [];
   }
 
+  /**
+   * @param {number} index
+   * @returns {unknown}
+   */
   getItem(index) {
     if (this._items[index] == null) {
       let pos = this.stream.pos;
-      this.stream.pos = this.base + this.type.size(null, this.parent) * index;
-      this._items[index] = this.type.decode(this.stream, this.parent);
+      let itemSize = this.type.size?.(null, this.parent);
+      this.stream.pos = this.base + /** @type {number} */ (itemSize) * index;
+      this._items[index] = this.type.decode?.(this.stream, this.parent);
       this.stream.pos = pos;
     }
 
     return this._items[index];
   }
 
+  /**
+   * @returns {string}
+   */
   inspect() {
-    return `[UnboundedArray ${this.type.constructor.name}]`;
+    let name = this.type.constructor && this.type.constructor.name
+      ? this.type.constructor.name
+      : 'Type';
+    return `[UnboundedArray ${name}]`;
   }
 }
 
-export class UnboundedArray extends r.Array {
+/**
+ * Array whose length is not stored; consumers index via getItem().
+ * @implements {BaseType}
+ */
+export class UnboundedArray {
+  /**
+   * @param {BaseType} type
+   */
   constructor(type) {
-    super(type, 0);
+    /** @type {BaseType} */
+    this.type = type;
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue | null | undefined} parent
+   * @returns {UnboundedArrayAccessor}
+   */
   decode(stream, parent) {
     return new UnboundedArrayAccessor(this.type, stream, parent);
   }
 }
 
-export let LookupTable = function (ValueType = r.uint16) {
-  // Helper class that makes internal structures invisible to pointers
+/**
+ * @param {BaseType} [ValueType]
+ * @returns {VersionedStruct}
+ */
+export function LookupTable(ValueType = r.uint16) {
+  /**
+   * Re-parents decode/encode so internal lookup structs stay invisible to pointers.
+   * @implements {BaseType}
+   */
   class Shadow {
+    /**
+     * @param {BaseType} type
+     */
     constructor(type) {
+      /** @type {BaseType} */
       this.type = type;
     }
 
+    /**
+     * @param {DecodeStream} stream
+     * @param {StructValue | null | undefined} ctx
+     * @returns {unknown}
+     */
     decode(stream, ctx) {
-      ctx = ctx.parent.parent;
-      return this.type.decode(stream, ctx);
+      let parent = ctx && ctx.parent && ctx.parent.parent ? ctx.parent.parent : ctx;
+      return this.type.decode?.(stream, parent);
     }
 
+    /**
+     * @param {unknown} val
+     * @param {StructValue | null | undefined} ctx
+     * @returns {number}
+     */
     size(val, ctx) {
-      ctx = ctx.parent.parent;
-      return this.type.size(val, ctx);
+      let parent = ctx && ctx.parent && ctx.parent.parent ? ctx.parent.parent : ctx;
+      return /** @type {number} */ (this.type.size?.(val, parent));
     }
 
+    /**
+     * @param {EncodeStream | null} stream
+     * @param {unknown} val
+     * @param {StructValue | null | undefined} ctx
+     * @returns {unknown}
+     */
     encode(stream, val, ctx) {
-      ctx = ctx.parent.parent;
-      return this.type.encode(stream, val, ctx);
+      let parent = ctx && ctx.parent && ctx.parent.parent ? ctx.parent.parent : ctx;
+      return this.type.encode?.(stream, val, parent);
     }
   }
 
-  ValueType = new Shadow(ValueType);
+  let shadowed = new Shadow(ValueType);
 
   let BinarySearchHeader = new r.Struct({
     unitSize: r.uint16,
@@ -71,44 +142,69 @@ export let LookupTable = function (ValueType = r.uint16) {
   let LookupSegmentSingle = new r.Struct({
     lastGlyph: r.uint16,
     firstGlyph: r.uint16,
-    value: ValueType
+    value: shadowed
   });
 
   let LookupSegmentArray = new r.Struct({
     lastGlyph: r.uint16,
     firstGlyph: r.uint16,
-    values: new r.Pointer(r.uint16, new r.Array(ValueType, t => t.lastGlyph - t.firstGlyph + 1), { type: 'parent' })
+    values: new r.Pointer(
+      r.uint16,
+      new r.Array(
+        shadowed,
+        /** @param {StructValue} t @returns {number} */
+        t => /** @type {number} */ (t.lastGlyph) - /** @type {number} */ (t.firstGlyph) + 1
+      ),
+      { type: 'parent' }
+    )
   });
 
   let LookupSingle = new r.Struct({
     glyph: r.uint16,
-    value: ValueType
+    value: shadowed
   });
 
   return new r.VersionedStruct(r.uint16, {
     0: {
-      values: new UnboundedArray(ValueType) // length == number of glyphs maybe?
+      values: new UnboundedArray(shadowed) // length == number of glyphs maybe?
     },
     2: {
       binarySearchHeader: BinarySearchHeader,
-      segments: new r.Array(LookupSegmentSingle, t => t.binarySearchHeader.nUnits)
+      segments: new r.Array(
+        LookupSegmentSingle,
+        /** @param {StructValue} t @returns {number} */
+        t => /** @type {number} */ (/** @type {StructValue} */ (t.binarySearchHeader).nUnits)
+      )
     },
     4: {
       binarySearchHeader: BinarySearchHeader,
-      segments: new r.Array(LookupSegmentArray, t => t.binarySearchHeader.nUnits)
+      segments: new r.Array(
+        LookupSegmentArray,
+        /** @param {StructValue} t @returns {number} */
+        t => /** @type {number} */ (/** @type {StructValue} */ (t.binarySearchHeader).nUnits)
+      )
     },
     6: {
       binarySearchHeader: BinarySearchHeader,
-      segments: new r.Array(LookupSingle, t => t.binarySearchHeader.nUnits)
+      segments: new r.Array(
+        LookupSingle,
+        /** @param {StructValue} t @returns {number} */
+        t => /** @type {number} */ (/** @type {StructValue} */ (t.binarySearchHeader).nUnits)
+      )
     },
     8: {
       firstGlyph: r.uint16,
       count: r.uint16,
-      values: new r.Array(ValueType, 'count')
+      values: new r.Array(shadowed, 'count')
     }
   });
-};
+}
 
+/**
+ * @param {StructFields} [entryData]
+ * @param {BaseType} [lookupType]
+ * @returns {import('restructure').Struct}
+ */
 export function StateTable(entryData = {}, lookupType = r.uint16) {
   let entry = Object.assign({
     newState: r.uint16,
@@ -116,21 +212,31 @@ export function StateTable(entryData = {}, lookupType = r.uint16) {
   }, entryData);
 
   let Entry = new r.Struct(entry);
-  let StateArray = new UnboundedArray(new r.Array(r.uint16, t => t.nClasses));
+  let StateArray = new UnboundedArray(
+    new r.Array(
+      r.uint16,
+      /** @param {StructValue} t @returns {number} */
+      t => /** @type {number} */ (t.nClasses)
+    )
+  );
 
-  let StateHeader = new r.Struct({
+  return new r.Struct({
     nClasses: r.uint32,
-    classTable: new r.Pointer(r.uint32, new LookupTable(lookupType)),
+    classTable: new r.Pointer(r.uint32, LookupTable(lookupType)),
     stateArray: new r.Pointer(r.uint32, StateArray),
     entryTable: new r.Pointer(r.uint32, new UnboundedArray(Entry))
   });
-
-  return StateHeader;
 }
 
-// This is the old version of the StateTable structure
+/**
+ * Old (16-bit) StateTable structure.
+ * @param {StructFields} [entryData]
+ * @param {BaseType} [_lookupType]
+ * @returns {import('restructure').Struct}
+ */
 export function StateTable1(entryData = {}, _lookupType = r.uint16) {
   let ClassLookupTable = new r.Struct({
+    /** @returns {number} */
     version() { return 8; }, // simulate LookupTable
     firstGlyph: r.uint16,
     values: new r.Array(r.uint8, r.uint16)
@@ -138,20 +244,39 @@ export function StateTable1(entryData = {}, _lookupType = r.uint16) {
 
   let entry = Object.assign({
     newStateOffset: r.uint16,
-    // convert offset to stateArray index
-    newState: t => (t.newStateOffset - (t.parent.stateArray.base - t.parent._startOffset)) / t.parent.nClasses,
+    /**
+     * Convert offset to stateArray index.
+     * @param {StructValue} t
+     * @returns {number}
+     */
+    newState: (t) => {
+      /**
+       * @typedef {{
+       *   stateArray: { base: number },
+       *   _startOffset: number,
+       *   nClasses: number
+       * }} StateParent
+       */
+      let parent = /** @type {StructValue & StateParent} */ (t.parent);
+      return (/** @type {number} */ (t.newStateOffset)
+        - (parent.stateArray.base - parent._startOffset)) / parent.nClasses;
+    },
     flags: r.uint16
   }, entryData);
 
   let Entry = new r.Struct(entry);
-  let StateArray = new UnboundedArray(new r.Array(r.uint8, t => t.nClasses));
+  let StateArray = new UnboundedArray(
+    new r.Array(
+      r.uint8,
+      /** @param {StructValue} t @returns {number} */
+      t => /** @type {number} */ (t.nClasses)
+    )
+  );
 
-  let StateHeader1 = new r.Struct({
+  return new r.Struct({
     nClasses: r.uint16,
     classTable: new r.Pointer(r.uint16, ClassLookupTable),
     stateArray: new r.Pointer(r.uint16, StateArray),
     entryTable: new r.Pointer(r.uint16, new UnboundedArray(Entry))
   });
-
-  return StateHeader1;
 }

package/src/tables/avar.js

@@ -12,6 +12,7 @@ let Segment = new r.Struct({
   correspondence: new r.Array(Correspondence, 'pairCount')
 });
 
+/** @type {import('restructure').Struct} */
 export default new r.Struct({
   version: r.fixed32,
   axisCount: r.uint32,

package/src/tables/bsln.js

@@ -8,7 +8,7 @@ let BslnSubtable = new r.VersionedStruct('format', {
 
   1: { // Distance-based, with mapping
     deltas: new r.Array(r.int16, 32),
-    mappingData: new LookupTable(r.uint16)
+    mappingData: LookupTable(r.uint16)
   },
 
   2: { // Control point-based, no mapping
@@ -19,10 +19,11 @@ let BslnSubtable = new r.VersionedStruct('format', {
   3: { // Control point-based, with mapping
     standardGlyph: r.uint16,
     controlPoints: new r.Array(r.uint16, 32),
-    mappingData: new LookupTable(r.uint16)
+    mappingData: LookupTable(r.uint16)
   }
 });
 
+/** @type {import('restructure').Struct} */
 export default new r.Struct({
   version: r.fixed32,
   format: r.uint16,

package/src/tables/cmap.js

@@ -1,5 +1,7 @@
 import * as r from 'restructure';
 
+/** @typedef {import('restructure').StructValue} StructValue */
+
 let SubHeader = new r.Struct({
   firstCode: r.uint16,
   entryCount: r.uint16,
@@ -43,16 +45,29 @@ let CmapSubtable = new r.VersionedStruct(r.uint16, {
     length: r.uint16,
     language: r.uint16,
     subHeaderKeys: new r.Array(r.uint16, 256),
-    subHeaderCount: t => Math.max.apply(Math, t.subHeaderKeys),
+    /**
+     * Keys store subHeaderIndex * 8; count is max index + 1.
+     * @param {StructValue} t
+     * @returns {number}
+     */
+    subHeaderCount: t => (Math.max.apply(Math, /** @type {number[]} */ (t.subHeaderKeys)) / 8) + 1,
     subHeaders: new r.LazyArray(SubHeader, 'subHeaderCount'),
-    glyphIndexArray: new r.LazyArray(r.uint16, 'subHeaderCount')
+    glyphIndexArray: new r.LazyArray(
+      r.uint16,
+      /** @param {StructValue} t @returns {number} */
+      t => (/** @type {number} */ (t.length) - /** @type {number} */ (t._currentOffset)) / 2
+    )
   },
 
   4: { // Segment mapping to delta values
     length: r.uint16, // Total table length in bytes
     language: r.uint16, // Language code
     segCountX2: r.uint16,
-    segCount: t => t.segCountX2 >> 1,
+    /**
+     * @param {StructValue} t
+     * @returns {number}
+     */
+    segCount: t => /** @type {number} */ (t.segCountX2) >> 1,
     searchRange: r.uint16,
     entrySelector: r.uint16,
     rangeShift: r.uint16,
@@ -61,7 +76,11 @@ let CmapSubtable = new r.VersionedStruct(r.uint16, {
     startCode: new r.LazyArray(r.uint16, 'segCount'),
     idDelta: new r.LazyArray(r.int16, 'segCount'),
     idRangeOffset: new r.LazyArray(r.uint16, 'segCount'),
-    glyphIndexArray: new r.LazyArray(r.uint16, t => (t.length - t._currentOffset) / 2)
+    glyphIndexArray: new r.LazyArray(
+      r.uint16,
+      /** @param {StructValue} t @returns {number} */
+      t => (/** @type {number} */ (t.length) - /** @type {number} */ (t._currentOffset)) / 2
+    )
   },
 
   6: { // Trimmed table
@@ -86,8 +105,8 @@ let CmapSubtable = new r.VersionedStruct(r.uint16, {
     length: r.uint32,
     language: r.uint32,
     firstCode: r.uint32,
-    entryCount: r.uint32,
-    glyphIndices: new r.LazyArray(r.uint16, 'numChars')
+    entryCount: r.uint32, // OpenType name: numChars
+    glyphIndices: new r.LazyArray(r.uint16, 'entryCount')
   },
 
   12: { // Segmented coverage
@@ -120,6 +139,7 @@ let CmapEntry = new r.Struct({
 });
 
 // character to glyph mapping
+/** @type {import('restructure').Struct} */
 export default new r.Struct({
   version: r.uint16,
   numSubtables: r.uint16,

package/src/tables/cvt.js

@@ -1,6 +1,7 @@
 import * as r from 'restructure';
 
 // An array of predefined values accessible by instructions
+/** @type {import('restructure').Struct} */
 export default new r.Struct({
   controlValues: new r.Array(r.int16)
 });

package/src/tables/directory.js

@@ -1,58 +1,86 @@
 import * as r from 'restructure';
 import Tables from './';
 
-let TableEntry = new r.Struct({
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('../../types/fontkit').TableEntry} TableEntry */
+/** @typedef {import('../../types/fontkit').TableCodec} TableCodec */
+
+/**
+ * @typedef {StructValue & {
+ *   tag: string,
+ *   numTables: number,
+ *   searchRange: number,
+ *   entrySelector: number,
+ *   rangeShift: number,
+ *   tables: TableEntry[] | Record<string, TableEntry>
+ * }} DirectoryValue
+ */
+
+let TableEntryStruct = new r.Struct({
   tag: new r.String(4),
   checkSum: r.uint32,
   offset: new r.Pointer(r.uint32, 'void', { type: 'global' }),
   length: r.uint32
 });
 
+/** @type {import('restructure').Struct} */
 let Directory = new r.Struct({
   tag: new r.String(4),
   numTables: r.uint16,
   searchRange: r.uint16,
   entrySelector: r.uint16,
   rangeShift: r.uint16,
-  tables: new r.Array(TableEntry, 'numTables')
+  tables: new r.Array(TableEntryStruct, 'numTables')
 });
 
 Directory.process = function () {
+  let self = /** @type {DirectoryValue} */ (this);
+  /** @type {Record<string, TableEntry>} */
   let tables = {};
-  for (let table of this.tables) {
+  for (let table of /** @type {TableEntry[]} */ (self.tables)) {
     tables[table.tag] = table;
   }
 
-  this.tables = tables;
+  self.tables = tables;
 };
 
 Directory.preEncode = function () {
-  if (!Array.isArray(this.tables)) {
+  let self = /** @type {DirectoryValue} */ (this);
+  if (!Array.isArray(self.tables)) {
+    /** @type {TableEntry[]} */
     let tables = [];
-    for (let tag in this.tables) {
-      let table = this.tables[tag];
+    /** @type {Record<string, TableEntry>} */
+    let byTag = self.tables;
+    for (let tag of Object.keys(byTag)) {
+      let table = byTag[tag];
       if (table) {
+        let codec = /** @type {TableCodec | undefined} */ (Tables[tag]);
+        if (!codec || typeof codec.size !== 'function') {
+          throw new Error(`Missing encoder for table "${tag}"`);
+        }
         tables.push({
           tag: tag,
           checkSum: 0,
-          offset: new r.VoidPointer(Tables[tag], table),
-          length: Tables[tag].size(table)
+          offset: /** @type {number} */ (/** @type {unknown} */ (
+            new r.VoidPointer(/** @type {import('restructure').BaseType} */ (/** @type {unknown} */ (codec)), table)
+          )),
+          length: codec.size(table)
         });
       }
     }
 
-    this.tables = tables;
+    self.tables = tables;
   }
 
-  this.tag = 'true';
-  this.numTables = this.tables.length;
+  self.tag = 'true';
+  self.numTables = self.tables.length;
 
-  let maxExponentFor2 = Math.floor((Math.log(this.numTables) / Math.LN2));
+  let maxExponentFor2 = Math.floor((Math.log(self.numTables) / Math.LN2));
   let maxPowerOf2 = Math.pow(2, maxExponentFor2);
 
-  this.searchRange = maxPowerOf2 * 16;
-  this.entrySelector = Math.log(maxPowerOf2) / Math.LN2;
-  this.rangeShift = this.numTables * 16 - this.searchRange;
+  self.searchRange = maxPowerOf2 * 16;
+  self.entrySelector = Math.log(maxPowerOf2) / Math.LN2;
+  self.rangeShift = self.numTables * 16 - self.searchRange;
 };
 
 export default Directory;