turbine-orm 0.19.1 → 0.21.0

package/dist/query/index.d.ts

@@ -5,11 +5,11 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
-export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions } from './builder.js';
+export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './builder.js';
 export { QueryInterface } from './builder.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/query/types.d.ts

@@ -6,6 +6,13 @@
 export type OrderDirection = 'asc' | 'desc';
 /** Operator object for advanced where filtering */
 export interface WhereOperator<V = unknown> {
+    /**
+     * Explicit equality: `{ equals: value }` → `column = $n`.
+     * `{ equals: null }` → `column IS NULL`.
+     * On json/jsonb columns `equals` routes to the JSONB containment filter
+     * ({@link JsonFilter}) instead.
+     */
+    equals?: V | null;
     gt?: V;
     gte?: V;
     lt?: V;
@@ -225,8 +232,12 @@ export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWit
      */
     batchSize?: number;
 }
-export interface CreateArgs<T> {
-    data: Partial<T>;
+export interface CreateArgs<T, R extends object = {}> {
+    /**
+     * Row data. On typed clients, relation names additionally accept nested
+     * write ops ({@link NestedCreateOp}): `create` / `connect` / `connectOrCreate`.
+     */
+    data: CreateDataInput<T, R>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
@@ -267,9 +278,14 @@ export type UpdateOperatorInput<V> = {
 export type UpdateInput<T> = {
     [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
 };
-export interface UpdateArgs<T> {
+export interface UpdateArgs<T, R extends object = {}> {
     where: WhereClause<T>;
-    data: UpdateInput<T>;
+    /**
+     * Update data. On typed clients, relation names additionally accept nested
+     * write ops ({@link NestedUpdateOp}): `create` / `connect` / `connectOrCreate`
+     * / `disconnect` / `set` / `delete` / `update` / `upsert`.
+     */
+    data: UpdateDataInput<T, R>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /**
@@ -331,23 +347,57 @@ export interface UpsertArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
-export interface ConnectOrCreateOp<T> {
+/** `connectOrCreate` op: connect to the row matching `where`, or create it. */
+export interface ConnectOrCreateOp<T, TR extends object = {}> {
     where: Partial<T>;
-    create: Partial<T>;
+    create: CreateDataInput<T, TR>;
 }
-export interface NestedCreateOp<T> {
-    create?: Partial<T> | Partial<T>[];
+/** Nested write ops valid inside `create()` data for a relation field. */
+export interface NestedCreateOp<T, TR extends object = {}> {
+    create?: CreateDataInput<T, TR> | CreateDataInput<T, TR>[];
     connect?: Partial<T> | Partial<T>[];
-    connectOrCreate?: ConnectOrCreateOp<T> | ConnectOrCreateOp<T>[];
+    connectOrCreate?: ConnectOrCreateOp<T, TR> | ConnectOrCreateOp<T, TR>[];
+}
+/** A nested `update` op item: update the related row(s) matching `where`. `where` is optional for belongsTo relations (derived from the parent's FK). */
+export interface NestedUpdateOpItem<T, TR extends object = {}> {
+    where?: Partial<T>;
+    data: UpdateDataInput<T, TR>;
 }
-export interface NestedUpdateOp<T> {
-    create?: Partial<T> | Partial<T>[];
+/** A nested `upsert` op item: update the row matching `where` or create it. */
+export interface NestedUpsertOpItem<T, TR extends object = {}> {
+    where: Partial<T>;
+    create: CreateDataInput<T, TR>;
+    update: UpdateDataInput<T, TR>;
+}
+/** Nested write ops valid inside `update()` data for a relation field. */
+export interface NestedUpdateOp<T, TR extends object = {}> {
+    create?: CreateDataInput<T, TR> | CreateDataInput<T, TR>[];
     connect?: Partial<T> | Partial<T>[];
-    connectOrCreate?: ConnectOrCreateOp<T> | ConnectOrCreateOp<T>[];
+    connectOrCreate?: ConnectOrCreateOp<T, TR> | ConnectOrCreateOp<T, TR>[];
     disconnect?: Partial<T> | Partial<T>[];
     set?: Partial<T>[];
     delete?: Partial<T> | Partial<T>[];
+    update?: NestedUpdateOpItem<T, TR> | NestedUpdateOpItem<T, TR>[];
+    upsert?: NestedUpsertOpItem<T, TR> | NestedUpsertOpItem<T, TR>[];
 }
+/**
+ * `create()` data input. When the relations map `R` is known (typed clients),
+ * each relation name additionally accepts a {@link NestedCreateOp} for the
+ * relation's target entity — recursively, via the target's own relations map.
+ * When `R` is `{}` (untyped escape hatch) this collapses to plain `Partial<T>`.
+ */
+export type CreateDataInput<T, R extends object = {}> = [keyof R] extends [never] ? Partial<T> : Partial<T> & {
+    [K in keyof R]?: NestedCreateOp<RelationTarget<R[K]> & object, RelationRelations<R[K]> & object>;
+};
+/**
+ * `update()` data input. Like {@link CreateDataInput} but relation fields
+ * accept the full {@link NestedUpdateOp} surface (disconnect / set / delete /
+ * update / upsert in addition to the create-context ops), and scalar fields
+ * accept atomic {@link UpdateOperatorInput} objects.
+ */
+export type UpdateDataInput<T, R extends object = {}> = [keyof R] extends [never] ? UpdateInput<T> : UpdateInput<T> & {
+    [K in keyof R]?: NestedUpdateOp<RelationTarget<R[K]> & object, RelationRelations<R[K]> & object>;
+};
 export interface CountArgs<T> {
     where?: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */

package/dist/query/utils.js

@@ -99,6 +99,7 @@ export function sqlToPreparedName(sql) {
 }
 /** Known operator keys — used to detect operator objects vs plain values */
 export const OPERATOR_KEYS = new Set([
+    'equals',
     'gt',
     'gte',
     'lt',

package/dist/sqlite.d.ts

@@ -0,0 +1,144 @@
+/**
+ * turbine-orm/sqlite — zero-dependency SQLite engine
+ *
+ * Binds Turbine to SQLite via Node's built-in `node:sqlite` driver
+ * (`DatabaseSync`), so SQLite is a **zero new dependency** engine: the root
+ * package's runtime dependency stays exactly `pg`. This is the in-process
+ * test / edge / "try it in 10 seconds" engine — `:memory:` databases run
+ * entirely in-process with no service container.
+ *
+ * ## Driver
+ *
+ * - **Primary:** `node:sqlite` `DatabaseSync` (Node ≥ 22.5, experimental). Emits
+ *   an `ExperimentalWarning` — harmless. No native build, no extra dependency.
+ * - **Fallback:** `better-sqlite3` for Node < 22.5. Not bundled and not required;
+ *   wrap a `better-sqlite3` handle in the same `PgCompatPool` shape if needed.
+ *
+ * ## Capabilities & limits (vs PostgreSQL)
+ *
+ * - `RETURNING` + `ON CONFLICT … DO UPDATE` (SQLite ≥ 3.35) → create / upsert /
+ *   update / delete return real rows in a single statement (`resultStrategy =
+ *   'returning'`, same as Postgres).
+ * - **Single-writer:** one connection / one write transaction at a time;
+ *   concurrent writers get `SQLITE_BUSY` (treated as retryable). `journal_mode =
+ *   WAL` is enabled for file databases to allow concurrent readers.
+ * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
+ *   LISTEN/NOTIFY (`$listen` / `$notify`), RLS `sessionContext`. Advisory-lock
+ *   migration locking is unavailable — SQLite is single-writer, so migrations
+ *   serialize naturally.
+ * - **Type affinity caveats:** SQLite has no native `BOOLEAN` (0/1 integers) or
+ *   `DATE` (TEXT/INTEGER). Booleans bind as 1/0; `Date` values bind as ISO-8601
+ *   text; columns declared `TIMESTAMP`/`DATETIME`/`DATE` are coerced back to
+ *   `Date`. Integers wider than `Number.MAX_SAFE_INTEGER` come back as strings
+ *   (the same safe-int policy Turbine uses for Postgres `int8`).
+ * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
+ *   (no Unicode case folding).
+ *
+ * ## Example — `:memory:` database
+ *
+ * ```ts
+ * import { turbineSqlite } from 'turbine-orm/sqlite';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = turbineSqlite(':memory:', SCHEMA);
+ * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect, type IntrospectOptions } from './dialect.js';
+import { type SchemaMetadata, type TableMetadata } from './schema.js';
+/** pg-style query argument: a SQL string or a `{ text, values }` config object. */
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A `PgCompatPool` backed by a single `node:sqlite` `DatabaseSync` connection.
+ * SQLite is single-connection by nature (a `:memory:` database is per-handle),
+ * so `connect()` hands back a client over the **same** handle — transactions
+ * (`BEGIN`/`COMMIT`/`ROLLBACK`, `SAVEPOINT` nesting) just run on it. Queries are
+ * serialized; this is the documented single-writer model.
+ */
+export declare class SqlitePool implements PgCompatPool {
+    /** The underlying `node:sqlite` handle — exposed as an escape hatch (seed/DDL). */
+    readonly db: DatabaseSync;
+    private closed;
+    constructor(db: DatabaseSync);
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/**
+ * Map a SQLite declared column type (type affinity) to a TypeScript type.
+ * SQLite is dynamically typed; we read the declared `PRAGMA table_info` type.
+ */
+export declare function sqliteTypeToTs(declaredType: string, nullable: boolean): string;
+/**
+ * SQLite implementation of the {@link Dialect} contract. Standardizes on `"…"`
+ * identifier quoting and positional `?` placeholders, uses `json_object` /
+ * `json_group_array` for the single-query nested-relation engine (with the
+ * critical `json(...)` subresult wrap so nested objects are real JSON, not
+ * SQLite's strings-of-strings double-encoding), keeps `RETURNING` + `ON CONFLICT`
+ * (SQLite ≥ 3.35), and disables the Postgres-only capabilities (vector,
+ * LISTEN/NOTIFY, RLS, advisory locks).
+ */
+export declare const sqliteDialect: Dialect;
+/**
+ * Read a live SQLite database (an open `DatabaseSync` handle) into the same
+ * {@link SchemaMetadata} shape the Postgres catalog introspector produces.
+ * Exposed directly so callers (and tests) can introspect an in-process
+ * `:memory:` database without round-tripping through a file path.
+ */
+export declare function introspectSqliteDatabase(db: DatabaseSync, options?: {
+    include?: string[];
+    exclude?: string[];
+}): {
+    tables: Record<string, TableMetadata>;
+    enums: {};
+};
+/**
+ * Open the SQLite database named by `options.connectionString` (a file path or
+ * `':memory:'`), introspect it, and close it. Wraps
+ * {@link introspectSqliteDatabase} for the {@link DialectIntrospector} seam used
+ * by `introspect()` / `npx turbine generate`.
+ *
+ * Note: introspecting `':memory:'` opens a *fresh, empty* database (memory DBs
+ * are per-handle), so codegen should target a real file.
+ */
+export declare function introspectSqlite(options: IntrospectOptions): Promise<SchemaMetadata>;
+/** Options for {@link turbineSqlite}. Mirrors the relevant {@link TurbineConfig} fields. */
+export interface TurbineSqliteOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /**
+     * Enable WAL journal mode for file databases (better read concurrency).
+     * Ignored for `':memory:'`. Default: `true`.
+     */
+    wal?: boolean;
+    /** `PRAGMA busy_timeout` in ms — how long a writer waits on `SQLITE_BUSY`. Default: 5000. */
+    busyTimeoutMs?: number;
+    /** Enable `PRAGMA foreign_keys` enforcement. Default: `true`. */
+    foreignKeys?: boolean;
+}
+/**
+ * Create a {@link TurbineClient} bound to SQLite via `node:sqlite`.
+ *
+ * Pass a file path, `':memory:'`, or an already-open `DatabaseSync` handle (so
+ * you can seed / introspect it first and reuse the same connection). The
+ * returned client uses {@link sqliteDialect} and disables prepared-statement
+ * names (SQLite caches plans internally).
+ *
+ * @param target  A SQLite file path, `':memory:'`, or an open `DatabaseSync`.
+ * @param schema  Introspected or hand-written {@link SchemaMetadata}.
+ * @param options Optional pragmas + logging / defaultLimit / warnOnUnlimited.
+ *
+ * @example
+ * ```ts
+ * import { turbineSqlite } from 'turbine-orm/sqlite';
+ * const db = turbineSqlite(':memory:', SCHEMA);
+ * ```
+ */
+export declare function turbineSqlite(target: string | DatabaseSync, schema: SchemaMetadata, options?: TurbineSqliteOptions): TurbineClient;
+export {};
+//# sourceMappingURL=sqlite.d.ts.map