turbine-orm 0.24.0 → 0.25.0

package/dist/cjs/serverless.js

@@ -89,12 +89,29 @@ const client_js_1 = require("./client.js");
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -102,10 +119,25 @@ const client_js_1 = require("./client.js");
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
 function turbineHttp(pool, schema, options = {}) {
+    // The generated subclass only layers `declare readonly` accessor typings
+    // over the base client; the base constructor materializes those same
+    // accessors at runtime (Object.defineProperty per schema table). So the
+    // returned instance genuinely has TClient's shape — the assertion is safe.
     return new client_js_1.TurbineClient({ pool, ...options }, schema);
 }

package/dist/serverless.d.ts

@@ -94,12 +94,29 @@ export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'def
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -107,8 +124,19 @@ export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'def
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
-export declare function turbineHttp(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TurbineClient;
+export declare function turbineHttp<TClient extends TurbineClient = TurbineClient>(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TClient;

package/dist/serverless.js

@@ -86,12 +86,29 @@ import { TurbineClient } from './client.js';
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -99,10 +116,25 @@ import { TurbineClient } from './client.js';
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
 export function turbineHttp(pool, schema, options = {}) {
+    // The generated subclass only layers `declare readonly` accessor typings
+    // over the base client; the base constructor materializes those same
+    // accessors at runtime (Object.defineProperty per schema table). So the
+    // returned instance genuinely has TClient's shape — the assertion is safe.
     return new TurbineClient({ pool, ...options }, schema);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.24.0",
+  "version": "0.25.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": {