@cantoo/fontkit 2.0.5 → 2.0.6

package/src/cff/CFFOperand.js

@@ -1,9 +1,18 @@
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').EncodeStream} EncodeStream */
+
+/**
+ * Operand value that may force a 32-bit encoding (e.g. CFF pointer placeholders).
+ * @typedef {number | { forceLarge?: boolean, valueOf(): number }} CFFOperandValue
+ */
+
 const FLOAT_EOF = 0xf;
 const FLOAT_LOOKUP = [
   '0', '1', '2', '3', '4', '5', '6', '7',
   '8', '9', '.', 'E', 'E-', null, '-'
 ];
 
+/** @type {Record<string, number>} */
 const FLOAT_ENCODE_LOOKUP = {
   '.': 10,
   E: 11,
@@ -12,6 +21,11 @@ const FLOAT_ENCODE_LOOKUP = {
 };
 
 export default class CFFOperand {
+  /**
+   * @param {DecodeStream} stream
+   * @param {number} value
+   * @returns {number | null}
+   */
   static decode(stream, value) {
     if (32 <= value && value <= 246) {
       return value - 139;
@@ -53,73 +67,94 @@ export default class CFFOperand {
     return null;
   }
 
+  /**
+   * @param {CFFOperandValue} value
+   * @returns {number}
+   */
   static size(value) {
     // if the value needs to be forced to the largest size (32 bit)
     // e.g. for unknown pointers, set to 32768
-    if (value.forceLarge) {
-      value = 32768;
+    /** @type {number} */
+    let n;
+    if (value && typeof value === 'object' && value.forceLarge) {
+      n = 32768;
+    } else {
+      n = Number(value);
     }
 
-    if ((value | 0) !== value) { // floating point
-      let str = '' + value;
+    if ((n | 0) !== n) { // floating point
+      let str = '' + n;
       return 1 + Math.ceil((str.length + 1) / 2);
-    } else if (-107 <= value && value <= 107) {
+    } else if (-107 <= n && n <= 107) {
       return 1;
-    } else if (108 <= value && value <= 1131 || -1131 <= value && value <= -108) {
+    } else if (108 <= n && n <= 1131 || -1131 <= n && n <= -108) {
       return 2;
-    } else if (-32768 <= value && value <= 32767) {
+    } else if (-32768 <= n && n <= 32767) {
       return 3;
     } else {
       return 5;
     }
   }
 
+  /**
+   * @param {EncodeStream} stream
+   * @param {CFFOperandValue} value
+   * @returns {void}
+   */
   static encode(stream, value) {
     // if the value needs to be forced to the largest size (32 bit)
     // e.g. for unknown pointers, save the old value and set to 32768
     let val = Number(value);
 
-    if (value.forceLarge) {
+    if (value && typeof value === 'object' && value.forceLarge) {
       stream.writeUInt8(29);
-      return stream.writeInt32BE(val);
+      stream.writeInt32BE(val);
+      return;
     } else if ((val | 0) !== val) { // floating point
       stream.writeUInt8(30);
 
       let str = '' + val;
+      /** @type {number | undefined} */
       let n2;
       for (let i = 0; i < str.length; i += 2) {
         let c1 = str[i];
-        let n1 = FLOAT_ENCODE_LOOKUP[c1] || +c1;
+        let n1 = FLOAT_ENCODE_LOOKUP[c1] ?? (+c1);
 
         if (i === str.length - 1) {
           n2 = FLOAT_EOF;
         } else {
           let c2 = str[i + 1];
-          n2 = FLOAT_ENCODE_LOOKUP[c2] || +c2;
+          n2 = FLOAT_ENCODE_LOOKUP[c2] ?? (+c2);
         }
 
         stream.writeUInt8((n1 << 4) | (n2 & 15));
       }
 
       if (n2 !== FLOAT_EOF) {
-        return stream.writeUInt8((FLOAT_EOF << 4));
+        stream.writeUInt8((FLOAT_EOF << 4));
       }
+      return;
     } else if (-107 <= val && val <= 107) {
-      return stream.writeUInt8(val + 139);
+      stream.writeUInt8(val + 139);
+      return;
     } else if (108 <= val && val <= 1131) {
       val -= 108;
       stream.writeUInt8((val >> 8) + 247);
-      return stream.writeUInt8(val & 0xff);
+      stream.writeUInt8(val & 0xff);
+      return;
     } else if (-1131 <= val && val <= -108) {
       val = -val - 108;
       stream.writeUInt8((val >> 8) + 251);
-      return stream.writeUInt8(val & 0xff);
+      stream.writeUInt8(val & 0xff);
+      return;
     } else if (-32768 <= val && val <= 32767) {
       stream.writeUInt8(28);
-      return stream.writeInt16BE(val);
+      stream.writeInt16BE(val);
+      return;
     } else {
       stream.writeUInt8(29);
-      return stream.writeInt32BE(val);
+      stream.writeInt32BE(val);
+      return;
     }
   }
 }

package/src/cff/CFFPointer.js

@@ -1,6 +1,20 @@
 import * as r from 'restructure';
 
+/** @typedef {import('restructure').BaseType} BaseType */
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').EncodeStream} EncodeStream */
+/** @typedef {import('restructure').PointerOptions} PointerOptions */
+/** @typedef {import('restructure').StructValue} StructValue */
+
+/**
+ * CFF dict pointer: offset comes from a prior operand rather than the stream.
+ * Temporary offsetType stubs only implement the method needed for that phase.
+ */
 export default class CFFPointer extends r.Pointer {
+  /**
+   * @param {BaseType | null} type
+   * @param {PointerOptions} [options]
+   */
   constructor(type, options = {}) {
     if (options.type == null) {
       options.type = 'global';
@@ -9,6 +23,12 @@ export default class CFFPointer extends r.Pointer {
     super(null, type, options);
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue | null | undefined} parent
+   * @param {number[]} operands
+   * @returns {unknown}
+   */
   decode(stream, parent, operands) {
     this.offsetType = {
       decode: () => operands[0]
@@ -17,6 +37,12 @@ export default class CFFPointer extends r.Pointer {
     return super.decode(stream, parent, operands);
   }
 
+  /**
+   * @param {EncodeStream | null} stream
+   * @param {unknown} value
+   * @param {StructValue | null | undefined} ctx
+   * @returns {Ptr[]}
+   */
   encode(stream, value, ctx) {
     if (!stream) {
       // compute the size (so ctx.pointerSize is correct)
@@ -28,22 +54,35 @@ export default class CFFPointer extends r.Pointer {
       return [new Ptr(0)];
     }
 
+    /** @type {number | null} */
     let ptr = null;
     this.offsetType = {
-      encode: (stream, val) => ptr = val
+      /**
+       * @param {EncodeStream} _stream
+       * @param {number} val
+       */
+      encode: (_stream, val) => { ptr = val; }
     };
 
     super.encode(stream, value, ctx);
-    return [new Ptr(ptr)];
+    return [new Ptr(ptr ?? 0)];
   }
 }
 
 class Ptr {
+  /**
+   * @param {number} val
+   */
   constructor(val) {
+    /** @type {number} */
     this.val = val;
+    /** @type {boolean} */
     this.forceLarge = true;
   }
 
+  /**
+   * @returns {number}
+   */
   valueOf() {
     return this.val;
   }

package/src/cff/CFFPrivateDict.js

@@ -2,17 +2,27 @@ import CFFDict from './CFFDict';
 import CFFIndex from './CFFIndex';
 import CFFPointer from './CFFPointer';
 
-class CFFBlendOp {
-  static decode(stream, parent, operands) {
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').StructValue} StructValue */
+
+/** @type {import('../../types/fontkit').CFFOperandType} */
+const CFFBlendOp = {
+  /**
+   * @param {DecodeStream} _stream
+   * @param {StructValue} _parent
+   * @param {number[]} operands
+   * @returns {void}
+   */
+  decode(_stream, _parent, operands) {
     let numBlends = operands.pop();
 
     // TODO: actually blend. For now just consume the deltas
     // since we don't use any of the values anyway.
-    while (operands.length > numBlends) {
+    while (operands.length > /** @type {number} */ (numBlends)) {
       operands.pop();
     }
   }
-}
+};
 
 export default new CFFDict([
   // key       name                    type                                          default

package/src/cff/CFFStandardStrings.js

@@ -1,5 +1,6 @@
 // Automatically generated from Appendix A of the CFF specification; do
 // not edit. Length should be 391.
+/** @type {string[]} */
 export default [
   '.notdef', 'space', 'exclam', 'quotedbl', 'numbersign', 'dollar',
   'percent', 'ampersand', 'quoteright', 'parenleft', 'parenright',

package/src/cff/CFFTop.js

@@ -8,33 +8,89 @@ import { StandardEncoding, ExpertEncoding } from './CFFEncodings';
 import { ISOAdobeCharset, ExpertCharset, ExpertSubsetCharset } from './CFFCharsets';
 import { ItemVariationStore } from '../tables/variations';
 
+/** @typedef {import('restructure').BaseType} BaseType */
+/** @typedef {import('restructure').DecodeStream} DecodeStream */
+/** @typedef {import('restructure').EncodeStream} EncodeStream */
+/** @typedef {import('restructure').StructValue} StructValue */
+/** @typedef {import('../../types/fontkit').CFFEncodeContext} CFFEncodeContext */
+
+/**
+ * @param {StructValue} t
+ * @returns {number}
+ */
+function charStringsCount(t) {
+  let parent = t.parent;
+  if (!parent) {
+    return 0;
+  }
+  let cs = parent.CharStrings;
+  if (cs && typeof cs === 'object' && 'length' in cs && typeof /** @type {{ length: unknown }} */ (cs).length === 'number') {
+    return /** @type {{ length: number }} */ (cs).length;
+  }
+  return 0;
+}
+
 // Checks if an operand is an index of a predefined value,
 // otherwise delegates to the provided type.
 class PredefinedOp {
+  /**
+   * @param {unknown[]} predefinedOps
+   * @param {BaseType} type
+   */
   constructor(predefinedOps, type) {
+    /** @type {unknown[]} */
     this.predefinedOps = predefinedOps;
+    /** @type {BaseType} */
     this.type = type;
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue} parent
+   * @param {number[]} operands
+   * @returns {unknown}
+   */
   decode(stream, parent, operands) {
-    if (this.predefinedOps[operands[0]]) {
+    if (this.predefinedOps[operands[0]] != null) {
       return this.predefinedOps[operands[0]];
     }
 
+    if (!this.type.decode) {
+      throw new Error('PredefinedOp type must implement decode()');
+    }
     return this.type.decode(stream, parent, operands);
   }
 
+  /**
+   * @param {unknown} value
+   * @param {StructValue | null | undefined} ctx
+   * @returns {unknown}
+   */
   size(value, ctx) {
+    if (!this.type.size) {
+      throw new Error('PredefinedOp type must implement size()');
+    }
     return this.type.size(value, ctx);
   }
 
+  /**
+   * @param {EncodeStream | null} stream
+   * @param {unknown} value
+   * @param {StructValue | null | undefined} ctx
+   * @returns {unknown[]}
+   */
   encode(stream, value, ctx) {
     let index = this.predefinedOps.indexOf(value);
     if (index !== -1) {
-      return index;
+      // Must be an operand list — CFFDict iterates with for-of.
+      return [index];
     }
 
-    return this.type.encode(stream, value, ctx);
+    if (!this.type.encode) {
+      throw new Error('PredefinedOp type must implement encode()');
+    }
+    let encoded = this.type.encode(stream, value, ctx);
+    return Array.isArray(encoded) ? encoded : [encoded];
   }
 }
 
@@ -43,6 +99,10 @@ class CFFEncodingVersion extends r.Number {
     super('UInt8');
   }
 
+  /**
+   * @param {DecodeStream} stream
+   * @returns {number}
+   */
   decode(stream) {
     return r.uint8.decode(stream) & 0x7f;
   }
@@ -77,15 +137,29 @@ let CFFEncoding = new PredefinedOp([StandardEncoding, ExpertEncoding], new CFFPo
 // Decodes an array of ranges until the total
 // length is equal to the provided length.
 class RangeArray extends r.Array {
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue} parent
+   * @returns {Array<StructValue & { nLeft: number, offset: number }>}
+   */
   decode(stream, parent) {
+    if (this.length == null) {
+      throw new Error('RangeArray requires a length');
+    }
     let length = resolveLength(this.length, stream, parent);
     let count = 0;
+    /** @type {Array<StructValue & { nLeft: number, offset: number }>} */
     let res = [];
     while (count < length) {
-      let range = this.type.decode(stream, parent);
+      if (!this.type.decode) {
+        throw new Error('RangeArray element type must implement decode()');
+      }
+      let range = /** @type {StructValue & { nLeft: number, offset?: number }} */ (
+        this.type.decode(stream, parent)
+      );
       range.offset = count;
       count += range.nLeft + 1;
-      res.push(range);
+      res.push(/** @type {StructValue & { nLeft: number, offset: number }} */ (range));
     }
 
     return res;
@@ -94,15 +168,15 @@ class RangeArray extends r.Array {
 
 let CFFCustomCharset = new r.VersionedStruct(r.uint8, {
   0: {
-    glyphs: new r.Array(r.uint16, t => t.parent.CharStrings.length - 1)
+    glyphs: new r.Array(r.uint16, t => charStringsCount(t) - 1)
   },
 
   1: {
-    ranges: new RangeArray(Range1, t => t.parent.CharStrings.length - 1)
+    ranges: new RangeArray(Range1, t => charStringsCount(t) - 1)
   },
 
   2: {
-    ranges: new RangeArray(Range2, t => t.parent.CharStrings.length - 1)
+    ranges: new RangeArray(Range2, t => charStringsCount(t) - 1)
   }
 });
 
@@ -120,7 +194,7 @@ let FDRange4 = new r.Struct({
 
 let FDSelect = new r.VersionedStruct(r.uint8, {
   0: {
-    fds: new r.Array(r.uint8, t => t.parent.CharStrings.length)
+    fds: new r.Array(r.uint8, t => charStringsCount(t))
   },
 
   3: {
@@ -138,15 +212,34 @@ let FDSelect = new r.VersionedStruct(r.uint8, {
 
 let ptr = new CFFPointer(CFFPrivateDict);
 class CFFPrivateOp {
+  /**
+   * @param {DecodeStream} stream
+   * @param {StructValue} parent
+   * @param {number[]} operands
+   * @returns {unknown}
+   */
   decode(stream, parent, operands) {
     parent.length = operands[0];
     return ptr.decode(stream, parent, [operands[1]]);
   }
 
+  /**
+   * Size operands match encode(null, …): [privateDictByteLength, pointerOperand].
+   * @param {StructValue} dict
+   * @param {CFFEncodeContext | StructValue} ctx
+   * @returns {unknown[]}
+   */
   size(dict, ctx) {
-    return [CFFPrivateDict.size(dict, ctx, false), ptr.size(dict, ctx)[0]];
+    // Delegate to encode(null) so pointerSize is updated and operands match.
+    return this.encode(null, dict, ctx);
   }
 
+  /**
+   * @param {EncodeStream | null} stream
+   * @param {StructValue} dict
+   * @param {CFFEncodeContext | StructValue} ctx
+   * @returns {unknown[]}
+   */
   encode(stream, dict, ctx) {
     return [CFFPrivateDict.size(dict, ctx, false), ptr.encode(stream, dict, ctx)[0]];
   }

package/src/decorators.js

@@ -1,7 +1,12 @@
 /**
- * This decorator caches the results of a getter or method such that
- * the results are lazily computed once, and then cached.
- * @private
+ * Cache decorator for getters/methods.
+ * Results are lazily computed once, then cached on the instance.
+ *
+ * @template T
+ * @param {object} target
+ * @param {string} key
+ * @param {TypedPropertyDescriptor<T>} descriptor
+ * @returns {TypedPropertyDescriptor<T> | void}
  */
 export function cache(target, key, descriptor) {
   if (descriptor.get) {
@@ -11,26 +16,40 @@ export function cache(target, key, descriptor) {
       Object.defineProperty(this, key, { value });
       return value;
     };
-  } else if (typeof descriptor.value === 'function') {
-    let fn = descriptor.value;
+    return;
+  }
+
+  if (typeof descriptor.value === 'function') {
+    let fn = /** @type {(...args: unknown[]) => T} */ (descriptor.value);
 
-    return {
+    /** @type {TypedPropertyDescriptor<T>} */
+    let replacement = {
+      configurable: true,
+      enumerable: false,
       get() {
-        let cache = new Map();
-        function memoized(...args) {
-          let key = args.length > 0 ? args[0] : 'value';
-          if (cache.has(key)) {
-            return cache.get(key);
+        /** @type {Map<unknown, T>} */
+        let cacheMap = new Map();
+
+        /**
+         * @param {...unknown} args
+         * @returns {T}
+         */
+        let memoized = (...args) => {
+          let cacheKey = args.length > 0 ? args[0] : 'value';
+          if (cacheMap.has(cacheKey)) {
+            return /** @type {T} */ (cacheMap.get(cacheKey));
           }
 
           let result = fn.apply(this, args);
-          cache.set(key, result);
+          cacheMap.set(cacheKey, result);
           return result;
         };
 
         Object.defineProperty(this, key, { value: memoized });
-        return memoized;
+        return /** @type {T} */ (/** @type {unknown} */ (memoized));
       }
     };
+
+    return replacement;
   }
 }

package/src/encodings.js

@@ -1,6 +1,10 @@
 /**
  * Gets an encoding name from platform, encoding, and language ids.
  * Returned encoding names can be used in iconv-lite to decode text.
+ * @param {number} platformID
+ * @param {number} encodingID
+ * @param {number} [languageID]
+ * @returns {string | null | undefined}
  */
 export function getEncoding(platformID, encodingID, languageID = 0) {
   if (platformID === 1 && MAC_LANGUAGE_ENCODINGS[languageID]) {
@@ -10,7 +14,10 @@ export function getEncoding(platformID, encodingID, languageID = 0) {
   return ENCODINGS[platformID][encodingID];
 }
 
+/** @type {Set<string>} */
 const SINGLE_BYTE_ENCODINGS = new Set(['x-mac-roman', 'x-mac-cyrillic', 'iso-8859-6', 'iso-8859-8']);
+
+/** @type {Record<string, string>} */
 const MAC_ENCODINGS = {
   'x-mac-croatian': 'ÄÅÇÉÑÖÜáàâäãåçéèêëíìîïñóòôöõúùûü†°¢£§•¶ß®Š™´¨≠ŽØ∞±≤≥∆µ∂∑∏š∫ªºΩžø¿¡¬√ƒ≈Ć«Č… ÀÃÕŒœĐ—“”‘’÷◊©⁄€‹›Æ»–·‚„‰ÂćÁčÈÍÎÏÌÓÔđÒÚÛÙıˆ˜¯πË˚¸Êæˇ',
   'x-mac-gaelic': 'ÄÅÇÉÑÖÜáàâäãåçéèêëíìîïñóòôöõúùûü†°¢£§•¶ß®©™´¨≠ÆØḂ±≤≥ḃĊċḊḋḞḟĠġṀæøṁṖṗɼƒſṠ«»… ÀÃÕŒœ–—“”‘’ṡẛÿŸṪ€‹›Ŷŷṫ·Ỳỳ⁊ÂÊÁËÈÍÎÏÌÓÔ♣ÒÚÛÙıÝýŴŵẄẅẀẁẂẃ',
@@ -22,8 +29,13 @@ const MAC_ENCODINGS = {
   'x-mac-turkish': 'ÄÅÇÉÑÖÜáàâäãåçéèêëíìîïñóòôöõúùûü†°¢£§•¶ß®©™´¨≠ÆØ∞±≤≥¥µ∂∑∏π∫ªºΩæø¿¡¬√ƒ≈∆«»… ÀÃÕŒœ–—“”‘’÷◊ÿŸĞğİıŞş‡·‚„‰ÂÊÁËÈÍÎÏÌÓÔÒÚÛÙˆ˜¯˘˙˚¸˝˛ˇ'
 };
 
+/** @type {Map<string, Map<number, number>>} */
 const encodingCache = new Map();
 
+/**
+ * @param {string} encoding
+ * @returns {Map<number, number> | undefined}
+ */
 export function getEncodingMapping(encoding) {
   let cached = encodingCache.get(encoding);
   if (cached) {
@@ -47,13 +59,13 @@ export function getEncodingMapping(encoding) {
     // TextEncoder only supports utf8, whereas TextDecoder supports legacy encodings.
     // Use this to create a mapping of code points.
     let decoder = new TextDecoder(encoding);
-    let mapping = new Uint8Array(0x80);
+    let bytes = new Uint8Array(0x80);
     for (let i = 0; i < 0x80; i++) {
-      mapping[i] = 0x80 + i;
+      bytes[i] = 0x80 + i;
     }
 
     let res = new Map();
-    let s = decoder.decode(mapping);
+    let s = decoder.decode(bytes);
     for (let i = 0; i < 0x80; i++) {
       res.set(s.charCodeAt(i), 0x80 + i);
     }
@@ -61,9 +73,12 @@ export function getEncodingMapping(encoding) {
     encodingCache.set(encoding, res);
     return res;
   }
+
+  return undefined;
 }
 
 // Map of platform ids to encoding ids.
+/** @type {(string | null)[][]} */
 export const ENCODINGS = [
   // unicode
   ['utf-16be', 'utf-16be', 'utf-16be', 'utf-16be', 'utf-16be', 'utf-16be', 'utf-16be'],
@@ -103,6 +118,7 @@ export const ENCODINGS = [
 
 // Overrides for Mac scripts by language id.
 // See http://unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt
+/** @type {Record<number, string>} */
 export const MAC_LANGUAGE_ENCODINGS = {
   15: 'x-mac-icelandic',
   17: 'x-mac-turkish',
@@ -122,9 +138,10 @@ export const MAC_LANGUAGE_ENCODINGS = {
 };
 
 // Map of platform ids to BCP-47 language codes.
+/** @type {Array<Record<number, string>>} */
 export const LANGUAGES = [
   // unicode
-  [],
+  {},
 
   { // macintosh
     0: 'en', 30: 'fo', 60: 'ks', 90: 'rw',
@@ -160,7 +177,7 @@ export const LANGUAGES = [
   },
 
   // ISO (deprecated)
-  [],
+  {},
 
   { // windows
     0x0436: 'af', 0x4009: 'en-IN', 0x0487: 'rw', 0x0432: 'tn',

package/src/fs.js

@@ -1,11 +1,21 @@
 import { create } from './base';
 import fs from 'fs';
 
+/**
+ * @param {string | import('fs').PathLike} filename
+ * @param {string | Uint8Array} [postscriptName]
+ * @returns {import('../types/fontkit').OpenedFont | null | undefined}
+ */
 export function openSync(filename, postscriptName) {
   let buffer = fs.readFileSync(filename);
   return create(buffer, postscriptName);
 }
 
+/**
+ * @param {string | import('fs').PathLike} filename
+ * @param {string | Uint8Array} [postscriptName]
+ * @returns {Promise<import('../types/fontkit').OpenedFont | null | undefined>}
+ */
 export async function open(filename, postscriptName) {
   let buffer = await fs.promises.readFile(filename);
   return create(buffer, postscriptName);

package/src/glyph/BBox.js

@@ -2,6 +2,12 @@
  * Represents a glyph bounding box
  */
 export default class BBox {
+  /**
+   * @param {number} [minX]
+   * @param {number} [minY]
+   * @param {number} [maxX]
+   * @param {number} [maxY]
+   */
   constructor(minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity) {
     /**
      * The minimum X position in the bounding box
@@ -44,6 +50,11 @@ export default class BBox {
     return this.maxY - this.minY;
   }
 
+  /**
+   * @param {number} x
+   * @param {number} y
+   * @returns {void}
+   */
   addPoint(x, y) {
     if (Math.abs(x) !== Infinity) {
       if (x < this.minX) {
@@ -66,6 +77,9 @@ export default class BBox {
     }
   }
 
+  /**
+   * @returns {BBox}
+   */
   copy() {
     return new BBox(this.minX, this.minY, this.maxX, this.maxY);
   }