turbine-orm 0.16.0 → 0.19.0

package/dist/typed-sql.d.ts

@@ -0,0 +1,101 @@
+/**
+ * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ *
+ * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
+ * a generic tagged template where the caller supplies the row shape, and the
+ * builder yields a typed result that can be awaited as an array of rows, or
+ * narrowed to a single row (`.one()`) or a single scalar value (`.scalar()`).
+ *
+ * Design goals & guarantees:
+ *
+ *  1. **Compile-time only types.** `T` is supplied by the caller and never
+ *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
+ *     is a convenience for autocomplete and downstream type-checking.
+ *
+ *  2. **Mandatory parameterization.** Only the *static* string segments of the
+ *     template literal ever reach the SQL text. Every interpolated `${value}`
+ *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     impossible to string-concatenate a value into the query through this API.
+ *     This is the whole point of the tagged-template shape: the literal segments
+ *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
+ *     get a runtime value into the query is via `${...}`, which we bind.
+ *
+ *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
+ *     existing `client.raw()` behavior: a typed raw query is a literal escape
+ *     hatch, so the result columns are whatever your `SELECT` names them. Alias
+ *     columns in SQL (`SELECT created_at AS "createdAt"`) if you want camelCase.
+ *
+ * @example
+ * ```ts
+ * // Awaited directly -> rows
+ * const rows = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE org_id = ${orgId}
+ * `;
+ * //    ^? { id: number; name: string }[]
+ *
+ * // .one() -> single row or null
+ * const user = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE id = ${userId}
+ * `.one();
+ * //    ^? { id: number; name: string } | null
+ *
+ * // .scalar() -> first column of first row, or null
+ * const total = await db.sql<{ count: number }>`
+ *   SELECT COUNT(*)::int AS count FROM users WHERE org_id = ${orgId}
+ * `.scalar();
+ * //    ^? number | null
+ * ```
+ */
+import type { PgCompatPool } from './client.js';
+/**
+ * Build a `(sql, params)` pair from a tagged-template invocation.
+ *
+ * Each interpolated value is replaced by a positional `$N` placeholder and
+ * pushed to the params array in order. The static string segments are the only
+ * thing concatenated into the SQL text. This is the single point that
+ * guarantees parameterization for the entire typed-SQL surface.
+ *
+ * Exported for unit testing the parameterization invariant without a database.
+ */
+export declare function buildTypedSql(strings: TemplateStringsArray, values: readonly unknown[]): {
+    sql: string;
+    params: unknown[];
+};
+/**
+ * A pending typed raw SQL query. Implements the thenable contract, so it can be
+ * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
+ *
+ * The query is executed lazily and exactly once per terminal call (`then`,
+ * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * an escape hatch, not a cached query object, so don't call two terminals on
+ * the same builder expecting a single round-trip; build a fresh template each
+ * time (the common pattern is `await db.sql\`...\`` inline).
+ */
+export declare class TypedSqlQuery<T extends Record<string, unknown>> implements PromiseLike<T[]> {
+    private readonly pool;
+    private readonly sql;
+    private readonly params;
+    private readonly logging;
+    constructor(pool: PgCompatPool, sql: string, params: unknown[], logging: boolean);
+    /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
+    private run;
+    /**
+     * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.
+     */
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Execute and return the first row, or `null` if the query returns no rows.
+     * Use for queries you expect to match at most one row.
+     */
+    one(): Promise<T | null>;
+    /**
+     * Execute and return the first column of the first row, or `null` if there
+     * are no rows. Useful for `SELECT COUNT(*)`, `SELECT EXISTS(...)`, etc.
+     *
+     * The generic `V` defaults to the value type of `T`'s first property, but you
+     * can override it: `db.sql<{ count: number }>\`...\`.scalar<number>()`.
+     */
+    scalar<V = T[keyof T]>(): Promise<V | null>;
+}
+//# sourceMappingURL=typed-sql.d.ts.map

package/dist/typed-sql.js

