turbine-orm 0.5.0 → 0.7.0

package/dist/serverless.d.ts

@@ -1,162 +1,114 @@
 /**
- * @batadata/turbine/serverless — HTTP-based query driver for edge functions
+ * turbine-orm/serverless — edge / serverless driver integration
  *
- * Use this driver when you cannot establish a direct TCP connection to Postgres
- * (e.g., Vercel Edge Functions, Cloudflare Workers, Deno Deploy).
+ * Turbine runs on any Postgres driver that speaks the node-postgres API.
+ * This module exposes a thin factory (`turbineHttp`) that binds an external
+ * pg-compatible pool to a schema, so you can use Turbine on Vercel Edge,
+ * Cloudflare Workers, Deno Deploy, Netlify Edge, or any other environment
+ * where a direct TCP connection is unavailable.
  *
- * It sends queries as JSON over HTTP to a Turbine query endpoint, which executes
- * them against the actual database and returns typed results.
+ * ## Supported drivers
  *
- * NOTE: This is a scaffold. The server-side query endpoint does not exist yet.
- * The HTTP protocol and response format are defined here and will be implemented
- * on the server side in a future release.
+ * Any driver whose `Pool` satisfies `PgCompatPool` will work. The ones
+ * below are verified:
+ *
+ * - **Neon** (`@neondatabase/serverless`) — HTTP and WebSocket transports
+ * - **Vercel Postgres** (`@vercel/postgres`) — wraps Neon
+ * - **Cloudflare Hyperdrive** — exposes a pg-compatible driver
+ * - **Supabase** — use the regular `pg` package; Supabase is Postgres-native
+ *
+ * Turbine does NOT bundle any of these — install whichever you need and
+ * pass its pool directly.
+ *
+ * ## Limitations over HTTP
+ *
+ * - **Streaming cursors** (`findManyStream`, `findManyCursor`) require
+ *   server-side `DECLARE CURSOR`, which most HTTP drivers do not support.
+ *   If you call these on an HTTP pool the underlying driver will error.
+ * - **LISTEN/NOTIFY** is not available over HTTP.
+ * - **Transactions** are supported but each transaction holds an HTTP
+ *   connection for its duration — keep them short.
+ *
+ * ## Example — Neon on Vercel Edge
  *
- * @example
  * ```ts
- * import { createServerlessClient } from '@batadata/turbine/serverless';
+ * // app/api/users/route.ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { schema } from '@/generated/turbine/metadata';
+ *
+ * export const runtime = 'edge';
  *
- * const db = createServerlessClient({
- *   endpoint: 'https://your-turbine-proxy.fly.dev/query',
- *   authToken: process.env.TURBINE_AUTH_TOKEN!,
- * });
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, schema);
  *
- * const result = await db.query('SELECT * FROM users WHERE id = $1', [1]);
+ * export async function GET() {
+ *   const users = await db.table('users').findMany({ limit: 10 });
+ *   return Response.json(users);
+ * }
+ * ```
+ *
+ * ## Example — Supabase (direct Postgres, no HTTP proxy needed)
+ *
+ * ```ts
+ * import { TurbineClient } from 'turbine-orm';
+ * import { schema } from './generated/turbine/metadata.js';
+ *
+ * const db = new TurbineClient({
+ *   connectionString: process.env.SUPABASE_DB_URL,
+ *   ssl: { rejectUnauthorized: false },
+ * }, schema);
+ * ```
+ *
+ * ## Example — Cloudflare Workers
+ *
+ * ```ts
+ * // Use the Neon HTTP driver which works in Workers runtime
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ *
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const pool = new Pool({ connectionString: env.DATABASE_URL });
+ *     const db = turbineHttp(pool, schema);
+ *     const users = await db.table('users').findMany({ limit: 10 });
+ *     return Response.json(users);
+ *   }
+ * };
  * ```
  */
