@keshavsoft/api-tree 2.0.0 → 6.1.0

package/README.md

@@ -1,62 +1,65 @@
-# @keshavsoft/api-tree
+# api-tree
 
-[![npm version](https://img.shields.io/npm/v/@keshavsoft/api-tree.svg)](https://www.npmjs.com/package/@keshavsoft/api-tree)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node.js CI](https://img.shields.io/badge/node-%3E%3D20.10-brightgreen.svg)]()
-
-> A declarative, ultra-lean routing engine that transforms **Source Schemas**, **API Paths**, and an **Executor** into a callable runtime API tree.
+A small, zero-dependency runtime API-tree builder.
 
 ---
 
-## 💡 The Problem & Philosophy
+## 💡 When Should You Use This?
 
-In modern modular architectures, APIs often end up bloated because **schema contracts**, **route definitions**, and **runtime execution** are tangled together.
+`@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.
 
-`@keshavsoft/api-tree` decouples these concerns completely:
+### The Problem It Solves
 
-$$\mathbf{Runtime\ Tree} = \underbrace{\mathbf{Source\ Schema}}_{\text{JSON Contract}} \;+\; \underbrace{\mathbf{API\ Paths}}_{\text{Dotted Routes}} \;+\; \underbrace{\mathbf{Executor}}_{\text{Execution Flavor}}$$
+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
 
-- **Domain-Agnostic**: Does not know about HTTP, XML, TDL, databases, or specific business logic.
-- **Single Responsibility**: Generates the navigable runtime object tree from contracts and leaves execution to your handler.
-- **Zero Dependencies**: Pure, modern ES module running at native speeds.
+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.
 
-```text
-┌─────────────────────────┐     ┌────────────────────────┐     ┌───────────────────────┐
-│       Source JSON       │  +  │       API Paths        │  +  │       Executor        │
-│ (Schema Specifications) │     │ (Dotted Route Strings) │     │ (Custom Handler Func) │
-└───────────┬─────────────┘     └───────────┬────────────┘     └──────────┬────────────┘
-            │                               │                             │
-            └───────────────────────┬───────┴─────────────────────────────┘
-                                    │
-                                    ▼
-                         @keshavsoft/api-tree
-                                    │
-                                    ▼
-                       Callable Runtime API Tree
-                     app.users.profile.fetch("123")
+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>...");
 ```
 
 ---
 
-## 📦 Installation
+## 🚀 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.
 
-```bash
-npm install @keshavsoft/api-tree
+```text
+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.
+
 ---
 
-## 🚀 Quick Start
+## Usage
 
 ```javascript
 import apiTree from "@keshavsoft/api-tree";
 
-// 1. Source JSON (the schema/metadata contract)
+// 1. Source JSON (the variable parameters)
 const source = {
     app: {
         users: {
             profile: {
-                fetch: { action: "fetch", resource: "User", timeout: 5000 }
+                fetch: { action: "fetch", resource: "User" }
             }
         }
     }
@@ -67,67 +70,27 @@ const apiPaths = [
     "app.users.profile.fetch"
 ];
 
-// 3. Executor Function
-const executor = async ({ inRoutePath, inParam, inLeafSpec }) => {
-    console.log(`Executing ${inRoutePath} for ID: ${inParam}`);
-    console.log("Leaf schema definition:", inLeafSpec);
-    return { id: inParam, name: "Alice", action: inLeafSpec.action };
+// 3. The Single Executor Function (handles 100% of execution)
+const executor = async ({ inRoutePath, inLeafSpec, inParam }) => {
+    return {
+        path: inRoutePath,
+        spec: inLeafSpec,
+        id: inParam
+    };
 };
 
 // 4. Build the callable tree
-const api = apiTree(source, apiPaths, executor);
+const app = apiTree(source, apiPaths, executor);
 
 // 5. Call your generated tree!
-const user = await api.users.profile.fetch("123");
-console.log(user);
-// => { id: "123", name: "Alice", action: "fetch" }
-```
-
----
-
-## ⚡ Key Features (v2)
-
-### 1. Pre-Resolved Leaf Specification (`inLeafSpec`)
-Your executor automatically receives the pre-resolved definition object directly from `source.json` under `inLeafSpec`. No need to write repetitive nested property access code!
-
-### 2. Intelligent Root Handling
-- **Single-Root Unwrapping**: When all paths share a common root namespace (e.g., `app.users.list`, `app.orders.create`), `api-tree` automatically unwraps the root so you call `api.users.list()` directly.
-- **Multi-Root Preservation**: When paths span multiple top-level domains (e.g., `users.list` and `orders.create`), `api-tree` automatically preserves all top-level roots (`api.users.list()` and `api.orders.create()`).
-- **Explicit Override**: You can pass `{ inUnwrapRoot: false }` to keep the root prefix intact.
-
-### 3. Dual Signature Support
-Supports both **positional** arguments and the **in-local named object** convention:
-
-```javascript
-// Positional
-const api = apiTree(source, apiPaths, executor, options);
-
-// Named Object
-const api = apiTree({
-    inSource: source,
-    inApiPaths: apiPaths,
-    inExecutor: executor,
-    inOptions: { inUnwrapRoot: false }
-});
-```
-
-### 4. Callable Hybrid Branches
-If a path is both a callable node and has child branches (e.g. `api.users` and `api.users.profile`), `api-tree` attaches child branches directly onto the function:
-```javascript
-await api.users();         // Callable root!
-await api.users.profile(); // Child leaf also callable!
+const result = await app.users.profile.fetch("123");
 ```
 
 ---
 
-## 📖 Execution Context Reference
-
-Whenever an attached leaf function is invoked:
-```javascript
-await api.users.profile.fetch("param1", "extraArg1", "extraArg2");
-```
+## Execution Context
 
-Your `executor` receives a single, standardized context object:
+When an attached leaf function is invoked, your `executor` receives a single, standardized context object:
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
@@ -140,61 +103,16 @@ Your `executor` receives a single, standardized context object:
 
 ---
 
-## 🛡️ Input Validation & Error Handling
+## Validation & Guarantees
 
 `@keshavsoft/api-tree` performs strict pre-flight validation to catch contract misconfigurations early:
 
-- **`source`**: Must be a non-null plain JSON object (throws `TypeError: source must be a JSON object.`).
-- **`apiPaths`**: Must be an array of non-empty strings without empty segments (e.g., `"users..fetch"` or `"users."` throws `TypeError`).
-- **`executor`**: Must be a valid callable function (throws `TypeError: executor must be a function.`).
-
----
-
-## 🌍 Real-World Architecture Examples
-
-### Example A: Decoupling TallyPrime Runtimes
-```javascript
-import apiTree from "@keshavsoft/api-tree";
-import { source, apiPaths } from "tally-spec";
-import tallyXmlExecutor from "./tallyXmlExecutor.js";
-
-// Generates app.masters.unit.all(), app.company.fetch(), etc.
-const tally = apiTree(source, apiPaths, tallyXmlExecutor);
-const units = await tally.masters.unit.all();
-```
-
-### Example B: Dynamic HTTP / REST Client
-```javascript
-import apiTree from "@keshavsoft/api-tree";
-
-const endpoints = {
-    api: {
-        v1: {
-            users: { get: { method: "GET", url: "/api/v1/users" } }
-        }
-    }
-};
-
-const client = apiTree(endpoints, ["api.v1.users.get"], async ({ inLeafSpec, inParam }) => {
-    const res = await fetch(`${inLeafSpec.url}/${inParam}`, { method: inLeafSpec.method });
-    return res.json();
-});
-
-const user = await client.v1.users.get(42);
-```
-
----
-
-## 🧪 Testing
-
-The package includes a comprehensive test suite using Node's native test runner:
-
-```bash
-npm test
-```
+- **`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.
 
 ---
 
-## 📄 License
+## License
 
 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>