tson-psql 🚀

Advanced TSON to PostgreSQL Query Generator & Type Caster.

Convert TSON (Token-Structured Object Notation) responses from LLMs like Gemini, OpenAI GPT-4o, Claude, and Llama directly into Parameterized PostgreSQL Queries (INSERT, ON CONFLICT DO UPDATE, UPDATE, WHERE) with RETURNING * and native PostgreSQL type safety.

Cuts AI output generation costs & latency by 30% to 50%!

💡 Why tson-psql?

When requesting database writes or PostgreSQL queries from an LLM:

• ❌ High Output Costs: LLM output tokens cost 3x to 4x more than prompt input tokens.
• ❌ Slow Output Speed: Generating full JSON arrays or raw SQL strings with repeating column names doubles generation latency.
• ❌ SQL Injection Risk: Direct raw SQL string generation from LLMs can expose your database to injection vulnerabilities.

tson-psql instructs your AI model to reply in compact TSON format, and safely generates parameterized PostgreSQL queries ($1, $2) with native support for RETURNING * and ON CONFLICT upserts.

📊 Token Savings & Speed Benchmark

| LLM Output Target | Standard JSON Output | TSON Output | Output Tokens Saved | Speedup | | :--- | :--- | :--- | :--- | :--- | | Extract 10 Rows | ~1,200 tokens | ~610 tokens | 590 tokens | ~2.0x Faster ⚡ | | Extract 50 Rows | ~5,800 tokens | ~2,350 tokens | 3,450 tokens | ~2.2x Faster ⚡ | | PostgreSQL Upsert | ~300 tokens | ~140 tokens | 160 tokens | ~2.1x Faster ⚡ |

📦 Installation

npm install tson-psql
# or
yarn add tson-psql
# or
pnpm add tson-psql

⚡ Quick Start

1. Generate Parameterized PostgreSQL INSERT Query

import { tsonToPsqlInsert } from 'tson-psql';
import { Pool } from 'pg';

const pool = new Pool();

// TSON response received from LLM
const llmTsonOutput = `
first_name: Abhi, Sarah
last_name: Asok, Chen
email: [email protected], [email protected]
role: Architect, AI Engineer
`;

// Generate Parameterized PostgreSQL Query
const query = tsonToPsqlInsert(llmTsonOutput, {
  tableName: 'users',
  returning: true
});

console.log(query.text);
// Output: INSERT INTO "users" ("first_name", "last_name", "email", "role") VALUES ($1, $2, $3, $4), ($5, $6, $7, $8) RETURNING *;

console.log(query.values);
// Output: ['Abhi', 'Asok', '[email protected]', 'Architect', 'Sarah', 'Chen', '[email protected]', 'AI Engineer']

// Execute safely with pg pool!
const result = await pool.query(query.text, query.values);

2. Generate PostgreSQL ON CONFLICT DO UPDATE (Upsert) Query

import { tsonToPsqlUpsert } from 'tson-psql';

const upsertQuery = tsonToPsqlUpsert(llmTsonOutput, {
  tableName: 'users',
  conflictColumns: ['email']
});

console.log(upsertQuery.text);
// INSERT INTO "users" (...) VALUES (...) RETURNING * ON CONFLICT ("email") DO UPDATE SET "first_name" = EXCLUDED."first_name", "last_name" = EXCLUDED."last_name", "role" = EXCLUDED."role";

3. Generate Parameterized PostgreSQL UPDATE Query

import { tsonToPsqlUpdate } from 'tson-psql';

const tsonUpdate = `
id: 42
status: completed
updatedAt: 2026-08-27T17:05:00.000Z
`;

const updateQuery = tsonToPsqlUpdate(tsonUpdate, {
  tableName: 'orders',
  whereColumns: ['id']
});

console.log(updateQuery.text);
// Output: UPDATE "orders" SET "status" = $1, "updatedAt" = $2 WHERE "id" = $3;

4. Interactive Terminal Demo

Run the interactive CLI demonstration:

npm run demo

Check cumulative token savings logged automatically in SAVINGS_TRACKER.json:

import { getGlobalSavingsTracker } from 'tson-psql';

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

🛠️ API Reference

| Function | Output | Description | | :--- | :--- | :--- | | tsonToPsql(tsonStr, options?) | Record<string, any>[] | Parses TSON string into JavaScript PostgreSQL row objects. | | tsonToPsqlInsert(tsonStr, options?) | { text, values, columns } | Generates parameterized PostgreSQL INSERT statements ($1, $2) with RETURNING *. | | tsonToPsqlUpsert(tsonStr, options) | { text, values } | Generates PostgreSQL ON CONFLICT DO UPDATE queries. | | tsonToPsqlUpdate(tsonStr, options?) | { text, values } | Generates parameterized PostgreSQL UPDATE statements. | | tsonToPsqlWhere(tsonStr, options?) | { text, values } | Generates PostgreSQL WHERE filter clauses. |

👤 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