-/** Configuration for the serverless HTTP driver */
-export interface ServerlessConfig {
-    /** URL of the Turbine query endpoint (e.g. https://proxy.example.com/query) */
-    endpoint: string;
-    /** Authentication token for the endpoint */
-    authToken: string;
-    /** Request timeout in milliseconds (default: 10000) */
-    timeout?: number;
-    /** Custom fetch implementation (defaults to global fetch) */
-    fetch?: typeof globalThis.fetch;
-    /** Custom headers to include with every request */
-    headers?: Record<string, string>;
-}
-/** A single SQL query to execute */
-export interface QueryRequest {
-    /** SQL query string with $1, $2, ... parameter placeholders */
-    sql: string;
-    /** Parameter values */
-    params?: unknown[];
-    /** Hint for the server about expected result shape */
-    mode?: 'rows' | 'one' | 'count' | 'void';
-}
-/** Batch of queries to execute in a single round-trip */
-export interface BatchRequest {
-    queries: QueryRequest[];
-    /** Whether to wrap the batch in a transaction */
-    transaction?: boolean;
-}
-/** Response from the query endpoint for a single query */
-export interface QueryResponse<T = Record<string, unknown>> {
-    /** Returned rows */
-    rows: T[];
-    /** Number of rows affected (for INSERT/UPDATE/DELETE) */
-    rowCount: number;
-    /** Column metadata */
-    fields?: Array<{
-        name: string;
-        dataTypeID: number;
-    }>;
-    /** Server-side execution time in milliseconds */
-    durationMs?: number;
-}
-/** Response from the query endpoint for a batch */
-export interface BatchResponse {
-    results: QueryResponse[];
-    /** Total server-side execution time in milliseconds */
-    totalDurationMs?: number;
-}
-/** Error response from the query endpoint */
-export interface QueryError {
-    error: string;
-    code?: string;
-    detail?: string;
-}
+import { type PgCompatPool, TurbineClient, type TurbineConfig } from './client.js';
+import type { SchemaMetadata } from './schema.js';
+export type { PgCompatPool, PgCompatPoolClient, PgCompatQueryResult } from './client.js';
 /**
- * HTTP-based Postgres query client for serverless/edge environments.
- *
- * Sends SQL queries as JSON POST requests to a Turbine query endpoint.
- * Does not require a direct TCP connection to Postgres.
+ * Options for `turbineHttp()`. Mirrors the fields of `TurbineConfig`
+ * that are relevant for externally-managed pools.
  */
-export declare class ServerlessClient {
-    private readonly config;
-    private readonly fetchFn;
-    constructor(config: ServerlessConfig);
-    /**
-     * Execute a single SQL query.
-     *
-     * @param sql - SQL string with $1, $2, ... placeholders
-     * @param params - Parameter values
-     * @returns Query result with typed rows
-     *
-     * @example
-     * ```ts
-     * const result = await client.query<{ id: number; name: string }>(
-     *   'SELECT id, name FROM users WHERE org_id = $1',
-     *   [42]
-     * );
-     * console.log(result.rows);
-     * ```
-     */
-    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResponse<T>>;
-    /**
-     * Execute a single SQL query and return the first row, or null.
-     */
-    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
-    /**
-     * Execute a batch of queries in a single HTTP request.
-     * Optionally wraps them in a transaction.
-     *
-     * @param queries - Array of queries to execute
-     * @param options - Batch options
-     * @returns Array of results, one per query
-     *
-     * @example
-     * ```ts
-     * const results = await client.batch([
-     *   { sql: 'SELECT * FROM users WHERE id = $1', params: [1] },
-     *   { sql: 'SELECT COUNT(*) FROM posts WHERE user_id = $1', params: [1] },
-     * ], { transaction: true });
-     * ```
-     */
-    batch(queries: QueryRequest[], options?: {
-        transaction?: boolean;
-    }): Promise<BatchResponse>;
-    /**
-     * Tagged template helper for SQL queries.
-     *
-     * @example
-     * ```ts
-     * const users = await client.sql<{ id: number; name: string }>`
-     *   SELECT id, name FROM users WHERE org_id = ${orgId}
-     * `;
-     * ```
-     */
-    sql<T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
-    private post;
+export interface TurbineHttpOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
 }
 /**
- * Create a serverless Turbine client for edge/serverless environments.
+ * Create a TurbineClient bound to an external pg-compatible pool.
+ *
+ * Use this for serverless/edge environments where Turbine should NOT
+ * manage its own `pg.Pool`. The caller retains ownership of the pool's
+ * lifecycle — `db.disconnect()` is a no-op.
  *
- * @param config - Endpoint URL and auth token
- * @returns A ServerlessClient instance
+ * @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
  *
  * @example
  * ```ts
- * import { createServerlessClient } from '@batadata/turbine/serverless';
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { schema } from './generated/turbine/metadata.js';
  *
- * const db = createServerlessClient({
- *   endpoint: process.env.TURBINE_ENDPOINT!,
- *   authToken: process.env.TURBINE_AUTH_TOKEN!,
- * });
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, schema);
  *
- * const users = await db.sql`SELECT * FROM users LIMIT 10`;
+ * const users = await db.table('users').findMany({ limit: 10 });
  * ```
  */
