tally-xml-tdl 1.27.3 → 1.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tally-xml-tdl",
-  "version": "1.27.3",
+  "version": "1.31.1",
   "description": "Simple, clean TDL and XML extraction and manipulation tools for Tally",
   "type": "module",
   "main": "src/index.js",
@@ -37,7 +37,7 @@
     "create-intellisense": "^1.2.1"
   },
   "dependencies": {
-    "@keshavsoft/api-tree": "^11.1.1",
-    "tally-spec": "^1.2.2"
+    "tally-extract": "^1.10.2",
+    "tally-spec": "^1.2.4"
   }
 }

package/src/index.js

@@ -1,2 +1,2 @@
-export { default } from "./v27/index.js";
-export * from "./v27/index.js";
+export { company, masters, vouchers } from "./v31/index.js";
+export { default } from "./v31/index.js";

package/src/v28/apiTree/blueprint/api.json

@@ -0,0 +1,13 @@
+[
+  "app.ecosystem.architecture.philosophy.fetch",
+  "app.ecosystem.architecture.layers.fetch",
+  "app.ecosystem.tools.blueprint.fetch",
+  "app.ecosystem.tools.scaffolder.fetch",
+  "app.ecosystem.tools.intellisense.fetch",
+  "app.ecosystem.workflow.steps.fetch",
+  "app.ecosystem.workflow.principles.fetch",
+  "app.founder.profile.fetch",
+  "app.founder.links.fetch",
+  "app.company.info.fetch",
+  "app.company.packages.fetch"
+]

package/src/v28/apiTree/blueprint/source.json

