@safeaccess/inline 0.1.1 → 0.1.3

package/package.json

@@ -1,8 +1,8 @@
 {
     "name": "@safeaccess/inline",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "private": false,
-    "description": "Safe nested data access with dot notation — JavaScript/TypeScript",
+    "description": "Safe nested data access with dot notation - JavaScript/TypeScript",
     "license": "MIT",
     "type": "module",
     "main": "./dist/index.js",
@@ -13,6 +13,15 @@
             "types": "./dist/index.d.ts"
         }
     },
+    "keywords": [
+        "safeaccess",
+        "dot-notation",
+        "nested-data",
+        "data-access",
+        "array-access",
+        "object-access",
+        "null-safe"
+    ],
     "scripts": {
         "build": "tsc",
         "test": "vitest run",
@@ -20,7 +29,6 @@
         "test:typecheck": "tsc --noEmit",
         "test:parity": "vitest run --reporter=verbose",
         "lint": "npx eslint src/ tests/",
-        "bench": "npx vitest bench benchmarks/",
         "test:coverage": "npx vitest run --coverage",
         "test:mutation": "npx stryker run"
     },

package/src/accessors/abstract-accessor.ts

@@ -1,8 +1,16 @@
 import type { AccessorsInterface } from '../contracts/accessors-interface.js';
-import { DotNotationParser } from '../core/dot-notation-parser.js';
+import type { ValidatableParserInterface } from '../contracts/validatable-parser-interface.js';
 import { PathNotFoundException } from '../exceptions/path-not-found-exception.js';
 import { ReadonlyViolationException } from '../exceptions/readonly-violation-exception.js';
 
+/** @internal Mutable state grouped to allow O(1) shallow clone in mutations. */
+interface AccessorState {
+    data: Record<string, unknown>;
+    isReadonly: boolean;
+    isStrict: boolean;
+    rawInput: unknown;
+}
+
 /**
  * Base accessor providing read, write, and lifecycle operations.
  *
@@ -12,14 +20,9 @@ import { ReadonlyViolationException } from '../exceptions/readonly-violation-exc
  *
  * Subclasses must implement `parse()` to convert raw input into
  * a normalized plain object.
+ *
+ * @api
  */
