tina4-nodejs 3.10.11 → 3.10.12

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.11)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.12)
 
 > 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.10.11 — a convention-over-configuration structural paradigm. **Not a framework.** The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.10.12 — 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.11",
+  "version": "3.10.12",
   "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/index.ts

@@ -98,3 +98,5 @@ export { Container, container } from "./container.js";
 export { Validator } from "./validator.js";
 export type { ValidationError } from "./validator.js";
 export type { WebSocketConnection } from "./websocketConnection.js";
+export { RedisBackplane, NATSBackplane, createBackplane } from "./websocketBackplane.js";
+export type { WebSocketBackplane } from "./websocketBackplane.js";

package/packages/core/src/server.ts

@@ -594,6 +594,12 @@ ${reset}
       const origEnd = rawRes.end.bind(rawRes);
       rawRes.end = function (...args: any[]) {
         sess.save();
+
+        // Probabilistic garbage collection (~1% of requests)
+        if (Math.floor(Math.random() * 100) === 0) {
+          try { sess.gc(); } catch { /* GC failure is non-critical */ }
+        }
+
         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);

package/packages/core/src/session.ts

@@ -25,7 +25,7 @@
  *   session.destroy();
  */
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { RedisNpmSessionHandler } from "./sessionHandlers/redisHandler.js";
@@ -70,6 +70,8 @@ export interface SessionHandler {
   read(sessionId: string): SessionData | null;
   write(sessionId: string, data: SessionData, ttl: number): void;
   destroy(sessionId: string): void;
+  /** Garbage-collect expired sessions. Optional — Redis/Valkey/Mongo handle TTL natively. */
+  gc?(maxLifetime: number): void;
 }
 
 // ── File Session Handler ──────────────────────────────────────────
@@ -115,6 +117,28 @@ export class FileSessionHandler implements SessionHandler {
       if (existsSync(filePath)) unlinkSync(filePath);
     } catch { /* ignore */ }
   }
+
+  gc(maxLifetime: number): void {
+    if (!existsSync(this.storagePath)) return;
+    const now = Math.floor(Date.now() / 1000);
+    try {
+      const files = readdirSync(this.storagePath);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const fullPath = join(this.storagePath, file);
+        try {
+          const raw = readFileSync(fullPath, "utf-8");
+          const data = JSON.parse(raw) as SessionData;
+          if (data._accessed && (now - data._accessed) > maxLifetime) {
+            unlinkSync(fullPath);
+          }
+        } catch {
+          // Corrupt file — remove it
+          try { unlinkSync(fullPath); } catch { /* ignore */ }
+        }
+      }
+    } catch { /* ignore */ }
+  }
 }
 
 // ── Redis Session Handler (raw TCP, zero dependencies) ────────────
@@ -499,6 +523,16 @@ export class Session {
     return this.sessionId;
   }
 
+  /**
+   * Run garbage collection on the session backend.
+   * Removes expired file/database sessions. Redis/Valkey/Mongo handle TTL natively.
+   */
+  gc(): void {
+    if (this.handler.gc) {
+      this.handler.gc(this.ttl);
+    }
+  }
+
   // ── Private ───────────────────────────────────────────────────
 
   private save(): void {

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -119,4 +119,12 @@ export class DatabaseSessionHandler implements SessionHandler {
       .prepare("DELETE FROM tina4_session WHERE session_id = ?")
       .run(sessionId);
   }
+
+  gc(_maxLifetime: number): void {
+    this.ensureTable();
+    const now = Date.now() / 1000;
+    this.db
+      .prepare("DELETE FROM tina4_session WHERE expires_at > 0 AND expires_at < ?")
+      .run(now);
+  }
 }

package/packages/core/src/websocketBackplane.ts

@@ -98,6 +98,84 @@ export class RedisBackplane implements WebSocketBackplane {
   }
 }
 
+/**
+ * NATS pub/sub backplane.
+ *
+ * Requires the `nats` package (`npm install nats`). 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.
+ *
+ * NATS is async-native. The subscription listener runs via the NATS client's
+ * built-in async iteration.
+ */
+export class NATSBackplane implements WebSocketBackplane {
+  private nc: any;
+  private url: string;
+  private subs: Map<string, any> = new Map();
+  private ready: Promise<void>;
+
+  constructor(url?: string) {
+    this.url = url ?? process.env.TINA4_WS_BACKPLANE_URL ?? "nats://localhost:4222";
+
+    this.ready = (async () => {
+      let nats: any;
+      try {
+        nats = await import("nats");
+      } catch {
+        throw new Error(
+          "The 'nats' package is required for NATSBackplane. " +
+          "Install it with: npm install nats"
+        );
+      }
+
+      this.nc = await nats.connect({ servers: this.url });
+      console.log(`[Tina4] NATSBackplane connected to ${this.url}`);
+    })();
+  }
+
+  async publish(channel: string, message: string): Promise<void> {
+    await this.ready;
+    const { StringCodec } = await import("nats");
+    const sc = StringCodec();
+    this.nc.publish(channel, sc.encode(message));
+  }
+
+  async subscribe(channel: string, callback: (message: string) => void): Promise<void> {
+    await this.ready;
+    const { StringCodec } = await import("nats");
+    const sc = StringCodec();
+    const sub = this.nc.subscribe(channel);
+    this.subs.set(channel, sub);
+
+    // Process messages in the background via async iteration
+    (async () => {
+      for await (const msg of sub) {
+        try {
+          callback(sc.decode(msg.data));
+        } catch { /* ignore callback errors */ }
+      }
+    })();
+  }
+
+  async unsubscribe(channel: string): Promise<void> {
+    const sub = this.subs.get(channel);
+    if (sub) {
+      sub.unsubscribe();
+      this.subs.delete(channel);
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const sub of this.subs.values()) {
+      sub.unsubscribe();
+    }
+    this.subs.clear();
+    if (this.nc) {
+      await this.nc.close();
+    }
+  }
+}
+
 /**
  * Factory that reads TINA4_WS_BACKPLANE and returns the appropriate
  * backplane instance, or `null` if no backplane is configured.
@@ -112,7 +190,7 @@ export function createBackplane(url?: string): WebSocketBackplane | null {
     case "redis":
       return new RedisBackplane(url);
     case "nats":
-      throw new Error("NATS backplane is on the roadmap but not yet implemented.");
+      return new NATSBackplane(url);
     case "":
       return null;
     default: