turbine-orm 0.4.0 → 0.5.0

package/dist/client.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — TurbineClient
+ * @batadata/turbine — TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -16,7 +16,7 @@
  * const user = await db.users.findUnique({ where: { id: 1 } });
  *
  * // With base client (dynamic):
- * import { TurbineClient } from 'turbine-orm';
+ * import { TurbineClient } from '@batadata/turbine';
  * const db = new TurbineClient({ connectionString: '...' }, schema);
  * const users = db.table<User>('users');
  * ```
@@ -24,19 +24,20 @@
 import pg from 'pg';
 import { QueryInterface } from './query.js';
 import { executePipeline } from './pipeline.js';
-// Parse int8 (bigint, OID 20) as JavaScript number instead of string.
-// Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
+/**
+ * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
+ * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
+ *
+ * NOTE: For values exceeding Number.MAX_SAFE_INTEGER, the parser falls back
+ * to returning the raw string to avoid precision loss. The generated TypeScript
+ * type maps int8/bigint to `number`, which is correct for the vast majority of
+ * use cases (IDs, counts, timestamps). If you store values > 2^53 - 1 in a
+ * bigint column, the runtime return type will be `string` for those rows.
+ */
 pg.types.setTypeParser(20, (val) => {
     const n = Number(val);
     return Number.isSafeInteger(n) ? n : val; // fall back to string for huge values
 });
-// Parse numeric (OID 1700) as number when safe, string otherwise
-pg.types.setTypeParser(1700, (val) => {
-    const n = Number(val);
-    if (val.includes('.') && Number.isFinite(n))
-        return n;
-    return Number.isSafeInteger(n) ? n : val;
-});
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
     ReadUncommitted: 'READ UNCOMMITTED',
@@ -56,12 +57,14 @@ export class TransactionClient {
     client;
     schema;
     middlewares;
+    queryOptions;
     tableCache = new Map();
     savepointCounter = 0;
-    constructor(client, schema, middlewares) {
+    constructor(client, schema, middlewares, queryOptions) {
         this.client = client;
         this.schema = schema;
         this.middlewares = middlewares;
+        this.queryOptions = queryOptions;
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
             const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
@@ -83,7 +86,7 @@ export class TransactionClient {
             // Create a QueryInterface that uses the transaction client as its "pool"
             // We use a proxy pool that routes queries through the transaction client
             const txPool = this.createTxPool();
-            qi = new QueryInterface(txPool, name, this.schema, this.middlewares);
+            qi = new QueryInterface(txPool, name, this.schema, this.middlewares, this.queryOptions);
             this.tableCache.set(name, qi);
         }
         return qi;
@@ -145,9 +148,14 @@ export class TurbineClient {
     logging;
     tableCache = new Map();
     middlewares = [];
+    queryOptions;
     constructor(config = {}, schema) {
         this.logging = config.logging ?? false;
         this.schema = schema;
+        this.queryOptions = {
+            defaultLimit: config.defaultLimit,
+            warnOnUnlimited: config.warnOnUnlimited,
+        };
         const poolConfig = {
             max: config.poolSize ?? 10,
             idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
@@ -187,6 +195,11 @@ export class TurbineClient {
     /**
      * Register a middleware function that runs before/after every query.
      *
+     * Middleware can inspect and log query parameters, modify results after execution,
+     * and measure timing. Note: query SQL is generated before middleware runs, so
+     * modifying params.args in middleware will NOT affect the executed SQL.
+     * To intercept queries before SQL generation, use the raw() method instead.
+     *
      * @example
      * ```ts
      * // Query timing middleware
