tina4-nodejs 3.13.29 → 3.13.31

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.29)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.31)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -193,7 +193,7 @@ Max upload size: `TINA4_MAX_UPLOAD_SIZE` env var (default 10MB).
 getToken(payload, secret?, expiresIn=60): string
 validToken(token, secret?): Record | null
 getPayload(token): Record | null
-refreshToken(token, secret?, expiresIn=60): string | null
+refreshToken(token, expiresIn=60): string | null  // reads SECRET from env
 hashPassword(password, salt?, iterations=260000): string  // PBKDF2-SHA256, $ delimiter
 checkPassword(password, hash): boolean  // timing-safe
 validateApiKey(provided, expected?): boolean  // reads TINA4_API_KEY from env

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.29",
+  "version": "3.13.31",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/auth.ts

@@ -36,17 +36,17 @@ function base64urlDecode(str: string): Buffer {
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  *
  * @param payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
- * @param secretOrExpiresIn - Signing secret string, OR expiresIn number (back-compat with old 2-arg form)
- * @param expiresIn         - Lifetime in seconds (default 3600). Only used when secret is a string.
+ * @param secretOrExpiresIn - Signing secret string, OR expiresIn number in MINUTES (back-compat with old 2-arg form)
+ * @param expiresIn         - Lifetime in MINUTES (default 60). `0` ⇒ no `exp` claim (non-expiring). Only used when secret is a string.
  * @returns Signed JWT string: header.payload.signature
  */
 export function getToken(
   payload: Record<string, unknown>,
   secretOrExpiresIn?: string | number,
-  expiresIn: number = 3600,
+  expiresIn: number = 60,
   algorithm?: string,
 ): string {
-  // Back-compat: if second arg is a number, treat it as expiresIn (old 2-arg form)
+  // Back-compat: if second arg is a number, treat it as expiresIn in minutes (old 2-arg form)
   let resolvedSecret: string;
   let resolvedExpiresIn: number;
   if (typeof secretOrExpiresIn === "number") {
@@ -66,8 +66,9 @@ export function getToken(
   const now = Math.floor(Date.now() / 1000);
 
   const claims: Record<string, unknown> = { ...payload, iat: now };
+  // expiresIn is in MINUTES (parity with Python/PHP/Ruby); 0 ⇒ non-expiring.
   if (resolvedExpiresIn !== 0) {
-    claims.exp = now + resolvedExpiresIn;
+    claims.exp = now + resolvedExpiresIn * 60;
   }
 
   const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
@@ -173,7 +174,7 @@ function verifySignature(input: string, sig: string, secret: string, algorithm:
  *
  * @param password   - Plaintext password
  * @param salt       - Hex-encoded salt (auto-generated if omitted)
- * @param iterations - PBKDF2 iterations (default 100000)
+ * @param iterations - PBKDF2 iterations (default 260000)
  * @returns Format: `pbkdf2_sha256$iterations$salt$hash` (all hex-encoded)
  */
 export function hashPassword(
@@ -250,12 +251,12 @@ export function authMiddleware(secret?: string, algorithm: string = "HS256"): Mi
  * Secret is always read from `process.env.TINA4_SECRET`.
  *
  * @param token     - Existing JWT to refresh
- * @param expiresIn - New lifetime in seconds (default 3600)
+ * @param expiresIn - New lifetime in MINUTES (default 60)
  * @returns New signed JWT string, or null if the input token is invalid/expired
  */
 export function refreshToken(
   token: string,
-  expiresIn: number = 3600,
+  expiresIn: number = 60,
 ): string | null {
   if (!validToken(token)) return null;
 

package/packages/core/src/request.ts

@@ -101,7 +101,7 @@ export function createRequest(req: IncomingMessage): Tina4Request {
     return null;
   };
 
-  tReq.param = function (key: string, defaultValue?: string): string | undefined {
+  tReq.param = function (key: string, defaultValue?: string | number): string | number | undefined {
     return tReq.params[key] ?? tReq.query[key] ?? defaultValue;
   };
 

package/packages/core/src/router.ts

@@ -12,9 +12,35 @@ export function isTrailingSlashRedirectEnabled(): boolean {
   return isTruthy(process.env.TINA4_TRAILING_SLASH_REDIRECT);
 }
 
+/**
+ * Coerce a matched path param to its declared type. Mirrors Python/PHP/Ruby:
+ * `{id:int}`/`{id:integer}` arrive as a JS integer `number`, `{p:float}`/
+ * `{p:number}` as a float `number`, and every other type (string/alpha/alnum/
+ * slug/uuid/path) plus untyped `{id}` stay the decoded string. The URL regex
+ * already constrains what reaches here (`int` only matches `\d+`), so a cast
+ * should never fail — but we never throw: a NaN result falls back to the raw
+ * string so a malformed value can't take the router down.
+ */
+function coerceParam(raw: string, type: string | undefined): string | number {
+  switch (type) {
+    case "int":
+    case "integer": {
+      const n = parseInt(raw, 10);
+      return Number.isNaN(n) ? raw : n;
+    }
+    case "float":
+    case "number": {
+      const n = parseFloat(raw);
+      return Number.isNaN(n) ? raw : n;
+    }
+    default:
+      return raw;
+  }
+}
+
 interface MatchResult {
   handler: RouteHandler;
-  params: Record<string, string>;
+  params: Record<string, string | number>;
   pattern: string;
   meta?: RouteMeta;
   middlewares?: Middleware[];
@@ -28,6 +54,7 @@ interface CompiledRoute {
   pattern: string;
   regex: RegExp;
   paramNames: string[];
+  paramTypes: string[];
   handler: RouteHandler;
   meta?: RouteMeta;
   filePath?: string;
@@ -117,7 +144,7 @@ export class Router {
    */
   addRoute(definition: RouteDefinition): RouteRef {
     const method = definition.method.toUpperCase();
-    const { regex, paramNames } = this.compilePattern(definition.pattern);
+    const { regex, paramNames, paramTypes } = this.compilePattern(definition.pattern);
 
     if (!this.routes.has(method)) {
       this.routes.set(method, []);
@@ -143,6 +170,7 @@ export class Router {
       pattern: definition.pattern,
       regex,
       paramNames,
+      paramTypes,
       handler: definition.handler,
       meta: definition.meta,
       filePath: definition.filePath,
@@ -309,9 +337,10 @@ export class Router {
     for (const route of routes) {
       const match = route.regex.exec(path);
       if (match) {
-        const params: Record<string, string> = {};
+        const params: Record<string, string | number> = {};
         for (let i = 0; i < route.paramNames.length; i++) {
-          params[route.paramNames[i]] = decodeURIComponent(match[i + 1]);
+          const raw = decodeURIComponent(match[i + 1]);
+          params[route.paramNames[i]] = coerceParam(raw, route.paramTypes[i]);
         }
         return {
           handler: route.handler,
@@ -505,8 +534,13 @@ export class Router {
     ".*": ".+",
   };
 
-  private compilePattern(pattern: string): { regex: RegExp; paramNames: string[] } {
+  private compilePattern(pattern: string): { regex: RegExp; paramNames: string[]; paramTypes: string[] } {
     const paramNames: string[] = [];
+    // Declared type per capture group, parallel to paramNames. Drives value
+    // coercion at match time (int/integer/float/number → JS number). Every
+    // capture below pushes a type so the two arrays stay index-aligned; only
+    // {name:type} carries a non-"string" type — all other forms are "string".
+    const paramTypes: string[] = [];
 
     // Supports {id} (primary, matches Python), [id] (file-based dirs), and :id (Express-style)
     const regexStr = pattern
@@ -519,6 +553,7 @@ export class Router {
         ) {
           const name = segment.startsWith("{") ? segment.slice(4, -1) : segment.slice(4, -1);
           paramNames.push(name);
+          paramTypes.push("string");
           return "(.+)";
         }
         // Dynamic param: {id}, {id:int}, {id:float}, {id:path} (matching Python/Ruby)
@@ -528,6 +563,7 @@ export class Router {
           const name = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
           const type = colonIdx >= 0 ? inner.slice(colonIdx + 1) : "string";
           paramNames.push(name);
+          paramTypes.push(type);
           const table = Router.PARAM_TYPE_PATTERNS;
           if (!Object.prototype.hasOwnProperty.call(table, type)) {
             const valid = Object.keys(table).filter((k) => k !== ".*").sort().join(", ");
@@ -541,17 +577,20 @@ export class Router {
         if (segment.startsWith("[") && segment.endsWith("]")) {
           const name = segment.slice(1, -1);
           paramNames.push(name);
+          paramTypes.push("string");
           return "([^/]+)";
         }
         // Express-style param: :id
         if (segment.startsWith(":")) {
           const name = segment.slice(1);
           paramNames.push(name);
+          paramTypes.push("string");
           return "([^/]+)";
         }
         // Wildcard: * (catch-all, param key is "*")
         if (segment === "*") {
           paramNames.push("*");
+          paramTypes.push("string");
           return "(.+)";
         }
         return segment;
@@ -561,6 +600,7 @@ export class Router {
     return {
       regex: new RegExp(`^${regexStr}$`),
       paramNames,
+      paramTypes,
     };
   }
 }

package/packages/core/src/types.ts

@@ -18,7 +18,12 @@ export interface Tina4Session {
 }
 
 export interface Tina4Request extends IncomingMessage {
-  params: Record<string, string>;
+  /**
+   * Path params. Typed params arrive coerced: `{id:int}`/`{id:integer}` and
+   * `{p:float}`/`{p:number}` are JS `number`s; every other type and untyped
+   * `{id}` stay `string` (parity with Python/PHP/Ruby).
+   */
+  params: Record<string, string | number>;
   query: Record<string, string>;
   /**
    * Request path only — no query string. Matches `request.path` in
@@ -49,8 +54,11 @@ export interface Tina4Request extends IncomingMessage {
   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;
+  /**
+   * Get a parameter by key from merged params (route + query). Route params
+   * may be coerced numbers (e.g. `{id:int}`); query params are always strings.
+   */
+  param(key: string, defaultValue?: string | number): string | number | undefined;
   /** Parse the request body based on content type. */
   parseBody(): Promise<void>;
 }