@safeaccess/inline 0.1.1

package/dist/security/security-parser.js

@@ -0,0 +1,192 @@
+import { SecurityException } from '../exceptions/security-exception.js';
+/**
+ * Enforce structural security constraints on parsed data.
+ *
+ * Validates payload size, maximum key count, recursion depth, and
+ * structural depth limits.
+ *
+ * @example
+ * const parser = new SecurityParser({ maxDepth: 10, maxKeys: 100 });
+ * parser.assertPayloadSize('{"key":"value"}');
+ */
+export class SecurityParser {
+    maxDepth;
+    maxPayloadBytes;
+    maxKeys;
+    maxCountRecursiveDepth;
+    maxResolveDepth;
+    /**
+     * Build security options from configuration values.
+     *
+     * @param options - Configuration overrides.
+     * @param options.maxDepth - Maximum allowed structural nesting depth. Default: 512.
+     * @param options.maxPayloadBytes - Maximum allowed raw payload size in bytes. Default: 10 MB.
+     * @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.
+     * @param options.maxCountRecursiveDepth - Maximum recursion depth when counting keys. Default: 100.
+     * @param options.maxResolveDepth - Maximum recursion depth for path resolution. Default: 100.
+     */
+    constructor(options = {}) {
+        this.maxDepth = SecurityParser.clampOption(options.maxDepth, 512);
+        this.maxPayloadBytes = SecurityParser.clampOption(options.maxPayloadBytes, 10 * 1024 * 1024);
+        this.maxKeys = SecurityParser.clampOption(options.maxKeys, 10_000);
+        this.maxCountRecursiveDepth = SecurityParser.clampOption(options.maxCountRecursiveDepth, 100);
+        this.maxResolveDepth = SecurityParser.clampOption(options.maxResolveDepth, 100);
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * parser.assertPayloadSize('small input'); // OK
+     */
+    assertPayloadSize(input, maxBytes) {
+        const limit = maxBytes ?? this.maxPayloadBytes;
+        const size = new TextEncoder().encode(input).length;
+        if (size > limit) {
+            throw new SecurityException(`Payload size ${size} bytes exceeds maximum of ${limit} bytes.`);
+        }
+    }
+    /**
+     * Assert that resolve depth does not exceed the configured limit.
+     *
+     * @param depth - Current depth counter.
+     * @throws {SecurityException} When depth exceeds the maximum.
+     *
+     * @example
+     * parser.assertMaxResolveDepth(5); // OK
+     */
+    assertMaxResolveDepth(depth) {
+        if (depth > this.maxResolveDepth) {
+            throw new SecurityException(`Deep merge exceeded maximum depth of ${this.maxResolveDepth}`);
+        }
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * parser.assertMaxKeys({ a: 1, b: 2 }); // OK
+     */
+    assertMaxKeys(data, maxKeys, maxCountDepth) {
+        const limit = maxKeys ?? this.maxKeys;
+        const count = this.countKeys(data, 0, maxCountDepth ?? this.maxCountRecursiveDepth);
+        if (count > limit) {
+            throw new SecurityException(`Data contains ${count} keys, exceeding maximum of ${limit}.`);
+        }
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * parser.assertMaxDepth(3); // OK
+     */
+    assertMaxDepth(currentDepth, maxDepth) {
+        const limit = maxDepth ?? this.maxDepth;
+        if (currentDepth > limit) {
+            throw new SecurityException(`Recursion depth ${currentDepth} exceeds maximum of ${limit}.`);
+        }
+    }
+    /**
+     * 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.
+     *
+     * @example
+     * parser.assertMaxStructuralDepth({ a: { b: 1 } }, 10); // OK
+     */
+    assertMaxStructuralDepth(data, maxDepth) {
+        const depth = this.measureDepth(data, 0, maxDepth + 1);
+        if (depth > maxDepth) {
+            throw new SecurityException(`Data structural depth ${depth} exceeds policy maximum of ${maxDepth}.`);
+        }
+    }
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * @returns Maximum allowed depth.
+     */
+    getMaxDepth() {
+        return this.maxDepth;
+    }
+    /**
+     * Return the configured maximum path-resolve recursion depth.
+     *
+     * @returns Maximum allowed resolve depth.
+     */
+    getMaxResolveDepth() {
+        return this.maxResolveDepth;
+    }
+    /**
+     * Return the configured maximum total key count.
+     *
+     * @returns Maximum allowed key count.
+     */
+    getMaxKeys() {
+        return this.maxKeys;
+    }
+    /**
+     * Recursively count keys in a data structure.
+     *
+     * @param obj - Data to count keys in.
+     * @param depth - Current recursion depth.
+     * @param maxDepth - Maximum recursion depth for counting.
+     * @returns Total number of keys found.
+     */
+    countKeys(obj, depth, maxDepth) {
+        if (depth > maxDepth) {
+            return 0;
+        }
+        if (typeof obj !== 'object' || obj === null) {
+            return 0;
+        }
+        const entries = Object.entries(obj);
+        let count = entries.length;
+        for (const [, value] of entries) {
+            count += this.countKeys(value, depth + 1, maxDepth);
+        }
+        return count;
+    }
+    /**
+     * Recursively measure the maximum nesting depth of a data structure.
+     *
+     * @param value - Data to measure.
+     * @param current - Current depth counter.
+     * @param maxDepth - Ceiling to stop measuring.
+     * @returns Maximum depth found.
+     */
+    measureDepth(value, current, maxDepth) {
+        /* Stryker disable next-line ConditionalExpression,EqualityOperator -- equivalent: >= vs > at ceiling; both correctly stop at maxDepth */
+        if (current >= maxDepth || typeof value !== 'object' || value === null) {
+            return current;
+        }
+        let max = current;
+        for (const child of Object.values(value)) {
+            const d = this.measureDepth(child, current + 1, maxDepth);
+            /* Stryker disable next-line ConditionalExpression,EqualityOperator -- equivalent: d > max vs d >= max; assigning d when d===max is a no-op */
+            if (d > max) {
+                max = d;
+            }
+        }
+        return max;
+    }
+    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

@@ -0,0 +1,28 @@
+/**
+ * Enumeration of supported data format types.
+ *
+ * Used by {@link Inline.from} to select the appropriate accessor.
+ *
+ * @example
+ * const accessor = Inline.from(TypeFormat.Json, '{"key":"value"}');
+ */
+export declare enum TypeFormat {
+    /** Plain array or object data. */
+    Array = "array",
+    /** JavaScript object (class instance or plain). */
+    Object = "object",
+    /** JSON string. */
+    Json = "json",
+    /** XML string. */
+    Xml = "xml",
+    /** YAML string. */
+    Yaml = "yaml",
+    /** INI configuration string. */
+    Ini = "ini",
+    /** Dotenv-formatted string. */
+    Env = "env",
+    /** Newline-delimited JSON string. */
+    Ndjson = "ndjson",
+    /** Auto-detected format via integration. */
+    Any = "any"
+}

package/dist/type-format.js

@@ -0,0 +1,29 @@
+/**
+ * Enumeration of supported data format types.
+ *
+ * Used by {@link Inline.from} to select the appropriate accessor.
+ *
+ * @example
+ * const accessor = Inline.from(TypeFormat.Json, '{"key":"value"}');
+ */
+export var TypeFormat;
+(function (TypeFormat) {
+    /** Plain array or object data. */
+    TypeFormat["Array"] = "array";
+    /** JavaScript object (class instance or plain). */
+    TypeFormat["Object"] = "object";
+    /** JSON string. */
+    TypeFormat["Json"] = "json";
+    /** XML string. */
+    TypeFormat["Xml"] = "xml";
+    /** YAML string. */
+    TypeFormat["Yaml"] = "yaml";
+    /** INI configuration string. */
+    TypeFormat["Ini"] = "ini";
+    /** Dotenv-formatted string. */
+    TypeFormat["Env"] = "env";
+    /** Newline-delimited JSON string. */
+    TypeFormat["Ndjson"] = "ndjson";
+    /** Auto-detected format via integration. */
+    TypeFormat["Any"] = "any";
+})(TypeFormat || (TypeFormat = {}));

package/eslint.config.js

@@ -0,0 +1 @@
+export { default } from '../../eslint.config.js';

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@safeaccess/inline",
+    "version": "0.1.1",
+    "private": false,
+    "description": "Safe nested data access with dot notation — JavaScript/TypeScript",
+    "license": "MIT",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "typecheck": "tsc --noEmit",
+        "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"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/felipesauer/safeaccess-inline",
+        "directory": "packages/js"
+    },
+    "devDependencies": {
+        "@stryker-mutator/core": "^9.6.0",
+        "@stryker-mutator/vitest-runner": "^9.6.0",
+        "@vitest/coverage-v8": "^4.1.2",
+        "typescript": "^6.0.2",
+        "vitest": "^4.1.2"
+    }
+}

package/src/accessors/abstract-accessor.ts

@@ -0,0 +1,353 @@
+import type { AccessorsInterface } from '../contracts/accessors-interface.js';
+import { DotNotationParser } from '../core/dot-notation-parser.js';
+import { PathNotFoundException } from '../exceptions/path-not-found-exception.js';
+import { ReadonlyViolationException } from '../exceptions/readonly-violation-exception.js';
+
+/**
+ * Base accessor providing read, write, and lifecycle operations.
+ *
+ * Implements all AccessorsInterface methods with immutable copy
+ * semantics for writes, optional readonly enforcement, and strict mode
+ * for security validation on data ingestion.
+ *
+ * Subclasses must implement `parse()` to convert raw input into
+ * a normalized plain object.
+ */
+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 = {
+        data: {},
+        isReadonly: false,
+        isStrict: true,
+        rawInput: null,
+    };
+
+    /**
+     * @param parser - Dot-notation parser for path operations.
+     */
+    constructor(protected readonly parser: DotNotationParser) {}
+
+    /**
+     * Convert raw input data into a normalized plain object.
+     *
+     * @param raw - Raw input in the format expected by the accessor.
+     * @returns Parsed data structure.
+     * @throws {InvalidFormatException} When the input is malformed.
+     */
+    protected abstract parse(raw: unknown): Record<string, unknown>;
+
+    /**
+     * Ingest raw data, optionally validating via strict mode.
+     *
+     * When strict mode is enabled (default), validates payload size for string
+     * inputs and runs structural/key-safety validation on parsed data.
+     *
+     * @param raw - Raw input data.
+     * @returns Same instance with data populated.
+     * @throws {InvalidFormatException} When the raw data cannot be parsed.
+     * @throws {SecurityException} When payload exceeds size limit, data contains forbidden keys, or violates limits.
+     */
+    protected ingest(raw: unknown): this {
+        this._state.rawInput = raw;
+        if (this._state.isStrict && typeof raw === 'string') {
+            this.parser.assertPayload(raw);
+        }
+        const parsed = this.parse(raw);
+        if (this._state.isStrict) {
+            this.parser.validate(parsed);
+        }
+        this._state.data = parsed;
+        return this;
+    }
+
+    /**
+     * Hydrate the accessor from raw input data.
+     *
+     * @param data - Raw input in the format expected by the accessor.
+     * @returns Populated accessor instance.
+     */
+    abstract from(data: unknown): this;
+
+    /**
+     * Retrieve the original raw input data before parsing.
+     *
+     * @returns Original input passed to `from()`.
+     */
+    getRaw(): unknown {
+        return this._state.rawInput;
+    }
+
+    /**
+     * Return a new instance with the given readonly state.
+     *
+     * @param isReadonly - Whether the new instance should block mutations.
+     * @returns New accessor instance with the readonly state applied.
+     */
+    readonly(isReadonly: boolean = true): this {
+        const copy = this.cloneInstance();
+        copy._state = { ...copy._state, isReadonly };
+        return copy;
+    }
+
+    /**
+     * Return a new instance with the given strict mode state.
+     *
+     * @param strict - Whether to enable strict security validation.
+     * @returns New accessor instance with the strict mode applied.
+     *
+     * @security Passing `false` disables all SecurityGuard and SecurityParser
+     * validation (key safety, payload size, depth and key-count limits).
+     * Only use with fully trusted, application-controlled input.
+     *
+     * @example
+     * // Trust the input — skip all security checks
+     * const accessor = new JsonAccessor(parser).strict(false).from(trustedPayload);
+     */
+    strict(strict: boolean = true): this {
+        const copy = this.cloneInstance();
+        copy._state = { ...copy._state, isStrict: strict };
+        return copy;
+    }
+
+    /**
+     * 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.
+     *
+     * @example
+     * accessor.get('user.name', 'unknown');
+     */
+    get(path: string, defaultValue: unknown = null): unknown {
+        return this.parser.get(this._state.data, path, defaultValue);
+    }
+
+    /**
+     * 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.
+     *
+     * @example
+     * accessor.getOrFail('user.name'); // throws if not found
+     */
+    getOrFail(path: string): unknown {
+        const sentinel = Object.create(null) as Record<string, never>;
+        const result = this.parser.get(this._state.data, path, sentinel);
+
+        if (result === sentinel) {
+            throw new PathNotFoundException(`Path '${path}' not found.`);
+        }
+
+        return result;
+    }
+
+    /**
+     * 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 = null): unknown {
+        return this.parser.getAt(this._state.data, segments, defaultValue);
+    }
+
+    /**
+     * 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 {
+        return this.parser.has(this._state.data, path);
+    }
+
+    /**
+     * 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 {
+        return this.parser.hasAt(this._state.data, segments);
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.set(this._state.data, path, value));
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.setAt(this._state.data, segments, value));
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.remove(this._state.data, path));
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.removeAt(this._state.data, segments));
+    }
+
+    /**
+     * 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> {
+        const results: Record<string, unknown> = {};
+        for (const [path, defaultValue] of Object.entries(paths)) {
+            results[path] = this.get(path, defaultValue);
+        }
+        return results;
+    }
+
+    /**
+     * Return all parsed data as a plain object.
+     *
+     * @returns Complete internal data.
+     */
+    all(): Record<string, unknown> {
+        return this._state.data;
+    }
+
+    /**
+     * 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 {
+        const target = path !== undefined ? this.get(path, {}) : this._state.data;
+        if (typeof target === 'object' && target !== null) {
+            return Object.keys(target).length;
+        }
+        return 0;
+    }
+
+    /**
+     * 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[] {
+        const target = path !== undefined ? 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);
+        }
+        return [];
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.merge(this._state.data, path, value));
+    }
+
+    /**
+     * 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 {
+        this.assertNotReadOnly();
+        return this.mutateTo(this.parser.merge(this._state.data, '', value));
+    }
+
+    /**
+     * Assert that the accessor is not in readonly mode.
+     *
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     */
+    private assertNotReadOnly(): void {
+        if (this._state.isReadonly) {
+            throw new ReadonlyViolationException();
+        }
+    }
+
+    /**
+     * Create a shallow clone of this accessor.
+     *
+     * @returns Cloned accessor instance.
+     */
+    private cloneInstance(): this {
+        const copy = Object.create(Object.getPrototypeOf(this) as object) as this;
+        Object.assign(copy, this);
+        // Shallow-clone state so mutations on copy don't affect original
+        copy._state = { ...this._state };
+        return copy;
+    }
+
+    /**
+     * Create a clone with new internal data.
+     *
+     * @param newData - New data for the clone.
+     * @returns Cloned accessor with updated data.
+     */
+    private mutateTo(newData: Record<string, unknown>): this {
+        const copy = this.cloneInstance();
+        copy._state = { ...copy._state, data: newData };
+        return copy;
+    }
+}

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

@@ -0,0 +1,51 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import type { ParseIntegrationInterface } from '../../contracts/parse-integration-interface.js';
+import type { DotNotationParser } from '../../core/dot-notation-parser.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+
+/**
+ * Accessor for arbitrary formats via a custom {@link ParseIntegrationInterface}.
+ *
+ * Delegates format detection and parsing to a user-provided integration.
+ * Validates string payloads against security constraints before parsing.
+ *
+ * @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;
+
+    /**
+     * @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;
+    }
+
+    /**
+     * Hydrate from raw data via the custom integration.
+     *
+     * @param data - Raw input data in any format supported by the integration.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the integration rejects the format.
+     * @throws {SecurityException} When string input violates payload-size limits.
+     */
+    from(data: unknown): this {
+        if (!this.integration.assertFormat(data)) {
+            throw new InvalidFormatException(`AnyAccessor failed, got ${typeof data}`);
+        }
+
+        return this.ingest(data);
+    }
+
+    /**
+     * @internal
+     */
+    protected parse(raw: unknown): Record<string, unknown> {
+        return this.integration.parse(raw);
+    }
+}