tina4-nodejs 3.13.81 → 3.13.82

package/packages/core/src/mqttMessage.ts

@@ -0,0 +1,104 @@
+/**
+ * One MQTT 3.1.1 application message as delivered by the broker.
+ *
+ * Shaped like the Queue's job (its unit of work): it carries the payload plus
+ * the delivery metadata a consumer needs, and it knows how to acknowledge itself
+ * back to the client it came from. Mirrors tina4_python.mqtt.MqttMessage,
+ * Tina4::MqttMessage (Ruby), and Tina4\MqttMessage (PHP).
+ *
+ * The two flags matter for correctness, not decoration:
+ *
+ *   retained  — the broker replayed the topic's last known value to us because
+ *               we subscribed AFTER it was published. It is current state, not a
+ *               fresh event.
+ *   duplicate — the DUP flag. The broker is REDELIVERING a QoS 1 message it never
+ *               saw acknowledged. QoS 1 is at-least-once, so a duplicate is
+ *               guaranteed eventually; a consumer that treats a DUP delivery as a
+ *               new sample double-counts energy or mileage. Key the ingest on
+ *               (deviceId, deviceTimestamp) and it is harmless.
+ *
+ * The payload is a Buffer of the raw bytes; text() decodes it for JSON/string
+ * payloads.
+ */
+
+/** The slice of an Mqtt client an MqttMessage needs to acknowledge itself. */
+export interface MqttAcknowledger {
+  acknowledge(packetId: number): Promise<boolean>;
+}
+
+export class MqttMessage {
+  private acknowledgedFlag = false;
+
+  constructor(
+    public readonly topic: string,
+    public readonly payload: Buffer,
+    public readonly qos: number = 0,
+    public readonly retained: boolean = false,
+    public readonly duplicate: boolean = false,
+    public readonly packetId: number | null = null,
+    private readonly client: MqttAcknowledger | null = null,
+  ) {}
+
+  /** True when the broker replayed this as the topic's retained (last known) value. */
+  isRetained(): boolean {
+    return this.retained;
+  }
+
+  /**
+   * True when the broker set the DUP flag — a REDELIVERY of a QoS 1 message we
+   * never acknowledged, not a new sample.
+   */
+  isDuplicate(): boolean {
+    return this.duplicate;
+  }
+
+  /**
+   * PUBACK a QoS 1 delivery so the broker stops redelivering it.
+   *
+   * A QoS 0 message needs no acknowledgement, and a second call is a no-op, so
+   * this is always safe to call once processing succeeded. Returns true only
+   * when a PUBACK was actually sent.
+   */
+  async acknowledge(): Promise<boolean> {
+    if (this.acknowledgedFlag || this.qos === 0 || this.packetId === null || this.client === null) {
+      return false;
+    }
+    await this.client.acknowledge(this.packetId);
+    this.acknowledgedFlag = true;
+    return true;
+  }
+
+  /** True once this message has been acknowledged back to the broker. */
+  isAcknowledged(): boolean {
+    return this.acknowledgedFlag;
+  }
+
+  /** The payload decoded as text (for JSON / string payloads). */
+  text(encoding: BufferEncoding = "utf-8"): string {
+    return this.payload.toString(encoding);
+  }
+
+  /** The message as a plain object. */
+  toObject(): {
+    topic: string;
+    payload: Buffer;
+    qos: number;
+    retained: boolean;
+    duplicate: boolean;
+    packetId: number | null;
+  } {
+    return {
+      topic: this.topic,
+      payload: this.payload,
+      qos: this.qos,
+      retained: this.retained,
+      duplicate: this.duplicate,
+      packetId: this.packetId,
+    };
+  }
+
+  /** String form is the payload text (parity with Python __str__ / Ruby to_s). */
+  toString(): string {
+    return this.text();
+  }
+}

package/packages/core/src/scss.ts

@@ -168,9 +168,56 @@ function resolveImports(content: string, paths: string[], imported: Set<string>)
 
 // ── Variables ────────────────────────────────────────────────────
 
