tally-xml-tdl 1.4.1 → 1.6.2

package/README.md

@@ -1,95 +1,175 @@
-# KeshavSoft
-
-Simple tools. Clean architecture. Fast development.
-
----
-
-## @keshavsoft/kschema
-
-A lightweight schema-driven JSON database for Node.js.
-
----
-
-## Install
-
-npm i @keshavsoft/kschema
-
----
-
-## Usage
-
-import { kschema } from "@keshavsoft/kschema";
-
-kschema.loadConfig({ dataPath: "./data" });
-
-const users = kschema.table("users");
-
-users.insert({ name: "keshav" });
-
-const data = users.get();
-
-console.log(data);
-
----
-
-## API
-
-Create
-
-users.insert(record);
-users.insertStrict(record);
-
-Read
-
-users.get();
-users.findByPk(id);
-
-Filter
-
-users.filterByPk(id);
-users.filterByColumns({ name: "keshav" });
-
-Update
-
-users.update(record);
-
-Delete
-
-users.delete(id);
-users.deleteByColumns({ name: "keshav" });
-
----
-
-## Features
-
-* File-based JSON storage
-* Schema-driven design
-* Auto primary key
-* Simple CRUD API
-* Zero dependencies
-
----
-
-## Links
-
-GitHub: https://github.com/keshavsoft/kschema
-NPM: https://www.npmjs.com/package/@keshavsoft/kschema
-Website: https://keshavsoft.com
-
----
-
-## Contact
-
-Email: founder@keshavsoft.com
-
----
-
-## About
-
-KeshavSoft builds simple and practical developer tools focused on clarity, speed, and real-world usage.
-
----
-
-## License
-
-MIT License — see LICENSE file
+# tally-xml-tdl
+
+> Simple, clean TDL and XML extraction and manipulation tools for Tally.
+
+[![npm version](https://img.shields.io/npm/v/tally-xml-tdl.svg)](https://www.npmjs.com/package/tally-xml-tdl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Extract data directly from **Tally Prime / Tally.ERP 9** using TDL XML requests over HTTP, and get back **clean, developer-friendly JSON** ready for modern web apps, APIs, dashboards, and databases.
+
+---
+
+## 📖 The Story
+
+Interfacing with Tally usually means dealing with complex, deeply nested XML envelopes, verbose TDL message syntax, and responses filled with XML parser artifacts (`@_RESERVEDNAME`, `#text`, `@_TYPE`, etc.):
+
+```json
+// Traditional Tally XML-to-JSON response (cluttered & nested):
+{
+  "ENVELOPE": {
+    "BODY": {
+      "DATA": {
+        "COLLECTION": {
+          "UNIT": [
+            {
+              "@_NAME": "Kgs",
+              "@_RESERVEDNAME": "",
+              "NAME": { "#text": "Kgs", "@_TYPE": "String" }
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+**`tally-xml-tdl` changes that.** With version **`v6`**, it introduces a streamlined template-driven engine and two simple functions:
+
+- **`clean()`**: Strips all XML noise, flattens text nodes, removes reserved attributes, and returns plain JavaScript objects or arrays.
+- **`get()`**: Returns the full XML-to-JSON parsed object when you need raw envelope fidelity.
+
+```json
+// With tally-xml-tdl clean():
+[
+  "Kgs"
+]
+```
+
+---
+
+## 🚀 Features
+
+- 🧹 **Clean Data Out-of-the-Box**: Automatically strips Tally metadata attributes and flattens nested values.
+- ⚡ **Two Extraction Modes**: Choose `clean()` for clean data arrays, or `get()` for the full parsed envelope.
+- 📋 **Pre-configured Queries**: Built-in TDL queries for UOM, Stock Items, Stock Items with Base Units, and Ledgers.
+- 🏎️ **Fast & Lightweight**: Built on top of `fast-xml-parser` with minimal overhead.
+- 📦 **Zero-Config HTTP Transport**: Communicates directly with Tally's built-in HTTP server (`http://localhost:9000`).
+- 🔷 **First-Class TypeScript Support**: Full type declarations included (`.d.ts`).
+- 🌐 **Modern ESM**: Native ES modules with subpath exports (`tally-xml-tdl` and `tally-xml-tdl/v6`).
+
+---
+
+## 📦 Installation
+
+```bash
+npm install tally-xml-tdl
+```
+
+### Prerequisites
+Make sure Tally is running and its HTTP server is enabled:
+- **Tally Prime / Tally.ERP 9**: Press `F12` (Configure) -> **Advanced Configuration** -> Set **Tally is acting as** to `Both` or `Server`, and note the port (default is `9000`).
+
+---
+
+## 💡 Quick Start
+
+```javascript
+import { clean, get } from "tally-xml-tdl";
+
+// 1. Fetch clean, simplified data
+const items = await clean({
+    company: "My Company Name",
+    jsonId: "stockItemsWithBaseUnits"
+});
+
+console.log(items);
+// Output:
+// [
+//   { NAME: "Item A", BASEUNITS: "Nos" },
+//   { NAME: "Item B", BASEUNITS: "Kgs" }
+// ]
+
+// 2. Fetch raw parsed JSON (full fidelity)
+const raw = await get({
+    company: "My Company Name",
+    jsonId: "uom"
+});
+
+console.log(raw);
+```
+
+---
+
+## 📚 API Reference
+
+### `clean(options)`
+Sends the TDL query to Tally, parses the XML response, and cleans the resulting collection data.
+
+```typescript
+clean<T = any>(options: V6Options): Promise<T>
+```
+
+#### Options:
+| Option | Type | Required | Default | Description |
+| :--- | :--- | :---: | :--- | :--- |
+| `company` | `string` | **Yes** | — | Name of the active company in Tally. |
+| `jsonId` | `string` | **Yes** | — | ID of the pre-configured TDL query. |
+| `url` | `string` | No | `"http://localhost:9000"` | Tally HTTP endpoint URL. |
+
+---
+
+### `get(options)`
+Sends the TDL query to Tally and returns the complete XML response converted to a JavaScript object without stripping any metadata.
+
+```typescript
+get<T = any>(options: V6Options): Promise<T>
+```
+
+---
+
+## 🗂️ Built-in Query Catalog (`jsonId`)
+
+| `jsonId` | Target Entity | Description | Fields Fetched |
+| :--- | :--- | :--- | :--- |
+| `"uom"` | Units of Measure | List of units of measurement | `$$Alias:Name` |
+| `"stockItems"` | Stock Items | List of inventory stock items | `$$Alias:Name` |
+| `"stockItemsWithBaseUnits"` | Stock Items | Inventory stock items with their base units | `$$Alias:Name`, `BaseUnits` |
+| `"ledgerNames"` | Ledgers | List of accounting ledgers | `$$Alias:Name` |
+
+---
+
+## 🎯 Advanced Usage
+
+### Connecting to a Remote or Custom Port
+If Tally is hosted on another machine or running on a non-default port:
+
+```javascript
+import { clean } from "tally-xml-tdl";
+
+const data = await clean({
+    company: "Acme Corp",
+    jsonId: "ledgerNames",
+    url: "http://192.168.1.100:9005"
+});
+```
+
+### Subpath Import
+You can also explicitly import from the `v6` subpath:
+
+```javascript
+import { clean, get } from "tally-xml-tdl/v6";
+```
+
+### Using Namespaces
+```javascript
+import { v6 } from "tally-xml-tdl";
+
+const data = await v6.clean({ company: "Acme Corp", jsonId: "uom" });
+```
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © [KeshavSoft](https://keshavsoft.com)

package/index.d.ts

@@ -1,84 +1,10 @@
-/**
- * Converts an XML string into a JavaScript object.
- * Attributes are prefixed with '@_'.
- */
-export function xmlToJson<T = any>(xml: string, options?: Record<string, any>): T;
-
-/**
- * Converts a JavaScript object into a formatted XML string.
- */
-export function jsonToXml(jsonObj: Record<string, any>, options?: Record<string, any>): string;
-
-export interface CreateEnvelopeOptions {
-    id?: string;
-    type?: string;
-    staticVariables?: Record<string, any>;
-    tdlMessage?: Record<string, any>;
-}
-
-/**
- * Creates a base Tally XML Envelope JavaScript Object.
- */
-export function createEnvelope(options?: CreateEnvelopeOptions): Record<string, any>;
-
-export interface CreateCollectionEnvelopeOptions {
-    name: string;
-    type: string;
-    fields?: string | string[];
-    filters?: Record<string, any>;
-    staticVariables?: Record<string, any>;
-}
-
-/**
- * Creates a Tally Collection Request Envelope object.
- */
-export function createCollectionEnvelope(options: CreateCollectionEnvelopeOptions): Record<string, any>;
-
-/**
- * Directly builds a Tally XML string for a collection request.
- */
-export function buildCollectionXml(options: CreateCollectionEnvelopeOptions): string;
-
-export interface SendToTallyOptions {
-    xml: string;
-    url?: string;
-}
-
-/**
- * Sends an XML payload to Tally via HTTP POST and returns parsed JSON response.
- */
-export function sendToTally<T = any>(options: SendToTallyOptions): Promise<T>;
-
-export interface FetchCollectionOptions {
-    name: string;
-    type: string;
-    fields?: string | string[];
-    filters?: Record<string, any>;
-    staticVariables?: Record<string, any>;
-    url?: string;
-}
-
-/**
- * High-level helper to fetch any Tally collection directly.
- */
-export function fetchCollection<T = any>(options: FetchCollectionOptions): Promise<T>;
-
-export interface ExecuteBodyOptions {
-    full?: boolean;
-    url?: string;
-}
-
-/**
- * Executes a Tally request from a JSON body (either envelope or collection definition).
- * If options.full is false (default), returns only the children of DATA.COLLECTION on success.
- * If options.full is true, returns the raw full ENVELOPE JSON response.
- */
-export function executeBody<T = any>(body: Record<string, any>, options?: ExecuteBodyOptions): Promise<T>;
-
-export * as v1 from "./src/v1/index.js";
-export * as v2 from "./src/v2/index.js";
-export * as v3 from "./src/v3/index.js";
-export * as v4 from "./src/v4/index.js";
-
-
-
+export interface V6Options {
+    company: string;
+    jsonId: string;
+    url?: string;
+}
+
+export function get<T = any>(options?: V6Options): Promise<T>;
+export function clean<T = any>(options?: V6Options): Promise<T>;
+
+export * as v6 from "./src/v6/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tally-xml-tdl",
-  "version": "1.4.1",
+  "version": "1.6.2",
   "description": "Simple, clean TDL and XML extraction and manipulation tools for Tally",
   "type": "module",
   "main": "index.js",
@@ -12,30 +12,15 @@
       "import": "./index.js",
       "default": "./index.js"
     },
-    "./v1": {
-      "types": "./src/v1/index.d.ts",
-      "import": "./src/v1/index.js",
-      "default": "./src/v1/index.js"
-    },
-    "./v2": {
-      "types": "./src/v2/index.d.ts",
-      "import": "./src/v2/index.js",
-      "default": "./src/v2/index.js"
-    },
-    "./v3": {
-      "types": "./src/v3/index.d.ts",
-      "import": "./src/v3/index.js",
-      "default": "./src/v3/index.js"
-    },
-    "./v4": {
-      "types": "./src/v4/index.d.ts",
-      "import": "./src/v4/index.js",
-      "default": "./src/v4/index.js"
-    },
-    "./*": "./src/*.js"
+    "./v6": {
+      "types": "./src/v6/index.d.ts",
+      "import": "./src/v6/index.js",
+      "default": "./src/v6/index.js"
+    }
   },
   "files": [
-    "src",
+    "src/v6",
+    "src/index.js",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -50,8 +35,6 @@
     "url": "https://github.com/keshavsoft/tally-xml-tdl/issues"
   },
   "dependencies": {
-    "fast-xml-parser": "^5.11.1",
-    "stream-chain": "^4.2.5",
-    "stream-json": "^3.6.0"
+    "fast-xml-parser": "^5.11.1"
   }
 }

