tina4-nodejs 3.10.83 → 3.10.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.83",
+  "version": "3.10.85",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/auth.ts

@@ -32,31 +32,29 @@ function base64urlDecode(str: string): Buffer {
 /**
  * Create a signed JWT token.
  *
- * @param payload  - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
- * @param secret   - HMAC secret (HS256) or PEM private key (RS256)
+ * Secret is always read from `process.env.SECRET`.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ *
+ * @param payload   - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
  * @param expiresIn - Lifetime in seconds (default 3600)
- * @param algorithm - "HS256" or "RS256" (default "HS256")
  * @returns Signed JWT string: header.payload.signature
  */
 export function getToken(
   payload: Record<string, unknown>,
-  secret?: string,
-  expiresIn: number = 60,
-  algorithm: string = "HS256",
+  expiresIn: number = 3600,
 ): string {
+  const secret = process.env.SECRET ?? "";
   if (!secret) {
-    secret = process.env.SECRET ?? "";
-    if (!secret) {
-      console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
-    }
+    console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
+  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
 
   const header = { alg: algorithm, typ: "JWT" };
   const now = Math.floor(Date.now() / 1000);
 
   const claims: Record<string, unknown> = { ...payload, iat: now };
   if (expiresIn !== 0) {
-    claims.exp = now + Math.floor(expiresIn * 60);
+    claims.exp = now + expiresIn;
   }
 
   const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
@@ -68,39 +66,37 @@ export function getToken(
 }
 
 /**
- * Validate a JWT token and return the decoded payload, or null if invalid/expired.
+ * Validate a JWT token and return the decoded payload, or false if invalid/expired.
+ *
+ * Secret is always read from `process.env.SECRET`.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  */
-export function validToken(
-  token: string,
-  secret?: string,
-  algorithm: string = "HS256",
-): Record<string, unknown> | null {
+export function validToken(token: string): boolean {
+  const secret = process.env.SECRET ?? "";
   if (!secret) {
-    secret = process.env.SECRET ?? "";
-    if (!secret) {
-      console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
-    }
+    console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
+  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {
     const parts = token.split(".");
-    if (parts.length !== 3) return null;
+    if (parts.length !== 3) return false;
 
     const [h, p, sig] = parts;
     const signingInput = `${h}.${p}`;
 
-    if (!verifySignature(signingInput, sig, secret, algorithm)) {
-      return null;
+    if (!verifySignature(signingInput, sig, secret as string, algorithm)) {
+      return false;
     }
 
     const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
 
     if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) {
-      return null;
+      return false;
     }
 
-    return payload;
+    return true;
   } catch {
-    return null;
+    return false;
   }
 }
 
@@ -205,7 +201,7 @@ export function checkPassword(password: string, hash: string): boolean {
  * Authorization header. On success, attaches the decoded payload to
  * `(request as any).auth`. On failure, sends a 401 JSON response.
  */
-export function authMiddleware(secret: string, algorithm: string = "HS256"): Middleware {
+export function authMiddleware(secret?: string, algorithm: string = "HS256"): Middleware {
   return (req: Tina4Request, res: Tina4Response, next: () => void): void => {
     const authHeader = req.headers.authorization ?? "";
 
@@ -215,14 +211,12 @@ export function authMiddleware(secret: string, algorithm: string = "HS256"): Mid
     }
 
     const token = authHeader.slice(7);
-    const payload = validToken(token, secret, algorithm);
-
-    if (payload === null) {
+    if (!validToken(token)) {
       res({ error: "Unauthorized" }, 401);
       return;
     }
 
-    (req as any).auth = payload;
+    (req as any).auth = getPayload(token);
     next();
   };
 }
@@ -233,24 +227,24 @@ export function authMiddleware(secret: string, algorithm: string = "HS256"): Mid
  * Refresh a JWT token — validate the existing token then re-sign
  * with a fresh expiry.
  *
+ * Secret is always read from `process.env.SECRET`.
+ *
  * @param token     - Existing JWT to refresh
- * @param secret    - HMAC secret or PEM key
  * @param expiresIn - New lifetime in seconds (default 3600)
- * @param algorithm - "HS256" or "RS256" (default "HS256")
  * @returns New signed JWT string, or null if the input token is invalid/expired
  */
 export function refreshToken(
   token: string,
-  secret?: string,
-  expiresIn: number = 60,
-  algorithm: string = "HS256",
+  expiresIn: number = 3600,
 ): string | null {
-  const payload = validToken(token, secret, algorithm);
-  if (payload === null) return null;
+  if (!validToken(token)) return null;
+
+  const payload = getPayload(token);
+  if (!payload) return null;
 
   // Strip standard timing claims so getToken sets fresh ones
   const { iat: _iat, exp: _exp, ...claims } = payload;
-  return getToken(claims, secret, expiresIn, algorithm);
+  return getToken(claims, expiresIn);
 }
 
 // ── Request Authentication ───────────────────────────────────────
@@ -275,9 +269,8 @@ export function authenticateRequest(
 
   const token = authHeader.slice(7);
 
-  // Try JWT first
-  const payload = validToken(token, secret, algorithm);
-  if (payload !== null) return payload;
+  // Try JWT first (secret/algorithm params kept for backward compat but validToken reads from env)
+  if (validToken(token)) return getPayload(token);
 
   // Fallback: treat Bearer value as API key
   if (validateApiKey(token)) {

package/packages/core/src/middleware.ts

@@ -1,5 +1,5 @@
 import type { Tina4Request, Tina4Response, Middleware } from "./types.js";
-import { validToken } from "./auth.js";
+import { validToken, getPayload } from "./auth.js";
 
 export class MiddlewareChain {
   private middlewares: Middleware[] = [];
@@ -455,9 +455,7 @@ export class CsrfMiddleware {
     if (authHeader.startsWith("Bearer ")) {
       const bearerToken = authHeader.slice(7).trim();
       if (bearerToken) {
-        const secret = process.env.SECRET || "tina4-default-secret";
-        const payload = validToken(bearerToken, secret);
-        if (payload !== null) {
+        if (validToken(bearerToken)) {
           return [req, res];
         }
       }
@@ -494,10 +492,7 @@ export class CsrfMiddleware {
     }
 
     // Validate the token
-    const secret = process.env.SECRET || "tina4-default-secret";
-    const payload = validToken(token, secret);
-
-    if (payload === null) {
+    if (!validToken(token)) {
       res({
         error: "CSRF_INVALID",
         message: "Invalid or missing form token",
@@ -505,6 +500,8 @@ export class CsrfMiddleware {
       return [req, res];
     }
 
+    const payload = getPayload(token) ?? {};
+
     // Session binding — if token has session_id, verify it matches
     const tokenSessionId = payload.session_id as string | undefined;
     if (tokenSessionId) {

package/packages/core/src/queue.ts

@@ -57,7 +57,7 @@ export interface QueueBackendInterface {
   push(queue: string, payload: unknown, delay?: number): string;
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
-  clear(queue: string): void;
+  clear(queue: string): number;
 }
 
 // ── Queue ────────────────────────────────────────────────────
@@ -185,16 +185,16 @@ export class Queue {
   }
 
   /**
-   * Remove all jobs from this queue's topic.
+   * Remove all jobs from this queue's topic. Returns the number cleared.
    */
-  clear(): void {
+  clear(): number {
     const q = this.topic;
 
     if (this.externalBackend) {
       this.externalBackend.clear(q);
-      return;
+      return 0;
     }
-    this.liteBackend.clear(q);
+    return this.liteBackend.clear(q);
   }
 
   /**
@@ -205,10 +205,21 @@ export class Queue {
   }
 
   /**
-   * Retry a failed job by moving it back to the queue.
+   * Retry all dead letter jobs for this queue's topic.
+   * Moves failed jobs that exceeded max retries back to pending.
+   *
+   * @param delaySeconds - Optional delay before jobs become available
+   * @returns true if at least one job was re-queued, false if none found
    */
-  retry(jobId: string, delaySeconds?: number): boolean {
-    return this.liteBackend.retry(this.topic, jobId, delaySeconds);
+  retry(delaySeconds?: number): boolean {
+    const deadJobs = this.deadLetters();
+    if (deadJobs.length === 0) return false;
+    let retried = false;
+    for (const job of deadJobs) {
+      const ok = this.liteBackend.retry(this.topic, job.id, delaySeconds);
+      if (ok) retried = true;
+    }
+    return retried;
   }
 
   /**

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

@@ -122,12 +122,14 @@ export class LiteBackend {
     return count;
   }
 
-  clear(queue: string): void {
+  clear(queue: string): number {
     const dir = this.ensureDir(queue);
+    let count = 0;
     try {
       const files = readdirSync(dir).filter(f => f.endsWith(".queue-data"));
       for (const file of files) {
         unlinkSync(join(dir, file));
+        count++;
       }
     } catch {
       // directory might not exist
@@ -140,11 +142,13 @@ export class LiteBackend {
         const files = readdirSync(failedDir).filter(f => f.endsWith(".queue-data"));
         for (const file of files) {
           unlinkSync(join(failedDir, file));
+          count++;
         }
       }
     } catch {
       // ignore
     }
+    return count;
   }
 
   failed(queue: string): QueueJob[] {
@@ -168,7 +172,7 @@ export class LiteBackend {
     return results;
   }
 
-  retry(queue: string, jobId: string): boolean {
+  retry(queue: string, jobId: string, delaySeconds?: number): boolean {
     try {
       const queues = readdirSync(this.basePath);
       for (const q of queues) {
@@ -180,6 +184,7 @@ export class LiteBackend {
           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")}`;

package/packages/core/src/server.ts

@@ -8,7 +8,7 @@ import cluster from "node:cluster";
 import os from "node:os";
 import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
-import { validToken } from "./auth.js";
+import { validToken, getPayload } from "./auth.js";
 import { discoverRoutes } from "./routeDiscovery.js";
 import { createRequest, parseBody } from "./request.js";
 import { createResponse, setDefaultTemplatesDir } from "./response.js";
@@ -596,7 +596,7 @@ ${reset}
           console.log(`    \x1b[35m${definition.tableName}\x1b[0m (${Object.keys(definition.fields).length} fields)`);
         }
 
-        // Generate auto-CRUD routes (file-based routes take precedence)
+        // Generate auto-CRUD routes for all discovered models
         const crudRoutes = orm.generateCrudRoutes(models);
         for (const route of crudRoutes) {
           // Only add if no file-based route already handles this
@@ -791,15 +791,12 @@ ${reset}
         if (match.secure === true && match.noAuth !== true && !isDevAdmin) {
           const authHeader = req.headers.authorization ?? "";
           const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
-          const secret = process.env.SECRET || "";
-          const payload = token ? validToken(token, secret) : null;
-
-          if (!payload) {
+          if (!token || !validToken(token)) {
             res.raw.writeHead(401, { "Content-Type": "application/json" });
             res.raw.end(JSON.stringify({ error: "Unauthorized" }));
             return;
           }
-          req.user = payload;
+          req.user = getPayload(token) ?? {};
         }
 
         // Inject path params by name into handler arguments, then request/response

package/packages/orm/src/baseModel.ts

@@ -2,6 +2,7 @@ import { getAdapter, getNamedAdapter, setAdapter, parseDatabaseUrl } from "./dat
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
+import { QueryCache } from "./sqlTranslation.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 
 /**
@@ -54,6 +55,7 @@ export class BaseModel {
   static hasMany?: RelationshipDefinition[];
   static belongsTo?: RelationshipDefinition[];
   static _db?: string;
+  static _queryCache?: QueryCache;
 
   /**
    * When true, auto-generates fieldMapping entries from camelCase field names
@@ -69,6 +71,12 @@ export class BaseModel {
    */
   static fieldMapping: Record<string, string> = {};
 
+  /**
+   * When true, auto-generates CRUD routes for this model.
+   * Models must explicitly opt-in by setting `static autoCrud = true;`.
+   */
+  static autoCrud: boolean = false;
+
   /** Instance data */
   [key: string]: unknown;
 
@@ -468,7 +476,7 @@ export class BaseModel {
   /**
    * Delete this instance. Uses soft delete if configured.
    */
-  delete(): void {
+  delete(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -498,6 +506,7 @@ export class BaseModel {
       db.rollback();
       throw e;
     }
+    return true;
   }
 
   /**
@@ -630,9 +639,9 @@ export class BaseModel {
    * Generate and execute CREATE TABLE DDL from the model's field definitions.
    * Uses the adapter's createTable method if available, otherwise builds SQL directly.
    */
-  static createTable(): void {
+  static createTable(): boolean {
     const db = this.getDb();
-    if (db.tableExists(this.tableName)) return;
+    if (db.tableExists(this.tableName)) return true;
 
     if (typeof db.createTable === "function") {
       // Remap field keys to DB column names if fieldMapping is defined
@@ -679,6 +688,7 @@ export class BaseModel {
         throw e;
       }
     }
+    return true;
   }
 
   /**
@@ -693,6 +703,45 @@ export class BaseModel {
     return result;
   }
 
+  /**
+   * Return true if a record with the given primary key exists.
+   */
+  static exists(id: unknown): boolean {
+    const ModelClass = this as unknown as typeof BaseModel;
+    return ModelClass.findById(id) !== null;
+  }
+
+  /**
+   * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+   */
+  static cached<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    sql: string,
+    params?: unknown[],
+    ttl = 60,
+  ): T[] {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    if (!ModelClass._queryCache) {
+      ModelClass._queryCache = new QueryCache({ defaultTtl: ttl, maxSize: 500 });
+    }
+    const key = QueryCache.queryKey(`${ModelClass.tableName}:${sql}`, params ?? []);
+    const hit = ModelClass._queryCache.get(key) as T[] | undefined;
+    if (hit !== undefined) return hit;
+    const results = ModelClass.select<T>(sql, params);
+    ModelClass._queryCache.set(key, results, ttl);
+    return results;
+  }
+
+  /**
+   * Clear the per-model query cache.
+   */
+  static clearCache(): void {
+    const ModelClass = this as unknown as typeof BaseModel;
+    if (ModelClass._queryCache) {
+      ModelClass._queryCache.clear();
+    }
+  }
+
   /**
    * Execute a raw SQL SELECT and return results as model instances.
    */
@@ -725,7 +774,7 @@ export class BaseModel {
   /**
    * Permanently delete this instance, bypassing soft delete.
    */
-  forceDelete(): void {
+  forceDelete(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -747,12 +796,13 @@ export class BaseModel {
       db.rollback();
       throw e;
     }
+    return true;
   }
 
   /**
    * Restore a soft-deleted record.
    */
-  restore(): void {
+  restore(): boolean {
     const ModelClass = this.constructor as typeof BaseModel;
     if (!ModelClass.softDelete) {
       throw new Error("restore() is only available on models with softDelete enabled");
@@ -779,6 +829,7 @@ export class BaseModel {
       throw e;
     }
     this.is_deleted = 0;
+    return true;
   }
 
   /**

package/packages/orm/src/index.ts

@@ -32,6 +32,7 @@ export {
   migrate,
   createMigration,
   status,
+  Migration,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { generateCrudRoutes } from "./autoCrud.js";

package/packages/orm/src/migration.ts

@@ -745,3 +745,84 @@ export async function createMigration(
 
   return { upPath, downPath };
 }
+
+/**
+ * Object-oriented Migration class — canonical Tina4 Migration API.
+ *
+ * Provides parity with Python, PHP, and Ruby:
+ *   - migrate()           Run all pending migrations
+ *   - rollback(steps=1)   Roll back last N batches
+ *   - status()            Show completed/pending
+ *   - create(description) Scaffold new .sql + .down.sql files
+ *   - getApplied()        List applied migrations
+ *   - getPending()        List pending migration filenames
+ *   - getFiles()          List all migration files on disk
+ *
+ * @example
+ *   const m = new Migration(db, { migrationsDir: "migrations" });
+ *   await m.migrate();
+ *   await m.rollback(2);
+ *   await m.status();
+ *   await m.create("add users table");
+ */
+export class Migration {
+  private db?: DatabaseAdapter;
+  private dir: string;
+  private delimiter: string;
+
+  constructor(db?: DatabaseAdapter, options?: { migrationsDir?: string; delimiter?: string }) {
+    this.db = db;
+    this.dir = options?.migrationsDir ?? "migrations";
+    this.delimiter = options?.delimiter ?? ";";
+  }
+
+  /** Run all pending migrations. Returns applied/skipped/failed summary. */
+  async migrate(): Promise<MigrationResult> {
+    return migrate(this.db, { migrationsDir: this.dir, delimiter: this.delimiter });
+  }
+
+  /** Roll back the last N batches. Returns list of rolled-back migration names. */
+  async rollback(steps = 1): Promise<string[]> {
+    const db = this.db ?? (await import("./database.js")).getAdapter();
+    // If tracking table doesn't exist yet there's nothing to roll back
+    if (!db.tableExists(MIGRATION_TABLE)) return [];
+    const rolled: string[] = [];
+    for (let i = 0; i < steps; i++) {
+      const batch = rollback(this.dir, this.delimiter);
+      if (batch.length === 0) break;
+      rolled.push(...batch);
+    }
+    return rolled;
+  }
+
+  /** Get migration status: which are completed and which are pending. */
+  async status(): Promise<MigrationStatus> {
+    return status(this.db, { migrationsDir: this.dir });
+  }
+
+  /** Scaffold a new .sql + .down.sql migration file. Returns created paths. */
+  async create(description: string): Promise<{ upPath: string; downPath: string }> {
+    return createMigration(description, { migrationsDir: this.dir });
+  }
+
+  /** Return list of completed (applied) migration filenames. */
+  async getApplied(): Promise<string[]> {
+    const s = await this.status();
+    return s.completed;
+  }
+
+  /** Return list of pending migration filenames. */
+  async getPending(): Promise<string[]> {
+    const s = await this.status();
+    return s.pending;
+  }
+
+  /** Return sorted list of all migration files on disk (excludes .down.sql). */
+  getFiles(): string[] {
+    const dir = resolve(this.dir);
+    if (!existsSync(dir)) return [];
+    return sortMigrationFiles(
+      readdirSync(dir).filter((f) => f.endsWith(".sql") && !f.endsWith(".down.sql")),
+    );
+  }
+}