@effect/sql-mssql 4.0.0-beta.9 → 4.0.0-beta.90

package/src/MssqlClient.ts

@@ -1,7 +1,19 @@
 /**
- * @since 1.0.0
+ * Microsoft SQL Server client implementation for Effect SQL, backed by the
+ * `tedious` driver.
+ *
+ * This module provides the `MssqlClient` service, constructors, layers, and SQL
+ * Server statement compiler. `make` creates a pooled Tedious client, checks the
+ * connection with `SELECT 1`, maps SQL Server failures to `SqlError`, and
+ * supports transactions with savepoints. The SQL Server-specific service adds
+ * typed Tedious parameters with `param`, stored procedure calls with `call`,
+ * direct or config-backed layers, and default parameter type mappings.
+ * Streaming queries are not implemented by this driver.
+ *
+ * @since 4.0.0
  */
 import * as Config from "effect/Config"
+import * as Context from "effect/Context"
 import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import { identity } from "effect/Function"
@@ -9,12 +21,23 @@ import * as Layer from "effect/Layer"
 import * as Pool from "effect/Pool"
 import * as Redacted from "effect/Redacted"
 import * as Scope from "effect/Scope"
-import * as ServiceMap from "effect/ServiceMap"
 import * as Stream from "effect/Stream"
 import * as Reactivity from "effect/unstable/reactivity/Reactivity"
 import * as Client from "effect/unstable/sql/SqlClient"
 import type { Connection } from "effect/unstable/sql/SqlConnection"
-import { SqlError } from "effect/unstable/sql/SqlError"
+import {
+  AuthenticationError,
+  AuthorizationError,
+  ConnectionError,
+  ConstraintError,
+  DeadlockError,
+  LockTimeoutError,
+  SerializationError,
+  SqlError,
+  SqlSyntaxError,
+  UniqueViolation,
+  UnknownError
+} from "effect/unstable/sql/SqlError"
 import * as Statement from "effect/unstable/sql/Statement"
 import * as Tedious from "tedious"
 import type { ConnectionOptions } from "tedious/lib/connection.ts"
@@ -28,21 +51,116 @@ const ATTR_DB_NAMESPACE = "db.namespace"
 const ATTR_SERVER_ADDRESS = "server.address"
 const ATTR_SERVER_PORT = "server.port"
 