package/src/index.js

@@ -1,5 +1,2 @@
-export * from "./v4/index.js";
-export * as v1 from "./v1/index.js";
-export * as v2 from "./v2/index.js";
-export * as v3 from "./v3/index.js";
-export * as v4 from "./v4/index.js";
+export * from "./v6/index.js";
+export * as v6 from "./v6/index.js";

package/src/v6/body.json

@@ -0,0 +1,26 @@
+{
+  "uom": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>Unit</TYPE><FETCH>$$Alias:Name</FETCH>"
+  },
+  "stockItems": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>StockItem</TYPE><FETCH>$$Alias:Name</FETCH>"
+  },
+  "stockItemsWithBaseUnits": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>StockItem</TYPE><FETCH>$$Alias:Name</FETCH><FETCH>BaseUnits</FETCH>"
+  },
+  "ledgerNames": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>Ledger</TYPE><FETCH>$$Alias:Name</FETCH>"
+  },
+  "stockGroups": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>StockGroup</TYPE><FETCH>$$Alias:Name</FETCH>"
+  },
+  "stockGroupsAndParent": {
+    "staticVariables": "<SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>",
+    "tdlMessage": "<TYPE>StockGroup</TYPE><FETCH>$$Alias:Name</FETCH><FETCH>Parent</FETCH>"
+  }
+}