@@ -0,0 +1,228 @@
+{
+    "app": {
+        "ecosystem": {
+            "architecture": {
+                "philosophy": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "philosophy",
+                        "description": "Explains why endpoints as structured data eliminates conventional folder sprawl.",
+                        "data": {
+                            "concept": "Endpoints as Data",
+                            "problem": "In conventional client libraries, adding 50 endpoints requires creating 50 directories and 50 repetitive boilerplate files, causing maintenance drag and import fragility.",
+                            "solution": "Define endpoints declaratively in JSON contracts (source.json + api.json) and assemble the callable object tree in memory at startup.",
+                            "benefits": [
+                                "Zero directory sprawl across packages",
+                                "Single point of query customization in engine/execution",
+                                "Instant in-memory object tree generation without code duplication",
+                                "Deterministic compile-time TypeScript typing directly from JSON"
+                            ]
+                        }
+                    }
+                },
+                "layers": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "layers",
+                        "description": "Details the three clean architectural layers of a JSON-driven NPM package.",
+                        "data": {
+                            "layers": [
+                                {
+                                    "name": "1. Public Contract (api.json)",
+                                    "role": "Explicit array of allowed dot-separated paths controlling the public perimeter."
+                                },
+                                {
+                                    "name": "2. Domain Specification (source.json)",
+                                    "role": "Single source of truth for resources, actions, schemas, JSDocs, and mock or real payloads."
+                                },
+                                {
+                                    "name": "3. Engine (engine/)",
+                                    "role": "In-memory route tree assembly (engine/route/) and story-driven execution pipeline (engine/execution/)."
+                                }
+                            ]
+                        }
+                    }
+                }
+            },
+            "tools": {
+                "blueprint": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "blueprint",
+                        "description": "Specification for json-driven-npm: The Architectural Source of Truth.",
+                        "data": {
+                            "package": "json-driven-npm",
+                            "role": "Architectural Source of Truth & Reference Specification",
+                            "repository": "https://github.com/keshavsoft/json-driven-npm",
+                            "npm": "https://www.npmjs.com/package/json-driven-npm",
+                            "responsibilities": [
+                                "Maintains reference versions (v1, v2, v3, v4)",
+                                "Provides the in-memory route mounting engine",
+                                "Provides the narrative execution coordinator",
+                                "Exposes live CLI terminal inspector via npx json-driven-npm"
+                            ],
+                            "rule": "Never transports code itself; acts as the authoritative template source."
+                        }
+                    }
+                },
+                "scaffolder": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "scaffolder",
+                        "description": "Specification for create-json-driven-npm: The Zero-Dependency Code Transporter.",
+                        "data": {
+                            "package": "create-json-driven-npm",
+                            "role": "The Scaffolder & Code Transporter",
+                            "repository": "https://github.com/keshavsoft/create-json-driven-npm",
+                            "npm": "https://www.npmjs.com/package/create-json-driven-npm",
+                            "usage": "npm create json-driven-npm [target-directory] or npx create-json-driven-npm [target-directory]",
+                            "mechanism": "Dynamically inspects node_modules/json-driven-npm/src, resolves the highest active version, and transports the clean skeleton into the target directory.",
+                            "features": [
+                                "Zero hardcoded templates (reads from json-driven-npm)",
+                                "Built-in safety guards preventing overwrites",
+                                "Instant scaffolding in 1 second"
+                            ]
+                        }
+                    }
+                },
+                "intellisense": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "intellisense",
+                        "description": "Specification for create-intellisense: The Automated TypeScript Generator.",
+                        "data": {
+                            "package": "create-intellisense",
+                            "role": "Zero-Dependency TypeScript Type & JSDoc Generator",
+                            "repository": "https://github.com/keshavsoft/create-intellisense",
+                            "npm": "https://www.npmjs.com/package/create-intellisense",
+                            "usage": "npx create-intellisense",
+                            "mechanism": "Scans api.json and source.json in the project root or active version folder and emits index.d.ts with full IDE autocomplete and hover tooltips.",
+                            "features": [
+                                "Zero external dependencies (pure Node.js builtins)",
+                                "Flexible path discovery (supports flattened and nested layouts)",
+                                "Auto-infers types from package.json and active exports"
+                            ]
+                        }
+                    }
+                }
+            },
+            "workflow": {
+                "steps": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "workflow",
+                        "description": "The 3-step development guide for creating a new JSON-driven NPM package.",
+                        "data": {
+                            "steps": [
+                                {
+                                    "step": 1,
+                                    "name": "Scaffold",
+                                    "command": "npm create json-driven-npm ./my-api-client",
+                                    "description": "create-json-driven-npm transports the clean v4 skeleton into your project directory with zero dependencies."
+                                },
+                                {
+                                    "step": 2,
+                                    "name": "Customize",
+                                    "command": "Edit api.json & source.json",
+                                    "description": "Define your public routes in api.json and endpoint metadata in source.json. Implement your custom query/fetch logic in engine/execution/index.js."
+                                },
+                                {
+                                    "step": 3,
+                                    "name": "Generate Types",
+                                    "command": "npx create-intellisense",
+                                    "description": "create-intellisense scans your JSON contracts and emits index.d.ts, giving your users instant autocomplete and type safety."
+                                }
+                            ]
+                        }
+                    }
+                },
+                "principles": {
+                    "fetch": {
+                        "action": "fetch",
+                        "resource": "principles",
+                        "description": "Core KeshavSoft engineering standards and design conventions.",
+                        "data": {
+                            "standards": [
+                                {
+                                    "rule": "Strictly One Default Export",
+                                    "syntax": "export default startFunc;",
+                                    "rationale": "Eliminates named export clutter and namespace ambiguity."
+                                },
+                                {
+                                    "rule": "Standardized Parameter Unwrapping",
+                                    "syntax": "const startFunc = ({ inParam }) => { const localParam = inParam; ... };",
+                                    "rationale": "Prevents mutation of input objects and makes parameter origins explicit."
+                                },
+                                {
+                                    "rule": "Pure Domain Decoupling",
+                                    "syntax": "source.json contains business metadata only",
+                                    "rationale": "Keeps domain specifications independent from network protocols, headers, or runtime environments."
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "founder": {
+            "profile": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "profile",
+                    "description": "Fetches founder and software architect profile.",
+                    "data": {
+                        "name": "Keshav Nalam",
+                        "role": "Software Architect & Developer",
+                        "company": "KeshavSoft",
+                        "location": "India",
+                        "bio": "Creator of zero-dependency, declarative, JSON-driven NPM architectures."
+                    }
+                }
+            },
+            "links": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "links",
+                    "description": "Fetches official website, GitHub, NPM, and LinkedIn profile links.",
+                    "data": {
+                        "website": "https://keshavsoft.com/",
+                        "github": "https://github.com/keshavsoft",
+                        "npm": "https://www.npmjs.com/~keshavsoft",
+                        "linkedin": "https://www.linkedin.com/in/keshav-nalam"
+                    }
+                }
+            }
+        },
+        "company": {
+            "info": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "info",
+                    "description": "Fetches KeshavSoft organization information and engineering philosophy.",
+                    "data": {
+                        "name": "KeshavSoft",
+                        "tagline": "Pure, declarative, and config-driven software engineering",
+                        "website": "https://keshavsoft.com/",
+                        "philosophy": "Zero-dependency architectures, declarative pipelines, and zero folder sprawl"
+                    }
+                }
+            },
+            "packages": {
+                "fetch": {
+                    "action": "fetch",
+                    "resource": "packages",
+                    "description": "Lists flagship packages in the KeshavSoft ecosystem.",
+                    "data": [
+                        { "name": "tally-simple", "description": "Raw TDL transport client & CLI for Tally ERP/Prime" },
+                        { "name": "tally-simple-json", "description": "Fast XML-to-JSON parsing client for Tally" },
+                        { "name": "create-intellisense", "description": "Zero-dependency TypeScript declaration generator for JSON-driven architectures" },
+                        { "name": "create-json-driven-npm", "description": "Official scaffolding tool to transport JSON-driven client architectures" },
+                        { "name": "json-renderers", "description": "Browser DOM mounting runtime for declarative UI specifications" },
+                        { "name": "json-renderers-build", "description": "Headless UI component specification compiler" },
+                        { "name": "json-driven-npm", "description": "Architectural reference implementation and CLI runner for declarative, JSON-driven NPM packages" }
+                    ]
+                }
+            }
+        }
+    }
+}

