tina4-nodejs 3.10.76 → 3.10.83

package/packages/core/src/queueBackends/liteBackend.ts

@@ -0,0 +1,369 @@
+/**
+ * LiteBackend — file-based queue backend for Tina4 Queue.
+ * Stores jobs as JSON files on disk. Zero dependencies.
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { type QueueJob } from "../job.js";
+import { createJob, type JobQueueBridge } from "../job.js";
+
+export class LiteBackend {
+  private basePath: string;
+  private seq: number = 0;
+
+  constructor(basePath: string = "data/queue") {
+    this.basePath = basePath;
+  }
+
+  private ensureDir(queue: string): string {
+    const dir = join(this.basePath, queue);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  private ensureFailedDir(queue: string): string {
+    const dir = join(this.basePath, queue, "failed");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  push(queue: string, payload: unknown, delay?: number, priority?: number): string {
+    const dir = this.ensureDir(queue);
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    this.seq++;
+
+    const job = {
+      id,
+      payload,
+      status: "pending" as const,
+      createdAt: now,
+      attempts: 0,
+      delayUntil: delay ? new Date(Date.now() + delay * 1000).toISOString() : null,
+      priority: priority ?? 0,
+    };
+
+    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+    writeFileSync(join(dir, `${prefix}_${id}.queue-data`), JSON.stringify(job, null, 2));
+    return id;
+  }
+
+  pop(queue: string, bridge: JobQueueBridge): QueueJob | null {
+    const dir = this.ensureDir(queue);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
+    } catch {
+      return null;
+    }
+
+    const now = new Date().toISOString();
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      let job: QueueJob;
+      try {
+        job = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+
+      if (job.status !== "pending") continue;
+      if (job.delayUntil && job.delayUntil > now) continue;
+
+      job.status = "reserved";
+      job.topic = queue;
+      job.priority = job.priority ?? 0;
+      writeFileSync(filePath, JSON.stringify(job, null, 2));
+
+      try {
+        unlinkSync(filePath);
+      } catch {
+        // Already consumed by another worker
+      }
+
+      return createJob(job as any, bridge);
+    }
+
+    return null;
+  }
+
+  size(queue: string, status: string = "pending"): number {
+    if (status === "failed") {
+      const failedDir = this.ensureFailedDir(queue);
+      let files: string[];
+      try {
+        files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
+      } catch {
+        return 0;
+      }
+      return files.length;
+    }
+
+    const dir = this.ensureDir(queue);
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return 0;
+    }
+
+    let count = 0;
+    for (const file of files) {
+      try {
+        const job = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+        if (job.status === status) count++;
+      } catch {
+        // skip corrupt files
+      }
+    }
+    return count;
+  }
+
+  clear(queue: string): void {
+    const dir = this.ensureDir(queue);
+    try {
+      const files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+      for (const file of files) {
+        unlinkSync(join(dir, file));
+      }
+    } catch {
+      // directory might not exist
+    }
+
+    // Also clear failed jobs
+    const failedDir = join(dir, "failed");
+    try {
+      if (existsSync(failedDir)) {
+        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          unlinkSync(join(failedDir, file));
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  failed(queue: string): QueueJob[] {
+    const failedDir = this.ensureFailedDir(queue);
+    const results: QueueJob[] = [];
+
+    try {
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
+      for (const file of files) {
+        try {
+          const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
+          results.push(job);
+        } catch {
+          // skip corrupt files
+        }
+      }
+    } catch {
+      // directory might not exist
+    }
+
+    return results;
+  }
+
+  retry(queue: string, jobId: string): boolean {
+    try {
+      const queues = readdirSync(this.basePath);
+      for (const q of queues) {
+        const failedDir = join(this.basePath, q, "failed");
+        const filePath = join(failedDir, `${jobId}.queue-data`);
+
+        if (existsSync(filePath)) {
+          const job: QueueJob = JSON.parse(readFileSync(filePath, "utf-8"));
+          job.status = "pending";
+          job.attempts = (job.attempts || 0) + 1;
+          job.error = undefined;
+
+          this.seq++;
+          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          const queueDir = join(this.basePath, q);
+          writeFileSync(join(queueDir, `${prefix}_${jobId}.queue-data`), JSON.stringify(job, null, 2));
+          unlinkSync(filePath);
+          return true;
+        }
+      }
+    } catch {
+      // ignore
+    }
+
+    return false;
+  }
+
+  deadLetters(queue: string, maxRetries: number = 3): QueueJob[] {
+    const failedDir = this.ensureFailedDir(queue);
+    const results: QueueJob[] = [];
+
+    try {
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data")).sort();
+      for (const file of files) {
+        try {
+          const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
+          if ((job.attempts || 0) >= maxRetries) {
+            job.status = "dead";
+            results.push(job);
+          }
+        } catch {
+          // skip corrupt files
+        }
+      }
+    } catch {
+      // directory might not exist
+    }
+
+    return results;
+  }
+
+  purge(queue: string, status: string, maxRetries: number = 3): number {
+    let count = 0;
+
+    if (status === "dead") {
+      const failedDir = this.ensureFailedDir(queue);
+      try {
+        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          try {
+            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
+            if ((job.attempts || 0) >= maxRetries) {
+              unlinkSync(join(failedDir, file));
+              count++;
+            }
+          } catch {
+            // skip corrupt files
+          }
+        }
+      } catch {
+        // directory might not exist
+      }
+    } else if (status === "failed") {
+      const failedDir = this.ensureFailedDir(queue);
+      try {
+        const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          try {
+            const job: QueueJob = JSON.parse(readFileSync(join(failedDir, file), "utf-8"));
+            if ((job.attempts || 0) < maxRetries) {
+              unlinkSync(join(failedDir, file));
+              count++;
+            }
+          } catch {
+            // skip corrupt files
+          }
+        }
+      } catch {
+        // directory might not exist
+      }
+    } else {
+      const dir = this.ensureDir(queue);
+      try {
+        const files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+        for (const file of files) {
+          try {
+            const job: QueueJob = JSON.parse(readFileSync(join(dir, file), "utf-8"));
+            if (job.status === status) {
+              unlinkSync(join(dir, file));
+              count++;
+            }
+          } catch {
+            // skip corrupt files
+          }
+        }
+      } catch {
+        // directory might not exist
+      }
+    }
+
+    return count;
+  }
+
+  retryFailed(queue: string, maxRetries: number = 3): number {
+    const failedDir = this.ensureFailedDir(queue);
+    const queueDir = this.ensureDir(queue);
+    let count = 0;
+
+    try {
+      const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
+      for (const file of files) {
+        try {
+          const filePath = join(failedDir, file);
+          const job: QueueJob = JSON.parse(readFileSync(filePath, "utf-8"));
+
+          if ((job.attempts || 0) >= maxRetries) {
+            continue;
+          }
+
+          job.status = "pending";
+          job.error = undefined;
+
+          this.seq++;
+          const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+          writeFileSync(join(queueDir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
+          unlinkSync(filePath);
+          count++;
+        } catch {
+          // skip corrupt files
+        }
+      }
+    } catch {
+      // directory might not exist
+    }
+
+    return count;
+  }
+
+  popById(queue: string, id: string): QueueJob | null {
+    const dir = this.ensureDir(queue);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
+    } catch {
+      return null;
+    }
+
+    for (const file of files) {
+      const filePath = join(dir, file);
+      let job: QueueJob;
+      try {
+        job = JSON.parse(readFileSync(filePath, "utf-8"));
+      } catch {
+        continue;
+      }
+
+      if (job.status !== "pending") continue;
+      if (job.id === id) {
+        try { unlinkSync(filePath); } catch { /* already consumed */ }
+        return job;
+      }
+    }
+
+    return null;
+  }
+
+  failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+    const failedDir = this.ensureFailedDir(queue);
+    job.status = "failed";
+    job.attempts = (job.attempts || 0) + 1;
+    job.error = error;
+
+    writeFileSync(join(failedDir, `${job.id}.queue-data`), JSON.stringify(job, null, 2));
+  }
+
+  retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    const dir = this.ensureDir(queue);
+    job.status = "pending";
+    job.attempts = (job.attempts || 0) + 1;
+    job.error = undefined;
+    job.delayUntil = delaySeconds ? new Date(Date.now() + delaySeconds * 1000).toISOString() : null;
+
+    this.seq++;
+    const prefix = `${Date.now()}-${String(this.seq).padStart(6, "0")}`;
+    writeFileSync(join(dir, `${prefix}_${job.id}.queue-data`), JSON.stringify(job, null, 2));
+  }
+}

