@cantoo/fontkit 2.0.5 → 2.0.7

package/src/TTFFont.js

@@ -1,5 +1,6 @@
 import { cache } from './decorators';
 import * as fontkit from './base';
+import * as r from 'restructure';
 import Directory from './tables/directory';
 import tables from './tables';
 import CmapProcessor from './CmapProcessor';
@@ -15,18 +16,114 @@ import CFFSubset from './subset/CFFSubset';
 import BBox from './glyph/BBox';
 import { asciiDecoder } from './utils';
 
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').BinaryBuffer} BinaryBuffer */
+/** @typedef {import('../types/fontkit').FontDirectory} FontDirectory */
+/** @typedef {import('../types/fontkit').FontLike} FontLike */
+/** @typedef {import('../types/fontkit').FontMetrics} FontMetrics */
+/** @typedef {import('../types/fontkit').TableEntry} TableEntry */
+/** @typedef {import('../types/fontkit').TableCodec} TableCodec */
+/** @typedef {import('../types/fontkit').VariationCoords} VariationCoords */
+/** @typedef {import('../types/fontkit').NameString} NameString */
+/** @typedef {import('../types/fontkit').HeadTable} HeadTable */
+/** @typedef {import('../types/fontkit').HheaTable} HheaTable */
+/** @typedef {import('../types/fontkit').MaxpTable} MaxpTable */
+/** @typedef {import('../types/fontkit').OS2Table} OS2Table */
+/** @typedef {import('../types/fontkit').NameTable} NameTable */
+/** @typedef {import('../types/fontkit').PostTable} PostTable */
+/** @typedef {import('../types/fontkit').CmapTable} CmapTable */
+/** @typedef {import('../types/fontkit').MetricsTable} MetricsTable */
+/** @typedef {import('../types/fontkit').FvarTable} FvarTable */
+/** @typedef {import('../types/fontkit').FvarAxis} FvarAxis */
+/** @typedef {import('../types/fontkit').CFFFontLike} CFFFontLike */
+/** @typedef {import('../types/fontkit').FeatureInput} FeatureInput */
+/** @typedef {import('../types/fontkit').ScriptTag} ScriptTag */
+/** @typedef {import('../types/fontkit').LanguageTag} LanguageTag */
+/** @typedef {import('../types/fontkit').TextDirection} TextDirection */
+/** @typedef {import('./glyph/Glyph').default} Glyph */
+/** @typedef {import('./layout/GlyphRun').default} GlyphRun */
+/** @typedef {import('./subset/Subset').default} Subset */
+
+/**
+ * Axis description from {@link TTFFont#variationAxes}.
+ * @typedef {{ name: NameString | undefined, min: number, default: number, max: number }} VariationAxisInfo
+ */
+
 /**
  * This is the base class for all SFNT-based font formats in fontkit.
  * It supports TrueType, and PostScript glyphs, and several color glyph formats.
+ *
+ * Dynamic SFNT table accessors (`cmap`, `head`, `hhea`, …) are installed by
+ * `_installTableGetters` and typed here so call sites see real table shapes.
+ *
+ * @implements {FontLike}
  */
 export default class TTFFont {
+  /** @type {string} */
   type = 'TTF';
 
+  /** @type {DecodeStream} */
+  stream = new r.DecodeStream(new Uint8Array(0));
+  /** @type {FontDirectory} */
+  directory = /** @type {FontDirectory} */ ({ tables: {} });
+  /** @type {string | null} */
+  defaultLanguage = null;
+  /** @type {number[] | null} */
+  variationCoords = null;
+  /** @type {number} */
+  _directoryPos = 0;
+  /** @type {Record<string, unknown>} */
+  _tables = {};
+  /** @type {Record<number, Glyph | undefined>} */
+  _glyphs = {};
+  /** @type {FontMetrics | undefined} */
+  _metrics;
+
+  // SFNT tables installed as configurable getters by `_installTableGetters`.
+  /** @type {CmapTable | undefined} */
+  cmap;
+  /** @type {HeadTable} */
+  head = /** @type {HeadTable} */ ({ unitsPerEm: 0, xMin: 0, yMin: 0, xMax: 0, yMax: 0 });
+  /** @type {HheaTable | undefined} */
+  hhea;
+  /** @type {MetricsTable} */
+  hmtx = /** @type {MetricsTable} */ ({
+    metrics: { length: 0, get() { return undefined; } },
+    bearings: { length: 0, get() { return undefined; } }
+  });
+
+  /** @type {MaxpTable} */
+  maxp = { numGlyphs: 0 };
+  /** @type {NameTable | undefined} */
+  name;
+  /** @type {OS2Table | undefined} */
+  'OS/2';
+  /** @type {PostTable} */
+  post = { version: 0, italicAngle: 0, underlinePosition: 0, underlineThickness: 0 };
+  /** @type {FvarTable | undefined} */
+  fvar;
+  /** @type {CFFFontLike | undefined} */
+  CFF2;
+  /** @type {CFFFontLike | undefined} */
+  'CFF ';
+
+  /**
+   * @param {ArrayBufferView} buffer
+   * @returns {boolean}
+   */
   static probe(buffer) {
-    let format = asciiDecoder.decode(buffer.slice(0, 4));
+    let bytes
+      = buffer instanceof Uint8Array
+        ? buffer
+        : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    let format = asciiDecoder.decode(bytes.subarray(0, 4));
     return format === 'true' || format === 'OTTO' || format === String.fromCharCode(0, 1, 0, 0);
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @param {number[] | null} [variationCoords]
+   */
   constructor(stream, variationCoords = null) {
     this.defaultLanguage = null;
     this.stream = stream;
@@ -35,14 +132,28 @@ export default class TTFFont {
     this._directoryPos = this.stream.pos;
     this._tables = {};
     this._glyphs = {};
+    this._metrics = undefined;
+    this.directory = /** @type {FontDirectory} */ ({ tables: {} });
+
     this._decodeDirectory();
     this._installTableGetters();
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @returns {void}
+   */
+  _setStream(stream) {
+    this.stream = stream;
+  }
+
+  /** @returns {void} */
   _installTableGetters() {
-    for (let tag in this.directory.tables) {
-      let table = this.directory.tables[tag];
-      if (tables[tag] && table.length > 0) {
+    let tableMap = this.directory.tables;
+    for (let tag in tableMap) {
+      let table = tableMap[tag];
+      let codec = tables[tag];
+      if (codec && table && table.length > 0) {
         Object.defineProperty(this, tag, {
           get: this._getTable.bind(this, table),
           configurable: true
@@ -51,10 +162,18 @@ export default class TTFFont {
     }
   }
 
+  /**
+   * @param {string | null} [lang]
+   * @returns {void}
+   */
   setDefaultLanguage(lang = null) {
     this.defaultLanguage = lang;
   }
 
+  /**
+   * @param {TableEntry} table
+   * @returns {unknown}
+   */
   _getTable(table) {
     if (!(table.tag in this._tables)) {
       try {
@@ -62,7 +181,8 @@ export default class TTFFont {
       } catch (e) {
         if (fontkit.logErrors) {
           console.error(`Error decoding table ${table.tag}`);
-          console.error(e.stack);
+          let err = /** @type {{ stack?: string }} */ (e);
+          console.error(err.stack);
         }
       }
     }
@@ -70,6 +190,10 @@ export default class TTFFont {
     return this._tables[table.tag];
   }
 
+  /**
+   * @param {string} tag
+   * @returns {DecodeStream | null}
+   */
   _getTableStream(tag) {
     let table = this.directory.tables[tag];
     if (table) {
@@ -80,20 +204,36 @@ export default class TTFFont {
     return null;
   }
 
+  /** @returns {void} */
   _decodeDirectory() {
-    return this.directory = Directory.decode(this.stream, { _startOffset: 0 });
+    this.directory = /** @type {FontDirectory} */ (
+      /** @type {unknown} */ (Directory.decode(this.stream, { _startOffset: 0 }))
+    );
   }
 
+  /**
+   * @param {TableEntry} table
+   * @returns {unknown}
+   */
   _decodeTable(table) {
     let pos = this.stream.pos;
 
     let stream = this._getTableStream(table.tag);
-    let result = tables[table.tag].decode(stream, this, table.length);
+    let codec = /** @type {TableCodec | undefined} */ (tables[table.tag]);
+    if (!stream || !codec || !codec.decode) {
+      this.stream.pos = pos;
+      return undefined;
+    }
+
+    let result = codec.decode(stream, this, table.length);
 
     this.stream.pos = pos;
     return result;
   }
 
+  /**
+   * @returns {FontMetrics}
+   */
   _getMetrics() {
     if (this._metrics) {
       return this._metrics;
@@ -103,21 +243,34 @@ export default class TTFFont {
     // https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/src/sfnt/sfobjs.c
     // typo*/win* fields exist only in OS/2 version >= 1
     let os2 = this['OS/2'];
-    let hasTypo = os2 && os2.version > 0;
-    let ascent, descent, lineGap;
-
-    if (hasTypo && os2.fsSelection.useTypoMetrics) {
-      ({ typoAscender: ascent, typoDescender: descent, typoLineGap: lineGap } = os2);
+    let hasTypo = !!(os2 && os2.version > 0);
+    /** @type {number} */
+    let ascent;
+    /** @type {number} */
+    let descent;
+    /** @type {number} */
+    let lineGap;
+
+    if (hasTypo && os2 && os2.fsSelection.useTypoMetrics) {
+      ascent = /** @type {number} */ (os2.typoAscender);
+      descent = /** @type {number} */ (os2.typoDescender);
+      lineGap = /** @type {number} */ (os2.typoLineGap);
     } else {
-      ({ ascent, descent, lineGap } = this.hhea);
+      let hhea = this.hhea;
+      if (!hhea) {
+        throw new Error('Missing hhea table');
+      }
+      ({ ascent, descent, lineGap } = hhea);
 
       // Only when both hhea values are zero — FreeType uses !(ascender || descender)
-      if (!(ascent || descent) && hasTypo) {
+      if (!(ascent || descent) && hasTypo && os2) {
         if (os2.typoAscender || os2.typoDescender) {
-          ({ typoAscender: ascent, typoDescender: descent, typoLineGap: lineGap } = os2);
+          ascent = /** @type {number} */ (os2.typoAscender);
+          descent = /** @type {number} */ (os2.typoDescender);
+          lineGap = /** @type {number} */ (os2.typoLineGap);
         } else {
-          ascent = os2.winAscent;
-          descent = -os2.winDescent;
+          ascent = /** @type {number} */ (os2.winAscent);
+          descent = -(/** @type {number} */ (os2.winDescent));
           lineGap = 0;
         }
       }
@@ -134,18 +287,22 @@ export default class TTFFont {
   /**
    * Gets a string from the font's `name` table
    * `lang` is a BCP-47 language code.
-   * @return {string}
+   * @param {string} key
+   * @param {string | null} [lang]
+   * @returns {NameString | null}
    */
   getName(key, lang = this.defaultLanguage || fontkit.defaultLanguage) {
     let record = this.name && this.name.records[key];
-    if (record) {
+    if (record && typeof record === 'object') {
       // Attempt to retrieve the entry, depending on which translation is available:
+      /** @type {import('../types/fontkit').NameLocaleMap} */
+      let locales = /** @type {import('../types/fontkit').NameLocaleMap} */ (record);
       return (
-        record[lang]
-        || record[this.defaultLanguage]
-        || record[fontkit.defaultLanguage]
-        || record['en']
-        || record[Object.keys(record)[0]] // Seriously, ANY language would be fine
+        (lang ? locales[lang] : undefined)
+        || (this.defaultLanguage ? locales[this.defaultLanguage] : undefined)
+        || locales[fontkit.defaultLanguage]
+        || locales['en']
+        || locales[Object.keys(locales)[0]] // Seriously, ANY language would be fine
         || null
       );
     }
@@ -155,7 +312,7 @@ export default class TTFFont {
 
   /**
    * The unique PostScript name for this font, e.g. "Helvetica-Bold"
-   * @type {string}
+   * @type {NameString | null}
    */
   get postscriptName() {
     return this.getName('postscriptName');
@@ -163,7 +320,7 @@ export default class TTFFont {
 
   /**
    * The font's full name, e.g. "Helvetica Bold"
-   * @type {string}
+   * @type {NameString | null}
    */
   get fullName() {
     return this.getName('fullName');
@@ -171,7 +328,7 @@ export default class TTFFont {
 
   /**
    * The font's family name, e.g. "Helvetica"
-   * @type {string}
+   * @type {NameString | null}
    */
   get familyName() {
     return this.getName('fontFamily');
@@ -179,7 +336,7 @@ export default class TTFFont {
 
   /**
    * The font's sub-family, e.g. "Bold".
-   * @type {string}
+   * @type {NameString | null}
    */
   get subfamilyName() {
     return this.getName('fontSubfamily');
@@ -187,7 +344,7 @@ export default class TTFFont {
 
   /**
    * The font's copyright information
-   * @type {string}
+   * @type {NameString | null}
    */
   get copyright() {
     return this.getName('copyright');
@@ -195,7 +352,7 @@ export default class TTFFont {
 
   /**
    * The font's version number
-   * @type {string}
+   * @type {NameString | null}
    */
   get version() {
     return this.getName('version');
@@ -265,7 +422,7 @@ export default class TTFFont {
    */
   get capHeight() {
     let os2 = this['OS/2'];
-    return os2 ? os2.capHeight : this.ascent;
+    return os2 && os2.capHeight != null ? os2.capHeight : this.ascent;
   }
 
   /**
@@ -275,7 +432,7 @@ export default class TTFFont {
    */
   get xHeight() {
     let os2 = this['OS/2'];
-    return os2 ? os2.xHeight : 0;
+    return os2 && os2.xHeight != null ? os2.xHeight : 0;
   }
 
   /**
@@ -303,9 +460,12 @@ export default class TTFFont {
     return Object.freeze(new BBox(this.head.xMin, this.head.yMin, this.head.xMax, this.head.yMax));
   }
 
+  /**
+   * @type {CmapProcessor}
+   */
   @cache
   get _cmapProcessor() {
-    return new CmapProcessor(this.cmap);
+    return new CmapProcessor(/** @type {CmapTable} */ (this.cmap));
   }
 
   /**
@@ -332,7 +492,7 @@ export default class TTFFont {
    * Does not perform any advanced substitutions (there is no context to do so).
    *
    * @param {number} codePoint
-   * @return {Glyph}
+   * @return {Glyph | null}
    */
   glyphForCodePoint(codePoint) {
     return this.getGlyph(this._cmapProcessor.lookup(codePoint), [codePoint]);
@@ -348,6 +508,7 @@ export default class TTFFont {
    * @return {Glyph[]}
    */
   glyphsForString(string) {
+    /** @type {Glyph[]} */
     let glyphs = [];
     let len = string.length;
     let idx = 0;
@@ -377,10 +538,16 @@ export default class TTFFont {
 
       if (state === 0 && nextState === 1) {
         // Variation selector following normal codepoint.
-        glyphs.push(this.getGlyph(this._cmapProcessor.lookup(last, code), [last, code]));
+        let g = this.getGlyph(this._cmapProcessor.lookup(last, code), [last, code]);
+        if (g) {
+          glyphs.push(g);
+        }
       } else if (state === 0 && nextState === 0) {
         // Normal codepoint following normal codepoint.
-        glyphs.push(this.glyphForCodePoint(last));
+        let g = this.glyphForCodePoint(last);
+        if (g) {
+          glyphs.push(g);
+        }
       }
 
       last = code;
@@ -390,6 +557,9 @@ export default class TTFFont {
     return glyphs;
   }
 
+  /**
+   * @type {LayoutEngine}
+   */
   @cache
   get _layoutEngine() {
     return new LayoutEngine(this);
@@ -399,10 +569,10 @@ export default class TTFFont {
    * Returns a GlyphRun object, which includes an array of Glyphs and GlyphPositions for the given string.
    *
    * @param {string} string
-   * @param {string[]} [userFeatures]
-   * @param {string} [script]
-   * @param {string} [language]
-   * @param {string} [direction]
+   * @param {FeatureInput} [userFeatures]
+   * @param {ScriptTag} [script]
+   * @param {LanguageTag} [language]
+   * @param {TextDirection} [direction]
    * @return {GlyphRun}
    */
   layout(string, userFeatures, script, language, direction) {
@@ -412,6 +582,7 @@ export default class TTFFont {
   /**
    * Returns an array of strings that map to the given glyph id.
    * @param {number} gid - glyph id
+   * @returns {string[]}
    */
   stringsForGlyph(gid) {
     return this._layoutEngine.stringsForGlyph(gid);
@@ -429,16 +600,27 @@ export default class TTFFont {
     return this._layoutEngine.getAvailableFeatures();
   }
 
+  /**
+   * @param {ScriptTag} [script]
+   * @param {LanguageTag} [language]
+   * @returns {string[]}
+   */
   getAvailableFeatures(script, language) {
     return this._layoutEngine.getAvailableFeatures(script, language);
   }
 
+  /**
+   * @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;
     }
 
+    /** @type {Glyph | null} */
     let outline = null;
     if (this.directory.tables.glyf) {
       outline = new TTFGlyph(glyph, characters, this);
@@ -459,8 +641,8 @@ export default class TTFFont {
    * your use later, and it will be stored in the glyph object.
    *
    * @param {number} glyph
-   * @param {number[]} characters
-   * @return {Glyph}
+   * @param {number[]} [characters]
+   * @return {Glyph | null}
    */
   getGlyph(glyph, characters = []) {
     if (!this._glyphs[glyph]) {
@@ -495,10 +677,11 @@ export default class TTFFont {
    * that this font supports. Keys are setting tags, and values
    * contain the axis name, range, and default value.
    *
-   * @type {object}
+   * @type {Record<string, VariationAxisInfo>}
    */
   @cache
   get variationAxes() {
+    /** @type {Record<string, VariationAxisInfo>} */
     let res = {};
     if (!this.fvar) {
       return res;
@@ -506,7 +689,7 @@ export default class TTFFont {
 
     for (let axis of this.fvar.axis) {
       res[axis.axisTag.trim()] = {
-        name: axis.name.en,
+        name: axis.name && axis.name.en,
         min: axis.minValue,
         default: axis.defaultValue,
         max: axis.maxValue
@@ -521,23 +704,28 @@ export default class TTFFont {
    * that the font designer has specified. Keys are variation names
    * and values are the variation settings for this instance.
    *
-   * @type {object}
+   * @type {Record<string, Record<string, number>>}
    */
   @cache
   get namedVariations() {
+    /** @type {Record<string, Record<string, number>>} */
     let res = {};
     if (!this.fvar) {
       return res;
     }
 
     for (let instance of this.fvar.instance) {
+      /** @type {Record<string, number>} */
       let settings = {};
       for (let i = 0; i < this.fvar.axis.length; i++) {
         let axis = this.fvar.axis[i];
         settings[axis.axisTag.trim()] = instance.coord[i];
       }
 
-      res[instance.name.en] = settings;
+      let key = instance.name && instance.name.en;
+      if (typeof key === 'string') {
+        res[key] = settings;
+      }
     }
 
     return res;
@@ -548,7 +736,7 @@ export default class TTFFont {
    * Settings can either be an instance name, or an object containing
    * variation tags as specified by the `variationAxes` property.
    *
-   * @param {object} settings
+   * @param {string | Record<string, number>} settings
    * @return {TTFFont}
    */
   getVariation(settings) {
@@ -556,27 +744,34 @@ export default class TTFFont {
       throw new Error('Variations require a font with the fvar, gvar and glyf, or CFF2 tables.');
     }
 
+    /** @type {Record<string, number> | undefined} */
+    let resolved;
     if (typeof settings === 'string') {
-      settings = this.namedVariations[settings];
+      resolved = this.namedVariations[settings];
+    } else {
+      resolved = settings;
     }
 
-    if (typeof settings !== 'object') {
+    if (typeof resolved !== 'object' || resolved == null) {
       throw new Error('Variation settings must be either a variation name or settings object.');
     }
 
+    let fvar = /** @type {FvarTable} */ (this.fvar);
+
     // normalize the coordinates
-    let coords = this.fvar.axis.map((axis) => {
+    let coords = fvar.axis.map((/** @type {FvarAxis} */ axis) => {
       let axisTag = axis.axisTag.trim();
-      if (axisTag in settings) {
-        return Math.max(axis.minValue, Math.min(axis.maxValue, settings[axisTag]));
+      if (axisTag in resolved) {
+        return Math.max(axis.minValue, Math.min(axis.maxValue, resolved[axisTag]));
       } else {
         return axis.defaultValue;
       }
     });
 
     // Decompress WOFF/WOFF2 on the source once so the clone shares resolved tables.
-    if (typeof this._decompress === 'function') {
-      this._decompress();
+    let maybeDecompress = /** @type {{ _decompress?: () => void }} */ (this)._decompress;
+    if (typeof maybeDecompress === 'function') {
+      maybeDecompress.call(this);
     }
 
     // Preserve subclass (WOFF/WOFF2) and share decoded state. @cache values and
@@ -590,6 +785,9 @@ export default class TTFFont {
     return font;
   }
 
+  /**
+   * @type {GlyphVariationProcessor | null}
+   */
   @cache
   get _variationProcessor() {
     if (!this.fvar) {
@@ -604,14 +802,18 @@ export default class TTFFont {
     }
 
     if (!variationCoords) {
-      variationCoords = this.fvar.axis.map(axis => axis.defaultValue);
+      variationCoords = this.fvar.axis.map((/** @type {FvarAxis} */ axis) => axis.defaultValue);
     }
 
     return new GlyphVariationProcessor(this, variationCoords);
   }
 
   // Standardized format plugin API
+  /**
+   * @param {string | Uint8Array | Record<string, number>} name
+   * @returns {TTFFont}
+   */
   getFont(name) {
-    return this.getVariation(name);
+    return this.getVariation(/** @type {string | Record<string, number>} */ (name));
   }
 }