tiny-essentials 1.28.18 → 1.29.0

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

@@ -1,7 +1,4 @@
-import { readFile, writeFile } from 'fs/promises';
-import { existsSync } from 'fs';
-import { join as pathJoin } from 'path';
-import { createCheckDestroyed } from '../utils/tools.mjs';
+import { createCheckDestroyed } from '../../utils/tools.mjs';
 const checkDestroy = createCheckDestroyed('TinyI18');
 /**
  * Supported operating modes for TinyI18.
@@ -12,66 +9,67 @@ const checkDestroy = 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).
+ * @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.
+ */
+/**
+ * Represents a translation entry as it appears in JSON files, extending
+ * the base pattern/function fields with arbitrary string key-value pairs.
  *
- * `$fn` - Helper function name associated with this entry.
-
- * `[key]` - Additional key-value pairs for interpolation or extra metadata.
+ * @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.
@@ -82,12 +80,12 @@ const checkDestroy = 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.
@@ -98,9 +96,11 @@ const checkDestroy = 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.
  */
 /**
@@ -115,16 +115,87 @@ const checkDestroy = 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)
@@ -135,9 +206,9 @@ 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 (!existsSync(filePath))
+            if (TinyI18.#existsSync !== false && !TinyI18.#existsSync(filePath))
                 throw new Error(`mergeLocaleFiles: file "${filePath}" does not exist`);
-            const raw = await readFile(filePath, 'utf-8');
+            const raw = await TinyI18.#readFile(filePath, 'utf-8');
             let json;
             try {
                 json = JSON.parse(raw);
@@ -148,10 +219,10 @@ class TinyI18 {
             // Deep merge (locale-based)
             Object.assign(merged, json);
         }
-        await 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;
@@ -163,28 +234,29 @@ class TinyI18 {
     get destroyed() {
         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);
@@ -219,6 +291,14 @@ class TinyI18 {
         checkDestroy(this.#destroyed);
         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`.
@@ -231,7 +311,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);
@@ -243,7 +323,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);
@@ -257,7 +337,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);
@@ -275,11 +355,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;
@@ -289,7 +369,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);
@@ -307,8 +387,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 (value == null ||
@@ -398,9 +478,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) {
@@ -563,18 +645,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 = pathJoin(this.#basePath, `${locale}.json`);
+        const file = TinyI18.#join(this.#basePath, `${locale}.json`);
         let json;
         try {
-            const raw = await readFile(file, 'utf8');
+            const raw = await TinyI18.#readFile(file, 'utf8');
             json = JSON.parse(raw);
         }
         catch (err) {
@@ -596,7 +680,7 @@ class TinyI18 {
         const patterns = [...(this.#patternTables.get(locale) ?? [])];
         /**
          * @param {string} prefix
-         * @param {FileValue|string|null} node
+         * @param {FileValue|TranslateResult} node
          */
         const walk = (prefix, node) => {
             if (node == null)
@@ -639,7 +723,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)
@@ -666,8 +750,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
@@ -697,13 +781,15 @@ 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)
                 throw new TypeError('TinyI18: "basePath" is required in file mode');
@@ -712,6 +798,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)) {
                 this.#ingestLocale(loc, data);
@@ -737,8 +824,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);
@@ -759,13 +848,13 @@ 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);
@@ -776,7 +865,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);
@@ -808,17 +898,17 @@ 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);
     }
     /**
      * 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);
@@ -830,6 +920,8 @@ class TinyI18 {
         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 this.#materialize(resolved, params);
@@ -841,16 +933,16 @@ 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);
     }
     /**
      * 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);
@@ -862,6 +954,8 @@ class TinyI18 {
         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;
@@ -883,8 +977,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) {
@@ -908,7 +1002,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)