tally-simple 1.1.1 → 1.8.2

package/docs/architecture.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>System Architecture — Tally Simple</title>
+    <link rel="stylesheet" href="style.css">
+</head>
+<body>
+    <div class="container">
+        <nav class="doc-nav">
+            <a href="index.html">&larr; Documentation Hub</a>
+            <a href="architecture.md">View Markdown</a>
+        </nav>
+
+        <h1>System Architecture</h1>
+        <p>Tally Simple is designed with strict boundaries separating the public contract from the internal execution engines.</p>
+
+        <h2>Architectural Overview</h2>
+        <pre><code>┌─────────────────────────────────────────────────────────────┐
+│                 1. Declarative Specifications               │
+│                                                             │
+│   src/v7/api.json                 src/v7/source.json        │
+│   (Public Route Allowlist)        (TDL Definition Tree)     │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 2. Public Composition Root                  │
+│                                                             │
+│   src/v7/index.js                                           │
+│   (Injects Specifications into Route &amp; Execution Engines)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 3. Internal Working Engines                 │
+│                                                             │
+│   internal-working/route/         internal-working/execution│
+│   (Object Tree Assembly)          (4-Step Request Pipeline) │
+└─────────────────────────────────────────────────────────────┘</code></pre>
+
+        <h2>The Three Layers</h2>
+
+        <h3>1. The Declarative Specifications (<code>src/v7/</code>)</h3>
+        <ul>
+            <li><strong><code>api.json</code> (The Allowlist)</strong>: An explicit array of dot-separated string paths that declare the public API boundary (e.g., <code>["tally.masters.units.fetch", "tally.masters.stockItems.withBatches", ...]</code>).</li>
+            <li><strong><code>source.json</code> (The Tree of Truth)</strong>: A pure domain tree containing the TDL collection queries (<code>&lt;TYPE&gt;Unit&lt;/TYPE&gt;...</code>) and actions. It is completely decoupled from transport and contains no connection settings or HTTP logic.</li>
+        </ul>
+
+        <h3>2. The Public Composition Root (<code>src/v7/index.js</code>)</h3>
+        <ul>
+            <li>Acts as the single entry point for the active version.</li>
+            <li>Imports <code>source.json</code> and <code>api.json</code> and injects them directly into the internal route builder via dependency injection.</li>
+            <li>Exports a single, ready-to-use default client object.</li>
+        </ul>
+
+        <h3>3. The Internal Working Engines (<code>src/v7/internal-working/</code>)</h3>
+        <ul>
+            <li><strong><code>route/</code></strong>: Dynamically builds the nested, callable JavaScript object tree based on <code>api.json</code> without hardcoding methods.</li>
+            <li><strong><code>execution/</code></strong>: Executes the runtime query: validates the company argument, retrieves the TDL query from <code>source.json</code>, constructs the XML request envelope, and dispatches the HTTP POST request to Tally.</li>
+        </ul>
+
+        <h2>Architectural Principles</h2>
+        <ol>
+            <li><strong>Single Source of Truth for Domain Only:</strong> <code>source.json</code> is the authority on <em>what queries exist and what TDL they request</em>, not a dumping ground for server URLs or HTTP headers.</li>
+            <li><strong>Strictly One Export per File:</strong> Every module in the codebase adheres to a single default export (<code>export default startFunc;</code>).</li>
+            <li><strong>Explicit Parameter Unwrapping:</strong> Every function accepts a single object with <code>in</code>-prefixed keys and unwraps them immediately to <code>local</code>-prefixed variables.</li>
+            <li><strong>Zero Runtime Dependencies:</strong> Built entirely on standard Node.js built-ins.</li>
+        </ol>
+    </div>
+</body>
+</html>

package/docs/architecture.md