package/src/v6/body.xml

@@ -0,0 +1,25 @@
+<ENVELOPE>
+    <HEADER>
+        <VERSION>1</VERSION>
+        <TALLYREQUEST>Export</TALLYREQUEST>
+        <TYPE>Collection</TYPE>
+        <ID>TDLID</ID>
+    </HEADER>
+
+    <BODY>
+        <DESC>
+            <STATICVARIABLES>
+            <SVEXPORTFORMAT>$$SysName:XML</SVEXPORTFORMAT>
+                {{STATICVARIABLES}}
+            </STATICVARIABLES>
+
+            <TDL>
+                <TDLMESSAGE>
+                    <COLLECTION NAME="TDLID">
+                        {{TDLMESSAGE}}
+                    </COLLECTION>
+                </TDLMESSAGE>
+            </TDL>
+        </DESC>
+    </BODY>
+</ENVELOPE>

package/src/v6/core/buildXml.js

@@ -0,0 +1,9 @@
+export const buildXml = (body, {
+    staticVariables,
+    tdlMessage
+}) => {
+
+    return body
+        .replace("{{STATICVARIABLES}}", staticVariables)
+        .replace("{{TDLMESSAGE}}", tdlMessage);
+};

package/src/v6/core/cleanTallyResponse.js

@@ -0,0 +1,57 @@
+export const cleanTallyResponse = (json) => {
+
+    const collection = json?.ENVELOPE?.BODY?.DATA?.COLLECTION;
+
+    if (!collection) {
+        return [];
+    }
+
+    const key = Object.keys(collection).find(
+        key => Array.isArray(collection[key])
+    );
+
+    if (!key) {
+        return [];
+    }
+
+    const rows = collection[key];
+
+    return rows.map(row => {
+
+        const result = {};
+
+        for (const [key, value] of Object.entries(row)) {
+
+            // Remove Tally/XML metadata
+            if (key === "@_RESERVEDNAME") {
+                continue;
+            }
+
+            // Keep NAME simple
+            if (key === "@_NAME") {
+                result.NAME = value;
+                continue;
+            }
+
+            // Handle XML parser objects like:
+            // { "#text": "kgs", "@_TYPE": "String" }
+            if (
+                value &&
+                typeof value === "object" &&
+                "#text" in value
+            ) {
+                result[key] = value["#text"];
+                continue;
+            }
+
+            result[key] = value;
+        }
+
+        // If only NAME exists, return the NAME itself
+        if (Object.keys(result).length === 1 && result.NAME !== undefined) {
+            return result.NAME;
+        }
+
+        return result;
+    });
+};