+const mssqlNumberFromCause = (cause: unknown): number | undefined => {
+  if (typeof cause !== "object" || cause === null || !("number" in cause)) {
+    return undefined
+  }
+  const number = cause.number
+  return typeof number === "number" ? number : undefined
+}
+
+const mssqlConnectionErrorCodes = new Set([233, 10054])
+const mssqlAuthenticationErrorCodes = new Set([4060, 18452, 18456])
+const mssqlAuthorizationErrorCodes = new Set([229, 230, 262, 297, 300])
+const mssqlSyntaxErrorCodes = new Set([102, 207, 208, 2714])
+const mssqlConstraintErrorCodes = new Set([515, 547])
+
+const UNKNOWN_CONSTRAINT = "unknown"
+
+const normalizeConstraintIdentifier = (identifier: unknown): string => {
+  if (typeof identifier !== "string") {
+    return UNKNOWN_CONSTRAINT
+  }
+  const trimmed = identifier.trim()
+  return trimmed.length === 0 ? UNKNOWN_CONSTRAINT : trimmed
+}
+
+const mssqlCauseProperty = (cause: unknown, property: "constraint" | "message"): unknown => {
+  if (typeof cause !== "object" || cause === null || !(property in cause)) {
+    return undefined
+  }
+  return (cause as Record<string, unknown>)[property]
+}
+
+const mssqlUniqueViolationConstraintFromMessage = (number: 2601 | 2627, message: unknown): string => {
+  if (typeof message !== "string") {
+    return UNKNOWN_CONSTRAINT
+  }
+  const match = number === 2627 ?
+    /\bconstraint\s+'([^']*)'/i.exec(message) :
+    /\bunique index\s+'([^']*)'/i.exec(message)
+  return match === null ? UNKNOWN_CONSTRAINT : normalizeConstraintIdentifier(match[1])
+}
+
+const mssqlUniqueViolationConstraintFromCause = (number: 2601 | 2627, cause: unknown): string => {
+  const constraint = normalizeConstraintIdentifier(mssqlCauseProperty(cause, "constraint"))
+  if (constraint !== UNKNOWN_CONSTRAINT) {
+    return constraint
+  }
+  return mssqlUniqueViolationConstraintFromMessage(number, mssqlCauseProperty(cause, "message"))
+}
+
+const classifyError = (
+  cause: unknown,
+  message: string,
+  operation: string,
+  fallback: "connection" | "unknown" = "unknown"
+) => {
+  const props = { cause, message, operation }
+  const number = mssqlNumberFromCause(cause)
+  if (number !== undefined) {
+    if (mssqlConnectionErrorCodes.has(number)) {
+      return new ConnectionError(props)
+    }
+    if (mssqlAuthenticationErrorCodes.has(number)) {
+      return new AuthenticationError(props)
+    }
+    if (mssqlAuthorizationErrorCodes.has(number)) {
+      return new AuthorizationError(props)
+    }
+    if (mssqlSyntaxErrorCodes.has(number)) {
+      return new SqlSyntaxError(props)
+    }
+    if (number === 2601 || number === 2627) {
+      return new UniqueViolation({ ...props, constraint: mssqlUniqueViolationConstraintFromCause(number, cause) })
+    }
+    if (mssqlConstraintErrorCodes.has(number)) {
+      return new ConstraintError(props)
+    }
+    if (number === 1205) {
+      return new DeadlockError(props)
+    }
+    if (number === 3960) {
+      return new SerializationError(props)
+    }
+    if (number === 1222) {
+      return new LockTimeoutError(props)
+    }
+  }
+  return fallback === "connection" ? new ConnectionError(props) : new UnknownError(props)
+}
+
 /**
- * @category type ids
- * @since 1.0.0
+ * Runtime type identifier used to mark `MssqlClient` values.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: unique symbol = Symbol.for("@effect/sql-mssql/MssqlClient")
 
 /**
- * @category type ids
- * @since 1.0.0
+ * Type-level identifier used to mark `MssqlClient` values.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = typeof TypeId
 
 /**
+ * Microsoft SQL Server client service, extending `SqlClient` with typed parameter fragments and stored procedure calls.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface MssqlClient extends Client.SqlClient {
   readonly [TypeId]: TypeId
@@ -65,14 +183,23 @@ export interface MssqlClient extends Client.SqlClient {
 }
 
 /**
- * @category tags
- * @since 1.0.0
+ * Service tag for the Microsoft SQL Server client service.
+ *
+ * **When to use**
+ *
+ * Use to access or provide a Microsoft SQL Server client through the Effect
+ * context.
+ *
+ * @category services
+ * @since 4.0.0
  */
