tiny-essentials 1.28.19 → 1.29.0

package/dist/v1/libs/text/{TinyI18.cjs → TinyI18/index.cjs}

@@ -1,9 +1,6 @@
 'use strict';
 
-var promises = require('fs/promises');
-var fs = require('fs');
-var path = require('path');
-var tools = require('../utils/tools.cjs');
+var tools = require('../../utils/tools.cjs');
 
 const checkDestroy = tools.createCheckDestroyed('TinyI18');
 
@@ -17,74 +14,76 @@ const checkDestroy = tools.createCheckDestroyed('TinyI18');
 /**
  * Dictionary of translation keys mapped to values.
  *
- * @typedef {Record<string, any>} Dict
+ * @typedef {Record<string, any>} Dict - A collection of key-value pairs for translations.
  */
 
 /**
  * Represents a translation entry as it appears in JSON files.
  *
- * @typedef {{
- *   $pattern: string,
- *   $fn: string,
- *   [key: string]: string
- * }} FileValue
- *
- * `$pattern` - Regex string (will be compiled into RegExp).
- *
- * `$fn` - Helper function name associated with this entry.
+ * @typedef {Object} FileValueBase
+ * @property {string} $pattern - Regex string (will be compiled into RegExp).
+ * @property {string} $fn - Helper function name associated with this entry.
+ * @property {string} [key] - Additional key-value pairs for interpolation or extra metadata.
+ */
 
