tina4-nodejs 3.10.90 → 3.10.92

package/packages/core/src/scss.ts

@@ -1,8 +1,8 @@
 // Tina4 SCSS — Zero-dependency SCSS-to-CSS compiler (subset).
 // Supports variables, nesting, & parent selector, @import, @mixin/@include, comments, basic math.
 
-import { readFileSync, existsSync } from "node:fs";
-import { join, resolve, dirname } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve, dirname, basename } from "node:path";
 
 // ── Types ────────────────────────────────────────────────────────
 
@@ -46,6 +46,48 @@ export class ScssCompiler {
     const key = name.startsWith("$") ? name.slice(1) : name;
     this._variables[key] = value;
   }
+
+  /** Compile all .scss files in a directory into a single CSS output file. */
+  compileScss(scssDir: string = "src/scss", output: string = "public/css/default.css", minify: boolean = false): string {
+    const absDir = resolve(scssDir);
+    if (!existsSync(absDir)) return "";
+
+    // Collect non-partial .scss files, sorted
+    const files = readdirSync(absDir)
+      .filter((f) => f.endsWith(".scss") && !f.startsWith("_"))
+      .sort()
+      .map((f) => join(absDir, f));
+
+    if (files.length === 0) return "";
+
+    // Merge all files, resolving imports
+    const paths = [absDir, ...this._importPaths];
+    const imported = new Set<string>();
+    let merged = "";
+    for (const file of files) {
+      const content = readFileSync(file, "utf-8");
+      imported.add(file);
+      merged += resolveImports(content, paths, imported) + "\n";
+    }
+
+    let css = compileString(merged, paths, { ...this._variables });
+
+    if (minify) {
+      css = css.replace(/\/\*.*?\*\//gs, "");
+      css = css.replace(/\s+/g, " ");
+      css = css.replace(/\s*([{}:;,])\s*/g, "$1");
+      css = css.replace(/;}/g, "}");
+      css = css.trim();
+    }
+
+    // Write output
+    const absOutput = resolve(output);
+    const outDir = dirname(absOutput);
+    if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+    writeFileSync(absOutput, css, "utf-8");
+
+    return css;
+  }
 }
 
 // ── Internal Compilation Pipeline ────────────────────────────────

package/packages/core/src/server.ts

@@ -10,7 +10,7 @@ import type { Tina4Config, Tina4Request, Tina4Response } from "./types.js";
 import { Router, defaultRouter, runRouteMiddlewares } from "./router.js";
 import { validToken, getPayload } from "./auth.js";
 import { discoverRoutes } from "./routeDiscovery.js";
-import { createRequest, parseBody } from "./request.js";
+import { createRequest } from "./request.js";
 import { createResponse, setDefaultTemplatesDir } from "./response.js";
 import { MiddlewareChain, cors, requestLogger } from "./middleware.js";
 import { tryServeStatic } from "./static.js";