-export declare function createServerlessClient(config: ServerlessConfig): ServerlessClient;
+export declare function turbineHttp(pool: PgCompatPool, schema: SchemaMetadata, options?: TurbineHttpOptions): TurbineClient;
 //# sourceMappingURL=serverless.d.ts.map

package/dist/serverless.js

@@ -1,195 +1,108 @@
 /**
- * @batadata/turbine/serverless — HTTP-based query driver for edge functions
+ * turbine-orm/serverless — edge / serverless driver integration
  *
- * Use this driver when you cannot establish a direct TCP connection to Postgres
- * (e.g., Vercel Edge Functions, Cloudflare Workers, Deno Deploy).
+ * Turbine runs on any Postgres driver that speaks the node-postgres API.
+ * This module exposes a thin factory (`turbineHttp`) that binds an external
+ * pg-compatible pool to a schema, so you can use Turbine on Vercel Edge,
+ * Cloudflare Workers, Deno Deploy, Netlify Edge, or any other environment
+ * where a direct TCP connection is unavailable.
  *
- * It sends queries as JSON over HTTP to a Turbine query endpoint, which executes
- * them against the actual database and returns typed results.
+ * ## Supported drivers
  *
- * NOTE: This is a scaffold. The server-side query endpoint does not exist yet.
- * The HTTP protocol and response format are defined here and will be implemented
- * on the server side in a future release.
+ * Any driver whose `Pool` satisfies `PgCompatPool` will work. The ones
+ * below are verified:
+ *
+ * - **Neon** (`@neondatabase/serverless`) — HTTP and WebSocket transports
+ * - **Vercel Postgres** (`@vercel/postgres`) — wraps Neon
+ * - **Cloudflare Hyperdrive** — exposes a pg-compatible driver
+ * - **Supabase** — use the regular `pg` package; Supabase is Postgres-native
+ *
+ * Turbine does NOT bundle any of these — install whichever you need and
+ * pass its pool directly.
+ *
+ * ## Limitations over HTTP
+ *
+ * - **Streaming cursors** (`findManyStream`, `findManyCursor`) require
+ *   server-side `DECLARE CURSOR`, which most HTTP drivers do not support.
+ *   If you call these on an HTTP pool the underlying driver will error.
+ * - **LISTEN/NOTIFY** is not available over HTTP.
+ * - **Transactions** are supported but each transaction holds an HTTP
+ *   connection for its duration — keep them short.
+ *
+ * ## Example — Neon on Vercel Edge
  *
- * @example
  * ```ts
- * import { createServerlessClient } from '@batadata/turbine/serverless';
+ * // app/api/users/route.ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { schema } from '@/generated/turbine/metadata';
+ *
+ * export const runtime = 'edge';
  *
- * const db = createServerlessClient({
- *   endpoint: 'https://your-turbine-proxy.fly.dev/query',
- *   authToken: process.env.TURBINE_AUTH_TOKEN!,
- * });
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, schema);
  *
- * const result = await db.query('SELECT * FROM users WHERE id = $1', [1]);
+ * export async function GET() {
+ *   const users = await db.table('users').findMany({ limit: 10 });
+ *   return Response.json(users);
+ * }
  * ```
- */
-// ---------------------------------------------------------------------------
-// Serverless client
-// ---------------------------------------------------------------------------
-/**
- * HTTP-based Postgres query client for serverless/edge environments.
  *
- * Sends SQL queries as JSON POST requests to a Turbine query endpoint.
- * Does not require a direct TCP connection to Postgres.
+ * ## Example — Supabase (direct Postgres, no HTTP proxy needed)
+ *
+ * ```ts
+ * import { TurbineClient } from 'turbine-orm';
+ * import { schema } from './generated/turbine/metadata.js';
+ *
+ * const db = new TurbineClient({
+ *   connectionString: process.env.SUPABASE_DB_URL,
+ *   ssl: { rejectUnauthorized: false },
+ * }, schema);
+ * ```
+ *
+ * ## Example — Cloudflare Workers
+ *
+ * ```ts
+ * // Use the Neon HTTP driver which works in Workers runtime
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ *
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const pool = new Pool({ connectionString: env.DATABASE_URL });
+ *     const db = turbineHttp(pool, schema);
+ *     const users = await db.table('users').findMany({ limit: 10 });
+ *     return Response.json(users);
+ *   }
+ * };
+ * ```
  */
