@cantoo/fontkit 2.0.5 → 2.0.7

package/src/TrueTypeCollection.js

@@ -2,6 +2,26 @@ import * as r from 'restructure';
 import TTFFont from './TTFFont';
 import { asciiDecoder } from './utils';
 
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('restructure').BinaryBuffer} BinaryBuffer */
+/** @typedef {import('../types/fontkit').NameString} NameString */
+
+/**
+ * @param {NameString | null | undefined} a
+ * @param {string | Uint8Array} b
+ * @returns {boolean}
+ */
+function postscriptNamesEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a instanceof Uint8Array && b instanceof Uint8Array) {
+    return a.length === b.length && a.every((v, i) => b[i] === v);
+  }
+  return false;
+}
+
 let TTCHeader = new r.VersionedStruct(r.uint32, {
   0x00010000: {
     numFonts: r.uint32,
@@ -16,35 +36,55 @@ let TTCHeader = new r.VersionedStruct(r.uint32, {
   }
 });
 
+/**
+ * @typedef {StructValue & { offsets: number[] }} TTCHeaderValue
+ */
+
 export default class TrueTypeCollection {
+  /** @type {string} */
   type = 'TTC';
 
+  /** @type {DecodeStream} */
+  stream;
+  /** @type {TTCHeaderValue} */
+  header;
+
+  /**
+   * @param {ArrayBufferView} buffer
+   * @returns {boolean}
+   */
   static probe(buffer) {
-    return asciiDecoder.decode(buffer.slice(0, 4)) === 'ttcf';
+    let bytes
+      = buffer instanceof Uint8Array
+        ? buffer
+        : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    return asciiDecoder.decode(bytes.subarray(0, 4)) === 'ttcf';
   }
 
+  /**
+   * @param {DecodeStream} stream
+   */
   constructor(stream) {
     this.stream = stream;
     if (stream.readString(4) !== 'ttcf') {
       throw new Error('Not a TrueType collection');
     }
 
-    this.header = TTCHeader.decode(stream);
+    this.header = /** @type {TTCHeaderValue} */ (
+      /** @type {unknown} */ (TTCHeader.decode(stream))
+    );
   }
 
+  /**
+   * @param {string | Uint8Array} name
+   * @returns {TTFFont | null}
+   */
   getFont(name) {
     for (let offset of this.header.offsets) {
       let stream = new r.DecodeStream(this.stream.buffer);
       stream.pos = offset;
       let font = new TTFFont(stream);
-      if (
-        font.postscriptName === name
-        || (
-          font.postscriptName instanceof Uint8Array
-          && name instanceof Uint8Array
-          && font.postscriptName.every((v, i) => name[i] === v)
-        )
-      ) {
+      if (postscriptNamesEqual(font.postscriptName, name)) {
         return font;
       }
     }
@@ -52,7 +92,11 @@ export default class TrueTypeCollection {
     return null;
   }
 
+  /**
+   * @type {TTFFont[]}
+   */
   get fonts() {
+    /** @type {TTFFont[]} */
     let fonts = [];
     for (let offset of this.header.offsets) {
       let stream = new r.DecodeStream(this.stream.buffer);

package/src/WOFF2Font.js

@@ -6,45 +6,98 @@ import WOFF2Glyph from './glyph/WOFF2Glyph';
 import WOFF2Directory from './tables/WOFF2Directory';
 import { asciiDecoder } from './utils';
 
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('restructure').BinaryBuffer} BinaryBuffer */
+/** @typedef {import('restructure').BaseType} BaseType */
+/** @typedef {import('../types/fontkit').FontDirectory} FontDirectory */
+/** @typedef {import('../types/fontkit').TableEntry} TableEntry */
+/** @typedef {import('../types/fontkit').TransformedGlyf} TransformedGlyf */
+/** @typedef {import('../types/fontkit').DecodedGlyf} DecodedGlyf */
+/** @typedef {import('./glyph/Glyph').default} Glyph */
+
 /**
  * Subclass of TTFFont that represents a TTF/OTF font compressed by WOFF2
  * See spec here: http://www.w3.org/TR/WOFF2/
+ *
+ * @property {number} [_dataPos] Byte offset of the compressed table data (set in `_decodeDirectory`).
  */
 export default class WOFF2Font extends TTFFont {
+  /** @type {string} */
   type = 'WOFF2';
 
+  // NOTE: Do not declare `_dataPos` as a class field. It is assigned in
+  // `_decodeDirectory()` during `super()`, and subclass field initializers
+  // run *after* `super()` returns — which would wipe the real offset.
+
+  /** @type {boolean | undefined} */
+  _decompressed;
+  /** @type {(TransformedGlyf | undefined)[] | undefined} */
+  _transformedGlyphs;
+
+  /**
+   * @param {ArrayBufferView} buffer
+   * @returns {boolean}
+   */
   static probe(buffer) {
-    return asciiDecoder.decode(buffer.slice(0, 4)) === 'wOF2';
+    let bytes
+      = buffer instanceof Uint8Array
+        ? buffer
+        : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    return asciiDecoder.decode(bytes.subarray(0, 4)) === 'wOF2';
   }
 
+  /** @returns {void} */
   _decodeDirectory() {
-    this.directory = WOFF2Directory.decode(this.stream);
+    this.directory = /** @type {FontDirectory} */ (
+      /** @type {unknown} */ (WOFF2Directory.decode(this.stream))
+    );
     this._dataPos = this.stream.pos;
   }
 
+  /** @returns {void} */
   _decompress() {
     // decompress data and setup table offsets if we haven't already
     if (!this._decompressed) {
-      this.stream.pos = this._dataPos;
-      let buffer = this.stream.readBuffer(this.directory.totalCompressedSize);
+      let dataPos = this._dataPos;
+      if (dataPos == null) {
+        throw new Error('Missing WOFF2 data offset; directory was not decoded');
+      }
+      this.stream.pos = dataPos;
+      let totalCompressedSize = this.directory.totalCompressedSize;
+      if (totalCompressedSize == null) {
+        throw new Error('Missing totalCompressedSize in WOFF2 directory');
+      }
+      let buffer = this.stream.readBuffer(totalCompressedSize);
 
       let decompressedSize = 0;
-      for (let tag in this.directory.tables) {
-        let entry = this.directory.tables[tag];
+      let tableMap = this.directory.tables;
+      for (let tag in tableMap) {
+        let entry = tableMap[tag];
+        if (!entry) {
+          continue;
+        }
         entry.offset = decompressedSize;
         decompressedSize += (entry.transformLength != null) ? entry.transformLength : entry.length;
       }
 
-      let decompressed = brotli(buffer, decompressedSize);
+      let decompressed = brotli(
+        buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength),
+        decompressedSize
+      );
       if (!decompressed) {
         throw new Error('Error decoding compressed data in WOFF2');
       }
 
-      this.stream = new r.DecodeStream(decompressed);
+      this._setStream(new r.DecodeStream(decompressed));
       this._decompressed = true;
     }
   }
 
+  /**
+   * @param {TableEntry} table
+   * @returns {unknown}
+   */
   _decodeTable(table) {
     this._decompress();
     return super._decodeTable(table);
@@ -52,13 +105,19 @@ export default class WOFF2Font extends TTFFont {
 
   // Override this method to get a glyph and return our
   // custom subclass if there is a glyf table.
+  /**
+   * @param {number} glyph
+   * @param {number[]} [characters]
+   * @returns {Glyph | null | undefined}
+   */
   _getBaseGlyph(glyph, characters = []) {
     let cached = this._glyphs[glyph];
-    if (cached?._getContours) {
+    if (cached && typeof (/** @type {{ _getContours?: unknown }} */ (cached))._getContours === 'function') {
       return cached;
     }
 
-    if (this.directory.tables.glyf && this.directory.tables.glyf.transformed) {
+    let glyfEntry = this.directory.tables.glyf;
+    if (glyfEntry && glyfEntry.transformed) {
       if (!this._transformedGlyphs) { this._transformGlyfTable(); }
       let outline = new WOFF2Glyph(glyph, characters, this);
       if (!cached) {
@@ -70,18 +129,27 @@ export default class WOFF2Font extends TTFFont {
     return super._getBaseGlyph(glyph, characters);
   }
 
+  /** @returns {void} */
   _transformGlyfTable() {
     this._decompress();
-    this.stream.pos = this.directory.tables.glyf.offset;
-    let table = GlyfTable.decode(this.stream);
+    let glyfEntry = this.directory.tables.glyf;
+    if (!glyfEntry) {
+      this._transformedGlyphs = [];
+      return;
+    }
+    this.stream.pos = glyfEntry.offset;
+    let table = /** @type {GlyfTableDecoded} */ (GlyfTable.decode(this.stream));
+    /** @type {TransformedGlyf[]} */
     let glyphs = [];
 
     for (let index = 0; index < table.numGlyphs; index++) {
-      let glyph = {};
+      /** @type {TransformedGlyf} */
+      let glyph = { numberOfContours: 0 };
       let nContours = table.nContours.readInt16BE();
       glyph.numberOfContours = nContours;
 
       if (nContours > 0) { // simple glyph
+        /** @type {number[]} */
         let nPoints = [];
         let totalPoints = 0;
 
@@ -93,12 +161,19 @@ export default class WOFF2Font extends TTFFont {
 
         glyph.points = decodeTriplet(table.flags, table.glyphs, totalPoints);
         for (let i = 0; i < nContours; i++) {
-          glyph.points[nPoints[i] - 1].endContour = true;
+          let pts = glyph.points;
+          if (pts) {
+            pts[nPoints[i] - 1].endContour = true;
+          }
         }
 
         read255UInt16(table.glyphs);
       } else if (nContours < 0) { // composite glyph
-        let haveInstructions = TTFGlyph.prototype._decodeComposite.call({ _font: this }, glyph, table.composites);
+        let haveInstructions = TTFGlyph.prototype._decodeComposite.call(
+          /** @type {TTFGlyph} */ (/** @type {unknown} */ ({ _font: this })),
+          /** @type {DecodedGlyf} */ (glyph),
+          table.composites
+        );
         if (haveInstructions) {
           read255UInt16(table.glyphs);
         }
@@ -111,13 +186,33 @@ export default class WOFF2Font extends TTFFont {
   }
 }
 
+/**
+ * @typedef {{
+ *   version: number,
+ *   numGlyphs: number,
+ *   nContours: DecodeStream,
+ *   nPoints: DecodeStream,
+ *   flags: DecodeStream,
+ *   glyphs: DecodeStream,
+ *   composites: DecodeStream
+ * }} GlyfTableDecoded
+ */
+
 // Special class that accepts a length and returns a sub-stream for that data
 class Substream {
+  /**
+   * @param {number | string} length
+   */
   constructor(length) {
     this.length = length;
     this._buf = new r.Buffer(length);
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue} parent
+   * @returns {DecodeStream}
+   */
   decode(stream, parent) {
     return new r.DecodeStream(this._buf.decode(stream, parent));
   }
@@ -149,6 +244,10 @@ const ONE_MORE_BYTE_CODE2 = 254;
 const ONE_MORE_BYTE_CODE1 = 255;
 const LOWEST_U_CODE = 253;
 
+/**
+ * @param {DecodeStream} stream
+ * @returns {number}
+ */
 function read255UInt16(stream) {
   let code = stream.readUInt8();
 
@@ -167,17 +266,30 @@ function read255UInt16(stream) {
   return code;
 }
 
+/**
+ * @param {number} flag
+ * @param {number} baseval
+ * @returns {number}
+ */
 function withSign(flag, baseval) {
   return flag & 1 ? baseval : -baseval;
 }
 
+/**
+ * @param {DecodeStream} flags
+ * @param {DecodeStream} glyphs
+ * @param {number} nPoints
+ * @returns {Point[]}
+ */
 function decodeTriplet(flags, glyphs, nPoints) {
   let y;
   let x = y = 0;
+  /** @type {Point[]} */
   let res = [];
 
   for (let i = 0; i < nPoints; i++) {
-    let dx, dy;
+    let dx = 0;
+    let dy = 0;
     let flag = flags.readUInt8();
     let onCurve = !(flag >> 7);
     flag &= 0x7f;

package/src/WOFFFont.js

@@ -4,17 +4,41 @@ import { unzlibSync } from 'fflate';
 import * as r from 'restructure';
 import { asciiDecoder } from './utils';
 
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').BinaryBuffer} BinaryBuffer */
+/** @typedef {import('../types/fontkit').FontDirectory} FontDirectory */
+/** @typedef {import('../types/fontkit').TableEntry} TableEntry */
+
 export default class WOFFFont extends TTFFont {
+  /** @type {string} */
   type = 'WOFF';
 
+  /** @type {boolean | undefined} */
+  _decompressed;
+
+  /**
+   * @param {ArrayBufferView} buffer
+   * @returns {boolean}
+   */
   static probe(buffer) {
-    return asciiDecoder.decode(buffer.slice(0, 4)) === 'wOFF';
+    let bytes
+      = buffer instanceof Uint8Array
+        ? buffer
+        : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    return asciiDecoder.decode(bytes.subarray(0, 4)) === 'wOFF';
   }
 
+  /** @returns {void} */
   _decodeDirectory() {
-    this.directory = WOFFDirectory.decode(this.stream, { _startOffset: 0 });
+    this.directory = /** @type {FontDirectory} */ (
+      /** @type {unknown} */ (WOFFDirectory.decode(this.stream, { _startOffset: 0 }))
+    );
   }
 
+  /**
+   * @param {TableEntry} table
+   * @returns {unknown}
+   */
   _decodeTable(table) {
     this._decompress();
     return super._decodeTable(table);
@@ -22,15 +46,21 @@ export default class WOFFFont extends TTFFont {
 
   // Inflate all tables into one stream so internal offsets (e.g. gvar) stay
   // valid against this.stream — same reason WOFF2Font decompresses up front.
+  /** @returns {void} */
   _decompress() {
     if (this._decompressed) {
       return;
     }
 
     let totalSize = 0;
+    /** @type {Array<{ entry: TableEntry, newOffset: number }>} */
     let layout = [];
-    for (let tag in this.directory.tables) {
-      let entry = this.directory.tables[tag];
+    let tableMap = this.directory.tables;
+    for (let tag in tableMap) {
+      let entry = tableMap[tag];
+      if (!entry) {
+        continue;
+      }
       layout.push({ entry, newOffset: totalSize });
       totalSize = (totalSize + entry.length + 3) & ~3;
     }
@@ -38,19 +68,26 @@ export default class WOFFFont extends TTFFont {
     let buffer = new Uint8Array(totalSize);
     for (let { entry, newOffset } of layout) {
       this.stream.pos = entry.offset;
+      /** @type {BinaryBuffer | Uint8Array} */
       let data;
-      if (entry.compLength < entry.length) {
-        data = unzlibSync(this.stream.readBuffer(entry.compLength), {
+      let compLength = entry.compLength != null ? entry.compLength : entry.length;
+      if (compLength < entry.length) {
+        let compressed = this.stream.readBuffer(compLength);
+        let compressedBytes
+          = compressed instanceof Uint8Array
+            ? compressed
+            : new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.byteLength);
+        data = unzlibSync(compressedBytes, {
           out: new Uint8Array(entry.length)
         });
       } else {
         data = this.stream.readBuffer(entry.length);
       }
-      buffer.set(data, newOffset);
+      buffer.set(data instanceof Uint8Array ? data : new Uint8Array(data.buffer, data.byteOffset, data.byteLength), newOffset);
       entry.offset = newOffset;
     }
 
-    this.stream = new r.DecodeStream(buffer);
+    this._setStream(new r.DecodeStream(buffer));
     this._decompressed = true;
   }
 }

package/src/aat/AATFeatureMap.js

@@ -1,5 +1,15 @@
 // see https://developer.apple.com/fonts/TrueType-Reference-Manual/RM09/AppendixF.html
 // and /System/Library/Frameworks/CoreText.framework/Versions/A/Headers/SFNTLayoutTypes.h on a Mac
+
+/** @typedef {import('../../types/fontkit').FeatureMap} FeatureMap */
+/** @typedef {import('../../types/fontkit').FeatureValue} FeatureValue */
+/** @typedef {import('../../types/fontkit').AATFeatureSettings} AATFeatureSettings */
+
+/**
+ * @typedef {{ code: number, exclusive: boolean, [selector: string]: number | boolean }} AATFeatureDef
+ */
+
+/** @type {Record<string, AATFeatureDef>} */
 const features = {
   allTypographicFeatures: {
     code: 0,
@@ -346,8 +356,17 @@ const features = {
   }
 };
 
-const feature = (name, selector) => [features[name].code, features[name][selector]];
+/**
+ * @param {string} name
+ * @param {string} selector
+ * @returns {[number, number]}
+ */
+const feature = (name, selector) => {
+  let f = features[name];
+  return [(f.code), /** @type {number} */ (f[selector])];
+};
 
+/** @type {Record<string, [number, number]>} */
 const OTMapping = {
   rlig: feature('ligatures', 'requiredLigatures'),
   clig: feature('ligatures', 'contextualLigatures'),
@@ -463,7 +482,7 @@ for (let i = 1; i <= 99; i++) {
   OTMapping[`cv${`00${i}`.slice(-2)}`] = [features.characterAlternatives.code, i];
 }
 
-// create inverse mapping
+/** @type {Record<number, Record<number, string>>} */
 let AATMapping = {};
 for (let ot in OTMapping) {
   let aat = OTMapping[ot];
@@ -474,9 +493,14 @@ for (let ot in OTMapping) {
   AATMapping[aat[0]][aat[1]] = ot;
 }
 
-// Maps an array of OpenType features to AAT features
-// in the form of {featureType:{featureSetting:true}}
+/**
+ * Maps an OpenType feature map to AAT features
+ * in the form of {featureType:{featureSetting:true}}
+ * @param {FeatureMap | Record<string, FeatureValue>} features
+ * @returns {AATFeatureSettings}
+ */
 export function mapOTToAAT(features) {
+  /** @type {AATFeatureSettings} */
   let res = {};
   for (let k in features) {
     let r;
@@ -492,38 +516,58 @@ export function mapOTToAAT(features) {
   return res;
 }
 
-// Maps strings in a [featureType, featureSetting]
-// to their equivalent number codes
+/**
+ * @param {string | number} value
+ * @returns {value is string}
+ */
+function isFeatureName(value) {
+  return typeof value === 'string' && Number.isNaN(Number(value));
+}
+
+/**
+ * Maps strings in a [featureType, featureSetting]
+ * to their equivalent number codes
+ * @param {[string | number, string | number]} f
+ * @returns {[number | undefined, number | undefined]}
+ */
 function mapFeatureStrings(f) {
   let [type, setting] = f;
+  /** @type {number | undefined} */
   let typeCode;
-  if (isNaN(type)) {
-    typeCode = features[type] && features[type].code;
+  if (isFeatureName(type)) {
+    typeCode = features[type] && /** @type {number} */ (features[type].code);
   } else {
-    typeCode = type;
+    typeCode = Number(type);
   }
 
+  /** @type {number | undefined} */
   let settingCode;
-  if (isNaN(setting)) {
-    settingCode = features[type] && features[type][setting];
+  if (isFeatureName(setting)) {
+    let feat = isFeatureName(type) ? features[type] : undefined;
+    settingCode = feat ? /** @type {number} */ (feat[setting]) : undefined;
   } else {
-    settingCode = setting;
+    settingCode = Number(setting);
   }
 
   return [typeCode, settingCode];
 }
 
-// Maps AAT features to an array of OpenType features
-// Supports both arrays in the form of [[featureType, featureSetting]]
-// and objects in the form of {featureType:{featureSetting:true}}
-// featureTypes and featureSettings can be either strings or number codes
+/**
+ * Maps AAT features to an array of OpenType features.
+ * Supports both arrays in the form of [[featureType, featureSetting]]
+ * and objects in the form of {featureType:{featureSetting:true}}.
+ * featureTypes and featureSettings can be either strings or number codes.
+ * @param {Array<[string | number, string | number]> | Record<string, Record<string, FeatureValue>>} features
+ * @returns {string[]}
+ */
 export function mapAATToOT(features) {
+  /** @type {Record<string, true>} */
   let res = {};
   if (Array.isArray(features)) {
     for (let k = 0; k < features.length; k++) {
       let r;
       let f = mapFeatureStrings(features[k]);
-      if ((r = AATMapping[f[0]] && AATMapping[f[0]][f[1]])) {
+      if (f[0] != null && f[1] != null && (r = AATMapping[f[0]] && AATMapping[f[0]][f[1]])) {
         res[r] = true;
       }
     }
@@ -533,7 +577,7 @@ export function mapAATToOT(features) {
       for (let setting in feature) {
         let r;
         let f = mapFeatureStrings([type, setting]);
-        if (feature[setting] && (r = AATMapping[f[0]] && AATMapping[f[0]][f[1]])) {
+        if (feature[setting] && f[0] != null && f[1] != null && (r = AATMapping[f[0]] && AATMapping[f[0]][f[1]])) {
           res[r] = true;
         }
       }

package/src/aat/AATLayoutEngine.js

@@ -1,13 +1,27 @@
 import * as AATFeatureMap from './AATFeatureMap';
 import AATMorxProcessor from './AATMorxProcessor';
 
+/** @typedef {import('../../types/fontkit').LayoutFont} LayoutFont */
+/** @typedef {import('../../types/fontkit').GlyphRunLike} GlyphRunLike */
+/** @typedef {import('../../types/fontkit').ScriptTag} ScriptTag */
+/** @typedef {import('../../types/fontkit').LanguageTag} LanguageTag */
+
 export default class AATLayoutEngine {
+  /**
+   * @param {LayoutFont} font
+   */
   constructor(font) {
+    /** @type {LayoutFont} */
     this.font = font;
+    /** @type {AATMorxProcessor} */
     this.morxProcessor = new AATMorxProcessor(font);
+    /** @type {boolean} */
     this.fallbackPosition = false;
   }
 
+  /**
+   * @param {GlyphRunLike} glyphRun
+   */
   substitute(glyphRun) {
     // AAT expects the glyphs to be in visual order prior to morx processing,
     // so reverse the glyphs if the script is right-to-left.
@@ -15,13 +29,25 @@ export default class AATLayoutEngine {
       glyphRun.glyphs.reverse();
     }
 
-    this.morxProcessor.process(glyphRun.glyphs, AATFeatureMap.mapOTToAAT(glyphRun.features));
+    this.morxProcessor.process(
+      /** @type {import('../../types/fontkit').LayoutGlyph[]} */ (glyphRun.glyphs),
+      AATFeatureMap.mapOTToAAT(glyphRun.features)
+    );
   }
 
+  /**
+   * @param {ScriptTag | string[] | null | undefined} [_script]
+   * @param {LanguageTag | null | undefined} [_language]
+   * @returns {string[]}
+   */
   getAvailableFeatures(_script, _language) {
     return AATFeatureMap.mapAATToOT(this.morxProcessor.getSupportedFeatures());
   }
 
+  /**
+   * @param {number} gid
+   * @returns {Set<string>}
+   */
   stringsForGlyph(gid) {
     let glyphStrings = this.morxProcessor.generateInputs(gid);
     let result = new Set();
@@ -33,6 +59,12 @@ export default class AATLayoutEngine {
     return result;
   }
 
+  /**
+   * @param {number[]} glyphs
+   * @param {number} index
+   * @param {Set<string>} strings
+   * @param {string} string
+   */
   _addStrings(glyphs, index, strings, string) {
     let codePoints = this.font._cmapProcessor.codePointsForGlyph(glyphs[index]);