tina4-nodejs 3.10.91 → 3.10.93

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

@@ -8,9 +8,9 @@ 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, getPayload } from "./auth.js";
+import { validToken, getPayload, refreshToken } 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";
@@ -19,6 +19,7 @@ import { createHealthRoute } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector } from "./devAdmin.js";
+import { I18n } from "./i18n.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -439,6 +440,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.
@@ -546,6 +569,22 @@ ${reset}
     // Frond not available
   }
 
+  // Auto-wire i18n → template global t() when locale files exist
+  if (frondEngine) {
+    const localeDir = resolve(base, process.env.TINA4_LOCALE_DIR ?? "src/locales");
+    if (existsSync(localeDir)) {
+      try {
+        const localeFiles = readdirSync(localeDir).filter((f: string) => f.endsWith(".json"));
+        if (localeFiles.length > 0 && !frondEngine.globals?.t) {
+          const i18nInstance = new I18n(localeDir, process.env.TINA4_LOCALE ?? "en");
+          frondEngine.addGlobal("t", (key: string, params?: Record<string, string>) => i18nInstance.t(key, params));
+        }
+      } catch {
+        // Locale directory unreadable — skip auto-wire
+      }
+    }
+  }
+
   // Built-in middleware
   middleware.use(cors());
   middleware.use(requestLogger());
@@ -640,7 +679,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 +735,7 @@ ${reset}
       if (res.raw.writableEnded) return;
 
       // Parse request body
-      await parseBody(req);
+      await req.parseBody();
 
       const pathname = (req.url ?? "/").split("?")[0];
 
@@ -785,18 +824,56 @@ ${reset}
           if (!proceed || res.raw.writableEnded) return;
         }
 
-        // Auth enforcement: secure routes require a valid Bearer token
+        // Auth enforcement: secure routes require a valid token
+        // Check sources in priority order: Authorization header > body formToken > session token
         // Dev admin routes (/__dev) are always public
         const isDevAdmin = pathname.startsWith("/__dev");
         if (match.secure === true && match.noAuth !== true && !isDevAdmin) {
           const authHeader = req.headers.authorization ?? "";
-          const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
-          if (!token || !validToken(token)) {
+          const headerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+
+          // Priority 1: Authorization Bearer header
+          let resolvedToken = "";
+          let tokenSource: "header" | "body" | "session" | "" = "";
+
+          if (headerToken && validToken(headerToken)) {
+            resolvedToken = headerToken;
+            tokenSource = "header";
+          }
+
+          // Priority 2: formToken from request body
+          if (!resolvedToken) {
+            const bodyToken = (req.body as Record<string, unknown>)?.formToken as string | undefined;
+            if (bodyToken && validToken(bodyToken)) {
+              resolvedToken = bodyToken;
+              tokenSource = "body";
+            }
+          }
+
+          // Priority 3: Session token
+          if (!resolvedToken) {
+            const sessionToken = (req as any).session?.get?.("token") as string | undefined;
+            if (sessionToken && validToken(sessionToken)) {
+              resolvedToken = sessionToken;
+              tokenSource = "session";
+            }
+          }
+
+          if (!resolvedToken) {
             res.raw.writeHead(401, { "Content-Type": "application/json" });
             res.raw.end(JSON.stringify({ error: "Unauthorized" }));
             return;
           }
-          req.user = getPayload(token) ?? {};
+
+          req.user = getPayload(resolvedToken) ?? {};
+
+          // When body formToken validates, return a FreshToken header with a refreshed JWT
+          if (tokenSource === "body") {
+            const fresh = refreshToken(resolvedToken);
+            if (fresh) {
+              res.header("FreshToken", fresh);
+            }
+          }
         }
 
         // Inject path params by name into handler arguments, then request/response
@@ -828,7 +905,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/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

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

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") {