-interface AccessorState {
-    data: Record<string, unknown>;
-    isReadonly: boolean;
-    isStrict: boolean;
-    rawInput: unknown;
-}
-
 export abstract class AbstractAccessor implements AccessorsInterface {
     /** @internal Mutable state grouped to allow O(1) shallow clone in mutations. */
     private _state: AccessorState = {
@@ -32,7 +35,7 @@ export abstract class AbstractAccessor implements AccessorsInterface {
     /**
      * @param parser - Dot-notation parser for path operations.
      */
-    constructor(protected readonly parser: DotNotationParser) {}
+    constructor(protected readonly parser: ValidatableParserInterface) {}
 
     /**
      * Convert raw input data into a normalized plain object.
@@ -72,6 +75,8 @@ export abstract class AbstractAccessor implements AccessorsInterface {
      *
      * @param data - Raw input in the format expected by the accessor.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the raw input cannot be parsed.
+     * @throws {SecurityException} When payload exceeds size limit, data contains forbidden keys, or violates structural limits.
      */
     abstract from(data: unknown): this;
 
@@ -107,7 +112,7 @@ export abstract class AbstractAccessor implements AccessorsInterface {
      * Only use with fully trusted, application-controlled input.
      *
      * @example
-     * // Trust the input — skip all security checks
+     * // Trust the input - skip all security checks
      * const accessor = new JsonAccessor(parser).strict(false).from(trustedPayload);
      */
     strict(strict: boolean = true): this {
@@ -179,7 +184,8 @@ export abstract class AbstractAccessor implements AccessorsInterface {
      * @returns True if the path resolves to a value.
      */
     hasAt(segments: Array<string | number>): boolean {
-        return this.parser.hasAt(this._state.data, segments);
+        const sentinel = Object.create(null) as Record<string, never>;
+        return this.parser.getAt(this._state.data, segments, sentinel) !== sentinel;
     }
 
     /**
@@ -260,13 +266,13 @@ export abstract class AbstractAccessor implements AccessorsInterface {
     }
 
     /**
-     * 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 {
-        const target = path !== undefined ? this.get(path, {}) : this._state.data;
+    count(path?: string | null): number {
+        const target = path != null ? this.get(path, {}) : this._state.data;
         if (typeof target === 'object' && target !== null) {
             return Object.keys(target).length;
         }
@@ -274,13 +280,13 @@ export abstract class AbstractAccessor implements AccessorsInterface {
     }
 
     /**
-     * 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[] {
-        const target = path !== undefined ? this.get(path, {}) : this._state.data;
+    keys(path?: string | null): string[] {
+        const target = path != null ? this.get(path, {}) : this._state.data;
         /* Stryker disable next-line ConditionalExpression -- equivalent: get() always returns an object-type value here; typeof check is a type guard only */
         if (typeof target === 'object' && target !== null) {
             return Object.keys(target);

package/src/accessors/abstract-integration-accessor.ts

@@ -0,0 +1,27 @@
+import { AbstractAccessor } from './abstract-accessor.js';
+import type { ParseIntegrationInterface } from '../contracts/parse-integration-interface.js';
+import type { ValidatableParserInterface } from '../contracts/validatable-parser-interface.js';
+
+/**
+ * Base accessor with custom format integration support.
+ *
+ * Extends {@link AbstractAccessor} to inject a {@link ParseIntegrationInterface}
+ * for user-defined format detection and parsing. Used exclusively by
+ * {@link AnyAccessor} to handle arbitrary input formats.
+ *
+ * @internal
+ */
+export abstract class AbstractIntegrationAccessor extends AbstractAccessor {
+    /**
+     * Create an accessor with parser and custom integration dependencies.
+     *
+     * @param parser - Dot-notation parser.
+     * @param integration - Custom format parser.
+     */
+    constructor(
+        parser: ValidatableParserInterface,
+        protected readonly integration: ParseIntegrationInterface,
+    ) {
+        super(parser);
+    }
+}

package/src/accessors/formats/any-accessor.ts

@@ -1,6 +1,6 @@
-import { AbstractAccessor } from '../abstract-accessor.js';
+import { AbstractIntegrationAccessor } from '../abstract-integration-accessor.js';
 import type { ParseIntegrationInterface } from '../../contracts/parse-integration-interface.js';
-import type { DotNotationParser } from '../../core/dot-notation-parser.js';
+import type { ValidatableParserInterface } from '../../contracts/validatable-parser-interface.js';
 import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
 
 /**
@@ -9,21 +9,20 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  * Delegates format detection and parsing to a user-provided integration.
  * Validates string payloads against security constraints before parsing.
  *
+ * @api
+ *
  * @example
  * const integration = new MyCsvIntegration();
  * const accessor = Inline.withParserIntegration(integration).fromAny(csvString);
  * accessor.get('0.name'); // first row, name column
  */
-export class AnyAccessor extends AbstractAccessor {
-    private readonly integration: ParseIntegrationInterface;
-
+export class AnyAccessor extends AbstractIntegrationAccessor {
     /**
      * @param parser      - Dot-notation parser with security configuration.
      * @param integration - Custom format parser for detecting and parsing input.
      */
-    constructor(parser: DotNotationParser, integration: ParseIntegrationInterface) {
-        super(parser);
-        this.integration = integration;
+    constructor(parser: ValidatableParserInterface, integration: ParseIntegrationInterface) {
+        super(parser, integration);
     }
 
     /**
@@ -33,6 +32,9 @@ export class AnyAccessor extends AbstractAccessor {
      * @returns Populated accessor instance.
      * @throws {InvalidFormatException} When the integration rejects the format.
      * @throws {SecurityException} When string input violates payload-size limits.
+     *
+     * @example
+     * const accessor = new AnyAccessor(parser, integration).from(rawData);
      */
     from(data: unknown): this {
         if (!this.integration.assertFormat(data)) {
@@ -42,9 +44,7 @@ export class AnyAccessor extends AbstractAccessor {
         return this.ingest(data);
     }
 
-    /**
-     * @internal
-     */
+    /** {@inheritDoc} */
     protected parse(raw: unknown): Record<string, unknown> {
         return this.integration.parse(raw);
     }

package/src/accessors/formats/array-accessor.ts

@@ -6,6 +6,8 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  *
  * Accepts a plain object or array directly. No string parsing is involved.
  *
+ * @api
+ *
  * @example
  * const accessor = new ArrayAccessor(parser).from({ key: 'value' });
  * accessor.get('key'); // 'value'

package/src/accessors/formats/env-accessor.ts

@@ -7,6 +7,8 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  * Parses KEY=VALUE lines, skipping comments (#) and blank lines.
  * Strips surrounding single and double quotes from values.
  *
+ * @api
+ *
  * @example
  * const accessor = new EnvAccessor(parser).from('DB_HOST=localhost\nDEBUG=true');
  * accessor.get('DB_HOST'); // 'localhost'

package/src/accessors/formats/ini-accessor.ts

@@ -7,6 +7,8 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  * Parses sections (e.g. `[section]`) as nested keys.
  * Type inference: numeric strings become numbers, `true`/`false` become booleans.
  *
+ * @api
+ *
  * @example
  * const accessor = new IniAccessor(parser).from('[db]\nhost=localhost\nport=5432');
  * accessor.get('db.host'); // 'localhost'

package/src/accessors/formats/json-accessor.ts

@@ -6,6 +6,8 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  *
  * Decodes JSON via `JSON.parse()`. Validates payload size before parsing.
  *
+ * @api
+ *
  * @example
  * const accessor = new JsonAccessor(parser).from('{"key":"value"}');
  * accessor.get('key'); // 'value'

package/src/accessors/formats/ndjson-accessor.ts

@@ -7,6 +7,8 @@ import { InvalidFormatException } from '../../exceptions/invalid-format-exceptio
  * Parses each non-empty line as a standalone JSON object,
  * producing an indexed record of parsed entries.
  *
+ * @api
+ *
  * @example
  * const ndjson = '{"id":1}\n{"id":2}';
  * const accessor = new NdjsonAccessor(parser).from(ndjson);

package/src/accessors/formats/object-accessor.ts

@@ -8,6 +8,8 @@ import { SecurityException } from '../../exceptions/security-exception.js';
  * Handles nested objects and arrays of objects without JSON roundtrip.
  * Respects the configured max depth to prevent DoS from deeply nested structures.
  *
+ * @api
+ *
  * @example
  * const obj = { user: { name: 'Alice' } };
  * const accessor = new ObjectAccessor(parser).from(obj);

package/src/accessors/formats/xml-accessor.ts

@@ -9,6 +9,8 @@ import { XmlParser } from '../../parser/xml-parser.js';
  * Parses XML using the DOM parser available in the current environment.
  * Blocks DOCTYPE declarations to prevent XXE attacks.
  *
+ * @api
+ *
  * @example
  * const accessor = new XmlAccessor(parser).from('<root><key>value</key></root>');
  * accessor.get('key'); // 'value'

package/src/accessors/formats/yaml-accessor.ts

@@ -9,6 +9,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
@@ -24,7 +26,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: unknown): this {
         if (typeof data !== 'string') {
@@ -47,6 +49,6 @@ export class YamlAccessor extends AbstractAccessor {
         }
         /* c8 ignore stop */
 
-        return new YamlParser().parse(raw);
+        return new YamlParser(this.parser.getMaxDepth()).parse(raw);
     }
 }

package/src/cache/simple-path-cache.ts

@@ -0,0 +1,77 @@
+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 class SimplePathCache implements PathCacheInterface {
+    private readonly cache: Map<string, Segment[]> = new Map();
+
+    /**
+     * Create a cache with the given maximum capacity.
+     *
+     * @param maxSize - Maximum number of cached path entries.
+     */
+    constructor(private readonly maxSize: number = 1000) {}
+
+    /**
+     * 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 {
+        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: string, segments: Segment[]): void {
+        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: string): boolean {
+        return this.cache.has(path);
+    }
+
+    /**
+     * Clear all cached entries.
+     *
+     * @returns Same instance for fluent chaining.
+     */
+    clear(): this {
+        this.cache.clear();
+        return this;
+    }
+}

package/src/contracts/accessors-interface.ts

@@ -7,6 +7,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/src/contracts/factory-accessors-interface.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/src/contracts/filter-evaluator-interface.ts

@@ -0,0 +1,30 @@
+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/src/contracts/parse-integration-interface.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/src/contracts/parser-interface.ts

@@ -0,0 +1,114 @@
+/**
+ * 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/src/contracts/path-cache-interface.ts

@@ -1,13 +1,15 @@
+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,7 +18,7 @@ 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.
@@ -24,7 +26,7 @@ export interface PathCacheInterface {
      * @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/src/contracts/readable-accessors-interface.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 {
     /**
@@ -71,18 +76,18 @@ 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/src/contracts/security-guard-interface.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/src/contracts/security-parser-interface.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 {
     /**