@effect/sql-mssql 4.0.0-beta.7 → 4.0.0-beta.71

package/src/MssqlClient.ts

@@ -1,7 +1,43 @@
 /**
- * @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. The layers provide both `MssqlClient` and the
+ * generic `SqlClient` service, so code written against Effect SQL can run
+ * regular queries while SQL Server-specific code can add typed Tedious
+ * parameters with `param` and execute stored procedures with `call`.
+ *
+ * **Mental model**
+ *
+ * A client owns a scoped pool of Tedious connections and validates startup with
+ * `SELECT 1`. Ordinary queries borrow a pooled connection for one operation.
+ * Transactions keep one connection for their lifetime, and nested transactions
+ * are represented with SQL Server savepoints. Long-running transactions
+ * therefore reduce available pool capacity.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layer} for a concrete `MssqlClientConfig`, {@link layerConfig} when
+ * configuration should come from Effect `Config`, and {@link make} when a scoped
+ * client value is needed directly. Use `param` to override the default mapping
+ * from Effect SQL primitive values to Tedious `DataType`s, and use the
+ * `Procedure` and `Parameter` helpers when a stored procedure needs typed input
+ * parameters, output parameters, or result rows.
+ *
+ * **Gotchas**
+ *
+ * Tedious permits one active request per connection, and this client does not
+ * implement streaming queries. Statements compile to SQL Server-style `@1`
+ * parameters and bracket-escaped identifiers. Be explicit about connection pool
+ * and timeout settings for workloads with transactions. Review TLS settings:
+ * `encrypt` defaults to `false`, and `trustServer` defaults to `true` for the
+ * Tedious `trustServerCertificate` option unless overridden.
+ *
+ * @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 +45,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 +75,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 +207,18 @@ export interface MssqlClient extends Client.SqlClient {
 }
 
 /**
+ * Context tag used to access the `MssqlClient` service.
+ *
  * @category tags
- * @since 1.0.0
+ * @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
@@ -111,14 +257,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
@@ -174,7 +324,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 +341,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 +386,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) {
@@ -291,7 +447,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 +462,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 +478,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 +492,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 +527,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 +567,7 @@ export const make = (
       yield* Client.make({
         acquirer: Pool.get(pool),
         compiler,
+        transactionService: transactionService as any,
         spanAttributes,
         transformRows
       }),
@@ -426,42 +612,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 +702,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,26 @@
 /**
- * @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`. It is typically used at application
+ * startup, during deployment, in integration tests that provision temporary SQL
+ * Server databases, or in layer graphs that need the database schema to be
+ * current before dependent services are acquired.
+ *
+ * Applied migrations are stored in `effect_sql_migrations` by default and use
+ * the shared `<id>_<name>` loader convention. Only migrations with ids greater
+ * than the latest recorded id are run, so avoid inserting older migration ids
+ * after a later migration has reached production. SQL Server migrations run
+ * inside the shared migrator transaction and this adapter does not add a
+ * dialect-specific table lock, so coordinate concurrent startup runners and
+ * write T-SQL that is valid inside an explicit transaction. Remember that `GO`
+ * is a client-side batch separator rather than a T-SQL statement, and split
+ * migrations when SQL Server requires an object definition such as `CREATE
+ * VIEW`, `CREATE PROCEDURE`, or `CREATE TRIGGER` to start its own batch. This
+ * adapter also does not emit SQL Server schema dumps for `schemaDirectory`.
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
@@ -8,13 +29,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 +48,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,66 @@
 /**
- * @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.
+ *
+ * **Mental model**
+ *
+ * A `Parameter<A>` describes how Tedious should bind a value; it is not the
+ * value itself. The `A` type guides the record accepted by
+ * `Procedure.compile`, while Tedious validates and encodes the runtime value
+ * when the request is executed.
+ *
+ * **Common tasks**
+ *
+ * - Annotate inputs that need explicit SQL Server data types, sizes, precision,
+ *   scale, or table-valued parameter options.
+ * - Define output parameters so `MssqlClient.call` can collect returned values
+ *   by name.
+ * - Reuse the same metadata shape from direct `make` calls and the `Procedure`
+ *   builders.
+ *
+ * **Gotchas**
+ *
+ * Names should match the stored procedure parameter name expected by Tedious,
+ * normally without a leading `@`. Table-valued parameter values must use
+ * Tedious' table shape with `name`, optional `schema`, `columns`, and `rows`.
+ * Output parameters are registered without an initial value, so input-output
+ * parameters need explicit modeling instead of assuming compiled input values
+ * are reused.
+ *
+ * @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"
 
 /**
+ * Runtime type identifier used to mark SQL Server stored procedure parameter metadata.
+ *
  * @category type id
- * @since 1.0.0
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/sql-mssql/Parameter"
 
 /**
+ * Type-level identifier used to mark SQL Server stored procedure parameter metadata.
+ *
  * @category type id
- * @since 1.0.0
+ * @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 +71,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,