@keshavsoft/api-tree 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeshavSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @keshavsoft/api-tree
+
+A small 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.
+
+```text
+source JSON
+     +
+API paths
+     +
+executor
+     ↓
+  api-tree
+     ↓
+callable API
+```
+
+## Usage
+
+```js
+import apiTree from "@keshavsoft/api-tree";
+
+const source = {
+    app: {
+        users: {
+            profile: {
+                fetch: { action: "fetch", resource: "users" }
+            }
+        }
+    }
+};
+
+const apiPaths = [
+    "app.users.profile.fetch"
+];
+
+const executor = async ({ inRoutePath, inParam, inSource }) => {
+    return {
+        path: inRoutePath,
+        param: inParam,
+        spec: inSource.app.users.profile.fetch
+    };
+};
+
+const api = apiTree(source, apiPaths, executor);
+
+const result = await api.users.profile.fetch("123");
+```
+
+## Contract
+
+`apiTree(source, apiPaths, executor)` accepts exactly three responsibilities:
+
+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.
+
+`@keshavsoft/api-tree` does not know Tally, XML, HTTP, databases, or business rules.
+
+## Validation
+
+The public entry point checks:
+
+- `source` is a JSON-compatible object.
+- `apiPaths` is an array.
+- every API path is a string.
+- `executor` is a function.
+
+Invalid input produces a clear `TypeError` before the tree is built.
+
+## 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
+```
+
+The domain repository owns the meaning and execution. `@keshavsoft/api-tree` only creates the navigable runtime surface.

package/docs/api.md

@@ -0,0 +1,40 @@
+# API Reference
+
+## `apiTree(source, apiPaths, executor)`
+
+Builds and returns a callable runtime API tree.
+
+### `source`
+
+A JSON-compatible object containing the domain definitions.
+
+### `apiPaths`
+
+A flat array of dotted API paths.
+
+```js
+[
+  "app.users.profile.fetch",
+  "app.reports.summary.fetch"
+]
+```
+
+Nested arrays or non-string path entries are rejected.
+
+### `executor`
+
+A function called when a generated leaf is invoked.
+
+It receives:
+
+```js
+{
+  inRoutePath,
+  inParam,
+  inSource
+}
+```
+
+### Return value
+
+A callable object representing the API paths.

package/docs/index.html

@@ -0,0 +1,26 @@
+<!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>

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@keshavsoft/api-tree",
+  "version": "1.0.0",
+  "description": "Build a callable runtime API tree from API paths, source JSON, and an external executor.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/test.js",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keshavsoft/api-tree.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api-tree",
+    "json-driven",
+    "runtime-api",
+    "api-paths",
+    "declarative-api"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.10"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+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>;

package/src/index.js

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

package/src/v1/blueprint/api.json

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

package/src/v1/blueprint/source.json

@@ -0,0 +1,36 @@
+{
+    "app": {
+        "users": {
+            "profile": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "users",
+                    "description": "Fetches user profile details by ID."
+                }
+            },
+            "settings": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "user_settings",
+                    "description": "Fetches user configuration settings by ID."
+                }
+            }
+        },
+        "reports": {
+            "summary": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "daily_summary",
+                    "description": "Fetches aggregate business summary by date."
+                }
+            },
+            "metrics": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "system_metrics",
+                    "description": "Fetches performance metrics by date."
+                }
+            }
+        }
+    }
+}

package/src/v1/index.js

@@ -0,0 +1,48 @@
+import routeStart from "./internal-working/route/index.js";
+
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== "object") return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+
+const validate = (inSource, inApiPaths, inExecutor) => {
+    if (!isPlainObject(inSource)) {
+        throw new TypeError("source must be a JSON object.");
+    }
+
+    if (!Array.isArray(inApiPaths)) {
+        throw new TypeError("apiPaths must be an array of strings.");
+    }
+
+    if (!inApiPaths.every((path) => typeof path === "string")) {
+        throw new TypeError("apiPaths must be an array of strings.");
+    }
+
+    if (typeof inExecutor !== "function") {
+        throw new TypeError("executor must be a function.");
+    }
+};
+
+const start = (inSource, inApiPaths, inExecutor) => {
+    let source = inSource;
+    let paths = inApiPaths;
+    let executor = inExecutor;
+
+    if (inSource && typeof inSource === "object" && "inSource" in inSource) {
+        source = inSource.inSource;
+        paths = inSource.inApiPaths;
+        executor = inSource.inExecutor;
+    }
+
+    validate(source, paths, executor);
+
+    return routeStart({
+        inApiPaths: paths,
+        inSource: source,
+        inExecutor: executor
+    });
+};
+
+export default start;
+export { start };

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

@@ -0,0 +1,25 @@
+import createLeafHandler from "./createLeafHandler.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];
+    }
+
+    branch[leafName] = createLeafHandler({
+        inPath: localPath,
+        inSource: localSource,
+        inExecutor: localExecutor
+    });
+};
+
+export default startFunc;

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

@@ -0,0 +1,19 @@
+const startFunc = ({ inPath, inSource, inExecutor }) => {
+    const localPath = inPath;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    return async (inParam, ...inArgs) => {
+        const localParam = inParam;
+        const localArgs = inArgs;
+
+        return await localExecutor({
+            inRoutePath: localPath,
+            inParam: localParam,
+            inArgs: localArgs,
+            inSource: localSource
+        });
+    };
+};
+
+export default startFunc;

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

@@ -0,0 +1,24 @@
+import attachPath from "./attachPath.js";
+
+const startFunc = ({ inApiPaths, inSource, inExecutor }) => {
+    const localApiPaths = inApiPaths;
+    const localSource = inSource;
+    const localExecutor = inExecutor;
+
+    const tree = {};
+
+    for (const path of localApiPaths) {
+        attachPath({
+            inTree: tree,
+            inPath: path,
+            inSource: localSource,
+            inExecutor: localExecutor
+        });
+    }
+
+    const rootNamespace = localApiPaths[0]?.split(".")[0];
+
+    return rootNamespace ? tree[rootNamespace] : tree;
+};
+
+export default startFunc;