@safeaccess/inline 0.1.1

package/dist/accessors/abstract-accessor.d.ts

@@ -0,0 +1,213 @@
+import type { AccessorsInterface } from '../contracts/accessors-interface.js';
+import { DotNotationParser } from '../core/dot-notation-parser.js';
+export declare abstract class AbstractAccessor implements AccessorsInterface {
+    protected readonly parser: DotNotationParser;
+    /** @internal Mutable state grouped to allow O(1) shallow clone in mutations. */
+    private _state;
+    /**
+     * @param parser - Dot-notation parser for path operations.
+     */
+    constructor(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;
+    /**
+     * 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 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): this;
+    /**
+     * 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): this;
+    /**
+     * 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): 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.
+     *
+     * @example
+     * accessor.getOrFail('user.name'); // throws if not found
+     */
+    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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * Assert that the accessor is not in readonly mode.
+     *
+     * @throws {ReadonlyViolationException} When the accessor is readonly.
+     */
+    private assertNotReadOnly;
+    /**
+     * Create a shallow clone of this accessor.
+     *
+     * @returns Cloned accessor instance.
+     */
+    private cloneInstance;
+    /**
+     * Create a clone with new internal data.
+     *
+     * @param newData - New data for the clone.
+     * @returns Cloned accessor with updated data.
+     */
+    private mutateTo;
+}

package/dist/accessors/abstract-accessor.js

@@ -0,0 +1,294 @@
+import { PathNotFoundException } from '../exceptions/path-not-found-exception.js';
+import { ReadonlyViolationException } from '../exceptions/readonly-violation-exception.js';
+export class AbstractAccessor {
+    parser;
+    /** @internal Mutable state grouped to allow O(1) shallow clone in mutations. */
+    _state = {
+        data: {},
+        isReadonly: false,
+        isStrict: true,
+        rawInput: null,
+    };
+    /**
+     * @param parser - Dot-notation parser for path operations.
+     */
+    constructor(parser) {
+        this.parser = parser;
+    }
+    /**
+     * 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.
+     */
+    ingest(raw) {
+        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;
+    }
+    /**
+     * Retrieve the original raw input data before parsing.
+     *
+     * @returns Original input passed to `from()`.
+     */
+    getRaw() {
+        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 = true) {
+        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 = true) {
+        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, defaultValue = null) {
+        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) {
+        const sentinel = Object.create(null);
+        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, defaultValue = null) {
+        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) {
+        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) {
+        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, value) {
+        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, value) {
+        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) {
+        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) {
+        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) {
+        const results = {};
+        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() {
+        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) {
+        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) {
+        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, value) {
+        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) {
+        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.
+     */
+    assertNotReadOnly() {
+        if (this._state.isReadonly) {
+            throw new ReadonlyViolationException();
+        }
+    }
+    /**
+     * Create a shallow clone of this accessor.
+     *
+     * @returns Cloned accessor instance.
+     */
+    cloneInstance() {
+        const copy = Object.create(Object.getPrototypeOf(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.
+     */
+    mutateTo(newData) {
+        const copy = this.cloneInstance();
+        copy._state = { ...copy._state, data: newData };
+        return copy;
+    }
+}

package/dist/accessors/formats/any-accessor.d.ts

@@ -0,0 +1,35 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import type { ParseIntegrationInterface } from '../../contracts/parse-integration-interface.js';
+import type { DotNotationParser } from '../../core/dot-notation-parser.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 declare class AnyAccessor extends AbstractAccessor {
+    private readonly integration;
+    /**
+     * @param parser      - Dot-notation parser with security configuration.
+     * @param integration - Custom format parser for detecting and parsing input.
+     */
+    constructor(parser: DotNotationParser, integration: ParseIntegrationInterface);
+    /**
+     * 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;
+    /**
+     * @internal
+     */
+    protected parse(raw: unknown): Record<string, unknown>;
+}

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

@@ -0,0 +1,44 @@
+import { AbstractAccessor } from '../abstract-accessor.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 {
+    integration;
+    /**
+     * @param parser      - Dot-notation parser with security configuration.
+     * @param integration - Custom format parser for detecting and parsing input.
+     */
+    constructor(parser, integration) {
+        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) {
+        if (!this.integration.assertFormat(data)) {
+            throw new InvalidFormatException(`AnyAccessor failed, got ${typeof data}`);
+        }
+        return this.ingest(data);
+    }
+    /**
+     * @internal
+     */
+    parse(raw) {
+        return this.integration.parse(raw);
+    }
+}

package/dist/accessors/formats/array-accessor.d.ts

@@ -0,0 +1,26 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+/**
+ * Accessor for plain objects and arrays.
+ *
+ * Accepts a plain object or array directly. No string parsing is involved.
+ *
+ * @example
+ * const accessor = new ArrayAccessor(parser).from({ key: 'value' });
+ * accessor.get('key'); // 'value'
+ */
+export declare class ArrayAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a plain object or array.
+     *
+     * @param data - Object or array input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is neither an object nor an array.
+     * @throws {SecurityException} When data contains forbidden keys.
+     *
+     * @example
+     * accessor.from({ name: 'Alice' });
+     */
+    from(data: unknown): this;
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown>;
+}

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

@@ -0,0 +1,39 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+import { InvalidFormatException } from '../../exceptions/invalid-format-exception.js';
+/**
+ * Accessor for plain objects and arrays.
+ *
+ * Accepts a plain object or array directly. No string parsing is involved.
+ *
+ * @example
+ * const accessor = new ArrayAccessor(parser).from({ key: 'value' });
+ * accessor.get('key'); // 'value'
+ */
+export class ArrayAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a plain object or array.
+     *
+     * @param data - Object or array input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is neither an object nor an array.
+     * @throws {SecurityException} When data contains forbidden keys.
+     *
+     * @example
+     * accessor.from({ name: 'Alice' });
+     */
+    from(data) {
+        if (typeof data !== 'object' || data === null) {
+            /* Stryker disable StringLiteral -- error message content is cosmetic */
+            throw new InvalidFormatException(`ArrayAccessor expects an object or array, got ${typeof data}`);
+            /* Stryker restore StringLiteral */
+        }
+        const resolved = Array.isArray(data)
+            ? Object.fromEntries(data.map((v, i) => [String(i), v]))
+            : data;
+        return this.ingest(resolved);
+    }
+    /** {@inheritDoc} */
+    parse(raw) {
+        return raw;
+    }
+}

package/dist/accessors/formats/env-accessor.d.ts

@@ -0,0 +1,27 @@
+import { AbstractAccessor } from '../abstract-accessor.js';
+/**
+ * Accessor for dotenv-formatted strings.
+ *
+ * Parses KEY=VALUE lines, skipping comments (#) and blank lines.
+ * Strips surrounding single and double quotes from values.
+ *
+ * @example
+ * const accessor = new EnvAccessor(parser).from('DB_HOST=localhost\nDEBUG=true');
+ * accessor.get('DB_HOST'); // 'localhost'
+ */
+export declare class EnvAccessor extends AbstractAccessor {
+    /**
+     * Hydrate from a dotenv-formatted string.
+     *
+     * @param data - Dotenv string input.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When input is not a string.
+     * @throws {SecurityException} When payload size exceeds limit.
+     *
+     * @example
+     * accessor.from('APP_ENV=production\nPORT=3000');
+     */
+    from(data: unknown): this;
+    /** {@inheritDoc} */
+    protected parse(raw: unknown): Record<string, unknown>;
+}