tina4-nodejs 3.9.1 → 3.9.2

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.8.0)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.9.1)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.8.0 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.9.1 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -587,7 +587,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **`npx tina4nodejs generate`**: model, route, migration, middleware scaffolding
 - **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), query caching (`TINA4_DB_CACHE=true`)
 - **Sessions**: file backend (default)
-- **Queue**: SQLite/RabbitMQ/Kafka/MongoDB backends, configured via env vars
+- **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: memory/Redis/file backends
 - **Messenger**: .env driven SMTP/IMAP
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "type": "module",
   "description": "This is not a framework. Tina4 for Node.js/TypeScript — zero deps, 38 built-in features.",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/server.ts

@@ -585,7 +585,8 @@ ${reset}
         const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
         if (newSid && newSid !== existingSid && !rawRes.headersSent) {
           const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-          rawRes.setHeader("Set-Cookie", `tina4_session=${newSid}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${ttl}`);
+          const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
+          rawRes.setHeader("Set-Cookie", `tina4_session=${newSid}; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=${ttl}`);
         }
         return origEnd(...args);
       } as typeof rawRes.end;

package/packages/core/src/websocketBackplane.ts

@@ -0,0 +1,120 @@
+/**
+ * WebSocket Backplane Abstraction for Tina4 Node.js.
+ *
+ * Enables broadcasting WebSocket messages across multiple server instances
+ * using a shared pub/sub channel (e.g. Redis). Without a backplane configured,
+ * broadcast() only reaches connections on the local process.
+ *
+ * Configuration via environment variables:
+ *   TINA4_WS_BACKPLANE     — Backend type: "redis", "nats", or "" (default: none)
+ *   TINA4_WS_BACKPLANE_URL — Connection string (default: redis://localhost:6379)
+ *
+ * Usage:
+ *   const backplane = createBackplane();
+ *   if (backplane) {
+ *     backplane.subscribe("chat", (msg) => relayToLocal(msg));
+ *     backplane.publish("chat", '{"user":"A","text":"hello"}');
+ *   }
+ */
+
+/**
+ * Base interface for scaling WebSocket broadcast across instances.
+ *
+ * Implementations relay messages over a shared bus so every server instance
+ * receives every broadcast, not just the originator.
+ */
+export interface WebSocketBackplane {
+  /** Publish a message to all instances listening on `channel`. */
+  publish(channel: string, message: string): Promise<void>;
+
+  /** Subscribe to `channel`. `callback` is invoked with each incoming message. */
+  subscribe(channel: string, callback: (message: string) => void): Promise<void>;
+
+  /** Stop listening on `channel`. */
+  unsubscribe(channel: string): Promise<void>;
+
+  /** Tear down connections. */
+  close(): Promise<void>;
+}
+
+/**
+ * Redis pub/sub backplane.
+ *
+ * Requires the `redis` package (`npm install redis`). The import is deferred
+ * so the rest of Tina4 works fine without it installed — an error is thrown
+ * only when this class is actually instantiated.
+ */
+export class RedisBackplane implements WebSocketBackplane {
+  private publisher: any;
+  private subscriber: any;
+  private url: string;
+  private ready: Promise<void>;
+
+  constructor(url?: string) {
+    this.url = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "redis://localhost:6379";
+
+    let redis: any;
+    try {
+      redis = require("redis");
+    } catch {
+      throw new Error(
+        "The 'redis' package is required for RedisBackplane. " +
+        "Install it with: npm install redis"
+      );
+    }
+
+    this.publisher = redis.createClient({ url: this.url });
+    this.subscriber = this.publisher.duplicate();
+
+    this.ready = Promise.all([
+      this.publisher.connect(),
+      this.subscriber.connect(),
+    ]).then(() => {
+      console.log(`[Tina4] RedisBackplane connected to ${this.url}`);
+    });
+  }
+
+  async publish(channel: string, message: string): Promise<void> {
+    await this.ready;
+    await this.publisher.publish(channel, message);
+  }
+
+  async subscribe(channel: string, callback: (message: string) => void): Promise<void> {
+    await this.ready;
+    await this.subscriber.subscribe(channel, (message: string) => {
+      callback(message);
+    });
+  }
+
+  async unsubscribe(channel: string): Promise<void> {
+    await this.ready;
+    await this.subscriber.unsubscribe(channel);
+  }
+
+  async close(): Promise<void> {
+    await this.publisher.quit();
+    await this.subscriber.quit();
+  }
+}
+
+/**
+ * Factory that reads TINA4_WS_BACKPLANE and returns the appropriate
+ * backplane instance, or `null` if no backplane is configured.
+ *
+ * This keeps backplane usage entirely optional — callers simply check
+ * `if (backplane)` before publishing.
+ */
+export function createBackplane(url?: string): WebSocketBackplane | null {
+  const backend = (process.env.TINA4_WS_BACKPLANE ?? "").trim().toLowerCase();
+
+  switch (backend) {
+    case "redis":
+      return new RedisBackplane(url);
+    case "nats":
+      throw new Error("NATS backplane is on the roadmap but not yet implemented.");
+    case "":
+      return null;
+    default:
+      throw new Error(`Unknown TINA4_WS_BACKPLANE value: '${backend}'`);
+  }
+}

package/packages/orm/src/queryBuilder.ts

@@ -268,6 +268,198 @@ export class QueryBuilder {
     return this.count() > 0;
   }
 
