@keshavsoft/api-tree 2.0.0 → 6.1.0

package/docs/index.html

@@ -3,296 +3,93 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>@keshavsoft/api-tree — Declarative Runtime API Tree Builder</title>
-  <link rel="preconnect" href="https://fonts.googleapis.com">
-  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=Inter:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
-  <style>
-    :root {
-      --bg: #0b0f19;
-      --card-bg: #111827;
-      --card-border: #1f2937;
-      --text: #f3f4f6;
-      --text-muted: #9ca3af;
-      --primary: #3b82f6;
-      --primary-light: #60a5fa;
-      --accent: #10b981;
-      --code-bg: #030712;
-      --border: #374151;
-    }
-
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-    body {
-      font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-      background: var(--bg);
-      color: var(--text);
-      line-height: 1.6;
-      padding: 0 1.5rem 4rem;
-    }
-
-    .container {
-      max-width: 900px;
-      margin: 0 auto;
-    }
-
-    header {
-      padding: 4rem 0 2.5rem;
-      border-bottom: 1px solid var(--border);
-      margin-bottom: 3rem;
-    }
-
-    .badge-bar {
-      display: flex;
-      gap: 0.5rem;
-      margin-bottom: 1rem;
-      flex-wrap: wrap;
-    }
-
-    .badge {
-      display: inline-flex;
-      align-items: center;
-      padding: 0.25rem 0.65rem;
-      border-radius: 9999px;
-      font-size: 0.75rem;
-      font-weight: 600;
-      background: #1e293b;
-      color: #94a3b8;
-      border: 1px solid #334155;
-    }
-    .badge.green { background: #064e3b; color: #34d399; border-color: #059669; }
-    .badge.blue { background: #1e3a8a; color: #93c5fd; border-color: #2563eb; }
-
-    h1 {
-      font-size: 2.75rem;
-      font-weight: 800;
-      letter-spacing: -0.03em;
-      margin-bottom: 0.75rem;
-      background: linear-gradient(135deg, #ffffff 0%, #93c5fd 100%);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-    }
-
-    .tagline {
-      font-size: 1.25rem;
-      color: var(--text-muted);
-      max-width: 700px;
-    }
-
-    h2 {
-      font-size: 1.75rem;
-      font-weight: 700;
-      margin: 2.5rem 0 1rem;
-      color: #ffffff;
-      border-bottom: 1px solid var(--border);
-      padding-bottom: 0.5rem;
-    }
-
-    h3 {
-      font-size: 1.25rem;
-      font-weight: 600;
-      margin: 1.5rem 0 0.75rem;
-      color: var(--primary-light);
-    }
-
-    p, ul {
-      color: #d1d5db;
-      margin-bottom: 1.25rem;
-    }
-
-    ul { padding-left: 1.5rem; }
-    li { margin-bottom: 0.5rem; }
-
-    .formula-box {
-      background: linear-gradient(180deg, rgba(30, 58, 138, 0.2) 0%, rgba(17, 24, 39, 0.6) 100%);
-      border: 1px solid #2563eb;
-      border-radius: 12px;
-      padding: 1.5rem;
-      margin: 2rem 0;
-      text-align: center;
-      font-size: 1.15rem;
-      font-weight: 600;
-      color: #bfdbfe;
-    }
-
-    pre {
-      background: var(--code-bg);
-      border: 1px solid var(--card-border);
-      border-radius: 8px;
-      padding: 1.25rem;
-      overflow-x: auto;
-      font-family: 'Fira Code', monospace;
-      font-size: 0.9rem;
-      margin-bottom: 1.5rem;
-    }
-
-    code {
-      font-family: 'Fira Code', monospace;
-      color: #93c5fd;
-    }
+  <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>
 
-    pre code {
-      color: #e2e8f0;
-    }
+    <main class="content">
+      <h1>api-tree</h1>
+      <div class="lead">A small, zero-dependency runtime API-tree builder.</div>
 
-    .grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
-      gap: 1.25rem;
-      margin: 1.5rem 0;
-    }
+      <p>We had a situation in our codebase: we were writing function after function just to expose different endpoints.</p>
 
-    .card {
-      background: var(--card-bg);
-      border: 1px solid var(--card-border);
-      border-radius: 10px;
-      padding: 1.25rem;
-    }
+      <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>
 
-    .card h4 {
-      color: #60a5fa;
-      margin-bottom: 0.5rem;
-      font-size: 1.05rem;
-    }
+      <p>Writing dozens of nearly identical wrapper functions created boilerplate, duplicated code, and made maintenance tedious.</p>
 
-    .card p {
-      color: var(--text-muted);
-      font-size: 0.9rem;
-      margin-bottom: 0;
-    }
+      <h2>What We Did</h2>
 
-    table {
-      width: 100%;
-      border-collapse: collapse;
-      margin: 1.5rem 0;
-    }
+      <p>We separated the parts that never change from the parts that do:</p>
 
-    th, td {
-      border: 1px solid var(--border);
-      padding: 0.75rem 1rem;
-      text-align: left;
-      font-size: 0.9rem;
-    }
+      <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>
 
-    th {
-      background: var(--card-bg);
-      color: #ffffff;
-    }
+      <p><strong>api-tree</strong> marries the single executor function with the variable JSON, dynamically building the callable dot-notation tree at runtime.</p>
 
-    td {
-      background: rgba(17, 24, 39, 0.4);
-    }
+      <h2>The Code</h2>
 
-    footer {
-      margin-top: 4rem;
-      padding-top: 2rem;
-      border-top: 1px solid var(--border);
-      color: var(--text-muted);
-      font-size: 0.85rem;
-      text-align: center;
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <header>
-      <div class="badge-bar">
-        <span class="badge blue">@keshavsoft/api-tree</span>
-        <span class="badge green">v2.0.0</span>
-        <span class="badge">Zero Dependencies</span>
-        <span class="badge">Node &gt;= 20.10</span>
-      </div>
-      <h1>@keshavsoft/api-tree</h1>
-      <p class="tagline">A declarative, ultra-lean routing engine that turns source schemas, API paths, and an external executor into a callable runtime API tree.</p>
-    </header>
+      <p>Instead of writing endless wrapper functions like this:</p>
 
-    <div class="formula-box">
-      Runtime Tree = Source Schema (JSON) + API Paths (Routes) + Custom Executor
-    </div>
+<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>
 
-    <h2>Core Architecture</h2>
-    <p><code>@keshavsoft/api-tree</code> decouples specification contracts from runtime execution:</p>
-    <div class="grid">
-      <div class="card">
-        <h4>1. Source Schema</h4>
-        <p>The single source of truth containing leaf specifications, metadata, and domain contracts.</p>
-      </div>
-      <div class="card">
-        <h4>2. API Paths</h4>
-        <p>A flat, declarative array of dotted routes (e.g. <code>app.users.profile.fetch</code>).</p>
-      </div>
-      <div class="card">
-        <h4>3. Custom Executor</h4>
-        <p>A pure execution handler that receives standardized context and executes the operation.</p>
-      </div>
-    </div>
+      <p>You write your executor once, put your variables in JSON, and let <code>api-tree</code> generate the surface:</p>
 
-    <h2>Quick Start</h2>
-    <pre><code>import apiTree from "@keshavsoft/api-tree";
+<pre><code>import apiTree from "@keshavsoft/api-tree";
 
+// 1. Only the variables
 const source = {
-  app: {
-    users: {
-      profile: {
-        fetch: { action: "fetch", resource: "User" }
-      }
+    app: {
+        masters: {
+            unit: { all: { resource: "Unit", action: "fetch" } }
+        }
     }
-  }
 };
 
-const apiPaths = ["app.users.profile.fetch"];
+const apiPaths = ["app.masters.unit.all"];
 
-const executor = async ({ inRoutePath, inLeafSpec, inParam }) => {
-  return { id: inParam, action: inLeafSpec.action };
+// 2. The single executor function
+const execute = async ({ inLeafSpec, inParam }) => {
+    return await dispatch(inLeafSpec.resource, inParam);
 };
 
-const api = apiTree(source, apiPaths, executor);
+// 3. Build the callable tree
+const app = apiTree(source, apiPaths, execute);
 
-// Call the navigable tree!
-const result = await api.users.profile.fetch("123");
-console.log(result); // { id: "123", action: "fetch" }</code></pre>
+// 4. Call naturally
+const units = await app.masters.unit.all();</code></pre>
 
-    <h2>Execution Context</h2>
-    <p>When an attached leaf function is invoked, your executor receives a rich 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>string</td>
-          <td>The full dot-notation route path.</td>
-        </tr>
-        <tr>
-          <td><code>inParam</code></td>
-          <td>any</td>
-          <td>First argument passed to the leaf.</td>
-        </tr>
-        <tr>
-          <td><code>inArgs</code></td>
-          <td>any[]</td>
-          <td>Array of all additional arguments.</td>
-        </tr>
-        <tr>
-          <td><code>inLeafSpec</code></td>
-          <td>object</td>
-          <td>Pre-resolved leaf definition from source.json.</td>
-        </tr>
-        <tr>
-          <td><code>inSource</code></td>
-          <td>object</td>
-          <td>The raw source schema object.</td>
-        </tr>
-      </tbody>
-    </table>
+      <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>
 
-    <footer>
-      <p>MIT License &copy; KeshavSoft. Distributed via npm.</p>
-    </footer>
+      <div class="page-nav">
+        <span></span>
+        <a href="how-it-works.html">Next: How It Works &rarr;</a>
+      </div>
+    </main>
   </div>
 </body>
 </html>

package/docs/style.css

@@ -0,0 +1,272 @@
+:root {
+  --bg: #0d1117;
+  --sidebar-bg: #090d13;
+  --card-bg: #161b22;
+  --border: #30363d;
+  --text: #e6edf3;
+  --text-muted: #8b949e;
+  --accent: #58a6ff;
+  --accent-hover: #79c0ff;
+  --active-bg: rgba(56, 139, 253, 0.15);
+  --code-bg: #161b22;
+  --callout-border: #388bfd;
+}
+
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  background: var(--bg);
+  color: var(--text);
+  line-height: 1.7;
+  min-height: 100vh;
+}
+
+.layout {
+  display: flex;
+  min-height: 100vh;
+}
+
+/* Sidebar Navigation (Left Side) */
+.sidebar {
+  width: 250px;
+  background: var(--sidebar-bg);
+  border-right: 1px solid var(--border);
+  padding: 36px 20px 40px;
+  flex-shrink: 0;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.sidebar-brand {
+  margin-bottom: 32px;
+}
+
+.brand-title {
+  font-size: 1.25rem;
+  font-weight: 700;
+  color: #ffffff;
+  text-decoration: none;
+  display: block;
+  letter-spacing: -0.01em;
+}
+
+.brand-subtitle {
+  font-size: 0.8rem;
+  color: var(--text-muted);
+  margin-top: 4px;
+}
+
+.nav-label {
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted);
+  font-weight: 600;
+  margin-bottom: 12px;
+}
+
+.nav-list {
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: auto;
+}
+
+.nav-link {
+  display: flex;
+  align-items: center;
+  padding: 8px 12px;
+  border-radius: 6px;
+  font-size: 0.92rem;
+  color: var(--text-muted);
+  text-decoration: none;
+  transition: all 0.15s ease;
+}
+
+.nav-link:hover {
+  color: var(--text);
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.nav-link.active {
+  color: var(--accent);
+  background: var(--active-bg);
+  font-weight: 600;
+}
+
+.sidebar-footer {
+  padding-top: 24px;
+  border-top: 1px solid var(--border);
+  font-size: 0.8rem;
+  color: var(--text-muted);
+}
+
+.sidebar-footer a {
+  color: var(--text-muted);
+  text-decoration: none;
+}
+
+.sidebar-footer a:hover {
+  color: var(--accent);
+}
+
+/* Main Content Area (Right Side) */
+.content {
+  flex: 1;
+  max-width: 800px;
+  padding: 56px 64px 96px;
+}
+
+h1 {
+  font-size: 2.2rem;
+  font-weight: 700;
+  color: #ffffff;
+  margin-bottom: 8px;
+  letter-spacing: -0.025em;
+}
+
+.lead {
+  font-size: 1.15rem;
+  color: var(--text-muted);
+  margin-bottom: 40px;
+}
+
+h2 {
+  font-size: 1.45rem;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 44px 0 16px;
+  letter-spacing: -0.015em;
+}
+
+h3 {
+  font-size: 1.15rem;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 28px 0 12px;
+}
+
+p {
+  margin-bottom: 18px;
+  color: #c9d1d9;
+  font-size: 1.02rem;
+}
+
+ul, ol {
+  margin: 0 0 24px 24px;
+  color: #c9d1d9;
+}
+
+li {
+  margin-bottom: 10px;
+  font-size: 1.02rem;
+}
+
+strong {
+  color: #ffffff;
+}
+
+pre {
+  background: var(--card-bg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 18px 22px;
+  overflow-x: auto;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.9rem;
+  line-height: 1.6;
+  margin: 20px 0 28px;
+  color: #e6edf3;
+}
+
+code {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 0.88em;
+  background: rgba(110, 118, 129, 0.2);
+  padding: 2px 6px;
+  border-radius: 4px;
+  color: #79c0ff;
+}
+
+pre code {
+  background: none;
+  padding: 0;
+  color: inherit;
+}
+
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 24px 0;
+}
+
+th, td {
+  border: 1px solid var(--border);
+  padding: 12px 16px;
+  text-align: left;
+  font-size: 0.92rem;
+}
+
+th {
+  background: var(--card-bg);
+  color: #ffffff;
+  font-weight: 600;
+}
+
+td {
+  background: rgba(22, 27, 34, 0.4);
+}
+
+.page-nav {
+  margin-top: 60px;
+  padding-top: 24px;
+  border-top: 1px solid var(--border);
+  display: flex;
+  justify-content: space-between;
+}
+
+.page-nav a {
+  color: var(--accent);
+  text-decoration: none;
+  font-size: 0.95rem;
+  font-weight: 500;
+}
+
+.page-nav a:hover {
+  color: var(--accent-hover);
+  text-decoration: underline;
+}
+
+/* Mobile Responsive */
+@media (max-width: 820px) {
+  .layout {
+    flex-direction: column;
+  }
+  .sidebar {
+    width: 100%;
+    height: auto;
+    position: static;
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+    padding: 24px 20px;
+  }
+  .nav-list {
+    flex-direction: row;
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+  .content {
+    padding: 36px 20px 64px;
+  }
+}