turbine-orm 0.10.0 → 0.11.0

package/dist/cjs/query/index.js

@@ -7,7 +7,9 @@
  * former monolithic `import { … } from './query.js'`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryInterface = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = void 0;
+exports.QueryInterface = exports.sqlToPreparedName = exports.quoteIdent = exports.OPERATOR_KEYS = exports.LRUCache = exports.fnv1a64Hex = exports.escSingleQuote = exports.escapeLike = exports.buildCorrelation = exports.postgresDialect = void 0;
+var dialect_js_1 = require("../dialect.js");
+Object.defineProperty(exports, "postgresDialect", { enumerable: true, get: function () { return dialect_js_1.postgresDialect; } });
 var utils_js_1 = require("./utils.js");
 Object.defineProperty(exports, "buildCorrelation", { enumerable: true, get: function () { return utils_js_1.buildCorrelation; } });
 Object.defineProperty(exports, "escapeLike", { enumerable: true, get: function () { return utils_js_1.escapeLike; } });

package/dist/client.d.ts

@@ -22,6 +22,7 @@
  * ```
  */
 import pg from 'pg';
+import type { Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
@@ -142,6 +143,8 @@ export interface TurbineConfig {
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
     sqlCache?: boolean;
+    /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
+    dialect?: Dialect;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {

package/dist/client.js

@@ -197,6 +197,7 @@ export class TurbineClient {
             warnOnUnlimited: config.warnOnUnlimited,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
+            dialect: config.dialect,
         };
         // Apply NotFoundError message redaction mode (default: safe — values are
         // stripped from messages to avoid leaking PII into error logs).

package/dist/dialect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * turbine-orm — SQL dialect contract
+ *
+ * Phase-1 seam for future database packages. The current package remains
+ * PostgreSQL-native by default, but query generation now depends on this
+ * contract for the SQL primitives that vary across MySQL and SQLite.
+ */
+import type { SchemaMetadata } from './schema.js';
+export type DialectName = 'postgresql' | 'mysql' | 'sqlite' | (string & {});
+export interface Dialect {
+    /** Dialect identifier. */
+    readonly name: DialectName;
+    /** Parameter placeholder for the Nth value, using a 1-indexed public count. */
+    paramPlaceholder(index: number): string;
+    /** Quote a SQL identifier (table, column, cursor, alias). */
+    quoteIdentifier(name: string): string;
+    /** Escape a string literal body for SQL single-quoted strings. */
+    escapeStringLiteral(value: string): string;
+    /** Empty JSON array literal used as a fallback for to-many relations. */
+    readonly emptyJsonArrayLiteral: string;
+    /** JSON null literal/fallback for to-one relations. */
+    readonly nullJsonLiteral: string;
+    /** Build a JSON object expression from output keys and SQL expressions. */
+    buildJsonObject(pairs: [key: string, expr: string][]): string;
+    /** Build a JSON array aggregation expression with a dialect-specific empty-array fallback. */
+    buildJsonArrayAgg(jsonObjectExpr: string, orderBy?: string): string;
+    /** Whether INSERT/UPDATE/DELETE support RETURNING rows. */
+    readonly supportsReturning: boolean;
+    /** Whether native ILIKE is supported. */
+    readonly supportsILike: boolean;
+    /** Build a case-insensitive LIKE equivalent. */
+    buildInsensitiveLike(column: string, paramRef: string): string;
+    /** JSON operator support level for this dialect. */
+    readonly jsonPathSupport: 'native' | 'function' | 'limited';
+    /** Build a JSON containment check. */
+    buildJsonContains(column: string, paramRef: string): string;
+    /** Build a JSON path text extraction expression. */
+    buildJsonPathExtract(column: string, pathParamRef: string): string;
+    /** Build a correlation clause across single or composite keys. */
+    buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
+    /** Type mapping hook for code generation. */
+    typeToTypeScript(dialectType: string, nullable: boolean): string;
+    /** Optional array-cast hook for bulk insert implementations. */
+    arrayType?(baseType: string): string;
+}
+export interface DialectIntrospector {
+    introspect(options: IntrospectOptions): Promise<SchemaMetadata>;
+}
+export interface IntrospectOptions {
+    connectionString: string;
+    schema?: string;
+    include?: string[];
+    exclude?: string[];
+}
+export interface DialectMigrator {
+    acquireLock(lockId: number): Promise<boolean>;
+    releaseLock(lockId: number): Promise<void>;
+}
+/** PostgreSQL implementation of the dialect contract. */
+export declare const postgresDialect: Dialect;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/dialect.js

@@ -0,0 +1,55 @@
+/**
+ * turbine-orm — SQL dialect contract
+ *
+ * Phase-1 seam for future database packages. The current package remains
+ * PostgreSQL-native by default, but query generation now depends on this
+ * contract for the SQL primitives that vary across MySQL and SQLite.
+ */
+/** PostgreSQL implementation of the dialect contract. */
+export const postgresDialect = {
+    name: 'postgresql',
+    supportsReturning: true,
+    supportsILike: true,
+    jsonPathSupport: 'native',
+    emptyJsonArrayLiteral: "'[]'::json",
+    nullJsonLiteral: 'NULL',
+    paramPlaceholder(index) {
+        return `$${index}`;
+    },
+    quoteIdentifier(name) {
+        return `"${name.replace(/"/g, '""')}"`;
+    },
+    escapeStringLiteral(value) {
+        return value.replace(/'/g, "''");
+    },
+    buildJsonObject(pairs) {
+        const args = pairs.map(([key, expr]) => `'${this.escapeStringLiteral(key)}', ${expr}`);
+        return `json_build_object(${args.join(', ')})`;
+    },
+    buildJsonArrayAgg(jsonObjectExpr, orderBy) {
+        const suffix = orderBy ? ` ${orderBy}` : '';
+        return `COALESCE(json_agg(${jsonObjectExpr}${suffix}), ${this.emptyJsonArrayLiteral})`;
+    },
+    buildInsensitiveLike(column, paramRef) {
+        return `${column} ILIKE ${paramRef}`;
+    },
+    buildJsonContains(column, paramRef) {
+        return `${column} @> ${paramRef}::jsonb`;
+    },
+    buildJsonPathExtract(column, pathParamRef) {
+        return `${column} #>> ${pathParamRef}::text[]`;
+    },
+    buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
+        const leftCols = Array.isArray(leftColumns) ? leftColumns : [leftColumns];
+        const rightCols = Array.isArray(rightColumns) ? rightColumns : [rightColumns];
+        return leftCols
+            .map((col, i) => `${leftRef}.${this.quoteIdentifier(col)} = ${rightRef}.${this.quoteIdentifier(rightCols[i])}`)
+            .join(' AND ');
+    },
+    typeToTypeScript(_dialectType, _nullable) {
+        // Existing PostgreSQL type mapping remains in schema.ts/generate.ts for now.
+        // This hook is the package boundary MySQL/SQLite implementations will fill.
+        return 'unknown';
+    },
+};
+//# sourceMappingURL=dialect.js.map

