@keshavsoft/api-tree 1.0.0 → 6.1.0

package/README.md

@@ -1,93 +1,118 @@
-# @keshavsoft/api-tree
+# api-tree
 
-A small runtime API-tree builder.
+A small, zero-dependency runtime API-tree builder.
 
-`@keshavsoft/api-tree` does one job: it takes **source JSON**, **API paths**, and an **executor**, then returns a callable runtime tree.
+---
+
+## 💡 When Should You Use This?
+
+`@keshavsoft/api-tree` is built specifically for systems where **most of the execution logic is identical** and handled by a **single core function**, while only a few parameters vary from endpoint to endpoint.
+
+### The Problem It Solves
+
+Consider an SDK or API client with 20, 50, or 200 endpoints. In most codebases, **95% of the work is identical across all of them**:
+- Sending an HTTP POST or XML payload
+- Setting headers and managing network timeouts
+- Parsing envelopes and extracting data
+
+The only thing that actually changes between `app.masters.unit.all()` and `app.company.fetch()` are a few variables: a resource name, a TDL query string, or a URL parameter.
+
+Yet without `api-tree`, developers write dozens or hundreds of repetitive, hand-crafted wrapper functions just to call the exact same underlying function with different arguments:
+
+```javascript
+// ❌ The Anti-Pattern: 100 repetitive functions doing the exact same thing
+export const getUnits = () => dispatchTally("<TYPE>Unit</TYPE>...");
+export const getLedgers = () => dispatchTally("<TYPE>Ledger</TYPE>...");
+export const getCompany = () => dispatchTally("<TYPE>Company</TYPE>...");
+```
+
+---
+
+## 🚀 The api-tree Pattern: 1 Engine + Variable JSON
+
+Instead of writing endless boilerplate wrappers, you separate concerns into three clean parts:
+
+1. **One Single Executor**: You write your execution muscle exactly once. It knows how to send the request and handle responses.
+2. **Variable Data in JSON (`source.json`)**: You define only the things that change (TDL queries, actions, resources, URLs) in a declarative schema.
+3. **The Navigation List (`api.json`)**: You list the allowed routes in a flat, readable array.
 
 ```text
-source JSON
-     +
-API paths
-     +
-executor
-     ↓
-  api-tree
-     ↓
-callable API
+source JSON (Variables)  +  API paths (Routes)  +  executor (Single Function)
+                                ↓
+                             api-tree
+                                ↓
+                      Callable Runtime Tree
+                    app.masters.unit.all()
 ```
 
+When a new endpoint is needed, you don't write new JavaScript wrapper functions, manage imports, or test routing logic. **You simply add one entry to your JSON file.** `@keshavsoft/api-tree` binds your single executor to that new definition and instantly exposes it on the callable tree.
+
+---
+
 ## Usage
 
-```js
+```javascript
 import apiTree from "@keshavsoft/api-tree";
 
+// 1. Source JSON (the variable parameters)
 const source = {
     app: {
         users: {
             profile: {
-                fetch: { action: "fetch", resource: "users" }
+                fetch: { action: "fetch", resource: "User" }
             }
         }
     }
 };
 
+// 2. Allowable API Paths
 const apiPaths = [
     "app.users.profile.fetch"
 ];
 
