@safeaccess/inline 0.1.1

package/dist/inline.js

@@ -0,0 +1,512 @@
+import { TypeFormat } from './type-format.js';
+import { DotNotationParser } from './core/dot-notation-parser.js';
+import { SecurityGuard } from './security/security-guard.js';
+import { SecurityParser } from './security/security-parser.js';
+import { AbstractAccessor } from './accessors/abstract-accessor.js';
+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 { UnsupportedTypeException } from './exceptions/unsupported-type-exception.js';
+import { InvalidFormatException } from './exceptions/invalid-format-exception.js';
+/**
+ * Facade for creating typed data accessors fluently.
+ *
+ * All static factory methods return a strongly-typed accessor instance.
+ * Use the builder methods (`withSecurityGuard`, `withSecurityParser`) to
+ * customize the security configuration before creating an accessor.
+ *
+ * @example
+ * const accessor = Inline.fromJson('{"name":"Alice"}');
+ * accessor.get('name'); // 'Alice'
+ *
+ * @example
+ * const accessor = Inline.from(TypeFormat.Yaml, 'name: Alice');
+ * accessor.get('name'); // 'Alice'
+ */
+export class Inline {
+    guard;
+    secParser;
+    pathCache;
+    integration;
+    strictMode;
+    constructor(guard, secParser, pathCache = null, integration = null, strictMode = null) {
+        this.guard = guard;
+        this.secParser = secParser;
+        this.pathCache = pathCache;
+        this.integration = integration;
+        this.strictMode = strictMode;
+    }
+    static defaultInstance() {
+        return new Inline(new SecurityGuard(), new SecurityParser());
+    }
+    makeParser() {
+        return new DotNotationParser(this.guard, this.secParser, this.pathCache ?? undefined);
+    }
+    /**
+     * Apply configured strict mode to a new accessor before hydration.
+     *
+     * @param accessor - Unhydrated accessor instance.
+     * @returns Same accessor with strict mode applied if configured.
+     */
+    prepare(accessor) {
+        if (this.strictMode !== null) {
+            return accessor.strict(this.strictMode);
+        }
+        return accessor;
+    }
+    /**
+     * Return a new Inline instance with a custom SecurityGuard, preserving other settings.
+     *
+     * @param guard - Custom security guard implementation.
+     * @returns New Inline builder instance.
+     */
+    withSecurityGuard(guard) {
+        return new Inline(guard, this.secParser, this.pathCache, this.integration, this.strictMode);
+    }
+    /**
+     * Return a new Inline instance with a custom SecurityParser, preserving other settings.
+     *
+     * @param parser - Custom security parser implementation.
+     * @returns New Inline builder instance.
+     */
+    withSecurityParser(parser) {
+        return new Inline(this.guard, parser, this.pathCache, this.integration, this.strictMode);
+    }
+    /**
+     * Return a new Inline instance with a custom path cache, preserving other settings.
+     *
+     * @param cache - Custom path cache implementation.
+     * @returns New Inline builder instance.
+     */
+    withPathCache(cache) {
+        return new Inline(this.guard, this.secParser, cache, this.integration, this.strictMode);
+    }
+    /**
+     * Return a new Inline instance with a custom parser integration, preserving other settings.
+     *
+     * @param integration - Custom format integration implementation.
+     * @returns New Inline builder instance.
+     */
+    withParserIntegration(integration) {
+        return new Inline(this.guard, this.secParser, this.pathCache, integration, this.strictMode);
+    }
+    /**
+     * Return a new Inline instance with the given strict mode, preserving other settings.
+     *
+     * @param strict - Whether to enable strict security validation.
+     * @returns New Inline builder instance.
+     *
+     * @security Passing `false` disables all SecurityGuard and SecurityParser
+     * validation. Only use with fully trusted, application-controlled input.
+     */
+    withStrictMode(strict) {
+        return new Inline(this.guard, this.secParser, this.pathCache, this.integration, strict);
+    }
+    /**
+     * Return a new Inline instance with a custom SecurityGuard.
+     *
+     * @param guard - Custom security guard implementation.
+     * @returns New Inline builder instance.
+     *
+     * @example
+     * Inline.withSecurityGuard(new SecurityGuard(10, ['extraKey'])).fromJson('{}');
+     */
+    static withSecurityGuard(guard) {
+        return new Inline(guard, new SecurityParser());
+    }
+    /**
+     * Return a new Inline instance with a custom SecurityParser.
+     *
+     * @param parser - Custom security parser implementation.
+     * @returns New Inline builder instance.
+     *
+     * @example
+     * Inline.withSecurityParser(new SecurityParser({ maxDepth: 10 })).fromJson('{}');
+     */
+    static withSecurityParser(parser) {
+        return new Inline(new SecurityGuard(), parser);
+    }
+    /**
+     * Return a new Inline instance with a custom path cache.
+     *
+     * @param cache - Custom path cache implementation.
+     * @returns New Inline builder instance.
+     *
+     * @example
+     * const cache: PathCacheInterface = { get: () => null, set: () => {}, has: () => false, clear: () => {} };
+     * Inline.withPathCache(cache).fromJson('{"key":"value"}');
+     */
+    static withPathCache(cache) {
+        return new Inline(new SecurityGuard(), new SecurityParser(), cache);
+    }
+    /**
+     * Return a new Inline instance with a custom parser integration for `fromAny()`.
+     *
+     * @param integration - Custom format integration implementation.
+     * @returns New Inline builder instance.
+     *
+     * @example
+     * Inline.withParserIntegration(new MyCsvIntegration()).fromAny(csvString);
+     */
+    static withParserIntegration(integration) {
+        return new Inline(new SecurityGuard(), new SecurityParser(), null, integration);
+    }
+    /**
+     * Return a new Inline instance with the given strict mode.
+     *
+     * @param strict - Whether to enable strict security validation.
+     * @returns New Inline builder instance.
+     *
+     * @security Passing `false` disables all SecurityGuard and SecurityParser
+     * validation. Only use with fully trusted, application-controlled input.
+     *
+     * @example
+     * Inline.withStrictMode(false).fromJson(hugePayload).get('key');
+     */
+    static withStrictMode(strict) {
+        return new Inline(new SecurityGuard(), new SecurityParser(), null, null, strict);
+    }
+    /**
+     * Create an ArrayAccessor from a plain object or array.
+     *
+     * @param data - Plain object or array input.
+     * @returns Populated ArrayAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromArray({ name: 'Alice' }).get('name'); // 'Alice'
+     */
+    fromArray(data) {
+        return this.prepare(new ArrayAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an ObjectAccessor from a JavaScript object.
+     *
+     * @param data - Object input (plain object, class instance, etc.).
+     * @returns Populated ObjectAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromObject({ user: { name: 'Alice' } }).get('user.name');
+     */
+    fromObject(data) {
+        return this.prepare(new ObjectAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create a JsonAccessor from a JSON string.
+     *
+     * @param data - Raw JSON string.
+     * @returns Populated JsonAccessor instance.
+     * @throws {InvalidFormatException} When the JSON is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromJson('{"key":"value"}').get('key'); // 'value'
+     */
+    fromJson(data) {
+        return this.prepare(new JsonAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an XmlAccessor from an XML string.
+     *
+     * @param data - Raw XML string.
+     * @returns Populated XmlAccessor instance.
+     * @throws {InvalidFormatException} When the XML is malformed.
+     * @throws {SecurityException} When DOCTYPE is detected.
+     *
+     * @example
+     * inline.fromXml('<root><key>value</key></root>').get('key');
+     */
+    fromXml(data) {
+        return this.prepare(new XmlAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create a YamlAccessor from a YAML string.
+     *
+     * @param data - Raw YAML string.
+     * @returns Populated YamlAccessor instance.
+     * @throws {YamlParseException} When the YAML is malformed or contains unsafe constructs.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromYaml('name: Alice').get('name'); // 'Alice'
+     */
+    fromYaml(data) {
+        return this.prepare(new YamlAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an IniAccessor from an INI string.
+     *
+     * @param data - Raw INI string.
+     * @returns Populated IniAccessor instance.
+     * @throws {InvalidFormatException} When the input is not a string.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromIni('[section]\nkey=value').get('section.key'); // 'value'
+     */
+    fromIni(data) {
+        return this.prepare(new IniAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an EnvAccessor from a dotenv-formatted string.
+     *
+     * @param data - Raw dotenv string.
+     * @returns Populated EnvAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromEnv('APP_NAME=MyApp').get('APP_NAME'); // 'MyApp'
+     */
+    fromEnv(data) {
+        return this.prepare(new EnvAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an NdjsonAccessor from a newline-delimited JSON string.
+     *
+     * @param data - Raw NDJSON string.
+     * @returns Populated NdjsonAccessor instance.
+     * @throws {InvalidFormatException} When any JSON line is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * inline.fromNdjson('{"id":1}\n{"id":2}').get('0.id'); // 1
+     */
+    fromNdjson(data) {
+        return this.prepare(new NdjsonAccessor(this.makeParser())).from(data);
+    }
+    /**
+     * Create an AnyAccessor from raw data using a custom integration.
+     *
+     * Uses the integration provided via `withParserIntegration()` by default,
+     * or the one passed as the second argument for a one-off override.
+     *
+     * @param data - Raw input data in any format supported by the integration.
+     * @param integration - Override integration for this call (optional).
+     * @returns Populated AnyAccessor instance.
+     * @throws {InvalidFormatException} When no integration is available or it rejects the format.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.withParserIntegration(new CsvIntegration()).fromAny(csvString);
+     */
+    fromAny(data, integration) {
+        const resolved = integration ?? this.integration;
+        if (resolved === null) {
+            throw new InvalidFormatException('AnyAccessor requires a ParseIntegrationInterface — use Inline.withParserIntegration(integration).fromAny(data).');
+        }
+        return this.prepare(new AnyAccessor(this.makeParser(), resolved)).from(data);
+    }
+    /**
+     * Create a typed accessor by its constructor.
+     *
+     * @param AccessorConstructor - The accessor class to instantiate.
+     * @param data                - Raw data to hydrate the accessor with.
+     * @returns Populated accessor instance.
+     *
+     * @example
+     * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'
+     */
+    make(AccessorConstructor, data) {
+        const accessor = new AccessorConstructor(this.makeParser());
+        if (this.strictMode !== null && accessor instanceof AbstractAccessor) {
+            return accessor.strict(this.strictMode).from(data);
+        }
+        return accessor.from(data);
+    }
+    /**
+     * Create an accessor for the given TypeFormat and raw data.
+     *
+     * @param typeFormat - The format to parse as.
+     * @param data - Raw input data.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data is malformed for the target format.
+     * @throws {SecurityException} When security constraints are violated.
+     * @throws {UnsupportedTypeException} When the TypeFormat is not supported.
+     */
+    from(typeFormat, data) {
+        switch (typeFormat) {
+            case TypeFormat.Array:
+                return this.fromArray(data);
+            case TypeFormat.Object:
+                return this.fromObject(data);
+            case TypeFormat.Json:
+                return this.fromJson(data);
+            case TypeFormat.Xml:
+                return this.fromXml(data);
+            case TypeFormat.Yaml:
+                return this.fromYaml(data);
+            case TypeFormat.Ini:
+                return this.fromIni(data);
+            case TypeFormat.Env:
+                return this.fromEnv(data);
+            case TypeFormat.Ndjson:
+                return this.fromNdjson(data);
+            case TypeFormat.Any:
+                return this.fromAny(data);
+            default: {
+                const exhaustive = typeFormat;
+                throw new UnsupportedTypeException(`TypeFormat '${String(exhaustive)}' is not supported.`);
+            }
+        }
+    }
+    /**
+     * Create an ArrayAccessor from a plain object or array.
+     *
+     * @param data - Plain object or array input.
+     * @returns Populated ArrayAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromArray({ name: 'Alice' }).get('name'); // 'Alice'
+     */
+    static fromArray(data) {
+        return Inline.defaultInstance().fromArray(data);
+    }
+    /**
+     * Create an ObjectAccessor from a JavaScript object.
+     *
+     * @param data - Object input (plain object, class instance, etc.).
+     * @returns Populated ObjectAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromObject({ user: { name: 'Alice' } }).get('user.name');
+     */
+    static fromObject(data) {
+        return Inline.defaultInstance().fromObject(data);
+    }
+    /**
+     * Create a JsonAccessor from a JSON string.
+     *
+     * @param data - Raw JSON string.
+     * @returns Populated JsonAccessor instance.
+     * @throws {InvalidFormatException} When the JSON is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromJson('{"key":"value"}').get('key'); // 'value'
+     */
+    static fromJson(data) {
+        return Inline.defaultInstance().fromJson(data);
+    }
+    /**
+     * Create an XmlAccessor from an XML string.
+     *
+     * @param data - Raw XML string.
+     * @returns Populated XmlAccessor instance.
+     * @throws {InvalidFormatException} When the XML is malformed.
+     * @throws {SecurityException} When DOCTYPE is detected.
+     *
+     * @example
+     * Inline.fromXml('<root><key>value</key></root>').get('key');
+     */
+    static fromXml(data) {
+        return Inline.defaultInstance().fromXml(data);
+    }
+    /**
+     * Create a YamlAccessor from a YAML string.
+     *
+     * @param data - Raw YAML string.
+     * @returns Populated YamlAccessor instance.
+     * @throws {YamlParseException} When the YAML is malformed or contains unsafe constructs.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromYaml('name: Alice\nage: 30').get('name'); // 'Alice'
+     */
+    static fromYaml(data) {
+        return Inline.defaultInstance().fromYaml(data);
+    }
+    /**
+     * Create an IniAccessor from an INI string.
+     *
+     * @param data - Raw INI string.
+     * @returns Populated IniAccessor instance.
+     * @throws {InvalidFormatException} When the input is not a string.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromIni('[section]\nkey=value').get('section.key'); // 'value'
+     */
+    static fromIni(data) {
+        return Inline.defaultInstance().fromIni(data);
+    }
+    /**
+     * Create an EnvAccessor from a dotenv-formatted string.
+     *
+     * @param data - Raw dotenv string.
+     * @returns Populated EnvAccessor instance.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromEnv('APP_NAME=MyApp\nDEBUG=true').get('APP_NAME'); // 'MyApp'
+     */
+    static fromEnv(data) {
+        return Inline.defaultInstance().fromEnv(data);
+    }
+    /**
+     * Create an NdjsonAccessor from a newline-delimited JSON string.
+     *
+     * @param data - Raw NDJSON string.
+     * @returns Populated NdjsonAccessor instance.
+     * @throws {InvalidFormatException} When any JSON line is malformed.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromNdjson('{"id":1}\n{"id":2}').get('0.id'); // 1
+     */
+    static fromNdjson(data) {
+        return Inline.defaultInstance().fromNdjson(data);
+    }
+    /**
+     * Create an accessor for the given TypeFormat and raw data.
+     *
+     * @param typeFormat - The format to parse as.
+     * @param data - Raw input data.
+     * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data is malformed for the target format.
+     * @throws {SecurityException} When security constraints are violated.
+     * @throws {UnsupportedTypeException} When the TypeFormat is not supported.
+     *
+     * @example
+     * Inline.from(TypeFormat.Json, '{"key":"value"}').get('key'); // 'value'
+     */
+    static from(typeFormat, data) {
+        return Inline.defaultInstance().from(typeFormat, data);
+    }
+    /**
+     * Create an AnyAccessor from raw data using a custom integration.
+     *
+     * @param data - Raw input data.
+     * @param integration - Integration that detects and parses the format (optional if set via `withParserIntegration`).
+     * @returns Populated AnyAccessor instance.
+     * @throws {InvalidFormatException} When no integration is available or it rejects the format.
+     * @throws {SecurityException} When security constraints are violated.
+     *
+     * @example
+     * Inline.fromAny(csvString, new CsvIntegration()).get('0.name');
+     */
+    static fromAny(data, integration) {
+        return Inline.defaultInstance().fromAny(data, integration);
+    }
+    /**
+     * Create a typed accessor by its constructor.
+     *
+     * @param AccessorConstructor - The accessor class to instantiate.
+     * @param data                - Raw data to hydrate the accessor with.
+     * @returns Populated accessor instance.
+     *
+     * @example
+     * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'
+     */
+    static make(AccessorConstructor, data) {
+        return Inline.defaultInstance().make(AccessorConstructor, data);
+    }
+}

package/dist/parser/xml-parser.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal XML-to-object parser for XmlAccessor.
+ *
+ * Provides both a browser path (DOMParser) and a minimal manual parser
+ * for Node.js environments. Does not depend on external XML libraries.
+ *
+ * @internal
+ */
+export declare class XmlParser {
+    private readonly maxDepth;
+    private readonly maxElements;
+    /**
+     * @param maxDepth - Maximum structural depth allowed.
+     * @param maxElements - Maximum number of opening-tag occurrences allowed in the
+     *   Node.js manual-parser path before parsing is aborted. Acts as a complexity
+     *   bound and defence-in-depth against document-bombing. Defaults to 10 000
+     *   (matches `SecurityParser.maxKeys`). Non-positive, non-finite, or `NaN` values
+     *   are clamped to 10 000 to prevent accidental guard disablement.
+     */
+    constructor(maxDepth: number, maxElements?: number);
+    /**
+     * Parse an XML body into a plain object using the best available parser.
+     *
+     * @param xml - Raw XML content (must not contain DOCTYPE).
+     * @returns Parsed data structure.
+     * @throws {InvalidFormatException} When XML is malformed.
+     * @throws {SecurityException} When structural depth exceeds limit.
+     *
+     * @example
+     * new XmlParser(10).parse('<root><key>value</key></root>'); // { key: 'value' }
+     */
+    parse(xml: string): Record<string, unknown>;
+    private parseBrowserXml;
+    private elementToRecord;
+    private parseXmlManual;
+    /**
+     * Extract root element inner content using an indexOf-based O(n) scan.
+     *
+     * Replaces the previous backreference regex to guarantee O(n) time regardless
+     * of document structure. The closing-tag match is verified by scanning
+     * backwards from the final `>` character of the trimmed document.
+     */
+    private extractRootContent;
+    private parseXmlChildren;
+    private addChild;
+}