tina4-nodejs 3.13.85 → 3.13.87

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.85)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.87)
 
 > 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.85 - 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.87 - 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.
 
@@ -232,10 +232,10 @@ Backends: file, redis, redis-npm, valkey, mongodb, database.
 ### Database extras
 
 ```typescript
-db.execute(sql, params?): boolean | unknown  // RAISES on SQL error (never returns false; cause on getError()); on success: bool for writes, result for RETURNING/CALL/EXEC. try/catch — don't test the return.
-db.getLastId(): string | number
-db.getError(): string | null
-db.cacheStats(): { enabled, size, ttl }
+await db.execute(sql, params?): Promise<boolean | unknown>  // ASYNC — await it. RAISES on SQL error (never returns false; cause on getError()); on success: bool for writes, result for RETURNING/CALL/EXEC. try/catch — don't test the return.
+db.getLastId(): string | number   // synchronous
+db.getError(): string | null       // synchronous
+db.cacheStats(): { enabled, size, ttl }   // synchronous
 ```
 
 ### DocStore — pymongo-style document store (zero-config SQLite fallback)
@@ -627,43 +627,49 @@ import { initDatabase, bindDatabase, createAdapterFromUrl, Database, DatabaseRes
 const db = await initDatabase({ url: "sqlite:///app.db" });
 // Connection pooling: pass `pool: 4` for round-robin connections.
 
-// Reads — synchronous (node:sqlite is sync; other adapters are wrapped)
-db.fetch(sql, params?, limit?, offset?): DatabaseResult           // .records, .count, .limit, .offset
-db.fetchOne<T>(sql, params?): T | null
+// EVERY db method that touches the database is ASYNC on the Database wrapper --
+// it returns a Promise, so `await` it. (The node:sqlite ADAPTER underneath is
+// synchronous, but the wrapper is async so the query cache and the pg/mysql/
+// mssql/firebird adapters share one uniform API.) Only getLastId(), getError()
+// and close() are synchronous.
+
+// Reads — async, await them
+await db.fetch(sql, params?, limit?, offset?): Promise<DatabaseResult>   // .records, .count, .limit, .offset
+await db.fetchOne<T>(sql, params?): Promise<T | null>
 
 // Writes — execute() RAISES on a SQL error (bad SQL, constraint violation,
 // dead connection, missing driver): it records the cause on getError() then
 // re-throws — it never swallows and returns false (mirrors fetch()/fetchOne()).
-// On SUCCESS it returns boolean for simple writes, the result set for
+// On SUCCESS it resolves to boolean for simple writes, the result set for
 // RETURNING / CALL / EXEC / SELECT. Callers needing a bool (ORM save(),
 // createTable(), migration runner, dev-admin/MCP DB tools) try/catch and
 // convert — they must NOT test the return value for false.
-db.execute(sql, params?): boolean | unknown
-db.executeMany(sql, paramSets): unknown[]                         // wrapped in a transaction
-db.insert(table, data): DatabaseWriteResult
-db.update(table, data, filter?, params?): DatabaseWriteResult
-db.delete(table, filter?, params?): DatabaseWriteResult
-
-// Last-write metadata
-db.getLastId(): string | number | null
+await db.execute(sql, params?): Promise<boolean | unknown>
+await db.executeMany(sql, paramSets): Promise<unknown[]>          // wrapped in a transaction
+await db.insert(table, data): Promise<DatabaseWriteResult>
+await db.update(table, data, filter?, params?): Promise<DatabaseWriteResult>
+await db.delete(table, filter?, params?): Promise<DatabaseWriteResult>
+
+// Last-write metadata — SYNCHRONOUS (no await)
+db.getLastId(): string | number
 db.getError(): string | null
 
-// Transactions — autoCommit defaults to ON: a standalone write commits on its
-// own connection (durable + visible across the pool); inside startTransaction()
-// the per-statement commit is suppressed so the transaction stays atomic. Set
-// TINA4_AUTOCOMMIT=false for strict manual-commit mode.
-db.startTransaction(): void
-db.commit(): void
-db.rollback(): void
+// Transactions — async (await). autoCommit defaults to ON: a standalone write
+// commits on its own connection (durable + visible across the pool); inside
+// startTransaction() the per-statement commit is suppressed so the transaction
+// stays atomic. Set TINA4_AUTOCOMMIT=false for strict manual-commit mode.
+await db.startTransaction(): Promise<void>
+await db.commit(): Promise<void>
+await db.rollback(): Promise<void>
 
-// Schema introspection
-db.tableExists(name): boolean
-db.getTables(): string[]
-db.getColumns(table): { name, type, nullable?, default?, primaryKey? }[]
+// Schema introspection — async (await)
+await db.tableExists(name): Promise<boolean>
+await db.getTables(): Promise<string[]>
+await db.getColumns(table): Promise<{ name, type, nullable?, default?, primaryKey? }[]>
 
-// Race-safe sequence — uses tina4_sequences for SQLite/MySQL/MSSQL,
+// Race-safe sequence — async (await). Uses tina4_sequences for SQLite/MySQL/MSSQL,
 // auto-creates Postgres sequences, and uses native Firebird generators.
-db.getNextId(table, pkColumn?, generatorName?): number
+await db.getNextId(table, pkColumn?, generatorName?): Promise<number>
 
 // DB query cache — request-scoped auto cache is OFF by default (opt-in via
 // TINA4_AUTO_CACHING=true, TTL TINA4_AUTO_CACHING_TTL=5s): when enabled it dedupes
@@ -1238,7 +1244,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **98 built-in features**, zero third-party dependencies
-- **5,379 tests** passing across 154 files (build + typecheck green; 9 PostgreSQL/Valkey service-gated failures)
+- **5,879 tests** passing across 189 files (build + typecheck green)
 - **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)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.85",
+  "version": "3.13.87",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [
@@ -26,10 +26,26 @@
   "main": "packages/core/dist/index.js",
   "types": "packages/core/src/index.ts",
   "exports": {
-    ".": "./packages/core/src/index.ts",
-    "./orm": "./packages/orm/src/index.ts",
-    "./swagger": "./packages/swagger/src/index.ts",
-    "./frond": "./packages/frond/src/engine.ts"
+    ".": {
+      "types": "./packages/core/src/index.ts",
+      "import": "./packages/core/dist/index.js",
+      "default": "./packages/core/dist/index.js"
+    },
+    "./orm": {
+      "types": "./packages/orm/src/index.ts",
+      "import": "./packages/orm/dist/index.js",
+      "default": "./packages/orm/dist/index.js"
+    },
+    "./swagger": {
+      "types": "./packages/swagger/src/index.ts",
+      "import": "./packages/swagger/dist/index.js",
+      "default": "./packages/swagger/dist/index.js"
+    },
+    "./frond": {
+      "types": "./packages/frond/src/engine.ts",
+      "import": "./packages/frond/dist/index.js",
+      "default": "./packages/frond/dist/index.js"
+    }
   },
   "files": [
     "packages/frond/dist/**/*",
@@ -58,6 +74,7 @@
   "scripts": {
     "build": "npm run build --workspaces",
     "clean": "rm -rf packages/*/dist",
+    "pretest": "npm run build",
     "test": "tsx test/run-all.ts && npm run test:i18n",
     "test:i18n": "vitest run test/i18n.test.ts test/i18n-leaf-alias.test.ts",
     "typecheck": "tsc -p tsconfig.typecheck.json",