@safeaccess/inline 0.1.1

package/src/contracts/path-cache-interface.ts

@@ -0,0 +1,43 @@
+/**
+ * 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/src/contracts/readable-accessors-interface.ts

@@ -0,0 +1,88 @@
+/**
+ * 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/src/contracts/security-guard-interface.ts

@@ -0,0 +1,43 @@
+/**
+ * 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/src/contracts/security-parser-interface.ts

@@ -0,0 +1,74 @@
+/**
+ * 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/src/contracts/writable-accessors-interface.ts

@@ -0,0 +1,70 @@
+/**
+ * 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;
+}