package/packages/core/src/websocket.ts

@@ -170,6 +170,10 @@ export class WebSocketServer {
   private server: Server | null = null;
   private clients: Map<string, WebSocketClient> = new Map();
   private handlers: Map<string, EventHandler[]> = new Map();
+  /** rooms[roomName] = Set of clientIds */
+  private rooms: Map<string, Set<string>> = new Map();
+  /** clientRooms[clientId] = Set of roomNames */
+  private clientRooms: Map<string, Set<string>> = new Map();
 
   constructor(options?: { port?: number }) {
     this.port = options?.port ?? parseInt(process.env.TINA4_WS_PORT ?? "8080", 10);
@@ -281,6 +285,70 @@ export class WebSocketServer {
     return this.clients;
   }
 
+  // ── Rooms ──────────────────────────────────────────────────
+
+  /**
+   * Add a client to a named room.
+   */
+  joinRoom(clientId: string, roomName: string): void {
+    if (!this.rooms.has(roomName)) this.rooms.set(roomName, new Set());
+    this.rooms.get(roomName)!.add(clientId);
+
+    if (!this.clientRooms.has(clientId)) this.clientRooms.set(clientId, new Set());
+    this.clientRooms.get(clientId)!.add(roomName);
+  }
+
+  /**
+   * Remove a client from a named room.
+   */
+  leaveRoom(clientId: string, roomName: string): void {
+    this.rooms.get(roomName)?.delete(clientId);
+    this.clientRooms.get(clientId)?.delete(roomName);
+  }
+
+  /**
+   * Return the list of client IDs in a room.
+   */
+  getRoomConnections(roomName: string): string[] {
+    return Array.from(this.rooms.get(roomName) ?? []);
+  }
+
+  /**
+   * Return the number of clients in a room.
+   */
+  roomCount(roomName: string): number {
+    return this.rooms.get(roomName)?.size ?? 0;
+  }
+
+  /**
+   * Return the names of all rooms a client has joined.
+   */
+  getClientRooms(clientId: string): string[] {
+    return Array.from(this.clientRooms.get(clientId) ?? []);
+  }
+
+  /**
+   * Broadcast a message to all clients in a room.
+   */
+  broadcastToRoom(roomName: string, message: string, excludeIds?: string[]): void {
+    const members = this.rooms.get(roomName);
+    if (!members) return;
+
+    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
+    const exclude = new Set(excludeIds ?? []);
+
+    for (const clientId of members) {
+      if (exclude.has(clientId)) continue;
+      const client = this.clients.get(clientId);
+      if (!client || client.closed) continue;
+      try {
+        client.socket.write(frame);
+      } catch {
+        // client disconnected
+      }
+    }
+  }
+
   // ── Private ────────────────────────────────────────────────
 
   private emit(event: string, ...args: unknown[]): void {
@@ -348,12 +416,14 @@ export class WebSocketServer {
     socket.on("close", () => {
       client.closed = true;
       this.clients.delete(clientId);
+      this.removeClientFromAllRooms(clientId);
       this.emit("close", client);
     });
 
     socket.on("error", (err) => {
       client.closed = true;
       this.clients.delete(clientId);
+      this.removeClientFromAllRooms(clientId);
       this.emit("error", err, client);
     });
   }
@@ -405,6 +475,7 @@ export class WebSocketServer {
               // already closed
             }
             this.clients.delete(client.id);
+            this.removeClientFromAllRooms(client.id);
             this.emit("close", client);
           }
           break;
@@ -414,4 +485,14 @@ export class WebSocketServer {
 
     setBuffer(remaining);
   }
+
+  private removeClientFromAllRooms(clientId: string): void {
+    const rooms = this.clientRooms.get(clientId);
+    if (rooms) {
+      for (const roomName of rooms) {
+        this.rooms.get(roomName)?.delete(clientId);
+      }
+    }
+    this.clientRooms.delete(clientId);
+  }
 }

package/packages/orm/src/baseModel.ts

@@ -235,17 +235,95 @@ export class BaseModel {
     return instance;
   }
 
-  /** Alias for findById(). */
-  static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): T | null {
-    return (this as unknown as typeof BaseModel).findById.call(this, id, include) as T | null;
+  /**
+   * Find records by filter dict. Always returns an array.
+   *
+   * Usage:
+   *   User.find({ name: "Alice" })              → [User, ...]
+   *   User.find({ age: 18 }, 10)                → [User, ...] (limit 10)
+   *   User.find({}, 100, 0, "name ASC")         → [User, ...] (with orderBy)
+   *   User.find()                                → all records
+   *
+   * Use findById(id) for single-record primary key lookup.
+   */
+  static find<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    filter?: Record<string, unknown>,
+    limit = 100,
+    offset = 0,
+    orderBy?: string,
+    include?: string[],
+  ): T[] {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    const db = ModelClass.getDb();
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter) {
+      for (const [key, value] of Object.entries(filter)) {
+        const col = ModelClass.getDbColumn(key) ?? key;
+        conditions.push(`"${col}" = ?`);
+        params.push(value);
+      }
+    }
+
+    if (ModelClass.softDelete) {
+      conditions.push("is_deleted = 0");
+    }
+
+    let sql = `SELECT * FROM "${ModelClass.tableName}"`;
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    if (orderBy) {
+      sql += ` ORDER BY ${orderBy}`;
+    }
+
+    const rows = db.fetch(sql, params, limit, offset);
+    const data = (rows as any)?.data ?? rows;
+    const instances = (Array.isArray(data) ? data : []).map((row: Record<string, unknown>) => {
+      const inst = new this(row) as T;
+      (inst as any)._exists = true;
+      return inst;
+    });
+
+    if (include) {
+      ModelClass._eagerLoad(instances as BaseModel[], include);
+    }
+
+    return instances;
   }
 
   /**
    * Load a record into this instance via selectOne.
    * Returns true if found and loaded, false otherwise.
    */
