@safeaccess/inline 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,12 +2,25 @@
 
 All notable changes to the `@safeaccess/inline` JavaScript/TypeScript package are documented in this file.
 
-## [0.1.2](https://github.com/felipesauer/safeaccess-inline/compare/js-v0.1.1...js-v0.1.2) (2026-04-08)
+## [0.1.3](https://github.com/felipesauer/safeaccess-inline/compare/js-v0.1.2...js-v0.1.3) (2026-04-09)
+
+
+### Bug Fixes
 
+* **js:** expose readonly extraForbiddenKeys on SecurityGuard for PHP parity ([2b428f6](https://github.com/felipesauer/safeaccess-inline/commit/2b428f6a1fef3607cb968ff18b52d8281158cc92))
+* **php:** correct array<string,mixed> type annotations and NdjsonAccessor integer key coercion ([7849f89](https://github.com/felipesauer/safeaccess-inline/commit/7849f89365bd5970738105ed3be9d2b58a15cd93))
+
+## [0.1.2](https://github.com/felipesauer/safeaccess-inline/compare/js-v0.1.1...js-v0.1.2) (2026-04-08)
 
 ### Bug Fixes
 
-* **js:** fix logo image URL in README ([16f4fc5](https://github.com/felipesauer/safeaccess-inline/commit/16f4fc5d69fa7ce86e3017bbbfc9f393925a5c37))
+- **js:** fix logo image URL in README ([16f4fc5](https://github.com/felipesauer/safeaccess-inline/commit/16f4fc5d69fa7ce86e3017bbbfc9f393925a5c37))
+
+### Internal Changes
+
+- **js:** expose `readonly extraForbiddenKeys` on `SecurityGuard` for parity with PHP (`public readonly array $extraForbiddenKeys`)
+- **js:** extract `ValidatableParserInterface` from `DotNotationParser` — `AbstractAccessor` now types its parser dependency against this contract instead of the concrete class
+- **js:** `SecurityGuard.sanitize()` handles nested arrays via a dedicated `sanitizeArray()` private method, matching the PHP `sanitizeRecursive` pattern
 
 ## [0.1.1](https://github.com/felipesauer/safeaccess-inline/compare/js-v0.1.0...js-v0.1.1) (2026-04-07)
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://github.com/user-attachments/assets/28202f8b-8ef1-4b94-b6d1-ec16f16c9cf9" width="80" alt="safeaccess-inline logo">
+  <img src="https://raw.githubusercontent.com/felipesauer/safeaccess-inline/main/.github/assets/logo.svg" width="80" alt="safeaccess-inline logo">
 </p>
 
 <h1 align="center">Safe Access Inline - TypeScript</h1>
@@ -11,7 +11,7 @@
 
 ---
 
-Safe nested data access with dot notation for JavaScript and TypeScript. Navigate deeply nested objects, JSON, YAML, XML, INI, ENV, and NDJSON structures - with built-in security validation, immutable writes, and a fluent builder API.
+Safe nested data access with dot notation for JavaScript and TypeScript. Navigate deeply nested arrays, objects, JSON, YAML, XML, INI, ENV, and NDJSON structures - with built-in security validation, immutable writes, and a fluent builder API.
 
 ## Installation
 
@@ -151,7 +151,7 @@ accessor.get('database.host'); // 'localhost'
 <summary><strong>ENV (dotenv)</strong></summary>
 
 ```typescript
-const accessor = Inline.fromEnv('APP_NAME=MyApp\nDB_HOST=localhost');
+const accessor = Inline.fromEnv('APP_NAME=MyApp\nAPP_DEBUG=true\nDB_HOST=localhost');
 accessor.get('DB_HOST'); // 'localhost'
 ```
 
@@ -181,6 +181,20 @@ objAccessor.get('name'); // 'Alice'
 
 </details>
 
+<details>
+<summary><strong>Any (custom format via integration)</strong></summary>
+
+```typescript
+import { Inline } from '@safeaccess/inline';
+import type { ParseIntegrationInterface } from '@safeaccess/inline';
+
+// Requires implementing ParseIntegrationInterface
+const accessor = Inline.withParserIntegration(new MyCsvIntegration()).fromAny(csvString);
+accessor.get('0.column_name');
+```
+
+</details>
+
 <details>
 <summary><strong>Dynamic (by TypeFormat enum)</strong></summary>
 
@@ -215,10 +229,8 @@ accessor.getMany({
 accessor.getRaw(); // original JSON string
 
 // Write (immutable - every write returns a new instance)
-const updated = accessor.set('a.d', 3);
-const cleaned = updated.remove('a.c');
-const merged = cleaned.merge('a', { e: 4 });
-const full = merged.mergeAll({ f: 5 });
+const updated = accessor.set('a.d', 3).remove('a.c').merge('a', { e: 4 }).mergeAll({ f: 5 });
+updated.all(); // { a: { b: 1, d: 3, e: 4 }, f: 5 }
 
 // Readonly mode - block all writes
 const readonly = accessor.readonly();
@@ -245,7 +257,7 @@ const accessor = Inline.withSecurityGuard(new SecurityGuard(512, ['secret']))
 | ------------------------------------ | ------------------------------------------------ |
 | `withSecurityGuard(guard)`           | Custom forbidden-key rules and depth limits      |
 | `withSecurityParser(parser)`         | Custom payload size and structural limits        |
-| `withPathCache(cache)`               | Custom path segment cache for repeated lookups   |
+| `withPathCache(cache)`               | Path segment cache for repeated lookups          |
 | `withParserIntegration(integration)` | Custom format parser for `fromAny()`             |
 | `withStrictMode(false)`              | Disable security validation (trusted input only) |
 
@@ -391,7 +403,7 @@ const accessor = Inline.withParserIntegration(csvIntegration).fromAny(csvString)
 
 ## API Reference
 
-### Facade: `Inline`
+### `Inline` Facade
 
 #### Static Factory Methods
 
@@ -442,6 +454,10 @@ const accessor = Inline.withParserIntegration(csvIntegration).fromAny(csvString)
 | `readonly(flag?)` | Block all writes           |
 | `strict(flag?)`   | Toggle security validation |
 
+#### TypeFormat Enum
+
+`Array` · `Object` · `Json` · `Xml` · `Yaml` · `Ini` · `Env` · `Ndjson` · `Any`
+
 ## Exports
 
 The package uses **named exports only** (no default exports). All public types are available from the main entry point:

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

@@ -45,6 +45,8 @@ export declare abstract class AbstractAccessor implements AccessorsInterface {
      *
      * @param data - Raw input in the format expected by the accessor.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the raw input cannot be parsed.
+     * @throws {SecurityException} When payload exceeds size limit, data contains forbidden keys, or violates structural limits.
      */
     abstract from(data: unknown): this;
     /**

package/dist/inline.d.ts

@@ -209,6 +209,8 @@ export declare class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'
@@ -360,6 +362,8 @@ export declare class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'

package/dist/inline.js

@@ -227,6 +227,8 @@ export class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'
@@ -430,6 +432,8 @@ export class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'

package/dist/security/security-guard.d.ts

@@ -24,6 +24,7 @@ import type { SecurityGuardInterface } from '../contracts/security-guard-interfa
  */
 export declare class SecurityGuard implements SecurityGuardInterface {
     readonly maxDepth: number;
+    readonly extraForbiddenKeys: ReadonlyArray<string>;
     private readonly forbiddenKeysMap;
     /**
      * Build the guard with default forbidden keys plus any extras.

package/dist/security/security-guard.js

@@ -25,6 +25,7 @@ import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-key
  */
 export class SecurityGuard {
     maxDepth;
+    extraForbiddenKeys;
     forbiddenKeysMap;
     /**
      * Build the guard with default forbidden keys plus any extras.
@@ -35,6 +36,7 @@ export class SecurityGuard {
     constructor(maxDepth = 512, 
     /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys = []) {
         this.maxDepth = Number.isFinite(maxDepth) ? maxDepth : 512;
+        this.extraForbiddenKeys = [...extraForbiddenKeys];
         /* Stryker disable next-line ConditionalExpression -- equivalent: if (false) still produces the same forbiddenKeysMap for empty arrays since Set(DEFAULT)=DEFAULT */
         if (extraForbiddenKeys.length === 0) {
             this.forbiddenKeysMap = DEFAULT_FORBIDDEN_KEYS;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@safeaccess/inline",
-    "version": "0.1.2",
+    "version": "0.1.3",
     "private": false,
     "description": "Safe nested data access with dot notation - JavaScript/TypeScript",
     "license": "MIT",

package/src/accessors/abstract-accessor.ts

@@ -75,6 +75,8 @@ export abstract class AbstractAccessor implements AccessorsInterface {
      *
      * @param data - Raw input in the format expected by the accessor.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the raw input cannot be parsed.
+     * @throws {SecurityException} When payload exceeds size limit, data contains forbidden keys, or violates structural limits.
      */
     abstract from(data: unknown): this;
 

package/src/inline.ts

@@ -259,6 +259,8 @@ export class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'
@@ -479,6 +481,8 @@ export class Inline extends InlineBuilderAccessor {
      * @param AccessorConstructor - The accessor class to instantiate.
      * @param data                - Raw data to hydrate the accessor with.
      * @returns Populated accessor instance.
+     * @throws {InvalidFormatException} When the data does not match the accessor's expected format.
+     * @throws {SecurityException} When security constraints are violated.
      *
      * @example
      * Inline.make(JsonAccessor, '{"key":"value"}').get('key'); // 'value'

package/src/security/security-guard.ts

@@ -28,6 +28,8 @@ import { DEFAULT_FORBIDDEN_KEYS, STREAM_WRAPPER_PREFIXES } from './forbidden-key
 export class SecurityGuard implements SecurityGuardInterface {
     readonly maxDepth: number;
 
+    readonly extraForbiddenKeys: ReadonlyArray<string>;
+
     private readonly forbiddenKeysMap: ReadonlySet<string>;
 
     /**
@@ -41,6 +43,7 @@ export class SecurityGuard implements SecurityGuardInterface {
         /* Stryker disable next-line ArrayDeclaration -- equivalent: default [] produces identical behavior; no extra keys added to Set */ extraForbiddenKeys: string[] = [],
     ) {
         this.maxDepth = Number.isFinite(maxDepth) ? maxDepth : 512;
+        this.extraForbiddenKeys = [...extraForbiddenKeys];
 
         /* Stryker disable next-line ConditionalExpression -- equivalent: if (false) still produces the same forbiddenKeysMap for empty arrays since Set(DEFAULT)=DEFAULT */
         if (extraForbiddenKeys.length === 0) {

package/tests/parser/xml-parser-scanner.test.ts

@@ -253,6 +253,24 @@ describe(`${XmlParser.name} > linear scanner - nesting counter`, () => {
         const a = result['a'] as Record<string, unknown>;
         expect(a['a']).toBe('');
     });
+
+    it('increments nestDepth for same-name opening tag with tab after name', () => {
+        const result = makeParser().parse('<root><a><a\t>inner</a></a></root>');
+        const a = result['a'] as Record<string, unknown>;
+        expect(a).toEqual({ a: 'inner' });
+    });
+
+    it('increments nestDepth for same-name opening tag with newline after name', () => {
+        const result = makeParser().parse('<root><a><a\n>inner</a></a></root>');
+        const a = result['a'] as Record<string, unknown>;
+        expect(a).toEqual({ a: 'inner' });
+    });
+
+    it('increments nestDepth for same-name opening tag with carriage return after name', () => {
+        const result = makeParser().parse('<root><a><a\r>inner</a></a></root>');
+        const a = result['a'] as Record<string, unknown>;
+        expect(a).toEqual({ a: 'inner' });
+    });
 });
 
 describe(`${XmlParser.name} > linear scanner - self-closing detection`, () => {
@@ -265,6 +283,11 @@ describe(`${XmlParser.name} > linear scanner - self-closing detection`, () => {
         const result = makeParser().parse('<root><flag enabled="true" /></root>');
         expect(result['flag']).toBe('');
     });
+
+    it('treats <tag / > (space after slash before >) as self-closing', () => {
+        const result = makeParser().parse('<root><empty / ></root>');
+        expect(result['empty']).toBe('');
+    });
 });
 
 describe(`${XmlParser.name} > linear scanner - skip non-element tokens`, () => {
@@ -299,6 +322,30 @@ describe(`${XmlParser.name} > linear scanner - skip non-element tokens`, () => {
         const result = makeParser().parse('<root><1tag>value</root>');
         expect(result['#text']).toBe('<1tag>value');
     });
+
+    it('does not parse element-like tokens inside XML comments', () => {
+        const result = makeParser().parse('<root><!-- <fake>x</fake> --><name>Alice</name></root>');
+        expect(result['name']).toBe('Alice');
+        expect(Object.keys(result)).toEqual(['name']);
+    });
+
+    it('does not parse element-like tokens inside processing instructions', () => {
+        const result = makeParser().parse('<root><?pi <data>x</data> ?><name>Bob</name></root>');
+        expect(result['name']).toBe('Bob');
+        expect(Object.keys(result)).toEqual(['name']);
+    });
+
+    it('ignores digit-started tag even when it has a matching close tag', () => {
+        const result = makeParser().parse('<root><1>v</1><name>w</name></root>');
+        expect(result['name']).toBe('w');
+        expect(Object.keys(result)).toEqual(['name']);
+    });
+
+    it('does not parse elements embedded inside a stray closing tag prefix', () => {
+        const result = makeParser().parse('<root></a<b>text</b><name>v</name></root>');
+        expect(result['name']).toBe('v');
+        expect(Object.keys(result)).toEqual(['name']);
+    });
 });
 
 describe(`${XmlParser.name} > linear scanner - unclosed and malformed tags`, () => {

package/tests/parser/xml-parser.test.ts

@@ -291,4 +291,15 @@ describe(`${XmlParser.name} > manual parser edge cases`, () => {
         const result = makeParser().parse('<root><item>hello <world</item></root>');
         expect(result['item']).toBe('hello <world');
     });
+
+    it('parses elements preceded by plain text in child content', () => {
+        const result = makeParser().parse('<root><wrap>prefix<a>v</a></wrap></root>');
+        const wrap = result['wrap'] as Record<string, unknown>;
+        expect(wrap['a']).toBe('v');
+    });
+
+    it('preserves child object with multiple keys without #text flattening', () => {
+        const result = makeParser().parse('<root><w><x>1</x><y>2</y></w></root>');
+        expect(result['w']).toEqual({ x: '1', y: '2' });
+    });
 });

package/tests/security/security-guard.test.ts

@@ -162,4 +162,14 @@ describe(`${SecurityGuard.name} > extraForbiddenKeys`, () => {
         expect(guard.isForbiddenKey('__proto__')).toBe(true);
         expect(guard.isForbiddenKey('constructor')).toBe(true);
     });
+
+    it('exposes the extra forbidden keys as a readonly array', () => {
+        const guard = new SecurityGuard(512, ['custom_a', 'custom_b']);
+        expect(guard.extraForbiddenKeys).toEqual(['custom_a', 'custom_b']);
+    });
+
+    it('exposes an empty readonly array when no extra keys are provided', () => {
+        const guard = new SecurityGuard();
+        expect(guard.extraForbiddenKeys).toEqual([]);
+    });
 });