@keshavsoft/api-tree 1.0.0 → 6.1.0

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;
+  }
+}

package/docs/validation.html

@@ -0,0 +1,88 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>api-tree — Guarantees &amp; Validation</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">Examples</a></li>
+        <li><a href="validation.html" class="nav-link active">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>Guarantees &amp; Validation</h1>
+      <div class="lead">Fail-fast contract validation and reliability guarantees.</div>
+
+      <h2>Fail-Fast Philosophy</h2>
+      <p><code>@keshavsoft/api-tree</code> strictly enforces contract integrity before building any runtime objects. If any input is malformed, it throws a descriptive <code>TypeError</code> immediately so errors never leak into runtime invocations.</p>
+
+      <h2>Validation Rules</h2>
+
+      <h3>1. Source Object</h3>
+      <ul>
+        <li>Must be a non-null plain JavaScript object.</li>
+        <li>Arrays, primitives, and null throw: <code>TypeError: source must be a JSON object.</code></li>
+      </ul>
+
+      <h3>2. API Paths Array</h3>
+      <ul>
+        <li>Must be a JavaScript Array. Non-arrays throw: <code>TypeError: apiPaths must be an array of strings.</code></li>
+        <li>Every element must be a string. Non-string elements throw: <code>TypeError: apiPaths must be an array of strings. apiPaths[i] must be a string.</code></li>
+        <li>Empty strings throw: <code>TypeError: apiPaths[i] must not be an empty string.</code></li>
+        <li>Paths with empty segments (such as <code>"users..fetch"</code> or <code>"users."</code>) throw: <code>TypeError: apiPaths[i] contains an invalid empty path segment.</code></li>
+      </ul>
+
+      <h3>3. Executor Function</h3>
+      <ul>
+        <li>Must be a callable function. Non-functions throw: <code>TypeError: executor must be a function.</code></li>
+      </ul>
+
+      <h3>4. Options</h3>
+      <ul>
+        <li>If provided, options must be a plain object. Passing non-objects throws: <code>TypeError: options must be an object if provided.</code></li>
+      </ul>
+
+      <h2>Test Suite Verification</h2>
+      <p>The package is verified using Node's native test runner with 100% passing tests:</p>
+      <pre><code>npm test
+
+✔ v2: builds a callable API tree with single root unwrapped
+✔ v2: automatically preserves multiple root namespaces
+✔ v2: supports explicit inUnwrapRoot: false option
+✔ v2: supports multi-argument leaves and inPathSegments
+✔ v2: supports hybrid branches (callable node with children)
+✔ v2: rejects empty paths or empty segments
+✔ v2: rejects invalid source, executor, and options
+✔ builds a callable API tree
+✔ supports multi-argument leaves
+✔ supports named-object signature
+✔ rejects a non-object source
+✔ rejects non-array api paths
+✔ rejects non-string api paths
+✔ rejects a non-function executor</code></pre>
+
+      <div class="page-nav">
+        <a href="examples.html">&larr; Examples</a>
+        <a href="index.html">Back to The Story &rarr;</a>
+      </div>
+    </main>
+  </div>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keshavsoft/api-tree",
-  "version": "1.0.0",
+  "version": "6.1.0",
   "description": "Build a callable runtime API tree from API paths, source JSON, and an external executor.",
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/test.js",
+    "test": "node --test test/*.test.js",
     "prepublishOnly": "npm test"
   },
   "repository": {
@@ -40,5 +40,9 @@
   "license": "MIT",
   "engines": {
     "node": ">=20.10"
+  },
+  "devDependencies": {
+    "fast-xml-parser": "^5.11.2",
+    "tally-spec": "^1.0.0"
   }
-}
+}

package/src/index.d.ts

