turbine-orm 0.75.0 → 0.76.0

package/dist/sqlite.js

@@ -34,7 +34,7 @@
  * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
  *   (no Unicode case folding).
  *
- * ## Example, `:memory:` database
+ * ## Example, `:memory:` database, from a generated schema
  *
  * ```ts
  * import { turbineSqlite } from 'turbine-orm/sqlite';
@@ -44,11 +44,43 @@
  * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
  * await db.disconnect();
  * ```
+ *
+ * ## Example, SQLite with no Postgres anywhere
+ *
+ * The snippet above needs `turbine generate`, which reads a live **Postgres**
+ * catalog, so it is the wrong starting point if SQLite is your only database.
+ * Describe the schema in code instead: `schemaToSQL` emits the DDL and
+ * `schemaDefToMetadata` derives the runtime metadata (relations included, from
+ * the same `references:`), both pure functions with no database involved.
+ *
+ * ```ts
+ * import { defineSchema, schemaDefToMetadata, schemaToSQL } from 'turbine-orm';
+ * import { sqliteDialect, turbineSqlite } from 'turbine-orm/sqlite';
+ *
+ * const schema = defineSchema({
+ *   users: { id: { type: 'serial', primaryKey: true }, email: { type: 'text', notNull: true } },
+ *   posts: {
+ *     id: { type: 'serial', primaryKey: true },
+ *     userId: { type: 'integer', notNull: true, references: 'users.id' },
+ *     title: { type: 'text', notNull: true },
+ *   },
+ * });
+ *
+ * const db = turbineSqlite(':memory:', schemaDefToMetadata(schema));
+ * for (const stmt of schemaToSQL(schema, { dialect: sqliteDialect })) {
+ *   await db.raw([stmt] as never);
+ * }
+ *
+ * // `db.table(...)`, not `db.users`: the typed property accessors are emitted
+ * // by `turbine generate`, and this path skips it.
+ * const users = await db.table('users').findMany({ with: { posts: true }, orderBy: { id: 'asc' } });
+ * await db.disconnect();
+ * ```
  */
 import { createRequire } from 'node:module';
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
-import { ConnectionError, UnsupportedFeatureError } from './errors.js';
+import { ConnectionError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import { LRUCache } from './query/utils.js';
 import { isDateType, snakeToCamel, } from './schema.js';
@@ -241,8 +273,24 @@ function statementReturnsRows(sql) {
  * recognizable SQLite error.
  *
  * `wrapPgError` is invoked downstream (in the query executor and the
- * transaction proxy), so we only annotate here, we never throw a `new`
- * Turbine error from the driver itself.
+ * transaction proxy), so annotation is the preferred half of the job: every
+ * failure whose meaning Postgres already has a SQLSTATE for is expressed as
+ * that SQLSTATE and typed by the one classifier.
+ *
+ * ONE family cannot be handled that way, and it was the family a new user hits
+ * first. `SQLITE_ERROR` (primary code 1, "SQL logic error") covers
+ * `no such table: users`, `no such column: emial`, and a plain syntax error;
+ * Postgres reports the same three as 42P01 / 42703 / 42601, and `wrapPgError`
+ * classifies none of them, on either engine. So on SQLite they reached the
+ * caller as a bare `Error` with `code: 'ERR_SQLITE_ERROR'`: no `TURBINE_E0NN`,
+ * no `.docsUrl`, not a `TurbineError` at all, in a library whose typed-error
+ * table is a headline feature. {@link sqliteLogicError} builds the
+ * `ValidationError` for them here, the way `wrapPowdbError` builds its errors
+ * for a driver with no SQLSTATEs to annotate.
+ *
+ * Everything else stays annotation, so the two engines cannot drift: fixing a
+ * constraint classification in `wrapPgError` fixes it for SQLite in the same
+ * commit.
  */
 function augmentSqliteError(err) {
     if (!err || typeof err !== 'object')
@@ -290,10 +338,43 @@ function augmentSqliteError(err) {
             if (primary === 5 || primary === 6) {
                 // Map to serialization_failure so withRetry()/$retry() retry it.
                 target.code = '40001';
+                return err;
             }
+            // SQLITE_ERROR (1): the statement itself is wrong. See the note above.
+            if (primary === 1)
+                return sqliteLogicError(message, err);
             return err;
     }
 }
+/**
+ * The `ValidationError` for a `SQLITE_ERROR`, with a hint for the two spellings
+ * that account for nearly all of them.
+ *
+ * The driver's own text IS the diagnosis (`no such table: users` names the
+ * table), so it is kept verbatim rather than replaced.
+ *
+ * The original error IS attached as `cause`, and safe mode is not a reason not
+ * to: `TurbineError` runs every cause it is given through `redactCauseForMode`,
+ * so attaching one goes THROUGH the redaction rather than around it. It also
+ * discloses nothing new here, because the driver's message is already quoted
+ * verbatim into the message above it. What it buys is the stack: without it a
+ * `no such table` surfaces with Turbine's frames and none of the driver's.
+ */
+function sqliteLogicError(message, cause) {
+    const missingTable = /^no such table:\s*(\S+)/i.exec(message);
+    if (missingTable) {
+        return new ValidationError(`[turbine] SQLite has no table "${missingTable[1]}": ${message}. ` +
+            'Create it first (run your migrations, or execute the CREATE TABLE statements for this schema); ' +
+            'an in-memory database starts empty on every connection.', { cause });
+    }
+    const missingColumn = /^no such column:\s*(\S+)/i.exec(message);
+    if (missingColumn) {
+        return new ValidationError(`[turbine] SQLite has no column "${missingColumn[1]}": ${message}. ` +
+            'Check the spelling against the table as it exists in this database, ' +
+            'and re-run `turbine generate` if the schema has changed.', { cause });
+    }
+    return new ValidationError(`[turbine] SQLite rejected the statement: ${message}`, { cause });
+}
 function normalizeQueryArgs(arg, values) {
     if (typeof arg === 'string')
         return { text: arg, params: values ?? [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -128,7 +128,7 @@
     "//coverage:cli": "The CLI coverage gate, split into ONE collection run plus a per-file threshold check for every file in it, and an aggregate. c8 enforces a single threshold set per invocation and its --per-file applies the SAME numbers to every file, neither of which can express 'destructive.ts holds 100 while migrate.ts holds 70'. An aggregate-only floor lets the least-covered file spend the whole slack the best-covered file earned: at the measured 3623/2951 lines, migrate.ts could fall from 70.3% to 66.6% with the aggregate still green. So each file gets its OWN floor, checked by re-reporting the coverage already on disk (c8 report re-reads ./coverage/tmp, so this costs no extra test run). The aggregate check is kept as well: it catches all three sagging together inside their individual margins. Per-file gates run FIRST because their failure names the file. DATABASE_URL is neutralized on the collection run: these test files include live migration tests that create and drop tables, and this script runs from prepublishOnly.",
     "test:coverage:cli": "npm run coverage:cli:collect && npm run coverage:cli:gate:destructive && npm run coverage:cli:gate:sql-statements && npm run coverage:cli:gate:pii-guard && npm run coverage:cli:gate:error-catalog && npm run coverage:cli:gate:mcp && npm run coverage:cli:gate:compile-query && npm run coverage:cli:gate:studio && npm run coverage:cli:gate:migrate && npm run coverage:cli:gate:aggregate",
     "//coverage:cli:collect": "--check-coverage=false is load-bearing, not tidying. c8 reads .c8rc.json for defaults, so this COLLECTION step was silently enforcing the MAIN gate's global thresholds against a src/cli-only file set. That is a gate nobody wrote and nobody wanted, and it went unnoticed only because the main floor was low enough (75) for the CLI aggregate (89.29) to clear it by accident. When the main floors were re-baselined to 93/89/78 (see //merge-bug in .c8rc.json) it started failing here, several steps before the per-file gates that are supposed to decide. Thresholds for these files belong to the coverage:cli:gate:* scripts, which pass their own explicitly.",
-    "coverage:cli:collect": "DATABASE_URL= c8 --all --check-coverage=false --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/compile-query.ts --include src/cli/error-catalog.ts tsx --test src/test/studio-write.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/tracking-table-race.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts src/test/mcp.test.ts src/test/mcp-relations.test.ts src/test/mcp-pii.test.ts src/test/mcp-pii-round2.test.ts src/test/mcp-agent-tools.test.ts src/test/mcp-compile-query.test.ts",
+    "coverage:cli:collect": "DATABASE_URL= c8 --all --check-coverage=false --reporter text --exclude 'src/test/**' --include src/cli/studio.ts --include src/cli/migrate.ts --include src/cli/destructive.ts --include src/cli/sql-statements.ts --include src/cli/pii-predicate-guard.ts --include src/cli/mcp.ts --include src/cli/compile-query.ts --include src/cli/error-catalog.ts tsx --test src/test/studio-write.test.ts src/test/pii-guard-symmetry.test.ts src/test/studio-demo.test.ts src/test/studio.test.ts src/test/studio-security.test.ts src/test/migrate.test.ts src/test/migrate-deploy.test.ts src/test/migrate-smoke-fixes.test.ts src/test/tracking-table-race.test.ts src/test/destructive-dynamic-assembly.test.ts src/test/destructive-migrations.test.ts src/test/backfill-recipe.test.ts src/test/cli.test.ts src/test/cli-diff-migration.test.ts src/test/cli-flags.test.ts src/test/cli-first-run.test.ts src/test/mcp.test.ts src/test/mcp-relations.test.ts src/test/mcp-pii.test.ts src/test/mcp-pii-round2.test.ts src/test/mcp-agent-tools.test.ts src/test/mcp-compile-query.test.ts src/test/mcp-perimeter-bounds.test.ts",
     "coverage:cli:gate": "c8 report --all --exclude 'src/test/**' --reporter text --check-coverage",
     "coverage:cli:gate:destructive": "npm run coverage:cli:gate -- --include src/cli/destructive.ts --lines 98 --statements 98 --branches 84 --functions 98",
     "coverage:cli:gate:sql-statements": "npm run coverage:cli:gate -- --include src/cli/sql-statements.ts --lines 100 --statements 100 --branches 98 --functions 100",