tina4-nodejs 3.9.1 → 3.9.3

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.2)
 
 > 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.2 — 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.
 
@@ -38,12 +38,12 @@ tina4-nodejs/
         service.ts       # Service layer helpers
         session.ts       # Session management
         testing.ts       # Inline testing framework (attach tests to functions)
-        websocket.ts     # WebSocket support
+        websocket.ts     # WebSocket support (with backplane)
         wsdl.ts          # WSDL / SOAP support
     orm/        # Database adapters, models, auto-CRUD, query builder, seeding
       src/
         adapters/
-          sqlite.ts        # SQLite via better-sqlite3 (default)
+          sqlite.ts        # SQLite via node:sqlite (default)
           postgres.ts      # PostgreSQL adapter
           mysql.ts         # MySQL adapter
           mssql.ts         # MSSQL / SQL Server adapter
@@ -69,7 +69,7 @@ This is an **npm workspaces monorepo**. All packages are in `packages/*`.
 - **Language:** TypeScript (strict mode, ES2022 target, Node16 module resolution)
 - **Runtime:** Node.js 20+ (ESM only, `"type": "module"` everywhere)
 - **HTTP:** Native `node:http` — no Express, no Fastify
-- **Database:** SQLite via `better-sqlite3` (default), with adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird
+- **Database:** SQLite via `node:sqlite` (default), with adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird
 - **Templates:** Twig via `twig` npm package (optional)
 - **Dev tooling:** `tsx` for runtime TS execution, `esbuild` for builds
 - **Testing:** 43 test files via `tsx test/run-all.ts`
@@ -120,8 +120,8 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `devAdmin.ts` — Dev toolbar (fixed bottom bar injected into HTML pages) and admin dashboard at `/_dev/`
 - `auth.ts` — Authentication helpers
 - `cache.ts` — In-memory caching
-- `session.ts` — Session management with pluggable handlers
-- `websocket.ts` — WebSocket support
+- `session.ts` — Session management with pluggable handlers. `TINA4_SESSION_SAMESITE` env var (default: Lax)
+- `websocket.ts` — WebSocket support with backplane for scaling via Redis pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`)
 - `queue.ts` — Queue system with pluggable backends
 - `graphql.ts` — GraphQL engine
 - `i18n.ts` — Internationalization / localization
@@ -139,7 +139,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 
 **Key files:**
 - `database.ts` — Adapter manager, `initDatabase()` factory
-- `adapters/sqlite.ts` — `better-sqlite3` implementation of `DatabaseAdapter` interface
+- `adapters/sqlite.ts` — `node:sqlite` implementation of `DatabaseAdapter` interface
 - `adapters/postgres.ts` — PostgreSQL adapter
 - `adapters/mysql.ts` — MySQL adapter
 - `adapters/mssql.ts` — MSSQL / SQL Server adapter (`mssql` or `sqlserver` scheme)
@@ -153,6 +153,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `fakeData.ts` — ORM-aware fake data extending core (adds `forField()` with column-name heuristics)
 - `seeder.ts` — Database seeding (`seedTable` for raw SQL, `seedOrm` for model-based)
 - `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
+- QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 
 ### @tina4/swagger (`packages/swagger/`)
 Auto-generates OpenAPI 3.0 docs.
@@ -173,7 +174,7 @@ Developer-facing CLI commands.
 
 **Key files:**
 - `bin.ts` — Entry point, command dispatch (`init`, `serve`, `--help`)
-- `commands/init.ts` — Scaffolds a new project directory with sample files
+- `commands/init.ts` — Scaffolds a new project directory with sample files, Dockerfile, and .dockerignore
 - `commands/serve.ts` — Starts dev server with hot-reload via `@tina4/core`
 
 ## Module: Events (`packages/core/src/events.ts`)
@@ -469,7 +470,7 @@ import { Router } from "./router.js";  // .js even though the file is .ts
 3. **Convention-based models** — `static fields = {}` over decorators. No special TypeScript config needed.
 4. **CDN for Swagger UI** — Keeps install under 8MB. Single HTML file loads from unpkg.com.
 5. **Process restart for hot-reload** — Simpler and more reliable than HMR with ESM.
-6. **SQLite default** — `better-sqlite3` is synchronous and fast. Full adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird.
+6. **SQLite default** — `node:sqlite` is synchronous and fast. Full adapters for Postgres, MySQL, MSSQL/SQL Server, and Firebird.
 7. **CLI named `tina4nodejs`** (primary) with `tina4` as alias — So `npx tina4nodejs init` or `npx tina4 init` both work.
 8. **Event system** — Static `Events` class, synchronous dispatch, priority ordering, zero deps.
 9. **Inline testing** — Tests as decorators on functions, no external test runner for unit-level checks.
@@ -531,7 +532,7 @@ await initDatabase({ type: "postgres", host: "localhost", port: 5432, database:
 ### Available adapters
 | Adapter | Scheme(s) | Package |
 |---------|-----------|---------|
-| SQLite | `sqlite://` | `better-sqlite3` |
+| SQLite | `sqlite://` | `node:sqlite` |
 | PostgreSQL | `postgres://`, `postgresql://` | `pg` |
 | MySQL | `mysql://` | `mysql2` |
 | MSSQL | `mssql://`, `sqlserver://` | `tedious` |
@@ -586,12 +587,16 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode
 - **`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
+- **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
+- **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`)
 - **Frond pre-compilation**: 2.8x template render improvement
+- **QueryBuilder** with NoSQL/MongoDB support (`toMongo()`)
+- **WebSocket backplane** (Redis pub/sub) for horizontal scaling
+- **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
+- **`tina4 init`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/_dev/`
 
 ## Don'ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.9.1",
+  "version": "3.9.3",
   "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.
    */