@safeaccess/inline 0.1.1

package/dist/core/dot-notation-parser.js

@@ -0,0 +1,343 @@
+import { SecurityGuard } from '../security/security-guard.js';
+import { SecurityParser } from '../security/security-parser.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 class DotNotationParser {
+    securityGuard;
+    securityParser;
+    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, securityParser, pathCache) {
+        this.securityGuard = securityGuard ?? new SecurityGuard();
+        this.securityParser = securityParser ?? new SecurityParser();
+        this.pathCache = pathCache ?? null;
+    }
+    /**
+     * 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, path, defaultValue = null) {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- equivalent: empty path on split produces [''] which misses all keys anyway */
+        if (path === '') {
+            return defaultValue;
+        }
+        const segments = this.parsePath(path);
+        return this.getAt(data, segments, defaultValue);
+    }
+    /**
+     * 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, path, value) {
+        const segments = this.parsePath(path);
+        return this.setAt(data, segments, value);
+    }
+    /**
+     * 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, path) {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement,StringLiteral -- equivalent: empty path produces [''] key which is never found → false anyway */
+        if (path === '') {
+            return false;
+        }
+        const sentinel = Object.create(null);
+        return this.get(data, path, sentinel) !== sentinel;
+    }
+    /**
+     * 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, path) {
+        const segments = this.parsePath(path);
+        return this.removeAt(data, segments);
+    }
+    /**
+     * 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, segments, defaultValue = null) {
+        let current = data;
+        for (const key of segments) {
+            if (
+            /* Stryker disable next-line ConditionalExpression -- equivalent: false||null-check||own-check still returns default for primitives */
+            typeof current !== 'object' ||
+                current === null ||
+                !Object.prototype.hasOwnProperty.call(current, key)) {
+                return defaultValue;
+            }
+            current = current[key];
+        }
+        return current;
+    }
+    /**
+     * 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, segments, value) {
+        if (segments.length === 0) {
+            return data;
+        }
+        return this.writeAt(data, segments, 0, value);
+    }
+    /**
+     * 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, segments) {
+        const sentinel = Object.create(null);
+        return this.getAt(data, segments, sentinel) !== sentinel;
+    }
+    /**
+     * 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, segments) {
+        /* Stryker disable next-line ConditionalExpression,BlockStatement -- equivalent: empty segments → eraseAt hits undefined key → hasOwnProperty false → returns data anyway */
+        if (segments.length === 0) {
+            return data;
+        }
+        return this.eraseAt(data, segments, 0);
+    }
+    /**
+     * 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, path, value) {
+        const existing = path !== '' ? this.get(data, path, {}) : data;
+        const merged = this.deepMerge(
+        /* Stryker disable next-line ConditionalExpression -- equivalent: existing !== null → true still passes {} when existing is not an object due to typeof check */
+        typeof existing === 'object' && existing !== null
+            ? existing
+            : {}, value);
+        return path !== '' ? this.set(data, path, merged) : merged;
+    }
+    /**
+     * 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) {
+        this.securityParser.assertMaxKeys(data);
+        this.securityParser.assertMaxStructuralDepth(data, this.securityParser.getMaxDepth());
+        this.securityGuard.assertSafeKeys(data);
+    }
+    /**
+     * 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) {
+        this.securityParser.assertPayloadSize(input);
+    }
+    /**
+     * Return the configured maximum structural nesting depth.
+     *
+     * @returns Maximum allowed depth from the security parser.
+     */
+    getMaxDepth() {
+        return this.securityParser.getMaxDepth();
+    }
+    /**
+     * Return the configured maximum total key count.
+     *
+     * @returns Maximum allowed key count from the security parser.
+     */
+    getMaxKeys() {
+        return this.securityParser.getMaxKeys();
+    }
+    /**
+     * Parse a dot-notation path into segments, using cache when available.
+     *
+     * @param path - Dot-notation path string.
+     * @returns Array of path segments.
+     */
+    parsePath(path) {
+        if (this.pathCache !== null) {
+            const cached = this.pathCache.get(path);
+            if (cached !== null) {
+                return cached;
+            }
+            const segments = path.split('.');
+            this.pathCache.set(path, segments);
+            return segments;
+        }
+        return path.split('.');
+    }
+    /**
+     * 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.
+     */
+    writeAt(data, segments, index, value) {
+        const key = segments[index];
+        this.securityGuard.assertSafeKey(key);
+        const copy = { ...data };
+        if (index === segments.length - 1) {
+            copy[key] = value;
+            return copy;
+        }
+        const child = copy[key];
+        const childObj = 
+        /* Stryker disable next-line ConditionalExpression -- equivalent: child !== null → true still handles array via !Array.isArray */
+        typeof child === 'object' && child !== null && !Array.isArray(child)
+            ? child
+            : {};
+        copy[key] = this.writeAt(childObj, segments, index + 1, value);
+        return copy;
+    }
+    /**
+     * 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.
+     */
+    eraseAt(data, segments, index) {
+        const key = segments[index];
+        this.securityGuard.assertSafeKey(key);
+        /* Stryker disable next-line ConditionalExpression,BlockStatement -- equivalent: missing key → continue to delete copy[undefined] which is a no-op */
+        if (!Object.prototype.hasOwnProperty.call(data, key)) {
+            return data;
+        }
+        const copy = { ...data };
+        /* Stryker disable next-line ConditionalExpression -- equivalent: terminal vs recurse; extra recursion with empty segments produces the same delete */
+        if (index === segments.length - 1) {
+            delete copy[key];
+            return copy;
+        }
+        const child = copy[key];
+        /* Stryker disable next-line ConditionalExpression -- equivalent: false||null removes only null guard but hasOwnProperty on non-objects still returns copy unchanged */
+        if (typeof child !== 'object' || child === null) {
+            return copy;
+        }
+        copy[key] = this.eraseAt(child, segments, index + 1);
+        return copy;
+    }
+    /**
+     * 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.
+     */
+    deepMerge(target, source, depth = 0) {
+        this.securityParser.assertMaxResolveDepth(depth);
+        const result = { ...target };
+        for (const [key, sourceVal] of Object.entries(source)) {
+            this.securityGuard.assertSafeKey(key);
+            const targetVal = result[key];
+            if (
+            /* Stryker disable next-line ConditionalExpression,LogicalOperator -- equivalent: null checks on objects that are already typed as unknown; isArray guards ensure correct behavior */
+            typeof sourceVal === 'object' &&
+                /* Stryker disable next-line ConditionalExpression -- equivalent: Array.isArray already prevents non-object arrays */
+                sourceVal !== null &&
+                !Array.isArray(sourceVal) &&
+                /* Stryker disable next-line ConditionalExpression -- equivalent */
+                typeof targetVal === 'object' &&
+                /* Stryker disable next-line ConditionalExpression -- equivalent: null guarded by Array.isArray check below */
+                targetVal !== null &&
+                !Array.isArray(targetVal)) {
+                result[key] = this.deepMerge(targetVal, sourceVal, depth + 1);
+            }
+            else {
+                result[key] = sourceVal;
+            }
+        }
+        return result;
+    }
+}

