mongo-tson-sdk 🚀

Unified Bi-directional MongoDB $\leftrightarrow$ TSON (Token-Structured Object Notation) Converter & Parser SDK for LLMs & RAG Pipelines.

Cuts 50% of prompt input tokens and 50% of AI output generation tokens when communicating between MongoDB and AI models like Gemini, OpenAI GPT-4o, Claude, and Llama.

💡 Why mongo-tson-sdk?

When building AI Agents or RAG pipelines with MongoDB:

1. Read Path Bloat: Sending raw JSON.stringify() MongoDB outputs into prompts duplicates key names across every record.
2. Write Path Latency & Cost: Forcing LLMs to reply in verbose JSON increases output costs by 3x to 4x and doubles generation latency.

mongo-tson-sdk provides a single unified SDK to handle both directions:

• mongoToTson(): Serializes MongoDB records into columnar TSON for prompt inputs.
• tsonToMongo(): Parses LLM TSON responses into MongoDB write payloads, filters, and updates.

📊 Bi-Directional Token Savings Benchmark

| Operation | Standard JSON Format | TSON Format | Token Savings | Speedup | | :--- | :--- | :--- | :--- | :--- | | Read Path (Prompt Context) | ~12,500 tokens | ~5,800 tokens | 6,700 tokens saved | 53.6% Less Input Cost ⚡ | | Write Path (LLM Output) | ~5,800 tokens | ~2,350 tokens | 3,450 tokens saved | ~2.2x Faster Generation ⚡ |

📦 Installation

npm install mongo-tson-sdk
# or
yarn add mongo-tson-sdk
# or
pnpm add mongo-tson-sdk

⚡ Quick Start

1. Read Path: MongoDB $\rightarrow$ TSON (Prompt Context)

import { mongoToTson } from 'mongo-tson-sdk';

// Fetch MongoDB query results
const users = await User.find({ active: true }).lean();

// Convert to compact TSON prompt context
const tsonPrompt = mongoToTson(users, { trackSavings: true });

console.log(tsonPrompt);
/*
_id: 64f123456789, 64f12345678a
name: Abhi Asok, Sarah Chen
email: [email protected], [email protected]
role: Architect, AI Engineer
*/

2. Write Path: LLM TSON Response $\rightarrow$ MongoDB Writes

import { tsonToMongo } from 'mongo-tson-sdk';

// Prompt LLM to output in TSON
const prompt = "Extract user records and reply strictly in TSON format with headers: name, email, role, status.";
const response = await model.generateContent(prompt);

// Convert AI TSON output directly into MongoDB documents
const mongoDocs = tsonToMongo(response.response.text(), {
  restoreDates: true,
  trackSavings: true
});

// Insert straight to MongoDB!
await db.collection('users').insertMany(mongoDocs);

3. Generate Query Filters & Update Pipelines

import { tsonToMongoFilter, tsonToMongoUpdate } from 'mongo-tson-sdk';

// Generate Query Filter
const filterTson = "status: active, pending\nrole: Architect";
const filter = tsonToMongoFilter(filterTson);
// Output: { status: { $in: ['active', 'pending'] }, role: 'Architect' }

// Generate $set Update Payload
const updateTson = "status: completed\npaidAt: 2026-08-27T15:45:00.000Z";
const update = tsonToMongoUpdate(updateTson);
// Output: { $set: { status: 'completed', paidAt: Date(...) } }

4. Interactive Terminal Demo & Token Tracker

Run the terminal demonstration to verify both directions:

npm run demo

Check cumulative token savings logged automatically in SAVINGS_TRACKER.json:

import { getGlobalSavingsTracker } from 'mongo-tson-sdk';

const tracker = getGlobalSavingsTracker();
console.log(tracker.getStats());

🛠️ API Reference

| Function | Direction | Description | | :--- | :--- | :--- | | mongoToTson(data, options?) | MongoDB -> TSON | Converts documents/arrays/cursors to TSON prompt strings. | | tsonToMongo(tsonStr, options?) | TSON -> MongoDB | Parses TSON strings back into MongoDB objects / document arrays. | | tsonToMongoFilter(tsonStr, options?) | TSON -> Filter | Converts TSON strings into MongoDB $in filter query objects. | | tsonToMongoUpdate(tsonStr, options?) | TSON -> Update | Converts TSON strings into MongoDB $set update pipeline objects. | | streamMongoToTson(cursor, options?) | Stream -> TSON | Transforms MongoDB node streams / AsyncIterables into TSON chunks. |

👤 Author & Contact

Developed with ❤️ by Abhi Asok.

For business inquiries, collaboration, or support:

• 📧 Email: [email protected]
• 📞 Phone / WhatsApp: +91 9142125724
• 💼 LinkedIn: linkedin.com/in/abhi-asok-09439788
• 🐙 GitHub: github.com/AbhiArvension

📄 License

MIT © Abhi Asok