@safeaccess/inline 0.1.1 → 0.1.3

package/dist/core/accessor-factory.js

@@ -0,0 +1,157 @@
+import { ArrayAccessor } from '../accessors/formats/array-accessor.js';
+import { ObjectAccessor } from '../accessors/formats/object-accessor.js';
+import { JsonAccessor } from '../accessors/formats/json-accessor.js';
+import { XmlAccessor } from '../accessors/formats/xml-accessor.js';
+import { YamlAccessor } from '../accessors/formats/yaml-accessor.js';
+import { IniAccessor } from '../accessors/formats/ini-accessor.js';
+import { EnvAccessor } from '../accessors/formats/env-accessor.js';
+import { NdjsonAccessor } from '../accessors/formats/ndjson-accessor.js';
+import { AnyAccessor } from '../accessors/formats/any-accessor.js';
+import { InvalidFormatException } from '../exceptions/invalid-format-exception.js';
+/**
+ * Factory for creating typed format-specific accessors.
+ *
+ * Encapsulates the wiring between a parser and accessor construction,
+ * providing one method per supported format. Used internally by
+ * {@link Inline} to create accessors.
+ *
+ * @internal
+ */
+export class AccessorFactory {
+    parser;
+    defaultIntegration;
+    strictMode;
+    /**
+     * Initialize the factory with a parser, optional integration, and optional strict mode.
+     *
+     * @param parser - Parser for dot-notation resolution.
+     * @param defaultIntegration - Default integration for AnyAccessor.
+     * @param strictMode - Override strict mode for created accessors.
+     */
+    constructor(parser, defaultIntegration = null, strictMode = null) {
+        this.parser = parser;
+        this.defaultIntegration = defaultIntegration;
+        this.strictMode = strictMode;
+    }
+    /**
+     * Return the underlying parser used by this factory.
+     *
+     * @returns The parser instance.
+     */
+    getParser() {
+        return this.parser;
+    }
+    /**
+     * Apply configured strict mode to a new accessor before hydration.
+     *
+     * @param accessor - Unhydrated accessor instance.
+     * @returns Same accessor with strict mode applied if configured.
+     */
+    applyOptions(accessor) {
+        if (this.strictMode !== null) {
+            return accessor.strict(this.strictMode);
+        }
+        return accessor;
+    }
+    /**
+     * Create an ArrayAccessor from raw array data.
+     *
+     * @param data - Source array or object.
+     * @returns Populated ArrayAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    array(data) {
+        return this.applyOptions(new ArrayAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an ObjectAccessor from a source object.
+     *
+     * @param data - Source object.
+     * @returns Populated ObjectAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    object(data) {
+        return this.applyOptions(new ObjectAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create a JsonAccessor from a JSON string.
+     *
+     * @param data - Raw JSON string.
+     * @returns Populated JsonAccessor.
+     * @throws {InvalidFormatException} When the JSON is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    json(data) {
+        return this.applyOptions(new JsonAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an XmlAccessor from an XML string.
+     *
+     * @param data - Raw XML string.
+     * @returns Populated XmlAccessor.
+     * @throws {InvalidFormatException} When the XML is malformed.
+     * @throws {SecurityException} When DOCTYPE is detected.
+     */
+    xml(data) {
+        return this.applyOptions(new XmlAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create a YamlAccessor from a YAML string.
+     *
+     * @param data - Raw YAML string.
+     * @returns Populated YamlAccessor.
+     * @throws {YamlParseException} When the YAML is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    yaml(data) {
+        return this.applyOptions(new YamlAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an IniAccessor from an INI string.
+     *
+     * @param data - Raw INI string.
+     * @returns Populated IniAccessor.
+     * @throws {InvalidFormatException} When the INI is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    ini(data) {
+        return this.applyOptions(new IniAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an EnvAccessor from a dotenv-formatted string.
+     *
+     * @param data - Raw dotenv string.
+     * @returns Populated EnvAccessor.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    env(data) {
+        return this.applyOptions(new EnvAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an NdjsonAccessor from a newline-delimited JSON string.
+     *
+     * @param data - Raw NDJSON string.
+     * @returns Populated NdjsonAccessor.
+     * @throws {InvalidFormatException} When any JSON line is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     */
+    ndjson(data) {
+        return this.applyOptions(new NdjsonAccessor(this.parser)).from(data);
+    }
+    /**
+     * Create an AnyAccessor with automatic format detection.
+     *
+     * @param data - Raw data in any supported format.
+     * @param integration - Override integration (falls back to default).
+     * @returns Populated AnyAccessor.
+     * @throws {InvalidFormatException} When no integration is available.
+     */
+    any(data, integration) {
+        const resolved = integration ?? this.defaultIntegration;
+        if (resolved === null) {
+            throw new InvalidFormatException('AnyAccessor requires a ParseIntegrationInterface. ' +
+                'Pass one directly or configure a default via Inline.withParserIntegration(i).fromAny(data).');
+        }
+        return this.applyOptions(new AnyAccessor(this.parser, resolved)).from(data);
+    }
+}

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

@@ -1,26 +1,36 @@
 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';
+import type { ValidatableParserInterface } from '../contracts/validatable-parser-interface.js';
+import { SegmentParser } from '../path-query/segment-parser.js';
+import { SegmentPathResolver } from '../path-query/segment-path-resolver.js';
+import type { Segment } from '../path-query/segment-type.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.
  *
+ * @internal
+ *
  * @example
  * const parser = new DotNotationParser();
  * parser.get({ user: { name: 'Alice' } }, 'user.name'); // 'Alice'
  */
-export declare class DotNotationParser {
+export declare class DotNotationParser implements ValidatableParserInterface {
     private readonly securityGuard;
     private readonly securityParser;
     private readonly pathCache;
+    private readonly segmentParser;
+    private readonly segmentPathResolver;
     /**
      * @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.
+     * @param segmentParser - Path-string → segment converter.
+     * @param segmentPathResolver - Segment → value resolver.
      */
-    constructor(securityGuard?: SecurityGuardInterface, securityParser?: SecurityParserInterface, pathCache?: PathCacheInterface);
+    constructor(securityGuard?: SecurityGuardInterface, securityParser?: SecurityParserInterface, pathCache?: PathCacheInterface, segmentParser?: SegmentParser, segmentPathResolver?: SegmentPathResolver);
     /**
      * Resolve a dot-notation path against data, returning the matched value.
      *
@@ -34,6 +44,25 @@ export declare class DotNotationParser {
      * parser.get({ a: 1 }, 'a.b', 'default'); // 'default'
      */
     get(data: Record<string, unknown>, path: string, defaultValue?: unknown): unknown;
+    /**
+     * Resolve a pre-parsed segment array against data, returning the matched value.
+     *
+     * @param data - Source data object.
+     * @param segments - Typed segments from {@link SegmentParser}.
+     * @param defaultValue - Fallback returned when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    resolve(data: Record<string, unknown>, segments: Segment[], defaultValue?: unknown): unknown;
+    /**
+     * Retrieve a value at the given path, throwing when not found.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string.
+     * @returns Resolved value.
+     *
+     * @throws {PathNotFoundException} When the path does not exist.
+     */
+    getStrict(data: Record<string, unknown>, path: string): unknown;
     /**
      * Set a value at a dot-notation path, returning a new object.
      *
@@ -161,12 +190,12 @@ export declare class DotNotationParser {
      */
     getMaxKeys(): number;
     /**
-     * Parse a dot-notation path into segments, using cache when available.
+     * Retrieve parsed segments from cache or parse and cache the path.
      *
      * @param path - Dot-notation path string.
-     * @returns Array of path segments.
+     * @returns Cached or freshly parsed typed segments.
      */
-    private parsePath;
+    private segmentPathCache;
     /**
      * Recursively write a value at the given key path.
      *

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

@@ -1,11 +1,17 @@
 import { SecurityGuard } from '../security/security-guard.js';
 import { SecurityParser } from '../security/security-parser.js';
+import { PathNotFoundException } from '../exceptions/path-not-found-exception.js';
+import { SegmentFilterParser } from '../path-query/segment-filter-parser.js';
+import { SegmentParser } from '../path-query/segment-parser.js';
+import { SegmentPathResolver } from '../path-query/segment-path-resolver.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.
  *
+ * @internal
+ *
  * @example
  * const parser = new DotNotationParser();
  * parser.get({ user: { name: 'Alice' } }, 'user.name'); // 'Alice'
@@ -14,15 +20,22 @@ export class DotNotationParser {
     securityGuard;
     securityParser;
     pathCache;
+    segmentParser;
+    segmentPathResolver;
     /**
      * @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.
+     * @param segmentParser - Path-string → segment converter.
+     * @param segmentPathResolver - Segment → value resolver.
      */
-    constructor(securityGuard, securityParser, pathCache) {
+    constructor(securityGuard, securityParser, pathCache, segmentParser, segmentPathResolver) {
         this.securityGuard = securityGuard ?? new SecurityGuard();
         this.securityParser = securityParser ?? new SecurityParser();
         this.pathCache = pathCache ?? null;
+        const filterParser = new SegmentFilterParser(this.securityGuard);
+        this.segmentParser = segmentParser ?? new SegmentParser(filterParser);
+        this.segmentPathResolver = segmentPathResolver ?? new SegmentPathResolver(filterParser);
     }
     /**
      * Resolve a dot-notation path against data, returning the matched value.
@@ -41,8 +54,36 @@ export class DotNotationParser {
         if (path === '') {
             return defaultValue;
         }
-        const segments = this.parsePath(path);
-        return this.getAt(data, segments, defaultValue);
+        const segments = this.segmentPathCache(path);
+        return this.resolve(data, segments, defaultValue);
+    }
+    /**
+     * Resolve a pre-parsed segment array against data, returning the matched value.
+     *
+     * @param data - Source data object.
+     * @param segments - Typed segments from {@link SegmentParser}.
+     * @param defaultValue - Fallback returned when the path does not exist.
+     * @returns Resolved value or the default.
+     */
+    resolve(data, segments, defaultValue = null) {
+        return this.segmentPathResolver.resolve(data, segments, 0, defaultValue, this.securityParser.getMaxResolveDepth());
+    }
+    /**
+     * Retrieve a value at the given path, throwing when not found.
+     *
+     * @param data - Source data object.
+     * @param path - Dot-notation path string.
+     * @returns Resolved value.
+     *
+     * @throws {PathNotFoundException} When the path does not exist.
+     */
+    getStrict(data, path) {
+        const sentinel = Object.create(null);
+        const result = this.get(data, path, sentinel);
+        if (result === sentinel) {
+            throw new PathNotFoundException(`Path '${path}' not found.`);
+        }
+        return result;
     }
     /**
      * Set a value at a dot-notation path, returning a new object.
@@ -56,7 +97,7 @@ export class DotNotationParser {
      * parser.set({}, 'user.name', 'Alice'); // { user: { name: 'Alice' } }
      */
     set(data, path, value) {
-        const segments = this.parsePath(path);
+        const segments = this.segmentParser.parseKeys(path);
         return this.setAt(data, segments, value);
     }
     /**
@@ -89,7 +130,7 @@ export class DotNotationParser {
      * parser.remove({ a: { b: 1 } }, 'a.b'); // { a: {} }
      */
     remove(data, path) {
-        const segments = this.parsePath(path);
+        const segments = this.segmentParser.parseKeys(path);
         return this.removeAt(data, segments);
     }
     /**
@@ -229,22 +270,22 @@ export class DotNotationParser {
         return this.securityParser.getMaxKeys();
     }
     /**
-     * Parse a dot-notation path into segments, using cache when available.
+     * Retrieve parsed segments from cache or parse and cache the path.
      *
      * @param path - Dot-notation path string.
-     * @returns Array of path segments.
+     * @returns Cached or freshly parsed typed segments.
      */
-    parsePath(path) {
+    segmentPathCache(path) {
         if (this.pathCache !== null) {
             const cached = this.pathCache.get(path);
             if (cached !== null) {
                 return cached;
             }
-            const segments = path.split('.');
+            const segments = this.segmentParser.parseSegments(path);
             this.pathCache.set(path, segments);
             return segments;
         }
-        return path.split('.');
+        return this.segmentParser.parseSegments(path);
     }
     /**
      * Recursively write a value at the given key path.

package/dist/core/inline-builder-accessor.d.ts

@@ -0,0 +1,82 @@
+import type { SecurityGuardInterface } from '../contracts/security-guard-interface.js';
+import type { SecurityParserInterface } from '../contracts/security-parser-interface.js';
+import type { ParseIntegrationInterface } from '../contracts/parse-integration-interface.js';
+import type { PathCacheInterface } from '../contracts/path-cache-interface.js';
+import { AccessorFactory } from './accessor-factory.js';
+/**
+ * Builder for configuring and constructing the internal components of SafeAccess Inline.
+ *
+ * Provides an immutable builder API: each `withXxx()` method returns a new
+ * instance with the specified override, leaving the original unchanged.
+ *
+ * Note: PHP's equivalent uses `__callStatic`/`__call` magic to expose
+ * protected methods publicly. TypeScript has no equivalent mechanism, so
+ * builder methods are public directly and static forwarding is explicit
+ * in the {@link Inline} subclass.
+ *
+ * @internal
+ *
+ * @see Inline
+ */
+export declare class InlineBuilderAccessor {
+    protected readonly _guard: SecurityGuardInterface;
+    protected readonly _secParser: SecurityParserInterface;
+    protected readonly _pathCache: PathCacheInterface | null;
+    protected readonly _integration: ParseIntegrationInterface | null;
+    protected readonly _strictMode: boolean | null;
+    /**
+     * Create a builder with optional component overrides.
+     *
+     * @param guard - Custom security guard, or undefined for default.
+     * @param secParser - Custom security parser, or undefined for default.
+     * @param pathCache - Custom path cache, or null/undefined for default.
+     * @param integration - Custom format integration, or null/undefined for none.
+     * @param strictMode - Strict mode override, or null/undefined for accessor default.
+     */
+    constructor(guard?: SecurityGuardInterface, secParser?: SecurityParserInterface, pathCache?: PathCacheInterface | null, integration?: ParseIntegrationInterface | null, strictMode?: boolean | null);
+    /**
+     * Initialize the builder with default or provided components.
+     *
+     * @returns Configured factory ready to create typed accessors.
+     */
+    builder(): AccessorFactory;
+    /**
+     * Set a custom parser integration implementation.
+     *
+     * @param integration - Custom format integration to use.
+     * @returns New builder instance with the integration configured.
+     */
+    withParserIntegration(integration: ParseIntegrationInterface): this;
+    /**
+     * Set a custom security guard implementation.
+     *
+     * @param guard - Custom guard implementation to use.
+     * @returns New builder instance with the guard configured.
+     */
+    withSecurityGuard(guard: SecurityGuardInterface): this;
+    /**
+     * Set a custom security parser implementation.
+     *
+     * @param parser - Custom parser implementation to use.
+     * @returns New builder instance with the parser configured.
+     */
+    withSecurityParser(parser: SecurityParserInterface): this;
+    /**
+     * Set a custom path cache implementation.
+     *
+     * @param cache - Custom cache implementation to use.
+     * @returns New builder instance with the cache configured.
+     */
+    withPathCache(cache: PathCacheInterface): this;
+    /**
+     * Set the strict mode for all accessors created by this builder.
+     *
+     * @param strict - Whether to enable strict security validation.
+     * @returns New builder instance with the strict mode configured.
+     *
+     * @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.
+     */
+    withStrictMode(strict: boolean): this;
+}

package/dist/core/inline-builder-accessor.js

@@ -0,0 +1,107 @@
+import { SecurityGuard } from '../security/security-guard.js';
+import { SecurityParser } from '../security/security-parser.js';
+import { SimplePathCache } from '../cache/simple-path-cache.js';
+import { DotNotationParser } from './dot-notation-parser.js';
+import { AccessorFactory } from './accessor-factory.js';
+import { SegmentFilterParser } from '../path-query/segment-filter-parser.js';
+import { SegmentParser } from '../path-query/segment-parser.js';
+import { SegmentPathResolver } from '../path-query/segment-path-resolver.js';
+/**
+ * Builder for configuring and constructing the internal components of SafeAccess Inline.
+ *
+ * Provides an immutable builder API: each `withXxx()` method returns a new
+ * instance with the specified override, leaving the original unchanged.
+ *
+ * Note: PHP's equivalent uses `__callStatic`/`__call` magic to expose
+ * protected methods publicly. TypeScript has no equivalent mechanism, so
+ * builder methods are public directly and static forwarding is explicit
+ * in the {@link Inline} subclass.
+ *
+ * @internal
+ *
+ * @see Inline
+ */
+export class InlineBuilderAccessor {
+    _guard;
+    _secParser;
+    _pathCache;
+    _integration;
+    _strictMode;
+    /**
+     * Create a builder with optional component overrides.
+     *
+     * @param guard - Custom security guard, or undefined for default.
+     * @param secParser - Custom security parser, or undefined for default.
+     * @param pathCache - Custom path cache, or null/undefined for default.
+     * @param integration - Custom format integration, or null/undefined for none.
+     * @param strictMode - Strict mode override, or null/undefined for accessor default.
+     */
+    constructor(guard, secParser, pathCache, integration, strictMode) {
+        this._guard = guard ?? new SecurityGuard();
+        this._secParser = secParser ?? new SecurityParser();
+        this._pathCache = pathCache ?? null;
+        this._integration = integration ?? null;
+        this._strictMode = strictMode ?? null;
+    }
+    /**
+     * Initialize the builder with default or provided components.
+     *
+     * @returns Configured factory ready to create typed accessors.
+     */
+    builder() {
+        const filterParser = new SegmentFilterParser(this._guard);
+        const segmentParser = new SegmentParser(filterParser);
+        const segmentPathResolver = new SegmentPathResolver(filterParser);
+        const dotNotationParser = new DotNotationParser(this._guard, this._secParser, this._pathCache ?? new SimplePathCache(), segmentParser, segmentPathResolver);
+        return new AccessorFactory(dotNotationParser, this._integration, this._strictMode);
+    }
+    /**
+     * Set a custom parser integration implementation.
+     *
+     * @param integration - Custom format integration to use.
+     * @returns New builder instance with the integration configured.
+     */
+    withParserIntegration(integration) {
+        return new this.constructor(this._guard, this._secParser, this._pathCache, integration, this._strictMode);
+    }
+    /**
+     * Set a custom security guard implementation.
+     *
+     * @param guard - Custom guard implementation to use.
+     * @returns New builder instance with the guard configured.
+     */
+    withSecurityGuard(guard) {
+        return new this.constructor(guard, this._secParser, this._pathCache, this._integration, this._strictMode);
+    }
+    /**
+     * Set a custom security parser implementation.
+     *
+     * @param parser - Custom parser implementation to use.
+     * @returns New builder instance with the parser configured.
+     */
+    withSecurityParser(parser) {
+        return new this.constructor(this._guard, parser, this._pathCache, this._integration, this._strictMode);
+    }
+    /**
+     * Set a custom path cache implementation.
+     *
+     * @param cache - Custom cache implementation to use.
+     * @returns New builder instance with the cache configured.
+     */
+    withPathCache(cache) {
+        return new this.constructor(this._guard, this._secParser, cache, this._integration, this._strictMode);
+    }
+    /**
+     * Set the strict mode for all accessors created by this builder.
+     *
+     * @param strict - Whether to enable strict security validation.
+     * @returns New builder instance with the strict mode configured.
+     *
+     * @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.
+     */
+    withStrictMode(strict) {
+        return new this.constructor(this._guard, this._secParser, this._pathCache, this._integration, strict);
+    }
+}

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

@@ -1,6 +1,15 @@
 /**
  * Base exception for all accessor-layer errors.
  *
+ * @api
+ *
+ * @see InvalidFormatException  Thrown on malformed input data.
+ * @see ParserException         Thrown on parser-level operational errors.
+ * @see PathNotFoundException   Thrown when a requested path does not exist.
+ * @see SecurityException       Thrown on security constraint violations.
+ * @see ReadonlyViolationException Thrown on write attempts to a readonly accessor.
+ * @see UnsupportedTypeException   Thrown when an unsupported format is requested.
+ *
  * @example
  * throw new AccessorException('Something went wrong.');
  */

package/dist/exceptions/accessor-exception.js

@@ -1,6 +1,15 @@
 /**
  * Base exception for all accessor-layer errors.
  *
+ * @api
+ *
+ * @see InvalidFormatException  Thrown on malformed input data.
+ * @see ParserException         Thrown on parser-level operational errors.
+ * @see PathNotFoundException   Thrown when a requested path does not exist.
+ * @see SecurityException       Thrown on security constraint violations.
+ * @see ReadonlyViolationException Thrown on write attempts to a readonly accessor.
+ * @see UnsupportedTypeException   Thrown when an unsupported format is requested.
+ *
  * @example
  * throw new AccessorException('Something went wrong.');
  */

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

@@ -2,6 +2,11 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when the input data cannot be parsed as the expected format.
  *
+ * @api
+ *
+ * @see AccessorException       Parent exception class.
+ * @see YamlParseException      Specialized subclass for YAML parsing errors.
+ *
  * @example
  * throw new InvalidFormatException('Expected JSON string, got number.');
  */

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

@@ -2,6 +2,11 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when the input data cannot be parsed as the expected format.
  *
+ * @api
+ *
+ * @see AccessorException       Parent exception class.
+ * @see YamlParseException      Specialized subclass for YAML parsing errors.
+ *
  * @example
  * throw new InvalidFormatException('Expected JSON string, got number.');
  */

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

@@ -2,6 +2,10 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when an underlying parser encounters a structural error.
  *
+ * @api
+ *
+ * @see AccessorException  Parent exception class.
+ *
  * @example
  * throw new ParserException('Parser failed to process input.');
  */

package/dist/exceptions/parser-exception.js

@@ -2,6 +2,10 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when an underlying parser encounters a structural error.
  *
+ * @api
+ *
+ * @see AccessorException  Parent exception class.
+ *
  * @example
  * throw new ParserException('Parser failed to process input.');
  */

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

@@ -2,6 +2,10 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when a dot-notation path does not exist in the data.
  *
+ * @api
+ *
+ * @see AccessorException  Parent exception class.
+ *
  * @example
  * throw new PathNotFoundException("Path 'user.address.zip' not found.");
  */

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

@@ -2,6 +2,10 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when a dot-notation path does not exist in the data.
  *
+ * @api
+ *
+ * @see AccessorException  Parent exception class.
+ *
  * @example
  * throw new PathNotFoundException("Path 'user.address.zip' not found.");
  */

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

@@ -2,6 +2,10 @@ import { AccessorException } from './accessor-exception.js';
 /**
  * Thrown when a write operation is attempted on a readonly accessor.
  *
+ * @api
+ *
+ * @see AccessorException  Parent exception class.
+ *
  * @example
  * const accessor = Inline.fromJson('{}').readonly(true);
  * accessor.set('key', 'value'); // throws ReadonlyViolationException