@@ -1,43 +1,82 @@
-# Architecture and the package story
-
-## One definition, two ways to use it
-
-The package has one query model and two entrypoints:
-
-~~~text
-src/v1/source.json
-        │
-        ├── api.json ──> generated JavaScript client ──> application imports
-        │
-        └── request traversal ──> XML over HTTP ──> Tally
-
-api.json ──> tally-simple CLI ──> stdout
-~~~
-
-source.json owns the TDL collection definitions and the default request envelope. api.json is the product boundary: only paths listed there become public methods or CLI commands.
-
-## Request lifecycle
-
-1. An application or CLI selects a public path.
-2. The client validates and trims the company name.
-3. The path is traversed into the source definition.
-4. The company is XML-escaped and inserted into the request envelope.
-5. The collection body is inserted into the envelope.
-6. The configured fetch implementation sends the request to Tally.
-7. The response body is returned as text; non-2xx responses become errors.
-
-The default client is useful for a quick start. createTallyClient() provides the boundary for applications that need a different URL, headers, timeout, or fetch implementation.
-
-## Adding a public endpoint
-
-1. Add the TDL definition under src/v1/source.json.
-2. Add its complete path to src/v1/external-api/api.json.
-3. Run npm run generate:dts.
-4. Add or update an offline test.
-5. Run npm run verify.
-
-Do not edit src/index.d.ts by hand; it is generated from the public path list.
-
-## Publish boundary
-
-package.json exposes the ESM entrypoint and CLI explicitly. Its files allowlist publishes src, bin, docs, and the package-facing metadata while excluding tests and development scripts. prepublishOnly runs declaration generation and the offline test suite before npm publish.
+# System Architecture
+
+[**View this document as HTML**](./architecture.html) · [**Documentation Hub**](./index.html)
+
+Tally Simple is designed with strict boundaries separating the public contract from the internal execution engines.
+
+---
+
+## Architectural Overview
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                 1. Declarative Specifications               │
+│                                                             │
+│   src/v7/api.json                 src/v7/source.json        │
+│   (Public Route Allowlist)        (TDL Definition Tree)     │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 2. Public Composition Root                  │
+│                                                             │
+│   src/v7/index.js                                           │
+│   (Injects Specifications into Route & Execution Engines)   │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 3. Internal Working Engines                 │
+│                                                             │
+│   internal-working/route/         internal-working/execution│
+│   (Object Tree Assembly)          (4-Step Request Pipeline) │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## The Three Layers
+
+### 1. The Declarative Specifications (`src/v7/`)
+- **`api.json` (The Allowlist)**: An explicit array of dot-separated string paths that declare the public API boundary (e.g., `["tally.masters.units.fetch", "tally.masters.stockItems.withBatches", ...]`).
+- **`source.json` (The Tree of Truth)**: A pure domain tree containing the TDL collection queries (`<TYPE>Unit</TYPE>...`) and actions. It is completely decoupled from transport and contains **no** connection settings or HTTP logic.
+
+### 2. The Public Composition Root (`src/v7/index.js`)
+- Acts as the single entry point for the active version.
+- Imports `source.json` and `api.json` and injects them directly into the internal route builder:
+  ```javascript
+  const tally = createRoute({
+      inApiPaths: apiPaths,
+      inSource: source,
+      inExecutor: execute
+  });
+  ```
+- Exports a single, ready-to-use default client object.
+
+### 3. The Internal Working Engines (`src/v7/internal-working/`)
+- **`route/`**: Dynamically builds the nested, callable JavaScript object tree based on `api.json` without hardcoding methods.
+- **`execution/`**: Executes the runtime query: validates the company argument, retrieves the TDL query from `source.json`, constructs the XML request envelope, and dispatches the HTTP POST request to Tally.
+
+---
+
+## Architectural Principles
+
+1. **Single Source of Truth for Domain Only:**
+   `source.json` is the sole authority on *what queries exist and what TDL they request*, not a dumping ground for server URLs or HTTP headers.
+
+2. **Strictly One Export per File:**
+   Every module in the codebase adheres to a single default export (`export default startFunc;`).
+
+3. **Explicit Parameter Unwrapping:**
+   Every function accepts a single object with `in`-prefixed keys and unwraps them immediately to `local`-prefixed variables:
+   ```javascript
+   const startFunc = ({ inRoutePath, inCompany, inSource }) => {
+       const localRoutePath = inRoutePath;
+       const localCompany = inCompany;
+       const localSource = inSource;
+       // ...
+   };
+   ```
+
+4. **Zero Runtime Dependencies:**
+   Built entirely on standard Node.js built-ins. No intermediate proxy frameworks, no third-party HTTP libraries.