@@ -1,19 +1,65 @@
-export type ApiExecutor<TSource = Record<string, unknown>, TResult = unknown, TParam = unknown> = (input: {
-    inRoutePath: string;
-    inParam: TParam;
-    inSource: TSource;
-}) => TResult | Promise<TResult>;
-
-export type ApiPaths = string[];
-
-export default function start<TSource = Record<string, unknown>, TResult = unknown, TParam = unknown>(
-    source: TSource,
-    apiPaths: ApiPaths,
-    executor: ApiExecutor<TSource, TResult, TParam>
-): Record<string, unknown>;
-
-export function start<TSource = Record<string, unknown>, TResult = unknown, TParam = unknown>(
-    source: TSource,
-    apiPaths: ApiPaths,
-    executor: ApiExecutor<TSource, TResult, TParam>
-): Record<string, unknown>;
+/**
+ * Context passed to the executor function when a leaf method is invoked.
+ */
+export interface ApiTreeExecutionContext<TSource = Record<string, any>> {
+    /** The full dot-notation path of the invoked leaf (e.g. "app.users.profile.fetch") */
+    inRoutePath: string;
+    /** The first argument passed to the leaf method */
+    inParam?: any;
+    /** Array of all remaining arguments passed to the leaf method */
+    inArgs: any[];
+    /** The complete source JSON object */
+    inSource: TSource;
+}
+
+/**
+ * An executor function responsible for handling the execution of an invoked leaf.
+ */
+export type ApiTreeExecutor<TSource = Record<string, any>, TReturn = any> = (
+    context: ApiTreeExecutionContext<TSource>
+) => Promise<TReturn> | TReturn;
+
+/**
+ * Options for customizing api-tree building behavior.
+ */
+export interface ApiTreeOptions {
+    /**
+     * Whether to unwrap a single shared root namespace.
+     * Default: true when all paths share one root namespace; false when paths have different roots.
+     */
+    inUnwrapRoot?: boolean;
+}
+
+/**
+ * Named argument object for apiTree.
+ */
+export interface ApiTreeParams<TSource = Record<string, any>, TReturn = any> {
+    inSource: TSource;
+    inApiPaths: string[];
+    inExecutor: ApiTreeExecutor<TSource, TReturn>;
+    inOptions?: ApiTreeOptions;
+}
+
+/**
+ * Builds and returns a callable runtime API tree from source JSON, API paths, and an executor.
+ *
+ * @param source Source JSON object containing schema definitions
+ * @param apiPaths Array of dot-separated route paths (e.g. ["app.users.fetch"])
+ * @param executor Execution function invoked when a leaf is called
+ * @param options Optional configuration
+ */
+export declare function apiTree<TSource = Record<string, any>, TReturn = any>(
+    source: TSource,
+    apiPaths: string[],
+    executor: ApiTreeExecutor<TSource, TReturn>,
+    options?: ApiTreeOptions
+): Record<string, any>;
+
+/**
+ * Named argument signature for apiTree.
+ */
+export declare function apiTree<TSource = Record<string, any>, TReturn = any>(
+    params: ApiTreeParams<TSource, TReturn>
+): Record<string, any>;
+
+export default apiTree;

package/src/index.js

@@ -1,2 +1,2 @@
-export { default } from "./v1/index.js";
-export * from "./v1/index.js";
+export { default } from "./v6/index.js";
+export * from "./v6/index.js";

package/src/v2/blueprint/api.json

@@ -0,0 +1,4 @@
+[
+  "app.users.profile.fetch",
+  "app.reports.summary.fetch"
+]

package/src/v2/blueprint/source.json

@@ -0,0 +1,22 @@
+{
+  "app": {
+    "users": {
+      "profile": {
+        "fetch": {
+          "action": "fetch",
+          "resource": "User",
+          "description": "Fetch user profile details"
+        }
+      }
+    },
+    "reports": {
+      "summary": {
+        "fetch": {
+          "action": "fetch",
+          "resource": "Report",
+          "description": "Fetch summary report"
+        }
+      }
+    }
+  }
+}

package/src/v2/index.js