-export const MssqlClient = ServiceMap.Service<MssqlClient>("@effect/sql-mssql/MssqlClient")
+export const MssqlClient = Context.Service<MssqlClient>("@effect/sql-mssql/MssqlClient")
 
 /**
+ * Configuration for a Microsoft SQL Server client, including connection, authentication, pool, parameter type, span attribute, and query/result name transform options.
+ *
  * @category models
- * @since 1.0.0
+ * @since 4.0.0
  */
 export interface MssqlClientConfig {
   readonly domain?: string | undefined
@@ -86,6 +213,10 @@ export interface MssqlClientConfig {
   readonly username?: string | undefined
   readonly password?: Redacted.Redacted | undefined
   readonly connectTimeout?: Duration.Input | undefined
+  readonly cancelTimeout?: Duration.Input | undefined
+  readonly connectionRetryInterval?: Duration.Input | undefined
+  readonly multiSubnetFailover?: boolean | undefined
+  readonly maxRetriesOnTransientErrors?: number | undefined
 
   readonly minConnections?: number | undefined
   readonly maxConnections?: number | undefined
@@ -111,14 +242,18 @@ interface MssqlConnection extends Connection {
   readonly rollback: (name?: string) => Effect.Effect<void, SqlError>
 }
 
-const TransactionConnection = Client.TransactionConnection as unknown as ServiceMap.Service<
+const TransactionConnection = Client.TransactionConnection as unknown as (clientId: number) => Context.Service<
   readonly [conn: MssqlConnection, counter: number],
   readonly [conn: MssqlConnection, counter: number]
 >
 
+let clientIdCounter = 0
+
 /**
+ * Creates a scoped Microsoft SQL Server client backed by a connection pool, with transaction and stored procedure support. Streaming queries are not implemented.
+ *
  * @category constructors
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const make = (
   options: MssqlClientConfig
@@ -149,13 +284,21 @@ export const make = (
           port: options.port,
           database: options.database,
           trustServerCertificate: options.trustServer ?? true,
+          multiSubnetFailover: options.multiSubnetFailover,
           connectTimeout: options.connectTimeout
             ? Duration.toMillis(Duration.fromInputUnsafe(options.connectTimeout))
             : undefined,
           rowCollectionOnRequestCompletion: true,
           useColumnNames: false,
           instanceName: options.instanceName,
-          encrypt: options.encrypt ?? false
+          encrypt: options.encrypt ?? false,
+          cancelTimeout: options.cancelTimeout
+            ? Duration.toMillis(Duration.fromInputUnsafe(options.cancelTimeout))
+            : undefined,
+          connectionRetryInterval: options.connectionRetryInterval
+            ? Duration.toMillis(Duration.fromInputUnsafe(options.connectionRetryInterval))
+            : undefined,
+          maxRetriesOnTransientErrors: options.maxRetriesOnTransientErrors
         } as ConnectionOptions,
         server: options.server,
         authentication: {
@@ -174,7 +317,9 @@ export const make = (
       yield* Effect.callback<void, SqlError>((resume) => {
         conn.connect((cause) => {
           if (cause) {
-            resume(Effect.fail(new SqlError({ cause, message: "Failed to connect" })))
+            resume(
+              Effect.fail(new SqlError({ reason: classifyError(cause, "Failed to connect", "connect", "connection") }))
+            )
           } else {
             resume(Effect.void)
           }
@@ -189,7 +334,9 @@ export const make = (
         Effect.callback<any, SqlError>((resume) => {
           const req = new Tedious.Request(sql, (cause, _rowCount, result) => {
             if (cause) {
-              resume(Effect.fail(new SqlError({ cause, message: "Failed to execute statement" })))
+              resume(
+                Effect.fail(new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") }))
+              )
               return
             }
 
@@ -232,7 +379,9 @@ export const make = (
             escape(procedure.name),
             (cause, _, rows) => {
               if (cause) {
-                resume(Effect.fail(new SqlError({ cause, message: "Failed to execute statement" })))
+                resume(
+                  Effect.fail(new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") }))
+                )
               } else {
                 rows = rowsToObjects(rows)
                 if (transformRows) {
@@ -279,6 +428,9 @@ export const make = (
         executeValues(sql, params) {
           return run(sql, params, true)
         },
+        executeValuesUnprepared(sql, params) {
+          return run(sql, params, true)
+        },
         executeUnprepared(sql, params, transformRows) {
           return this.execute(sql, params, transformRows)
         },
@@ -291,7 +443,13 @@ export const make = (
         begin: Effect.callback<void, SqlError>((resume) => {
           conn.beginTransaction((cause) => {
             if (cause) {
-              resume(Effect.fail(new SqlError({ cause, message: "Failed to begin transaction" })))
+              resume(
+                Effect.fail(
+                  new SqlError({
+                    reason: classifyError(cause, "Failed to begin transaction", "beginTransaction")
+                  })
+                )
+              )
             } else {
               resume(Effect.void)
             }
@@ -300,7 +458,13 @@ export const make = (
         commit: Effect.callback<void, SqlError>((resume) => {
           conn.commitTransaction((cause) => {
             if (cause) {
-              resume(Effect.fail(new SqlError({ cause, message: "Failed to commit transaction" })))
+              resume(
+                Effect.fail(
+                  new SqlError({
+                    reason: classifyError(cause, "Failed to commit transaction", "commitTransaction")
+                  })
+                )
+              )
             } else {
               resume(Effect.void)
             }
@@ -310,7 +474,11 @@ export const make = (
           Effect.callback<void, SqlError>((resume) => {
             conn.saveTransaction((cause) => {
               if (cause) {
-                resume(Effect.fail(new SqlError({ cause, message: "Failed to create savepoint" })))
+                resume(
+                  Effect.fail(
+                    new SqlError({ reason: classifyError(cause, "Failed to create savepoint", "createSavepoint") })
+                  )
+                )
               } else {
                 resume(Effect.void)
               }
@@ -320,7 +488,13 @@ export const make = (
           Effect.callback<void, SqlError>((resume) => {
             conn.rollbackTransaction((cause) => {
               if (cause) {
-                resume(Effect.fail(new SqlError({ cause, message: "Failed to rollback transaction" })))
+                resume(
+                  Effect.fail(
+                    new SqlError({
+                      reason: classifyError(cause, "Failed to rollback transaction", "rollbackTransaction")
+                    })
+                  )
+                )
               } else {
                 resume(Effect.void)
               }
@@ -349,22 +523,29 @@ export const make = (
 
     yield* Pool.get(pool).pipe(
       Effect.tap((connection) => connection.executeUnprepared("SELECT 1", [], undefined)),
-      Effect.mapError(({ cause }) => new SqlError({ cause, message: "MssqlClient: Failed to connect" })),
+      Effect.mapError((cause) =>
+        new SqlError({ reason: classifyError(cause, "MssqlClient: Failed to connect", "connect", "connection") })
+      ),
       Effect.scoped,
       Effect.timeoutOrElse({
         duration: options.connectTimeout ?? Duration.seconds(5),
-        onTimeout: () =>
+        orElse: () =>
           Effect.fail(
             new SqlError({
-              message: "MssqlClient: Connection timeout",
-              cause: new Error("connection timeout")
+              reason: new ConnectionError({
+                message: "MssqlClient: Connection timeout",
+                cause: new Error("connection timeout"),
+                operation: "connect"
+              })
             })
           )
       })
     )
 
+    const transactionService = TransactionConnection(clientIdCounter++)
+
     const withTransaction = Client.makeWithTransaction({
-      transactionService: TransactionConnection,
+      transactionService,
       spanAttributes,
       acquireConnection: Effect.gen(function*() {
         const scope = Scope.makeUnsafe()
@@ -382,6 +563,7 @@ export const make = (
       yield* Client.make({
         acquirer: Pool.get(pool),
         compiler,
+        transactionService: transactionService as any,
         spanAttributes,
         transformRows
       }),
@@ -426,42 +608,48 @@ export const make = (
   })
 
 /**
+ * Creates a layer from a `Config`-wrapped SQL Server client configuration, providing both `MssqlClient` and `SqlClient`.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layerConfig: (
   config: Config.Wrap<MssqlClientConfig>
 ) => Layer.Layer<Client.SqlClient | MssqlClient, Config.ConfigError | SqlError> = (
   config: Config.Wrap<MssqlClientConfig>
 ): Layer.Layer<Client.SqlClient | MssqlClient, Config.ConfigError | SqlError> =>
-  Layer.effectServices(
-    Config.unwrap(config).asEffect().pipe(
+  Layer.effectContext(
+    Config.unwrap(config).pipe(
       Effect.flatMap(make),
       Effect.map((client) =>
-        ServiceMap.make(MssqlClient, client).pipe(
-          ServiceMap.add(Client.SqlClient, client)
+        Context.make(MssqlClient, client).pipe(
+          Context.add(Client.SqlClient, client)
         )
       )
     )
   ).pipe(Layer.provide(Reactivity.layer))
 
 /**
+ * Creates a layer from a concrete SQL Server client configuration, providing both `MssqlClient` and `SqlClient`.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layer = (
   config: MssqlClientConfig
 ): Layer.Layer<Client.SqlClient | MssqlClient, never | SqlError> =>
-  Layer.effectServices(
+  Layer.effectContext(
     Effect.map(make(config), (client) =>
-      ServiceMap.make(MssqlClient, client).pipe(
-        ServiceMap.add(Client.SqlClient, client)
+      Context.make(MssqlClient, client).pipe(
+        Context.add(Client.SqlClient, client)
       ))
   ).pipe(Layer.provide(Reactivity.layer))
 
 /**
+ * Creates the SQL Server statement compiler, using `@1`-style placeholders, bracket-escaped identifiers, and SQL Server `OUTPUT INSERTED` returning clauses.
+ *
  * @category compiler
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const makeCompiler = (transform?: (_: string) => string) =>
   Statement.makeCompiler<MssqlCustom>({
@@ -510,7 +698,10 @@ function numberToParamName(n: number) {
 }
 
 /**
- * @since 1.0.0
+ * Default mapping from Effect SQL primitive value kinds to Tedious SQL Server parameter data types.
+ *
+ * @category configuration
+ * @since 4.0.0
  */
 export const defaultParameterTypes: Record<Statement.PrimitiveKind, DataType> = {
   string: Tedious.TYPES.VarChar,

package/src/MssqlMigrator.ts

@@ -1,5 +1,13 @@
 /**
- * @since 1.0.0
+ * Utilities for applying Effect SQL migrations to Microsoft SQL Server.
+ *
+ * This module re-exports the shared `Migrator` loaders and error types, then
+ * provides `run` and `layer` helpers for applying ordered migrations through
+ * the current SQL Server `SqlClient`. `run` returns the applied migration IDs
+ * and names, while `layer` runs migrations during layer construction and
+ * provides no services.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -8,13 +16,15 @@ import type * as Client from "effect/unstable/sql/SqlClient"
 import type { SqlError } from "effect/unstable/sql/SqlError"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "effect/unstable/sql/Migrator"
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Runs SQL migrations using the configured `SqlClient`, returning the migrations that were applied.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const run: <R>(
   options: Migrator.MigratorOptions<R>
@@ -25,8 +35,10 @@ export const run: <R>(
 > = Migrator.make({})
 
 /**
+ * Creates a layer that runs the configured SQL migrations during layer construction.
+ *
  * @category layers
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const layer = <R>(
   options: Migrator.MigratorOptions<R>

package/src/Parameter.ts

@@ -1,25 +1,41 @@
 /**
- * @since 1.0.0
+ * Typed SQL Server stored procedure parameter metadata.
+ *
+ * This module builds {@link Parameter} values that pair a stored procedure
+ * parameter name with a Tedious `DataType`, Tedious `ParameterOptions`, and a
+ * phantom TypeScript value type. `Procedure.param` and
+ * `Procedure.outputParam` use this metadata, and `MssqlClient.call` forwards it
+ * to Tedious when registering input and output parameters.
+ *
+ * @see {@link make} for constructing parameter metadata directly.
+ *
+ * @since 4.0.0
  */
 import { identity } from "effect/Function"
 import type { DataType } from "tedious/lib/data-type.ts"
 import type { ParameterOptions } from "tedious/lib/request.ts"
 
 /**
- * @category type id
- * @since 1.0.0
+ * Runtime type identifier used to mark SQL Server stored procedure parameter metadata.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/sql-mssql/Parameter"
 
 /**
- * @category type id
- * @since 1.0.0
+ * Type-level identifier used to mark SQL Server stored procedure parameter metadata.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/sql-mssql/Parameter"
 
 /**
- * @category model
- * @since 1.0.0
+ * Metadata for a SQL Server stored procedure parameter, including its name, Tedious data type, options, and phantom value type.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Parameter<out A> {
   readonly [TypeId]: (_: never) => A
@@ -30,8 +46,10 @@ export interface Parameter<out A> {
 }
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates typed metadata for a SQL Server stored procedure parameter.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = <A>(
   name: string,