@nodable/entities 1.0.1 → 1.1.0

package/README.md

@@ -4,7 +4,7 @@ Standalone, zero-dependency XML/HTML entity replacement with:
 
 - **5 entity categories** processed in a fixed, predictable order
 - **Persistent vs. input entity separation** — no state leaks between documents
-- **`getInstance()`** — clean per-document reset without cloning
+- **`reset()`** — clean per-document reset without cloning
 - **Composable named entity groups** (HTML, currency, math, arrows, numeric refs)
 - **Security limits** — cap total expansions and expanded length per document
 - **Granular limit targeting** — apply limits to any subset of categories
@@ -57,7 +57,7 @@ persistent input/runtime → external → system → default → amp
 
 ### `persistent external` — Caller-supplied configuration entities
 
-Entities set at configuration time that survive across all documents. Never wiped by `getInstance()`. Set via `setExternalEntities()` or `addExternalEntity()` / `addEntity()`.
+Entities set at configuration time that survive across all documents. Never wiped by `reset()`. Set via `setExternalEntities()` or `addExternalEntity()` / `addEntity()`.
 
 ```js
 const replacer = new EntityReplacer({ default: true });
@@ -68,7 +68,7 @@ replacer.replace('&brand; makes &product;');
 
 ### `input / runtime` — Per-document DOCTYPE entities
 
-Entities injected by the parser from the document's DOCTYPE block. Stored separately from persistent entities and **wiped on every `getInstance()` call** so they cannot leak between documents.
+Entities injected by the parser from the document's DOCTYPE block. Stored separately from persistent entities and **wiped on every `reset()` call** so they cannot leak between documents.
 
 Set via `addInputEntities()`. Never call this manually — `BaseOutputBuilder` calls it automatically.
 
@@ -155,7 +155,7 @@ replacer.replace('Tom & Jerry <cartoons>');
 
 ### `setExternalEntities(map)`
 
-Replace the full set of **persistent** external entities. These survive across all documents and are not cleared by `getInstance()`.
+Replace the full set of **persistent** external entities. These survive across all documents and are not cleared by `reset()`.
 
 ```js
 replacer.setExternalEntities({ brand: 'Acme', year: '2025' });
@@ -174,7 +174,7 @@ replacer.addExternalEntity('year', '2025');
 
 ### `addInputEntities(map)`
 
-Inject **input/runtime** (DOCTYPE) entities for the current document. These are stored separately from persistent entities and wiped on the next `getInstance()` call. Also resets per-document expansion counters.
+Inject **input/runtime** (DOCTYPE) entities for the current document. These are stored separately from persistent entities and wiped on the next `reset()` call. Also resets per-document expansion counters.
 
 ```js
 // Called automatically by BaseOutputBuilder — no manual wiring needed.
@@ -183,7 +183,7 @@ replacer.addInputEntities(doctypeEntityMap);
 
 Values containing `&` are silently skipped. Accepts pre-built `{ regex, val }` or `{ regx, val }` objects as produced by `DocTypeReader`.
 
-### `getInstance()`
+### `reset()`
 
 Reset all per-document state and return `this`.
 
@@ -200,9 +200,9 @@ The builder factory calls this when creating a new builder instance, ensuring ea
 
 ```js
 // In a builder factory:
-getInstance() {
+reset() {
   const builder = new MyBuilder(this.config);
-  builder.entityParser = this.entityVP.getInstance();
+  builder.entityParser = this.entityVP.reset();
   return builder;
 }
 ```
@@ -215,12 +215,12 @@ A key design goal is that entities from one document never bleed into the next.
 
 ```
 Document 1 parse:
-  factory.getInstance()           → evp.getInstance()  [clears input, resets counters]
+  factory.reset()           → evp.reset()  [clears input, resets counters]
   builder sees DOCTYPE            → evp.addInputEntities({ version: '1.0' })
   builder processes values        → evp.parse('&brand; v&version;') → 'Acme v1.0'
 
 Document 2 parse (no DOCTYPE):
-  factory.getInstance()           → evp.getInstance()  [clears &version;, resets counters]
+  factory.reset()           → evp.reset()  [clears &version;, resets counters]
   no DOCTYPE                      → addInputEntities() not called
   builder processes values        → evp.parse('&brand; v&version;') → 'Acme v&version;'
                                     ↑ persistent &brand; works
@@ -300,16 +300,14 @@ postCheck: (resolved) =>
 
 ---
 
-## `EntitiesValueParser` — flex-xml-parser adapter
-
-`EntitiesValueParser` wraps `EntityReplacer` and implements the `ValueParser` interface used by `@nodable/flexible-xml-parser`.
+## Integration with — flex-xml-parser adapter
 
 ### Setup
 
 ```js
-import { EntitiesValueParser, COMMON_HTML } from '@nodable/entities';
+import EntityReplacer, { COMMON_HTML } from '@nodable/entities';
 
-const evp = new EntitiesValueParser({
+const evp = new EntityReplacer({
   system: COMMON_HTML,
   maxTotalExpansions: 500,
 });
@@ -329,7 +327,7 @@ parser.parse(xml);
 All `EntityReplacerOptions` are accepted, plus one extra:
 
 ```js
-new EntitiesValueParser({
+new EntityReplacer({
   // All EntityReplacer options...
   default: true,
   system: COMMON_HTML,
@@ -341,48 +339,20 @@ new EntitiesValueParser({
 })
 ```
 
-### `setExternalEntities(map)`
-
-Replace the full persistent entity map. These entities survive across all documents.
-
-```js
-evp.setExternalEntities({ brand: 'Acme', copy: '©' });
-```
-
-### `addEntity(key, value)`
-
-Append a single persistent external entity. Previously registered entities are preserved.
-
-```js
-evp.addEntity('copy',  '©');
-evp.addEntity('trade', '™');
-evp.addEntity('year',  '2024');
-```
-
-Throws if `key` contains `&` or `;`, or if `value` contains `&`.
-
-### `getInstance()` — called by builder factory
+### `reset()` — called by builder factory
 
 Reset per-document state (input entities + counters) and return `this`. The builder factory calls this each time it creates a new builder instance.
 
 ```js
-// In your CompactObjBuilderFactory.getInstance():
-getInstance() {
+// In your CompactObjBuilderFactory.reset():
+reset() {
   const builder = new CompactObjBuilder(this._config);
   // Reset EVP for the new document:
-  builder.entityParser = this._entityVP.getInstance();
+  builder.entityParser = this._entityVP.reset();
   return builder;
 }
 ```
 
-### `addInputEntities(entities)` — called automatically
-
-Receives the DOCTYPE entity map from `BaseOutputBuilder` once per parse. Resets per-document expansion counters. Accepts both plain string values and `{ regx, val }` objects from `DocTypeReader`.
-
-### `parse(val, context?)`
-
-Implements the `ValueParser` interface. `context` is accepted but ignored. Returns non-string input unchanged.
-
 ---
 
 ## Custom Entity Tables
@@ -421,7 +391,7 @@ const replacer = new EntityReplacer({
 | Numeric refs with leading zeros                | ✅                | ✅                  |
 | DOCTYPE / external entity injection            | ❌                | ✅                  |
 | Persistent vs. input entity separation         | ❌                | ✅                  |
-| Per-document reset via `getInstance()`         | ❌                | ✅                  |
+| Per-document reset via `reset()`         | ❌                | ✅                  |
 | Expansion count limit                          | ❌                | ✅                  |
 | Expanded length limit                          | ❌                | ✅                  |
 | `applyLimitsTo` granularity                    | ❌                | ✅                  |
@@ -437,11 +407,9 @@ Full TypeScript declarations are included via `index.d.ts`. No `@types/` package
 
 ```ts
 import EntityReplacer, {
-  EntitiesValueParser,
   COMMON_HTML,
   EntityTable,
   EntityReplacerOptions,
-  EntitiesValueParserOptions,
 } from '@nodable/entities';
 
 // EntityReplacer
@@ -454,19 +422,8 @@ const opts: EntityReplacerOptions = {
 };
 const replacer = new EntityReplacer(opts);
 replacer.setExternalEntities({ brand: 'Acme' });
-replacer.getInstance(); // reset for new document
+replacer.reset(); // reset for new document
 replacer.addInputEntities({ version: '1.0' }); // from DOCTYPE
-
-// EntitiesValueParser
-const evpOpts: EntitiesValueParserOptions = {
-  system: COMMON_HTML,
-  entities: { brand: 'Acme' },
-};
-const evp = new EntitiesValueParser(evpOpts);
-evp.addEntity('copy', '©');
-evp.getInstance();                            // called by builder factory
-evp.addInputEntities({ company: 'Nodable' }); // called by BaseOutputBuilder
-const result: string = evp.parse('<©&brand;');
 ```
 
 ## Note

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodable/entities",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Replace XML, HTML, External entites with security controls",
   "main": "./src/index.js",
   "type": "module",

package/src/EntityReplacer.js

@@ -230,13 +230,11 @@ export default class EntityReplacer {
    * The builder factory calls this each time it creates a new builder instance
    * so DOCTYPE entities from a previous document are never carried over.
    *
-   * @returns {EntityReplacer} `this`, after reset
    */
-  getInstance() {
+  reset() {
     this._inputEntries = [];
     this._totalExpansions = 0;
     this._expandedLength = 0;
-    return this;
   }
 
   // -------------------------------------------------------------------------
@@ -295,6 +293,15 @@ export default class EntityReplacer {
     return str;
   }
 
+
+  /**
+   * 
+   * @param {string} val 
+   * @returns 
+   */
+  parse(val) {
+    return this.replace(val);
+  }
   // -------------------------------------------------------------------------
   // Private helpers
   // -------------------------------------------------------------------------

package/src/index.d.ts

@@ -212,9 +212,8 @@ export default class EntityReplacer {
    * The builder factory calls this when creating a new builder instance,
    * ensuring each document starts clean regardless of whether it has a DOCTYPE.
    *
-   * @returns `this` — for convenient chaining in factory code
    */
-  getInstance(): this;
+  reset(): this;
 
   // -------------------------------------------------------------------------
   // Primary API
@@ -225,26 +224,18 @@ export default class EntityReplacer {
    * Returns `str` unchanged if it contains no `&` character (fast path).
    */
   replace(str: string): string;
+
+  /**
+   * wrapper on replace()
+   */
+  parse(str: string): string;
 }
 
 // ---------------------------------------------------------------------------
 // EntitiesValueParser
 // ---------------------------------------------------------------------------
 
-/**
- * Options accepted by `EntitiesValueParser` — a superset of `EntityReplacerOptions`.
- */
-export interface EntitiesValueParserOptions extends EntityReplacerOptions {
-  /**
-   * Initial persistent external entity map loaded at construction time.
-   * Values must not contain `&` (to prevent recursive expansion).
-   * Equivalent to calling `setExternalEntities()` after construction.
-   *
-   * @example
-   * new EntitiesValueParser({ entities: { copy: '©', trade: '™' } })
-   */
-  entities?: Record<string, string>;
-}
+
 
 /**
  * Raw DOCTYPE entity map shape as produced by `DocTypeReader`.
@@ -270,112 +261,6 @@ export interface ValueParserContext {
   isLeafNode?: boolean;
 }
 
-/**
- * `EntitiesValueParser` — value-parser adapter that wraps `EntityReplacer`
- * for use with `@nodable/flexible-xml-parser`.
- *
- * ## Setup
- *
- * ```ts
- * import { EntitiesValueParser, COMMON_HTML } from '@nodable/entities';
- *
- * const evp = new EntitiesValueParser({ system: COMMON_HTML });
- *
- * // Persistent entities — never wiped between documents:
- * evp.setExternalEntities({ brand: 'Acme', product: 'Widget' });
- *
- * // Register with the builder factory:
- * builder.registerValueParser('entity', evp);
- *
- * const parser = new XMLParser({ OutputBuilder: builder });
- * parser.parse(xml);
- * ```
- *
- * ## Lifecycle (called automatically by the builder / parser)
- *
- * | Caller          | Method                | When                                      |
- * |-----------------|----------------------|-------------------------------------------|
- * | Builder factory | `getInstance()`       | Before each `parse()` call                |
- * | Builder         | `addInputEntities()`  | After DOCTYPE is read (if present)        |
- * | Builder         | `parse(val)`          | For each text / attribute value           |
- */
-export class EntitiesValueParser {
-  constructor(options?: EntitiesValueParserOptions);
-
-  // -------------------------------------------------------------------------
-  // Persistent external entity registration
-  // -------------------------------------------------------------------------
-
-  /**
-   * Replace the full set of persistent external entities.
-   *
-   * These survive across all documents and are **not** cleared by
-   * `getInstance()`. Call this once after construction (or at any time to
-   * swap the entire persistent entity map).
-   *
-   * @throws if any value contains `&`
-   */
-  setExternalEntities(map: Record<string, string>): void;
-
-  /**
-   * Append a single persistent external entity.
-   *
-   * Provide the bare name without `&` and `;` — e.g. `'copy'` for `&copy;`.
-   * Existing persistent entities are preserved.
-   *
-   * @throws if `key` contains `&` or `;`
-   * @throws if `value` is not a string or contains `&`
-   */
-  addEntity(key: string, value: string): void;
-
-  // -------------------------------------------------------------------------
-  // Builder factory integration
-  // -------------------------------------------------------------------------
-
-  /**
-   * Reset per-document state and return `this`.
-   *
-   * Clears input/runtime entities (DOCTYPE) and resets expansion counters.
-   * Does **not** clear persistent external entities.
-   *
-   * The builder factory calls this when creating a new builder instance.
-   *
-   * @returns `this`
-   */
-  getInstance(): this;
-
-  // -------------------------------------------------------------------------
-  // DOCTYPE integration — called automatically by BaseOutputBuilder
-  // -------------------------------------------------------------------------
-
-  /**
-   * Receive DOCTYPE entities for the current document.
-   *
-   * Called automatically by `BaseOutputBuilder`. Stores entities separately
-   * from persistent entities so they are wiped on the next `getInstance()`.
-   * Also resets per-document expansion counters.
-   *
-   * Accepts both plain string values and `{ regx, val }` / `{ regex, val }`
-   * objects as produced by `DocTypeReader`.
-   */
-  addInputEntities(entities: DocTypeEntityMap): void;
-
-  // -------------------------------------------------------------------------
-  // ValueParser interface
-  // -------------------------------------------------------------------------
-
-  /**
-   * Replace entity references in `val`.
-   *
-   * Implements the `ValueParser` interface. The `context` argument is
-   * accepted but ignored — replacement is applied uniformly to all values.
-   *
-   * Returns non-string input unchanged.
-   */
-  parse(val: string, context?: ValueParserContext): string;
-  parse(val: unknown, context?: ValueParserContext): unknown;
-}
-
 // ---------------------------------------------------------------------------
 // Named entity group exports
 // ---------------------------------------------------------------------------

package/src/index.js

@@ -17,7 +17,6 @@
 
 export { default } from './EntityReplacer.js';
 export { DEFAULT_XML_ENTITIES, AMP_ENTITY } from './EntityReplacer.js';
-export { default as EntitiesValueParser } from './EntitiesValueParser.js';
 export {
   COMMON_HTML,
   CURRENCY_ENTITIES,

package/src/EntitiesValueParser.js

@@ -1,152 +0,0 @@
-import EntityReplacer from './EntityReplacer.js';
-
-/**
- * EntitiesValueParser — value-parser adapter that wraps `EntityReplacer`.
- *
- * Register an instance under the key `'entity'` on a `@nodable/flexible-xml-parser`
- * output builder factory to enable entity expansion for all parsed text values.
- *
- * ## Lifecycle
- *
- * 1. **Construction** — supply configuration and optional persistent entities.
- * 2. **`setExternalEntities(map)`** — (re)set the full persistent entity map.
- *    Or use `addEntity(key, value)` to add one at a time.
- * 3. **`getInstance()`** — builder factory calls this when creating a new builder
- *    instance. Resets input entities and per-document counters. Returns `this`.
- * 4. **`addInputEntities(map)`** — builder calls this if the document has a
- *    DOCTYPE block. Stores entities for *this document only*.
- * 5. **`parse(val)`** — called by the builder for each text value.
- *
- * ```js
- * const evp = new EntitiesValueParser({ system: COMMON_HTML });
- * evp.setExternalEntities({ brand: 'Acme' });
- * builder.registerValueParser('entity', evp);
- * ```
- *
- * -------------------------------------------------------------------------
- * Constructor options (all optional)
- * -------------------------------------------------------------------------
- *
- * `default`             — `true` (default) | `false`/`null` | custom EntityTable
- * `system`              — `false` (default) | `true` for COMMON_HTML | EntityTable
- * `amp`                 — `true` (default) | `false`/`null`
- * `maxTotalExpansions`  — max entity refs expanded per document (0 = unlimited)
- * `maxExpandedLength`   — max characters added by expansion per document (0 = unlimited)
- * `applyLimitsTo`       — which categories count toward limits (default: `'external'`)
- * `postCheck`           — `(resolved, original) => string` hook
- * `entities`            — initial persistent entity map, e.g. `{ copy: '©' }`
- */
-export default class EntitiesValueParser {
-  constructor(options = {}) {
-    this._replacer = new EntityReplacer(options);
-
-    // Load any entities provided inline at construction time as persistent entities
-    if (options.entities && typeof options.entities === 'object') {
-      const init = {};
-      for (const [key, val] of Object.entries(options.entities)) {
-        this._validateEntityArgs(key, val);
-        init[key] = val;
-      }
-      this._replacer.setExternalEntities(init);
-    }
-  }
-
-  // -------------------------------------------------------------------------
-  // Persistent external entity registration
-  // -------------------------------------------------------------------------
-
-  /**
-   * Replace the full set of persistent external entities.
-   * These survive across documents and are never wiped by `getInstance()`.
-   *
-   * @param {Record<string, string>} map  — e.g. `{ copy: '©', brand: 'Acme' }`
-   */
-  setExternalEntities(map) {
-    for (const [key, val] of Object.entries(map)) {
-      this._validateEntityArgs(key, val);
-    }
-    this._replacer.setExternalEntities(map);
-  }
-
-  /**
-   * Add (or replace) a single persistent external entity.
-   * Existing persistent entities are preserved.
-   *
-   * @param {string} key   — bare name without `&` / `;`, e.g. `'copy'`
-   * @param {string} value — replacement string, e.g. `'©'`
-   */
-  addEntity(key, value) {
-    this._validateEntityArgs(key, value);
-    this._replacer.addExternalEntity(key, value);
-  }
-
-  // -------------------------------------------------------------------------
-  // Builder factory integration
-  // -------------------------------------------------------------------------
-
-  /**
-   * Reset per-document state (input entities + expansion counters) and return `this`.
-   *
-   * The builder factory calls this when creating a new builder instance so that
-   * DOCTYPE entities from a previous document are never carried over.
-   *
-   * @returns {EntitiesValueParser} `this`
-   */
-  getInstance() {
-    this._replacer.getInstance();
-    return this;
-  }
-
-  // -------------------------------------------------------------------------
-  // DOCTYPE integration — called by BaseOutputBuilder
-  // -------------------------------------------------------------------------
-
-  /**
-   * Receive DOCTYPE entities from the output builder.
-   *
-   * These are stored separately from persistent entities and wiped on the next
-   * `getInstance()` call. Resets per-document expansion counters.
-   *
-   * @param {Record<string, string | { regx: RegExp, val: string | Function }>} entities
-   *   Raw entity map from `DocTypeReader` — values may be plain strings or
-   *   `{ regx, val }` objects (note: `regx`, not `regex`, matching the reader's output).
-   */
-  addInputEntities(entities) {
-    this._replacer.addInputEntities(entities);
-  }
-
-  // -------------------------------------------------------------------------
-  // ValueParser interface
-  // -------------------------------------------------------------------------
-
-  /**
-   * Replace entity references in `val`.
-   *
-   * @param {string} val
-   * @param {object} [_context]
-   * @returns {string}
-   */
-  parse(val, _context) {
-    if (typeof val !== 'string') return val;
-    return this._replacer.replace(val);
-  }
-
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
-  _validateEntityArgs(key, value) {
-    if (typeof key !== 'string' || key.includes('&') || key.includes(';')) {
-      throw new Error(
-        `[EntitiesValueParser] Entity key must not contain '&' or ';'. ` +
-        `Use 'copy' for '&copy;', got: ${JSON.stringify(key)}`
-      );
-    }
-    if (typeof value !== 'string' || value.includes('&')) {
-      throw new Error(
-        `[EntitiesValueParser] Entity value must be a plain string that does not ` +
-        `contain '&', got: ${JSON.stringify(value)}`
-      );
-    }
-  }
-}