-export class ServerlessClient {
-    config;
-    fetchFn;
-    constructor(config) {
-        if (!config.endpoint) {
-            throw new Error('[turbine/serverless] endpoint is required');
-        }
-        if (!config.authToken) {
-            throw new Error('[turbine/serverless] authToken is required');
-        }
-        this.config = {
-            ...config,
-            timeout: config.timeout ?? 10_000,
-        };
-        this.fetchFn = config.fetch ?? globalThis.fetch;
-    }
-    /**
-     * Execute a single SQL query.
-     *
-     * @param sql - SQL string with $1, $2, ... placeholders
-     * @param params - Parameter values
-     * @returns Query result with typed rows
-     *
-     * @example
-     * ```ts
-     * const result = await client.query<{ id: number; name: string }>(
-     *   'SELECT id, name FROM users WHERE org_id = $1',
-     *   [42]
-     * );
-     * console.log(result.rows);
-     * ```
-     */
-    async query(sql, params) {
-        const request = { sql, params, mode: 'rows' };
-        const response = await this.post('/query', request);
-        return response;
-    }
-    /**
-     * Execute a single SQL query and return the first row, or null.
-     */
-    async queryOne(sql, params) {
-        const request = { sql, params, mode: 'one' };
-        const response = await this.post('/query', request);
-        return response.rows[0] ?? null;
-    }
-    /**
-     * Execute a batch of queries in a single HTTP request.
-     * Optionally wraps them in a transaction.
-     *
-     * @param queries - Array of queries to execute
-     * @param options - Batch options
-     * @returns Array of results, one per query
-     *
-     * @example
-     * ```ts
-     * const results = await client.batch([
-     *   { sql: 'SELECT * FROM users WHERE id = $1', params: [1] },
-     *   { sql: 'SELECT COUNT(*) FROM posts WHERE user_id = $1', params: [1] },
-     * ], { transaction: true });
-     * ```
-     */
-    async batch(queries, options) {
-        const request = {
-            queries,
-            transaction: options?.transaction ?? false,
-        };
-        return this.post('/batch', request);
-    }
-    /**
-     * Tagged template helper for SQL queries.
-     *
-     * @example
-     * ```ts
-     * const users = await client.sql<{ id: number; name: string }>`
-     *   SELECT id, name FROM users WHERE org_id = ${orgId}
-     * `;
-     * ```
-     */
-    async sql(strings, ...values) {
-        let sqlStr = '';
-        strings.forEach((str, i) => {
-            sqlStr += str;
-            if (i < values.length) {
-                sqlStr += `$${i + 1}`;
-            }
-        });
-        const result = await this.query(sqlStr, values);
-        return result.rows;
-    }
-    // -------------------------------------------------------------------------
-    // Internal HTTP transport
-    // -------------------------------------------------------------------------
-    async post(path, body) {
-        const url = this.config.endpoint.replace(/\/$/, '') + path;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-        try {
-            const response = await this.fetchFn(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${this.config.authToken}`,
-                    'User-Agent': '@batadata/turbine-serverless',
-                    ...this.config.headers,
-                },
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                const errorBody = await response.text();
-                let parsed;
-                try {
-                    parsed = JSON.parse(errorBody);
-                }
-                catch {
-                    // Not JSON
-                }
-                const message = parsed?.error ?? `HTTP ${response.status}: ${errorBody.slice(0, 200)}`;
-                const err = new Error(`[turbine/serverless] ${message}`);
-                err['status'] = response.status;
-                err['code'] = parsed?.code;
-                throw err;
-            }
-            return (await response.json());
-        }
-        catch (err) {
-            if (err instanceof DOMException && err.name === 'AbortError') {
-                throw new Error(`[turbine/serverless] Request timed out after ${this.config.timeout}ms`);
-            }
-            throw err;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Factory function
-// ---------------------------------------------------------------------------
+import { TurbineClient } from './client.js';
 /**
- * Create a serverless Turbine client for edge/serverless environments.
+ * Create a TurbineClient bound to an external pg-compatible pool.
+ *
+ * Use this for serverless/edge environments where Turbine should NOT
+ * manage its own `pg.Pool`. The caller retains ownership of the pool's
+ * lifecycle — `db.disconnect()` is a no-op.
  *
- * @param config - Endpoint URL and auth token
- * @returns A ServerlessClient instance
+ * @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
  *
  * @example
  * ```ts
- * import { createServerlessClient } from '@batadata/turbine/serverless';
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import { schema } from './generated/turbine/metadata.js';
  *
- * const db = createServerlessClient({
- *   endpoint: process.env.TURBINE_ENDPOINT!,
- *   authToken: process.env.TURBINE_AUTH_TOKEN!,
- * });
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp(pool, schema);
  *
- * const users = await db.sql`SELECT * FROM users LIMIT 10`;
+ * const users = await db.table('users').findMany({ limit: 10 });
  * ```
  */
-export function createServerlessClient(config) {
-    return new ServerlessClient(config);
+export function turbineHttp(pool, schema, options = {}) {
+    return new TurbineClient({ pool, ...options }, schema);
 }
 //# sourceMappingURL=serverless.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "turbine-orm",
-  "version": "0.5.0",
-  "description": "TypeScript ORM with json_agg nested queries — 2-3x faster than Prisma, 1.5x faster than Drizzle",
+  "version": "0.7.0",
+  "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. 1 dependency, ~110KB",
   "type": "module",
   "exports": {
     ".": {
@@ -9,15 +9,15 @@
       "require": "./dist/cjs/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./cli": {
-      "import": "./dist/cli/config.js",
-      "require": "./dist/cjs/cli/config.js",
-      "types": "./dist/cli/config.d.ts"
-    },
     "./serverless": {
       "import": "./dist/serverless.js",
       "require": "./dist/cjs/serverless.js",
       "types": "./dist/serverless.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli/config.js",
+      "require": "./dist/cjs/cli/config.js",
+      "types": "./dist/cli/config.d.ts"
     }
   },
   "main": "./dist/cjs/index.js",
@@ -38,12 +38,18 @@
   "scripts": {
     "build": "tsc && tsc --project tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
     "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",
-    "test:unit": "tsx --test src/test/schema-builder.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",
+    "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",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm run test:unit",
+    "prepare": "husky"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -52,10 +58,14 @@
     "pg": "^8.13.1"
   },
   "devDependencies": {
-    "@types/pg": "^8.11.11",
+    "@biomejs/biome": "^2.4.10",
     "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "tsx": "^4.19.0"
+    "@types/pg": "^8.11.11",
+    "c8": "^11.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
   },
   "keywords": [
     "orm",
@@ -67,15 +77,22 @@
     "database",
     "sql",
     "turbine",
-    "batadata",
-    "nested-queries"
+    "nested-queries",
+    "prisma-alternative"
   ],
   "author": "ZVN DEV <dev@zvndev.com>",
   "license": "MIT",
   "homepage": "https://turbineorm.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zvndev/nexus-postgres",
-    "directory": "turbine/turbine-ts"
+    "url": "https://github.com/zvndev/turbine-orm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zvndev/turbine-orm/issues"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "biome check --no-errors-on-unmatched"
+    ]
   }
 }