@ozgurv/tg-db 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+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 whom the Software is
+furnished 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,532 @@
+# Telegram Chat Database (tg-db)
+
+A comprehensive npm package that lets you use Telegram chat as a database. Stores and queries data in chat messages using the Telegram Bot API.
+
+## Features
+
+- **CRUD Operations**: Create, Read, Update, Delete
+- **Table/Collection System**: Database-like table structure (similar to SQL tables or MongoDB collections)
+- **Fluent API**: Chainable usage like `db.table('users').find()`
+- **Advanced Queries**: Filter, find, findOne and similar query methods
+- **Batch Operations**: Bulk document insert and update
+- **Query Operators**: $gt, $gte, $lt, $lte, $ne, $in, $nin, $regex support
+- **Automatic Index**: Tracks message IDs automatically
+- **Cache System**: In-memory cache for performance
+- **TypeScript Support**: Full type safety
+- **Error Handling**: Retry mechanism and error handling
+
+## Installation
+
+```bash
+npm install @ozgurv/tg-db
+```
+
+## Requirements
+
+1. **Telegram Bot Token**: Create a bot via [@BotFather](https://t.me/botfather) and get a token
+2. **Chat ID**: The chat where data will be stored (add your bot to that chat)
+
+### How to Find Chat ID
+
+- **Private Chat**: Start a private chat with your bot; chat ID is usually a positive number
+- **Group/Channel**: Add the bot to the group/channel; chat ID is usually negative (e.g. `-1001234567890`)
+
+## Quick Start
+
+```typescript
+import { TelegramDB } from '@ozgurv/tg-db';
+
+// Initialize database
+const db = new TelegramDB({
+  botToken: 'YOUR_BOT_TOKEN',
+  chatId: 'YOUR_CHAT_ID', // or number: 123456789
+});
+
+// Connect
+await db.initialize();
+
+// Insert document (table is required)
+const result = await db.insert({
+  name: 'John',
+  age: 30,
+  city: 'New York'
+}, 'users'); // add to 'users' table
+
+console.log(result.data); // inserted document
+
+// Find documents (table is required)
+const users = await db.find({ city: 'New York' }, 'users');
+console.log(users);
+
+// Or use Fluent API (recommended)
+const usersTable = db.table('users');
+const users2 = await usersTable.find({ city: 'New York' });
+
+// Update document
+await db.update(
+  { name: 'John' },
+  { age: 31 },
+  'users'
+);
+
+// Delete document
+await db.delete({ name: 'John' }, 'users');
+```
+
+## API Documentation
+
+### `TelegramDB(config)`
+
+Creates the database instance.
+
+**Parameters:**
+
+- `botToken` (string, required): Telegram bot token
+- `chatId` (string | number, required): Chat ID where data will be stored
+- `messagePrefix` (string, optional): Message prefix (default: "TDB:")
+- `batchDelay` (number, optional): Delay between batch operations in ms (default: 100)
+- `maxRetries` (number, optional): Maximum retry count (default: 3)
+
+### Methods
+
+#### `initialize(): Promise<void>`
+
+Establishes the database connection. Must be called before use.
+
+```typescript
+await db.initialize();
+```
+
+#### `insert(doc: Partial<Document>, table: string): Promise<OperationResult>`
+
+Inserts a new document. **Every document must belong to a table.**
+
+```typescript
+const result = await db.insert({
+  name: 'John',
+  email: 'john@example.com'
+}, 'users'); // add to 'users' table
+
+if (result.success) {
+  console.log('Document inserted:', result.data);
+}
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.insert({ name: 'John', email: 'john@example.com' });
+```
+
+#### `insertMany(docs: Partial<Document>[], table: string, options?): Promise<OperationResult[]>`
+
+Inserts multiple documents.
+
+```typescript
+const results = await db.insertMany([
+  { name: 'Alice', age: 25 },
+  { name: 'Bob', age: 28 },
+  { name: 'Carol', age: 30 }
+], 'users', {
+  delay: 200, // wait 200ms between each insert
+  stopOnError: false // continue even on error
+});
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.insertMany([...], { delay: 200 });
+```
+
+#### `find(filter?: QueryFilter, table: string): Promise<Document[]>`
+
+Finds all documents matching the filter. **Table is required.**
+
+```typescript
+// All documents (from a specific table)
+const allDocs = await db.find({}, 'users');
+
+// Simple filter
+const users = await db.find({ city: 'London' }, 'users');
+
+// Advanced filters
+const adults = await db.find({
+  age: { $gte: 18 }
+}, 'users');
+
+// Or with Fluent API (recommended):
+const users = db.table('users');
+const allUsers = await users.find();
+const londonUsers = await users.find({ city: 'London' });
+```
+
+#### `findOne(filter?: QueryFilter, table: string): Promise<Document | null>`
+
+Finds the first document matching the filter. **Table is required.**
+
+```typescript
+const user = await db.findOne({ name: 'John' }, 'users');
+
+// Or with Fluent API:
+const users = db.table('users');
+const user = await users.findOne({ name: 'John' });
+```
+
+#### `findById(id: string, table: string): Promise<Document | null>`
+
+Finds a document by ID. **Table is required.**
+
+```typescript
+const doc = await db.findById('1234567890-abc123', 'users');
+
+// Or with Fluent API:
+const users = db.table('users');
+const doc = await users.findById('1234567890-abc123');
+```
+
+#### `update(filter: QueryFilter, update: Partial<Document>, table: string, options?): Promise<OperationResult>`
+
+Updates documents. **Table is required.**
+
+```typescript
+// Simple update
+await db.update(
+  { name: 'John' },
+  { age: 32 },
+  'users'
+);
+
+// Upsert (create if not exists)
+await db.update(
+  { name: 'New User' },
+  { age: 25, city: 'Paris' },
+  'users',
+  { upsert: true }
+);
+
+// Replace entire document
+await db.update(
+  { _id: '123' },
+  { name: 'New Name', age: 30 },
+  'users',
+  { replace: true }
+);
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.update({ name: 'John' }, { age: 32 });
+```
+
+#### `updateById(id: string, update: Partial<Document>, table: string, options?): Promise<OperationResult>`
+
+Updates a document by ID. **Table is required.**
+
+```typescript
+await db.updateById('1234567890-abc123', { age: 33 }, 'users');
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.updateById('1234567890-abc123', { age: 33 });
+```
+
+#### `delete(filter: QueryFilter, table: string): Promise<OperationResult>`
+
+Deletes documents. **Table is required.**
+
+```typescript
+// Delete by filter
+await db.delete({ city: 'London' }, 'users');
+
+// Delete all documents (from a specific table)
+await db.deleteAll('users');
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.delete({ city: 'London' });
+await users.deleteAll();
+```
+
+#### `deleteById(id: string, table: string): Promise<OperationResult>`
+
+Deletes a document by ID. **Table is required.**
+
+```typescript
+await db.deleteById('1234567890-abc123', 'users');
+
+// Or with Fluent API:
+const users = db.table('users');
+await users.deleteById('1234567890-abc123');
+```
+
+#### `count(filter?: QueryFilter, table: string): Promise<number>`
+
+Returns document count. **Table is required.**
+
+```typescript
+const total = await db.count({}, 'users');
+const londonUsers = await db.count({ city: 'London' }, 'users');
+
+// Or with Fluent API:
+const users = db.table('users');
+const total = await users.count();
+const londonUsers = await users.count({ city: 'London' });
+```
+
+#### `getTables(): Promise<string[]>`
+
+Returns all table names.
+
+```typescript
+const tables = await db.getTables();
+console.log('Tables:', tables); // ['users', 'products', 'orders']
+```
+
+#### `dropTable(table: string): Promise<OperationResult>`
+
+Drops a table completely.
+
+```typescript
+await db.dropTable('old_table');
+```
+
+#### `table(tableName: string): TableHandler`
+
+Returns a table handler for Fluent API. **Recommended usage.**
+
+```typescript
+const users = db.table('users');
+await users.insert({ name: 'John' });
+const user = await users.findOne({ name: 'John' });
+await users.update({ name: 'John' }, { age: 30 });
+await users.delete({ name: 'John' });
+```
+
+#### `getStats(table?: string): Promise<DatabaseStats>`
+
+Returns database statistics. If table is specified, returns stats for that table only.
+
+```typescript
+// All database statistics
+const stats = await db.getStats();
+console.log(`Total documents: ${stats.totalDocuments}`);
+
+// Specific table statistics
+const userStats = await db.getStats('users');
+console.log(`Users table: ${userStats.totalDocuments} documents`);
+```
+
+#### `clear(): Promise<OperationResult>`
+
+Clears all data.
+
+```typescript
+await db.clear();
+```
+
+#### `close(): Promise<void>`
+
+Closes the database connection.
+
+```typescript
+await db.close();
+```
+
+## Query Operators
+
+Use these operators for advanced queries:
+
+```typescript
+const users = db.table('users');
+
+// Greater than
+await users.find({ age: { $gt: 18 } });
+
+// Greater than or equal
+await users.find({ age: { $gte: 18 } });
+
+// Less than
+await users.find({ age: { $lt: 65 } });
+
+// Less than or equal
+await users.find({ age: { $lte: 65 } });
+
+// Not equal
+await users.find({ status: { $ne: 'deleted' } });
+
+// In
+await users.find({ city: { $in: ['London', 'Paris', 'Berlin'] } });
+
+// Not in
+await users.find({ city: { $nin: ['Paris'] } });
+
+// Regex
+await users.find({ email: { $regex: '@gmail\\.com$' } });
+
+// Exists
+await users.find({ phone: { $exists: true } });
+```
+
+## Nested Fields
+
+Query nested fields using dot notation:
+
+```typescript
+const result = await db.insert({
+  name: 'John',
+  address: {
+    city: 'London',
+    district: 'Westminster'
+  }
+}, 'users');
+
+const docs = await db.find({ 'address.city': 'London' }, 'users');
+```
+
+## Table/Collection System
+
+Every document must belong to a table. This lets you organize data and use it like a real database.
+
+### Two Usage Styles
+
+**1. Direct methods (table specified in each call):**
+
+```typescript
+await db.insert({ name: 'John' }, 'users');
+await db.find({}, 'users');
+await db.update({ name: 'John' }, { age: 30 }, 'users');
+await db.delete({ name: 'John' }, 'users');
+```
+
+**2. Fluent API (recommended - cleaner code):**
+
+```typescript
+const users = db.table('users');
+await users.insert({ name: 'John' });
+await users.find({});
+await users.update({ name: 'John' }, { age: 30 });
+await users.delete({ name: 'John' });
+```
+
+### Table Operations
+
+```typescript
+// List all tables
+const tables = await db.getTables();
+console.log(tables); // ['users', 'products', 'orders']
+
+// Drop a table
+await db.dropTable('old_table');
+
+// Table statistics
+const stats = await db.getStats('users');
+```
+
+## Examples
+
+### Todo List Application
+
+```typescript
+import { TelegramDB } from '@ozgurv/tg-db';
+
+const db = new TelegramDB({
+  botToken: process.env.BOT_TOKEN!,
+  chatId: process.env.CHAT_ID!
+});
+
+await db.initialize();
+
+// Fluent API (recommended)
+const todos = db.table('todos');
+
+// Add todo
+await todos.insert({
+  task: 'Buy groceries',
+  completed: false,
+  createdAt: new Date().toISOString()
+});
+
+// Get incomplete todos
+const incompleteTodos = await todos.find({ completed: false });
+
+// Mark todo as completed
+await todos.update(
+  { task: 'Buy groceries' },
+  { completed: true }
+);
+```
+
+### User Management
+
+```typescript
+// Fluent API (recommended)
+const users = db.table('users');
+
+// Create user
+await users.insert({
+  username: 'johndoe',
+  email: 'john@example.com',
+  role: 'user',
+  createdAt: Date.now()
+});
+
+// Find admin users
+const admins = await users.find({ role: 'admin' });
+
+// Find user by email
+const user = await users.findOne({ email: 'john@example.com' });
+
+// Update user
+await users.update(
+  { username: 'johndoe' },
+  { role: 'admin' }
+);
+```
+
+### Multiple Tables
+
+```typescript
+const users = db.table('users');
+const products = db.table('products');
+const orders = db.table('orders');
+
+// Add to users table
+await users.insert({ name: 'John', email: 'john@example.com' });
+
+// Add to products table
+await products.insert({ name: 'Laptop', price: 1000, stock: 5 });
+
+// Add to orders table
+await orders.insert({
+  userId: '123',
+  productId: '456',
+  quantity: 2,
+  total: 2000
+});
+
+// Each table works independently
+const allUsers = await users.find();
+const allProducts = await products.find();
+const allOrders = await orders.find();
+```
+
+## Limitations
+
+1. **Telegram API Limits**: The Telegram API has rate limits. Use batch delay for heavy operations.
+2. **Message Size**: Telegram messages are limited to 4096 characters. Large documents may need to be split.
+3. **Message History**: The Telegram Bot API cannot fetch old messages directly. A message index is used instead.
+4. **Bot Permissions**: The bot needs permission to delete messages for delete operations.
+
+## Security
+
+- Never share your bot token
+- Keep your chat ID private
+- Do not store sensitive data without encryption
+- Use environment variables:
+
+```typescript
+const db = new TelegramDB({
+  botToken: process.env.BOT_TOKEN!,
+  chatId: process.env.CHAT_ID!
+});
+```
+
+## License
+
+MIT License

package/dist/TableHandler.d.ts

@@ -0,0 +1,20 @@
+import { TelegramDB } from './TelegramDB';
+import { Document, QueryFilter, UpdateOptions, OperationResult, BatchOptions } from './types';
+/** Table/collection handler for fluent API usage */
+export declare class TableHandler {
+    private db;
+    private tableName;
+    constructor(db: TelegramDB, tableName: string);
+    insert(doc: Partial<Document>): Promise<OperationResult>;
+    insertMany(docs: Partial<Document>[], options?: BatchOptions): Promise<OperationResult[]>;
+    find(filter?: QueryFilter): Promise<Document[]>;
+    findOne(filter?: QueryFilter): Promise<Document | null>;
+    findById(id: string): Promise<Document | null>;
+    update(filter: QueryFilter, update: Partial<Document>, options?: UpdateOptions): Promise<OperationResult>;
+    updateById(id: string, update: Partial<Document>, options?: UpdateOptions): Promise<OperationResult>;
+    delete(filter: QueryFilter): Promise<OperationResult>;
+    deleteById(id: string): Promise<OperationResult>;
+    deleteAll(): Promise<OperationResult>;
+    count(filter?: QueryFilter): Promise<number>;
+    getTableName(): string;
+}

package/dist/TableHandler.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableHandler = void 0;
+/** Table/collection handler for fluent API usage */
+class TableHandler {
+    constructor(db, tableName) {
+        this.db = db;
+        this.tableName = tableName;
+    }
+    async insert(doc) {
+        return this.db.insert(doc, this.tableName);
+    }
+    async insertMany(docs, options) {
+        return this.db.insertMany(docs, this.tableName, options);
+    }
+    async find(filter = {}) {
+        return this.db.find(filter, this.tableName);
+    }
+    async findOne(filter = {}) {
+        return this.db.findOne(filter, this.tableName);
+    }
+    async findById(id) {
+        return this.db.findById(id, this.tableName);
+    }
+    async update(filter, update, options) {
+        return this.db.update(filter, update, this.tableName, options);
+    }
+    async updateById(id, update, options) {
+        return this.db.updateById(id, update, this.tableName, options);
+    }
+    async delete(filter) {
+        return this.db.delete(filter, this.tableName);
+    }
+    async deleteById(id) {
+        return this.db.deleteById(id, this.tableName);
+    }
+    async deleteAll() {
+        return this.db.deleteAll(this.tableName);
+    }
+    async count(filter = {}) {
+        return this.db.count(filter, this.tableName);
+    }
+    getTableName() {
+        return this.tableName;
+    }
+}
+exports.TableHandler = TableHandler;

package/dist/TelegramDB.d.ts

@@ -0,0 +1,61 @@
+import { TelegramDBConfig, Document, QueryFilter, UpdateOptions, OperationResult, BatchOptions, DatabaseStats } from './types';
+import { TableHandler } from './TableHandler';
+/** Uses Telegram chat messages to store and retrieve data */
+export declare class TelegramDB {
+    private bot;
+    private chatId;
+    private prefix;
+    private batchDelay;
+    private maxRetries;
+    private initialized;
+    private messageIndex;
+    private documentCache;
+    private indexMessageId;
+    constructor(config: TelegramDBConfig);
+    /** Initialize database connection. Must be called before use. */
+    initialize(): Promise<void>;
+    /** Insert a new document into a table */
+    insert(doc: Partial<Document>, table: string): Promise<OperationResult>;
+    /** Insert multiple documents into a table */
+    insertMany(docs: Partial<Document>[], table: string, options?: BatchOptions): Promise<OperationResult[]>;
+    /** Find documents matching the filter in a table */
+    find(filter: QueryFilter | undefined, table: string): Promise<Document[]>;
+    /** Find a single document matching the filter in a table */
+    findOne(filter: QueryFilter | undefined, table: string): Promise<Document | null>;
+    /** Find document by ID in a table */
+    findById(id: string, table: string): Promise<Document | null>;
+    /** Update documents matching the filter in a table */
+    update(filter: QueryFilter, update: Partial<Document>, table: string, options?: UpdateOptions): Promise<OperationResult>;
+    /** Update a single document by ID in a table */
+    updateById(id: string, update: Partial<Document>, table: string, options?: UpdateOptions): Promise<OperationResult>;
+    /** Delete documents matching the filter in a table */
+    delete(filter: QueryFilter, table: string): Promise<OperationResult>;
+    /** Delete a single document by ID in a table */
+    deleteById(id: string, table: string): Promise<OperationResult>;
+    /** Delete all documents in a table */
+    deleteAll(table: string): Promise<OperationResult>;
+    /** Count documents matching the filter in a table */
+    count(filter: QueryFilter | undefined, table: string): Promise<number>;
+    /** Get all table names in the database */
+    getTables(): Promise<string[]>;
+    /** Tabloyu tamamen siler */
+    dropTable(table: string): Promise<OperationResult>;
+    /** Belirli tablo veya tüm tablolar için istatistik döner */
+    getStats(table?: string): Promise<DatabaseStats>;
+    /** Clear all data from the database (all tables) */
+    clear(): Promise<OperationResult>;
+    /** Get a collection/table handler for fluent API usage */
+    table(tableName: string): TableHandler;
+    private getAllMessages;
+    private reloadCacheFromIndex;
+    private loadMessageIndex;
+    private saveMessageIndex;
+    private setupMessageListener;
+    /** Ensure database is initialized */
+    private ensureInitialized;
+    /** Retry operation with exponential backoff */
+    private retryOperation;
+    private sleep;
+    /** Close database connection */
+    close(): Promise<void>;
+}

package/dist/TelegramDB.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramDB = void 0;
+const telegraf_1 = require("telegraf");
+const utils_1 = require("./utils");
+const TableHandler_1 = require("./TableHandler");
+/** Uses Telegram chat messages to store and retrieve data */
+class TelegramDB {
+    constructor(config) {
+        this.initialized = false;
+        this.messageIndex = new Map();
+        this.documentCache = new Map();
+        this.indexMessageId = null;
+        this.bot = new telegraf_1.Telegraf(config.botToken);
+        this.chatId = config.chatId;
+        this.prefix = config.messagePrefix || 'TDB:';
+        this.batchDelay = config.batchDelay || 100;
+        this.maxRetries = config.maxRetries || 3;
+    }
+    /** Initialize database connection. Must be called before use. */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            await this.bot.telegram.getMe();
+            await this.bot.telegram.getChat(this.chatId);
+            await this.loadMessageIndex();
+            this.setupMessageListener();
+            this.initialized = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize Telegram DB: ${error}`);
+        }
+    }
+    /** Insert a new document into a table */
+    async insert(doc, table) {
+        await this.ensureInitialized();
+        try {
+            const document = {
+                ...doc,
+                _id: doc._id || (0, utils_1.generateId)(),
+                _table: table,
+            };
+            const message = (0, utils_1.encodeDocument)(document, this.prefix);
+            const sentMessage = await this.retryOperation(() => this.bot.telegram.sendMessage(this.chatId, message), this.maxRetries);
+            this.messageIndex.set(document._id, sentMessage.message_id);
+            this.documentCache.set(document._id, document);
+            await this.saveMessageIndex();
+            return {
+                success: true,
+                data: { ...document, _messageId: sentMessage.message_id },
+                message: 'Document inserted successfully',
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error,
+                message: `Failed to insert document: ${error.message}`,
+            };
+        }
+    }
+    /** Insert multiple documents into a table */
+    async insertMany(docs, table, options) {
+        await this.ensureInitialized();
+        const results = [];
+        const delay = options?.delay || this.batchDelay;
+        const stopOnError = options?.stopOnError || false;
+        for (const doc of docs) {
+            const result = await this.insert(doc, table);
+            results.push(result);
+            if (!result.success && stopOnError) {
+                break;
+            }
+            if (delay > 0 && docs.indexOf(doc) < docs.length - 1) {
+                await this.sleep(delay);
+            }
+        }
+        return results;
+    }
+    /** Find documents matching the filter in a table */
+    async find(filter = {}, table) {
+        await this.ensureInitialized();
+        try {
+            const documents = [];
+            const queryWithTable = { ...filter, _table: table };
+            for (const [docId, doc] of this.documentCache.entries()) {
+                if ((0, utils_1.matchesFilter)(doc, queryWithTable)) {
+                    documents.push(doc);
+                }
+            }
+            if (this.documentCache.size === 0) {
+                await this.reloadCacheFromIndex();
+                for (const [docId, doc] of this.documentCache.entries()) {
+                    if ((0, utils_1.matchesFilter)(doc, queryWithTable)) {
+                        documents.push(doc);
+                    }
+                }
+            }
+            return documents;
+        }
+        catch (error) {
+            throw new Error(`Failed to find documents: ${error.message}`);
+        }
+    }
+    /** Find a single document matching the filter in a table */
+    async findOne(filter = {}, table) {
+        const results = await this.find(filter, table);
+        return results.length > 0 ? results[0] : null;
+    }
+    /** Find document by ID in a table */
+    async findById(id, table) {
+        return this.findOne({ _id: id }, table);
+    }
+    /** Update documents matching the filter in a table */
+    async update(filter, update, table, options = {}) {
+        await this.ensureInitialized();
+        try {
+            const queryWithTable = { ...filter, _table: table };
+            const documents = await this.find({}, table).then(docs => docs.filter(doc => (0, utils_1.matchesFilter)(doc, queryWithTable)));
+            if (documents.length === 0 && options.upsert) {
+                const newDoc = (0, utils_1.deepMerge)(filter, update);
+                return await this.insert(newDoc, table);
+            }
+            if (documents.length === 0) {
+                return {
+                    success: false,
+                    message: 'No documents found to update',
+                };
+            }
+            const updatedDocs = [];
+            for (const doc of documents) {
+                const updated = options.replace
+                    ? { ...update, _id: doc._id }
+                    : (0, utils_1.deepMerge)(doc, { ...update, _id: doc._id });
+                const oldMessageId = this.messageIndex.get(doc._id);
+                if (oldMessageId) {
+                    try {
+                        await this.bot.telegram.deleteMessage(this.chatId, oldMessageId);
+                    }
+                    catch {
+                        // Ignore deletion errors
+                    }
+                }
+                const message = (0, utils_1.encodeDocument)(updated, this.prefix);
+                const sentMessage = await this.retryOperation(() => this.bot.telegram.sendMessage(this.chatId, message), this.maxRetries);
+                this.messageIndex.set(updated._id, sentMessage.message_id);
+                this.documentCache.set(updated._id, updated);
+                updatedDocs.push(updated);
+            }
+            await this.saveMessageIndex();
+            return {
+                success: true,
+                data: updatedDocs,
+                message: `Updated ${updatedDocs.length} document(s)`,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error,
+                message: `Failed to update documents: ${error.message}`,
+            };
+        }
+    }
+    /** Update a single document by ID in a table */
+    async updateById(id, update, table, options = {}) {
+        return this.update({ _id: id }, update, table, options);
+    }
+    /** Delete documents matching the filter in a table */
+    async delete(filter, table) {
+        await this.ensureInitialized();
+        try {
+            const queryWithTable = { ...filter, _table: table };
+            const documents = await this.find({}, table).then(docs => docs.filter(doc => (0, utils_1.matchesFilter)(doc, queryWithTable)));
+            if (documents.length === 0) {
+                return {
+                    success: false,
+                    message: 'No documents found to delete',
+                };
+            }
+            let deletedCount = 0;
+            for (const doc of documents) {
+                const messageId = this.messageIndex.get(doc._id);
+                if (messageId) {
+                    try {
+                        await this.bot.telegram.deleteMessage(this.chatId, messageId);
+                        this.messageIndex.delete(doc._id);
+                        this.documentCache.delete(doc._id);
+                        deletedCount++;
+                    }
+                    catch {
+                        this.messageIndex.delete(doc._id);
+                        this.documentCache.delete(doc._id);
+                    }
+                }
+            }
+            await this.saveMessageIndex();
+            return {
+                success: true,
+                data: { deletedCount },
+                message: `Deleted ${deletedCount} document(s)`,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error,
+                message: `Failed to delete documents: ${error.message}`,
+            };
+        }
+    }
+    /** Delete a single document by ID in a table */
+    async deleteById(id, table) {
+        return this.delete({ _id: id }, table);
+    }
+    /** Delete all documents in a table */
+    async deleteAll(table) {
+        return this.delete({}, table);
+    }
+    /** Count documents matching the filter in a table */
+    async count(filter = {}, table) {
+        const queryWithTable = { ...filter, _table: table };
+        const documents = await this.find({}, table);
+        return documents.filter(doc => (0, utils_1.matchesFilter)(doc, queryWithTable)).length;
+    }
+    /** Get all table names in the database */
+    async getTables() {
+        await this.ensureInitialized();
+        const tables = new Set();
+        for (const [, doc] of this.documentCache.entries()) {
+            if (doc._table) {
+                tables.add(doc._table);
+            }
+        }
+        return Array.from(tables);
+    }
+    /** Tabloyu tamamen siler */
+    async dropTable(table) {
+        return this.deleteAll(table);
+    }
+    /** Belirli tablo veya tüm tablolar için istatistik döner */
+    async getStats(table) {
+        await this.ensureInitialized();
+        const documents = table
+            ? await this.find({}, table)
+            : Array.from(this.documentCache.values());
+        const messages = await this.getAllMessages();
+        let oldestDoc;
+        let newestDoc;
+        if (documents.length > 0) {
+            oldestDoc = documents.reduce((oldest, current) => {
+                const oldestId = oldest._id.split('-')[0];
+                const currentId = current._id.split('-')[0];
+                return parseInt(currentId) < parseInt(oldestId) ? current : oldest;
+            });
+            newestDoc = documents.reduce((newest, current) => {
+                const newestId = newest._id.split('-')[0];
+                const currentId = current._id.split('-')[0];
+                return parseInt(currentId) > parseInt(newestId) ? current : newest;
+            });
+        }
+        return {
+            totalDocuments: documents.length,
+            totalMessages: messages.length,
+            oldestDocument: oldestDoc,
+            newestDocument: newestDoc,
+        };
+    }
+    /** Clear all data from the database (all tables) */
+    async clear() {
+        await this.ensureInitialized();
+        const tables = await this.getTables();
+        const results = [];
+        for (const table of tables) {
+            const result = await this.deleteAll(table);
+            results.push(result);
+        }
+        return {
+            success: results.every(r => r.success),
+            data: results,
+            message: `Cleared ${tables.length} table(s)`,
+        };
+    }
+    /** Get a collection/table handler for fluent API usage */
+    table(tableName) {
+        return new TableHandler_1.TableHandler(this, tableName);
+    }
+    async getAllMessages() {
+        const messages = [];
+        for (const [docId, messageId] of this.messageIndex.entries()) {
+            messages.push({
+                message_id: messageId,
+                text: '', // Text is stored in cache, not needed here
+            });
+        }
+        return messages;
+    }
+    async reloadCacheFromIndex() {
+        try {
+            if (this.indexMessageId) {
+                // Cache populated as operations happen
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    async loadMessageIndex() {
+        try {
+            this.messageIndex.clear();
+            this.documentCache.clear();
+        }
+        catch {
+            this.messageIndex.clear();
+            this.documentCache.clear();
+        }
+    }
+    async saveMessageIndex() {
+        try {
+            const indexData = {
+                _id: '__INDEX__',
+                _table: '__SYSTEM__',
+                messageIndex: Array.from(this.messageIndex.entries()),
+                documents: Array.from(this.documentCache.values()),
+                updatedAt: Date.now(),
+            };
+            const indexMessage = (0, utils_1.encodeDocument)(indexData, `${this.prefix}INDEX:`);
+            if (this.indexMessageId) {
+                try {
+                    await this.bot.telegram.deleteMessage(this.chatId, this.indexMessageId);
+                }
+                catch {
+                    // Ignore errors
+                }
+            }
+            if (this.messageIndex.size > 0) {
+                try {
+                    const sentMessage = await this.bot.telegram.sendMessage(this.chatId, indexMessage);
+                    this.indexMessageId = sentMessage.message_id;
+                }
+                catch {
+                    // Fail silently if message too long
+                }
+            }
+        }
+        catch (error) {
+            console.warn('Failed to save message index:', error);
+        }
+    }
+    setupMessageListener() {
+        this.bot.on('message', async (ctx) => {
+            const message = ctx.message;
+            if (!message || !('text' in message) || !message.text)
+                return;
+            const text = message.text;
+            if (String(ctx.chat?.id) !== String(this.chatId))
+                return;
+            if (text.startsWith(this.prefix) && !text.startsWith(`${this.prefix}INDEX:`)) {
+                const doc = (0, utils_1.decodeDocument)(text, this.prefix);
+                if (doc && doc._id) {
+                    this.messageIndex.set(doc._id, message.message_id);
+                    this.documentCache.set(doc._id, doc);
+                }
+            }
+            else if (text.startsWith(`${this.prefix}INDEX:`)) {
+                const indexData = (0, utils_1.decodeDocument)(text, `${this.prefix}INDEX:`);
+                if (indexData && indexData._id === '__INDEX__' && indexData.messageIndex && indexData.documents) {
+                    this.messageIndex = new Map(indexData.messageIndex);
+                    indexData.documents.forEach((doc) => {
+                        this.documentCache.set(doc._id, doc);
+                    });
+                    this.indexMessageId = message.message_id;
+                }
+            }
+        });
+        this.bot.launch().catch(() => { });
+    }
+    /** Ensure database is initialized */
+    async ensureInitialized() {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+    }
+    /** Retry operation with exponential backoff */
+    async retryOperation(operation, maxRetries) {
+        let lastError;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error;
+                if (i < maxRetries - 1) {
+                    await this.sleep(1000 * (i + 1));
+                }
+            }
+        }
+        throw lastError;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /** Close database connection */
+    async close() {
+        this.bot.stop();
+        this.initialized = false;
+    }
+}
+exports.TelegramDB = TelegramDB;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { TelegramDB } from './TelegramDB';
+export { TableHandler } from './TableHandler';
+export * from './types';
+export * from './utils';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableHandler = exports.TelegramDB = void 0;
+var TelegramDB_1 = require("./TelegramDB");
+Object.defineProperty(exports, "TelegramDB", { enumerable: true, get: function () { return TelegramDB_1.TelegramDB; } });
+var TableHandler_1 = require("./TableHandler");
+Object.defineProperty(exports, "TableHandler", { enumerable: true, get: function () { return TableHandler_1.TableHandler; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export interface TelegramDBConfig {
+    botToken: string;
+    chatId: string | number;
+    messagePrefix?: string;
+    batchDelay?: number;
+    maxRetries?: number;
+}
+export interface Document {
+    _id: string;
+    _table: string;
+    [key: string]: any;
+}
+export interface QueryFilter {
+    [key: string]: any;
+}
+export interface UpdateOptions {
+    upsert?: boolean;
+    replace?: boolean;
+}
+export interface OperationResult {
+    success: boolean;
+    message?: string;
+    data?: any;
+    error?: Error;
+}
+export interface BatchOptions {
+    delay?: number;
+    stopOnError?: boolean;
+}
+export interface DatabaseStats {
+    totalDocuments: number;
+    totalMessages: number;
+    oldestDocument?: Document;
+    newestDocument?: Document;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+import { Document, QueryFilter } from './types';
+export declare function encodeDocument(doc: Document, prefix?: string): string;
+export declare function decodeDocument(messageText: string, prefix?: string): Document | null;
+export declare function matchesFilter(doc: Document, filter: QueryFilter): boolean;
+export declare function generateId(): string;
+export declare function deepMerge(target: any, source: any): any;

package/dist/utils.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeDocument = encodeDocument;
+exports.decodeDocument = decodeDocument;
+exports.matchesFilter = matchesFilter;
+exports.generateId = generateId;
+exports.deepMerge = deepMerge;
+function encodeDocument(doc, prefix = "TDB:") {
+    const json = JSON.stringify(doc);
+    return `${prefix}${json}`;
+}
+function decodeDocument(messageText, prefix = "TDB:") {
+    if (!messageText.startsWith(prefix)) {
+        return null;
+    }
+    try {
+        const json = messageText.substring(prefix.length);
+        return JSON.parse(json);
+    }
+    catch (error) {
+        return null;
+    }
+}
+function matchesFilter(doc, filter) {
+    for (const [key, value] of Object.entries(filter)) {
+        if (key === '_id' && doc._id !== value) {
+            return false;
+        }
+        const docValue = getNestedValue(doc, key);
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            if (!matchesOperators(docValue, value)) {
+                return false;
+            }
+        }
+        else if (Array.isArray(value)) {
+            if (!value.includes(docValue)) {
+                return false;
+            }
+        }
+        else {
+            if (docValue !== value) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+}
+function matchesOperators(docValue, operators) {
+    for (const [op, opValue] of Object.entries(operators)) {
+        switch (op) {
+            case '$gt':
+                if (!(docValue > opValue))
+                    return false;
+                break;
+            case '$gte':
+                if (!(docValue >= opValue))
+                    return false;
+                break;
+            case '$lt':
+                if (!(docValue < opValue))
+                    return false;
+                break;
+            case '$lte':
+                if (!(docValue <= opValue))
+                    return false;
+                break;
+            case '$ne':
+                if (docValue === opValue)
+                    return false;
+                break;
+            case '$in':
+                if (!Array.isArray(opValue) || !opValue.includes(docValue))
+                    return false;
+                break;
+            case '$nin':
+                if (Array.isArray(opValue) && opValue.includes(docValue))
+                    return false;
+                break;
+            case '$regex':
+                if (typeof docValue !== 'string')
+                    return false;
+                const regex = new RegExp(opValue);
+                if (!regex.test(docValue))
+                    return false;
+                break;
+            case '$exists':
+                const exists = docValue !== undefined && docValue !== null;
+                if (opValue !== exists)
+                    return false;
+                break;
+            default:
+                break;
+        }
+    }
+    return true;
+}
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+}
+function deepMerge(target, source) {
+    const output = { ...target };
+    if (isObject(target) && isObject(source)) {
+        Object.keys(source).forEach(key => {
+            if (isObject(source[key])) {
+                if (!(key in target)) {
+                    Object.assign(output, { [key]: source[key] });
+                }
+                else {
+                    output[key] = deepMerge(target[key], source[key]);
+                }
+            }
+            else {
+                Object.assign(output, { [key]: source[key] });
+            }
+        });
+    }
+    return output;
+}
+function isObject(item) {
+    return item && typeof item === 'object' && !Array.isArray(item);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ozgurv/tg-db",
+  "version": "1.0.0",
+  "description": "Use Telegram chat as a database - Store and query data in Telegram conversations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "jest"
+  },
+  "keywords": [
+    "telegram",
+    "database",
+    "bot",
+    "storage",
+    "chat-db",
+    "telegram-bot"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "telegraf": "^4.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}