@@ -225,7 +238,7 @@ export class TurbineClient {
     table(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = new QueryInterface(this.pool, name, this.schema, this.middlewares);
+            qi = new QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
             this.tableCache.set(name, qi);
         }
         return qi;
@@ -338,7 +351,7 @@ export class TurbineClient {
             }
             await client.query(beginSQL);
             // Create the transaction client with typed table accessors
-            const tx = new TransactionClient(client, this.schema, this.middlewares);
+            const tx = new TransactionClient(client, this.schema, this.middlewares, this.queryOptions);
             // Dynamically attach table accessors to tx
             for (const tableName of Object.keys(this.schema.tables)) {
                 const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());

package/dist/generate.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Code generator
+ * @batadata/turbine — Code generator
  *
  * Takes an IntrospectedSchema and emits TypeScript files:
  *   - types.ts     — Entity interfaces, Create/Update input types

package/dist/generate.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Code generator
+ * @batadata/turbine — Code generator
  *
  * Takes an IntrospectedSchema and emits TypeScript files:
  *   - types.ts     — Entity interfaces, Create/Update input types
@@ -9,7 +9,7 @@
  * Output goes to the specified directory (default: ./generated/turbine/).
  */
 import { writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve, relative } from 'node:path';
 import { snakeToPascal, singularize, } from './schema.js';
 /** Get the TypeScript type name for a table (singularized PascalCase) */
 function entityName(tableName) {
@@ -24,6 +24,12 @@ function escSQ(value) {
 // ---------------------------------------------------------------------------
 export function generate(options) {
     const outDir = options.outDir ?? './generated/turbine';
+    // Path traversal protection — ensure output stays within project root
+    const resolved = resolve(outDir);
+    const rel = relative(process.cwd(), resolved);
+    if (rel.startsWith('..') || resolve(rel) !== resolved) {
+        throw new Error(`Output directory must be within the project root. Got: ${outDir}`);
+    }
     mkdirSync(outDir, { recursive: true });
     const files = [];
     // Generate types.ts
@@ -46,10 +52,10 @@ export function generate(options) {
 function generatedFileHeader() {
     return [
         '/**',
-        ' * Auto-generated by turbine-orm — DO NOT EDIT',
+        ' * Auto-generated by @batadata/turbine — DO NOT EDIT',
         ' *',
         ` * Generated at: ${new Date().toISOString()}`,
-        ' * @see https://github.com/zvndev/turbine-orm',
+        ' * @see https://batadata.com/docs/turbine',
         ' */',
         '',
     ];
@@ -136,7 +142,7 @@ function generateTypes(schema) {
 function generateMetadata(schema) {
     const lines = [
         ...generatedFileHeader(),
-        "import type { SchemaMetadata } from 'turbine-orm';",
+        "import type { SchemaMetadata } from '@batadata/turbine';",
         '',
         'export const SCHEMA: SchemaMetadata = {',
         '  tables: {',
@@ -209,8 +215,8 @@ function generateIndex(schema) {
     const tableEntries = Object.values(schema.tables);
     const lines = [
         ...generatedFileHeader(),
-        "import { TurbineClient as BaseTurbineClient, QueryInterface } from 'turbine-orm';",
-        "import type { TurbineConfig } from 'turbine-orm';",
+        "import { TurbineClient as BaseTurbineClient, QueryInterface } from '@batadata/turbine';",
+        "import type { TurbineConfig } from '@batadata/turbine';",
         "import { SCHEMA } from './metadata.js';",
     ];
     // Import all entity types

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm
+ * @batadata/turbine
  *
  * Turbine TypeScript SDK — type-safe Postgres queries with nested relations
  * and pipeline batching. Feels like Prisma, runs at raw-SQL speed.

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm
+ * @batadata/turbine
  *
  * Turbine TypeScript SDK — type-safe Postgres queries with nested relations
  * and pipeline batching. Feels like Prisma, runs at raw-SQL speed.

package/dist/introspect.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Schema introspection
+ * @batadata/turbine — Schema introspection
  *
  * Connects to a live Postgres database, reads information_schema + pg_catalog,
  * and produces a SchemaMetadata object describing every table, column, relation,

package/dist/introspect.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Schema introspection
+ * @batadata/turbine — Schema introspection
  *
  * Connects to a live Postgres database, reads information_schema + pg_catalog,
  * and produces a SchemaMetadata object describing every table, column, relation,

package/dist/pipeline.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Pipeline execution
+ * @batadata/turbine — Pipeline execution
  *
  * Pipelines batch multiple independent queries into a single database round-trip.
  * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.

package/dist/pipeline.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Pipeline execution
+ * @batadata/turbine — Pipeline execution
  *
  * Pipelines batch multiple independent queries into a single database round-trip.
  * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder
+ * @batadata/turbine — Query builder
  *
  * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
  * that builds parameterized SQL and executes it through the connection pool.
@@ -35,6 +35,8 @@ export interface WhereOperator<V = unknown> {
     contains?: string;
     startsWith?: string;
     endsWith?: string;
+    /** Set to 'insensitive' to use ILIKE instead of LIKE for string comparisons */
+    mode?: 'default' | 'insensitive';
 }
 /**
  * A where value can be:
@@ -77,6 +79,8 @@ export interface FindUniqueArgs<T> {
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
     with?: WithClause;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface FindManyArgs<T> {
     where?: WhereClause<T>;
@@ -92,36 +96,54 @@ export interface FindManyArgs<T> {
     take?: number;
     /** De-duplicate results by specified fields */
     distinct?: (keyof T & string)[];
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface CreateArgs<T> {
     data: Partial<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface CreateManyArgs<T> {
     data: Partial<T>[];
     /** When true, adds ON CONFLICT DO NOTHING to skip duplicate rows */
     skipDuplicates?: boolean;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface UpdateArgs<T> {
     where: WhereClause<T>;
     data: Partial<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface UpdateManyArgs<T> {
     where: WhereClause<T>;
     data: Partial<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface DeleteArgs<T> {
     where: WhereClause<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface DeleteManyArgs<T> {
     where: WhereClause<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface UpsertArgs<T> {
     where: WhereClause<T>;
     create: Partial<T>;
     update: Partial<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface CountArgs<T> {
     where?: WhereClause<T>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 export interface GroupByArgs<T> {
     by: (keyof T & string)[];
@@ -140,6 +162,8 @@ export interface GroupByArgs<T> {
     having?: Record<string, unknown>;
     /** Order groups */
     orderBy?: Record<string, OrderDirection>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 /** Arguments for the standalone aggregate method */
 export interface AggregateArgs<T> {
@@ -154,6 +178,8 @@ export interface AggregateArgs<T> {
     _min?: Partial<Record<keyof T & string, boolean>>;
     /** Maximum value of fields */
     _max?: Partial<Record<keyof T & string, boolean>>;
+    /** Query timeout in milliseconds. Rejects with an error if exceeded. */
+    timeout?: number;
 }
 /** Result type for aggregate queries */
 export interface AggregateResult<T> {
@@ -211,6 +237,13 @@ type MiddlewareFn = (params: {
     action: string;
     args: Record<string, unknown>;
 }) => Promise<unknown>) => Promise<unknown>;
+/** Options passed from TurbineClient to QueryInterface */
+export interface QueryInterfaceOptions {
+    /** Default LIMIT applied to findMany() when no limit is specified */
+    defaultLimit?: number;
+    /** Log a warning when findMany() is called without a limit */
+    warnOnUnlimited?: boolean;
+}
 export declare class QueryInterface<T extends object> {
     private readonly pool;
     private readonly table;
@@ -219,11 +252,25 @@ export declare class QueryInterface<T extends object> {
     /** SQL template cache: cacheKey → sql string (params are always positional $1,$2,...) */
     private readonly sqlCache;
     private readonly middlewares;
-    private readonly hasNoDateColumns;
-    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[]);
+    private readonly defaultLimit?;
+    private readonly warnOnUnlimited;
+    /** Pre-computed column type lookups (avoids linear scans per query) */
+    private readonly columnPgTypeMap;
+    private readonly columnArrayTypeMap;
+    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Execute a pool.query with an optional timeout.
+     * If timeout is set, races the query against a timer and rejects on expiry.
+     */
+    private queryWithTimeout;
     /**
      * Execute a query through the middleware chain.
      * If no middlewares are registered, executes directly.
+     *
+     * Middleware can inspect and log query parameters, modify results after execution,
+     * and measure timing. Note: query SQL is generated before middleware runs, so
+     * modifying params.args in middleware will NOT affect the executed SQL.
+     * To intercept queries before SQL generation, use the raw() method instead.
      */
     private executeWithMiddleware;
     /**
@@ -305,13 +352,6 @@ export declare class QueryInterface<T extends object> {
     private buildOrderBy;
     /** Parse a flat row: convert snake_case to camelCase + Date coercion */
     private parseRow;
-    /**
-     * Fast path: parse a flat row when the table has NO date columns.
-     * Only renames snake_case -> camelCase via the pre-computed reverseMap.
-     * Skips all date coercion checks — avoids Set.has() per field per row.
-     * Used by findUnique/findMany fast paths when hasNoDateColumns is true.
-     */
-    private parseRowFast;
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
     /**
@@ -338,6 +378,7 @@ export declare class QueryInterface<T extends object> {
     /**
      * Get the Postgres type for a column (e.g. 'jsonb', 'text', '_int4').
      * Used to detect JSONB/array columns for specialized operators.
+     * Uses pre-computed Map for O(1) lookup instead of linear scan.
      */
     private getColumnPgType;
     /**
@@ -355,7 +396,10 @@ export declare class QueryInterface<T extends object> {
      * Supports: has, hasEvery, hasSome, isEmpty.
      */
     private buildArrayFilterClauses;
-    /** Get the Postgres array type for a column (used by UNNEST in createMany) */
+    /**
+     * Get the Postgres array type for a column (used by UNNEST in createMany).
+     * Uses pre-computed Map for O(1) lookup instead of linear scan.
+     */
     private getColumnArrayType;
 }
 export {};