gramobase 1.0.11 → 1.0.13

package/README.md

@@ -9,15 +9,42 @@
 
 **Telegram as a free, infinite, production-grade backend database.**
 
-Every Telegram channel is a collection. Every message is a document. Zero infrastructure needed — all you need is a free Telegram account.
+Every Telegram channel is a collection. Every message is a document. Zero infrastructure needed. All you need is a free Telegram account.
+
+---
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+npm install gramobase
+```
+
+### 2. Setup
+
+Initialize your project with the auto-detect wizard:
+
+```bash
+npx gramobase init
+```
+
+This interactive wizard walks you through setting up your backend. It features **Auto-Detect** technology and **Anti-Flood** scaling: it will ask you how many Bot Tokens you want to configure (for 30 req/s scaling per bot). Provide your tokens, and leave the Channel ID blank! By sending a message in your channel, `gramobase` will automatically fetch your hidden Telegram Channel ID for you and generate your `.env` and `gramobase.config.ts`.
+
+**Prerequisites:**
+1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram — takes 30 seconds
+2. Create a private Telegram channel
+3. Add your bot as an **Administrator** with full permissions to the channel
+
+### 3. Usage
 
 ```ts
 import { createClient } from 'gramobase';
 import { z } from 'zod';
 
 const db = await createClient({
-  botToken: process.env.BOT_TOKEN!,
-  channelId: process.env.CHANNEL_ID!,
+  botToken: process.env.GRAMOBASE_BOT_TOKEN_1!,
+  channelId: process.env.GRAMOBASE_CHANNEL_ID!,
 }).connect();
 
 const users = db.collection('users', {
@@ -28,6 +55,44 @@ await users.insertOne({ name: 'Aarav', email: 'aarav@example.com' });
 const user = await users.findOne({ name: { $eq: 'Aarav' } });
 ```
 
+> [!IMPORTANT]
+> **Next.js & Hot-Reloading Environments:**
+> In development environments that support hot-reloading (like Next.js), the module cache is frequently cleared, which can instantiate multiple database clients and trigger write lease lock collisions. To prevent this, choose one of the following methods to cache your client:
+> 
+> **Option A: Built-in `global` config option (Recommended)**
+> Pass `global: true` in your client config to automatically handle global caching inside the package:
+> 
+> ```ts
+> import { createClient } from 'gramobase';
+> 
+> const client = createClient({
+>   botToken: process.env.GRAMOBASE_BOT_TOKEN_1!,
+>   channelId: process.env.GRAMOBASE_CHANNEL_ID!,
+>   global: true, // Automatically caches the client instance globally
+> });
+> const db = await client.connect();
+> ```
+> 
+> **Option B: Manual `globalThis` caching**
+> Alternatively, you can manage caching manually on the global scope:
+> 
+> ```ts
+> import { createClient } from 'gramobase';
+> 
+> const globalForDb = globalThis as unknown as { dbClient: any };
+> 
+> export async function getDb() {
+>   if (!globalForDb.dbClient) {
+>     const client = createClient({
+>       botToken: process.env.GRAMOBASE_BOT_TOKEN_1!,
+>       channelId: process.env.GRAMOBASE_CHANNEL_ID!,
+>     });
+>     globalForDb.dbClient = await client.connect();
+>   }
+>   return globalForDb.dbClient;
+> }
+> ```
+
 ---
 
 ## Why gramobase?
@@ -45,12 +110,6 @@ const user = await users.findOne({ name: { $eq: 'Aarav' } });
 
 ---
 
-## Installation
-
-```bash
-npm install gramobase
-```
-
 ### Running Tests
 
 To run the suite of 40 unit tests checking the ORM, caching, queue/worker pooling, and authentication:
@@ -59,20 +118,6 @@ To run the suite of 40 unit tests checking the ORM, caching, queue/worker poolin
 npm run test
 ```
 
-### Setup
-
-```bash
-npx gramobase init
-```
-
-This interactive wizard walks you through setting up your backend. 
-It features **Auto-Detect** technology and **Anti-Flood** scaling: it will ask you how many Bot Tokens you want to configure (for 30 req/s scaling per bot). Provide your tokens, and leave the Channel ID blank! By sending a message in your channel, `gramobase` will automatically fetch your hidden Telegram Channel ID for you and generate your `.env` and `gramobase.config.ts`.
-
-**Prerequisites:**
-1. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram — takes 30 seconds
-2. Create a private Telegram channel
-3. Add your bot as an **Administrator** with full permissions to the channel
-
 ---
 
 ## Core API
@@ -274,17 +319,17 @@ Developer API (ORM, Auth, Files, Realtime)
          │
   Telegram Bot API ─────────────────────────────────┐
          │                                          │
-  Private Channel              File Storage      Realtime
-  (messages = docs,        (sendDocument,       (webhook +
-   pinned = index)          file_id refs)       SSE bridge)
+   Private Channel              File Storage      Realtime
+   (messages = docs,        (sendDocument,       (webhook +
+    pinned = registry)       file_id refs)       SSE bridge)
 ```
 
 ### Storage model
 
 - Each collection maps to a private Telegram channel (or shares one via namespaced message tags)
-- A **pinned index message** stores `{ id → msgId }` for O(1) lookups
+- A **pinned registry message** acts as a distributed write lock across processes and stores the master index mapping of collection names to their respective index message IDs (`{ collectionName → indexMsgId }`)
+- Individual **index messages** (unpinned) store `{ id → msgId }` for O(1) document lookups
 - The **Write-Ahead Log** channel stores operation logs for crash recovery
-- A **registry message** acts as a distributed write lock across processes
 
 ### Limits
 
@@ -343,6 +388,7 @@ const db = createClient({
   concurrency?: number,         // max concurrent requests per token, default 25
   webhookUrl?: string,          // enables webhook mode for realtime
   debug?: boolean,
+  global?: boolean,             // auto-cache client globally (default: false)
 });
 ```
 

package/dist/{BotWorkerPool-9ndHQt2g.d.cts → BotWorkerPool-h_8a20dt.d.cts}

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 import TelegramBot from 'node-telegram-bot-api';
 import EventEmitter from 'eventemitter3';
 
@@ -11,7 +10,11 @@ interface GramoBaseDocument {
     [key: string]: unknown;
 }
 type WithId<T> = T & GramoBaseDocument;
-interface CollectionConfig<T extends z.ZodType> {
+interface SchemaLike<Output = any> {
+    parse(data: unknown): Output;
+}
+type InferSchema<T extends SchemaLike> = ReturnType<T['parse']>;
+interface CollectionConfig<T extends SchemaLike> {
     schema: T;
     /** Channel override — uses the default if omitted */
     channelId?: string | undefined;
@@ -157,6 +160,8 @@ interface GramoBaseConfig {
     webhookUrl?: string | undefined;
     /** Enable verbose debug logging */
     debug?: boolean | undefined;
+    /** Auto-cache client globally on globalThis in dev mode to prevent lease collisions in serverless/hot-reloading environments */
+    global?: boolean | undefined;
 }
 
 interface WorkerStats {
@@ -198,4 +203,4 @@ declare class BotWorkerPool extends EventEmitter {
     destroy(): Promise<void>;
 }
 
-export { type AuthConfig as A, BotWorkerPool as B, type CollectionConfig as C, type FileRecord as F, type GramoBaseEvent as G, type Lease as L, type Migration as M, type Session as S, type UploadOptions as U, type WorkerStats as W, type GramoBaseConfig as a, type ComparisonOperator as b, type Filter as c, type FindOptions as d, type GramoBaseDocument as e, type UpdateOperators as f, type User as g, type WalEntry as h, type WalOpType as i, type WithId as j };
+export { type AuthConfig as A, BotWorkerPool as B, type CollectionConfig as C, type FileRecord as F, type GramoBaseEvent as G, type InferSchema as I, type Lease as L, type Migration as M, type SchemaLike as S, type UploadOptions as U, type WorkerStats as W, type GramoBaseConfig as a, type ComparisonOperator as b, type Filter as c, type FindOptions as d, type GramoBaseDocument as e, type Session as f, type UpdateOperators as g, type User as h, type WalEntry as i, type WalOpType as j, type WithId as k };

package/dist/{BotWorkerPool-9ndHQt2g.d.ts → BotWorkerPool-h_8a20dt.d.ts}

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 import TelegramBot from 'node-telegram-bot-api';
 import EventEmitter from 'eventemitter3';
 
@@ -11,7 +10,11 @@ interface GramoBaseDocument {
     [key: string]: unknown;
 }
 type WithId<T> = T & GramoBaseDocument;
-interface CollectionConfig<T extends z.ZodType> {
+interface SchemaLike<Output = any> {
+    parse(data: unknown): Output;
+}
+type InferSchema<T extends SchemaLike> = ReturnType<T['parse']>;
+interface CollectionConfig<T extends SchemaLike> {
     schema: T;
     /** Channel override — uses the default if omitted */
     channelId?: string | undefined;
@@ -157,6 +160,8 @@ interface GramoBaseConfig {
     webhookUrl?: string | undefined;
     /** Enable verbose debug logging */
     debug?: boolean | undefined;
+    /** Auto-cache client globally on globalThis in dev mode to prevent lease collisions in serverless/hot-reloading environments */
+    global?: boolean | undefined;
 }
 
 interface WorkerStats {
@@ -198,4 +203,4 @@ declare class BotWorkerPool extends EventEmitter {
     destroy(): Promise<void>;
 }
 
-export { type AuthConfig as A, BotWorkerPool as B, type CollectionConfig as C, type FileRecord as F, type GramoBaseEvent as G, type Lease as L, type Migration as M, type Session as S, type UploadOptions as U, type WorkerStats as W, type GramoBaseConfig as a, type ComparisonOperator as b, type Filter as c, type FindOptions as d, type GramoBaseDocument as e, type UpdateOperators as f, type User as g, type WalEntry as h, type WalOpType as i, type WithId as j };
+export { type AuthConfig as A, BotWorkerPool as B, type CollectionConfig as C, type FileRecord as F, type GramoBaseEvent as G, type InferSchema as I, type Lease as L, type Migration as M, type SchemaLike as S, type UploadOptions as U, type WorkerStats as W, type GramoBaseConfig as a, type ComparisonOperator as b, type Filter as c, type FindOptions as d, type GramoBaseDocument as e, type Session as f, type UpdateOperators as g, type User as h, type WalEntry as i, type WalOpType as j, type WithId as k };

package/dist/{GramoBaseAuth-00fg0u_b.d.ts → GramoBaseAuth-DfRKq2yW.d.ts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { B as BotWorkerPool, e as GramoBaseDocument, i as WalOpType, h as WalEntry, C as CollectionConfig, j as WithId, c as Filter, d as FindOptions, f as UpdateOperators, A as AuthConfig, g as User, S as Session } from './BotWorkerPool-9ndHQt2g.js';
+import { B as BotWorkerPool, L as Lease, e as GramoBaseDocument, j as WalOpType, i as WalEntry, S as SchemaLike, C as CollectionConfig, I as InferSchema, k as WithId, c as Filter, d as FindOptions, g as UpdateOperators, A as AuthConfig, h as User, f as Session } from './BotWorkerPool-h_8a20dt.js';
 import EventEmitter from 'eventemitter3';
 
 /**
@@ -41,6 +41,41 @@ declare class HotCache extends EventEmitter {
     private docKey;
 }
 
+/**
+ * Registry uses a pinned Telegram message as a distributed lock.
+ *
+ * When a gramobase instance starts up, it reads the registry message.
+ * If no lease exists or the existing lease is expired, it writes a new
+ * lease with its own instanceId and begins sending heartbeats.
+ *
+ * This prevents multiple writer processes from corrupting the index
+ * (last-write-wins races on the pinned index message).
+ *
+ * Read-only operations are always permitted. Only index mutations
+ * require holding the write lease.
+ */
+declare class Registry {
+    private pool;
+    private channelId;
+    private debug;
+    private state;
+    private readonly instanceId;
+    constructor(pool: BotWorkerPool, channelId: string, debug?: boolean);
+    acquireWriteLease(options?: {
+        wait?: boolean;
+    }): Promise<Lease>;
+    releaseWriteLease(): Promise<void>;
+    forceRelease(): Promise<void>;
+    isWriteLeaseHeld(): Promise<boolean>;
+    private heartbeat;
+    private readRegistryMessage;
+    private writeRegistryMessage;
+    getCollectionIndexMsgId(collection: string): Promise<number | null>;
+    setCollectionIndexMsgId(collection: string, msgId: number): Promise<void>;
+    getInstanceId(): string;
+    getCurrentLease(): Lease | null;
+}
+
 interface IndexMessage {
     collection: string;
     entries: Record<string, number>;
@@ -60,10 +95,12 @@ interface IndexMessage {
 declare class TelegramStorage {
     private pool;
     private defaultChannelId;
+    private registry;
     private debug;
     private encryptionKey;
     private indexMsgIds;
-    constructor(pool: BotWorkerPool, defaultChannelId: string, encryptionKey?: string, debug?: boolean);
+    constructor(pool: BotWorkerPool, defaultChannelId: string, registry: Registry, encryptionKey?: string, debug?: boolean);
+    private readRawMessageText;
     loadIndex(collection: string, channelId?: string): Promise<IndexMessage>;
     saveIndex(index: IndexMessage, channelId?: string): Promise<void>;
     writeDocument(doc: GramoBaseDocument, channelId?: string): Promise<number>;
@@ -122,7 +159,7 @@ declare class WriteAheadLog {
     getCurrentSeq(): number;
 }
 
-type DocOf<T extends z.ZodType> = WithId<z.infer<T>>;
+type DocOf<T extends SchemaLike> = WithId<InferSchema<T>>;
 /**
  * Collection<T> is the main ORM interface.
  *
@@ -133,7 +170,7 @@ type DocOf<T extends z.ZodType> = WithId<z.infer<T>>;
  *   - Index management (id → msgId map, stored as a pinned message)
  *   - Filter/sort/skip/limit in memory after cache warm-up
  */
-declare class Collection<T extends z.ZodType> {
+declare class Collection<T extends SchemaLike> {
     private name;
     private config;
     private cache;
@@ -143,18 +180,18 @@ declare class Collection<T extends z.ZodType> {
     private indexLoaded;
     constructor(name: string, config: CollectionConfig<T>, cache: HotCache, storage: TelegramStorage, wal: WriteAheadLog, defaultChannelId: string);
     ensureIndexLoaded(): Promise<void>;
-    insertOne(data: z.infer<T>): Promise<DocOf<T>>;
-    insertMany(items: z.infer<T>[]): Promise<DocOf<T>[]>;
+    insertOne(data: InferSchema<T>): Promise<DocOf<T>>;
+    insertMany(items: InferSchema<T>[]): Promise<DocOf<T>[]>;
     findById(id: string): Promise<DocOf<T> | null>;
-    findOne(filter?: Filter<z.infer<T>>): Promise<DocOf<T> | null>;
-    find(options?: FindOptions<z.infer<T>>): Promise<DocOf<T>[]>;
-    count(filter?: Filter<z.infer<T>>): Promise<number>;
-    updateOne(filter: Filter<z.infer<T>>, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T> | null>;
-    updateMany(filter: Filter<z.infer<T>>, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T>[]>;
-    findByIdAndUpdate(id: string, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T> | null>;
+    findOne(filter?: Filter<InferSchema<T>>): Promise<DocOf<T> | null>;
+    find(options?: FindOptions<InferSchema<T>>): Promise<DocOf<T>[]>;
+    count(filter?: Filter<InferSchema<T>>): Promise<number>;
+    updateOne(filter: Filter<InferSchema<T>>, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T> | null>;
+    updateMany(filter: Filter<InferSchema<T>>, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T>[]>;
+    findByIdAndUpdate(id: string, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T> | null>;
     private applyUpdate;
-    deleteOne(filter: Filter<z.infer<T>>): Promise<boolean>;
-    deleteMany(filter: Filter<z.infer<T>>): Promise<number>;
+    deleteOne(filter: Filter<InferSchema<T>>): Promise<boolean>;
+    deleteMany(filter: Filter<InferSchema<T>>): Promise<number>;
     deleteById(id: string): Promise<boolean>;
     private flushIndex;
     private matchesFilter;
@@ -215,4 +252,4 @@ declare class GramoBaseAuth {
     requireRoleMiddleware(role: string): (req: any, res: any, next: any) => void;
 }
 
-export { Collection as C, GramoBaseAuth as G };
+export { Collection as C, GramoBaseAuth as G, Registry as R };

package/dist/{GramoBaseAuth-CHNn2_e5.d.cts → GramoBaseAuth-ObeOxqKj.d.cts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { B as BotWorkerPool, e as GramoBaseDocument, i as WalOpType, h as WalEntry, C as CollectionConfig, j as WithId, c as Filter, d as FindOptions, f as UpdateOperators, A as AuthConfig, g as User, S as Session } from './BotWorkerPool-9ndHQt2g.cjs';
+import { B as BotWorkerPool, L as Lease, e as GramoBaseDocument, j as WalOpType, i as WalEntry, S as SchemaLike, C as CollectionConfig, I as InferSchema, k as WithId, c as Filter, d as FindOptions, g as UpdateOperators, A as AuthConfig, h as User, f as Session } from './BotWorkerPool-h_8a20dt.cjs';
 import EventEmitter from 'eventemitter3';
 
 /**
@@ -41,6 +41,41 @@ declare class HotCache extends EventEmitter {
     private docKey;
 }
 
+/**
+ * Registry uses a pinned Telegram message as a distributed lock.
+ *
+ * When a gramobase instance starts up, it reads the registry message.
+ * If no lease exists or the existing lease is expired, it writes a new
+ * lease with its own instanceId and begins sending heartbeats.
+ *
+ * This prevents multiple writer processes from corrupting the index
+ * (last-write-wins races on the pinned index message).
+ *
+ * Read-only operations are always permitted. Only index mutations
+ * require holding the write lease.
+ */
+declare class Registry {
+    private pool;
+    private channelId;
+    private debug;
+    private state;
+    private readonly instanceId;
+    constructor(pool: BotWorkerPool, channelId: string, debug?: boolean);
+    acquireWriteLease(options?: {
+        wait?: boolean;
+    }): Promise<Lease>;
+    releaseWriteLease(): Promise<void>;
+    forceRelease(): Promise<void>;
+    isWriteLeaseHeld(): Promise<boolean>;
+    private heartbeat;
+    private readRegistryMessage;
+    private writeRegistryMessage;
+    getCollectionIndexMsgId(collection: string): Promise<number | null>;
+    setCollectionIndexMsgId(collection: string, msgId: number): Promise<void>;
+    getInstanceId(): string;
+    getCurrentLease(): Lease | null;
+}
+
 interface IndexMessage {
     collection: string;
     entries: Record<string, number>;
@@ -60,10 +95,12 @@ interface IndexMessage {
 declare class TelegramStorage {
     private pool;
     private defaultChannelId;
+    private registry;
     private debug;
     private encryptionKey;
     private indexMsgIds;
-    constructor(pool: BotWorkerPool, defaultChannelId: string, encryptionKey?: string, debug?: boolean);
+    constructor(pool: BotWorkerPool, defaultChannelId: string, registry: Registry, encryptionKey?: string, debug?: boolean);
+    private readRawMessageText;
     loadIndex(collection: string, channelId?: string): Promise<IndexMessage>;
     saveIndex(index: IndexMessage, channelId?: string): Promise<void>;
     writeDocument(doc: GramoBaseDocument, channelId?: string): Promise<number>;
@@ -122,7 +159,7 @@ declare class WriteAheadLog {
     getCurrentSeq(): number;
 }
 
-type DocOf<T extends z.ZodType> = WithId<z.infer<T>>;
+type DocOf<T extends SchemaLike> = WithId<InferSchema<T>>;
 /**
  * Collection<T> is the main ORM interface.
  *
@@ -133,7 +170,7 @@ type DocOf<T extends z.ZodType> = WithId<z.infer<T>>;
  *   - Index management (id → msgId map, stored as a pinned message)
  *   - Filter/sort/skip/limit in memory after cache warm-up
  */
-declare class Collection<T extends z.ZodType> {
+declare class Collection<T extends SchemaLike> {
     private name;
     private config;
     private cache;
@@ -143,18 +180,18 @@ declare class Collection<T extends z.ZodType> {
     private indexLoaded;
     constructor(name: string, config: CollectionConfig<T>, cache: HotCache, storage: TelegramStorage, wal: WriteAheadLog, defaultChannelId: string);
     ensureIndexLoaded(): Promise<void>;
-    insertOne(data: z.infer<T>): Promise<DocOf<T>>;
-    insertMany(items: z.infer<T>[]): Promise<DocOf<T>[]>;
+    insertOne(data: InferSchema<T>): Promise<DocOf<T>>;
+    insertMany(items: InferSchema<T>[]): Promise<DocOf<T>[]>;
     findById(id: string): Promise<DocOf<T> | null>;
-    findOne(filter?: Filter<z.infer<T>>): Promise<DocOf<T> | null>;
-    find(options?: FindOptions<z.infer<T>>): Promise<DocOf<T>[]>;
-    count(filter?: Filter<z.infer<T>>): Promise<number>;
-    updateOne(filter: Filter<z.infer<T>>, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T> | null>;
-    updateMany(filter: Filter<z.infer<T>>, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T>[]>;
-    findByIdAndUpdate(id: string, update: UpdateOperators<z.infer<T>>): Promise<DocOf<T> | null>;
+    findOne(filter?: Filter<InferSchema<T>>): Promise<DocOf<T> | null>;
+    find(options?: FindOptions<InferSchema<T>>): Promise<DocOf<T>[]>;
+    count(filter?: Filter<InferSchema<T>>): Promise<number>;
+    updateOne(filter: Filter<InferSchema<T>>, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T> | null>;
+    updateMany(filter: Filter<InferSchema<T>>, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T>[]>;
+    findByIdAndUpdate(id: string, update: UpdateOperators<InferSchema<T>>): Promise<DocOf<T> | null>;
     private applyUpdate;
-    deleteOne(filter: Filter<z.infer<T>>): Promise<boolean>;
-    deleteMany(filter: Filter<z.infer<T>>): Promise<number>;
+    deleteOne(filter: Filter<InferSchema<T>>): Promise<boolean>;
+    deleteMany(filter: Filter<InferSchema<T>>): Promise<number>;
     deleteById(id: string): Promise<boolean>;
     private flushIndex;
     private matchesFilter;
@@ -215,4 +252,4 @@ declare class GramoBaseAuth {
     requireRoleMiddleware(role: string): (req: any, res: any, next: any) => void;
 }
 
-export { Collection as C, GramoBaseAuth as G };
+export { Collection as C, GramoBaseAuth as G, Registry as R };

package/dist/auth/index.d.cts

@@ -1,5 +1,5 @@
 import 'zod';
-import '../BotWorkerPool-9ndHQt2g.cjs';
-export { G as GramoBaseAuth } from '../GramoBaseAuth-CHNn2_e5.cjs';
+import '../BotWorkerPool-h_8a20dt.cjs';
+export { G as GramoBaseAuth } from '../GramoBaseAuth-ObeOxqKj.cjs';
 import 'node-telegram-bot-api';
 import 'eventemitter3';

package/dist/auth/index.d.ts

@@ -1,5 +1,5 @@
 import 'zod';
-import '../BotWorkerPool-9ndHQt2g.js';
-export { G as GramoBaseAuth } from '../GramoBaseAuth-00fg0u_b.js';
+import '../BotWorkerPool-h_8a20dt.js';
+export { G as GramoBaseAuth } from '../GramoBaseAuth-DfRKq2yW.js';
 import 'node-telegram-bot-api';
 import 'eventemitter3';