package/docs/execution-pipeline.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Execution Pipeline — Tally Simple</title>
+    <link rel="stylesheet" href="style.css">
+</head>
+<body>
+    <div class="container">
+        <nav class="doc-nav">
+            <a href="index.html">&larr; Documentation Hub</a>
+            <a href="execution-pipeline.md">View Markdown</a>
+        </nav>
+
+        <h1>Execution Pipeline</h1>
+        <p>When a consumer invokes an endpoint like <code>tally.masters.units.fetch("Mani9")</code>, the execution engine handles the request through a clean, 4-step pipeline.</p>
+
+        <h2>The Pipeline Flow</h2>
+        <pre><code>Invocation: tally.masters.units.fetch("Mani9")
+  │
+  ▼
+Step 1: validateCompany({ inCompany })
+  │  Ensures company is a non-empty string; returns trimmed name
+  ▼
+Step 2: getTdl({ inSource, inRoutePath })
+  │  Direct O(1) path lookup of TDL collection query from source.json
+  ▼
+Step 3: buildXmlBody({ inCompany, inTdl })
+  │  XML-escapes company name and injects into XML envelope template
+  ▼
+Step 4: postHttp({ inXmlBody })
+  │  Sends HTTP POST to Tally (http://localhost:9000) and returns XML text
+  ▼
+Caller receives raw XML string</code></pre>
+
+        <h2>The Four Narrative Steps</h2>
+
+        <h3>Step 1: Validate Company Name (<code>validateCompany.js</code>)</h3>
+        <p>Verifies that the supplied company name is a non-empty string. Throws early if invalid.</p>
+
+        <h3>Step 2: Direct TDL Lookup (<code>getTdl.js</code>)</h3>
+        <p>Instead of crawling or traversing the JSON structure, the endpoint is retrieved in a single line using path reduction.</p>
+
+        <h3>Step 3: XML Body Construction (<code>buildXmlBody.js</code>)</h3>
+        <p>Safely escapes XML special characters in the company name and substitutes <code>{company}</code> and <code>{collectionBody}</code> into the envelope template.</p>
+
+        <h3>Step 4: HTTP Transport (<code>postHttp.js</code>)</h3>
+        <p>Performs a standard <code>POST</code> request to <code>http://localhost:9000</code> with <code>Content-Type: text/xml</code>.</p>
+
+        <h2>The Coordinator (<code>index.js</code>)</h2>
+        <p>The main entry point reads like a 4-line story:</p>
+        <pre><code>const companyName = validateCompany({ inCompany: localCompany });
+const tdl = getTdl({ inSource: localSource, inRoutePath: localRoutePath });
+const xmlBody = buildXmlBody({ inCompany: companyName, inTdl: tdl });
+
+return await postHttp({ inXmlBody: xmlBody });</code></pre>
+
+        <h2>Architectural Highlights</h2>
+        <ul>
+            <li><strong>Direct Resolution:</strong> No recursion, no skipping keys, no runtime guessing.</li>
+            <li><strong>Single Responsibility:</strong> Each file does exactly one job.</li>
+            <li><strong>Strict Single Export:</strong> Every file exports <code>export default startFunc;</code>.</li>
+        </ul>
+
+        <footer>
+            <p>&copy; KeshavSoft. Distributed under the MIT License.</p>
+        </footer>
+    </div>
+</body>
+</html>

package/docs/execution-pipeline.md

@@ -0,0 +1,158 @@
+# Execution Pipeline
+
+[**View this document as HTML**](./execution-pipeline.html) · [**Documentation Hub**](./index.html)
+
+When a consumer invokes an endpoint like `tally.masters.units.fetch("Mani9")`, the execution engine handles the request through a clean, 4-step pipeline.
+
+---
+
+## The Pipeline Flow
+
+```text
+Invocation: tally.masters.units.fetch("Mani9")
+  │
+  ▼
+Step 1: validateCompany({ inCompany })
+  │  Ensures company is a non-empty string; returns trimmed name
+  ▼
+Step 2: getTdl({ inSource, inRoutePath })
+  │  Direct O(1) path lookup of TDL collection query from source.json
+  ▼
+Step 3: buildXmlBody({ inCompany, inTdl })
+  │  XML-escapes company name and injects into XML envelope template
+  ▼
+Step 4: postHttp({ inXmlBody })
+  │  Sends HTTP POST to Tally (http://localhost:9000) and returns XML text
+  ▼
+Caller receives raw XML string
+```
+
+---
+
+## The Four Narrative Steps
+
+Each step is encapsulated in its own focused module under `internal-working/execution/`:
+
+### Step 1: Validate Company Name (`validateCompany.js`)
+
+Verifies that the supplied company name is a non-empty string. Throws early if invalid:
+
+```javascript
+const startFunc = ({ inCompany }) => {
+    const localCompany = inCompany;
+
+    if (typeof localCompany !== "string" || !localCompany.trim()) {
+        throw new TypeError("Company name is required.");
+    }
+
+    return localCompany.trim();
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 2: Direct TDL Lookup (`getTdl.js`)
+
+Instead of crawling or traversing the JSON structure, the endpoint is retrieved in a single line using path reduction:
+
+```javascript
+const startFunc = ({ inSource, inRoutePath }) => {
+    const localSource = inSource;
+    const localRoutePath = inRoutePath;
+
+    const endpoint = localRoutePath
+        .split(".")
+        .reduce((current, key) => current?.[key], localSource);
+
+    return endpoint?.tdl;
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 3: XML Body Construction (`buildXmlBody.js`)
+
+Safely escapes XML special characters (`&`, `<`, `>`, `"`, `'`) in the company name and substitutes `{company}` and `{collectionBody}` into the envelope template:
+
+```javascript
+const startFunc = ({ inCompany, inTdl }) => {
+    const localCompany = inCompany;
+    const localTdl = inTdl;
+
+    return xmlEnvelopeTemplate
+        .replace("{company}", escapeXml(localCompany))
+        .replace("{collectionBody}", localTdl?.collection ?? "");
+};
+
+export default startFunc;
+```
+
+---
+
+### Step 4: HTTP Transport (`postHttp.js`)
+
+Performs a standard `POST` request to `http://localhost:9000` with `Content-Type: text/xml`:
+
+```javascript
+const url = "http://localhost:9000";
+const headers = { "Content-Type": "text/xml" };
+
+const startFunc = async ({ inXmlBody }) => {
+    const localXmlBody = inXmlBody;
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: headers,
+        body: localXmlBody
+    });
+
+    const responseText = await response.text();
+
+    if (!response.ok) {
+        throw new Error(`Tally request failed with HTTP ${response.status}: ${responseText}`);
+    }
+
+    return responseText;
+};
+
+export default startFunc;
+```
+
+---
+
+### The Coordinator (`index.js`)
+
+The main entry point reads like a 4-line story:
+
+```javascript
+import validateCompany from "./validateCompany.js";
+import getTdl from "./getTdl.js";
+import buildXmlBody from "./buildXmlBody.js";
+import postHttp from "./postHttp.js";
+
+const startFunc = async ({ inRoutePath, inCompany, inSource }) => {
+    const localRoutePath = inRoutePath;
+    const localCompany = inCompany;
+    const localSource = inSource;
+
+    const companyName = validateCompany({ inCompany: localCompany });
+    const tdl = getTdl({ inSource: localSource, inRoutePath: localRoutePath });
+    const xmlBody = buildXmlBody({ inCompany: companyName, inTdl: tdl });
+
+    return await postHttp({ inXmlBody: xmlBody });
+};
+
+export default startFunc;
+```
+
+---
+
+## Architectural Highlights
+
+- **Direct Resolution:** No recursion, no skipping keys, no runtime guessing.
+- **Single Responsibility:** Each file does exactly one job.
+- **Strict Single Export:** Every file exports `export default startFunc;`.