tina4-nodejs 3.10.67 → 3.10.70

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.42)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.10.70)
 
 > 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.10.42 — 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.10.70 — 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.
 
@@ -153,8 +153,8 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `fakeData.ts` — ORM-aware fake data extending core (adds `forField()` with column-name heuristics)
 - `seeder.ts` — Database seeding (`seedTable` for raw SQL, `seedOrm` for model-based)
 - `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
-- **Instance methods:** `save()`, `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean` (selectOne into self), `validate(): string[]`, `toDict(include?): Record`, `toObject(): Record`, `toArray(): unknown[]`, `toList(): unknown[]`, `toJson(): string`, `hasOne()`, `hasMany()`, `belongsTo()`
-- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findAll(where?, params?, include?)`, `findOrFail(id)`, `create(data)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?)`, `scope(name, filterSql, params?)`, `createTable()`, `query(): QueryBuilder`
+- **Instance methods:** `save(): this|null` (fluent, null on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
+- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).
 
@@ -162,10 +162,10 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 
 ### File Uploads
 
-Multipart file uploads are available via `req.files` (array of UploadedFile objects):
+Multipart file uploads via `req.files` (dict keyed by field name):
 
 ```typescript
-// req.files[0] =>
+// req.files["avatar"] =>
 {
   fieldName: "avatar",
   filename: "photo.png",
@@ -177,15 +177,80 @@ Multipart file uploads are available via `req.files` (array of UploadedFile obje
 
 ```typescript
 post("/api/upload", (req, res) => {
-  const file = req.files?.find(f => f.fieldName === "avatar");
+  const file = req.files["avatar"];
   if (!file) return res.json({ error: "No file" }, 400);
-  fs.writeFileSync(`src/public/uploads/${file.filename}`, file.content);
+  fs.writeFileSync(`src/public/uploads/${(file as any).filename}`, (file as any).content);
   return res.json({ ok: true });
 });
 ```
 
 Max upload size: `TINA4_MAX_UPLOAD_SIZE` env var (default 10MB).
 
+### Auth
+
+```typescript
+// expires_in is in MINUTES (default 60). Reads SECRET from env if not passed.
+getToken(payload, secret?, expiresIn=60): string
+validToken(token, secret?): Record | null
+getPayload(token): Record | null
+refreshToken(token, secret?, expiresIn=60): string | null
+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
+authenticateRequest(headers, secret?): Record | null  // Bearer JWT, falls back to API key
+// Also available as Auth.getToken(), Auth.validToken(), etc.
+```
+
+### Session
+
+```typescript
+session.start(sessionId?): string
+session.get(key, defaultValue?): unknown
+session.set(key, value): void
+session.delete(key): void
+session.has(key): boolean
+session.all(): Record
+session.clear(): void
+session.destroy(): void
+session.regenerate(): string
+session.flash(key, value?): unknown     // Dual-mode: set with value, get+remove without
+session.getFlash(key, defaultValue?): unknown
+session.save(): void                    // Public — persist to backend
+session.cookieHeader(name?): string     // Set-Cookie header value
+session.getSessionId(): string | null
+session.gc(): void
+```
+
+Backends: file, redis, redis-npm, valkey, mongodb, database.
+
+### Database extras
+
+```typescript
+db.execute(sql, params?): boolean | unknown  // bool for writes, result for RETURNING/CALL/EXEC
+db.getLastId(): string | number
+db.getError(): string | null
+db.cacheStats(): { enabled, size, ttl }
+```
+
+### Request extras
+
+```typescript
+req.files: Record<string, UploadedFile>  // dict keyed by field name (not array)
+req.cookies: Record<string, string>       // parsed from Cookie header
+req.contentType: string                   // from content-type header
+req.query: Record<string, string>         // query string params
+response.xml(content, status?): Tina4Response
+response.stream(generator, contentType?: string, status?: number): void  // SSE/streaming
+```
+
+### Queue
+
+```typescript
+queue.consume(topic?, id?, pollInterval=1000): AsyncGenerator<QueueJob>
+// Long-running async generator. Sleeps when empty. pollInterval=0 for single-pass.
+// Usage: for await (const job of queue.consume("emails")) { ... }
+```
+
 ### @tina4/swagger (`packages/swagger/`)
 Auto-generates OpenAPI 3.0 docs.
 
@@ -613,7 +678,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 
 ## v3 Features Summary
 
-- **44 built-in features**, zero third-party dependencies
+- **45 built-in features**, zero third-party dependencies
 - **1,812 tests** passing across all modules
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
@@ -631,6 +696,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
 - **`tina4 init`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/_dev/`
+- **SSE/Streaming**: `response.stream()` for Server-Sent Events — pass an async generator, framework handles chunked transfer encoding and keep-alive
 
 ## Don'ts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.67",
+  "version": "3.10.70",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/core/src/auth.ts

