tina4-nodejs 3.13.73 → 3.13.75

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.73)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.75)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.73 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.75 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.73",
+  "version": "3.13.75",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/src/devAdmin.ts

@@ -1753,30 +1753,33 @@ const handleConnectionsTest: RouteHandler = async (req, res) => {
     let version = "Connected";
     let tableCount = 0;
     try {
-      const tables = db.getTables();
+      // getTables() is async (Promise<string[]>) and MUST be awaited — the
+      // un-awaited call made tableCount always 0 (Array.isArray(Promise) is
+      // false). Python (db.get_tables()) and Ruby (db.tables) were correct.
+      const tables = await db.getTables();
       tableCount = Array.isArray(tables) ? tables.length : 0;
     } catch { tableCount = 0; }
     try {
       const urlLower = url.toLowerCase();
-      // NOTE: db.execute() is async; these calls are intentionally left
-      // un-awaited to preserve the exact existing runtime behaviour during
-      // this type-only cleanup. `row` is therefore a Promise and the `as any`
-      // access below evaluates to the fallback string. See report open question.
+      // fetchOne() is async and returns a single row object ({ v: ... }); it
+      // must be awaited. Previously db.execute() was left un-awaited, so `row`
+      // was a Promise and the version always fell back to the default string.
+      // Mirrors Python/Ruby which read row["v"] from a fetch_one().
       if (urlLower.includes("sqlite")) {
-        const row = db.execute("SELECT sqlite_version() as v");
-        version = `SQLite ${(row as any)?.[0]?.v ?? ""}`;
+        const row = await db.fetchOne<{ v?: string }>("SELECT sqlite_version() as v");
+        version = `SQLite ${row?.v ?? ""}`;
       } else if (urlLower.includes("postgres")) {
-        const row = db.execute("SELECT version() as v");
-        version = ((row as any)?.[0]?.v ?? "PostgreSQL").toString().split(",")[0];
+        const row = await db.fetchOne<{ v?: string }>("SELECT version() as v");
+        version = (row?.v ?? "PostgreSQL").toString().split(",")[0];
       } else if (urlLower.includes("mysql")) {
-        const row = db.execute("SELECT version() as v");
-        version = `MySQL ${(row as any)?.[0]?.v ?? ""}`;
+        const row = await db.fetchOne<{ v?: string }>("SELECT version() as v");
+        version = `MySQL ${row?.v ?? ""}`;
       } else if (urlLower.includes("mssql")) {
-        const row = db.execute("SELECT @@VERSION as v");
-        version = ((row as any)?.[0]?.v ?? "MSSQL").toString().split("\n")[0];
+        const row = await db.fetchOne<{ v?: string }>("SELECT @@VERSION as v");
+        version = (row?.v ?? "MSSQL").toString().split("\n")[0];
       } else if (urlLower.includes("firebird")) {
-        const row = db.execute("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') as v FROM rdb$database");
-        version = `Firebird ${(row as any)?.[0]?.v ?? ""}`;
+        const row = await db.fetchOne<{ v?: string }>("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') as v FROM rdb$database");
+        version = `Firebird ${row?.v ?? ""}`;
       }
     } catch { /* keep version as Connected */ }
     db.close();

package/packages/core/src/static.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync, type Stats } from "node:fs";
 import { join, extname } from "node:path";
 import type { Tina4Request, Tina4Response } from "./types.js";
 
@@ -55,6 +55,29 @@ export function tryServeStatic(
     const ext = extname(filePath);
     const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
 
+    // Cheap validators from the file's size + mtime — no hashing needed. A weak
+    // ETag (W/) is correct here: two representations with the same size+mtime
+    // are treated as equivalent for caching. Last-Modified is second-resolution
+    // per HTTP.
+    const etag = `W/"${stat.size}-${stat.mtimeMs}"`;
+    const lastModified = stat.mtime.toUTCString();
+
+    // A static asset MAY be cached but MUST be revalidated before use, so a
+    // redeployed file reaches the browser on the next load without a manual hard
+    // refresh; an unchanged asset costs a cheap 304, not a re-download. These
+    // ride on both the 200 and the 304 so the client always has fresh
+    // validators. Parity with the Python master static handler.
+    res.raw.setHeader("Cache-Control", "no-cache, must-revalidate");
+    res.raw.setHeader("ETag", etag);
+    res.raw.setHeader("Last-Modified", lastModified);
+
+    // Conditional request → 304 Not Modified with no body.
+    if (isNotModified(req, etag, stat)) {
+      res.raw.statusCode = 304;
+      res.raw.end();
+      return true;
+    }
+
     res.raw.setHeader("Content-Type", contentType);
     res.raw.setHeader("Content-Length", stat.size);
     res.raw.end(readFileSync(filePath));
@@ -63,3 +86,53 @@ export function tryServeStatic(
 
   return false;
 }
+
+/**
+ * Read a conditional-request header off the incoming request. Works with the
+ * real `IncomingMessage` (`req.headers`, already lower-cased by Node) AND with
+ * the hand-rolled request objects used in unit tests. Header names must be
+ * lower-case. Returns "" when absent.
+ */
+function conditionalHeader(req: Tina4Request, name: string): string {
+  const headers = (req as { headers?: Record<string, string | string[] | undefined> }).headers;
+  const value = headers?.[name];
+  if (Array.isArray(value)) return value[0] ?? "";
+  return value ?? "";
+}
+
+/**
+ * Answer whether the cached representation the client already holds is still
+ * current. `If-None-Match` wins over `If-Modified-Since` (RFC 7232 §3.3): when
+ * the client sends an entity tag we compare against that alone.
+ */
+function isNotModified(req: Tina4Request, etag: string, stat: Stats): boolean {
+  const ifNoneMatch = conditionalHeader(req, "if-none-match");
+  if (ifNoneMatch) {
+    return etagMatches(ifNoneMatch, etag);
+  }
+  const ifModifiedSince = conditionalHeader(req, "if-modified-since");
+  if (ifModifiedSince) {
+    const since = Date.parse(ifModifiedSince);
+    if (!Number.isNaN(since)) {
+      // Last-Modified is second-resolution; floor the mtime so sub-second
+      // precision never reports a spurious "modified".
+      const modified = Math.floor(stat.mtimeMs / 1000) * 1000;
+      return modified <= since;
+    }
+  }
+  return false;
+}
+
+/**
+ * Weak comparison of an `If-None-Match` value against our ETag. The header may
+ * be `*`, a single tag, or a comma-separated list; the `W/` weak prefix is
+ * stripped on both sides before comparing (RFC 7232 §2.3.2 weak comparison).
+ */
+function etagMatches(ifNoneMatch: string, etag: string): boolean {
+  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
+  const target = strip(etag);
+  return ifNoneMatch.split(",").some((candidate) => {
+    const trimmed = candidate.trim();
+    return trimmed === "*" || strip(trimmed) === target;
+  });
+}