+/**
+ * Flags that may trail a variable declaration's value. `!default` means "assign
+ * only if this variable is not already set" — the flag that makes a variable
+ * themeable. `!global` is the scope flag. Both are compiler directives: they are
+ * consumed at the declaration and must never reach the CSS, because
+ * `padding: 1.5rem !default` is invalid CSS and browsers drop the whole
+ * declaration. Sass flag names are case-SENSITIVE (`!DEFAULT` is an error in
+ * Dart Sass), so the match is deliberately case-sensitive.
+ */
+const VARIABLE_FLAG = /\s*!(default|global)\s*$/;
+
+/**
+ * Split trailing `!default` / `!global` flags off a variable declaration value.
+ * Returns `[valueWithoutFlags, declaresDefault]`.
+ *
+ * Only ever called on the value of a `$name: value;` declaration, so a literal
+ * `!default` anywhere else — inside a quoted string (`content: "x !default y"`)
+ * or a function argument — is left untouched, exactly as Dart Sass leaves it. A
+ * blanket strip would corrupt real string content, and would silently turn
+ * `rgba(#000 !default, 0.1)` (a syntax error in Dart Sass) into valid-looking
+ * CSS that Sass would never emit.
+ */
+function stripVariableFlags(value: string): [string, boolean] {
+  let declaresDefault = false;
+  for (;;) {
+    const match = VARIABLE_FLAG.exec(value);
+    if (match === null) return [value.trim(), declaresDefault];
+    if (match[1] === "default") declaresDefault = true;
+    value = value.slice(0, match.index);
+  }
+}
+
+/**
+ * Extract `$variable: value;` declarations, honouring the `!default` flag.
+ *
+ * `$x: value !default;` assigns only when `$x` is not already set. That is what
+ * makes a variable themeable — a user who writes `$primary: red;` BEFORE
+ * importing a partial that declares `$primary: blue !default;` keeps red.
+ * Declarations are visited in source order, so "already set" means "set by an
+ * earlier declaration or by a preset variable". A value of `null` counts as
+ * unset, as in Sass.
+ */
 function extractVariables(scss: string, variables: Record<string, string>): string {
   return scss.replace(/\$([a-zA-Z_][\w-]*)\s*:\s*([^;]+);/g, (_m, name: string, value: string) => {
-    let resolved = value.trim();
+    const [stripped, declaresDefault] = stripVariableFlags(value.trim());
+    // !default must not overwrite a value that is already set.
+    if (declaresDefault && (variables[name] ?? "null") !== "null") {
+      return "";
+    }
+    let resolved = stripped;
     // Resolve variable references within the value
     for (const [vName, vVal] of Object.entries(variables)) {
       resolved = resolved.replaceAll(`$${vName}`, vVal);

package/packages/core/src/testClient.ts

@@ -18,7 +18,8 @@ import { IncomingMessage, ServerResponse } from "node:http";
 import { Socket } from "node:net";
 import { createRequest } from "./request.js";
 import { createResponse } from "./response.js";
-import { defaultRouter, type Router } from "./router.js";
+import { defaultRouter, Router, runRouteMiddlewares } from "./router.js";
+import { MiddlewareRunner } from "./middleware.js";
 import { enforceRouteAuth } from "./authGate.js";
 
 export class TestResponse {
@@ -160,14 +161,73 @@ export class TestClient {
     const cleanPath = path.includes("?") ? path.split("?")[0] : path;
 
     // Match route
-    const match = this.router.match(method.toUpperCase(), cleanPath);
+    const httpMethod = method.toUpperCase();
+    const match = this.router.match(httpMethod, cleanPath);
     if (!match) {
-      return new TestResponse(404, { "content-type": "application/json" }, '{"error":"Not found"}');
+      // D6: dispatch through the REAL front-controller behaviour on a miss —
+      // never fabricate a body. This mirrors the live server tail
+      // (server.ts dispatch): RFC 9110 conformance first (a path registered
+      // under another method answers OPTIONS with 204 + Allow and any other
+      // method with 405 + Allow), then the framework's real 404. The old
+      // TestClient short-circuited to a hand-invented {"error":"Not found"}
+      // that the live server never sends, so a green test proved nothing about
+      // production (the same silent-success class as Python's pre-fix client).
+      const allowed = this.router.methodsAllowedForPath(cleanPath);
+      if (allowed.length > 0) {
+        const allowHeader = allowed.join(", ");
+        if (httpMethod === "OPTIONS") {
+          return new TestResponse(204, { allow: allowHeader, "content-length": "0" }, "");
+        }
+        const body405 = JSON.stringify({
+          error: "Method Not Allowed",
+          path: cleanPath,
+          method: httpMethod,
+          allow: allowed,
+          statusCode: 405,
+        });
+        return new TestResponse(405, { allow: allowHeader, "content-type": "application/json" }, body405);
+      }
+      // The framework's real 404. The live server renders an HTML error page
+      // when a project templatesDir/frondEngine exists and otherwise emits this
+      // exact JSON; a server-less TestClient has no project dir, so it produces
+      // the JSON fallback the live front controller itself falls back to.
+      // tina4: HTML-error-page + filesystem static serving are the only live
+      // front-controller steps a server-less client can't reproduce.
+      const body404 = JSON.stringify({
+        error: "Not Found",
+        statusCode: 404,
+        message: `No route found for ${httpMethod} ${cleanPath}`,
+      });
+      return new TestResponse(404, { "content-type": "application/json" }, body404);
     }
 
     // Inject route params
     req.params = match.params;
 
+    // Global class-based middleware (Router.use / MiddlewareRunner.use), run in
+    // the SAME order the live dispatcher uses (server.ts): beforeX hooks before
+    // the handler, afterX hooks after — even on a before-short-circuit. Empty
+    // when a test registers none, so this is additive/non-breaking.
+    const globalMiddleware = [
+      ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
+    ];
+    if (globalMiddleware.length > 0) {
+      const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
+      if (!proceed || res.raw.writableEnded) {
+        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+        if (!res.raw.writableEnded) res.raw.end();
+        return this._collect(rawRes, chunks, socket);
+      }
+    }
+
+    // Per-route middleware, same as the live dispatcher.
+    if (match.middlewares && match.middlewares.length > 0) {
+      const proceed = await runRouteMiddlewares(match.middlewares, req, res);
+      if (!proceed || res.raw.writableEnded) {
+        return this._collect(rawRes, chunks, socket);
+      }
+    }
+
     // Route through the REAL auth gate (parity with the live server). A write to
     // an auth-required route (secure-by-default POST/PUT/PATCH/DELETE, or any
     // .secure() route) with no valid token / formToken / session token 401s here
@@ -183,9 +243,17 @@ export class TestClient {
     // Execute handler (only if auth passed)
     if (!rejected) {
       await match.handler(req, res);
+      // Global afterX hooks (logging / post-processing), mirroring the live tail.
+      if (globalMiddleware.length > 0) {
+        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+      }
     }
 
-    // Collect response
+    return this._collect(rawRes, chunks, socket);
+  }
+
+  /** Gather the captured status/headers/body into a TestResponse and free the socket. */
+  private _collect(rawRes: ServerResponse, chunks: Buffer[], socket: Socket): TestResponse {
     const responseBody = Buffer.concat(chunks).toString();
     const responseHeaders: Record<string, string> = {};
     for (const [name, value] of Object.entries(rawRes.getHeaders())) {
@@ -193,10 +261,7 @@ export class TestClient {
         responseHeaders[name] = Array.isArray(value) ? value.join(", ") : String(value);
       }
     }
-
-    // Clean up the socket
     socket.destroy();
-
     return new TestResponse(rawRes.statusCode, responseHeaders, responseBody);
   }
 }

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

@@ -5,7 +5,7 @@
  * URL format: firebird://user:pass@host:port/path/to/database.fdb
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let firebird: any = null;

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

@@ -5,7 +5,7 @@
  * URL format: mssql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let tedious: any = null;

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

@@ -5,7 +5,7 @@
  * URL format: mysql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 import { createRequire } from "node:module";
 
 let mysql2: any = null;

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

@@ -5,7 +5,7 @@
  * URL format: postgresql://user:pass@host:port/database
  */
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 
 import { createRequire } from "node:module";
 

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

@@ -2,7 +2,7 @@ import { DatabaseSync } from "node:sqlite";
 import { mkdirSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
-import { SQLTranslator } from "../sqlTranslation.js";
+import { SQLTranslator } from "../sqlTranslator.js";
 
 /** A safe-to-interpolate SQL identifier (no quoting/escaping needed). */
 function isIdentifier(str: string): boolean {

package/packages/orm/src/baseModel.ts

@@ -7,7 +7,7 @@ import {
 import { validate as validateFields } from "./validation.js";
 import { QueryBuilder } from "./queryBuilder.js";
 import { SQLiteAdapter } from "./adapters/sqlite.js";
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 import { Log } from "../../core/src/index.js";
 import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
 

package/packages/orm/src/cachedDatabase.ts

@@ -32,7 +32,7 @@
  *   db.cacheStats();                   // { enabled, mode, hits, misses, size, ttl }
  */
 
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
 import type { CacheBackend } from "../../core/src/index.js";
 

package/packages/orm/src/database.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, FieldDefinition } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
 import { CachedDatabaseAdapter, type CachedAdapterOptions } from "./cachedDatabase.js";
-import { QueryCache } from "./sqlTranslation.js";
+import { QueryCache } from "./sqlTranslator.js";
 
 /**
  * v3.13.12 — strip trailing `;` and whitespace from user-supplied SQL

package/packages/orm/src/index.ts

@@ -53,7 +53,7 @@ export { validate } from "./validation.js";
 export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
-export { SQLTranslator, QueryCache } from "./sqlTranslation.js";
+export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";