@voltro/sql-mssql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { CdcConfig } from '@voltro/database';
+import { ChangeEvent } from '@voltro/database';
+import { ChangeStrategy } from '@voltro/database';
+import { ConfigError } from 'effect';
+import { ConnectionConfig } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { DialectReplicationAdapter } from '@voltro/database';
+import { Effect } from 'effect';
+import { EventEmitter } from 'node:events';
+import { Layer } from 'effect';
+import { ManagedRuntime } from 'effect';
+import { MssqlClient } from '@effect/sql-mssql';
+import { Predicate } from '@voltro/database';
+import { QueryDescriptor } from '@voltro/database';
+import { QueryNamespace } from '@voltro/database';
+import { RawSqlFragment } from '@voltro/database/sql';
+import { RetryDecision } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { SqlClient } from '@effect/sql';
+import { SqlClient as SqlClient_2 } from '@effect/sql/SqlClient';
+import { SqlDialect } from '@voltro/database';
+import { SqlError } from '@effect/sql';
+import { TableLike } from '@voltro/database';
+import { TransactionConnection } from '@effect/sql/SqlClient';
+
+export declare const CDC_OFFSETS_TABLE = "_voltro_cdc_offsets";
+
+export declare interface ChangeTrackingCdcHandle {
+    readonly stop: () => Promise<void>;
+    /** The last CT version the reader has advanced past (for a final checkpoint). */
+    readonly currentVersion: () => string | null;
+}
+
+export declare interface ChangeTrackingCdcOptions {
+    readonly run: MssqlEffectRunner;
+    /** Unqualified table names to tail. Each must have CT enabled (the
+     *  reader enables them at start via `ensureChangeTracking`). */
+    readonly tables: ReadonlyArray<string>;
+    /** Poll cadence. Default 500ms. */
+    readonly pollIntervalMs?: number;
+    /** Resume cursor (decimal string of the CT version). Omit / null →
+     *  start at the CURRENT version (only future changes). */
+    readonly startVersion?: string | null;
+    readonly onChange: (event: ChangeEvent) => void;
+    /** Called with the CT version after each processed poll (checkpointing). */
+    readonly onVersion?: (version: string) => void;
+    readonly onError?: (err: unknown) => void;
+    /** Called when the reader had to skip forward because the persisted
+     *  cursor fell below the CT retention floor (auto-cleanup outran us).
+     *  The caller should treat live state as possibly-stale + re-query. */
+    readonly onResync?: () => void;
+}
+
+/**
+ * Parse a `ConnectionConfig` into the mssql-specific shape.
+ *
+ * Resolution order:
+ *   1. `url` — `mssql://user:pw@server:port/database` (also `sqlserver://`)
+ *   2. Discrete `host`/`port`/`username`/`password`/`database`
+ *   3. Defaults: server `localhost`, port 1433
+ *
+ * Sane defaults for dev: `trustServer: true` so the docker SQL Server
+ * Developer edition's self-signed cert doesn't trip TLS. Production
+ * setups override via env.
+ */
+export declare const connectionFromConfig: (config: ConnectionConfig) => MssqlConnection;
+
+/**
+ * Enable Change Tracking on `tables` (idempotent) + confirm the database
+ * itself has CT on. Called by the store at CDC start. Enabling per-table
+ * CT is a cheap `ALTER TABLE … ENABLE CHANGE_TRACKING`; re-enabling an
+ * already-tracked table is a no-op guarded by `sys.change_tracking_tables`.
+ */
+export declare const ensureChangeTracking: (run: MssqlEffectRunner, tables: ReadonlyArray<string>) => Promise<void>;
+
+export declare const makeMssqlSqlLayer: (options: MssqlConnection) => ReturnType<typeof MssqlClient.layerConfig>;
+
+export declare const makeMssqlSqlLayerFromConfig: (config: ConnectionConfig) => ReturnType<typeof MssqlClient.layerConfig>;
+
+export declare const makeMssqlStore: (options: MssqlStoreOptions) => Promise<MssqlStore>;
+
+declare interface MssqlAdapterFriend {
+    readonly runEffect: <A, E>(effect: Effect.Effect<A, E, SqlClient_2>) => Promise<A>;
+}
+
+export { MssqlClient }
+
+export declare interface MssqlConnection {
+    readonly server: string;
+    readonly port?: number;
+    readonly database?: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly encrypt?: boolean;
+    readonly trustServer?: boolean;
+    readonly maxConnections?: number;
+}
+
+export declare const mssqlDialect: SqlDialect;
+
+/** Effect runner bound to the store's managed runtime + connection pool
+ *  (the same `__mssqlReplicationFriend.runEffect` seam the replication
+ *  adapter uses) — so the CT reader needs no second pool. */
+declare type MssqlEffectRunner = <A, E>(effect: Effect.Effect<A, E, SqlClient_2>) => Promise<A>;
+
+export declare const mssqlReplicationAdapter: () => DialectReplicationAdapter;
+
+export declare const mssqlRetryFilter: (err: unknown) => RetryDecision;
+
+export declare class MssqlStore implements DataStore {
+    private readonly sql;
+    private readonly runtime;
+    private readonly changeStrategy;
+    private readonly namespace;
+    private readonly emitter;
+    private inflightTxns;
+    private cdcHandle;
+    private cdcCheckpointTimer;
+    private cdcPendingVersion;
+    private cdcReplicaId;
+    private cdcStreamName;
+    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | MssqlClient.MssqlClient, never>, changeStrategy?: ChangeStrategy, namespace?: QueryNamespace, sharedEmitter?: EventEmitter);
+    /** True when the write path emits its own deltas inline. In 'cdc' mode
+     *  the CT reader is the sole emitter, so the write path stays silent. */
+    private get inlineEmit();
+    /**
+     * Bind a per-request tenant namespace (a SCHEMA), returning a view that
+     * qualifies every table reference to `<schema>.<table>`. Shares this
+     * store's pool + emitter + CDC. The schema must already exist — see the
+     * migrator's namespace fan-out.
+     */
+    withNamespace(namespace: string | null): DataStore;
+    /** Qualify a table to this view's namespace (no-op when unset). */
+    private nsT;
+    /**
+     * Friend-handle the mssql replication adapter reads via a structural
+     * check on `DataStore` (declared in `./replicationAdapter.ts`). The
+     * adapter needs raw SQL access against THIS store's managed runtime
+     * to query `sys.dm_tran_database_transactions` /
+     * `sys.dm_hadr_database_replica_states` — without a friend handle
+     * the adapter would need its own connection pool + config, doubling
+     * the deployment cost.
+     *
+     * The handle stays on the store class as a public-but-prefixed
+     * property so the type cast in `adapterFriend(store)` resolves
+     * without exporting the runtime to the wider API surface.
+     */
+    readonly __mssqlReplicationFriend: MssqlAdapterFriend;
+    private executeQuery;
+    private executeInsert;
+    private executeUpdate;
+    private executeInsertMany;
+    private executePatchJson;
+    private executeDelete;
+    private routeEvent;
+    query(d: QueryDescriptor): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    raw<T extends object = Row>(fragment: RawSqlFragment, _opts?: {
+        dependsOn?: ReadonlyArray<string>;
+    }): Promise<ReadonlyArray<T>>;
+    private runWithEager;
+    /* Excluded from this release type: getInternalRunWithEager */
+    insert(t: string, r: Row): Promise<Readonly<Record<string, unknown>>>;
+    insertMany(t: string, rows: ReadonlyArray<Row>): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    patchJson(t: string, pk: string, path: string, value: unknown): Promise<Readonly<Record<string, unknown>> | null>;
+    update(t: string, pk: string, p: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>> | null>;
+    delete(t: string, pk: string): Promise<boolean>;
+    updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
+        where: Predicate;
+    }): Promise<number>;
+    deleteMany(table: string, options: {
+        where: Predicate;
+    }): Promise<number>;
+    upsert(t: string, r: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Readonly<Record<string, unknown>>>;
+    insertIgnore(t: string, r: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Readonly<Record<string, unknown>>>;
+    private upsertPatch;
+    private executeUpsert;
+    /**
+     * Single-statement native MERGE upsert. Builds a parameterised
+     * `MERGE <t> WITH (HOLDLOCK) AS tgt USING (VALUES (…)) AS src (cols)
+     *  ON tgt.<ck> = src.<ck>
+     *  WHEN MATCHED THEN UPDATE SET tgt.<c> = src.<c>
+     *  WHEN NOT MATCHED THEN INSERT (cols) VALUES (src.cols)
+     *  OUTPUT $action, INSERTED.*;`
+     * — every value binds as a parameter (no interpolation), `$action`
+     * distinguishes the insert vs update branch so the change event is
+     * emitted with the right `op`, and `INSERTED.*` returns the post-image
+     * in the SAME round-trip. Only reached for the column-list / default
+     * `update` form; the function form can't express its patch in a MERGE.
+     */
+    private mergeUpsert;
+    private executeInsertIgnore;
+    private findByConflict;
+    /* Excluded from this release type: emitChange */
+    /* Excluded from this release type: startCdcConsumer */
+    /* Excluded from this release type: readCdcOffset */
+    /* Excluded from this release type: flushCdcOffset */
+    /* Excluded from this release type: getInternalExecuteQuery */
+    /* Excluded from this release type: getInternalExecuteInsert */
+    /* Excluded from this release type: getInternalExecuteInsertMany */
+    /* Excluded from this release type: getInternalExecutePatchJson */
+    /* Excluded from this release type: getInternalExecuteUpdate */
+    /* Excluded from this release type: getInternalExecuteDelete */
+    /* Excluded from this release type: getInternalExecuteUpsert */
+    /* Excluded from this release type: getInternalExecuteInsertIgnore */
+    transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
+    onChange(listener: (event: ChangeEvent) => void): () => void;
+    /** 'fleet' under Change Tracking CDC (every replica gets the full
+     *  stream); 'local' under inline emission. See DataStore.changeScope. */
+    get changeScope(): 'local' | 'fleet';
+    /** Cross-instance reactivity seam — emit an externally-sourced event to
+     *  local subscribers without re-persisting. The Change Tracking CDC
+     *  consumer and `@voltro/plugin-broadcast` route through here. See
+     *  `DataStore.injectExternalChange`. */
+    injectExternalChange(event: ChangeEvent): void;
+    run<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+    close(gracePeriodMs?: number): Promise<void>;
+    /** Liveness probe — `SELECT 1`. Rejects if the pool can't answer. */
+    ping(): Promise<void>;
+}
+
+export declare interface MssqlStoreOptions {
+    readonly sqlLayer: Layer.Layer<SqlClient.SqlClient | MssqlClient.MssqlClient, ConfigError.ConfigError | SqlError.SqlError, never>;
+    readonly tracerLayer?: Layer.Layer<never, never, never>;
+    /** `'inline'` (default): the writing instance emits its own deltas.
+     *  `'cdc'`: a SQL Server Change Tracking reader is the sole emitter, so
+     *  a write on any replica surfaces on every replica's `onChange`. */
+    readonly changeStrategy?: ChangeStrategy;
+    /** Change Tracking CDC wiring — required when `changeStrategy: 'cdc'`.
+     *  `serverId` is unused by mssql (CT has no per-reader identity like a
+     *  binlog `server_id`); `replicaId` keys the per-pod resume offset and
+     *  `includeTables` scopes which tables the reader tails. */
+    readonly cdcConfig?: CdcConfig;
+}
+
+/**
+ * Start the Change Tracking reader. Resolves once the initial cursor is
+ * resolved + the first poll is armed (so the caller can guarantee
+ * "reader attached before subscriptions"). The returned handle stops it.
+ */
+export declare const startChangeTrackingCdc: (opts: ChangeTrackingCdcOptions) => Promise<ChangeTrackingCdcHandle>;
+
+declare type TxnContext = Context.Tag.Service<typeof TransactionConnection>;
+
+export declare const _voltroMssqlCdcOffsetsTable: TableLike;
+
+export { }