- * `[key]` - Additional key-value pairs for interpolation or extra metadata.
+/**
+ * Represents a translation entry as it appears in JSON files, extending
+ * the base pattern/function fields with arbitrary string key-value pairs.
+ *
+ * @typedef {FileValueBase & { [key: string]: string }} FileValue
  */
 
 /**
  * Represents a valid locale code string.
  * Example: "en", "pt-BR", "fr".
  *
- * @typedef {string} LocaleCode
+ * @typedef {string} LocaleCode - A string representing a valid locale identifier.
  */
 
 /**
- * Value types stored per locale:
- * - string: a direct translation with optional {named} interpolation
- * - Function: (params, helpers) => any (advanced rendering; HTML-safe if you control it)
- * - { $pattern: RegExp, value: string | { $fn: string, args?: any } | Function }
- * - { $fn: string, args?: any }  // in file mode; resolved to a registered function
+ * Value types stored per locale.
+ *
+ * @typedef {string|{ $fn: string; args?: any }} TranslationValue - The type of a value used in a translation entry.
  */
 
 /**
- * Represents a single regex-based translation entry.
+ * A resolved translation value.
  *
- * @typedef {Object} PatternEntry
- * @property {RegExp} $pattern - Compiled regular expression used for matching.
- * @property {any} value - Translation value or resolver function associated with the pattern.
- * @property {any} elseValue - Translation value or resolver function associated with the pattern.
+ * @typedef {string|null} TranslateResult - A resolved translation value, typically a string or null.
  */
 
 /**
- * @typedef {Object} FileModeEntryJSON
- * @property {string} [$pattern] - regex as string e.g. "^user\\.(\\d+)$"
- * @property {string|Object} value - string or { $fn: string, args?: any }
- * @property {string|Object} elseValue - string or { $fn: string, args?: any }
+ * Represents a single regex-based translation entry.
+ *
+ * @typedef {Object} PatternEntry - A representation of a translation entry that matches via a regular expression.
+ * @property {RegExp} $pattern - Compiled regular expression used for matching.
+ * @property {TranslationValue} value - Translation value or resolver function associated with the pattern.
+ * @property {TranslationValue} elseValue - Translation value or resolver function associated with the pattern.
  */
 
 /**
- * @typedef {Object} TinyI18Options
- * @property {ModeTypes} mode
- * @property {LocaleCode} defaultLocale
- * @property {string} [basePath] - Required in file mode. Directory with <locale>.json
- * @property {Dict} [localResources] - Optional initial map { locale: dict } for local mode
- * @property {boolean} [strict=true] - If true, throws on missing keys; else returns key
+ * Configuration options for the TinyI18 instance.
+ *
+ * @typedef {Object} TinyI18Options - Configuration options for the TinyI18 constructor.
+ * @property {ModeTypes} mode - The operating mode of the instance.
+ * @property {LocaleCode} defaultLocale - The fallback locale used when a key is missing.
+ * @property {string} [basePath] - Required in file mode. Directory containing <locale>.json files.
+ * @property {Dict} [localResources] - Optional initial map { locale: dict } for local mode.
+ * @property {boolean} [strict=true] - If true, throws on missing keys or invalid data; else returns fallback.
+ * @property {boolean} [acceptNullResults=false] - If true, returns null instead of the key for missing translations.
  */
 
 /**
- * @typedef {Object} ResolveOptions
- * @property {LocaleCode} [locale] - force resolve using a specific locale first
+ * Options used to customize the translation resolution process.
+ *
+ * @typedef {Object} ResolveOptions - Options to control the translation resolution process.
+ * @property {LocaleCode} [locale] - Force resolution using a specific locale first.
  */
 
 /**
- * Represents statistics for a specific locale.
+ * Statistics for a specific locale.
  *
- * @typedef {Object} StatLocale
+ * @typedef {Object} StatLocale - Information about the contents and status of a specific locale.
  * @property {string} locale - The locale code (e.g., "en", "pt-BR").
  * @property {number} strings - Total number of static string entries in this locale.
  * @property {number} patterns - Total number of regex-based pattern entries in this locale.
@@ -96,12 +95,12 @@ const checkDestroy = tools.createCheckDestroyed('TinyI18');
  * Read-only view of registered helpers, exposed to function-based entries.
  *
  * Provides safe access to:
- * - check if a helper exists by name
- * - call a helper by name, passing arguments
+ * - Check if a helper exists by name.
+ * - Call a helper by name, passing arguments.
  *
  * @template {any} T
  * @template {any} R
- * @typedef {Object} HelpersReadonly
+ * @typedef {Object} HelpersReadonly - A read-only interface for interacting with registered helpers.
  * @property {(name: string) => boolean} [has] - Check if a helper with given name is registered.
  * @property {(name: string, arg: T, extras?: HelpersReadonly<T, R>) => R} [call] -
  * Invoke a helper by name with an argument and optional extras.
@@ -113,9 +112,11 @@ const checkDestroy = tools.createCheckDestroyed('TinyI18');
  * - Receives user-supplied parameters and a read-only facade for calling other helpers.
  * - Must return a string (e.g. processed, interpolated, or formatted output).
  *
+ * @template {any} T
+ * @template {any} R
  * @callback HelperCallback
  * @param {Dict} params - Key-value parameters passed from the translation entry.
- * @param {HelpersReadonly<any, any>} helpers - Read-only access to other registered helpers.
+ * @param {HelpersReadonly<T, R>} helpers - Read-only access to other registered helpers.
  * @returns {string} Processed string result.
  */
 