package/src/{v4 → v6}/core/execute/executeXml.js

@@ -1,5 +1,4 @@
 // src/v4/core/execute/executeXml.js
-
 import { sendXml } from "../transport/http.js";
 import { xmlToJson } from "../response/xmlToJson.js";
 
@@ -9,5 +8,7 @@ export const executeXml = async (
 ) => {
     const rawXml = await sendXml({ xml, url });
 
-    return xmlToJson(rawXml);
+    const json = xmlToJson(rawXml);
+
+    return json;
 };

package/src/v6/core/execute/executeXmlAndClean.js

@@ -0,0 +1,15 @@
+// src/v4/core/execute/executeXml.js
+import { cleanTallyResponse } from "../cleanTallyResponse.js";
+import { sendXml } from "../transport/http.js";
+import { xmlToJson } from "../response/xmlToJson.js";
+
+export const executeXmlAndClean = async (
+    xml,
+    { url = "http://localhost:9000" } = {}
+) => {
+    const rawXml = await sendXml({ xml, url });
+
+    const json = xmlToJson(rawXml);
+
+    return cleanTallyResponse(json);
+};

package/src/v6/core/execute/index.js

@@ -0,0 +1,3 @@
+export { executeXml } from "./executeXml.js";
+export { executeXmlAndClean } from "./executeXmlAndClean.js";
+