package/dist/exceptions/accessor-exception.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Base exception for all accessor-layer errors.
+ *
+ * @example
+ * throw new AccessorException('Something went wrong.');
+ */
+export declare class AccessorException extends Error {
+    /**
+     * @param message - Human-readable error description.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/accessor-exception.js

@@ -0,0 +1,16 @@
+/**
+ * Base exception for all accessor-layer errors.
+ *
+ * @example
+ * throw new AccessorException('Something went wrong.');
+ */
+export class AccessorException extends Error {
+    /**
+     * @param message - Human-readable error description.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'AccessorException';
+    }
+}

package/dist/exceptions/invalid-format-exception.d.ts

@@ -0,0 +1,14 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when the input data cannot be parsed as the expected format.
+ *
+ * @example
+ * throw new InvalidFormatException('Expected JSON string, got number.');
+ */
+export declare class InvalidFormatException extends AccessorException {
+    /**
+     * @param message - Description of the format violation.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/invalid-format-exception.js

@@ -0,0 +1,17 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when the input data cannot be parsed as the expected format.
+ *
+ * @example
+ * throw new InvalidFormatException('Expected JSON string, got number.');
+ */
+export class InvalidFormatException extends AccessorException {
+    /**
+     * @param message - Description of the format violation.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'InvalidFormatException';
+    }
+}

package/dist/exceptions/parser-exception.d.ts

@@ -0,0 +1,14 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when an underlying parser encounters a structural error.
+ *
+ * @example
+ * throw new ParserException('Parser failed to process input.');
+ */
+export declare class ParserException extends AccessorException {
+    /**
+     * @param message - Description of the parser failure.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/parser-exception.js

@@ -0,0 +1,17 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when an underlying parser encounters a structural error.
+ *
+ * @example
+ * throw new ParserException('Parser failed to process input.');
+ */
+export class ParserException extends AccessorException {
+    /**
+     * @param message - Description of the parser failure.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ParserException';
+    }
+}

package/dist/exceptions/path-not-found-exception.d.ts

@@ -0,0 +1,14 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a dot-notation path does not exist in the data.
+ *
+ * @example
+ * throw new PathNotFoundException("Path 'user.address.zip' not found.");
+ */
+export declare class PathNotFoundException extends AccessorException {
+    /**
+     * @param message - Description including the missing path.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/path-not-found-exception.js

@@ -0,0 +1,17 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a dot-notation path does not exist in the data.
+ *
+ * @example
+ * throw new PathNotFoundException("Path 'user.address.zip' not found.");
+ */
+export class PathNotFoundException extends AccessorException {
+    /**
+     * @param message - Description including the missing path.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PathNotFoundException';
+    }
+}

package/dist/exceptions/readonly-violation-exception.d.ts

@@ -0,0 +1,15 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a write operation is attempted on a readonly accessor.
+ *
+ * @example
+ * const accessor = Inline.fromJson('{}').readonly(true);
+ * accessor.set('key', 'value'); // throws ReadonlyViolationException
+ */
+export declare class ReadonlyViolationException extends AccessorException {
+    /**
+     * @param message - Error message. Defaults to 'Cannot modify a readonly accessor.'
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/exceptions/readonly-violation-exception.js

@@ -0,0 +1,18 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a write operation is attempted on a readonly accessor.
+ *
+ * @example
+ * const accessor = Inline.fromJson('{}').readonly(true);
+ * accessor.set('key', 'value'); // throws ReadonlyViolationException
+ */
+export class ReadonlyViolationException extends AccessorException {
+    /**
+     * @param message - Error message. Defaults to 'Cannot modify a readonly accessor.'
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message = 'Cannot modify a readonly accessor.', options) {
+        super(message, options);
+        this.name = 'ReadonlyViolationException';
+    }
+}

package/dist/exceptions/security-exception.d.ts

@@ -0,0 +1,18 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a security validation check fails.
+ *
+ * Covers forbidden keys (prototype pollution vectors, legacy prototype manipulation
+ * methods, stream wrapper / protocol URI schemes, Node.js globals),
+ * payload size violations, key-count limits, and depth limit violations.
+ *
+ * @example
+ * throw new SecurityException("Forbidden key '__proto__' detected.");
+ */
+export declare class SecurityException extends AccessorException {
+    /**
+     * @param message - Description of the security violation.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/security-exception.js

@@ -0,0 +1,21 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when a security validation check fails.
+ *
+ * Covers forbidden keys (prototype pollution vectors, legacy prototype manipulation
+ * methods, stream wrapper / protocol URI schemes, Node.js globals),
+ * payload size violations, key-count limits, and depth limit violations.
+ *
+ * @example
+ * throw new SecurityException("Forbidden key '__proto__' detected.");
+ */
+export class SecurityException extends AccessorException {
+    /**
+     * @param message - Description of the security violation.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SecurityException';
+    }
+}

package/dist/exceptions/unsupported-type-exception.d.ts

@@ -0,0 +1,14 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when the requested format or TypeFormat value is not supported.
+ *
+ * @example
+ * throw new UnsupportedTypeException('TypeFormat.Csv is not supported.');
+ */
+export declare class UnsupportedTypeException extends AccessorException {
+    /**
+     * @param message - Description of the unsupported type.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/unsupported-type-exception.js

@@ -0,0 +1,17 @@
+import { AccessorException } from './accessor-exception.js';
+/**
+ * Thrown when the requested format or TypeFormat value is not supported.
+ *
+ * @example
+ * throw new UnsupportedTypeException('TypeFormat.Csv is not supported.');
+ */
+export class UnsupportedTypeException extends AccessorException {
+    /**
+     * @param message - Description of the unsupported type.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'UnsupportedTypeException';
+    }
+}

package/dist/exceptions/yaml-parse-exception.d.ts

@@ -0,0 +1,17 @@
+import { InvalidFormatException } from './invalid-format-exception.js';
+/**
+ * Thrown when a YAML string contains invalid syntax or unsafe constructs.
+ *
+ * Unsafe constructs include: tags (!! and !), anchors (&), aliases (*),
+ * and merge keys (<<).
+ *
+ * @example
+ * throw new YamlParseException('YAML anchors are not supported (line 3).');
+ */
+export declare class YamlParseException extends InvalidFormatException {
+    /**
+     * @param message - Description of the YAML parse failure.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/exceptions/yaml-parse-exception.js

@@ -0,0 +1,20 @@
+import { InvalidFormatException } from './invalid-format-exception.js';
+/**
+ * Thrown when a YAML string contains invalid syntax or unsafe constructs.
+ *
+ * Unsafe constructs include: tags (!! and !), anchors (&), aliases (*),
+ * and merge keys (<<).
+ *
+ * @example
+ * throw new YamlParseException('YAML anchors are not supported (line 3).');
+ */
+export class YamlParseException extends InvalidFormatException {
+    /**
+     * @param message - Description of the YAML parse failure.
+     * @param options - Optional cause chaining via `ErrorOptions`.
+     */
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'YamlParseException';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { Inline } from './inline.js';
+export { TypeFormat } from './type-format.js';
+export { AbstractAccessor } from './accessors/abstract-accessor.js';
+export { ArrayAccessor } from './accessors/formats/array-accessor.js';
+export { ObjectAccessor } from './accessors/formats/object-accessor.js';
+export { JsonAccessor } from './accessors/formats/json-accessor.js';
+export { XmlAccessor } from './accessors/formats/xml-accessor.js';
+export { YamlAccessor } from './accessors/formats/yaml-accessor.js';
+export { IniAccessor } from './accessors/formats/ini-accessor.js';
+export { EnvAccessor } from './accessors/formats/env-accessor.js';
+export { NdjsonAccessor } from './accessors/formats/ndjson-accessor.js';
+export { AnyAccessor } from './accessors/formats/any-accessor.js';
+export { SecurityGuard } from './security/security-guard.js';
+export { SecurityParser } from './security/security-parser.js';
+export { AccessorException } from './exceptions/accessor-exception.js';
+export { InvalidFormatException } from './exceptions/invalid-format-exception.js';
+export { YamlParseException } from './exceptions/yaml-parse-exception.js';
+export { ParserException } from './exceptions/parser-exception.js';
+export { PathNotFoundException } from './exceptions/path-not-found-exception.js';
+export { ReadonlyViolationException } from './exceptions/readonly-violation-exception.js';
+export { SecurityException } from './exceptions/security-exception.js';
+export { UnsupportedTypeException } from './exceptions/unsupported-type-exception.js';
+export type { AccessorsInterface } from './contracts/accessors-interface.js';
+export type { ReadableAccessorsInterface } from './contracts/readable-accessors-interface.js';
+export type { WritableAccessorsInterface } from './contracts/writable-accessors-interface.js';
+export type { FactoryAccessorsInterface } from './contracts/factory-accessors-interface.js';
+export type { SecurityGuardInterface } from './contracts/security-guard-interface.js';
+export type { SecurityParserInterface } from './contracts/security-parser-interface.js';
+export type { PathCacheInterface } from './contracts/path-cache-interface.js';
+export type { ParseIntegrationInterface } from './contracts/parse-integration-interface.js';