@safeaccess/inline 0.1.1

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

@@ -0,0 +1,46 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+import { YamlParser } from '../../parser/yaml-parser.js';
+/**
+ * Accessor for YAML-encoded strings.
+ *
+ * Uses the internal YamlParser for safe YAML parsing without
+ * depending on external YAML libraries. Tags, anchors, aliases, and
+ * merge keys are blocked as unsafe constructs.
+ *
+ * @example
+ * const accessor = new YamlAccessor(parser).from('key: value\nnested:\n  a: 1');
+ * accessor.get('nested.a'); // 1
+ */
+export class YamlAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a YAML string.
+     *
+     * @param data - YAML string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string or YAML is malformed.
+     * @throws {YamlParseException} When unsafe YAML constructs are present.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('name: Alice\nage: 30');
+     */
+    from(data) {
+        if (typeof data !== 'string') {
+            /* Stryker disable StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(`YamlAccessor expects a YAML string, got ${typeof data}`);
+            /* Stryker restore StringLiteral */
+        }
+        return this.ingest(data);
+    }
+    /** {@inheritDoc} */
+    parse(raw) {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- unreachable: from() always validates string before ingest() */
+        /* c8 ignore start */
+        if (typeof raw !== 'string') {
+            return {};
+        }
+        /* c8 ignore stop */
+        return new YamlParser().parse(raw);
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { ReadableAccessorsInterface } from './readable-accessors-interface.js';
+import type { WritableAccessorsInterface } from './writable-accessors-interface.js';
+import type { FactoryAccessorsInterface } from './factory-accessors-interface.js';
+/**
+ * Unified contract combining read, write, and factory capabilities.
+ *
+ * Marker interface that aggregates all accessor responsibilities into
+ * a single type, used as the base contract for AbstractAccessor.
+ */
+export interface AccessorsInterface extends ReadableAccessorsInterface, WritableAccessorsInterface, FactoryAccessorsInterface {
+}

package/dist/contracts/accessors-interface.js

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

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

@@ -0,0 +1,16 @@
+/**
+ * Contract for creating accessor instances from raw input.
+ *
+ * Note: this `from(data)` is the per-accessor hydrator, not
+ * {@link Inline.from} which selects an accessor by TypeFormat.
+ */
+export interface FactoryAccessorsInterface {
+    /**
+     * Hydrate the accessor from raw input data.
+     *
+     * @param data - Raw input in the format expected by the accessor.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the input cannot be parsed.
+     */
+    from(data: unknown): this;
+}

package/dist/contracts/factory-accessors-interface.js

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

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

@@ -0,0 +1,31 @@
+/**
+ * Contract for custom format detection and parsing integration.
+ *
+ * Enables the {@link AnyAccessor} to accept arbitrary input by delegating
+ * format validation and parsing to a user-provided implementation.
+ *
+ * @example
+ * class CsvIntegration implements ParseIntegrationInterface {
+ *   assertFormat(raw: unknown): boolean { return typeof raw === 'string' && raw.includes(','); }
+ *   parse(raw: unknown): Record<string, unknown> { ... }
+ * }
+ * const accessor = Inline.withParserIntegration(new CsvIntegration()).fromAny(csvString);
+ */
+export interface ParseIntegrationInterface {
+    /**
+     * Determine whether the given raw input is in a supported format.
+     *
+     * @param raw - Raw input data to validate.
+     * @returns `true` if the input can be parsed by this integration.
+     */
+    assertFormat(raw: unknown): boolean;
+    /**
+     * Parse raw input data into a normalized plain object.
+     *
+     * Called only after {@link assertFormat} returns `true`.
+     *
+     * @param raw - Raw input data previously validated by {@link assertFormat}.
+     * @returns Parsed data as a nested plain object.
+     */
+    parse(raw: unknown): Record<string, unknown>;
+}

package/dist/contracts/parse-integration-interface.js

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

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export interface PathCacheInterface {
+    /**
+     * Retrieve cached segments for a path string.
+     *
+     * @param path - Dot-notation path string.
+     * @returns Cached segment array, or null if not cached.
+     */
+    get(path: string): string[] | 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;
+    /**
+     * Check whether a path exists in the cache.
+     *
+     * @param path - Dot-notation path string.
+     * @returns `true` if segments are cached for this path.
+     */
+    has(path: string): boolean;
+    /**
+     * Clear all cached entries.
+     *
+     * @returns Same instance for fluent chaining.
+     */
+    clear(): this;
+}

package/dist/contracts/path-cache-interface.js

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

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

@@ -0,0 +1,79 @@
+/**
+ * Contract for read-only data access operations.
+ *
+ * Defines methods for retrieving, checking existence, counting,
+ * and inspecting keys within the accessor's internal data store.
+ */
+export interface ReadableAccessorsInterface {
+    /**
+     * Retrieve the original raw input data before parsing.
+     *
+     * @returns Original input passed to {@link FactoryAccessorsInterface.from}.
+     */
+    getRaw(): unknown;
+    /**
+     * Retrieve a value at a dot-notation path.
+     *
+     * @param path - Dot-notation path (e.g. "user.name").
+     * @param defaultValue - Fallback when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    get(path: string, defaultValue?: unknown): unknown;
+    /**
+     * Retrieve a value or throw when the path does not exist.
+     *
+     * @param path - Dot-notation path.
+     * @returns Resolved value.
+     * @throws {PathNotFoundException} When the path is missing.
+     */
+    getOrFail(path: string): unknown;
+    /**
+     * Retrieve a value using pre-parsed key segments.
+     *
+     * @param segments - Ordered list of keys.
+     * @param defaultValue - Fallback when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    getAt(segments: Array<string | number>, defaultValue?: unknown): unknown;
+    /**
+     * Check whether a dot-notation path exists.
+     *
+     * @param path - Dot-notation path.
+     * @returns True if the path resolves to a value.
+     */
+    has(path: string): boolean;
+    /**
+     * Check whether a path exists using pre-parsed key segments.
+     *
+     * @param segments - Ordered list of keys.
+     * @returns True if the path resolves to a value.
+     */
+    hasAt(segments: Array<string | number>): boolean;
+    /**
+     * Retrieve multiple values by their paths with individual defaults.
+     *
+     * @param paths - Map of path to default value.
+     * @returns Map of path to resolved value.
+     */
+    getMany(paths: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Return all parsed data as a plain object.
+     *
+     * @returns Complete internal data.
+     */
+    all(): Record<string, unknown>;
+    /**
+     * Count elements at a path, or the root if undefined.
+     *
+     * @param path - Dot-notation path, or undefined for root.
+     * @returns Number of elements.
+     */
+    count(path?: string): number;
+    /**
+     * Retrieve array keys at a path, or root keys if undefined.
+     *
+     * @param path - Dot-notation path, or undefined for root.
+     * @returns List of keys.
+     */
+    keys(path?: string): string[];
+}

package/dist/contracts/readable-accessors-interface.js

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

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

@@ -0,0 +1,40 @@
+/**
+ * Contract for validating keys against a forbidden-key security list.
+ *
+ * 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.
+ */
+export interface SecurityGuardInterface {
+    /**
+     * Check whether a key is in the forbidden list.
+     *
+     * @param key - Key name to check.
+     * @returns True if the key is forbidden.
+     */
+    isForbiddenKey(key: string): boolean;
+    /**
+     * Assert that a single key is safe, throwing on violation.
+     *
+     * @param key - Key name to validate.
+     * @throws {SecurityException} When the key is forbidden.
+     */
+    assertSafeKey(key: string): void;
+    /**
+     * Recursively assert that all keys in a data structure are safe.
+     *
+     * @param data - Data to scan for forbidden keys.
+     * @param depth - Current recursion depth (internal use).
+     * @throws {SecurityException} When a forbidden key is found or depth is exceeded.
+     */
+    assertSafeKeys(data: unknown, depth?: number): void;
+    /**
+     * Remove all forbidden keys from a data structure recursively.
+     *
+     * @param data - Data to sanitize.
+     * @param depth - Current recursion depth.
+     * @returns Sanitized data without forbidden keys.
+     * @throws {SecurityException} When recursion depth exceeds the limit.
+     */
+    sanitize(data: Record<string, unknown>, depth?: number): Record<string, unknown>;
+}

package/dist/contracts/security-guard-interface.js

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

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

@@ -0,0 +1,67 @@
+/**
+ * Contract for security validation during parsing and path resolution.
+ *
+ * Defines methods for asserting payload size, maximum key counts,
+ * and recursion depth limits to prevent resource exhaustion and
+ * injection attacks during data access operations.
+ */
+export interface SecurityParserInterface {
+    /**
+     * Assert that a raw string payload does not exceed the byte limit.
+     *
+     * @param input - Raw input string to measure.
+     * @param maxBytes - Override limit, or undefined to use configured default.
+     * @throws {SecurityException} When the payload exceeds the limit.
+     */
+    assertPayloadSize(input: string, maxBytes?: number): void;
+    /**
+     * Assert that resolve depth does not exceed the configured limit.
+     *
+     * @param depth - Current depth counter.
+     * @throws {SecurityException} When depth exceeds the maximum.
+     */
+    assertMaxResolveDepth(depth: number): void;
+    /**
+     * Assert that total key count does not exceed the limit.
+     *
+     * @param data - Data to count keys in.
+     * @param maxKeys - Override limit, or undefined to use configured default.
+     * @param maxCountDepth - Override recursion depth limit, or undefined for default.
+     * @throws {SecurityException} When key count exceeds the limit.
+     */
+    assertMaxKeys(data: Record<string, unknown>, maxKeys?: number, maxCountDepth?: number): void;
+    /**
+     * Assert that current recursion depth does not exceed the limit.
+     *
+     * @param currentDepth - Current depth counter.
+     * @param maxDepth - Override limit, or undefined to use configured default.
+     * @throws {SecurityException} When the depth exceeds the limit.
+     */
+    assertMaxDepth(currentDepth: number, maxDepth?: number): void;
+    /**
+     * Assert that structural nesting depth does not exceed the policy limit.
+     *
+     * @param data - Data to measure structural depth of.
+     * @param maxDepth - Maximum allowed structural depth.
+     * @throws {SecurityException} When structural depth exceeds the limit.
+     */
+    assertMaxStructuralDepth(data: unknown, maxDepth: number): void;
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * @returns Maximum allowed depth.
+     */
+    getMaxDepth(): number;
+    /**
+     * Return the configured maximum path-resolve recursion depth.
+     *
+     * @returns Maximum allowed resolve depth.
+     */
+    getMaxResolveDepth(): number;
+    /**
+     * Return the configured maximum total key count.
+     *
+     * @returns Maximum allowed key count.
+     */
+    getMaxKeys(): number;
+}

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

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

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

@@ -0,0 +1,65 @@
+/**
+ * Contract for immutable write operations on accessor data.
+ *
+ * All mutations return a new instance with the modification applied,
+ * preserving the original accessor instance.
+ */
+export interface WritableAccessorsInterface {
+    /**
+     * Set a value at a dot-notation path.
+     *
+     * @param path - Dot-notation path.
+     * @param value - Value to assign.
+     * @returns New accessor instance with the value set.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When the path contains forbidden keys.
+     */
+    set(path: string, value: unknown): this;
+    /**
+     * Set a value using pre-parsed key segments.
+     *
+     * @param segments - Ordered list of keys.
+     * @param value - Value to assign.
+     * @returns New accessor instance with the value set.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When segments contain forbidden keys.
+     */
+    setAt(segments: Array<string | number>, value: unknown): this;
+    /**
+     * Remove a value at a dot-notation path.
+     *
+     * @param path - Dot-notation path to remove.
+     * @returns New accessor instance without the specified path.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When the path contains forbidden keys.
+     */
+    remove(path: string): this;
+    /**
+     * Remove a value using pre-parsed key segments.
+     *
+     * @param segments - Ordered list of keys.
+     * @returns New accessor instance without the specified path.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When segments contain forbidden keys.
+     */
+    removeAt(segments: Array<string | number>): this;
+    /**
+     * Deep-merge an object into the value at a dot-notation path.
+     *
+     * @param path - Dot-notation path to the merge target.
+     * @param value - Object to merge into the existing value.
+     * @returns New accessor instance with merged data.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When the path or values contain forbidden keys.
+     */
+    merge(path: string, value: Record<string, unknown>): this;
+    /**
+     * Deep-merge an object into the root data.
+     *
+     * @param value - Object to merge into the root.
+     * @returns New accessor instance with merged data.
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     * @throws {SecurityException} When values contain forbidden keys.
+     */
+    mergeAll(value: Record<string, unknown>): this;
+}

package/dist/contracts/writable-accessors-interface.js

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

package/dist/core/dot-notation-parser.d.ts

@@ -0,0 +1,204 @@
+import type { SecurityGuardInterface } from '../contracts/security-guard-interface.js';
+import type { SecurityParserInterface } from '../contracts/security-parser-interface.js';
+import type { PathCacheInterface } from '../contracts/path-cache-interface.js';
+/**
+ * Core dot-notation parser for reading, writing, and removing nested values.
+ *
+ * Provides path-based access to plain objects using dot-separated keys.
+ * Delegates security validation to SecurityGuard and SecurityParser.
+ *
+ * @example
+ * const parser = new DotNotationParser();
+ * parser.get({ user: { name: 'Alice' } }, 'user.name'); // 'Alice'
+ */
+export declare class DotNotationParser {
+    private readonly securityGuard;
+    private readonly securityParser;
+    private readonly pathCache;
+    /**
+     * @param securityGuard - Key-safety guard. Defaults to a new SecurityGuard instance.
+     * @param securityParser - Parser depth and size limits. Defaults to a new SecurityParser instance.
+     * @param pathCache - Optional path segment cache for repeated lookups.
+     */
+    constructor(securityGuard?: SecurityGuardInterface, securityParser?: SecurityParserInterface, pathCache?: PathCacheInterface);
+    /**
+     * Resolve a dot-notation path against data, returning the matched value.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string (e.g. "user.name").
+     * @param defaultValue - Fallback returned when the path does not exist.
+     * @returns Resolved value or the default.
+     *
+     * @example
+     * parser.get({ a: { b: 1 } }, 'a.b'); // 1
+     * parser.get({ a: 1 }, 'a.b', 'default'); // 'default'
+     */
+    get(data: Record<string, unknown>, path: string, defaultValue?: unknown): unknown;
+    /**
+     * Set a value at a dot-notation path, returning a new object.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string.
+     * @param value - Value to assign.
+     * @returns New object with the value set at the path.
+     *
+     * @example
+     * parser.set({}, 'user.name', 'Alice'); // { user: { name: 'Alice' } }
+     */
+    set(data: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+    /**
+     * Check whether a dot-notation path exists in the data.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string.
+     * @returns True if the path resolves to a value.
+     *
+     * @example
+     * parser.has({ a: { b: 1 } }, 'a.b'); // true
+     * parser.has({ a: 1 }, 'a.b'); // false
+     */
+    has(data: Record<string, unknown>, path: string): boolean;
+    /**
+     * Remove a value at a dot-notation path, returning a new object.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string.
+     * @returns New object with the path removed.
+     *
+     * @example
+     * parser.remove({ a: { b: 1 } }, 'a.b'); // { a: {} }
+     */
+    remove(data: Record<string, unknown>, path: string): Record<string, unknown>;
+    /**
+     * Resolve a pre-parsed segment array against data.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys.
+     * @param defaultValue - Fallback returned when the path does not exist.
+     * @returns Resolved value or the default.
+     *
+     * @example
+     * parser.getAt({ a: { b: 1 } }, ['a', 'b']); // 1
+     */
+    getAt(data: Record<string, unknown>, segments: Array<string | number>, defaultValue?: unknown): unknown;
+    /**
+     * Set a value using pre-parsed key segments, returning a new object.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys.
+     * @param value - Value to assign.
+     * @returns New object with the value set.
+     *
+     * @example
+     * parser.setAt({}, ['user', 'name'], 'Alice'); // { user: { name: 'Alice' } }
+     */
+    setAt(data: Record<string, unknown>, segments: Array<string | number>, value: unknown): Record<string, unknown>;
+    /**
+     * Check whether a path exists using pre-parsed key segments.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys.
+     * @returns True if the path resolves to a value.
+     *
+     * @example
+     * parser.hasAt({ a: { b: 1 } }, ['a', 'b']); // true
+     */
+    hasAt(data: Record<string, unknown>, segments: Array<string | number>): boolean;
+    /**
+     * Remove a value using pre-parsed key segments, returning a new object.
+     *
+     * @param data - Source data object.
+     * @param segments - Ordered list of keys.
+     * @returns New object without the specified path.
+     *
+     * @example
+     * parser.removeAt({ a: { b: 1 } }, ['a', 'b']); // { a: {} }
+     */
+    removeAt(data: Record<string, unknown>, segments: Array<string | number>): Record<string, unknown>;
+    /**
+     * Deep-merge an object into the value at a dot-notation path.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path to the merge target, or empty string for root merge.
+     * @param value - Object to merge into the existing value.
+     * @returns New object with merged data.
+     *
+     * @example
+     * parser.merge({ a: { b: 1 } }, 'a', { c: 2 }); // { a: { b: 1, c: 2 } }
+     */
+    merge(data: Record<string, unknown>, path: string, value: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Run all security validations on a parsed data structure.
+     *
+     * @param data - Data to validate.
+     * @throws {SecurityException} When a security violation is detected.
+     *
+     * @example
+     * parser.validate({ name: 'Alice' }); // OK
+     * parser.validate({ __construct: 'bad' }); // throws SecurityException
+     */
+    validate(data: Record<string, unknown>): void;
+    /**
+     * Assert that a string payload does not exceed the configured byte limit.
+     *
+     * @param input - Raw input string to measure.
+     * @throws {SecurityException} When the payload exceeds the limit.
+     *
+     * @example
+     * parser.assertPayload('small text'); // OK
+     */
+    assertPayload(input: string): void;
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * @returns Maximum allowed depth from the security parser.
+     */
+    getMaxDepth(): number;
+    /**
+     * Return the configured maximum total key count.
+     *
+     * @returns Maximum allowed key count from the security parser.
+     */
+    getMaxKeys(): number;
+    /**
+     * Parse a dot-notation path into segments, using cache when available.
+     *
+     * @param path - Dot-notation path string.
+     * @returns Array of path segments.
+     */
+    private parsePath;
+    /**
+     * Recursively write a value at the given key path.
+     *
+     * @param data - Current level data.
+     * @param segments - Flat key segments.
+     * @param index - Current depth index.
+     * @param value - Value to write.
+     * @returns Modified copy of the data.
+     *
+     * @throws {SecurityException} When a key violates security rules.
+     */
+    private writeAt;
+    /**
+     * Recursively remove a key at the given key path.
+     *
+     * @param data - Current level data.
+     * @param segments - Flat key segments.
+     * @param index - Current depth index.
+     * @returns Modified copy of the data.
+     *
+     * @throws {SecurityException} When a key violates security rules.
+     */
+    private eraseAt;
+    /**
+     * Recursively merge source into target, preserving nested structures.
+     *
+     * @param target - Base data.
+     * @param source - Data to merge on top.
+     * @param depth - Current recursion depth.
+     * @returns Merged result.
+     *
+     * @throws {SecurityException} When max resolve depth is exceeded.
+     */
+    private deepMerge;
+}