@@ -40,16 +40,23 @@ function base64urlDecode(str: string): Buffer {
  */
 export function getToken(
   payload: Record<string, unknown>,
-  secret: string,
-  expiresIn: number = 3600,
+  secret?: string,
+  expiresIn: number = 60,
   algorithm: string = "HS256",
 ): string {
+  if (!secret) {
+    secret = process.env.SECRET ?? "";
+    if (!secret) {
+      console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
+    }
+  }
+
   const header = { alg: algorithm, typ: "JWT" };
   const now = Math.floor(Date.now() / 1000);
 
   const claims: Record<string, unknown> = { ...payload, iat: now };
   if (expiresIn !== 0) {
-    claims.exp = now + expiresIn;
+    claims.exp = now + Math.floor(expiresIn * 60);
   }
 
   const h = base64urlEncode(Buffer.from(JSON.stringify(header)));
@@ -65,9 +72,15 @@ export function getToken(
  */
 export function validToken(
   token: string,
-  secret: string,
+  secret?: string,
   algorithm: string = "HS256",
 ): Record<string, unknown> | null {
+  if (!secret) {
+    secret = process.env.SECRET ?? "";
+    if (!secret) {
+      console.warn("Auth: SECRET not set in .env — using blank secret (insecure)");
+    }
+  }
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
@@ -145,24 +158,27 @@ 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)
- * @returns Format: `pbkdf2_sha256:iterations:salt:hash` (all hex-encoded)
+ * @returns Format: `pbkdf2_sha256$iterations$salt$hash` (all hex-encoded)
  */
 export function hashPassword(
   password: string,
   salt?: string,
-  iterations: number = 100000,
+  iterations: number = 260000,
 ): string {
   const actualSalt = salt ?? randomBytes(16).toString("hex");
   const dk = pbkdf2Sync(password, actualSalt, iterations, 32, "sha256");
-  return `pbkdf2_sha256:${iterations}:${actualSalt}:${dk.toString("hex")}`;
+  return `pbkdf2_sha256$${iterations}$${actualSalt}$${dk.toString("hex")}`;
 }
 
 /**
  * Check a password against a PBKDF2 hash string.
+ * Supports both $ and : delimiters for backward compatibility.
  */
 export function checkPassword(password: string, hash: string): boolean {
   try {
-    const parts = hash.split(":");
+    // Support both $ (standard) and : (legacy) delimiters
+    const delimiter = hash.includes("$") ? "$" : ":";
+    const parts = hash.split(delimiter);
     if (parts.length !== 4 || parts[0] !== "pbkdf2_sha256") return false;
 
     const iterations = parseInt(parts[1], 10);
@@ -225,8 +241,8 @@ export function authMiddleware(secret: string, algorithm: string = "HS256"): Mid
  */
 export function refreshToken(
   token: string,
-  secret: string,
-  expiresIn: number = 3600,
+  secret?: string,
+  expiresIn: number = 60,
   algorithm: string = "HS256",
 ): string | null {
   const payload = validToken(token, secret, algorithm);
@@ -249,7 +265,7 @@ export function refreshToken(
  */
 export function authenticateRequest(
   headers: Record<string, string | string[] | undefined>,
-  secret: string,
+  secret?: string,
   algorithm: string = "HS256",
 ): Record<string, unknown> | null {
   const authHeader =
@@ -258,7 +274,17 @@ export function authenticateRequest(
   if (!authHeader.startsWith("Bearer ")) return null;
 
   const token = authHeader.slice(7);
-  return validToken(token, secret, algorithm);
+
+  // Try JWT first
+  const payload = validToken(token, secret, algorithm);
+  if (payload !== null) return payload;
+
+  // Fallback: treat Bearer value as API key
+  if (validateApiKey(token)) {
+    return { _auth: "api_key" };
+  }
+
+  return null;
 }
 
 // ── Backward-Compatible Aliases ──────────────────────────────────

package/packages/core/src/events.ts

@@ -87,6 +87,28 @@ export class Events {
         return results;
     }
 
+    /**
+     * Emit an event and await all async listeners.
+     * Returns array of resolved results from each listener.
+     */
+    static async emitAsync(event: string, ...args: unknown[]): Promise<unknown[]> {
+        const entries = _listeners.get(event);
+        if (!entries) return [];
+
+        const snapshot = [...entries];
+        const results: unknown[] = [];
+
+        for (const entry of snapshot) {
+            if (entry.once) {
+                const idx = entries.indexOf(entry);
+                if (idx !== -1) entries.splice(idx, 1);
+            }
+            results.push(await entry.callback(...args));
+        }
+
+        return results;
+    }
+
     /**
      * Get all listener callbacks for an event (in priority order).
      */

package/packages/core/src/graphql.ts

@@ -383,6 +383,21 @@ export class GraphQL {
 
   constructor() {}
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Register a named type with its fields.
    */
@@ -391,6 +406,21 @@ export class GraphQL {
     return this;
   }
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Register a query resolver.
    */
@@ -404,6 +434,21 @@ export class GraphQL {
     return this;
   }
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Register a mutation resolver.
    */
@@ -417,6 +462,21 @@ export class GraphQL {
     return this;
   }
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Execute a GraphQL query string.
    */
@@ -464,10 +524,57 @@ export class GraphQL {
     return result;
   }
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
+
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Generate SDL schema string.
    */
-  schema(): string {
+
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
+  schemaSdl(): string {
     const lines: string[] = [];
 
     // Types
@@ -505,6 +612,21 @@ export class GraphQL {
     return lines.join("\n");
   }
 
+  /**
+   * Return schema metadata for debugging.
+   */
+  introspect(): Record<string, unknown> {
+    const queries: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.queries)) {
+      queries[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    const mutations: Record<string, unknown> = {};
+    for (const [name, config] of Object.entries(this.mutations)) {
+      mutations[name] = { type: (config as any).type, args: (config as any).args ?? {} };
+    }
+    return { types: Object.keys(this.types), queries, mutations };
+  }
+
   /**
    * Auto-generate type, queries, and CRUD mutations from an ORM model class.
    *

package/packages/core/src/i18n.ts

@@ -92,8 +92,8 @@ export class I18n {
     try {
       const files = readdirSync(this._localeDir);
       const locales = files
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => f.replace(/\.json$/, ""))
+        .filter((f) => f.endsWith(".json") || f.endsWith(".yml") || f.endsWith(".yaml"))
+        .map((f) => f.replace(/\.(json|ya?ml)$/, ""))
         .sort();
       return locales.length > 0 ? locales : [this._defaultLocale];
     } catch {
@@ -112,15 +112,58 @@ export class I18n {
         const raw = readFileSync(filePath, "utf-8");
         const data = JSON.parse(raw);
         this._translations.set(locale, I18n._flatten(data));
+        return;
       } catch {
         this._translations.set(locale, {});
+        return;
+      }
+    }
+    // Try YAML (.yml or .yaml) — zero-dep parser
+    for (const ext of [".yml", ".yaml"]) {
+      const yamlPath = join(this._localeDir, `${locale}${ext}`);
+      if (existsSync(yamlPath)) {
+        try {
+          const raw = readFileSync(yamlPath, "utf-8");
+          const data = I18n._parseSimpleYaml(raw);
+          this._translations.set(locale, I18n._flatten(data));
+          return;
+        } catch { /* skip */ }
       }
-    } else {
-      this._translations.set(locale, {});
     }
+    this._translations.set(locale, {});
   }
 
   /** Flatten nested objects: {"a": {"b": "c"}} → {"a.b": "c"} */
+
+  /** Zero-dep YAML parser for simple key: value locale files. */
+  private static _parseSimpleYaml(text: string): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    let currentParent: string | null = null;
+    for (const line of text.split("\n")) {
+      const stripped = line.trim();
+      if (!stripped || stripped.startsWith("#")) continue;
+      const indent = line.length - line.trimStart().length;
+      const colonIdx = stripped.indexOf(":");
+      if (colonIdx === -1) continue;
+      const key = stripped.substring(0, colonIdx).trim();
+      let value = stripped.substring(colonIdx + 1).trim();
+      // Strip quotes
+      if (value && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
+        value = value.substring(1, value.length - 1);
+      }
+      if (!value) {
+        currentParent = key;
+        result[key] = {};
+      } else if (indent > 0 && currentParent && typeof result[currentParent] === "object") {
+        (result[currentParent] as Record<string, string>)[key] = value;
+      } else {
+        currentParent = null;
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+
   private static _flatten(data: Record<string, unknown>, prefix = ""): Record<string, string> {
     const result: Record<string, string> = {};
     for (const [key, value] of Object.entries(data)) {

package/packages/core/src/queue.ts

@@ -623,7 +623,20 @@ export class Queue {
    *       processEmail(job);
    *   }
    */
-  *consume(topic?: string, id?: string): Generator<QueueJob> {
+  /**
+   * Long-running async generator that polls the queue continuously.
+   * When empty, sleeps for pollInterval ms before polling again.
+   * No external while-loop or sleep needed.
+   *
+   * @param topic Queue topic (defaults to constructor topic)
+   * @param id Optional job ID — single yield, no polling
+   * @param pollInterval Milliseconds to sleep when queue is empty (default 1000)
+   *
+   * Usage:
+   *   for await (const job of queue.consume("emails")) { ... }
+   *   for await (const job of queue.consume("emails", undefined, 5000)) { ... }
+   */
+  async *consume(topic?: string, id?: string, pollInterval: number = 1000): AsyncGenerator<QueueJob> {
     const q = topic ?? this.topic;
 
     if (id !== undefined) {
@@ -632,8 +645,15 @@ export class Queue {
       return;
     }
 
-    let raw: any;
-    while ((raw = this.pop(q)) !== null) {
+    // pollInterval=0 → single-pass drain (returns when empty)
+    // pollInterval>0 → long-running poll (sleeps when empty, never returns)
+    while (true) {
+      const raw = this.pop(q) as any;
+      if (raw === null) {
+        if (pollInterval <= 0) break;
+        await new Promise(resolve => setTimeout(resolve, pollInterval));
+        continue;
+      }
       yield createJob(raw, this, q);
     }
   }

package/packages/core/src/request.ts

@@ -12,7 +12,19 @@ export function createRequest(req: IncomingMessage): Tina4Request {
   tReq.params = {};
   tReq.query = query;
   tReq.body = undefined;
-  tReq.files = [];
+  tReq.files = {};
+  tReq.contentType = (req.headers["content-type"] ?? "") as string;
+
+  // Parse cookies from Cookie header
+  const cookieHeader = (req.headers.cookie ?? "") as string;
+  const cookies: Record<string, string> = {};
+  if (cookieHeader) {
+    for (const pair of cookieHeader.split(";")) {
+      const [k, ...v] = pair.trim().split("=");
+      if (k) cookies[k.trim()] = v.join("=").trim();
+    }
+  }
+  tReq.cookies = cookies;
 
   // Determine client IP with X-Forwarded-For support
   const forwarded = req.headers["x-forwarded-for"];
@@ -109,9 +121,9 @@ function extractBoundary(contentType: string): string | null {
 export function parseMultipart(
   body: Buffer,
   boundary: string,
-): { fields: Record<string, string>; files: UploadedFile[] } {
+): { fields: Record<string, string>; files: Record<string, UploadedFile | UploadedFile[]> } {
   const fields: Record<string, string> = {};
-  const files: UploadedFile[] = [];
+  const files: Record<string, UploadedFile | UploadedFile[]> = {};
 
   const delimiter = Buffer.from(`--${boundary}`);
   const closeDelimiter = Buffer.from(`--${boundary}--`);
@@ -152,13 +164,20 @@ export function parseMultipart(
 
     if (disposition.filename) {
       // File upload — standardised format: filename, type, content (raw bytes), size
-      files.push({
+      const file: UploadedFile = {
         fieldName: disposition.name,
         filename: disposition.filename,
         type: partContentType ?? "application/octet-stream",
         content: Buffer.from(content),
         size: content.length,
-      });
+      };
+      // Dict keyed by field name — multiple files under same name become array
+      if (files[disposition.name]) {
+        const existing = files[disposition.name];
+        files[disposition.name] = Array.isArray(existing) ? [...existing, file] : [existing, file];
+      } else {
+        files[disposition.name] = file;
+      }
     } else if (disposition.name) {
       // Regular field
       fields[disposition.name] = content.toString("utf-8");

package/packages/core/src/response.ts

@@ -110,6 +110,14 @@ export function createResponse(res: ServerResponse): Tina4Response {
     return response;
   };
 
+  response.xml = function (content: string, status?: number): Tina4Response {
+    if (res.headersSent) return response;
+    if (status !== undefined) res.statusCode = status;
+    safeSetHeader("Content-Type", "application/xml; charset=utf-8");
+    safeEnd(content);
+    return response;
+  };
+
   response.send = function (data: unknown, statusCode?: number, contentType?: string): Tina4Response {
     return response(data, statusCode, contentType);
   };
@@ -234,6 +242,40 @@ export function createResponse(res: ServerResponse): Tina4Response {
     return response.render(name, data, status, templateDir);
   };
 
+  /**
+   * Stream response from an async generator for Server-Sent Events (SSE).
+   *
+   * Usage:
+   *   export default async function (req, res) {
+   *     res.stream(async function* () {
+   *       for (let i = 0; i < 10; i++) {
+   *         yield `data: message ${i}\n\n`;
+   *         await new Promise(r => setTimeout(r, 1000));
+   *       }
+   *     }());
+   *   }
+   */
+  (response as any).stream = async function (
+    source: AsyncIterable<string | Buffer>,
+    contentType: string = "text/event-stream",
+  ): Promise<Tina4Response> {
+    if (res.headersSent) return response;
+    res.writeHead(200, {
+      "Content-Type": contentType,
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+
+    for await (const chunk of source) {
+      const data = typeof chunk === "string" ? chunk : chunk.toString();
+      res.write(data);
+    }
+
+    res.end();
+    return response;
+  };
+
   return response;
 }
 

package/packages/core/src/session.ts

@@ -430,18 +430,6 @@ export class Session {
     this.save();
   }
 
-  /**
-   * Clear all session data without destroying the session.
-   * The session ID and cookie remain — only the data is wiped.
-   */
-  clear(): void {
-    if (!this.data) return;
-    for (const key of Object.keys(this.data)) {
-      delete this.data[key];
-    }
-    this.save();
-  }
-
   /**
    * Destroy the entire session.
    */
@@ -506,31 +494,49 @@ export class Session {
   }
 
   /**
-   * Set flash data (auto-deleted after first read).
+   * Dual-mode flash: set with value, get+remove without.
+   *
+   *   session.flash("message", "Saved!")  // set
+   *   session.flash("message")            // get + auto-remove → "Saved!"
    */
-  flash(key: string, value: unknown): void {
-    this.set(`${FLASH_PREFIX}${key}`, value);
+  flash(key: string, value?: unknown): unknown {
+    const flashKey = `${FLASH_PREFIX}${key}`;
+    if (value !== undefined) {
+      // Set mode
+      this.set(flashKey, value);
+      return undefined;
+    }
+    // Get mode — read and remove
+    if (!this.data || !(flashKey in this.data)) return undefined;
+    const stored = this.data[flashKey];
+    delete this.data[flashKey];
+    this.save();
+    return stored;
   }
 
   /**
-   * Get flash data (auto-deleted after read).
+   * Get flash data by key (alias for flash(key) without value).
    */
   getFlash(key: string, defaultValue?: unknown): unknown {
-    const flashKey = `${FLASH_PREFIX}${key}`;
-    if (!this.data || !(flashKey in this.data)) return defaultValue;
-    const value = this.data[flashKey];
-    delete this.data[flashKey];
-    this.save();
-    return value ?? defaultValue;
+    const result = this.flash(key);
+    return result !== undefined ? result : defaultValue;
   }
 
   /**
    * Get the current session ID.
    */
-  getId(): string | null {
+  getSessionId(): string | null {
     return this.sessionId;
   }
 
+  /**
+   * Return a Set-Cookie header value for this session.
+   */
+  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}`;
+  }
+
   /**
    * Run garbage collection on the session backend.
    * Removes expired file/database sessions. Redis/Valkey/Mongo handle TTL natively.
@@ -541,9 +547,10 @@ export class Session {
     }
   }
 
-  // ── Private ───────────────────────────────────────────────────
-
-  private save(): void {
+  /**
+   * Persist session data to the backend.
+   */
+  save(): void {
     if (!this.sessionId || !this.data) return;
     this.handler.write(this.sessionId, this.data, this.ttl);
   }

package/packages/core/src/types.ts

@@ -22,7 +22,9 @@ export interface Tina4Request extends IncomingMessage {
   query: Record<string, string>;
   body: unknown;
   ip: string;
-  files: UploadedFile[];
+  files: Record<string, UploadedFile | UploadedFile[]>;
+  cookies: Record<string, string>;
+  contentType: string;
   session: Tina4Session;
   user?: Record<string, unknown>;
 }
@@ -41,6 +43,7 @@ export interface Tina4ResponseMethods {
   json(data: unknown, status?: number): Tina4Response;
   html(content: string, status?: number): Tina4Response;
   text(content: string, status?: number): Tina4Response;
+  xml(content: string, status?: number): Tina4Response;
   status(code: number): Tina4Response;
   header(name: string, value: string | number | readonly string[]): Tina4Response;
   send(data: unknown, statusCode?: number, contentType?: string): Tina4Response;
@@ -51,6 +54,8 @@ export interface Tina4ResponseMethods {
   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 */
   raw: ServerResponse;
 }

package/packages/core/src/websocket.ts

@@ -6,7 +6,7 @@
  *   import { WebSocketServer } from "@tina4/core";
  *
  *   const wss = new WebSocketServer({ port: 8080 });
- *   wss.on("connection", (client) => {
+ *   wss.on("open", (client) => {
  *     console.log("Connected:", client.id);
  *   });
  *   wss.on("message", (client, message) => {
@@ -330,7 +330,7 @@ export class WebSocketServer {
     };
 
     this.clients.set(clientId, client);
-    this.emit("connection", client);
+    this.emit("open", client);
 
     // Handle incoming data
     let buffer = Buffer.alloc(0);

package/packages/core/src/websocketConnection.ts

@@ -5,14 +5,18 @@
 export interface WebSocketConnection {
   /** Unique connection identifier */
   id: string;
+  /** The WebSocket route path this connection is on */
+  path: string;
+  /** Client IP address */
+  ip: string;
+  /** HTTP headers from the upgrade request */
+  headers: Record<string, string>;
+  /** Route parameters extracted from `{param}` segments in the path */
+  params: Record<string, string>;
   /** Send a message to this connection only */
   send(message: string): void;
   /** Broadcast a message to all connections on the same path (path-scoped) */
   broadcast(message: string): void;
   /** Close this connection */
   close(): void;
-  /** The WebSocket route path this connection is on */
-  path: string;
-  /** Route parameters extracted from `{param}` segments in the path */
-  params: Record<string, string>;
 }

package/packages/core/src/wsdl.ts

@@ -68,60 +68,95 @@ function escapeXml(value: string): string {
     .replace(/'/g, "'");
 }
 
-/**
- * Extract text content from an XML element by tag name (simple string parser).
- * Returns the text content of the first matching element, or null.
- */
-function extractElement(xml: string, tagName: string): string | null {
-  // Try with namespace prefix variations
-  const patterns = [
-    new RegExp(`<(?:[a-zA-Z0-9]+:)?${tagName}[^>]*>([\\s\\S]*?)</(?:[a-zA-Z0-9]+:)?${tagName}>`, "i"),
-    new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)</${tagName}>`, "i"),
-  ];
-
-  for (const pattern of patterns) {
-    const match = xml.match(pattern);
-    if (match) return match[1];
+// ── Minimal zero-dep XML DOM parser ────────────────────────────
+// Stack-based parser that builds a tree. Handles namespaces by
+// stripping prefixes. No external dependencies.
+
+interface XmlNode {
+  tag: string;
+  children: XmlNode[];
+  text: string;
+}
+
+function parseXml(xml: string): XmlNode {
+  const root: XmlNode = { tag: "", children: [], text: "" };
+  const stack: XmlNode[] = [root];
+  let i = 0;
+
+  while (i < xml.length) {
+    if (xml[i] === "<") {
+      const closeIdx = xml.indexOf(">", i);
+      if (closeIdx === -1) break;
+      const tagContent = xml.substring(i + 1, closeIdx).trim();
+
+      if (tagContent.startsWith("/")) {
+        stack.pop();
+      } else if (tagContent.startsWith("?") || tagContent.startsWith("!")) {
+        // PI or comment — skip
+      } else {
+        const selfClosing = tagContent.endsWith("/");
+        const raw = selfClosing ? tagContent.slice(0, -1).trim() : tagContent;
+        const spaceIdx = raw.indexOf(" ");
+        const fullTag = spaceIdx === -1 ? raw : raw.substring(0, spaceIdx);
+        const colonIdx = fullTag.indexOf(":");
+        const localTag = colonIdx === -1 ? fullTag : fullTag.substring(colonIdx + 1);
+
+        const node: XmlNode = { tag: localTag, children: [], text: "" };
+        stack[stack.length - 1].children.push(node);
+        if (!selfClosing) stack.push(node);
+      }
+      i = closeIdx + 1;
+    } else {
+      const nextTag = xml.indexOf("<", i);
+      const text = (nextTag === -1 ? xml.substring(i) : xml.substring(i, nextTag)).trim();
+      if (text && stack.length > 1) {
+        stack[stack.length - 1].text += text;
+      }
+      i = nextTag === -1 ? xml.length : nextTag;
+    }
   }
 
-  return null;
+  return root;
 }
 
-/**
- * Extract all direct child elements with their tag names and text content.
- * Returns an array of { name, value } pairs.
- */
-function extractChildren(xml: string): Array<{ name: string; value: string }> {
-  const results: Array<{ name: string; value: string }> = [];
-  // Match opening tags, capturing name (strip namespace prefix) and content
-  const pattern = /<(?:[a-zA-Z0-9]+:)?([a-zA-Z0-9_]+)[^>]*>([\s\S]*?)<\/(?:[a-zA-Z0-9]+:)?(\1)[^>]*>/g;
-
-  let match: RegExpExecArray | null;
-  while ((match = pattern.exec(xml)) !== null) {
-    results.push({ name: match[1], value: match[2].trim() });
+function findNode(node: XmlNode, tagName: string): XmlNode | null {
+  if (node.tag === tagName) return node;
+  for (const child of node.children) {
+    const found = findNode(child, tagName);
+    if (found) return found;
   }
+  return null;
+}
 
-  return results;
+function extractElement(xml: string, tagName: string): string | null {
+  const tree = parseXml(xml);
+  const node = findNode(tree, tagName);
+  if (!node) return null;
+  // Rebuild inner content from children
+  if (node.children.length === 0) return node.text || null;
+  // For complex content, fall back to regex on the original XML
+  const pattern = new RegExp(`<(?:[a-zA-Z0-9]+:)?${tagName}[^>]*>([\\s\\S]*?)</(?:[a-zA-Z0-9]+:)?${tagName}>`, "i");
+  const match = xml.match(pattern);
+  return match ? match[1] : node.text || null;
+}
+
+function extractChildren(xml: string): Array<{ name: string; value: string }> {
+  const tree = parseXml(xml);
+  const target = tree.children.length === 1 ? tree.children[0] : tree;
+  return target.children.map(c => ({ name: c.tag, value: c.text }));
 }
 
-/**
- * Extract the SOAP Body content from a SOAP envelope.
- */
 function extractSoapBody(xml: string): string | null {
   return extractElement(xml, "Body");
 }
 
-/**
- * Extract the operation element from the SOAP body.
- * Returns { name, content } or null.
- */
 function extractOperation(bodyXml: string): { name: string; content: string } | null {
-  // The first child element of Body is the operation
-  const match = bodyXml.match(/<(?:[a-zA-Z0-9]+:)?([a-zA-Z0-9_]+)[^>]*>([\s\S]*?)<\/(?:[a-zA-Z0-9]+:)?\1[^>]*>/i);
-  if (match) {
-    return { name: match[1], content: match[2] };
-  }
-  return null;
+  const tree = parseXml(bodyXml);
+  const firstChild = tree.children[0];
+  if (!firstChild) return null;
+  const pattern = new RegExp(`<(?:[a-zA-Z0-9]+:)?${firstChild.tag}[^>]*>([\\s\\S]*?)</(?:[a-zA-Z0-9]+:)?${firstChild.tag}>`, "i");
+  const match = bodyXml.match(pattern);
+  return { name: firstChild.tag, content: match ? match[1] : "" };
 }
 
 // ── Metadata storage ─────────────────────────────────────────

package/packages/orm/src/baseModel.ts

@@ -258,11 +258,12 @@ export class BaseModel {
 
   /**
    * Find all records, optionally with a where clause.
+   * Alias: all()
    * @param where Optional WHERE clause.
    * @param params Optional query parameters.
    * @param include Optional array of relationship names to eager-load.
    */
-  static findAll<T extends BaseModel>(
+  static all<T extends BaseModel>(
     this: new (data?: Record<string, unknown>) => T,
     where?: string,
     params?: unknown[],
@@ -293,10 +294,51 @@ export class BaseModel {
     return instances;
   }
 
+  /**
+   * Query records with a WHERE clause.
+   * Matches Python/PHP/Ruby where() API.
+   *
+   * @param conditions WHERE clause (e.g. "age > ? AND active = ?")
+   * @param params     Bind parameters
+   * @param limit      Max records (default 20)
+   * @param offset     Skip records (default 0)
+   * @param include    Relationship names to eager-load
+   */
+  static where<T extends BaseModel>(
+    this: new (data?: Record<string, unknown>) => T,
+    conditions: string,
+    params?: unknown[],
+    limit: number = 20,
+    offset: number = 0,
+    include?: string[],
+  ): T[] {
+    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
+    const db = ModelClass.getDb();
+
+    const parts: string[] = [];
+    if (ModelClass.softDelete) {
+      parts.push("is_deleted = 0");
+    }
+    if (ModelClass.tableFilter) {
+      parts.push(ModelClass.tableFilter);
+    }
+    parts.push(`(${conditions})`);
+
+    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${parts.join(" AND ")} LIMIT ${limit} OFFSET ${offset}`;
+
+    const rows = db.query(sql, params);
+    const instances = rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+    if (include) {
+      ModelClass._eagerLoad(instances, include);
+    }
+    return instances;
+  }
+
   /**
    * Save this instance (insert or update).
+   * Returns this on success (fluent), null on failure.
    */
-  save(): void {
+  save(): this | null {
     const ModelClass = this.constructor as typeof BaseModel;
     const db = ModelClass.getDb();
     const pk = ModelClass.getPkField();
@@ -339,8 +381,10 @@ export class BaseModel {
       db.commit();
     } catch (e) {
       db.rollback();
-      throw e;
+      return null;
     }
+    (this as any)._exists = true;
+    return this;
   }
 
   /**
@@ -454,6 +498,13 @@ export class BaseModel {
     return result;
   }
 
+  /**
+   * Convert to an associative object (alias for toDict).
+   */
+  toAssoc(include?: string[]): Record<string, unknown> {
+    return this.toDict(include);
+  }
+
   /**
    * Convert to a plain object (alias for toDict).
    */
@@ -477,9 +528,10 @@ export class BaseModel {
 
   /**
    * Convert to JSON string.
+   * @param include Optional relationship names to include.
    */
-  toJson(): string {
-    return JSON.stringify(this.toDict());
+  toJson(include?: string[]): string {
+    return JSON.stringify(this.toDict(include));
   }
 
   /**
@@ -659,7 +711,7 @@ export class BaseModel {
     conditions?: string,
     params?: unknown[],
     limit?: number,
-    skip?: number,
+    offset?: number,
   ): T[] {
     const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
     const db = ModelClass.getDb();
@@ -679,8 +731,8 @@ export class BaseModel {
     if (limit !== undefined) {
       sql += ` LIMIT ${limit}`;
     }
-    if (skip !== undefined) {
-      sql += ` OFFSET ${skip}`;
+    if (offset !== undefined) {
+      sql += ` OFFSET ${offset}`;
     }
 
     const rows = db.query(sql, params);
@@ -709,29 +761,22 @@ export class BaseModel {
   }
 
   /**
-   * Apply a named scope (reusable query filter).
+   * Register a reusable query scope on the class.
+   *
+   * Usage:
+   *   User.scope("active", "active = ?", [1]);
+   *   const users = (User as any).active();          // calls where("active = ?", [1])
+   *   const users = (User as any).active(10, 5);     // with limit/offset
    */
-  static scope<T extends BaseModel>(
-    this: new (data?: Record<string, unknown>) => T,
+  static scope(
     name: string,
     filterSql: string,
     params?: unknown[],
-  ): T[] {
-    const ModelClass = this as unknown as typeof BaseModel & (new (data?: Record<string, unknown>) => T);
-    const db = ModelClass.getDb();
-
-    const conditions: string[] = [];
-    if (ModelClass.softDelete) {
-      conditions.push("is_deleted = 0");
-    }
-    if (ModelClass.tableFilter) {
-      conditions.push(ModelClass.tableFilter);
-    }
-    conditions.push(filterSql);
-
-    const sql = `SELECT * FROM "${ModelClass.tableName}" WHERE ${conditions.join(" AND ")}`;
-    const rows = db.query(sql, params);
-    return rows.map((row) => new ModelClass(row as Record<string, unknown>) as T);
+  ): void {
+    const ModelClass = this as unknown as typeof BaseModel;
+    (ModelClass as any)[name] = (limit: number = 20, offset: number = 0) => {
+      return ModelClass.where.call(ModelClass as any, filterSql, params, limit, offset);
+    };
   }
 
   /**
@@ -773,6 +818,8 @@ export class BaseModel {
     this: T,
     relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R),
     foreignKey: string,
+    limit: number = 100,
+    offset: number = 0,
   ): R[] {
     const ModelClass = this.constructor as typeof BaseModel;
     const pk = ModelClass.getPkField();
@@ -787,6 +834,7 @@ export class BaseModel {
     if (relatedClass.softDelete) {
       sql += ` AND is_deleted = 0`;
     }
+    sql += ` LIMIT ${limit} OFFSET ${offset}`;
 
     const rows = db.query(sql, [pkValue]);
     const related = rows.map((row) => new relatedClass(row as Record<string, unknown>) as R);

package/packages/orm/src/database.ts

@@ -233,6 +233,7 @@ export class Database {
 
   /** Whether to automatically commit after each write operation */
   private autoCommit: boolean = process.env.TINA4_AUTOCOMMIT === "true";
+  private lastError: string | null = null;
 
   /** Database engine type (sqlite, postgres, mysql, mssql, firebird) */
   private dbType: string = "sqlite";
@@ -340,14 +341,28 @@ export class Database {
     return this.getNextAdapter().fetchOne<T>(sql, params);
   }
 
-  /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
-  execute(sql: string, params?: unknown[]): unknown {
-    const adapter = this.getNextAdapter();
-    const result = adapter.execute(sql, params);
-    if (this.autoCommit) {
-      try { adapter.commit(); } catch { /* no active transaction */ }
+  /**
+   * Execute a write statement. Returns true/false for simple writes.
+   * If SQL contains RETURNING, CALL, EXEC, or SELECT, returns the result set.
+   */
+  execute(sql: string, params?: unknown[]): boolean | unknown {
+    try {
+      const adapter = this.getNextAdapter();
+      const result = adapter.execute(sql, params);
+      if (this.autoCommit) {
+        try { adapter.commit(); } catch { /* no active transaction */ }
+      }
+      this.lastError = null;
+      const upper = sql.trim().toUpperCase();
+      if (upper.includes("RETURNING") || upper.startsWith("CALL ") ||
+          upper.startsWith("EXEC ") || upper.startsWith("SELECT ")) {
+        return result;
+      }
+      return true;
+    } catch (e: any) {
+      this.lastError = e?.message ?? String(e);
+      return false;
     }
-    return result;
   }
 
   /** Insert a row into a table. */
@@ -457,6 +472,20 @@ export class Database {
     return results;
   }
 
+  /** Return the last execute() error message, or null. */
+  getError(): string | null {
+    return this.lastError ?? null;
+  }
+
+  /** Return query cache statistics. */
+  cacheStats(): { enabled: boolean; size: number; ttl: number } {
+    return {
+      enabled: process.env.TINA4_DB_CACHE === "true",
+      size: 0,
+      ttl: parseInt(process.env.TINA4_DB_CACHE_TTL ?? "30", 10),
+    };
+  }
+
   /** Get the last auto-increment id. */
   getLastId(): string | number {
     const id = this.getNextAdapter().lastInsertId();