@@ -0,0 +1,145 @@
+/**
+ * turbine-orm — Typed raw SQL (Turbine's answer to Prisma's TypedSQL)
+ *
+ * `client.raw()` returns untyped rows. This module adds a *typed* escape hatch:
+ * a generic tagged template where the caller supplies the row shape, and the
+ * builder yields a typed result that can be awaited as an array of rows, or
+ * narrowed to a single row (`.one()`) or a single scalar value (`.scalar()`).
+ *
+ * Design goals & guarantees:
+ *
+ *  1. **Compile-time only types.** `T` is supplied by the caller and never
+ *     validated at runtime — exactly like Prisma's TypedSQL and the existing
+ *     `raw<T>()`. Postgres still returns whatever the SQL selects; the generic
+ *     is a convenience for autocomplete and downstream type-checking.
+ *
+ *  2. **Mandatory parameterization.** Only the *static* string segments of the
+ *     template literal ever reach the SQL text. Every interpolated `${value}`
+ *     becomes a `$N` placeholder and is passed in the params array — it is
+ *     impossible to string-concatenate a value into the query through this API.
+ *     This is the whole point of the tagged-template shape: the literal segments
+ *     are frozen by the compiler (`TemplateStringsArray`), and the only way to
+ *     get a runtime value into the query is via `${...}`, which we bind.
+ *
+ *  3. **Rows are returned as-is (no snake→camel mapping).** This matches the
+ *     existing `client.raw()` behavior: a typed raw query is a literal escape
+ *     hatch, so the result columns are whatever your `SELECT` names them. Alias
+ *     columns in SQL (`SELECT created_at AS "createdAt"`) if you want camelCase.
+ *
+ * @example
+ * ```ts
+ * // Awaited directly -> rows
+ * const rows = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE org_id = ${orgId}
+ * `;
+ * //    ^? { id: number; name: string }[]
+ *
+ * // .one() -> single row or null
+ * const user = await db.sql<{ id: number; name: string }>`
+ *   SELECT id, name FROM users WHERE id = ${userId}
+ * `.one();
+ * //    ^? { id: number; name: string } | null
+ *
+ * // .scalar() -> first column of first row, or null
+ * const total = await db.sql<{ count: number }>`
+ *   SELECT COUNT(*)::int AS count FROM users WHERE org_id = ${orgId}
+ * `.scalar();
+ * //    ^? number | null
+ * ```
+ */
+import { ValidationError, wrapPgError } from './errors.js';
+/**
+ * Build a `(sql, params)` pair from a tagged-template invocation.
+ *
+ * Each interpolated value is replaced by a positional `$N` placeholder and
+ * pushed to the params array in order. The static string segments are the only
+ * thing concatenated into the SQL text. This is the single point that
+ * guarantees parameterization for the entire typed-SQL surface.
+ *
+ * Exported for unit testing the parameterization invariant without a database.
+ */
+export function buildTypedSql(strings, values) {
+    // The tagged-template API guarantees `strings.length === values.length + 1`.
+    // Guard the directly-callable (exported) surface so a mismatched call can't
+    // silently desync `$N` placeholders from params (pg would reject it, but fail
+    // loudly here instead).
+    if (strings.length !== values.length + 1) {
+        throw new ValidationError(`[turbine] sql template segment/value count mismatch: ${strings.length} segments, ${values.length} values.`);
+    }
+    let sql = '';
+    for (let i = 0; i < strings.length; i++) {
+        sql += strings[i];
+        if (i < values.length) {
+            sql += `$${i + 1}`;
+        }
+    }
+    return { sql, params: values.slice() };
+}
+/**
+ * A pending typed raw SQL query. Implements the thenable contract, so it can be
+ * `await`ed directly to get `T[]`, or refined via `.one()` / `.scalar()` first.
+ *
+ * The query is executed lazily and exactly once per terminal call (`then`,
+ * `one`, `scalar`). Each terminal method runs the query independently — this is
+ * an escape hatch, not a cached query object, so don't call two terminals on
+ * the same builder expecting a single round-trip; build a fresh template each
+ * time (the common pattern is `await db.sql\`...\`` inline).
+ */
+export class TypedSqlQuery {
+    pool;
+    sql;
+    params;
+    logging;
+    constructor(pool, sql, params, logging) {
+        this.pool = pool;
+        this.sql = sql;
+        this.params = params;
+        this.logging = logging;
+    }
+    /** Execute and return all rows. Internal; powers `then`, `one`, and `scalar`. */
+    async run() {
+        if (this.logging) {
+            console.log(`[turbine] Typed SQL: ${this.sql.trim().substring(0, 120)}...`);
+        }
+        try {
+            const result = await this.pool.query(this.sql, this.params);
+            return result.rows;
+        }
+        catch (err) {
+            throw wrapPgError(err);
+        }
+    }
+    /**
+     * PromiseLike implementation: `await db.sql<T>\`...\`` resolves to `T[]`.
+     */
+    // biome-ignore lint/suspicious/noThenProperty: intentional thenable — this IS the PromiseLike contract that makes `await db.sql\`...\`` resolve to rows
+    then(onfulfilled, onrejected) {
+        return this.run().then(onfulfilled, onrejected);
+    }
+    /**
+     * Execute and return the first row, or `null` if the query returns no rows.
+     * Use for queries you expect to match at most one row.
+     */
+    async one() {
+        const rows = await this.run();
+        return rows.length > 0 ? rows[0] : null;
+    }
+    /**
+     * Execute and return the first column of the first row, or `null` if there
+     * are no rows. Useful for `SELECT COUNT(*)`, `SELECT EXISTS(...)`, etc.
+     *
+     * The generic `V` defaults to the value type of `T`'s first property, but you
+     * can override it: `db.sql<{ count: number }>\`...\`.scalar<number>()`.
+     */
+    async scalar() {
+        const rows = await this.run();
+        if (rows.length === 0)
+            return null;
+        const first = rows[0];
+        const keys = Object.keys(first);
+        if (keys.length === 0)
+            return null;
+        return first[keys[0]];
+    }
+}
+//# sourceMappingURL=typed-sql.js.map

