tally-xml-tdl 1.13.2 → 1.15.1

package/README.md

@@ -1,175 +1,175 @@
-# 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
-
+# 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,15 +1,15 @@
-export function company(showLog?: boolean): Promise<any>;
-export default company;
-
-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";
-export * as v13 from "./src/v13/main.js";
-
+export function company(showLog?: boolean): Promise<any>;
+export default company;
+
+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";
+export * as v13 from "./src/v13/main.js";
+

package/package.json

@@ -1,32 +1,21 @@
 {
   "name": "tally-xml-tdl",
-  "version": "1.13.2",
+  "version": "1.15.1",
   "description": "Simple, clean TDL and XML extraction and manipulation tools for Tally",
   "type": "module",
-  "main": "src/v13/main.js",
-  "module": "./src/v13/main.js",
+  "main": "src/v15/main.js",
+  "module": "./src/v15/main.js",
   "types": "index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./src/v13/main.js",
-      "default": "./src/v13/main.js"
-    },
-    "./v13": {
-      "types": "./src/v13/main.d.ts",
-      "import": "./src/v13/main.js",
-      "default": "./src/v13/main.js"
-    },
-    "./v6": {
-      "types": "./src/v6/index.d.ts",
-      "import": "./src/v6/index.js",
-      "default": "./src/v6/index.js"
+      "import": "./src/v15/main.js",
+      "default": "./src/v15/main.js"
     }
   },
   "files": [
-    "src/v13",
-    "src/v6",
+    "src/v15",
     "src/index.js",
     "index.js",
     "index.d.ts",

package/src/index.js

@@ -1,2 +1,2 @@
-export * from "./v13/main.js";
-export * as v13 from "./v13/main.js";
+export * from "./v15/main.js";
+export * as masters from "./v15/masters.js";

package/src/{v13 → v15}/company.js

@@ -11,6 +11,7 @@ const body = fs.readFileSync(path.join(__dirname, "body.xml"), "utf8");
 
 const startFunc = async (showLog = false) => {
     const jsonId = "company";
+    // console.log("------------ : ", jsonId);
 
     const { tdlMessage } = bodyJson[jsonId];
     if (showLog) console.log("tdlMessage : ", tdlMessage);
@@ -18,11 +19,12 @@ const startFunc = async (showLog = false) => {
     const xml = buildXml(body, {
         tdlMessage
     });
+
     if (showLog) console.log("xml : ", xml);
+
     const jsonToReturn = await executeXmlAndClean(xml);
+
     if (showLog) console.log("jsonToReturn : ", jsonToReturn);
-    // const firstRow = jsonToReturn[0];
-    // const { "@_NAME": name, "@_RESERVEDNAME": reservedName } = firstRow;
 
     return jsonToReturn;
 };

package/src/{v13 → v15}/core/changeType/v1/changeTypeString.js

@@ -1,111 +1,111 @@
-/**
- * The Story of Tally Type Conversion:
- *
- * Act 1 - The XML Artifacts:
- *   Tally XML represents typed primitive fields with attributes such as `@_TYPE="String"`,
- *   `@_TYPE="Date"`, or `@_TYPE="Logical"`. The XML parser converts these tags into
- *   objects where `#text` holds the actual content and `@_TYPE` holds the data type.
- *   Tags with empty content (e.g. <SERIALMASTER TYPE="String"/>) result in objects
- *   containing only `@_TYPE` without a `#text` key.
- *
- * Act 2 - The String Story:
- *   When `@_TYPE === "String"`, we extract `#text` as a clean string.
- *   If `#text` is missing (empty element), we normalize it to an empty string `""`
- *   rather than keeping the unparsed metadata object.
- *
- * Act 3 - The Date Story:
- *   When `@_TYPE === "Date"`, Tally returns dates in YYYYMMDD format (e.g., 20260904).
- *   XML parsers often parse this as a numeric literal (20260904). We safely normalize
- *   this into a clean string representation `'20260904'` for consistent date formatting.
- *
- * Act 4 - Logical & Other Primitives:
- *   When `@_TYPE === "Logical"` (values like 'Yes' / 'No') or other typed fields,
- *   we unwrap `#text` to its plain scalar value while leaving nested child arrays
- *   (e.g., inventory lines, ledger entries) intact.
- */
-
-/**
- * Normalizes a single field value based on its Tally XML type.
- *
- * @param {object} params
- * @param {*} params.inValue - The field value to inspect and transform.
- * @returns {*} The cleaned scalar or original complex structure.
- */
-const handleValue = ({ inValue }) => {
-    const localValue = inValue;
-
-    // Preserve null, undefined, primitives, and nested arrays (e.g. ALLINVENTORYENTRIES.LIST)
-    if (!localValue || typeof localValue !== "object" || Array.isArray(localValue)) {
-        return localValue;
-    }
-
-    // Process Tally typed objects with @_TYPE
-    if ("@_TYPE" in localValue) {
-        const type = localValue["@_TYPE"];
-        const hasText = "#text" in localValue;
-        const rawText = localValue["#text"];
-
-        // Act 2 fallback: Empty tags (<FIELD TYPE="..."/>) have no #text
-        if (!hasText) {
-            return "";
-        }
-
-        switch (type) {
-            // Act 2: String types
-            case "String":
-                return String(rawText);
-
-            // Act 3: Date types (normalize numbers like 20260904 to string '20260904')
-            case "Date":
-                return String(rawText);
-
-            // Act 4: Logical types ('Yes' / 'No')
-            case "Logical":
-                return String(rawText);
-
-            // Other types (Number, Amount, Rate, etc.)
-            default:
-                return rawText;
-        }
-    }
-
-    return localValue;
-};
-
-/**
- * Transforms an array of rows by converting Tally typed objects into clean values.
- *
- * @param {object|Array} input - Either { inArray: Array } or positional Array.
- * @returns {Array} Array of cleaned rows.
- */
-const changeTypeString = (input) => {
-    // Supports both { inArray } parameter convention and direct array argument
-    let localArray = Array.isArray(input) ? input : input?.inArray;
-
-    if (!localArray) {
-        return [];
-    }
-
-    if (!Array.isArray(localArray)) {
-        localArray = [localArray];
-    }
-
-    const newArray = localArray.map(row => {
-        if (!row || typeof row !== "object") {
-            return row;
-        }
-
-        const result = {};
-
-        for (const [key, value] of Object.entries(row)) {
-            result[key] = handleValue({ inValue: value });
-        }
-
-        return result;
-    });
-
-    return newArray;
-};
-
-export default changeTypeString;
-export { changeTypeString };
+/**
+ * The Story of Tally Type Conversion:
+ *
+ * Act 1 - The XML Artifacts:
+ *   Tally XML represents typed primitive fields with attributes such as `@_TYPE="String"`,
+ *   `@_TYPE="Date"`, or `@_TYPE="Logical"`. The XML parser converts these tags into
+ *   objects where `#text` holds the actual content and `@_TYPE` holds the data type.
+ *   Tags with empty content (e.g. <SERIALMASTER TYPE="String"/>) result in objects
+ *   containing only `@_TYPE` without a `#text` key.
+ *
+ * Act 2 - The String Story:
+ *   When `@_TYPE === "String"`, we extract `#text` as a clean string.
+ *   If `#text` is missing (empty element), we normalize it to an empty string `""`
+ *   rather than keeping the unparsed metadata object.
+ *
+ * Act 3 - The Date Story:
+ *   When `@_TYPE === "Date"`, Tally returns dates in YYYYMMDD format (e.g., 20260904).
+ *   XML parsers often parse this as a numeric literal (20260904). We safely normalize
+ *   this into a clean string representation `'20260904'` for consistent date formatting.
+ *
+ * Act 4 - Logical & Other Primitives:
+ *   When `@_TYPE === "Logical"` (values like 'Yes' / 'No') or other typed fields,
+ *   we unwrap `#text` to its plain scalar value while leaving nested child arrays
+ *   (e.g., inventory lines, ledger entries) intact.
+ */
+
+/**
+ * Normalizes a single field value based on its Tally XML type.
+ *
+ * @param {object} params
+ * @param {*} params.inValue - The field value to inspect and transform.
+ * @returns {*} The cleaned scalar or original complex structure.
+ */
+const handleValue = ({ inValue }) => {
+    const localValue = inValue;
+
+    // Preserve null, undefined, primitives, and nested arrays (e.g. ALLINVENTORYENTRIES.LIST)
+    if (!localValue || typeof localValue !== "object" || Array.isArray(localValue)) {
+        return localValue;
+    }
+
+    // Process Tally typed objects with @_TYPE
+    if ("@_TYPE" in localValue) {
+        const type = localValue["@_TYPE"];
+        const hasText = "#text" in localValue;
+        const rawText = localValue["#text"];
+
+        // Act 2 fallback: Empty tags (<FIELD TYPE="..."/>) have no #text
+        if (!hasText) {
+            return "";
+        }
+
+        switch (type) {
+            // Act 2: String types
+            case "String":
+                return String(rawText);
+
+            // Act 3: Date types (normalize numbers like 20260904 to string '20260904')
+            case "Date":
+                return String(rawText);
+
+            // Act 4: Logical types ('Yes' / 'No')
+            case "Logical":
+                return String(rawText);
+
+            // Other types (Number, Amount, Rate, etc.)
+            default:
+                return rawText;
+        }
+    }
+
+    return localValue;
+};
+
+/**
+ * Transforms an array of rows by converting Tally typed objects into clean values.
+ *
+ * @param {object|Array} input - Either { inArray: Array } or positional Array.
+ * @returns {Array} Array of cleaned rows.
+ */
+const changeTypeString = (input) => {
+    // Supports both { inArray } parameter convention and direct array argument
+    let localArray = Array.isArray(input) ? input : input?.inArray;
+
+    if (!localArray) {
+        return [];
+    }
+
+    if (!Array.isArray(localArray)) {
+        localArray = [localArray];
+    }
+
+    const newArray = localArray.map(row => {
+        if (!row || typeof row !== "object") {
+            return row;
+        }
+
+        const result = {};
+
+        for (const [key, value] of Object.entries(row)) {
+            result[key] = handleValue({ inValue: value });
+        }
+
+        return result;
+    });
+
+    return newArray;
+};
+
+export default changeTypeString;
+export { changeTypeString };