tina4-nodejs 3.12.2 → 3.12.4

package/packages/core/src/session.ts

@@ -531,10 +531,15 @@ export class Session {
 
   /**
    * Return a Set-Cookie header value for this session.
+   *
+   * Honours these env vars (cross-framework parity):
+   *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+   *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+   *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+   *   TINA4_SESSION_SECURE    — emit Secure (default: false)
    */
-  cookieHeader(cookieName: string = "tina4_session"): string {
-    const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
-    return `${cookieName}=${this.sessionId}; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=${this.ttl}`;
+  cookieHeader(cookieName?: string): string {
+    return buildSessionCookie(this.sessionId, this.ttl, cookieName);
   }
 
   /**
@@ -555,3 +560,38 @@ export class Session {
     this.handler.write(this.sessionId, this.data, this.ttl);
   }
 }
+
+/**
+ * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
+ * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on
+ * which env vars are honoured and what the defaults are.
+ *
+ * Env vars (Python parity):
+ *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+ *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+ *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+ *   TINA4_SESSION_SECURE    — emit Secure (default: false)
+ */
+export function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string): string {
+  const name = cookieName ?? process.env.TINA4_SESSION_NAME ?? "tina4_session";
+  const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
+
+  // HttpOnly defaults to TRUE (matches existing behaviour and Python parity).
+  // Treat any explicit non-truthy value (false/0/no/off) as opt-out.
+  const httpOnlyRaw = process.env.TINA4_SESSION_HTTPONLY;
+  const httpOnly = httpOnlyRaw === undefined
+    ? true
+    : !["false", "0", "no", "off"].includes(httpOnlyRaw.trim().toLowerCase());
+
+  // Secure defaults to FALSE — only emit when the operator opts in (https
+  // deployments). Setting it eagerly would break http://localhost dev cookies.
+  const secureRaw = process.env.TINA4_SESSION_SECURE ?? "";
+  const secure = ["true", "1", "yes", "on"].includes(secureRaw.trim().toLowerCase());
+
+  const parts = [`${name}=${sessionId ?? ""}`, "Path=/"];
+  if (httpOnly) parts.push("HttpOnly");
+  parts.push(`SameSite=${sameSite}`);
+  if (secure) parts.push("Secure");
+  parts.push(`Max-Age=${ttl}`);
+  return parts.join("; ");
+}

package/packages/frond/src/engine.ts

@@ -1327,10 +1327,16 @@ export class Frond {
   private _allowedVars: Set<string> | null;
   private fragmentCache: Map<string, [string, number]>;
   private _autoEscape: boolean;
-  /** Token pre-compilation cache for file templates */
-  private compiled = new Map<string, { tokens: Token[]; mtime: number }>();
+  /**
+   * Token pre-compilation cache for file templates.
+   *
+   * `cachedAt` is captured so the TINA4_TEMPLATE_CACHE_TTL env var can
+   * force re-compilation after N seconds even in production. TTL of 0
+   * means "no time-based invalidation" — entries live forever.
+   */
+  private compiled = new Map<string, { tokens: Token[]; mtime: number; cachedAt: number }>();
   /** Token pre-compilation cache for string templates */
-  private compiledStrings = new Map<string, Token[]>();
+  private compiledStrings = new Map<string, { tokens: Token[]; cachedAt: number }>();
 
   getTemplateDir(): string { return this.templateDir; }
 
@@ -1386,6 +1392,20 @@ export class Frond {
     this.tests[name] = fn;
   }
 
+  /**
+   * Read the cache TTL in seconds. `TINA4_TEMPLATE_CACHE_TTL=0` (the
+   * default) keeps the existing "cache forever in prod" behaviour — any
+   * positive value invalidates compiled tokens after N seconds, useful
+   * when running long-lived servers behind a slow file sync where mtime
+   * isn't a reliable freshness signal.
+   */
+  private cacheTtlSeconds(): number {
+    const raw = process.env.TINA4_TEMPLATE_CACHE_TTL;
+    if (raw === undefined) return 0;
+    const n = parseInt(raw, 10);
+    return isNaN(n) || n < 0 ? 0 : n;
+  }
+
   render(template: string, data?: Record<string, unknown>): string {
     const context = { ...this.globals, ...(data || {}) };
     const filePath = join(this.templateDir, template);
@@ -1395,12 +1415,17 @@ export class Frond {
     }
 
     const debugMode = (process.env.TINA4_DEBUG || "").toLowerCase() === "true";
+    const ttlMs = this.cacheTtlSeconds() * 1000;
 
     if (!debugMode) {
       // Production: use permanent cache (no filesystem checks)
       const cached = this.compiled.get(template);
       if (cached) {
-        return this.executeCached(cached.tokens, context);
+        // TTL=0 means cache forever; any positive value invalidates the
+        // compiled tokens after N seconds.
+        if (ttlMs === 0 || (Date.now() - cached.cachedAt) < ttlMs) {
+          return this.executeCached(cached.tokens, context);
+        }
       }
     }
     // Dev mode: skip cache entirely — always re-read and re-tokenize
@@ -1410,7 +1435,7 @@ export class Frond {
     const source = readFileSync(filePath, "utf-8");
     const mtime = statSync(filePath).mtimeMs;
     const tokens = tokenize(source);
-    this.compiled.set(template, { tokens, mtime });
+    this.compiled.set(template, { tokens, mtime, cachedAt: Date.now() });
     return this.executeWithSource(source, tokens, context);
   }
 
@@ -1418,13 +1443,16 @@ export class Frond {
     const context = { ...this.globals, ...(data || {}) };
 
     const key = createHash("md5").update(source).digest("hex");
-    const cachedTokens = this.compiledStrings.get(key);
-    if (cachedTokens) {
-      return this.executeCached(cachedTokens, context);
+    const ttlMs = this.cacheTtlSeconds() * 1000;
+    const cached = this.compiledStrings.get(key);
+    if (cached) {
+      if (ttlMs === 0 || (Date.now() - cached.cachedAt) < ttlMs) {
+        return this.executeCached(cached.tokens, context);
+      }
     }
 
     const tokens = tokenize(source);
-    this.compiledStrings.set(key, tokens);
+    this.compiledStrings.set(key, { tokens, cachedAt: Date.now() });
     return this.executeCached(tokens, context);
   }
 

package/packages/orm/src/database.ts

@@ -830,6 +830,21 @@ async function createAdapterFromUrl(url: string, username?: string, password?: s
  *   2. process.env.TINA4_DATABASE_URL
  *   3. config.type + config.path (legacy)
  */
+/**
+ * Resolve the connection-pool size from `TINA4_DB_POOL`.
+ *
+ * Default: 0 (single-connection mode). Any positive integer enables
+ * round-robin pooling with that many connections — Database.create() honours
+ * this transparently. The env var is the simple deploy-time override; tests
+ * and library users can still pass `pool` directly to Database.create().
+ */
+export function resolveDbPool(): number {
+  const raw = process.env.TINA4_DB_POOL;
+  if (raw === undefined || raw.trim() === "") return 0;
+  const n = parseInt(raw, 10);
+  return isNaN(n) || n < 0 ? 0 : n;
+}
+
 export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   // Resolve credentials: config.user > config.username > env TINA4_DATABASE_USERNAME
   const resolvedUser = config?.user ?? config?.username ?? process.env.TINA4_DATABASE_USERNAME;
@@ -839,6 +854,12 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   const url = config?.url ?? process.env.TINA4_DATABASE_URL;
 
   if (url) {
+    const pool = resolveDbPool();
+    if (pool > 0) {
+      // Pool-aware path — delegate to Database.create which manages
+      // round-robin adapter rotation and async-local-storage transaction pinning.
+      return Database.create(url, resolvedUser, resolvedPassword, pool);
+    }
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
     setAdapter(adapter);
     return new Database(adapter);

package/packages/orm/src/index.ts

@@ -14,7 +14,7 @@ export { FetchResult } from "./types.js";
 
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
-export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter } from "./database.js";
+export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool } from "./database.js";
 export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";

package/packages/swagger/src/generator.ts

@@ -1,9 +1,17 @@
 import type { RouteDefinition } from "@tina4/core";
 import type { ModelDefinition, FieldDefinition } from "@tina4/orm";
 
+interface OpenAPISpecInfo {
+  title: string;
+  version: string;
+  description?: string;
+  contact?: { name?: string; url?: string; email?: string };
+  license?: { name: string; url?: string };
+}
+
 interface OpenAPISpec {
   openapi: string;
-  info: { title: string; version: string; description?: string };
+  info: OpenAPISpecInfo;
   paths: Record<string, Record<string, unknown>>;
   components?: { schemas?: Record<string, unknown> };
 }
@@ -12,13 +20,30 @@ export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
 ): OpenAPISpec {
+  const info: OpenAPISpecInfo = {
+    title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
+    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
+  };
+
+  // Optional contact email — surfaced in the OpenAPI `info.contact.email`
+  // field when set. Matches the python `SWAGGER_CONTACT_EMAIL` convention.
+  const contactEmail = (process.env.TINA4_SWAGGER_CONTACT_EMAIL ?? "").trim();
+  if (contactEmail.length > 0) {
+    info.contact = { email: contactEmail };
+  }
+
+  // Optional license — accepts a plain SPDX identifier ("MIT", "Apache-2.0")
+  // or a "Name|URL" pair. Empty string disables license output entirely.
+  const licenseRaw = (process.env.TINA4_SWAGGER_LICENSE ?? "").trim();
+  if (licenseRaw.length > 0) {
+    const [name, url] = licenseRaw.split("|").map((s) => s.trim());
+    info.license = url ? { name, url } : { name };
+  }
+
   const spec: OpenAPISpec = {
     openapi: "3.0.3",
-    info: {
-      title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-      version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-      description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
-    },
+    info,
     paths: {},
     components: { schemas: {} },
   };

package/packages/swagger/src/index.ts

@@ -1,2 +1,2 @@
 export { generate } from "./generator.js";
-export { createSwaggerRoutes } from "./ui.js";
+export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/packages/swagger/src/ui.ts

@@ -26,6 +26,23 @@ const SWAGGER_UI_HTML = (specUrl: string) => `<!DOCTYPE html>
 </body>
 </html>`;
 
+/**
+ * Whether the Swagger UI + spec routes should be registered at boot.
+ *
+ * Default: enabled when `TINA4_DEBUG=true`, disabled otherwise. Operators
+ * can force either state with `TINA4_SWAGGER_ENABLED=true|false`. Matches
+ * Python parity: dev-only by default to keep production attack surface
+ * minimal, but easy to expose intentionally for public APIs.
+ */
+export function swaggerEnabled(): boolean {
+  const raw = (process.env.TINA4_SWAGGER_ENABLED ?? "").trim().toLowerCase();
+  if (raw === "") {
+    const debug = (process.env.TINA4_DEBUG ?? "").trim().toLowerCase();
+    return ["true", "1", "yes", "on"].includes(debug);
+  }
+  return ["true", "1", "yes", "on"].includes(raw);
+}
+
 export function createSwaggerRoutes(
   getSpec: () => Record<string, unknown>
 ): RouteDefinition[] {