package/src/v28/apiTree/engine/caller/index.js

@@ -0,0 +1,65 @@
+const createCallable = ({ inRoutePath, inLeafSpec, inExecutor, inSource }) => {
+    const localRoutePath = inRoutePath;
+    const localLeafSpec = inLeafSpec;
+    const localExecutor = inExecutor;
+    const localSource = inSource;
+
+    return async (param, ...args) => {
+        const localParam = param;
+        const localArgs = args;
+
+        return await localExecutor({
+            inRoutePath: localRoutePath,
+            inLeafSpec: localLeafSpec,
+            inParam: localParam,
+            inArgs: localArgs,
+            inSource: localSource
+        });
+    };
+};
+
+const createCaller = (source, executor) => {
+    const localSource = source?.inSource ?? source;
+    const localExecutor = source?.inExecutor ?? executor;
+
+    return async (inRoutePath, inParam, ...inArgs) => {
+        const localRoutePath = inRoutePath;
+        const localParam = inParam;
+        const localArgs = inArgs;
+
+        const localLeafSpec = localRoutePath
+            ?.split(".")
+            .reduce((curr, key) => curr?.[key], localSource);
+
+        return await localExecutor({
+            inRoutePath: localRoutePath,
+            inLeafSpec: localLeafSpec,
+            inParam: localParam,
+            inArgs: localArgs,
+            inSource: localSource
+        });
+    };
+};
+
+const callRoute = async ({ inSource, inRoutePath, inExecutor, inParam, inArgs, inLeafSpec }) => {
+    const localSource = inSource;
+    const localRoutePath = inRoutePath;
+    const localExecutor = inExecutor;
+    const localParam = inParam;
+    const localArgs = inArgs ?? [];
+
+    const localLeafSpec = inLeafSpec ?? localRoutePath
+        ?.split(".")
+        .reduce((curr, key) => curr?.[key], localSource);
+
+    return await localExecutor({
+        inRoutePath: localRoutePath,
+        inLeafSpec: localLeafSpec,
+        inParam: localParam,
+        inArgs: localArgs,
+        inSource: localSource
+    });
+};
+
+export default createCallable;
+export { createCallable, createCaller, callRoute };

package/src/v28/apiTree/engine/guards/index.js