package/src/v6/core/index.js

@@ -0,0 +1,20 @@
+// Sub-modules
+export * as transport from "./transport/index.js";
+export * as response from "./response/index.js";
+export * as execute from "./execute/index.js";
+
+// Direct Core Exports
+export {
+    sendXml,
+    sendToTally
+} from "./transport/index.js";
+
+export {
+    xmlToJson
+} from "./response/index.js";
+
+export {
+    executeXml,
+    executeXmlAndClean
+} from "./execute/index.js";
+

package/src/v6/core/response/index.js

@@ -0,0 +1,2 @@
+export { xmlToJson } from "./xmlToJson.js";
+

package/src/v6/index.d.ts

@@ -0,0 +1,8 @@
+export interface V6Options {
+    company: string;
+    jsonId: string;
+    url?: string;
+}
+
+export function get<T = any>(options?: V6Options): Promise<T>;
+export function clean<T = any>(options?: V6Options): Promise<T>;

package/src/v6/index.js

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { executeXml, executeXmlAndClean } from "./core/index.js";
+import { buildXml } from "./core/buildXml.js";
+import bodyJson from "./body.json" with {type: "json"};
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const body = fs.readFileSync(path.join(__dirname, "body.xml"), "utf8");
+
+const get = (options = {}) => {
+    const company = options.company;
+    const jsonId = options.jsonId;
+
+    const { tdlMessage } = bodyJson[jsonId];
+
+    const staticVariables = `<SVCURRENTCOMPANY>${company}</SVCURRENTCOMPANY>`;
+
+    const xml = buildXml(body, {
+        staticVariables,
+        tdlMessage
+    });
+
+    return executeXml(xml, options);
+};
+
+const clean = (options = {}) => {
+    const company = options.company;
+    const jsonId = options.jsonId;
+
+    const { tdlMessage } = bodyJson[jsonId];
+
+    const staticVariables = `<SVCURRENTCOMPANY>${company}</SVCURRENTCOMPANY>`;
+
+    const xml = buildXml(body, {
+        staticVariables,
+        tdlMessage
+    });
+
+    return executeXmlAndClean(xml, options);
+};
+
+export { get, clean };