tina4-nodejs 3.10.90 → 3.10.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.90",
+  "version": "3.10.91",
   "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/api.ts

@@ -36,7 +36,7 @@ export class Api {
     /**
      * Add custom headers to all subsequent requests.
      */
-    addCustomHeaders(headers: Record<string, string>): void {
+    addHeaders(headers: Record<string, string>): void {
         Object.assign(this.headers, headers);
     }
 
@@ -78,36 +78,36 @@ export class Api {
      * HTTP POST request.
      */
     async post(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "POST", body, contentType);
+        return this.sendRequest("POST", path, body, contentType);
     }
 
     /**
      * HTTP PUT request.
      */
     async put(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "PUT", body, contentType);
+        return this.sendRequest("PUT", path, body, contentType);
     }
 
     /**
      * HTTP PATCH request.
      */
     async patch(path: string, body?: unknown, contentType: string = "application/json"): Promise<ApiResult> {
-        return this.sendRequest(path, "PATCH", body, contentType);
+        return this.sendRequest("PATCH", path, body, contentType);
     }
 
     /**
      * HTTP DELETE request.
      */
     async delete(path: string, body?: unknown): Promise<ApiResult> {
-        return this.sendRequest(path, "DELETE", body);
+        return this.sendRequest("DELETE", path, body);
     }
 
     /**
      * Generic request method — public entry point for any HTTP method.
      */
     async sendRequest(
-        path: string,
         method: string,
+        path: string,
         body?: unknown,
         contentType: string = "application/json",
     ): Promise<ApiResult> {

package/packages/core/src/auth.ts

@@ -35,32 +35,45 @@ function base64urlDecode(str: string): Buffer {
  * 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 payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
+ * @param secretOrExpiresIn - Signing secret string, OR expiresIn number (back-compat with old 2-arg form)
+ * @param expiresIn         - Lifetime in seconds (default 3600). Only used when secret is a string.
  * @returns Signed JWT string: header.payload.signature
  */
 export function getToken(
   payload: Record<string, unknown>,
+  secretOrExpiresIn?: string | number,
   expiresIn: number = 3600,
+  algorithm?: string,
 ): string {
-  const secret = process.env.SECRET ?? "";
-  if (!secret) {
+  // Back-compat: if second arg is a number, treat it as expiresIn (old 2-arg form)
+  let resolvedSecret: string;
+  let resolvedExpiresIn: number;
+  if (typeof secretOrExpiresIn === "number") {
+    resolvedSecret = process.env.SECRET ?? "";
+    resolvedExpiresIn = secretOrExpiresIn;
+  } else {
+    resolvedSecret = secretOrExpiresIn ?? process.env.SECRET ?? "";
+    resolvedExpiresIn = expiresIn;
+  }
+
+  if (!resolvedSecret) {
     console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
-  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
 
-  const header = { alg: algorithm, typ: "JWT" };
+  const header = { alg: resolvedAlgorithm, typ: "JWT" };
   const now = Math.floor(Date.now() / 1000);
 
   const claims: Record<string, unknown> = { ...payload, iat: now };
-  if (expiresIn !== 0) {
-    claims.exp = now + expiresIn;
+  if (resolvedExpiresIn !== 0) {
+    claims.exp = now + resolvedExpiresIn;
   }
 
   const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
   const p = base64urlEncode(Buffer.from(JSON.stringify(claims)));
   const signingInput = `${h}.${p}`;
-  const signature = sign(signingInput, secret, algorithm);
+  const signature = sign(signingInput, resolvedSecret, resolvedAlgorithm);
 
   return `${h}.${p}.${signature}`;
 }
@@ -71,12 +84,12 @@ export function getToken(
  * Secret is always read from `process.env.SECRET`.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  */
-export function validToken(token: string): boolean {
-  const secret = process.env.SECRET ?? "";
-  if (!secret) {
+export function validToken(token: string, secret?: string, algorithm?: string): boolean {
+  const resolvedSecret = secret ?? process.env.SECRET ?? "";
+  if (!resolvedSecret) {
     console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
   }
-  const algorithm = process.env.TINA4_JWT_ALGORITHM ?? "HS256";
+  const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return false;
@@ -84,7 +97,7 @@ export function validToken(token: string): boolean {
     const [h, p, sig] = parts;
     const signingInput = `${h}.${p}`;
 
-    if (!verifySignature(signingInput, sig, secret as string, algorithm)) {
+    if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
       return false;
     }
 
@@ -211,7 +224,7 @@ export function authMiddleware(secret?: string, algorithm: string = "HS256"): Mi
     }
 
     const token = authHeader.slice(7);
-    if (!validToken(token)) {
+    if (!validToken(token, secret, algorithm)) {
       res({ error: "Unauthorized" }, 401);
       return;
     }

package/packages/core/src/cache.ts

@@ -501,6 +501,15 @@ export function cacheClear(): void {
   _getBackend().clear();
 }
 
+/** Remove expired entries from the cache. Returns count removed. */
+export function sweep(): number {
+  const backend = _getBackend();
+  if (typeof (backend as any).sweep === "function") {
+    return (backend as any).sweep();
+  }
+  return 0;
+}
+
 /** Return cache statistics from the active backend. */
 export function cacheBackendStats(): { hits: number; misses: number; size: number; backend: string } {
   return _getBackend().stats();

package/packages/core/src/fakeData.ts

@@ -68,12 +68,6 @@ const JOB_TITLES = [
   "Systems Administrator",
 ];
 
-const COLORS = [
-  "red", "blue", "green", "yellow", "purple", "orange", "pink",
-  "cyan", "magenta", "teal", "indigo", "violet", "coral", "salmon",
-  "turquoise", "maroon", "navy", "olive", "silver", "gold",
-];
-
 const CURRENCIES = [
   "USD", "EUR", "GBP", "JPY", "AUD", "CAD", "CHF", "CNY",
   "SEK", "NZD", "MXN", "SGD", "HKD", "NOK", "ZAR", "INR",
@@ -137,7 +131,7 @@ export class FakeData {
     return this.pick(LAST_NAMES);
   }
 
-  fullName(): string {
+  name(): string {
     return `${this.firstName()} ${this.lastName()}`;
   }
 
@@ -209,7 +203,7 @@ export class FakeData {
     return this.randInt(min, max + 1);
   }
 
-  float(min = 0, max = 1000, decimals = 2): number {
+  numeric(min = 0, max = 1000, decimals = 2): number {
     const raw = min + this.rng() * (max - min);
     return Number(raw.toFixed(decimals));
   }
@@ -251,11 +245,7 @@ export class FakeData {
     return `${this.randInt(1, 256)}.${this.randInt(0, 256)}.${this.randInt(0, 256)}.${this.randInt(1, 256)}`;
   }
 
-  color(): string {
-    return this.pick(COLORS);
-  }
-
-  hexColor(): string {
+  colorHex(): string {
     const hex = this.randInt(0, 0x1000000).toString(16).padStart(6, "0");
     return `#${hex}`;
   }
@@ -270,11 +260,31 @@ export class FakeData {
     return this.pick(CURRENCIES);
   }
 
+  /**
+   * Returns multi-paragraph text.
+   * Matches Python's text() method.
+   */
+  text(paragraphs = 3): string {
+    const parts: string[] = [];
+    for (let i = 0; i < paragraphs; i++) {
+      parts.push(this.paragraph(4));
+    }
+    return parts.join("\n\n");
+  }
+
+  /**
+   * Returns a random element from the given array.
+   * Matches Python's choice() method.
+   */
+  choice<T>(items: T[]): T {
+    return items[this.randInt(0, items.length)];
+  }
+
   /**
    * Run seed files from a directory. Each file should export a default async function.
    * Returns an array of executed file paths.
    */
-  async runSeeds(seedDir?: string): Promise<string[]> {
+  async seedDir(seedDir?: string): Promise<string[]> {
     const dir = resolve(seedDir ?? "src/seeds");
     if (!existsSync(dir)) return [];
     const files = readdirSync(dir)

package/packages/core/src/graphql.ts

@@ -69,7 +69,7 @@ const TOKEN_PATTERNS: Array<[string, RegExp]> = [
   ["COMMENT", /#[^\n]*/y],
 ];
 
-function tokenize(source: string): Token[] {
+export function tokenize(source: string): Token[] {
   const tokens: Token[] = [];
   let pos = 0;
 

package/packages/core/src/i18n.ts

@@ -85,7 +85,7 @@ export class I18n {
   }
 
   /** List available locale codes based on JSON files in the locale directory. */
-  getAvailableLocales(): string[] {
+  availableLocales(): string[] {
     if (!existsSync(this._localeDir)) {
       return [this._defaultLocale];
     }

package/packages/core/src/mcp.ts

@@ -990,3 +990,6 @@ export function registerDevTools(server: McpServer): void {
     schemaFromParams([]),
   );
 }
+
+/** Alias for registerDevTools — parity with PHP/Ruby/Python. */
+export const register = registerDevTools;

package/packages/core/src/middleware.ts

@@ -51,6 +51,30 @@ export class MiddlewareChain {
  * the chain short-circuits and runBefore returns shouldContinue = false.
  */
 export class MiddlewareRunner {
+  /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
+  private static globalMiddleware: any[] = [];
+
+  /**
+   * Register a middleware class to run on every request.
+   * Mirrors Tina4\Middleware::use (PHP), Tina4::Middleware.use (Ruby),
+   * and Middleware.use (Python).
+   */
+  static use(cls: any): void {
+    if (!MiddlewareRunner.globalMiddleware.includes(cls)) {
+      MiddlewareRunner.globalMiddleware.push(cls);
+    }
+  }
+
+  /** Return the list of globally registered middleware classes. */
+  static getGlobal(): any[] {
+    return [...MiddlewareRunner.globalMiddleware];
+  }
+
+  /** Clear all globally registered middleware (primarily for tests). */
+  static reset(): void {
+    MiddlewareRunner.globalMiddleware = [];
+  }
+
   /**
    * Execute every beforeX static method found on the supplied classes,
    * in order. Returns the (possibly mutated) request and response pair and a

package/packages/core/src/queue.ts

@@ -51,6 +51,14 @@ export interface ProcessOptions {
   pollInterval?: number;
   maxJobs?: number;
   maxRetries?: number;
+  batchSize?: number;
+}
+
+export interface ConsumeOptions {
+  batchSize?: number;
+  pollInterval?: number;
+  iterations?: number;
+  id?: string;
 }
 
 export interface QueueBackendInterface {
@@ -139,11 +147,18 @@ export class Queue {
     return this.liteBackend.pop(q, this);
   }
 
+  /**
+   * Pop up to count jobs at once. Returns a partial batch if fewer available.
+   */
+  popBatch(count: number): QueueJob[] {
+    return this.liteBackend.popBatch(this.topic, this, count);
+  }
+
   /**
    * Process jobs from a queue with a handler function.
    */
   process(
-    handler: (job: QueueJob) => Promise<void> | void,
+    handler: (job: QueueJob | QueueJob[]) => Promise<void> | void,
     options?: ProcessOptions,
   ): void {
     const queue = this.topic;
@@ -151,23 +166,44 @@ export class Queue {
 
     const maxJobs = opts?.maxJobs ?? Infinity;
     const maxRetries = opts?.maxRetries ?? this._maxRetries;
+    const batchSize = opts?.batchSize;
     let processed = 0;
 
-    while (processed < maxJobs) {
-      const job = this.pop();
-      if (!job) break;
-      try {
-        const result = handler(job);
-        if (result instanceof Promise) {
-          result.catch((err: Error) => {
-            this._failJob(queue, job, err.message, maxRetries);
-          });
+    if (batchSize && batchSize > 1) {
+      while (processed < maxJobs) {
+        const remaining = maxJobs === Infinity ? batchSize : Math.min(batchSize, maxJobs - processed);
+        const jobs = this.popBatch(remaining);
+        if (jobs.length === 0) break;
+        try {
+          const result = handler(jobs);
+          if (result instanceof Promise) {
+            result.catch((err: Error) => {
+              for (const job of jobs) this._failJob(queue, job, err.message, maxRetries);
+            });
+          }
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          for (const job of jobs) this._failJob(queue, job, message, maxRetries);
+        }
+        processed += jobs.length;
+      }
+    } else {
+      while (processed < maxJobs) {
+        const job = this.pop();
+        if (!job) break;
+        try {
+          const result = handler(job);
+          if (result instanceof Promise) {
+            result.catch((err: Error) => {
+              this._failJob(queue, job, err.message, maxRetries);
+            });
+          }
+          processed++;
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          this._failJob(queue, job, message, maxRetries);
+          processed++;
         }
-        processed++;
-      } catch (err: unknown) {
-        const message = err instanceof Error ? err.message : String(err);
-        this._failJob(queue, job, message, maxRetries);
-        processed++;
       }
     }
   }
@@ -211,7 +247,12 @@ export class Queue {
    * @param delaySeconds - Optional delay before jobs become available
    * @returns true if at least one job was re-queued, false if none found
    */
-  retry(delaySeconds?: number): boolean {
+  retry(jobId?: string, delaySeconds?: number): boolean {
+    if (jobId) {
+      // Retry a specific job by ID
+      return this.liteBackend.retry(this.topic, jobId, delaySeconds);
+    }
+    // Retry all dead-letter jobs
     const deadJobs = this.deadLetters();
     if (deadJobs.length === 0) return false;
     let retried = false;
@@ -246,7 +287,7 @@ export class Queue {
   /**
    * Produce a message onto a topic. Convenience wrapper around push().
    */
-  produce(topic: string, payload: unknown, delay?: number, priority: number = 0): string {
+  produce(topic: string, payload: unknown, priority: number = 0, delay: number = 0): string {
     if (this.externalBackend) {
       return this.externalBackend.push(topic, payload, delay);
     }
@@ -279,29 +320,61 @@ export class Queue {
    *   for await (const job of queue.consume("emails")) { ... }
    *   for await (const job of queue.consume("emails", undefined, 5000)) { ... }
    */
-  async *consume(topic?: string, id?: string, pollInterval: number = 1000, iterations: number = 0): AsyncGenerator<QueueJob> {
-    const q = topic ?? this.topic;
+  async *consume(topicOrOptions?: string | ConsumeOptions, id?: string, pollInterval: number = 1000, iterations: number = 0, batchSize: number = 1): AsyncGenerator<QueueJob | QueueJob[]> {
+    // Support options-object form: consume({ batchSize, pollInterval, iterations, id })
+    let q: string;
+    let resolvedId: string | undefined;
+    let resolvedPollInterval: number;
+    let resolvedIterations: number;
+    let resolvedBatchSize: number;
+
+    if (topicOrOptions !== null && typeof topicOrOptions === "object") {
+      const opts = topicOrOptions as ConsumeOptions;
+      q = this.topic;
+      resolvedId = opts.id;
+      resolvedPollInterval = opts.pollInterval ?? 1000;
+      resolvedIterations = opts.iterations ?? 0;
+      resolvedBatchSize = opts.batchSize ?? batchSize;
+    } else {
+      q = (topicOrOptions as string | undefined) ?? this.topic;
+      resolvedId = id;
+      resolvedPollInterval = pollInterval;
+      resolvedIterations = iterations;
+      resolvedBatchSize = batchSize;
+    }
 
-    if (id !== undefined) {
-      const raw = this.popById(id);
+    if (resolvedId !== undefined) {
+      const raw = this.popById(resolvedId);
       if (raw) yield createJob(raw as any, this);
       return;
     }
 
     // pollInterval=0 → single-pass drain (returns when empty)
     // pollInterval>0 → long-running poll (sleeps when empty, never returns)
-    // iterations>0   → stop after consuming N jobs
+    // iterations>0   → stop after consuming N jobs (or N batches when batchSize>1)
     let consumed = 0;
     while (true) {
-      const raw = this.pop(q) as any;
-      if (raw === null) {
-        if (pollInterval <= 0) break;
-        await new Promise(resolve => setTimeout(resolve, pollInterval));
-        continue;
+      if (resolvedBatchSize && resolvedBatchSize > 1) {
+        const jobs = this.popBatch(resolvedBatchSize);
+        if (jobs.length === 0) {
+          if (resolvedPollInterval <= 0) break;
+          await new Promise(resolve => setTimeout(resolve, resolvedPollInterval));
+          continue;
+        }
+        yield jobs;
+        consumed++;
+        if (resolvedIterations > 0 && consumed >= resolvedIterations) break;
+      } else {
+        const raw = this.pop() as any;
+        if (raw === null) {
+          if (resolvedPollInterval <= 0) break;
+          await new Promise(resolve => setTimeout(resolve, resolvedPollInterval));
+          continue;
+        }
+        yield createJob(raw, this);
+        consumed++;
+        if (resolvedIterations > 0 && consumed >= resolvedIterations) break;
       }
-      yield createJob(raw, this);
-      consumed++;
-      if (iterations > 0 && consumed >= iterations) break;
     }
   }
 

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

@@ -90,6 +90,49 @@ export class LiteBackend {
     return null;
   }
 
+  popBatch(queue: string, bridge: JobQueueBridge, count: number): QueueJob[] {
+    const dir = this.ensureDir(queue);
+
+    let files: string[];
+    try {
+      files = readdirSync(dir).filter(f => f.endsWith(".queue-data")).sort();
+    } catch {
+      return [];
+    }
+
+    const now = new Date().toISOString();
+    const results: QueueJob[] = [];
+
+    for (const file of files) {
+      if (results.length >= count) break;
+      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
+      }
+
+      results.push(createJob(job as any, bridge));
+    }
+
+    return results;
+  }
+
   size(queue: string, status: string = "pending"): number {
     if (status === "failed") {
       const failedDir = this.ensureFailedDir(queue);

package/packages/core/src/router.ts

@@ -54,6 +54,12 @@ export class RouteRef {
     this.route.cached = true;
     return this;
   }
+
+  /** Append middleware class(es) to this route. */
+  middleware(...middlewareClasses: Middleware[]): this {
+    this.route.middlewares = [...(this.route.middlewares ?? []), ...middlewareClasses];
+    return this;
+  }
 }
 
 export interface RouteInfo {
@@ -194,7 +200,7 @@ export class Router {
   /**
    * Match a request method + pathname to a registered route.
    */
-  match(method: string, pathname: string): MatchResult | null {
+  match(method: string, path: string): MatchResult | null {
     const upperMethod = method.toUpperCase();
 
     // Try exact method first, then ANY routes are already registered under each method
@@ -202,7 +208,7 @@ export class Router {
     if (!routes) return null;
 
     for (const route of routes) {
-      const match = route.regex.exec(pathname);
+      const match = route.regex.exec(path);
       if (match) {
         const params: Record<string, string> = {};
         for (let i = 0; i < route.paramNames.length; i++) {
@@ -310,46 +316,58 @@ export class Router {
   //   Router.get("/path", handler)
   // as an alternative to importing the top-level get(), post(), etc.
 
+  /**
+   * Register a route for a specific HTTP method.
+   * Core registration method — all convenience methods delegate here.
+   */
+  static add(method: string, path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    const m = method.toUpperCase();
+    if (m === "ANY") {
+      return defaultRouter.any(path, handler, middleware, swaggerMeta);
+    }
+    return defaultRouter.addRoute({ method: m, pattern: path, handler, middlewares: middleware, meta: swaggerMeta, template });
+  }
+
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.get(path, handler, middlewares, meta);
+  static get(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.get(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.post(path, handler, middlewares, meta);
+  static post(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.post(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.put(path, handler, middlewares, meta);
+  static put(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.put(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.patch(path, handler, middlewares, meta);
+  static patch(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.patch(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.delete(path, handler, middlewares, meta);
+  static delete(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.delete(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
-    return defaultRouter.any(path, handler, middlewares, meta);
+  static any(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+    return defaultRouter.any(path, handler, middleware, swaggerMeta);
   }
 
   /**

package/packages/core/src/session.ts

@@ -68,7 +68,7 @@ interface SessionData {
  */
 export interface SessionHandler {
   read(sessionId: string): SessionData | null;
-  write(sessionId: string, data: SessionData, ttl: number): void;
+  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;
@@ -112,7 +112,7 @@ export class FileSessionHandler implements SessionHandler {
     }
   }
 
-  write(sessionId: string, data: SessionData, ttl: number): void {
+  write(sessionId: string, data: SessionData, ttl: number = 0): void {
     this.ensureDir();
     const expires = ttl > 0 ? Math.floor(Date.now() / 1000) + ttl : 0;
     const wrapper = { _data: data, _expires: expires };
@@ -126,7 +126,7 @@ export class FileSessionHandler implements SessionHandler {
     } catch { /* ignore */ }
   }
 
-  gc(_maxLifetime: number): void {
+  gc(maxLifetime: number = 0): void {
     if (!existsSync(this.storagePath)) return;
     const now = Math.floor(Date.now() / 1000);
     try {
@@ -298,7 +298,7 @@ export class RedisSessionHandler implements SessionHandler {
     }
   }
 
-  write(sessionId: string, data: SessionData, ttl: number): void {
+  write(sessionId: string, data: SessionData, ttl: number = 0): void {
     const json = JSON.stringify(data);
     if (ttl > 0) {
       this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);

package/packages/core/src/websocket.ts

@@ -58,7 +58,7 @@ export interface WebSocketClient {
 
 type EventHandler = (...args: unknown[]) => void;
 
-// ── Frame Utilities (exported for testing) ───────────────────
+// ── Frame Utilities (internal) ───────────────────────────────
 
 /**
  * Compute Sec-WebSocket-Accept from Sec-WebSocket-Key per RFC 6455.
@@ -285,6 +285,27 @@ export class WebSocketServer {
     return this.clients;
   }
 
+  /**
+   * Close a specific client connection with an optional code and reason.
+   */
+  close(clientId: string, code: number = 1000, reason: string = ""): void {
+    const client = this.clients.get(clientId);
+    if (!client || client.closed) return;
+    client.closed = true;
+    const reasonBytes = Buffer.from(reason, "utf-8");
+    const payload = Buffer.alloc(2 + reasonBytes.length);
+    payload.writeUInt16BE(code, 0);
+    reasonBytes.copy(payload, 2);
+    try {
+      client.socket.write(buildFrame(OP_CLOSE, payload));
+      client.socket.end();
+    } catch {
+      // already closed
+    }
+    this.clients.delete(clientId);
+    this.removeClientFromAllRooms(clientId);
+  }
+
   // ── Rooms ──────────────────────────────────────────────────
 
   /**

package/packages/frond/src/engine.ts

@@ -1370,6 +1370,12 @@ export class Frond {
     this.compiledStrings.clear();
   }
 
+  /** Render a debug dump of a value as HTML — parity with PHP/Ruby/Python.
+   * Gated on TINA4_DEBUG=true. Returns empty string in production. */
+  renderDump(value: unknown): string {
+    return renderDump(value).toString();
+  }
+
   private load(name: string): string {
     const filePath = join(this.templateDir, name);
     if (!existsSync(filePath)) {

package/packages/orm/src/adapters/firebird.ts

@@ -212,7 +212,7 @@ export class FirebirdAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use updateAsync() for Firebird.");
   }
 
@@ -231,7 +231,7 @@ export class FirebirdAdapter implements DatabaseAdapter {
     }
   }
 
-  delete(table: string, filter: Record<string, unknown>): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use deleteAsync() for Firebird.");
   }
 

package/packages/orm/src/adapters/mssql.ts

@@ -257,7 +257,7 @@ export class MssqlAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use updateAsync() for MSSQL.");
   }
 
@@ -280,7 +280,7 @@ export class MssqlAdapter implements DatabaseAdapter {
     }
   }
 
-  delete(table: string, filter: Record<string, unknown>): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use deleteAsync() for MSSQL.");
   }
 

package/packages/orm/src/adapters/mysql.ts

@@ -183,7 +183,7 @@ export class MysqlAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use updateAsync() for MySQL.");
   }
 
@@ -202,7 +202,7 @@ export class MysqlAdapter implements DatabaseAdapter {
     }
   }
 
-  delete(table: string, filter: Record<string, unknown>): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use deleteAsync() for MySQL.");
   }
 

package/packages/orm/src/adapters/postgres.ts

@@ -167,7 +167,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use updateAsync() for PostgreSQL.");
   }
 
@@ -190,7 +190,7 @@ export class PostgresAdapter implements DatabaseAdapter {
     }
   }
 
-  delete(table: string, filter: Record<string, unknown>): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     throw new Error("Use deleteAsync() for PostgreSQL.");
   }
 

package/packages/orm/src/adapters/sqlite.ts

@@ -100,7 +100,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
     }
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult {
     const setClauses = Object.keys(data).map((k) => `"${k}" = ?`).join(", ");
     const whereClauses = Object.keys(filter).map((k) => `"${k}" = ?`).join(" AND ");
     const sql = `UPDATE "${table}" SET ${setClauses} WHERE ${whereClauses}`;
@@ -114,7 +114,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
     }
   }
 
-  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult {
     if (Array.isArray(filter)) {
       let totalAffected = 0;
       for (const row of filter) {
@@ -127,7 +127,7 @@ export class SQLiteAdapter implements DatabaseAdapter {
     if (typeof filter === "string") {
       const sql = filter ? `DELETE FROM "${table}" WHERE ${filter}` : `DELETE FROM "${table}"`;
       try {
-        const result = this.db.prepare(sql).run();
+        const result = this.db.prepare(sql).run(...(params ?? []));
         return { success: true, rowsAffected: result.changes };
       } catch (e) {
         return { success: false, rowsAffected: 0, error: (e as Error).message };

package/packages/orm/src/baseModel.ts

@@ -285,7 +285,7 @@ export class BaseModel {
    */
   static create<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
-    data: Record<string, unknown>,
+    data: Record<string, unknown> = {},
   ): T {
     const instance = new this(data) as T;
     instance.save();
@@ -403,6 +403,7 @@ export class BaseModel {
     where?: string,
     params?: unknown[],
     include?: string[],
+    orderBy?: string,
   ): T[] {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -419,7 +420,8 @@ export class BaseModel {
     }
 
     const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
-    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}`;
+    const orderClause = orderBy ? ` ORDER BY ${orderBy}` : "";
+    const sql = `SELECT * FROM "${ModelClass.tableName}"${whereClause}${orderClause}`;
 
     const rows = db.query(sql, params);
     const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
@@ -755,28 +757,46 @@ export class BaseModel {
   /**
    * Return true if a record with the given primary key exists.
    */
-  static exists(id: unknown): boolean {
+  static exists(pkValue: unknown): boolean {
     const ModelClass = this as unknown as typeof BaseModel;
-    return ModelClass.findById(id) !== null;
+    return ModelClass.findById(pkValue) !== null;
   }
 
   /**
    * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+   *
+   * @param sql     SQL query string.
+   * @param params  Bind parameters.
+   * @param ttl     Cache TTL in seconds (default 60).
+   * @param limit   Max records to return (default 20).
+   * @param offset  Records to skip (default 0).
+   * @param include Relationship names to eager-load on cache miss.
    */
   static cached<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     sql: string,
     params?: unknown[],
     ttl = 60,
+    limit = 20,
+    offset = 0,
+    include?: string[],
   ): 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 cacheKey = `${ModelClass.tableName}:${sql}:${limit}:${offset}`;
+    const key = QueryCache.queryKey(cacheKey, params ?? []);
     const hit = ModelClass._queryCache.get(key) as T[] | undefined;
     if (hit !== undefined) return hit;
-    const results = ModelClass.select<T>(sql, params);
+
+    const db = ModelClass.getDb();
+    const querySql = `${sql} LIMIT ${limit} OFFSET ${offset}`;
+    const rows = db.query(querySql, params);
+    const results = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    if (include && results.length > 0) {
+      ModelClass._eagerLoad(results as BaseModel[], include);
+    }
     ModelClass._queryCache.set(key, results, ttl);
     return results;
   }
@@ -1260,6 +1280,23 @@ export class BaseModel {
     }
   }
 
+  /**
+   * Public alias for _eagerLoad. Eagerly loads relationships for a list of instances,
+   * preventing N+1 queries.
+   *
+   * Usage:
+   *   const users = User.all();
+   *   await User.eagerLoad(users, ["posts", "profile"]);
+   *
+   * @param instances  Array of model instances to load relationships onto.
+   * @param includeList Array of relationship names (supports dot notation for nesting).
+   */
+  static eagerLoad(instances: BaseModel[], includeList: string[]): Promise<void> {
+    const ModelClass = this as unknown as typeof BaseModel;
+    ModelClass._eagerLoad(instances, includeList);
+    return Promise.resolve();
+  }
+
   /**
    * Clear the relationship cache.
    */

package/packages/orm/src/database.ts

@@ -95,7 +95,12 @@ export function parseDatabaseUrl(url: string, username?: string, password?: stri
   // Handle sqlite:// separately because URL class mangles the path
   if (url.startsWith("sqlite:///")) {
     // sqlite:///absolute/path — three slashes means absolute
-    const path = url.slice("sqlite://".length);
+    let path = url.slice("sqlite://".length);
+    // Windows: sqlite:///C:/Users/app.db → /C:/Users/app.db after slicing.
+    // The leading / before the drive letter must be removed.
+    if (/^\/[A-Za-z]:/.test(path)) {
+      path = path.slice(1);
+    }
     result = { type: "sqlite", path };
   } else if (url.startsWith("sqlite://")) {
     // sqlite://./relative or sqlite://relative
@@ -223,7 +228,7 @@ export class Database {
   private pool: (DatabaseAdapter | null)[] = [];
 
   /** Pool size (0 = single connection) */
-  private poolSize: number = 0;
+  private _poolSize: number = 0;
 
   /** Round-robin index */
   private poolIndex: number = 0;
@@ -270,7 +275,7 @@ export class Database {
       setAdapter(adapters[0]);
 
       const db = new Database(adapters[0]);
-      db.poolSize = pool;
+      db._poolSize = pool;
       db.pool = adapters;
       db.poolIndex = 0;
       db.adapter = null;  // Don't use single-adapter path
@@ -304,9 +309,9 @@ export class Database {
    * Get the next adapter — from pool (round-robin) or single connection.
    */
   private getNextAdapter(): DatabaseAdapter {
-    if (this.poolSize > 0) {
+    if (this._poolSize > 0) {
       const idx = this.poolIndex;
-      this.poolIndex = (this.poolIndex + 1) % this.poolSize;
+      this.poolIndex = (this.poolIndex + 1) % this._poolSize;
       return this.pool[idx] as DatabaseAdapter;
     }
 
@@ -319,16 +324,46 @@ export class Database {
   }
 
   /** Get the pool size (0 = single connection mode). */
-  getPoolSize(): number {
-    return this.poolSize;
+  poolSize(): number {
+    return this._poolSize;
+  }
+
+  /** Alias for poolSize() — returns total pool size (0 = single connection mode). */
+  size(): number {
+    return this._poolSize;
   }
 
   /** Get the number of active (created) connections in the pool. */
-  getActivePoolCount(): number {
-    if (this.poolSize === 0) return this.adapter ? 1 : 0;
+  activeCount(): number {
+    if (this._poolSize === 0) return this.adapter ? 1 : 0;
     return this.pool.filter(a => a !== null).length;
   }
 
+  /**
+   * Borrow a connection from the pool (or the single adapter).
+   * The caller is responsible for returning it via checkin().
+   */
+  checkout(): DatabaseAdapter {
+    return this.getNextAdapter();
+  }
+
+  /**
+   * Return a borrowed connection to the pool.
+   * For round-robin pools this is a no-op (connections stay in the pool array),
+   * but the method exists for API parity and future pooling strategies.
+   */
+  checkin(_adapter: DatabaseAdapter): void {
+    // No-op for round-robin pool — connections are not removed on checkout.
+  }
+
+  /**
+   * Close all pooled connections and clear the pool.
+   * Equivalent to close() but named for explicit pool teardown.
+   */
+  closeAll(): void {
+    this.close();
+  }
+
   /** Query rows with optional pagination. Returns a DatabaseResult wrapper. */
   fetch(sql: string, params?: unknown[], limit?: number, offset?: number): DatabaseResult {
     const adapter = this.getNextAdapter();
@@ -376,9 +411,9 @@ export class Database {
   }
 
   /** Update rows in a table matching filter. */
-  update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>): DatabaseWriteResult {
+  update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>, params?: unknown[]): DatabaseWriteResult {
     const adapter = this.getNextAdapter();
-    const result = adapter.update(table, data, filter ?? {});
+    const result = adapter.update(table, data, filter ?? {}, params);
     if (this.autoCommit) {
       try { adapter.commit(); } catch { /* no active transaction */ }
     }
@@ -386,9 +421,9 @@ export class Database {
   }
 
   /** Delete rows from a table matching filter. */
-  delete(table: string, filter?: Record<string, unknown>): DatabaseWriteResult {
+  delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): DatabaseWriteResult {
     const adapter = this.getNextAdapter();
-    const result = adapter.delete(table, filter ?? {});
+    const result = adapter.delete(table, filter ?? {}, params);
     if (this.autoCommit) {
       try { adapter.commit(); } catch { /* no active transaction */ }
     }
@@ -397,7 +432,7 @@ export class Database {
 
   /** Close all database connections (pool or single). */
   close(): void {
-    if (this.poolSize > 0) {
+    if (this._poolSize > 0) {
       for (let i = 0; i < this.pool.length; i++) {
         if (this.pool[i] !== null) {
           this.pool[i]!.close();
@@ -454,7 +489,7 @@ export class Database {
    * @param paramSets - Array of parameter arrays, one per execution.
    * @returns Array of results from each execution.
    */
-  executeMany(sql: string, paramSets: unknown[][]): unknown[] {
+  executeMany(sql: string, paramSets: unknown[][] = []): unknown[] {
     const adapter = this.getNextAdapter();
     const results: unknown[] = [];
 
@@ -486,6 +521,14 @@ export class Database {
     };
   }
 
+  /** Clear the query result cache. */
+  cacheClear(): void {
+    // Node database layer does not maintain an internal query cache at this
+    // level (caching lives in the SQLTranslation layer). This method exists
+    // for API parity with PHP, Python, and Ruby.
+    // To clear the SQLTranslation query cache use: QueryCache.clear()
+  }
+
   /** Get the last auto-increment id. */
   getLastId(): string | number {
     const id = this.getNextAdapter().lastInsertId();

package/packages/orm/src/fakeData.ts

@@ -14,16 +14,6 @@ export class FakeData extends CoreFakeData {
     super(seed);
   }
 
-  /** Alias for fullName() to match the Python API. */
-  name(): string {
-    return this.fullName();
-  }
-
-  /** Alias for float() to match the Python API. */
-  numeric(min = 0, max = 1000, decimals = 2): number {
-    return this.float(min, max, decimals);
-  }
-
   /**
    * Generate a Date object within a year range.
    * Matches the Python API's datetime() method.
@@ -69,7 +59,7 @@ export class FakeData extends CoreFakeData {
     if (col.includes("company") || col.includes("org")) return this.company();
     if (col.includes("job") || col.includes("title") || col.includes("position")) return this.jobTitle();
     if (col.includes("url") || col.includes("website") || col.includes("link")) return this.url();
-    if (col.includes("color") || col.includes("colour")) return this.hexColor();
+    if (col.includes("color") || col.includes("colour")) return this.colorHex();
     if (col.includes("uuid") || col === "guid") return this.uuid();
     if (col === "ip" || col === "ip_address" || col === "ipaddress") return this.ipAddress();
     if (col.includes("currency")) return this.currency();

package/packages/orm/src/migration.ts

@@ -191,7 +191,7 @@ export function isMigrationApplied(name: string): boolean {
 /**
  * Record a migration as applied.
  */
-export function recordMigration(name: string, batch: number): void {
+export function recordMigration(name: string, batch: number, passed: number = 1): void {
   const adapter = getAdapter();
   if (isFirebirdAdapter(adapter)) {
     // Firebird: generate ID from sequence
@@ -746,6 +746,66 @@ export async function createMigration(
   return { upPath, downPath };
 }
 
+/**
+ * Create a new TypeScript class-based migration file with a timestamp prefix.
+ *
+ * @param description - Human-readable description (used in filename and class name).
+ * @param options - Optional configuration.
+ * @returns Path to the created file.
+ */
+export async function createClassMigration(
+  description: string,
+  options?: { migrationsDir?: string },
+): Promise<string> {
+  const dir = resolve(options?.migrationsDir ?? "migrations");
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const safeName = description
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+
+  // Derive PascalCase class name
+  const className = description
+    .replace(/[^a-zA-Z0-9 ]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join("");
+
+  const now = new Date();
+  const timestamp = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+    String(now.getSeconds()).padStart(2, "0"),
+  ].join("");
+
+  const fileName = `${timestamp}_${safeName}.ts`;
+  const filePath = join(dir, fileName);
+
+  const content =
+    `// Migration: ${description}\n` +
+    `// Created: ${now.toISOString()}\n\n` +
+    `import type { DatabaseAdapter } from "@tina4/orm";\n\n` +
+    `export class ${className} {\n` +
+    `  async up(db: DatabaseAdapter): Promise<void> {\n` +
+    `    // db.execute("CREATE TABLE ...");\n` +
+    `  }\n\n` +
+    `  async down(db: DatabaseAdapter): Promise<void> {\n` +
+    `    // db.execute("DROP TABLE IF EXISTS ...");\n` +
+    `  }\n` +
+    `}\n`;
+
+  writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+
 /**
  * Object-oriented Migration class — canonical Tina4 Migration API.
  *
@@ -800,8 +860,18 @@ export class Migration {
     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 }> {
+  /**
+   * Scaffold a new migration file.
+   *
+   * kind="sql"   — creates {timestamp}_{description}.sql + .down.sql (default)
+   * kind="class" — creates {timestamp}_{description}.ts with a TypeScript class template
+   *
+   * Returns the path to the created up file (or class file).
+   */
+  async create(description: string, kind: "sql" | "class" = "sql"): Promise<string | { upPath: string; downPath: string }> {
+    if (kind === "class") {
+      return createClassMigration(description, { migrationsDir: this.dir });
+    }
     return createMigration(description, { migrationsDir: this.dir });
   }
 

package/packages/orm/src/sqlTranslation.ts

@@ -163,6 +163,7 @@ export class SQLTranslator {
 interface CacheEntry<T> {
   value: T;
   expiresAt: number;
+  tags: string[];
 }
 
 /**
@@ -201,11 +202,12 @@ export class QueryCache {
   }
 
   /**
-   * Set a cached value with optional TTL (seconds).
+   * Set a cached value with optional TTL (seconds) and tags for grouped
+   * invalidation via clearTag().
    */
-  set<T>(key: string, value: T, ttl?: number): void {
+  set<T>(key: string, value: T, ttl?: number, tags: string[] = []): void {
     // Evict oldest entry if at max size
-    if (this.store.size >= this.maxSize) {
+    if (this.store.size >= this.maxSize && !this.store.has(key)) {
       const firstKey = this.store.keys().next().value;
       if (firstKey !== undefined) this.store.delete(firstKey);
     }
@@ -213,9 +215,24 @@ export class QueryCache {
     this.store.set(key, {
       value,
       expiresAt: Date.now() + (ttl ?? this.defaultTtl) * 1000,
+      tags,
     });
   }
 
+  /**
+   * Remove all entries that carry the given tag. Returns the number removed.
+   */
+  clearTag(tag: string): number {
+    let removed = 0;
+    for (const [key, entry] of this.store) {
+      if (entry.tags.includes(tag)) {
+        this.store.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
   /**
    * Check if a key exists and is not expired.
    */

package/packages/orm/src/types.ts

@@ -69,10 +69,10 @@ export interface DatabaseAdapter {
   insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
 
   /** Update rows in a table matching filter, returns affected row count. */
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
 
   /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
-  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult;
+  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
 
   /** Start a transaction. */
   startTransaction(): void;