@safeaccess/inline 0.1.1 → 0.1.2

package/dist/accessors/formats/yaml-accessor.js

@@ -8,6 +8,8 @@ import { YamlParser } from '../../parser/yaml-parser.js';
  * depending on external YAML libraries. Tags, anchors, aliases, and
  * merge keys are blocked as unsafe constructs.
  *
+ * @api
+ *
  * @example
  * const accessor = new YamlAccessor(parser).from('key: value\nnested:\n  a: 1');
  * accessor.get('nested.a'); // 1
@@ -23,7 +25,7 @@ export class YamlAccessor extends AbstractAccessor {
      * @throws {SecurityException} When payload size exceeds limit.
      *
      * @example
-     * accessor.from('name: Alice\nage: 30');
+     * accessor.from('name: Alice\nage: 30'); // { name: 'Alice', age: 30 }
      */
     from(data) {
         if (typeof data !== 'string') {
@@ -41,6 +43,6 @@ export class YamlAccessor extends AbstractAccessor {
             return {};
         }
         /* c8 ignore stop */
-        return new YamlParser().parse(raw);
+        return new YamlParser(this.parser.getMaxDepth()).parse(raw);
     }
 }

package/dist/cache/simple-path-cache.d.ts

@@ -0,0 +1,51 @@
+import type { PathCacheInterface } from '../contracts/path-cache-interface.js';
+import type { Segment } from '../path-query/segment-type.js';
+/**
+ * LRU cache for parsed dot-notation path segments.
+ *
+ * Stores up to {@link maxSize} entries, evicting the least-recently-used
+ * entry when the capacity is reached. Recently accessed entries are
+ * promoted to the end of the internal map on read.
+ *
+ * @internal Consumers should type-hint against {@link PathCacheInterface};
+ *           this concrete class is an implementation detail subject to change.
+ *
+ * @see PathCacheInterface
+ */
+export declare class SimplePathCache implements PathCacheInterface {
+    private readonly maxSize;
+    private readonly cache;
+    /**
+     * Create a cache with the given maximum capacity.
+     *
+     * @param maxSize - Maximum number of cached path entries.
+     */
+    constructor(maxSize?: number);
+    /**
+     * Retrieve cached segments and promote to most-recently-used.
+     *
+     * @param path - Dot-notation path string.
+     * @returns Cached segments, or null on miss.
+     */
+    get(path: string): Segment[] | null;
+    /**
+     * Store segments, evicting the oldest entry if capacity is reached.
+     *
+     * @param path - Dot-notation path string.
+     * @param segments - Parsed segment array to cache.
+     */
+    set(path: string, segments: Segment[]): void;
+    /**
+     * Check whether a path exists in the cache.
+     *
+     * @param path - Dot-notation path string.
+     * @returns True if cached.
+     */
+    has(path: string): boolean;
+    /**
+     * Clear all cached entries.
+     *
+     * @returns Same instance for fluent chaining.
+     */
+    clear(): this;
+}

package/dist/cache/simple-path-cache.js

@@ -0,0 +1,72 @@
+/**
+ * LRU cache for parsed dot-notation path segments.
+ *
+ * Stores up to {@link maxSize} entries, evicting the least-recently-used
+ * entry when the capacity is reached. Recently accessed entries are
+ * promoted to the end of the internal map on read.
+ *
+ * @internal Consumers should type-hint against {@link PathCacheInterface};
+ *           this concrete class is an implementation detail subject to change.
+ *
+ * @see PathCacheInterface
+ */
+export class SimplePathCache {
+    maxSize;
+    cache = new Map();
+    /**
+     * Create a cache with the given maximum capacity.
+     *
+     * @param maxSize - Maximum number of cached path entries.
+     */
+    constructor(maxSize = 1000) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Retrieve cached segments and promote to most-recently-used.
+     *
+     * @param path - Dot-notation path string.
+     * @returns Cached segments, or null on miss.
+     */
+    get(path) {
+        if (this.cache.has(path)) {
+            const value = this.cache.get(path);
+            this.cache.delete(path);
+            this.cache.set(path, value);
+            return value;
+        }
+        return null;
+    }
+    /**
+     * Store segments, evicting the oldest entry if capacity is reached.
+     *
+     * @param path - Dot-notation path string.
+     * @param segments - Parsed segment array to cache.
+     */
+    set(path, segments) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(path, segments);
+    }
+    /**
+     * Check whether a path exists in the cache.
+     *
+     * @param path - Dot-notation path string.
+     * @returns True if cached.
+     */
+    has(path) {
+        return this.cache.has(path);
+    }
+    /**
+     * Clear all cached entries.
+     *
+     * @returns Same instance for fluent chaining.
+     */
+    clear() {
+        this.cache.clear();
+        return this;
+    }
+}

package/dist/contracts/accessors-interface.d.ts

@@ -6,6 +6,8 @@ import type { FactoryAccessorsInterface } from './factory-accessors-interface.js
  *
  * Marker interface that aggregates all accessor responsibilities into
  * a single type, used as the base contract for AbstractAccessor.
+ *
+ * @api
  */
 export interface AccessorsInterface extends ReadableAccessorsInterface, WritableAccessorsInterface, FactoryAccessorsInterface {
 }

package/dist/contracts/factory-accessors-interface.d.ts

@@ -3,6 +3,8 @@
  *
  * Note: this `from(data)` is the per-accessor hydrator, not
  * {@link Inline.from} which selects an accessor by TypeFormat.
+ *
+ * @api
  */
 export interface FactoryAccessorsInterface {
     /**

package/dist/contracts/filter-evaluator-interface.d.ts

@@ -0,0 +1,28 @@
+import type { FilterExpression } from '../path-query/segment-type.js';
+/**
+ * Contract for parsing and evaluating filter predicate expressions.
+ *
+ * Handles the `[?expression]` segment syntax, converting string predicates
+ * into structured condition arrays and evaluating them against data items.
+ *
+ * @internal
+ */
+export interface FilterEvaluatorInterface {
+    /**
+     * Parse a filter expression string into a structured condition array.
+     *
+     * @param expression - Raw filter expression (e.g. "age>18 && active==true").
+     * @returns Parsed conditions and logical operators.
+     *
+     * @throws {InvalidFormatException} When the expression syntax is invalid.
+     */
+    parse(expression: string): FilterExpression;
+    /**
+     * Evaluate a parsed expression against a single data item.
+     *
+     * @param item - Data item to test.
+     * @param expr - Parsed expression from {@link parse}.
+     * @returns True if the item satisfies the expression.
+     */
+    evaluate(item: Record<string, unknown>, expr: FilterExpression): boolean;
+}

package/dist/contracts/filter-evaluator-interface.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/parse-integration-interface.d.ts

@@ -4,6 +4,8 @@
  * Enables the {@link AnyAccessor} to accept arbitrary input by delegating
  * format validation and parsing to a user-provided implementation.
  *
+ * @api
+ *
  * @example
  * class CsvIntegration implements ParseIntegrationInterface {
  *   assertFormat(raw: unknown): boolean { return typeof raw === 'string' && raw.includes(','); }

package/dist/contracts/parser-interface.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Core contract for dot-notation path operations on object data.
+ *
+ * Defines the fundamental CRUD operations for reading, writing, and
+ * removing values from nested objects using dot-notation path strings
+ * or pre-parsed segment arrays.
+ *
+ * @internal Not part of the public API - consumers should not implement
+ *           or type-hint against this interface directly.
+ */
+export interface ParserInterface {
+    /**
+     * Retrieve a value at the given dot-notation path.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path (e.g. "user.address.city").
+     * @param defaultValue - Fallback value when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    get(data: Record<string, unknown>, path: string, defaultValue?: unknown): unknown;
+    /**
+     * Check whether a dot-notation path exists in the data.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path to check.
+     * @returns True if the path resolves to an existing value.
+     */
+    has(data: Record<string, unknown>, path: string): boolean;
+    /**
+     * Set a value at the given dot-notation path.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path for the target key.
+     * @param value - Value to assign.
+     * @returns New object with the value set.
+     *
+     * @throws {SecurityException} When the path contains forbidden keys.
+     */
+    set(data: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+    /**
+     * Remove a value at the given dot-notation path.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path to remove.
+     * @returns New object with the key removed.
+     *
+     * @throws {SecurityException} When the path contains forbidden keys.
+     */
+    remove(data: Record<string, unknown>, path: string): Record<string, unknown>;
+    /**
+     * Deep-merge an object into the value at the given path.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path to the merge target.
+     * @param value - Object to merge into the existing value.
+     * @returns New object with merged data.
+     *
+     * @throws {SecurityException} When merge depth exceeds the configured maximum.
+     * @throws {SecurityException} When keys contain forbidden values.
+     */
+    merge(data: Record<string, unknown>, path: string, value: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Retrieve a value using pre-parsed key segments.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys to traverse.
+     * @param defaultValue - Fallback value when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    getAt(data: Record<string, unknown>, segments: Array<string | number>, defaultValue?: unknown): unknown;
+    /**
+     * Set a value using pre-parsed key segments.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys to the target.
+     * @param value - Value to assign.
+     * @returns New object with the value set.
+     *
+     * @throws {SecurityException} When segments contain forbidden keys.
+     */
+    setAt(data: Record<string, unknown>, segments: Array<string | number>, value: unknown): Record<string, unknown>;
+    /**
+     * Remove a value using pre-parsed key segments.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys to the target.
+     * @returns New object with the key removed.
+     *
+     * @throws {SecurityException} When segments contain forbidden keys.
+     */
+    removeAt(data: Record<string, unknown>, segments: Array<string | number>): Record<string, unknown>;
+}

package/dist/contracts/parser-interface.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/path-cache-interface.d.ts

@@ -1,13 +1,14 @@
+import type { Segment } from '../path-query/segment-type.js';
 /**
  * Contract for a path-segment cache.
  *
  * Provides O(1) lookup for previously parsed dot-notation path strings,
  * avoiding repeated segment parsing on hot paths.
  *
- * Note: JS segments are flat `string[]` (from `path.split('.')`), whereas
- * PHP segments are structured `array<int, array<string, mixed>>` containing
- * SegmentType metadata. This architectural difference reflects each
- * language's parser implementation.
+ * Segments are structured typed arrays with {@link SegmentType} metadata,
+ * matching the PHP implementation.
+ *
+ * @api
  */
 export interface PathCacheInterface {
     /**
@@ -16,14 +17,14 @@ export interface PathCacheInterface {
      * @param path - Dot-notation path string.
      * @returns Cached segment array, or null if not cached.
      */
-    get(path: string): string[] | null;
+    get(path: string): Segment[] | null;
     /**
      * Store parsed segments for a path string.
      *
      * @param path - Dot-notation path string.
      * @param segments - Parsed segment array to cache.
      */
-    set(path: string, segments: string[]): void;
+    set(path: string, segments: Segment[]): void;
     /**
      * Check whether a path exists in the cache.
      *

package/dist/contracts/readable-accessors-interface.d.ts

@@ -3,6 +3,11 @@
  *
  * Defines methods for retrieving, checking existence, counting,
  * and inspecting keys within the accessor's internal data store.
+ *
+ * @api
+ *
+ * @see AbstractAccessor    Base implementation.
+ * @see AccessorsInterface  Composite interface extending this contract.
  */
 export interface ReadableAccessorsInterface {
     /**
@@ -63,17 +68,17 @@ export interface ReadableAccessorsInterface {
      */
     all(): Record<string, unknown>;
     /**
-     * Count elements at a path, or the root if undefined.
+     * Count elements at a path, or the root if null/undefined.
      *
-     * @param path - Dot-notation path, or undefined for root.
+     * @param path - Dot-notation path, or null/undefined for root.
      * @returns Number of elements.
      */
-    count(path?: string): number;
+    count(path?: string | null): number;
     /**
-     * Retrieve array keys at a path, or root keys if undefined.
+     * Retrieve array keys at a path, or root keys if null/undefined.
      *
-     * @param path - Dot-notation path, or undefined for root.
+     * @param path - Dot-notation path, or null/undefined for root.
      * @returns List of keys.
      */
-    keys(path?: string): string[];
+    keys(path?: string | null): string[];
 }

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

@@ -4,6 +4,8 @@
  * Prevents injection attacks by rejecting prototype pollution vectors,
  * legacy prototype manipulation methods, stream wrapper / protocol URI schemes,
  * and Node.js globals during data access and mutation operations.
+ *
+ * @api
  */
 export interface SecurityGuardInterface {
     /**

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

@@ -4,6 +4,8 @@
  * Defines methods for asserting payload size, maximum key counts,
  * and recursion depth limits to prevent resource exhaustion and
  * injection attacks during data access operations.
+ *
+ * @api
  */
 export interface SecurityParserInterface {
     /**

package/dist/contracts/validatable-parser-interface.d.ts

@@ -0,0 +1,59 @@
+import type { ParserInterface } from './parser-interface.js';
+/**
+ * Extended parser contract adding security validation capabilities.
+ *
+ * Adds structural validation and payload size assertion on top of
+ * the base {@link ParserInterface} CRUD operations.
+ *
+ * @internal Not part of the public API - used only by AbstractAccessor internally.
+ */
+export interface ValidatableParserInterface extends ParserInterface {
+    /**
+     * Retrieve a value at the given path, throwing when not found.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path.
+     * @returns Resolved value.
+     *
+     * @throws {PathNotFoundException} When the path does not exist.
+     */
+    getStrict(data: Record<string, unknown>, path: string): unknown;
+    /**
+     * Validate data structure against security constraints.
+     *
+     * Assert key safety, maximum keys, and structural depth
+     * using configured security guards and parser options.
+     *
+     * @param data - Data to validate.
+     *
+     * @throws {SecurityException} When any constraint is violated.
+     */
+    validate(data: Record<string, unknown>): void;
+    /**
+     * Assert that a raw string payload does not exceed size limits.
+     *
+     * @param input - Raw input string to check.
+     *
+     * @throws {SecurityException} When the payload exceeds the configured maximum.
+     */
+    assertPayload(input: string): void;
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * Used by accessors that perform their own recursive traversal
+     * (e.g. ObjectAccessor) before the post-parse validation step runs.
+     *
+     * @returns Maximum allowed structural depth.
+     */
+    getMaxDepth(): number;
+    /**
+     * Return the configured maximum total key count.
+     *
+     * Used by format parsers that enforce a document element-count limit before
+     * structural traversal runs. Accessor implementations that wrap XML parsers
+     * can pass this value as an upper bound to prevent document-bombing attacks.
+     *
+     * @returns Maximum allowed key count.
+     */
+    getMaxKeys(): number;
+}

package/dist/contracts/validatable-parser-interface.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/writable-accessors-interface.d.ts

@@ -3,6 +3,11 @@
  *
  * All mutations return a new instance with the modification applied,
  * preserving the original accessor instance.
+ *
+ * @api
+ *
+ * @see AccessorsInterface  Composite interface extending this contract.
+ * @see AbstractAccessor    Base implementation enforcing readonly guards.
  */
 export interface WritableAccessorsInterface {
     /**

package/dist/core/accessor-factory.d.ts

@@ -0,0 +1,124 @@
+import type { ValidatableParserInterface } from '../contracts/validatable-parser-interface.js';
+import type { ParseIntegrationInterface } from '../contracts/parse-integration-interface.js';
+import { ArrayAccessor } from '../accessors/formats/array-accessor.js';
+import { ObjectAccessor } from '../accessors/formats/object-accessor.js';
+import { JsonAccessor } from '../accessors/formats/json-accessor.js';
+import { XmlAccessor } from '../accessors/formats/xml-accessor.js';
+import { YamlAccessor } from '../accessors/formats/yaml-accessor.js';
+import { IniAccessor } from '../accessors/formats/ini-accessor.js';
+import { EnvAccessor } from '../accessors/formats/env-accessor.js';
+import { NdjsonAccessor } from '../accessors/formats/ndjson-accessor.js';
+import { AnyAccessor } from '../accessors/formats/any-accessor.js';
+/**
+ * Factory for creating typed format-specific accessors.
+ *
+ * Encapsulates the wiring between a parser and accessor construction,
+ * providing one method per supported format. Used internally by
+ * {@link Inline} to create accessors.
+ *
+ * @internal
+ */
+export declare class AccessorFactory {
+    private readonly parser;
+    private readonly defaultIntegration;
+    private readonly strictMode;
+    /**
+     * Initialize the factory with a parser, optional integration, and optional strict mode.
+     *
+     * @param parser - Parser for dot-notation resolution.
+     * @param defaultIntegration - Default integration for AnyAccessor.
+     * @param strictMode - Override strict mode for created accessors.
+     */
+    constructor(parser: ValidatableParserInterface, defaultIntegration?: ParseIntegrationInterface | null, strictMode?: boolean | null);
+    /**
+     * Return the underlying parser used by this factory.
+     *
+     * @returns The parser instance.
+     */
+    getParser(): ValidatableParserInterface;
+    /**
+     * Apply configured strict mode to a new accessor before hydration.
+     *
+     * @param accessor - Unhydrated accessor instance.
+     * @returns Same accessor with strict mode applied if configured.
+     */
+    private applyOptions;
+    /**
+     * Create an ArrayAccessor from raw array data.
+     *
+     * @param data - Source array or object.
+     * @returns Populated ArrayAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    array(data: Record<string, unknown> | unknown[]): ArrayAccessor;
+    /**
+     * Create an ObjectAccessor from a source object.
+     *
+     * @param data - Source object.
+     * @returns Populated ObjectAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    object(data: object): ObjectAccessor;
+    /**
+     * Create a JsonAccessor from a JSON string.
+     *
+     * @param data - Raw JSON string.
+     * @returns Populated JsonAccessor.
+     * @throws {InvalidFormatException} When the JSON is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    json(data: string): JsonAccessor;
+    /**
+     * Create an XmlAccessor from an XML string.
+     *
+     * @param data - Raw XML string.
+     * @returns Populated XmlAccessor.
+     * @throws {InvalidFormatException} When the XML is malformed.
+     * @throws {SecurityException} When DOCTYPE is detected.
+     */
+    xml(data: string): XmlAccessor;
+    /**
+     * Create a YamlAccessor from a YAML string.
+     *
+     * @param data - Raw YAML string.
+     * @returns Populated YamlAccessor.
+     * @throws {YamlParseException} When the YAML is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    yaml(data: string): YamlAccessor;
+    /**
+     * Create an IniAccessor from an INI string.
+     *
+     * @param data - Raw INI string.
+     * @returns Populated IniAccessor.
+     * @throws {InvalidFormatException} When the INI is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    ini(data: string): IniAccessor;
+    /**
+     * Create an EnvAccessor from a dotenv-formatted string.
+     *
+     * @param data - Raw dotenv string.
+     * @returns Populated EnvAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    env(data: string): EnvAccessor;
+    /**
+     * Create an NdjsonAccessor from a newline-delimited JSON string.
+     *
+     * @param data - Raw NDJSON string.
+     * @returns Populated NdjsonAccessor.
+     * @throws {InvalidFormatException} When any JSON line is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    ndjson(data: string): NdjsonAccessor;
+    /**
+     * Create an AnyAccessor with automatic format detection.
+     *
+     * @param data - Raw data in any supported format.
+     * @param integration - Override integration (falls back to default).
+     * @returns Populated AnyAccessor.
+     * @throws {InvalidFormatException} When no integration is available.
+     */
+    any(data: unknown, integration?: ParseIntegrationInterface | null): AnyAccessor;
+}