-  load(sql: string, params?: unknown[], include?: string[]): boolean {
+  /**
+   * Load a record into this instance.
+   *
+   * Usage:
+   *   orm.id = 1; orm.load()          — uses PK already set
+   *   orm.load("id = ?", [1])         — filter with params
+   *   orm.load("id = 1")              — filter string
+   *
+   * Returns true if found, false otherwise.
+   */
+  load(filter?: string, params?: unknown[], include?: string[]): boolean {
     const ModelClass = this.constructor as typeof BaseModel & (new (data?: Record<string, unknown>) => BaseModel);
+    const table = (ModelClass as any).tableName ?? (this as any).tableName;
+
+    let sql: string;
+    if (filter === undefined || filter === null) {
+      // No args — use PK already set
+      const pk = (ModelClass as any).primaryKey ?? (this as any).primaryKey ?? "id";
+      const pkValue = (this as any)[pk];
+      if (pkValue === undefined || pkValue === null) return false;
+      sql = `SELECT * FROM ${table} WHERE ${pk} = ?`;
+      params = [pkValue];
+    } else {
+      sql = `SELECT * FROM ${table} WHERE ${filter}`;
+    }
+
     const result = ModelClass.selectOne(sql, params, include);
     if (!result) return false;
     const data = (result as any).toJSON ? (result as any).toJSON() : result;
@@ -338,7 +416,7 @@ export class BaseModel {
    * Save this instance (insert or update).
    * Returns this on success (fluent), null on failure.
    */
-  save(): this | null {
+  save(): this | false {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -381,7 +459,7 @@ export class BaseModel {
       db.commit();
     } catch (e) {
       db.rollback();
-      return null;
+      return false;
     }
     (this as any)._exists = true;
     return this;