package/package.json

@@ -1,28 +1,28 @@
 {
   "name": "turbine-orm",
-  "version": "0.16.0",
-  "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. 1 dependency, ~110KB",
+  "version": "0.19.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": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/cjs/index.js"
     },
     "./serverless": {
+      "types": "./dist/serverless.d.ts",
       "import": "./dist/serverless.js",
-      "require": "./dist/cjs/serverless.js",
-      "types": "./dist/serverless.d.ts"
+      "require": "./dist/cjs/serverless.js"
     },
     "./cli": {
+      "types": "./dist/cli/config.d.ts",
       "import": "./dist/cli/config.js",
-      "require": "./dist/cjs/cli/config.js",
-      "types": "./dist/cli/config.d.ts"
+      "require": "./dist/cjs/cli/config.js"
     },
     "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.js",
-      "require": "./dist/cjs/adapters/index.js",
-      "types": "./dist/adapters/index.d.ts"
+      "require": "./dist/cjs/adapters/index.js"
     }
   },
   "main": "./dist/cjs/index.js",
@@ -48,9 +48,10 @@
     "generate": "tsx src/cli/index.ts generate",
     "status": "tsx src/cli/index.ts status",
     "examples": "tsx examples/examples.ts",
-    "test": "tsx --test src/test/*.test.ts",
+    "dogfood": "tsx examples/dogfood.ts",
+    "test": "tsx --test --test-concurrency=1 src/test/*.test.ts",
     "test:unit": "tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/dialect.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts src/test/cockroachdb-adapter.test.ts src/test/yugabytedb-adapter.test.ts src/test/pg-compat.test.ts src/test/relation-filter-validation.test.ts src/test/client-coverage.test.ts src/test/schema-diff.test.ts src/test/composite-fk.test.ts src/test/retry.test.ts src/test/text-search.test.ts src/test/optimistic-lock.test.ts src/test/sql-safety-property.test.ts src/test/nested-write.test.ts src/test/nested-write-update-upsert.test.ts src/test/cursor-pagination.test.ts src/test/client-branches.test.ts src/test/is-isNot-filter.test.ts src/test/event-emitter.test.ts src/test/observe.test.ts",
-    "test:coverage": "c8 tsx --test src/test/schema-builder.test.ts src/test/errors.test.ts src/test/stress.test.ts src/test/migrate.test.ts src/test/update-operators.test.ts src/test/empty-where-guard.test.ts src/test/cli.test.ts src/test/serverless.test.ts src/test/pipeline.test.ts src/test/pipeline-submittable.test.ts src/test/with-inference.test.ts src/test/operator-validation.test.ts src/test/unlimited-warning.test.ts src/test/generate-relations.test.ts src/test/stream-and-parse.test.ts src/test/sql-cache.test.ts src/test/dialect.test.ts src/test/studio.test.ts src/test/sql-injection.test.ts src/test/cli-flags.test.ts",
+    "test:coverage": "c8 tsx --test --test-concurrency=1 src/test/*.test.ts",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "format": "biome format --write src/",
@@ -74,17 +75,18 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@types/pg": "^8.11.11",
     "pg": "^8.13.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@size-limit/file": "^12.0.1",
+    "@size-limit/esbuild": "^12.1.0",
+    "@size-limit/file": "^12.1.0",
     "@types/node": "^22.10.0",
-    "@types/pg": "^8.11.11",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
-    "size-limit": "^12.0.1",
+    "size-limit": "^12.1.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   },