tally-xml-tdl 1.4.1

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 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,95 @@
+# 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

package/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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";
+
+
+

package/index.js

@@ -0,0 +1 @@
+export * from "./src/index.js";

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tally-xml-tdl",
+  "version": "1.4.1",
+  "description": "Simple, clean TDL and XML extraction and manipulation tools for Tally",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "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"
+  },
+  "files": [
+    "src",
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://keshavsoft.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keshavsoft/tally-xml-tdl"
+  },
+  "bugs": {
+    "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"
+  }
+}

package/src/index.js

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

package/src/v1/client.js

@@ -0,0 +1,59 @@
+import { xmlToJson } from "./xmlToJson.js";
+import { jsonToXml } from "./jsonToXml.js";
+import { createCollectionEnvelope } from "./envelope.js";
+
+/**
+ * Sends an XML payload to Tally via HTTP POST.
+ * 
+ * @param {object} params
+ * @param {string} params.xml - The XML string to send.
+ * @param {string} [params.url="http://localhost:9000"] - Tally HTTP endpoint URL.
+ * @returns {Promise<object>} Parsed JSON response from Tally.
+ */
+export const sendToTally = async ({
+    xml,
+    url = "http://localhost:9000"
+} = {}) => {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml"
+        },
+        body: xml
+    });
+
+    const text = await res.text();
+    return xmlToJson(text);
+};
+
+/**
+ * High-level helper to fetch any Tally collection directly.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (e.g. 'KeshavGroups')
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Fields to fetch (e.g. ['Name', 'Parent'])
+ * @param {object} [params.filters] - Filters/additional collection properties
+ * @param {object} [params.staticVariables] - Optional static variables
+ * @param {string} [params.url="http://localhost:9000"] - Tally URL
+ * @returns {Promise<object>} Parsed JSON response from Tally
+ */
+export const fetchCollection = async ({
+    name,
+    type,
+    fields,
+    filters,
+    staticVariables,
+    url = "http://localhost:9000"
+} = {}) => {
+    const envelope = createCollectionEnvelope({
+        name,
+        type,
+        fields,
+        filters,
+        staticVariables
+    });
+    const xml = jsonToXml(envelope);
+    return await sendToTally({ xml, url });
+};
+

package/src/v1/envelope.js

@@ -0,0 +1,87 @@
+import { jsonToXml } from "./jsonToXml.js";
+
+/**
+ * Creates a base Tally XML Envelope JavaScript Object.
+ * 
+ * @param {object} [params]
+ * @param {string} [params.id=""] - Collection or Request ID
+ * @param {string} [params.type="COLLECTION"] - Request Type (default "COLLECTION")
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @param {object} [params.tdlMessage] - Object to place inside TDLMESSAGE
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createEnvelope = ({
+    id = "",
+    type = "COLLECTION",
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" },
+    tdlMessage = {}
+} = {}) => {
+    return {
+        ENVELOPE: {
+            HEADER: {
+                VERSION: 1,
+                TALLYREQUEST: "EXPORT",
+                TYPE: type,
+                ID: id
+            },
+            BODY: {
+                DESC: {
+                    STATICVARIABLES: staticVariables,
+                    TDL: {
+                        TDLMESSAGE: tdlMessage
+                    }
+                }
+            }
+        }
+    };
+};
+
+/**
+ * Creates a Tally Collection Request Envelope object.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (used for ID and COLLECTION NAME)
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Field names to FETCH
+ * @param {object} [params.filters] - Additional collection child nodes or filters
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createCollectionEnvelope = ({
+    name,
+    type,
+    fields = [],
+    filters = {},
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" }
+} = {}) => {
+    const fetchValue = Array.isArray(fields)
+        ? fields.join(",\n        ")
+        : (fields || "");
+
+    const collectionDef = {
+        "@_NAME": name,
+        TYPE: type,
+        ...(fetchValue ? { FETCH: fetchValue } : {}),
+        ...filters
+    };
+
+    return createEnvelope({
+        id: name,
+        type: "COLLECTION",
+        staticVariables,
+        tdlMessage: {
+            COLLECTION: collectionDef
+        }
+    });
+};
+
+/**
+ * Helper to build an XML string directly for a collection query.
+ * 
+ * @param {object} options - Options passed to createCollectionEnvelope
+ * @returns {string} XML string ready to send to Tally
+ */
+export const buildCollectionXml = (options) => {
+    return jsonToXml(createCollectionEnvelope(options));
+};
+

package/src/v1/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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>;
+

package/src/v1/index.js

@@ -0,0 +1,12 @@
+export { xmlToJson } from "./xmlToJson.js";
+export { jsonToXml } from "./jsonToXml.js";
+export {
+    createEnvelope,
+    createCollectionEnvelope,
+    buildCollectionXml
+} from "./envelope.js";
+export {
+    sendToTally,
+    fetchCollection
+} from "./client.js";
+

package/src/v1/jsonToXml.js