@@ -131,16 +132,90 @@ const checkDestroy = tools.createCheckDestroyed('TinyI18');
  * - Safe: no dynamic code eval from files; functions in file mode are referenced by name ("$fn").
  */
 class TinyI18 {
+  /**
+   * Cached path join function used to resolve locale file paths.
+   * @type {((...paths: string[]) => string)|null}
+   */
+  static #join = null;
+  /**
+   * Cached file existence check function.
+   * @type {((path: string) => boolean)|null|false}
+   */
+  static #existsSync = null;
+  /**
+   * Cached asynchronous file read function.
+   * @type {((path: string, options: BufferEncoding) => Promise<string>)|null}
+   */
+  static #readFile = null;
+  /**
+   * Cached asynchronous file write function.
+   * @type {((path: string, data: string, options: BufferEncoding) => Promise<any>)|null}
+   */
+  static #writeFile = null;
+
+  /**
+   * Sets the path join function used to resolve locale file paths.
+   * Throws if a non-function value is provided or if the function has already been set.
+   * @param {(...paths: string[]) => string} value - The path join function to cache.
+   */
+  static set _join(value) {
+    if (typeof value !== 'function') throw new TypeError('TinyI18: "_join" must be a function');
+    if (TinyI18.#join !== null) throw new Error('TinyI18: "_join" has already been set');
+    TinyI18.#join = value;
+  }
+
+  /**
+   * Sets the file existence check function.
+   * Throws if a non-function value is provided or if the function has already been set.
+   * @param {((path: string) => boolean)|false} value - The existence check function, or false to disable.
+   */
+  static set _existsSync(value) {
+    if (typeof value !== 'function' && value !== false)
+      throw new TypeError('TinyI18: "_existsSync" must be a function or false');
+    if (TinyI18.#existsSync !== null)
+      throw new Error('TinyI18: "_existsSync" has already been set');
+    TinyI18.#existsSync = value;
+  }
+
+  /**
+   * Sets the asynchronous file read function.
+   * Throws if a non-function value is provided or if the function has already been set.
+   * @param {(path: string, options: BufferEncoding) => Promise<string>} value - The file read function to cache.
+   */
+  static set _readFile(value) {
+    if (typeof value !== 'function') throw new TypeError('TinyI18: "_readFile" must be a function');
+    if (TinyI18.#readFile !== null) throw new Error('TinyI18: "_readFile" has already been set');
+    TinyI18.#readFile = value;
+  }
+
+  /**
+   * Sets the asynchronous file write function.
+   * Throws if a non-function value is provided or if the function has already been set.
+   * @param {(path: string, data: string, options: BufferEncoding) => Promise<void>} value - The file write function to cache.
+   */
+  static set _writeFile(value) {
+    if (typeof value !== 'function')
+      throw new TypeError('TinyI18: "_writeFile" must be a function');
+    if (TinyI18.#writeFile !== null) throw new Error('TinyI18: "_writeFile" has already been set');
+    TinyI18.#writeFile = value;
+  }
+
   /**
    * Merges multiple JSON locale files into a single file for TinyI18 usage.
-   * @param {Object} options
+   *
+   * @param {Object} options - Configuration for the merge operation.
    * @param {string[]} options.files - List of JSON file paths to merge.
    * @param {string} options.output - Path where the merged JSON file will be written.
-   * @param {number} [options.spaces=0] - Number of spaces to use for indentation in the output file (0 for compact JSON).
+   * @param {number} [options.spaces=0] - Number of spaces to use for indentation in the output file.
    * @throws {TypeError} If arguments are invalid.
    * @throws {Error} If file reading or writing fails.
    */
   static async mergeLocaleFiles({ files, output, spaces = 0 }) {
+    if (TinyI18.#existsSync === null || TinyI18.#readFile === null || TinyI18.#writeFile === null)
+      throw new Error(
+        'TinyI18: "mergeLocaleFiles" requires "_existsSync", "_readFile", and "_writeFile" to be set',
+      );
+
     if (typeof spaces !== 'number' || Number.isNaN(spaces) || spaces < 0)
       throw new TypeError('mergeLocaleFiles: "spaces" must be a non-negative number');
     if (!Array.isArray(files) || files.length === 0)
@@ -153,10 +228,10 @@ class TinyI18 {
     for (const filePath of files) {
       if (typeof filePath !== 'string' || !filePath)
         throw new TypeError('mergeLocaleFiles: each file path must be a non-empty string');
-      if (!fs.existsSync(filePath))
+      if (TinyI18.#existsSync !== false && !TinyI18.#existsSync(filePath))
         throw new Error(`mergeLocaleFiles: file "${filePath}" does not exist`);
 
-      const raw = await promises.readFile(filePath, 'utf-8');
+      const raw = await TinyI18.#readFile(filePath, 'utf-8');
       let json;
       try {
         json = JSON.parse(raw);
@@ -168,11 +243,11 @@ class TinyI18 {
       Object.assign(merged, json);
     }
 
-    await promises.writeFile(output, JSON.stringify(merged, null, spaces), 'utf-8');
+    await TinyI18.#writeFile(output, JSON.stringify(merged, null, spaces), 'utf-8');
   }
 
   /**
-   * Tracks whether the instance has been destroyed.
+   * Indicates whether the instance has been destroyed.
    * @type {boolean}
    */
   #destroyed = false;
@@ -186,33 +261,31 @@ class TinyI18 {
     return this.#destroyed;
   }
 
-  /** @type {ModeTypes} */
+  /** @type {ModeTypes} - The current operating mode of the instance. */
   #mode;
-  /** @type {LocaleCode} */
+  /** @type {LocaleCode} - The default fallback locale. */
   #defaultLocale;
-  /** @type {LocaleCode|null} */
+  /** @type {LocaleCode|null} - The currently active locale. */
   #currentLocale = null;
-  /** @type {boolean} */
+  /** @type {boolean} - Whether to throw errors on missing keys or invalid data. */
   #strict;
-  /** @type {string|null} */
+  /** @type {boolean} - Whether to return null instead of the key for missing translations. */
+  #acceptNullResults = false;
+  /** @type {string|null} - The base directory for file-mode operations. */
   #basePath = null;
 
-  /** @type {Map<LocaleCode, Dict>} */
-  #stringTables = new Map(); // plain key => string | { $fn } | Function
-
-  /** @type {Map<LocaleCode, PatternEntry[]>} */
-  #patternTables = new Map(); // array of { $pattern: RegExp, value }
-
-  // Helpers registry for function-based entries in both modes.
-  /** @type {Map<string, HelperCallback>} */
+  /** @type {Map<LocaleCode, Dict>} - Internal storage for string translations per locale. */
+  #stringTables = new Map();
+  /** @type {Map<LocaleCode, PatternEntry[]>} - Internal storage for regex pattern entries per locale. */
+  #patternTables = new Map();
+  /** @type {Map<string, HelperCallback<any, any>>} - Registry of available helper functions. */
   #helpers = new Map();
-
-  /** @type {Map<string, RegExp>} */
+  /** @type {Map<string, RegExp>} - Cache for compiled regular expression objects. */
   #regexCache = new Map();
 
   /**
    * Gets the currently selected locale, or null if only default is active.
-   * @returns {LocaleCode|null}
+   * @returns {LocaleCode|null} The currently active locale code, or null.
    */
   get currentLocale() {
     checkDestroy(this.#destroyed);
@@ -251,6 +324,15 @@ class TinyI18 {
     return this.#strict;
   }
 
+  /**
+   * Whether null results are accepted when a translation is missing.
+   * @type {boolean}
+   */
+  get acceptNullResults() {
+    checkDestroy(this.#destroyed);
+    return this.#acceptNullResults;
+  }
+
   /**
    * Base directory path used in `"file"` mode to locate locale JSON files.
    * - In `"local"` mode this will always be `null`.
@@ -264,7 +346,7 @@ class TinyI18 {
 
   /**
    * Returns basic stats for debugging/memory insights.
-   * @returns {StatLocale[]}
+   * @returns {StatLocale[]} Array of statistics for each registered locale.
    */
   get stats() {
     checkDestroy(this.#destroyed);
@@ -276,7 +358,7 @@ class TinyI18 {
   /**
    * Deep-cloned view of string tables (Map → Object).
    * Preserves strings, $fn objects, and functions.
-   * @returns {Record<string, Dict>}
+   * @returns {Record<string, Dict>} A deep clone of the string tables.
    */
   get stringTables() {
     checkDestroy(this.#destroyed);
@@ -291,7 +373,7 @@ class TinyI18 {
   /**
    * Deep-cloned view of pattern tables (Map → Object).
    * Recreates RegExp objects to avoid mutation.
-   * @returns {Record<string, PatternEntry[]>}
+   * @returns {Record<string, PatternEntry[]>} A deep clone of the pattern tables.
    */
   get patternTables() {
     checkDestroy(this.#destroyed);
@@ -310,11 +392,11 @@ class TinyI18 {
   /**
    * Deep-cloned view of helpers (Map → Object).
    * Functions are referenced (cannot deep clone functions).
-   * @returns {Record<string, HelperCallback>}
+   * @returns {Record<string, HelperCallback<any, any>>} A copy of the helpers registry.
    */
   get helpers() {
     checkDestroy(this.#destroyed);
-    /** @type {Record<string, HelperCallback>} */
+    /** @type {Record<string, HelperCallback<any, any>>} */
     const obj = {};
     for (const [name, fn] of this.#helpers.entries()) {
       obj[name] = fn;
@@ -325,7 +407,7 @@ class TinyI18 {
   /**
    * Deep-cloned view of regex cache (Map → Object).
    * Recreates RegExp objects to avoid mutation.
-   * @returns {Record<string, RegExp>}
+   * @returns {Record<string, RegExp>} A copy of the regex cache.
    */
   get regexCache() {
     checkDestroy(this.#destroyed);
@@ -345,8 +427,8 @@ class TinyI18 {
    * - Objects/arrays are recursively cloned
    * - Functions are returned as-is
    * - RegExp are cloned
-   * @param {any} value
-   * @returns {any}
+   * @param {any} value - The value to clone.
+   * @returns {any} The deep-cloned value.
    */
   #deepClone(value) {
     if (
@@ -439,9 +521,11 @@ class TinyI18 {
    * - function (params, helpers) => any
    * - { $fn: string, args?: any }   // file mode placeholder resolved via helpers
    *
-   * @param {string | HelperCallback | { $fn: string; args?: any }} value
-   * @param {Dict} [params]
-   * @returns {string}
+   * @template {any} T
+   * @template {any} R
+   * @param {string | HelperCallback<T, R> | { $fn: string; args?: any }} value - The raw translation value.
+   * @param {Dict} [params] - Data used for interpolation or helper arguments.
+   * @returns {string} The processed translation string.
    */
   #materialize(value, params) {
     if (value === null || value === undefined) {
@@ -613,18 +697,20 @@ class TinyI18 {
    * - `$pattern` entries are compiled to RegExp and stored in the pattern table.
    * - `$fn` references are preserved for later resolution via helpers.
    *
-   * @param {LocaleCode} locale - Locale identifier (e.g. "en", "pt-BR").
-   * @returns {Promise<void>}
+   * @param {LocaleCode} locale - Locale identifier (e.g., "en", "pt-BR").
+   * @returns {Promise<void>} A promise that resolves when the locale file has been loaded and ingested.
    */
   async #loadLocaleFromFile(locale) {
+    if (TinyI18.#join === null || TinyI18.#readFile === null)
+      throw new Error('TinyI18: "file" mode requires "_join" and "_readFile" to be set');
     if (typeof locale !== 'string' || !locale)
       throw new TypeError('#loadLocaleFromFile: "locale" must be a non-empty string');
     if (typeof this.#basePath !== 'string' || !this.#basePath)
       throw new TypeError('#loadLocaleFromFile: "this.#basePath" must be a non-empty string');
-    const file = path.join(this.#basePath, `${locale}.json`);
+    const file = TinyI18.#join(this.#basePath, `${locale}.json`);
     let json;
     try {
-      const raw = await promises.readFile(file, 'utf8');
+      const raw = await TinyI18.#readFile(file, 'utf8');
       json = JSON.parse(raw);
     } catch (err) {
       if (!(err instanceof Error)) return;
@@ -645,7 +731,7 @@ class TinyI18 {
 
     /**
      * @param {string} prefix
-     * @param {FileValue|string|null} node
+     * @param {FileValue|TranslateResult} node
      */
     const walk = (prefix, node) => {
       if (node == null) return;
@@ -696,7 +782,7 @@ class TinyI18 {
    * In strict mode, throws on invalid regex; otherwise returns a never-matching regex.
    *
    * @param {string} src - Regex source pattern (no flags allowed).
-   * @returns {RegExp}
+   * @returns {RegExp} The compiled regular expression, or a never-matching regex in non-strict mode.
    */
   #safeRegExp(src) {
     if (typeof src !== 'string' || !src)
@@ -721,8 +807,8 @@ class TinyI18 {
    * - string → returned as-is
    * - { $fn: string, args?: any } → preserved for helper resolution
    *
-   * @param {string|FileValue} v
-   * @returns {string|{ $fn: string, args?: any }}
+   * @param {string|FileValue} v - The value to normalize.
+   * @returns {TranslationValue} The normalized translation value.
    */
   #coerceFileValue(v) {
     // Strings pass through; objects with $fn kept as-is; everything else ignored gracefully
@@ -752,13 +838,22 @@ class TinyI18 {
     if (!options || typeof options !== 'object') {
       throw new TypeError('TinyI18: options must be an object');
     }
-    const { mode, defaultLocale, basePath, localResources, strict = true } = options;
+    const {
+      mode,
+      defaultLocale,
+      basePath,
+      localResources,
+      strict = true,
+      acceptNullResults = false,
+    } = options;
 
     if (mode !== 'local' && mode !== 'file')
       throw new TypeError('TinyI18: "mode" must be "local" or "file"');
     if (typeof defaultLocale !== 'string' || !defaultLocale)
       throw new TypeError('TinyI18: "defaultLocale" must be a non-empty string');
     if (typeof strict !== 'boolean') throw new TypeError('TinyI18: "strict" must be a boolean');
+    if (typeof acceptNullResults !== 'boolean')
+      throw new TypeError('TinyI18: "acceptNullResults" must be a boolean');
 
     if (mode === 'file') {
       if (typeof basePath !== 'string' || !basePath)
@@ -769,6 +864,7 @@ class TinyI18 {
     this.#mode = mode;
     this.#defaultLocale = defaultLocale;
     this.#strict = strict;
+    this.#acceptNullResults = acceptNullResults;
 
     if (mode === 'local' && localResources && typeof localResources === 'object') {
       for (const [loc, data] of Object.entries(localResources)) {
@@ -799,8 +895,10 @@ class TinyI18 {
 
   /**
    * Registers a helper function available to function-based entries and $fn references.
-   * @param {string} name
-   * @param {HelperCallback} fn
+   * @template {any} T
+   * @template {any} R
+   * @param {string} name - The unique name of the helper.
+   * @param {HelperCallback<T, R>} fn - The callback function to register.
    */
   registerHelper(name, fn) {
     checkDestroy(this.#destroyed);
@@ -821,14 +919,14 @@ class TinyI18 {
   unregisterHelper(name) {
     checkDestroy(this.#destroyed);
     if (typeof name !== 'string' || !name)
-      throw new TypeError('unregisterHelper: "name" must be non-empty string');
+      throw new TypeError('unregisterHelper: "name" must be a non-empty string');
     return this.#helpers.delete(name);
   }
 
   /**
    * Loads or updates a locale data in-memory (local mode only).
-   * @param {LocaleCode} locale
-   * @param {Dict} data
+   * @param {LocaleCode} locale - The locale to load.
+   * @param {Dict} data - The dictionary data for the locale.
    */
   loadLocaleLocal(locale, data) {
     checkDestroy(this.#destroyed);
@@ -840,7 +938,8 @@ class TinyI18 {
   /**
    * Sets the current selected locale. In file mode, loads it from disk.
    * Keeps only the default and the selected locale in memory (unloads previous selected).
-   * @param {LocaleCode|null} locale - null -> keep only default
+   * @param {LocaleCode|null} locale - The locale to set, or null to use only the default.
+   * @returns {Promise<void>} A promise that resolves when the locale has been set and loaded.
    */
   async setLocale(locale) {
     checkDestroy(this.#destroyed);
@@ -875,7 +974,7 @@ class TinyI18 {
    * @param {string} key - Translation key (dot.notation).
    * @param {Dict} [params] - Parameters for string interpolation or helper functions.
    * @param {ResolveOptions} [options] - Override resolution options (e.g., force locale).
-   * @returns {any} - Usually string, but may be HTMLElement, DocumentFragment, or any return type from a helper.
+   * @returns {TranslateResult} - Usually string, but may be HTMLElement, DocumentFragment, or any return type from a helper.
    */
   t(key, params = undefined, options = undefined) {
     return this.get(key, params, options);
@@ -883,10 +982,10 @@ class TinyI18 {
 
   /**
    * Alias of t()
-   * @param {string} key
-   * @param {Dict} [params]
-   * @param {ResolveOptions} [options]
-   * @returns {any}
+   * @param {string} key - Translation key (dot.notation).
+   * @param {Dict} [params] - Parameters for string interpolation or helper functions.
+   * @param {ResolveOptions} [options] - Override resolution options (e.g., force locale).
+   * @returns {TranslateResult} - Usually string, but may be HTMLElement, DocumentFragment, or any return type from a helper.
    */
   get(key, params = undefined, options = undefined) {
     checkDestroy(this.#destroyed);
@@ -899,6 +998,7 @@ class TinyI18 {
     let resolved = this.#resolveExact(order, key);
     if (resolved === undefined) {
       if (this.#strict) throw new Error(`TinyI18: missing translation for key "${key}"`);
+      if (this.#acceptNullResults) return null;
       return key; // graceful fallback to key
     }
 
@@ -912,7 +1012,7 @@ class TinyI18 {
    *
    * @param {string} key - Input string to test against regex patterns.
    * @param {ResolveOptions} [options] - Override resolution options (e.g., force locale).
-   * @returns {any} - Translation value (string or custom return type).
+   * @returns {TranslateResult} - Translation value (string or custom return type).
    */
   p(key, options) {
     return this.resolveByPattern(key, options);
@@ -920,9 +1020,9 @@ class TinyI18 {
 
   /**
    * Alias of p()
-   * @param {string} key
-   * @param {ResolveOptions} [options]
-   * @returns {any}
+   * @param {string} key - Input string to test against regex patterns.
+   * @param {ResolveOptions} [options] - Override resolution options (e.g., force locale).
+   * @returns {TranslateResult} - Translation value (string or custom return type).
    */
   resolveByPattern(key, options) {
     checkDestroy(this.#destroyed);
@@ -933,6 +1033,7 @@ class TinyI18 {
     let resolved = this.#resolveByPattern(order, key);
     if (resolved === undefined) {
       if (this.#strict) throw new Error(`TinyI18: missing translation for key "${key}"`);
+      if (this.#acceptNullResults) return null;
       return key; // graceful fallback to key
     }
     return resolved;
@@ -956,8 +1057,8 @@ class TinyI18 {
 
   /**
    * Returns stats for a specific locale.
-   * @param {LocaleCode} locale
-   * @returns {StatLocale}
+   * @param {LocaleCode} locale - The locale code to query.
+   * @returns {StatLocale} An object containing the locale's current statistics.
    * @throws {Error} If the locale is not registered.
    */
   getStatsForLocale(locale) {
@@ -984,7 +1085,7 @@ class TinyI18 {
    * to free up memory. Once destroyed, the instance cannot be reused.
    *
    * @throws {Error} If the instance has already been destroyed.
-   * @returns {void}
+   * @returns {void} This method does not return a value.
    */
   destroy() {
     if (this.#destroyed) return;