@@ -439,6 +439,28 @@ function deployGallery(name) {
 // Allows handle() to route requests without requiring a reference to the server.
 let _dispatchFn: ((rawReq: IncomingMessage, rawRes: ServerResponse) => Promise<void>) | null = null;
 
+/** Module-level server handle for start()/stop() parity. */
+let _serverHandle: { close: () => void; router: Router; port: number } | null = null;
+
+/**
+ * Start the Tina4 HTTP server.
+ * Thin wrapper around startServer() for cross-framework parity with PHP and Ruby.
+ */
+export async function start(config?: Tina4Config): Promise<{ close: () => void; router: Router; port: number }> {
+  _serverHandle = await startServer(config);
+  return _serverHandle;
+}
+
+/**
+ * Stop the running Tina4 server gracefully.
+ */
+export function stop(): void {
+  if (_serverHandle) {
+    _serverHandle.close();
+    _serverHandle = null;
+  }
+}
+
 /**
  * Dispatch a raw Node.js request through the Tina4 router and write the response.
  * Requires startServer() to have been called first.
@@ -640,7 +662,7 @@ ${reset}
       // ORM not available, swagger will work without model schemas
     }
 
-    const getSpec = () => swagger.generateOpenAPISpec(allRoutes, modelDefs as any);
+    const getSpec = () => swagger.generate(allRoutes, modelDefs as any);
     const swaggerRoutes = swagger.createSwaggerRoutes(getSpec);
     for (const route of swaggerRoutes) {
       router.addRoute(route);
@@ -696,7 +718,7 @@ ${reset}
       if (res.raw.writableEnded) return;
 
       // Parse request body
-      await parseBody(req);
+      await req.parseBody();
 
       const pathname = (req.url ?? "/").split("?")[0];
 
@@ -828,7 +850,7 @@ ${reset}
           typeof result === "object" &&
           !Buffer.isBuffer(result)
         ) {
-          await res.template(match.template, result as Record<string, unknown>);
+          await res.render(match.template, result as Record<string, unknown>);
         }
 
         if (!res.raw.writableEnded) {

package/packages/core/src/service.ts

@@ -322,6 +322,13 @@ export class ServiceRunner {
     registry.clear();
   }
 
+  /**
+   * Check if a 5-field cron pattern matches the given (or current) date/time.
+   */
+  static matchCron(pattern: string, now?: Date): boolean {
+    return matchesCron(pattern, now ?? new Date());
+  }
+
   /**
    * Watch service files for changes and hot-reload in dev mode.
    */

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/testClient.ts

@@ -16,7 +16,7 @@
  */
 import { IncomingMessage, ServerResponse } from "node:http";
 import { Socket } from "node:net";
-import { createRequest, parseBody } from "./request.js";
+import { createRequest } from "./request.js";
 import { createResponse } from "./response.js";
 import { defaultRouter, type Router } from "./router.js";
 
@@ -153,7 +153,7 @@ export class TestClient {
     const res = createResponse(rawRes);
 
     // Parse body (populates req.body)
-    await parseBody(req);
+    await req.parseBody();
 
     // Split path for route matching
     const cleanPath = path.includes("?") ? path.split("?")[0] : path;

package/packages/core/src/testing.ts

@@ -3,17 +3,17 @@
  *
  * Attach test assertions to functions and run them all at once.
  *
- *     import { tests, assertEqual, assertThrows, runAllTests } from "./testing.js";
+ *     import { tests, assertEqual, assertRaises, runAll } from "./testing.js";
  *
  *     const add = tests(
  *       assertEqual([5, 3], 8),
- *       assertThrows(Error, [null]),
+ *       assertRaises(Error, [null]),
  *     )(function add(a: number, b: number | null = null): number {
  *       if (b === null) throw new Error("b required");
  *       return a + b;
  *     });
  *
- *     runAllTests();
+ *     runAll();
  */
 
 // ── Types ──────────────────────────────────────────────────────────
@@ -50,7 +50,7 @@ export function assertEqual(args: unknown[], expected: unknown): Assertion {
 }
 
 /** Assert that calling the function with `args` throws an instance of `errorClass`. */
-export function assertThrows(
+export function assertRaises(
   errorClass: new (...a: unknown[]) => Error,
   args: unknown[],
 ): Assertion {
@@ -93,7 +93,7 @@ export function tests(
 // ── Runner ─────────────────────────────────────────────────────────
 
 /** Run all registered tests. Returns results summary. */
-export function runAllTests(
+export function runAll(
   options: { quiet?: boolean; failfast?: boolean } = {},
 ): TestResults {
   const { quiet = false, failfast = false } = options;
@@ -141,7 +141,7 @@ export function runAllTests(
 }
 
 /** Reset the test registry (useful between test runs). */
-export function resetTests(): void {
+export function reset(): void {
   registry.length = 0;
 }
 

package/packages/core/src/types.ts

@@ -27,6 +27,14 @@ export interface Tina4Request extends IncomingMessage {
   contentType: string;
   session: Tina4Session;
   user?: Record<string, unknown>;
+  /** Get a specific header value by name (case-insensitive). */
+  header(name: string): string | undefined;
+  /** Extract the Bearer token from the Authorization header. */
+  bearerToken(): string | null;
+  /** Get a parameter by key from merged params (route + query). */
+  param(key: string, defaultValue?: string): string | undefined;
+  /** Parse the request body based on content type. */
+  parseBody(): Promise<void>;
 }
 
 export interface CookieOptions {
@@ -53,7 +61,6 @@ export interface Tina4ResponseMethods {
   file(path: string, options?: { download?: boolean; contentType?: string }): Tina4Response;
   error(code: string, message: string, status?: number): Tina4Response;
   render(template: string, data?: Record<string, unknown>, status?: number, templateDir?: string): Promise<Tina4Response>;
-  template(name: string, data?: Record<string, unknown>, status?: number, templateDir?: string): Promise<Tina4Response>;
   /** Stream response from an async generator (SSE or chunked). */
   stream(source: AsyncIterable<string | Buffer>, contentType?: string): Promise<Tina4Response>;
   /** The underlying ServerResponse for advanced use */

package/packages/core/src/watcher.ts

@@ -7,6 +7,72 @@ import { resolve, extname } from "node:path";
  */
 const CODE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 
+// Module-level state for start()/stop() API
+let _watchers: ReturnType<typeof watch>[] = [];
+let _debounceTimer: ReturnType<typeof setTimeout> | null = null;
+let _codeChangePending = false;
+let _running = false;
+
+/**
+ * Start the DevReload file watcher.
+ *
+ * Watches the given directories for file changes and calls onChange when
+ * a change is detected. Mirrors the Python DevReload.start() API.
+ *
+ * @param dirs - Directories to watch. Defaults to ["src", "public"].
+ * @param onChange - Callback invoked on file change. Receives `{ code: boolean }`.
+ */
+export function start(
+  dirs: string[] = ["src", "public"],
+  onChange: (info: { code: boolean }) => void = () => {},
+): void {
+  if (_running) return;
+  _running = true;
+
+  const debouncedOnChange = () => {
+    if (_debounceTimer) clearTimeout(_debounceTimer);
+    _debounceTimer = setTimeout(() => {
+      const code = _codeChangePending;
+      _codeChangePending = false;
+      console.log(
+        `\n  \x1b[33mFile change detected${code ? ", reloading routes" : ""}...\x1b[0m\n`,
+      );
+      onChange({ code });
+    }, 200);
+  };
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    try {
+      const watcher = watch(resolve(dir), { recursive: true }, (_event, filename) => {
+        if (filename && CODE_EXTENSIONS.has(extname(filename))) {
+          _codeChangePending = true;
+        }
+        debouncedOnChange();
+      });
+      _watchers.push(watcher);
+    } catch {
+      console.warn(`  Warning: Could not watch ${dir}`);
+    }
+  }
+}
+
+/**
+ * Stop the DevReload file watcher.
+ *
+ * Closes all active file watchers and resets internal state.
+ * Mirrors the Python DevReload.stop() API.
+ */
+export function stop(): void {
+  if (!_running) return;
+  _running = false;
+  for (const w of _watchers) w.close();
+  _watchers = [];
+  if (_debounceTimer) clearTimeout(_debounceTimer);
+  _debounceTimer = null;
+  _codeChangePending = false;
+}
+
 /**
  * Watch directories for file changes.
  *

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.
@@ -214,9 +214,9 @@ export class WebSocketServer {
   }
 
   /**
-   * Send a message to a specific client.
+   * Send a message to a specific client by ID.
    */
-  send(clientId: string, message: string): void {
+  sendTo(clientId: string, message: string): void {
     const client = this.clients.get(clientId);
     if (!client || client.closed) return;
 
@@ -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/core/src/websocketConnection.ts

@@ -17,6 +17,10 @@ export interface WebSocketConnection {
   send(message: string): void;
   /** Broadcast a message to all connections on the same path (path-scoped) */
   broadcast(message: string): void;
+  /** Join a room */
+  joinRoom(roomName: string): void;
+  /** Leave a room */
+  leaveRoom(roomName: string): void;
   /** Close this connection */
   close(): void;
 }

package/packages/core/src/wsdl.ts

@@ -6,13 +6,13 @@
  *
  * Matches the PHP reference implementation (Tina4\WSDL).
  *
- *   import { WSDLService, WSDLOp } from "@tina4/core";
+ *   import { WSDLService, WSDLOperation } from "@tina4/core";
  *
  *   class Calculator extends WSDLService {
  *     serviceName = "Calculator";
  *     serviceUrl = "/api/calculator";
  *
- *     @WSDLOp({ output: { Result: "int" } })
+ *     @WSDLOperation({ output: { Result: "int" } })
  *     async Add(a: number, b: number): Promise<Record<string, unknown>> {
  *       return { Result: a + b };
  *     }
@@ -21,14 +21,14 @@
 
 // ── Types ────────────────────────────────────────────────────
 
-export interface WSDLOperation {
+export interface WSDLOperationMeta {
   name: string;
   description?: string;
   input?: Record<string, string>;   // param name -> type
   output?: Record<string, string>;  // return name -> type
 }
 
-interface WSDLOpConfig {
+interface WSDLOperationConfig {
   description?: string;
   input?: Record<string, string>;
   output?: Record<string, string>;
@@ -167,13 +167,13 @@ const WSDL_OPS_KEY = Symbol("wsdl_operations");
 /**
  * Decorator function for marking methods as WSDL operations.
  *
- *   @WSDLOp({ description: "Add two numbers", input: { a: "int", b: "int" }, output: { Result: "int" } })
+ *   @WSDLOperation({ description: "Add two numbers", input: { a: "int", b: "int" }, output: { Result: "int" } })
  *   async Add(a: number, b: number): Promise<Record<string, unknown>> { ... }
  */
-export function WSDLOp(config?: WSDLOpConfig) {
+export function WSDLOperation(config?: WSDLOperationConfig) {
   return function (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
     // Store metadata on the method itself
-    const op: WSDLOperation = {
+    const op: WSDLOperationMeta = {
       name: propertyKey,
       description: config?.description,
       input: config?.input,
@@ -214,12 +214,12 @@ export abstract class WSDLService {
   }
 
   /** Discovered operations (populated on first use). */
-  private _operations: Map<string, WSDLOperation> | null = null;
+  private _operations: Map<string, WSDLOperationMeta> | null = null;
 
   /**
    * Discover operations by scanning for methods with _wsdlOp metadata.
    */
-  private discoverOperations(): Map<string, WSDLOperation> {
+  private discoverOperations(): Map<string, WSDLOperationMeta> {
     if (this._operations) return this._operations;
 
     this._operations = new Map();
@@ -233,7 +233,7 @@ export abstract class WSDLService {
         try {
           const method = (this as Record<string, unknown>)[name];
           if (typeof method === "function" && (method as unknown as Record<string, unknown>)._wsdlOp) {
-            const op = (method as unknown as Record<string, unknown>)._wsdlOp as WSDLOperation;
+            const op = (method as unknown as Record<string, unknown>)._wsdlOp as WSDLOperationMeta;
             if (!this._operations.has(name)) {
               this._operations.set(name, op);
             }
@@ -386,7 +386,7 @@ export abstract class WSDLService {
   /**
    * Handle incoming SOAP request (parse XML, dispatch to method, return SOAP response).
    */
-  async handleRequest(soapXml: string): Promise<string> {
+  async handle(soapXml: string = ""): Promise<string> {
     const ops = this.discoverOperations();
 
     // Parse SOAP body
@@ -538,7 +538,7 @@ export abstract class WSDLService {
       return;
     }
 
-    const soapResponse = await this.handleRequest(xmlBody);
+    const soapResponse = await this.handle(xmlBody);
 
     if (typeof res.send === "function") {
       if (typeof res.setHeader === "function") {

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 };