turbine-orm 0.19.2 → 0.22.0

package/dist/query/index.d.ts

@@ -10,6 +10,6 @@ export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, C
 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/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