@@ -0,0 +1,23 @@
+import isObject from "./isObject.js";
+import isStringArray from "./isStringArray.js";
+import isFunction from "./isFunction.js";
+
+const startFunc = ({ inSource, inRecipe, inExecutor }) => {
+    const localSource = inSource;
+    const localRecipe = inRecipe;
+    const localExecutor = inExecutor;
+
+    isObject({ inSource: localSource });
+
+    if (localRecipe !== undefined) {
+        if (Array.isArray(localRecipe)) {
+            isStringArray({ inApiPaths: localRecipe });
+        } else if (localRecipe === null || typeof localRecipe !== "object") {
+            isStringArray({ inApiPaths: localRecipe });
+        }
+    }
+
+    isFunction({ inExecutor: localExecutor });
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/guards/isFunction.js

@@ -0,0 +1,9 @@
+const startFunc = ({ inExecutor }) => {
+    const localExecutor = inExecutor;
+
+    if (typeof localExecutor !== "function") {
+        throw new TypeError("executor must be a function.");
+    }
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/guards/isObject.js

@@ -0,0 +1,9 @@
+const startFunc = ({ inSource }) => {
+    const localSource = inSource;
+
+    if (!localSource || typeof localSource !== "object" || Array.isArray(localSource)) {
+        throw new TypeError("source must be a JSON object.");
+    }
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/guards/isStringArray.js

@@ -0,0 +1,15 @@
+const startFunc = ({ inApiPaths }) => {
+    const localApiPaths = inApiPaths;
+
+    if (!Array.isArray(localApiPaths)) {
+        throw new TypeError("apiPaths must be an array of strings.");
+    }
+
+    for (let i = 0; i < localApiPaths.length; i++) {
+        if (typeof localApiPaths[i] !== "string") {
+            throw new TypeError(`apiPaths must be an array of strings. apiPaths[${i}] must be a string.`);
+        }
+    }
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/run.js

@@ -0,0 +1,16 @@
+import traverse from "./traversal/index.js";
+import toTransformRecipe from "./toTransformRecipe.js";
+
+const startFunc = ({ inSource, inRecipe, inExecutor }) => {
+    const localSource = inSource;
+    const localRecipe = toTransformRecipe({ inRecipe: inRecipe || inSource });
+    const localExecutor = inExecutor;
+
+    return traverse({
+        inSource: localSource,
+        inRecipe: localRecipe,
+        inExecutor: localExecutor
+    });
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/toTransformRecipe.js

@@ -0,0 +1,53 @@
+const startFunc = ({ inRecipe }) => {
+    const localRecipe = inRecipe;
+
+    if (Array.isArray(localRecipe)) {
+        const root = {};
+
+        for (const path of localRecipe) {
+            const parts = path.split(".");
+            let curr = root;
+
+            for (let i = 0; i < parts.length; i++) {
+                const part = parts[i];
+                curr.transform ??= {};
+                curr.transform[part] ??= {};
+
+                if (i < parts.length - 1) {
+                    curr = curr.transform[part];
+                }
+            }
+        }
+
+        return root;
+    }
+
+    if (localRecipe && typeof localRecipe === "object") {
+        if ("transform" in localRecipe) {
+            return localRecipe;
+        }
+
+        const buildTransform = (node) => {
+            if (!node || typeof node !== "object" || Array.isArray(node)) {
+                return {};
+            }
+
+            if ("action" in node) {
+                return {};
+            }
+
+            const transform = {};
+            for (const [key, value] of Object.entries(node)) {
+                transform[key] = buildTransform(value);
+            }
+
+            return { transform };
+        };
+
+        return buildTransform(localRecipe);
+    }
+
+    return undefined;
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/traversal/ifTransformFound/index.js

@@ -0,0 +1,49 @@
+import traverse from "../index.js";
+import createCallable from "../../caller/index.js";
+
+const startFunc = ({ inSource, inTransform, inRecipe, inExecutor, inPath, inRootSource }) => {
+    const localSource = inSource;
+    const localTransform = inTransform;
+    const localRecipe = inRecipe;
+    const localExecutor = inExecutor;
+    const localPath = inPath ?? [];
+    const localRootSource = inRootSource ?? inSource;
+
+    const newElement = {};
+
+    for (const [key, value] of Object.entries(localSource)) {
+        if (!(key in localTransform)) {
+            continue;
+        }
+
+        const directive = localTransform[key];
+        const newKey = directive?.alterKey || key;
+        const currentPath = [...localPath, key];
+
+        const hasNestedTransform = directive && typeof directive === "object" && "transform" in directive;
+        const hasSiblingRecipe = localRecipe && typeof localRecipe === "object" && newKey in localRecipe;
+
+        if (hasNestedTransform) {
+            newElement[newKey] = traverse({
+                inSource: value,
+                inRecipe: directive,
+                inExecutor: localExecutor,
+                inPath: currentPath,
+                inRootSource: localRootSource
+            });
+        } else if (hasSiblingRecipe) {
+            newElement[newKey] = value;
+        } else {
+            newElement[newKey] = createCallable({
+                inRoutePath: currentPath.join("."),
+                inLeafSpec: value,
+                inExecutor: localExecutor,
+                inSource: localRootSource
+            });
+        }
+    }
+
+    return newElement;
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/traversal/index.js

@@ -0,0 +1,34 @@
+import traverseObject from "./traverseObject/index.js";
+import traverseArray from "./traverseArray/index.js";
+
+const startFunc = ({ inSource, inRecipe, inExecutor, inPath, inRootSource }) => {
+    const localSource = inSource;
+    const localRecipe = inRecipe;
+    const localExecutor = inExecutor;
+    const localPath = inPath ?? [];
+    const localRootSource = inRootSource ?? inSource;
+
+    if (Array.isArray(localSource)) {
+        return traverseArray({
+            inItems: localSource,
+            inRecipe: localRecipe,
+            inExecutor: localExecutor,
+            inPath: localPath,
+            inRootSource: localRootSource
+        });
+    }
+
+    if (typeof localSource === "object" && localSource !== null) {
+        return traverseObject({
+            inSource: localSource,
+            inRecipe: localRecipe,
+            inExecutor: localExecutor,
+            inPath: localPath,
+            inRootSource: localRootSource
+        });
+    }
+
+    return localSource;
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/traversal/traverseArray/index.js

@@ -0,0 +1,21 @@
+import traverse from "../index.js";
+
+const startFunc = ({ inItems, inRecipe, inExecutor, inPath, inRootSource }) => {
+    const localItems = inItems;
+    const localRecipe = inRecipe;
+    const localExecutor = inExecutor;
+    const localPath = inPath ?? [];
+    const localRootSource = inRootSource;
+
+    return localItems.map((item, index) =>
+        traverse({
+            inSource: item,
+            inRecipe: localRecipe,
+            inExecutor: localExecutor,
+            inPath: [...localPath, index],
+            inRootSource: localRootSource
+        })
+    );
+};
+
+export default startFunc;

package/src/v28/apiTree/engine/traversal/traverseObject/index.js

@@ -0,0 +1,50 @@
+import ifTransformFound from "../ifTransformFound/index.js";
+import traverse from "../index.js";
+import traverseArray from "../traverseArray/index.js";
+
+const startFunc = ({ inSource, inRecipe, inExecutor, inPath, inRootSource }) => {
+    const localSource = inSource;
+    const localRecipe = inRecipe;
+    const localExecutor = inExecutor;
+    const localPath = inPath ?? [];
+    const localRootSource = inRootSource ?? inSource;
+
+    let newElement = {};
+
+    if (localRecipe && typeof localRecipe === "object" && "transform" in localRecipe) {
+        newElement = ifTransformFound({
+            inSource: localSource,
+            inTransform: localRecipe.transform,
+            inRecipe: localRecipe,
+            inExecutor: localExecutor,
+            inPath: localPath,
+            inRootSource: localRootSource
+        });
+    }
+
+    for (const [key, value] of Object.entries(newElement)) {
+        if (localRecipe && typeof localRecipe === "object" && key in localRecipe) {
+            if (Array.isArray(value)) {
+                newElement[key] = traverseArray({
+                    inItems: value,
+                    inRecipe: localRecipe[key],
+                    inExecutor: localExecutor,
+                    inPath: [...localPath, key],
+                    inRootSource: localRootSource
+                });
+            } else if (typeof value === "object" && value !== null) {
+                newElement[key] = traverse({
+                    inSource: value,
+                    inRecipe: localRecipe[key],
+                    inExecutor: localExecutor,
+                    inPath: [...localPath, key],
+                    inRootSource: localRootSource
+                });
+            }
+        }
+    }
+
+    return newElement;
+};
+
+export default startFunc;

package/src/v28/apiTree/index.js

@@ -0,0 +1,32 @@
+import guards from "./engine/guards/index.js";
+import run from "./engine/run.js";
+import { createCaller, callRoute } from "./engine/caller/index.js";
+
+const apiTree = (source, recipe, executor) => {
+    let localSource = source?.inSource ?? source;
+    let localRecipe = source?.inRecipe ?? source?.inInstruction ?? source?.inApiPaths ?? recipe;
+    let localExecutor = source?.inExecutor ?? executor;
+
+    if (executor === undefined && typeof recipe === "function") {
+        localRecipe = undefined;
+        localExecutor = recipe;
+    }
+
+    guards({
+        inSource: localSource,
+        inRecipe: localRecipe,
+        inExecutor: localExecutor
+    });
+
+    return run({
+        inSource: localSource,
+        inRecipe: localRecipe,
+        inExecutor: localExecutor
+    });
+};
+
+apiTree.createCaller = createCaller;
+apiTree.callRoute = callRoute;
+
+export default apiTree;
+export { apiTree, apiTree as start, createCaller, callRoute };