+  /**
+   * Convert the fluent builder state into a MongoDB-compatible query document.
+   *
+   * @returns An object with filter, projection, sort, limit, skip (only non-empty keys).
+   */
+  toMongo(): {
+    filter?: Record<string, unknown>;
+    projection?: Record<string, number>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+  } {
+    const result: Record<string, unknown> = {};
+
+    // -- projection --
+    if (
+      this.columns.length !== 1 ||
+      this.columns[0] !== "*"
+    ) {
+      const projection: Record<string, number> = {};
+      for (const col of this.columns) {
+        projection[col.trim()] = 1;
+      }
+      result.projection = projection;
+    }
+
+    // -- filter --
+    if (this.wheres.length > 0) {
+      let paramIndex = 0;
+      const andConditions: Record<string, unknown>[] = [];
+      const orConditions: Record<string, unknown>[] = [];
+
+      for (let i = 0; i < this.wheres.length; i++) {
+        const [connector, condition] = this.wheres[i];
+        const [mongoCond, newIndex] = this.parseConditionToMongo(
+          condition,
+          paramIndex,
+        );
+        paramIndex = newIndex;
+        if (i === 0 || connector === "AND") {
+          andConditions.push(mongoCond);
+        } else {
+          orConditions.push(mongoCond);
+        }
+      }
+
+      if (orConditions.length > 0) {
+        const andMerged = this.mergeMongoConditions(andConditions);
+        const allBranches = [andMerged, ...orConditions];
+        result.filter = { $or: allBranches };
+      } else {
+        result.filter = this.mergeMongoConditions(andConditions);
+      }
+    }
+
+    // -- sort --
+    if (this.orderByCols.length > 0) {
+      const sort: Record<string, 1 | -1> = {};
+      for (const expr of this.orderByCols) {
+        const parts = expr.trim().split(/\s+/);
+        const field = parts[0];
+        const direction: 1 | -1 =
+          parts.length > 1 && parts[1].toUpperCase() === "DESC" ? -1 : 1;
+        sort[field] = direction;
+      }
+      result.sort = sort;
+    }
+
+    // -- limit / skip --
+    if (this.limitVal !== undefined) {
+      result.limit = this.limitVal;
+    }
+    if (this.offsetVal !== undefined) {
+      result.skip = this.offsetVal;
+    }
+
+    return result as {
+      filter?: Record<string, unknown>;
+      projection?: Record<string, number>;
+      sort?: Record<string, 1 | -1>;
+      limit?: number;
+      skip?: number;
+    };
+  }
+
+  /**
+   * Parse a single SQL condition string into a MongoDB filter object.
+   */
+  private parseConditionToMongo(
+    condition: string,
+    paramIndex: number,
+  ): [Record<string, unknown>, number] {
+    const cond = condition.trim();
+
+    // IS NOT NULL
+    let match = cond.match(/^(\w+)\s+IS\s+NOT\s+NULL$/i);
+    if (match) {
+      return [{ [match[1]]: { $exists: true, $ne: null } }, paramIndex];
+    }
+
+    // IS NULL
+    match = cond.match(/^(\w+)\s+IS\s+NULL$/i);
+    if (match) {
+      return [{ [match[1]]: { $exists: false } }, paramIndex];
+    }
+
+    // NOT IN
+    match = cond.match(/^(\w+)\s+NOT\s+IN\s*\(\s*\?\s*\)$/i);
+    if (match) {
+      const val = this.params[paramIndex] ?? [];
+      const values = Array.isArray(val) ? val : [val];
+      return [{ [match[1]]: { $nin: values } }, paramIndex + 1];
+    }
+
+    // IN
+    match = cond.match(/^(\w+)\s+IN\s*\(\s*\?\s*\)$/i);
+    if (match) {
+      const val = this.params[paramIndex] ?? [];
+      const values = Array.isArray(val) ? val : [val];
+      return [{ [match[1]]: { $in: values } }, paramIndex + 1];
+    }
+
+    // LIKE
+    match = cond.match(/^(\w+)\s+LIKE\s+\?$/i);
+    if (match) {
+      const val = String(this.params[paramIndex] ?? "");
+      const pattern = val.replace(/%/g, ".*").replace(/_/g, ".");
+      return [
+        { [match[1]]: { $regex: pattern, $options: "i" } },
+        paramIndex + 1,
+      ];
+    }
+
+    // Comparison operators: >=, <=, <>, !=, >, <, =
+    match = cond.match(/^(\w+)\s*(>=|<=|<>|!=|>|<|=)\s*\?$/);
+    if (match) {
+      const field = match[1];
+      const op = match[2];
+      const val = this.params[paramIndex] ?? null;
+
+      const opMap: Record<string, string | null> = {
+        "=": null,
+        "!=": "$ne",
+        "<>": "$ne",
+        ">": "$gt",
+        ">=": "$gte",
+        "<": "$lt",
+        "<=": "$lte",
+      };
+
+      const mongoOp = opMap[op];
+      if (mongoOp === null || mongoOp === undefined) {
+        return [{ [field]: val }, paramIndex + 1];
+      }
+      return [{ [field]: { [mongoOp]: val } }, paramIndex + 1];
+    }
+
+    // Fallback
+    return [{ $where: cond }, paramIndex];
+  }
+
+  /**
+   * Merge multiple single-field mongo condition objects into one.
+   * Uses $and if field keys conflict.
+   */
+  private mergeMongoConditions(
+    conditions: Record<string, unknown>[],
+  ): Record<string, unknown> {
+    if (conditions.length === 1) {
+      return conditions[0];
+    }
+
+    const merged: Record<string, unknown> = {};
+    let hasConflict = false;
+
+    outer: for (const cond of conditions) {
+      for (const key of Object.keys(cond)) {
+        if (key in merged) {
+          hasConflict = true;
+          break outer;
+        }
+        merged[key] = cond[key];
+      }
+    }
+
+    if (hasConflict) {
+      return { $and: conditions };
+    }
+
+    return merged;
+  }
+
   /**
    * Build the WHERE clause from accumulated conditions.
    */