-const executor = async ({ inRoutePath, inParam, inSource }) => {
+// 3. The Single Executor Function (handles 100% of execution)
+const executor = async ({ inRoutePath, inLeafSpec, inParam }) => {
     return {
         path: inRoutePath,
-        param: inParam,
-        spec: inSource.app.users.profile.fetch
+        spec: inLeafSpec,
+        id: inParam
     };
 };
 
-const api = apiTree(source, apiPaths, executor);
+// 4. Build the callable tree
+const app = apiTree(source, apiPaths, executor);
 
-const result = await api.users.profile.fetch("123");
+// 5. Call your generated tree!
+const result = await app.users.profile.fetch("123");
 ```
 
-## Contract
+---
 
-`apiTree(source, apiPaths, executor)` accepts exactly three responsibilities:
+## Execution Context
 
-1. **source** — the domain/source JSON object.
-2. **apiPaths** — a flat array of API paths such as `app.users.profile.fetch`.
-3. **executor** — the function that decides what the selected operation actually does.
+When an attached leaf function is invoked, your `executor` receives a single, standardized context object:
 
-`@keshavsoft/api-tree` does not know Tally, XML, HTTP, databases, or business rules.
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `inRoutePath` | `string` | The full dot-notation route path (e.g. `"app.users.profile.fetch"`). |
+| `inParam` | `any` | The primary argument passed to the leaf method. |
+| `inArgs` | `any[]` | Array of all additional arguments passed beyond `inParam`. |
+| `inLeafSpec` | `object \| undefined` | The resolved leaf definition object found in `source.json`. |
+| `inSource` | `object` | The complete raw `source` schema object. |
+| `inPathSegments` | `string[]` | Array of path segments (e.g. `["app", "users", "profile", "fetch"]`). |
 
-## Validation
+---
 
-The public entry point checks:
+## Validation & Guarantees
 
-- `source` is a JSON-compatible object.
-- `apiPaths` is an array.
-- every API path is a string.
-- `executor` is a function.
+`@keshavsoft/api-tree` performs strict pre-flight validation to catch contract misconfigurations early:
 
-Invalid input produces a clear `TypeError` before the tree is built.
+- **`source`**: Must be a non-null plain JSON object.
+- **`apiPaths`**: Must be an array of non-empty strings with valid segments.
+- **`executor`**: Must be a valid callable function.
 
-## Blueprint examples
+---
 
-The package includes `src/v1/blueprint/source.json` and `src/v1/blueprint/api.json` as small reference examples. They are documentation/blueprint material, not hidden runtime configuration.
-
-## Architecture
-
-```text
-Domain repository
-    │
-    ├── source.json
-    ├── api.json
-    └── execution code
-             │
-             │ source + paths + executor
-             ▼
-        @keshavsoft/api-tree
-             │
-             ▼
-      callable runtime API
-```
+## License
 
-The domain repository owns the meaning and execution. `@keshavsoft/api-tree` only creates the navigable runtime surface.
+MIT © [KeshavSoft](https://github.com/keshavsoft)

package/docs/api.html

@@ -0,0 +1,123 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>api-tree — API Reference</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-brand">
+        <a href="index.html" class="brand-title">api-tree</a>
+        <div class="brand-subtitle">v2.0.0 &bull; KeshavSoft</div>
+      </div>
+      <div class="nav-label">Documentation</div>
+      <ul class="nav-list">
+        <li><a href="index.html" class="nav-link">The Story</a></li>
+        <li><a href="how-it-works.html" class="nav-link">How It Works</a></li>
+        <li><a href="api.html" class="nav-link active">API Reference</a></li>
+        <li><a href="examples.html" class="nav-link">Examples</a></li>
+        <li><a href="validation.html" class="nav-link">Guarantees</a></li>
+      </ul>
+      <div class="sidebar-footer">
+        <a href="https://github.com/keshavsoft/api-tree" target="_blank" rel="noopener">GitHub Repository &rarr;</a>
+      </div>
+    </aside>
+
+    <main class="content">
+      <h1>API Reference</h1>
+      <div class="lead">Complete contract specifications and execution context reference.</div>
+
+      <h2>Function Signatures</h2>
+      <p><code>@keshavsoft/api-tree</code> supports both positional arguments and the named object convention:</p>
+
+      <h3>Positional Call</h3>
+      <pre><code>import apiTree from "@keshavsoft/api-tree";
+
+const api = apiTree(source, apiPaths, executor, options);</code></pre>
+
+      <h3>Named Object Call</h3>
+      <pre><code>import apiTree from "@keshavsoft/api-tree";
+
+const api = apiTree({
+    inSource: source,
+    inApiPaths: apiPaths,
+    inExecutor: executor,
+    inOptions: { inUnwrapRoot: false }
+});</code></pre>
+
+      <h2>Execution Context Reference</h2>
+      <p>Whenever an attached leaf method is called (e.g. <code>app.users.profile.fetch("123", "extra")</code>), your executor receives a single standardized context object:</p>
+
+      <table>
+        <thead>
+          <tr>
+            <th>Property</th>
+            <th>Type</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>inRoutePath</code></td>
+            <td><code>string</code></td>
+            <td>The full dot-notation route path (e.g. <code>"app.users.profile.fetch"</code>).</td>
+          </tr>
+          <tr>
+            <td><code>inParam</code></td>
+            <td><code>any</code></td>
+            <td>The primary argument passed to the leaf method.</td>
+          </tr>
+          <tr>
+            <td><code>inArgs</code></td>
+            <td><code>any[]</code></td>
+            <td>Array containing all subsequent arguments passed after <code>inParam</code>.</td>
+          </tr>
+          <tr>
+            <td><code>inLeafSpec</code></td>
+            <td><code>object | undefined</code></td>
+            <td>The resolved leaf definition object found in <code>source.json</code>.</td>
+          </tr>
+          <tr>
+            <td><code>inSource</code></td>
+            <td><code>object</code></td>
+            <td>The complete raw <code>source</code> schema object.</td>
+          </tr>
+          <tr>
+            <td><code>inPathSegments</code></td>
+            <td><code>string[]</code></td>
+            <td>Array of individual path segments (e.g. <code>["app", "users", "profile", "fetch"]</code>).</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <h2>Options (<code>inOptions</code>)</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>Option</th>
+            <th>Type</th>
+            <th>Default</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>inUnwrapRoot</code></td>
+            <td><code>boolean</code></td>
+            <td><code>true</code></td>
+            <td>When <code>true</code> and all paths share a common root segment, unwraps the root. Set to <code>false</code> to preserve the full root namespace.</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <div class="page-nav">
+        <a href="how-it-works.html">&larr; How It Works</a>
+        <a href="examples.html">Next: Examples &rarr;</a>
+      </div>
+    </main>
+  </div>
+</body>
+</html>

package/docs/examples.html

@@ -0,0 +1,100 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>api-tree — Examples</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-brand">
+        <a href="index.html" class="brand-title">api-tree</a>
+        <div class="brand-subtitle">v2.0.0 &bull; KeshavSoft</div>
+      </div>
+      <div class="nav-label">Documentation</div>
+      <ul class="nav-list">
+        <li><a href="index.html" class="nav-link">The Story</a></li>
+        <li><a href="how-it-works.html" class="nav-link">How It Works</a></li>
+        <li><a href="api.html" class="nav-link">API Reference</a></li>
+        <li><a href="examples.html" class="nav-link active">Examples</a></li>
+        <li><a href="validation.html" class="nav-link">Guarantees</a></li>
+      </ul>
+      <div class="sidebar-footer">
+        <a href="https://github.com/keshavsoft/api-tree" target="_blank" rel="noopener">GitHub Repository &rarr;</a>
+      </div>
+    </aside>
+
+    <main class="content">
+      <h1>Examples</h1>
+      <div class="lead">Practical implementations across different ecosystems.</div>
+
+      <h2>1. Decoupling TallyPrime Runtimes</h2>
+      <p>In the KeshavSoft Tally ecosystem, <code>tally-spec</code> owns the data contracts, <code>@keshavsoft/api-tree</code> builds the navigable tree, and <code>tally-xml-tdl</code> executes raw XML over HTTP:</p>
+      <pre><code>import apiTree from "@keshavsoft/api-tree";
+import { source, apiPaths } from "tally-spec";
+import tallyXmlExecutor from "./engine/execution/index.js";
+
+// Builds callable tree: app.masters.unit.all(), app.company.fetch()
+const app = apiTree(source, apiPaths, tallyXmlExecutor);
+
+// Fetch live units directly from TallyPrime
+const units = await app.masters.unit.all();
+console.log(units);</code></pre>
+
+      <h2>2. Dynamic REST / HTTP Client</h2>
+      <p>Instead of manually writing HTTP client SDKs for every microservice, generate one on the fly from an endpoint schema:</p>
+      <pre><code>import apiTree from "@keshavsoft/api-tree";
+
+const endpoints = {
+    api: {
+        v1: {
+            users: {
+                get: { method: "GET", url: "https://api.example.com/users" }
+            }
+        }
+    }
+};
+
+const apiPaths = ["api.v1.users.get"];
+
+const httpExecutor = async ({ inLeafSpec, inParam }) => {
+    const response = await fetch(`${inLeafSpec.url}/${inParam}`, {
+        method: inLeafSpec.method
+    });
+    return response.json();
+};
+
+const client = apiTree(endpoints, apiPaths, httpExecutor);
+
+// Invokes GET https://api.example.com/users/42
+const user = await client.v1.users.get(42);</code></pre>
+
+      <h2>3. CLI Command Dispatcher</h2>
+      <p>Map command lines directly to business logic handlers using path notation:</p>
+      <pre><code>import apiTree from "@keshavsoft/api-tree";
+
+const commands = {
+    cli: {
+        auth: {
+            login: { description: "Authenticate user session" },
+            logout: { description: "Terminate session" }
+        }
+    }
+};
+
+const cli = apiTree(commands, ["cli.auth.login", "cli.auth.logout"], async ({ inRoutePath, inParam }) => {
+    console.log(`Executing ${inRoutePath} with credentials:`, inParam);
+});
+
+await cli.auth.login({ username: "admin" });</code></pre>
+
+      <div class="page-nav">
+        <a href="api.html">&larr; API Reference</a>
+        <a href="validation.html">Next: Guarantees &rarr;</a>
+      </div>
+    </main>
+  </div>
+</body>
+</html>

package/docs/how-it-works.html

@@ -0,0 +1,69 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>api-tree — How It Works</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-brand">
+        <a href="index.html" class="brand-title">api-tree</a>
+        <div class="brand-subtitle">v2.0.0 &bull; KeshavSoft</div>
+      </div>
+      <div class="nav-label">Documentation</div>
+      <ul class="nav-list">
+        <li><a href="index.html" class="nav-link">The Story</a></li>
+        <li><a href="how-it-works.html" class="nav-link active">How It Works</a></li>
+        <li><a href="api.html" class="nav-link">API Reference</a></li>
+        <li><a href="examples.html" class="nav-link">Examples</a></li>
+        <li><a href="validation.html" class="nav-link">Guarantees</a></li>
+      </ul>
+      <div class="sidebar-footer">
+        <a href="https://github.com/keshavsoft/api-tree" target="_blank" rel="noopener">GitHub Repository &rarr;</a>
+      </div>
+    </aside>
+
+    <main class="content">
+      <h1>How It Works</h1>
+      <div class="lead">Under the hood of the dynamic runtime routing engine.</div>
+
+      <h2>1. The Assembly Pipeline</h2>
+      <p>When you call <code>apiTree(source, apiPaths, executor)</code>, the engine performs three synchronous steps:</p>
+      <ol>
+        <li><strong>Pre-Flight Validation</strong>: Ensures that <code>source</code> is a valid plain object, <code>apiPaths</code> contains valid non-empty string segments, and <code>executor</code> is a callable function.</li>
+        <li><strong>Tree Branching</strong>: Splits each dotted path into segments (e.g. <code>["app", "users", "profile", "fetch"]</code>) and recursively builds nested JavaScript objects.</li>
+        <li><strong>Leaf Handler Attachment</strong>: The final segment becomes an async callable leaf function wired to your executor.</li>
+      </ol>
+
+      <h2>2. Pre-Resolved Leaf Specifications (<code>inLeafSpec</code>)</h2>
+      <p>In older patterns, executors had to manually traverse <code>inSource</code> to locate their definition. In <code>v2</code>, <code>api-tree</code> automatically resolves the leaf object from <code>source.json</code> during tree construction:</p>
+      <pre><code>const executor = async ({ inRoutePath, inLeafSpec, inParam }) => {
+    // inLeafSpec is already extracted from source:
+    // { action: "fetch", resource: "User", timeout: 5000 }
+    console.log(inLeafSpec.resource);
+};</code></pre>
+
+      <h2>3. Intelligent Root Handling</h2>
+      <p>Depending on your architecture, your API paths may belong to a single domain or multiple domains:</p>
+      <ul>
+        <li><strong>Single-Root Auto-Unwrapping</strong>: When all paths start with the same root (e.g. <code>["app.users.fetch", "app.reports.fetch"]</code>), <code>api-tree</code> automatically unwraps <code>app</code>, giving you clean access like <code>api.users.fetch()</code>.</li>
+        <li><strong>Multi-Root Domain Preservation</strong>: When paths belong to multiple roots (e.g. <code>["users.list", "orders.create"]</code>), <code>api-tree</code> preserves both roots (<code>api.users.list()</code> and <code>api.orders.create()</code>).</li>
+        <li><strong>Explicit Configuration</strong>: You can pass <code>{ inUnwrapRoot: false }</code> to force keeping the root prefix intact.</li>
+      </ul>
+
+      <h2>4. Hybrid Callable Branches</h2>
+      <p>In JavaScript, functions are objects. If your schema defines both a parent route and a child route (such as <code>api.users</code> and <code>api.users.profile</code>), <code>api-tree</code> seamlessly attaches the child branch onto the parent function:</p>
+      <pre><code>await api.users();         // Calls the parent handler
+await api.users.profile(); // Calls the child handler</code></pre>
+
+      <div class="page-nav">
+        <a href="index.html">&larr; The Story</a>
+        <a href="api.html">Next: API Reference &rarr;</a>
+      </div>
+    </main>
+  </div>
+</body>
+</html>

package/docs/index.html

@@ -1,26 +1,95 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<title>api-tree</title>
-<style>body{max-width:850px;margin:50px auto;padding:0 20px;font:16px/1.6 system-ui,sans-serif}code,pre{background:#f3f3f3;padding:3px 6px;border-radius:4px}pre{padding:16px;overflow:auto}h1{margin-bottom:4px}.muted{color:#666}</style>
-</head>
-<body>
-<h1>api-tree</h1>
-<p class="muted">A small runtime API-tree builder.</p>
-<h2>The story</h2>
-<p>A domain repository already knows its structure and its execution logic. api-tree does not replace that logic. It only turns a flat list of API paths into a callable runtime tree.</p>
-<pre>source JSON + API paths + executor
-                 ↓
-              api-tree
-                 ↓
-       app.users.profile.fetch()</pre>
-<h2>Three inputs</h2>
-<ul><li><b>source</b> — source/domain JSON</li><li><b>apiPaths</b> — flat array of dotted paths</li><li><b>executor</b> — external function that performs the operation</li></ul>
-<h2>Why separate it?</h2>
-<p>The route mechanism is reusable. Tally XML, Tally JSON, Tally Simple, or another domain can keep its own JSON and execution code while sharing the same runtime API-tree mechanism.</p>
-<h2>Validation</h2>
-<p>The public function rejects invalid source, API-path arrays, and executors with clear TypeErrors.</p>
-</body>
-</html>
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>api-tree — The Situation &amp; Solution</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-brand">
+        <a href="index.html" class="brand-title">api-tree</a>
+        <div class="brand-subtitle">v2.0.0 &bull; KeshavSoft</div>
+      </div>
+      <div class="nav-label">Documentation</div>
+      <ul class="nav-list">
+        <li><a href="index.html" class="nav-link active">The Story</a></li>
+        <li><a href="how-it-works.html" class="nav-link">How It Works</a></li>
+        <li><a href="api.html" class="nav-link">API Reference</a></li>
+        <li><a href="examples.html" class="nav-link">Examples</a></li>
+        <li><a href="validation.html" class="nav-link">Guarantees</a></li>
+      </ul>
+      <div class="sidebar-footer">
+        <a href="https://github.com/keshavsoft/api-tree" target="_blank" rel="noopener">GitHub Repository &rarr;</a>
+      </div>
+    </aside>
+
+    <main class="content">
+      <h1>api-tree</h1>
+      <div class="lead">A small, zero-dependency runtime API-tree builder.</div>
+
+      <p>We had a situation in our codebase: we were writing function after function just to expose different endpoints.</p>
+
+      <p>Yet under the hood, every single one of those functions was doing the exact same thing: calling one core execution function. The only difference from endpoint to endpoint was a few variables—like a resource name, an action, or a query string.</p>
+
+      <p>Writing dozens of nearly identical wrapper functions created boilerplate, duplicated code, and made maintenance tedious.</p>
+
+      <h2>What We Did</h2>
+
+      <p>We separated the parts that never change from the parts that do:</p>
+
+      <ul>
+        <li><strong>The Single Function (Executor)</strong>: The core execution engine is written exactly once. It handles the network requests, headers, and response parsing.</li>
+        <li><strong>The Variables (source.json)</strong>: The parameters that vary per endpoint are moved into a clean JSON contract.</li>
+        <li><strong>The Routes (api.json)</strong>: The allowed endpoints are defined in a flat array of dot-notation paths.</li>
+      </ul>
+
+      <p><strong>api-tree</strong> marries the single executor function with the variable JSON, dynamically building the callable dot-notation tree at runtime.</p>
+
+      <h2>The Code</h2>
+
+      <p>Instead of writing endless wrapper functions like this:</p>
+
+<pre><code>// The repetitive pattern
+export const getUnits = () => execute({ resource: "Unit" });
+export const getLedgers = () => execute({ resource: "Ledger" });
+export const getCompany = () => execute({ resource: "Company" });</code></pre>
+
+      <p>You write your executor once, put your variables in JSON, and let <code>api-tree</code> generate the surface:</p>
+
+<pre><code>import apiTree from "@keshavsoft/api-tree";
+
+// 1. Only the variables
+const source = {
+    app: {
+        masters: {
+            unit: { all: { resource: "Unit", action: "fetch" } }
+        }
+    }
+};
+
+const apiPaths = ["app.masters.unit.all"];
+
+// 2. The single executor function
+const execute = async ({ inLeafSpec, inParam }) => {
+    return await dispatch(inLeafSpec.resource, inParam);
+};
+
+// 3. Build the callable tree
+const app = apiTree(source, apiPaths, execute);
+
+// 4. Call naturally
+const units = await app.masters.unit.all();</code></pre>
+
+      <p>When you need a new endpoint tomorrow, you do not write a new JavaScript function. You simply add a new entry to your JSON file, and it is immediately available on the tree.</p>
+
+      <div class="page-nav">
+        <span></span>
+        <a href="how-it-works.html">Next: How It Works &rarr;</a>
+      </div>
+    </main>
+  </div>
+</body>
+</html>