@safeaccess/inline 0.1.1 → 0.1.2

package/dist/path-query/segment-path-resolver.js

@@ -0,0 +1,351 @@
+import { SecurityException } from '../exceptions/security-exception.js';
+import { SegmentType } from './segment-type.js';
+/**
+ * Resolve typed path segments against nested data structures.
+ *
+ * Traverses data using segment arrays produced by {@link SegmentParser},
+ * dispatching to segment-type-specific handlers for key, wildcard,
+ * descent, filter, slice, multi-key/index, and projection operations.
+ *
+ * @internal
+ *
+ * @see SegmentParser           Produces the segment arrays this resolver consumes.
+ * @see SegmentType             Enum governing which handler is dispatched.
+ * @see FilterEvaluatorInterface  Delegate for filter predicate evaluation.
+ * @see DotNotationParser       Invokes this resolver for path queries.
+ */
+export class SegmentPathResolver {
+    segmentFilterParser;
+    /**
+     * Create a resolver with a filter evaluator.
+     *
+     * @param segmentFilterParser - Delegate for filter evaluation.
+     */
+    constructor(segmentFilterParser) {
+        this.segmentFilterParser = segmentFilterParser;
+    }
+    /**
+     * Resolve a value by walking segments starting at the given index.
+     *
+     * @param current - Current data node.
+     * @param segments - Typed segment array from {@link SegmentParser}.
+     * @param index - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     *
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     */
+    resolve(current, segments, index, defaultValue, maxDepth) {
+        if (index > maxDepth) {
+            throw new SecurityException(`Recursion depth ${index} exceeds maximum of ${maxDepth}.`);
+        }
+        if (index >= segments.length) {
+            return current;
+        }
+        const segment = segments[index];
+        switch (segment.type) {
+            case SegmentType.Descent:
+                return this.segmentDescent(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.DescentMulti:
+                return this.segmentDescentMulti(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Wildcard:
+                return this.segmentWildcard(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Filter:
+                return this.segmentFilter(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.MultiKey:
+                return this.segmentMultiKey(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.MultiIndex:
+                return this.segmentMultiIndex(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Slice:
+                return this.segmentSlice(current, segments, index, defaultValue, maxDepth);
+            case SegmentType.Projection:
+                return this.segmentProjection(current, segments, index, defaultValue, maxDepth);
+            default:
+                return this.segmentAny(current, segments, index, defaultValue, maxDepth);
+        }
+    }
+    /**
+     * Resolve a simple key/index segment.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Resolved value or the default.
+     */
+    segmentAny(current, segments, index, defaultValue, maxDepth) {
+        const segment = segments[index];
+        const keyValue = 'value' in segment ? segment.value : '';
+        if (typeof current === 'object' &&
+            current !== null &&
+            Object.prototype.hasOwnProperty.call(current, keyValue)) {
+            return this.resolve(current[keyValue], segments, index + 1, defaultValue, maxDepth);
+        }
+        return defaultValue;
+    }
+    /**
+     * Resolve a recursive descent segment for a single key.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching the descent key.
+     */
+    segmentDescent(current, segments, index, defaultValue, maxDepth) {
+        const results = [];
+        const segment = segments[index];
+        const descentKey = segment.key;
+        this.collectDescent(current, descentKey, segments, index + 1, defaultValue, results, maxDepth);
+        return results;
+    }
+    /**
+     * Resolve a recursive descent segment for multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of all values matching any of the descent keys.
+     */
+    segmentDescentMulti(current, segments, index, defaultValue, maxDepth) {
+        const segment = segments[index];
+        const descentKeys = segment.keys;
+        const results = [];
+        for (const dk of descentKeys) {
+            this.collectDescent(current, dk, segments, index + 1, defaultValue, results, maxDepth);
+        }
+        return results.length > 0 ? results : defaultValue;
+    }
+    /**
+     * Resolve a wildcard segment, expanding all children.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for all children.
+     */
+    segmentWildcard(current, segments, index, defaultValue, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        const nextIndex = index + 1;
+        return items.map((item) => this.resolve(item, segments, nextIndex, defaultValue, maxDepth));
+    }
+    /**
+     * Resolve a filter segment, applying predicates to array items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of items passing the filter predicate.
+     */
+    segmentFilter(current, segments, index, defaultValue, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+        const segment = segments[index];
+        const filterExpr = segment.expression;
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        const filtered = [];
+        for (const item of items) {
+            if (typeof item === 'object' && item !== null) {
+                if (this.segmentFilterParser.evaluate(item, filterExpr)) {
+                    filtered.push(item);
+                }
+            }
+        }
+        const nextIndex = index + 1;
+        return filtered.map((item) => this.resolve(item, segments, nextIndex, defaultValue, maxDepth));
+    }
+    /**
+     * Resolve a multi-key segment, selecting values by multiple keys.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each key.
+     */
+    segmentMultiKey(current, segments, index, defaultValue, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+        const nextIndex = index + 1;
+        const segment = segments[index];
+        const multiKeys = segment.keys;
+        const obj = current;
+        return multiKeys.map((k) => {
+            const val = Object.prototype.hasOwnProperty.call(obj, k) ? obj[k] : defaultValue;
+            return this.resolve(val, segments, nextIndex, defaultValue, maxDepth);
+        });
+    }
+    /**
+     * Resolve a multi-index segment, selecting values by multiple indices.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values for each index.
+     */
+    segmentMultiIndex(current, segments, index, defaultValue, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+        const nextIndex = index + 1;
+        const segment = segments[index];
+        const indices = segment.indices;
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        const len = items.length;
+        return indices.map((idx) => {
+            const resolved = idx < 0 ? (items[len + idx] ?? null) : (items[idx] ?? null);
+            if (resolved === null) {
+                return defaultValue;
+            }
+            return this.resolve(resolved, segments, nextIndex, defaultValue, maxDepth);
+        });
+    }
+    /**
+     * Resolve a slice segment on an array (start:end:step).
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Array of resolved values matching the slice range.
+     */
+    segmentSlice(current, segments, index, defaultValue, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return defaultValue;
+        }
+        const items = Array.isArray(current)
+            ? current
+            : Object.values(current);
+        const len = items.length;
+        const segment = segments[index];
+        const step = segment.step ?? 1;
+        let start = segment.start ?? (step > 0 ? 0 : len - 1);
+        let end = segment.end ?? (step > 0 ? len : -len - 1);
+        if (start < 0) {
+            start = Math.max(len + start, 0);
+        }
+        if (end < 0) {
+            end = len + end;
+        }
+        if (start >= len) {
+            start = len;
+        }
+        if (end > len) {
+            end = len;
+        }
+        const sliced = [];
+        if (step > 0) {
+            for (let si = start; si < end; si += step) {
+                sliced.push(items[si]);
+            }
+        }
+        else {
+            for (let si = start; si > end; si += step) {
+                sliced.push(items[si]);
+            }
+        }
+        const nextSliceIndex = index + 1;
+        return sliced.map((item) => this.resolve(item, segments, nextSliceIndex, defaultValue, maxDepth));
+    }
+    /**
+     * Resolve a projection segment, selecting specific fields from items.
+     *
+     * @param current      - Current data node.
+     * @param segments     - Typed segment array.
+     * @param index        - Current segment index.
+     * @param defaultValue - Fallback value when resolution fails.
+     * @param maxDepth     - Maximum recursion depth.
+     * @returns Projected item(s) with only the specified fields.
+     */
+    segmentProjection(current, segments, index, defaultValue, maxDepth) {
+        const segment = segments[index];
+        const fields = segment.fields;
+        const projectItem = (item) => {
+            if (typeof item !== 'object' || item === null) {
+                const result = {};
+                for (const field of fields) {
+                    result[field.alias] = null;
+                }
+                return result;
+            }
+            const obj = item;
+            const result = {};
+            for (const field of fields) {
+                result[field.alias] = Object.prototype.hasOwnProperty.call(obj, field.source)
+                    ? obj[field.source]
+                    : null;
+            }
+            return result;
+        };
+        const nextProjectionIndex = index + 1;
+        if (Array.isArray(current)) {
+            const projected = current.map(projectItem);
+            return projected.map((item) => this.resolve(item, segments, nextProjectionIndex, defaultValue, maxDepth));
+        }
+        if (typeof current === 'object' && current !== null) {
+            const result = projectItem(current);
+            return this.resolve(result, segments, nextProjectionIndex, defaultValue, maxDepth);
+        }
+        return defaultValue;
+    }
+    /**
+     * Recursively collect values matching a descent key from nested data.
+     *
+     * @param current - Current data node.
+     * @param key - Key to search for recursively.
+     * @param segments - Typed segment array.
+     * @param nextIndex - Next segment index after the descent.
+     * @param defaultValue - Fallback value.
+     * @param results - Collector array (mutated in place).
+     * @param maxDepth - Maximum recursion depth.
+     */
+    collectDescent(current, key, segments, nextIndex, defaultValue, results, maxDepth) {
+        if (typeof current !== 'object' || current === null) {
+            return;
+        }
+        const obj = current;
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            if (nextIndex >= segments.length) {
+                results.push(obj[key]);
+            }
+            else {
+                const resolved = this.resolve(obj[key], segments, nextIndex, defaultValue, maxDepth);
+                if (Array.isArray(resolved)) {
+                    results.push(...resolved);
+                }
+                else {
+                    results.push(resolved);
+                }
+            }
+        }
+        for (const child of Object.values(obj)) {
+            if (typeof child === 'object' && child !== null) {
+                this.collectDescent(child, key, segments, nextIndex, defaultValue, results, maxDepth);
+            }
+        }
+    }
+}

package/dist/path-query/segment-type.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Enumerate all segment types produced by the path parser.
+ *
+ * Each case represents a distinct addressing mode within a dot-notation
+ * path expression. The {@link SegmentPathResolver} dispatches resolution
+ * logic based on the segment type.
+ *
+ * @internal
+ *
+ * @see SegmentParser        Parses path strings into typed segment arrays.
+ * @see SegmentPathResolver  Resolves data values from typed segments.
+ */
+export declare enum SegmentType {
+    /** Simple key or index access (e.g. `foo`, `0`). */
+    Key = "key",
+    /** Numeric index access (e.g. `[0]`). */
+    Index = "index",
+    /** Wildcard expansion over all children (e.g. `*`, `[*]`). */
+    Wildcard = "wildcard",
+    /** Recursive descent into a single key (e.g. `..name`). */
+    Descent = "descent",
+    /** Recursive descent into multiple keys (e.g. `..["a","b"]`). */
+    DescentMulti = "descent-multi",
+    /** Multi-index selection (e.g. `[0,1,2]`). */
+    MultiIndex = "multi-index",
+    /** Multi-key selection (e.g. `['a','b']`). */
+    MultiKey = "multi-key",
+    /** Filter predicate expression (e.g. `[?age>18]`). */
+    Filter = "filter",
+    /** Array slice notation (e.g. `[0:5]`, `[::2]`). */
+    Slice = "slice",
+    /** Field projection (e.g. `.{name, age}`). */
+    Projection = "projection"
+}
+/** Parsed filter expression structure. */
+export interface FilterExpression {
+    readonly conditions: ReadonlyArray<FilterCondition>;
+    readonly logicals: ReadonlyArray<string>;
+}
+/** A single parsed filter condition. */
+export interface FilterCondition {
+    readonly field: string;
+    readonly operator: string;
+    readonly value: boolean | null | number | string;
+    readonly func?: string;
+    readonly funcArgs?: ReadonlyArray<string>;
+}
+/** Projection field mapping. */
+export interface ProjectionField {
+    readonly alias: string;
+    readonly source: string;
+}
+/** Discriminated union of all possible segment shapes. */
+export type Segment = {
+    readonly type: SegmentType.Key;
+    readonly value: string;
+} | {
+    readonly type: SegmentType.Index;
+    readonly value: string;
+} | {
+    readonly type: SegmentType.Wildcard;
+} | {
+    readonly type: SegmentType.Descent;
+    readonly key: string;
+} | {
+    readonly type: SegmentType.DescentMulti;
+    readonly keys: ReadonlyArray<string>;
+} | {
+    readonly type: SegmentType.MultiIndex;
+    readonly indices: ReadonlyArray<number>;
+} | {
+    readonly type: SegmentType.MultiKey;
+    readonly keys: ReadonlyArray<string>;
+} | {
+    readonly type: SegmentType.Filter;
+    readonly expression: FilterExpression;
+} | {
+    readonly type: SegmentType.Slice;
+    readonly start: number | null;
+    readonly end: number | null;
+    readonly step: number | null;
+} | {
+    readonly type: SegmentType.Projection;
+    readonly fields: ReadonlyArray<ProjectionField>;
+};

package/dist/path-query/segment-type.js

@@ -0,0 +1,35 @@
+/**
+ * Enumerate all segment types produced by the path parser.
+ *
+ * Each case represents a distinct addressing mode within a dot-notation
+ * path expression. The {@link SegmentPathResolver} dispatches resolution
+ * logic based on the segment type.
+ *
+ * @internal
+ *
+ * @see SegmentParser        Parses path strings into typed segment arrays.
+ * @see SegmentPathResolver  Resolves data values from typed segments.
+ */
+export var SegmentType;
+(function (SegmentType) {
+    /** Simple key or index access (e.g. `foo`, `0`). */
+    SegmentType["Key"] = "key";
+    /** Numeric index access (e.g. `[0]`). */
+    SegmentType["Index"] = "index";
+    /** Wildcard expansion over all children (e.g. `*`, `[*]`). */
+    SegmentType["Wildcard"] = "wildcard";
+    /** Recursive descent into a single key (e.g. `..name`). */
+    SegmentType["Descent"] = "descent";
+    /** Recursive descent into multiple keys (e.g. `..["a","b"]`). */
+    SegmentType["DescentMulti"] = "descent-multi";
+    /** Multi-index selection (e.g. `[0,1,2]`). */
+    SegmentType["MultiIndex"] = "multi-index";
+    /** Multi-key selection (e.g. `['a','b']`). */
+    SegmentType["MultiKey"] = "multi-key";
+    /** Filter predicate expression (e.g. `[?age>18]`). */
+    SegmentType["Filter"] = "filter";
+    /** Array slice notation (e.g. `[0:5]`, `[::2]`). */
+    SegmentType["Slice"] = "slice";
+    /** Field projection (e.g. `.{name, age}`). */
+    SegmentType["Projection"] = "projection";
+})(SegmentType || (SegmentType = {}));

package/dist/security/forbidden-keys.d.ts

@@ -5,7 +5,7 @@
  * the same word prefix (e.g. `node_modules`) are not blocked.
  *
  * PHP-specific wrappers (`phar://`, `php://`, `expect://`, `glob://`, `zlib://`,
- * `ogg://`, `rar://`, `zip://`, `ssh2.tunnel://`) are intentionally absent — they
+ * `ogg://`, `rar://`, `zip://`, `ssh2.tunnel://`) are intentionally absent - they
  * have no meaning in a JavaScript/Node.js runtime.
  *
  * `data:` uses a single-colon delimiter (matching the browser RFC 2397 format
@@ -26,7 +26,7 @@ export declare const STREAM_WRAPPER_PREFIXES: readonly string[];
  * – `hasOwnProperty` shadow (overriding it can bypass guard checks)
  * – JS-relevant stream wrapper / protocol scheme strings as exact-match defence-in-depth
  *
- * PHP magic methods and PHP superglobals are deliberately absent — they are not
+ * PHP magic methods and PHP superglobals are deliberately absent - they are not
  * meaningful in a JavaScript runtime and belong in the PHP package's SecurityGuard only.
  *
  * @internal

package/dist/security/forbidden-keys.js

@@ -5,7 +5,7 @@
  * the same word prefix (e.g. `node_modules`) are not blocked.
  *
  * PHP-specific wrappers (`phar://`, `php://`, `expect://`, `glob://`, `zlib://`,
- * `ogg://`, `rar://`, `zip://`, `ssh2.tunnel://`) are intentionally absent — they
+ * `ogg://`, `rar://`, `zip://`, `ssh2.tunnel://`) are intentionally absent - they
  * have no meaning in a JavaScript/Node.js runtime.
  *
  * `data:` uses a single-colon delimiter (matching the browser RFC 2397 format
@@ -37,7 +37,7 @@ export const STREAM_WRAPPER_PREFIXES = [
  * – `hasOwnProperty` shadow (overriding it can bypass guard checks)
  * – JS-relevant stream wrapper / protocol scheme strings as exact-match defence-in-depth
  *
- * PHP magic methods and PHP superglobals are deliberately absent — they are not
+ * PHP magic methods and PHP superglobals are deliberately absent - they are not
  * meaningful in a JavaScript runtime and belong in the PHP package's SecurityGuard only.
  *
  * @internal
@@ -52,13 +52,13 @@ export const DEFAULT_FORBIDDEN_KEYS = new Set([
     '__definesetter__',
     '__lookupgetter__',
     '__lookupsetter__',
-    // Object.prototype shadow key — overriding it can break hasOwnProperty-based guards
+    // Object.prototype shadow key - overriding it can break hasOwnProperty-based guards
     'hasOwnProperty',
-    // Node.js module-scope path globals — should never appear as data keys to
+    // Node.js module-scope path globals - should never appear as data keys to
     // prevent path-injection risks in code that reads them via dynamic property access
     '__dirname',
     '__filename',
-    // Stream wrapper and protocol exact entries — also caught by STREAM_WRAPPER_PREFIXES prefix matching.
+    // Stream wrapper and protocol exact entries - also caught by STREAM_WRAPPER_PREFIXES prefix matching.
     // The Set entries below are intentional defence-in-depth: they allow O(1) exact-key
     // lookup before the O(n) prefix loop runs.
     'file://',

package/dist/security/security-guard.d.ts

@@ -15,6 +15,8 @@ import type { SecurityGuardInterface } from '../contracts/security-guard-interfa
  * Stream wrapper URIs are matched by prefix so that fully-formed URIs such as
  * `javascript:alert(1)` are also blocked, not only the bare scheme string.
  *
+ * @api
+ *
  * @example
  * const guard = new SecurityGuard();
  * guard.assertSafeKey('name'); // OK
@@ -29,7 +31,7 @@ export declare class SecurityGuard implements SecurityGuardInterface {
      * @param maxDepth - Maximum recursion depth for recursive key scanning.
      * @param extraForbiddenKeys - Additional keys to forbid beyond defaults.
      */
-    constructor(maxDepth?: number, /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys?: string[]);
+    constructor(maxDepth?: number, extraForbiddenKeys?: string[]);
     /**
      * Check whether a key is in the forbidden list.
      *

package/dist/security/security-guard.js

@@ -16,6 +16,8 @@ import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-key
  * Stream wrapper URIs are matched by prefix so that fully-formed URIs such as
  * `javascript:alert(1)` are also blocked, not only the bare scheme string.
  *
+ * @api
+ *
  * @example
  * const guard = new SecurityGuard();
  * guard.assertSafeKey('name'); // OK
@@ -30,7 +32,8 @@ export class SecurityGuard {
      * @param maxDepth - Maximum recursion depth for recursive key scanning.
      * @param extraForbiddenKeys - Additional keys to forbid beyond defaults.
      */
-    constructor(maxDepth = 512, /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys = []) {
+    constructor(maxDepth = 512, 
+    /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys = []) {
         this.maxDepth = Number.isFinite(maxDepth) ? maxDepth : 512;
         /* Stryker disable next-line ConditionalExpression -- equivalent: if (false) still produces the same forbiddenKeysMap for empty arrays since Set(DEFAULT)=DEFAULT */
         if (extraForbiddenKeys.length === 0) {
@@ -59,7 +62,7 @@ export class SecurityGuard {
      * guard.isForbiddenKey('name');      // false
      */
     isForbiddenKey(key) {
-        // Normalise __* keys to lowercase — catches case variants such as __PROTO__.
+        // Normalise __* keys to lowercase - catches case variants such as __PROTO__.
         const lookupKey = key.startsWith('__') ? key.toLowerCase() : key;
         if (this.forbiddenKeysMap.has(lookupKey)) {
             return true;

package/dist/security/security-parser.d.ts

@@ -5,6 +5,8 @@ import type { SecurityParserInterface } from '../contracts/security-parser-inter
  * Validates payload size, maximum key count, recursion depth, and
  * structural depth limits.
  *
+ * @api
+ *
  * @example
  * const parser = new SecurityParser({ maxDepth: 10, maxKeys: 100 });
  * parser.assertPayloadSize('{"key":"value"}');
@@ -24,7 +26,7 @@ export declare class SecurityParser implements SecurityParserInterface {
      * @param options.maxKeys - Maximum total number of keys across the entire structure. Default: 10000.
      *   This value is also passed to `XmlParser` as the element-count cap for the Node.js manual XML
      *   parser path. Setting it below a document's element count will cause `fromXml()` to throw
-     *   `SecurityException`. Non-positive or non-finite values disable that guard — prefer the default.
+     *   `SecurityException`. Non-positive or non-finite values disable that guard - prefer the default.
      * @param options.maxCountRecursiveDepth - Maximum recursion depth when counting keys. Default: 100.
      * @param options.maxResolveDepth - Maximum recursion depth for path resolution. Default: 100.
      */
@@ -126,5 +128,12 @@ export declare class SecurityParser implements SecurityParserInterface {
      * @returns Maximum depth found.
      */
     private measureDepth;
+    /**
+     * Clamp an optional numeric option to its default when not finite.
+     *
+     * @param value - User-provided option value.
+     * @param defaultValue - Fallback when value is undefined or non-finite.
+     * @returns Clamped numeric value.
+     */
     private static clampOption;
 }

package/dist/security/security-parser.js

@@ -5,6 +5,8 @@ import { SecurityException } from '../exceptions/security-exception.js';
  * Validates payload size, maximum key count, recursion depth, and
  * structural depth limits.
  *
+ * @api
+ *
  * @example
  * const parser = new SecurityParser({ maxDepth: 10, maxKeys: 100 });
  * parser.assertPayloadSize('{"key":"value"}');
@@ -24,7 +26,7 @@ export class SecurityParser {
      * @param options.maxKeys - Maximum total number of keys across the entire structure. Default: 10000.
      *   This value is also passed to `XmlParser` as the element-count cap for the Node.js manual XML
      *   parser path. Setting it below a document's element count will cause `fromXml()` to throw
-     *   `SecurityException`. Non-positive or non-finite values disable that guard — prefer the default.
+     *   `SecurityException`. Non-positive or non-finite values disable that guard - prefer the default.
      * @param options.maxCountRecursiveDepth - Maximum recursion depth when counting keys. Default: 100.
      * @param options.maxResolveDepth - Maximum recursion depth for path resolution. Default: 100.
      */
@@ -185,6 +187,13 @@ export class SecurityParser {
         }
         return max;
     }
+    /**
+     * Clamp an optional numeric option to its default when not finite.
+     *
+     * @param value - User-provided option value.
+     * @param defaultValue - Fallback when value is undefined or non-finite.
+     * @returns Clamped numeric value.
+     */
     static clampOption(value, defaultValue) {
         /* Stryker disable next-line ConditionalExpression -- equivalent: Number.isFinite covers undefined (isFinite(undefined)===false); simplest safe form */
         return Number.isFinite(value) ? value : defaultValue;

package/dist/type-format.d.ts

@@ -3,6 +3,8 @@
  *
  * Used by {@link Inline.from} to select the appropriate accessor.
  *
+ * @api
+ *
  * @example
  * const accessor = Inline.from(TypeFormat.Json, '{"key":"value"}');
  */

package/dist/type-format.js

@@ -3,6 +3,8 @@
  *
  * Used by {@link Inline.from} to select the appropriate accessor.
  *
+ * @api
+ *
  * @example
  * const accessor = Inline.from(TypeFormat.Json, '{"key":"value"}');
  */