turbine-orm 0.19.2 → 0.22.0

package/dist/mssql.d.ts

@@ -0,0 +1,233 @@
+/**
+ * turbine-orm/mssql — Microsoft SQL Server engine (driver-injected, optional peer)
+ *
+ * Binds Turbine to SQL Server 2016+ via the `mssql` driver (which wraps
+ * `tedious`). `mssql` is **not** a root dependency — it is an **optional peer**:
+ * `npm i turbine-orm` pulls nothing extra, and only consumers who
+ * `import 'turbine-orm/mssql'` install `mssql` themselves. The factory loads it
+ * through a dynamic `import('mssql')` so importing this module never crashes when
+ * `mssql` is absent for a consumer who does not use it. Turbine's root runtime
+ * dependency stays exactly `pg`.
+ *
+ * ## The three hard SQL Server realities this engine solves
+ *
+ *  1. **No `RETURNING`.** `INSERT`/`UPDATE`/`DELETE` cannot trail a `RETURNING`
+ *     clause; SQL Server returns affected rows via `OUTPUT INSERTED.*` /
+ *     `OUTPUT DELETED.*` injected MID-statement (between the column list and
+ *     `VALUES`, or between `SET …` and `WHERE …`). `mssqlDialect.resultStrategy =
+ *     'output'`: the statement returns its own rows in ONE round-trip (executed
+ *     exactly like the PostgreSQL `'returning'` path). Upsert becomes a
+ *     `MERGE … WHEN MATCHED … WHEN NOT MATCHED … OUTPUT INSERTED.* ;` (a MERGE
+ *     must end with `;`). This is the first shipped engine to exercise the
+ *     Phase-0 `'output'` result strategy.
+ *  2. **No `json_agg`.** SQL Server has no JSON aggregate function; the idiomatic
+ *     single-query nested-relation path is `(SELECT child cols … FOR JSON PATH)`,
+ *     whose object shape is expressed by the child SELECT's column ALIASES rather
+ *     than an explicit `JSON_OBJECT(...)`. That does NOT map onto
+ *     `buildJsonObject`/`buildJsonArrayAgg`, so `mssqlDialect` defines the
+ *     additive `Dialect.buildRelationSubquery` override (the sanctioned Phase-3
+ *     seam extension) and owns the whole correlated subquery. To-many wraps
+ *     `ISNULL((… FOR JSON PATH), '[]')` (FOR JSON over zero rows is NULL, not
+ *     `[]`); to-one adds `, WITHOUT_ARRAY_WRAPPER` and lets NULL be the no-row
+ *     value. Nested relations are embedded with `JSON_QUERY(...)` so they stay
+ *     real JSON instead of being escaped as a string. `INCLUDE_NULL_VALUES`
+ *     keeps NULL columns present (matching PostgreSQL `json_build_object`).
+ *  3. **No `LIMIT`.** Paging is `ORDER BY … OFFSET n ROWS FETCH NEXT m ROWS ONLY`,
+ *     which requires an ORDER BY — a stable `ORDER BY (SELECT NULL)` is injected
+ *     when the query has none (`Dialect.buildLimitOffset`).
+ *
+ * ## Named `@pN` placeholders (no positional `?`)
+ *
+ * `mssqlDialect.paramPlaceholder = (i) => '@p' + i`. The driver shim binds via
+ * `request.input('p' + i, value)`, so binding is by NAME and independent of where
+ * each placeholder lands in the SQL text — exactly the guarantee PostgreSQL's
+ * numbered `$N` gives. (SQL Server is naturally named-param friendly, sidestepping
+ * the positional-`?` mis-bind bug the SQLite/MySQL phases hit.)
+ *
+ * ## Capabilities & limits (vs PostgreSQL)
+ *
+ * - **Single query nested relations preserved** via `FOR JSON PATH` (SQL Server
+ *   2016+). Ordered/limited to-many uses `ORDER BY … OFFSET/FETCH` inside the FOR
+ *   JSON subquery (no inner-subquery rewrite needed — FOR JSON aggregates AFTER
+ *   the row selection).
+ * - **Result strategy `'output'`:** create/update/delete/upsert return their rows
+ *   from the same statement. `createMany` returns the inserted rows via
+ *   `OUTPUT INSERTED.*` on the multi-row VALUES insert (≤ 1000 rows / 2100 params
+ *   per statement — exceeding either throws a clear `ValidationError`; chunk
+ *   yourself or use single `create`s).
+ * - **MERGE concurrency caveat:** `MERGE` is the upsert primitive; under high
+ *   concurrency a `MERGE` can still race (it is NOT a substitute for a unique
+ *   constraint). Keep the conflict target backed by a real `UNIQUE`/`PK` index,
+ *   and rely on the typed `UniqueConstraintError` (2627/2601 → E008) for the
+ *   loser of a race.
+ * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
+ *   LISTEN/NOTIFY (`$listen`/`$notify`), RLS `sessionContext` (sp_set_session_context
+ *   exists but is connection-scoped, not transaction-local, so it is not wired —
+ *   throws rather than silently leaking context across pooled connections).
+ * - **Advisory-lock migration locking** is available in principle via
+ *   `sp_getapplock`/`sp_releaseapplock` (`supportsAdvisoryLock = true`); the
+ *   migrate CLI is still PostgreSQL-only, so this flag documents intent for a
+ *   future adapter.
+ * - **Case-insensitive matching** uses `LOWER(col) LIKE LOWER(ref)` — deterministic
+ *   regardless of the column's collation (note this can defeat an index unless a
+ *   computed/persisted `LOWER()` index exists).
+ * - **bignum:** the shim applies the same safe-int policy Turbine uses for Postgres
+ *   `int8` (number when it fits in 2^53, decimal string otherwise) WITHOUT mutating
+ *   any global driver state. `DECIMAL`/`NUMERIC`/`MONEY` come back as strings;
+ *   `BIT` binds/returns booleans.
+ * - **`DISTINCT ON`** is PostgreSQL-only and is not translated — avoid `distinct`
+ *   on SQL Server.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { turbineMssql } from 'turbine-orm/mssql';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+ * const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+ * await db.disconnect();
+ * ```
+ */
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type Dialect, type IntrospectOptions } from './dialect.js';
+import { type SchemaMetadata } from './schema.js';
+interface MssqlRequest {
+    input(name: string, value: unknown): MssqlRequest;
+    query<R = Record<string, unknown>>(text: string): Promise<MssqlQueryResult<R>>;
+    batch<R = Record<string, unknown>>(text: string): Promise<MssqlQueryResult<R>>;
+}
+/** Per-column metadata `mssql` attaches to a recordset (`recordset.columns`). */
+interface MssqlColumnMeta {
+    [name: string]: {
+        type?: {
+            name?: string;
+            declaration?: string;
+        };
+    } | undefined;
+}
+interface MssqlQueryResult<R = Record<string, unknown>> {
+    recordset?: R[] & {
+        columns?: MssqlColumnMeta;
+    };
+    recordsets?: R[][];
+    rowsAffected?: number[];
+}
+interface MssqlTransaction {
+    begin(isolationLevel?: number): Promise<unknown>;
+    commit(): Promise<unknown>;
+    rollback(): Promise<unknown>;
+}
+interface MssqlConnectionPool {
+    connect(): Promise<MssqlConnectionPool>;
+    request(): MssqlRequest;
+    close(): Promise<unknown>;
+    readonly connected?: boolean;
+}
+/** The subset of the `mssql` module namespace the shim constructs. */
+interface MssqlModule {
+    connect(config: any): Promise<MssqlConnectionPool>;
+    ConnectionPool: new (config: any) => MssqlConnectionPool;
+    Request: new (parent: MssqlConnectionPool | MssqlTransaction) => MssqlRequest;
+    Transaction: new (pool: MssqlConnectionPool) => MssqlTransaction;
+    ISOLATION_LEVEL: Record<string, number>;
+}
+/** pg-style query argument: a SQL string or a `{ text, values }` config object. */
+type QueryArg = string | {
+    name?: string;
+    text: string;
+    values?: unknown[];
+};
+/**
+ * A {@link PgCompatPool} backed by an `mssql` ConnectionPool. Non-transaction
+ * queries run on a fresh pooled `Request`; `connect()` returns a
+ * {@link MssqlTxClient} that drives a single transaction through the mssql
+ * `Transaction` API so `BEGIN`/`COMMIT`/`ROLLBACK`/savepoints all run on the same
+ * physical connection.
+ */
+export declare class MssqlPool implements PgCompatPool {
+    /** The underlying `mssql` ConnectionPool — exposed as an escape hatch (seed / DDL / advanced ops). */
+    readonly pool: MssqlConnectionPool;
+    private readonly sqlNS;
+    private closed;
+    constructor(pool: MssqlConnectionPool, sqlNS: MssqlModule);
+    query(text: QueryArg, values?: unknown[]): Promise<any>;
+    connect(): Promise<PgCompatPoolClient>;
+    end(): Promise<void>;
+}
+/**
+ * Map a SQL Server column type to a TypeScript type. `dialectType` is the
+ * `INFORMATION_SCHEMA.COLUMNS.DATA_TYPE` (lowercase, e.g. `bigint`, `nvarchar`,
+ * `datetime2`, `bit`, `uniqueidentifier`).
+ */
+export declare function mssqlTypeToTs(dialectType: string, nullable: boolean): string;
+/**
+ * SQL Server 2016+ implementation of the {@link Dialect} contract. Bracket
+ * identifier quoting (`[…]`), named `@pN` placeholders, the `FOR JSON PATH`
+ * nested-relation override (no `json_agg`), no `RETURNING`
+ * (`resultStrategy = 'output'` via `OUTPUT INSERTED.*` / `MERGE`), `OFFSET/FETCH`
+ * paging, and the Postgres-only capabilities disabled (vector / LISTEN-NOTIFY /
+ * RLS).
+ */
+export declare const mssqlDialect: Dialect;
+/** Async executor that returns plain row objects for a parameterized (`@pN`) query. */
+export type MssqlRowExecutor = (sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+/**
+ * Introspect a SQL Server database into the same {@link SchemaMetadata} shape the
+ * Postgres catalog introspector produces, using a caller-supplied query executor
+ * (so tests can dogfood an already-open `mssql` pool/connection). Reads
+ * `INFORMATION_SCHEMA.*` plus `sys.identity_columns` / `sys.foreign_keys` /
+ * `sys.indexes`.
+ *
+ * @param exec   Runs a parameterized (`@p1`, `@p2`, …) query and returns rows.
+ * @param schema The SQL Server schema to introspect (default `dbo`).
+ */
+export declare function introspectMssqlWith(exec: MssqlRowExecutor, schema?: string, options?: {
+    include?: string[];
+    exclude?: string[];
+}): Promise<SchemaMetadata>;
+/**
+ * Open a short-lived `mssql` connection from `options.connectionString`, introspect
+ * the database (schema = `options.schema` or `dbo`), and close it. Wraps
+ * {@link introspectMssqlWith} for the {@link DialectIntrospector} seam used by
+ * `introspect()` / `npx turbine generate`.
+ */
+export declare function introspectMssql(options: IntrospectOptions): Promise<SchemaMetadata>;
+interface MssqlConnectionConfig {
+    server?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    options?: {
+        encrypt?: boolean;
+        trustServerCertificate?: boolean;
+    };
+}
+/** Options for {@link turbineMssql}. Mirrors the relevant {@link TurbineConfig} fields. */
+export interface TurbineMssqlOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+    /** SQL Server schema for introspection / DDL (default `dbo`). */
+    schema?: string;
+}
+/**
+ * Create a {@link TurbineClient} bound to SQL Server 2016+ via `mssql`.
+ *
+ * Pass one of:
+ *  - a connection string (`'mssql://sa:pass@host:1433/db'`),
+ *  - an `mssql` config object (`{ server, user, password, database, options }`),
+ *  - an existing `MssqlPool` (injection — you own its lifecycle, `disconnect()` is
+ *    a no-op).
+ *
+ * When Turbine builds the pool (string/config), it probes
+ * `SERVERPROPERTY('ProductMajorVersion')` to reject SQL Server < 2016, and
+ * `disconnect()` closes the pool it created.
+ *
+ * @example
+ * ```ts
+ * import { turbineMssql } from 'turbine-orm/mssql';
+ * const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+ * ```
+ */
+export declare function turbineMssql(target: string | MssqlConnectionConfig | MssqlPool, schema: SchemaMetadata, options?: TurbineMssqlOptions): Promise<TurbineClient>;
+export {};
+//# sourceMappingURL=mssql.d.ts.map