@@ -0,0 +1,20 @@
+import { XMLBuilder } from "fast-xml-parser";
+
+/**
+ * Converts a JavaScript Object into formatted XML string.
+ * Preserves XML attributes prefixed with `@_`.
+ * 
+ * @param {object} jsonObj - The JavaScript object to serialize.
+ * @param {object} [options] - Optional XMLBuilder configurations.
+ * @returns {string} Formatted XML string.
+ */
+export const jsonToXml = (jsonObj, options = {}) => {
+    const builder = new XMLBuilder({
+        ignoreAttributes: false,
+        format: true,
+        ...options
+    });
+
+    return builder.build(jsonObj);
+};
+

package/src/v1/xmlToJson.js

@@ -0,0 +1,19 @@
+import { XMLParser } from "fast-xml-parser";
+
+/**
+ * Converts XML string into a JavaScript Object.
+ * Preserves XML attributes using the `@_` prefix.
+ * 
+ * @param {string} xml - The XML string to parse.
+ * @param {object} [options] - Optional XMLParser configurations.
+ * @returns {object} The parsed JavaScript object.
+ */
+export const xmlToJson = (xml, options = {}) => {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        ...options
+    });
+
+    return parser.parse(xml);
+};
+

package/src/v2/client.js

@@ -0,0 +1,59 @@
+import { xmlToJson } from "./xmlToJson.js";
+import { jsonToXml } from "./jsonToXml.js";
+import { createCollectionEnvelope } from "./envelope.js";
+
+/**
+ * Sends an XML payload to Tally via HTTP POST.
+ * 
+ * @param {object} params
+ * @param {string} params.xml - The XML string to send.
+ * @param {string} [params.url="http://localhost:9000"] - Tally HTTP endpoint URL.
+ * @returns {Promise<object>} Parsed JSON response from Tally.
+ */
+export const sendToTally = async ({
+    xml,
+    url = "http://localhost:9000"
+} = {}) => {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml"
+        },
+        body: xml
+    });
+
+    const text = await res.text();
+    return xmlToJson(text);
+};
+
+/**
+ * High-level helper to fetch any Tally collection directly.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (e.g. 'KeshavGroups')
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Fields to fetch (e.g. ['Name', 'Parent'])
+ * @param {object} [params.filters] - Filters/additional collection properties
+ * @param {object} [params.staticVariables] - Optional static variables
+ * @param {string} [params.url="http://localhost:9000"] - Tally URL
+ * @returns {Promise<object>} Parsed JSON response from Tally
+ */
+export const fetchCollection = async ({
+    name,
+    type,
+    fields,
+    filters,
+    staticVariables,
+    url = "http://localhost:9000"
+} = {}) => {
+    const envelope = createCollectionEnvelope({
+        name,
+        type,
+        fields,
+        filters,
+        staticVariables
+    });
+    const xml = jsonToXml(envelope);
+    return await sendToTally({ xml, url });
+};
+

package/src/v2/envelope.js

@@ -0,0 +1,87 @@
+import { jsonToXml } from "./jsonToXml.js";
+
+/**
+ * Creates a base Tally XML Envelope JavaScript Object.
+ * 
+ * @param {object} [params]
+ * @param {string} [params.id=""] - Collection or Request ID
+ * @param {string} [params.type="COLLECTION"] - Request Type (default "COLLECTION")
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @param {object} [params.tdlMessage] - Object to place inside TDLMESSAGE
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createEnvelope = ({
+    id = "",
+    type = "COLLECTION",
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" },
+    tdlMessage = {}
+} = {}) => {
+    return {
+        ENVELOPE: {
+            HEADER: {
+                VERSION: 1,
+                TALLYREQUEST: "EXPORT",
+                TYPE: type,
+                ID: id
+            },
+            BODY: {
+                DESC: {
+                    STATICVARIABLES: staticVariables,
+                    TDL: {
+                        TDLMESSAGE: tdlMessage
+                    }
+                }
+            }
+        }
+    };
+};
+
+/**
+ * Creates a Tally Collection Request Envelope object.
+ * 
+ * @param {object} params
+ * @param {string} params.name - Collection name (used for ID and COLLECTION NAME)
+ * @param {string} params.type - Tally Object Type (e.g. 'Group', 'Ledger', 'Company')
+ * @param {string|string[]} [params.fields] - Field names to FETCH
+ * @param {object} [params.filters] - Additional collection child nodes or filters
+ * @param {object} [params.staticVariables] - Static variables for DESC
+ * @returns {object} Tally Envelope JS Object
+ */
+export const createCollectionEnvelope = ({
+    name,
+    type,
+    fields = [],
+    filters = {},
+    staticVariables = { SVEXPORTFORMAT: "$$SysName:XML" }
+} = {}) => {
+    const fetchValue = Array.isArray(fields)
+        ? fields.join(",\n        ")
+        : (fields || "");
+
+    const collectionDef = {
+        "@_NAME": name,
+        TYPE: type,
+        ...(fetchValue ? { FETCH: fetchValue } : {}),
+        ...filters
+    };
+
+    return createEnvelope({
+        id: name,
+        type: "COLLECTION",
+        staticVariables,
+        tdlMessage: {
+            COLLECTION: collectionDef
+        }
+    });
+};
+
+/**
+ * Helper to build an XML string directly for a collection query.
+ * 
+ * @param {object} options - Options passed to createCollectionEnvelope
+ * @returns {string} XML string ready to send to Tally
+ */
+export const buildCollectionXml = (options) => {
+    return jsonToXml(createCollectionEnvelope(options));
+};
+