package/dist/index.d.ts

@@ -35,6 +35,8 @@
 export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, } from './client.js';
+export type { Dialect, DialectIntrospector, DialectMigrator, DialectName, IntrospectOptions as DialectIntrospectOptions, } from './dialect.js';
+export { postgresDialect } from './dialect.js';
 export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';

package/dist/index.js

@@ -35,6 +35,7 @@
 export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
+export { postgresDialect } from './dialect.js';
 // Error types
 export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation

package/dist/query/builder.d.ts

@@ -11,6 +11,7 @@
  * metadata — nothing is hardcoded.
  */
 import type pg from 'pg';
+import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
 import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause, WithResult } from './types.js';
 export interface DeferredQuery<T> {
@@ -64,6 +65,8 @@ export interface QueryInterfaceOptions {
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
     sqlCache?: boolean;
+    /** SQL dialect implementation. Defaults to PostgreSQL. */
+    dialect?: Dialect;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -77,6 +80,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly warnOnUnlimited;
     private readonly preparedStatementsEnabled;
     private readonly sqlCacheEnabled;
+    private readonly dialect;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -95,6 +99,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /** Quote an identifier through the active SQL dialect. */
+    private q;
+    /** Return the active dialect's placeholder for a 1-indexed parameter position. */
+    private p;
     /**
      * Return cache hit/miss statistics for this QueryInterface instance.
      * Useful for monitoring and benchmarking.
@@ -433,7 +441,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 8. **Parameter threading:** All user-supplied values (where filters, limit) are
      *    pushed to the shared `params` array with `$N` placeholders. No string
      *    interpolation of user data ever occurs -- all identifiers go through
-     *    `quoteIdent()` and all values are parameterized.
+     *    `this.q()` and all values are parameterized.
      *
      * ### Example output (hasMany with nested relation)
      * ```sql