@@ -0,0 +1,33 @@
+import validate from "./internal-working/validate/index.js";
+import routeStart from "./internal-working/route/index.js";
+
+const start = (inSource, inApiPaths, inExecutor, inOptions) => {
+    let source = inSource;
+    let paths = inApiPaths;
+    let executor = inExecutor;
+    let options = inOptions;
+
+    if (inSource && typeof inSource === "object" && "inSource" in inSource) {
+        source = inSource.inSource;
+        paths = inSource.inApiPaths;
+        executor = inSource.inExecutor;
+        options = inSource.inOptions;
+    }
+
+    validate({
+        inSource: source,
+        inApiPaths: paths,
+        inExecutor: executor,
+        inOptions: options
+    });
+
+    return routeStart({
+        inApiPaths: paths,
+        inSource: source,
+        inExecutor: executor,
+        inOptions: options
+    });
+};
+
+export default start;
+export { start, start as apiTree };

package/src/v2/internal-working/route/attachPath.js

@@ -0,0 +1,38 @@
+import createLeafHandler from "./createLeafHandler.js";
+import resolveLeafSpec from "./resolveLeafSpec.js";
+
+const startFunc = ({ inTree, inPath, inSource, inExecutor }) => {
+    const localTree = inTree;
+    const localPath = inPath;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    const parts = localPath.split(".");
+    const leafName = parts.pop();
+
+    let branch = localTree;
+    for (const segment of parts) {
+        branch[segment] ??= {};
+        branch = branch[segment];
+    }
+
+    const leafSpec = resolveLeafSpec({
+        inSource: localSource,
+        inPath: localPath
+    });
+
+    const handler = createLeafHandler({
+        inPath: localPath,
+        inSource: localSource,
+        inExecutor: localExecutor,
+        inLeafSpec: leafSpec
+    });
+
+    if (branch[leafName] && typeof branch[leafName] === "object") {
+        Object.assign(handler, branch[leafName]);
+    }
+
+    branch[leafName] = handler;
+};
+
+export default startFunc;

package/src/v2/internal-working/route/createLeafHandler.js

@@ -0,0 +1,25 @@
+const startFunc = ({ inPath, inSource, inExecutor, inLeafSpec }) => {
+    const localPath = inPath;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+    const localLeafSpec = inLeafSpec;
+    const localPathSegments = localPath.split(".");
+
+    const handler = async (inParam, ...inArgs) => {
+        const localParam = inParam;
+        const localArgs = inArgs;
+
+        return await localExecutor({
+            inRoutePath: localPath,
+            inParam: localParam,
+            inArgs: localArgs,
+            inSource: localSource,
+            inLeafSpec: localLeafSpec,
+            inPathSegments: localPathSegments
+        });
+    };
+
+    return handler;
+};
+
+export default startFunc;

package/src/v2/internal-working/route/index.js

@@ -0,0 +1,35 @@
+import attachPath from "./attachPath.js";
+
+const startFunc = ({ inApiPaths, inSource, inExecutor, inOptions }) => {
+    const localApiPaths = inApiPaths;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+    const localOptions = inOptions ?? {};
+
+    const tree = {};
+
+    for (const path of localApiPaths) {
+        attachPath({
+            inTree: tree,
+            inPath: path,
+            inSource: localSource,
+            inExecutor: localExecutor
+        });
+    }
+
+    if (localApiPaths.length === 0) {
+        return tree;
+    }
+
+    const rootSegments = new Set(localApiPaths.map((path) => path.split(".")[0]));
+
+    if (rootSegments.size === 1) {
+        const sharedRoot = rootSegments.values().next().value;
+        const unwrap = localOptions.inUnwrapRoot !== false;
+        return unwrap && tree[sharedRoot] ? tree[sharedRoot] : tree;
+    }
+
+    return tree;
+};
+
+export default startFunc;

package/src/v2/internal-working/route/resolveLeafSpec.js

@@ -0,0 +1,22 @@
+const startFunc = ({ inSource, inPath }) => {
+    const localSource = inSource;
+    const localPath = inPath;
+
+    if (!localSource || typeof localSource !== "object" || !localPath) {
+        return undefined;
+    }
+
+    const segments = localPath.split(".");
+    let current = localSource;
+
+    for (const segment of segments) {
+        if (current === null || typeof current !== "object" || !(segment in current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+
+    return current;
+};
+
+export default startFunc;