@effect/sql-mssql 4.0.0-beta.8 → 4.0.0-beta.81

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
@@ -111,14 +238,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 +305,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 +322,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 +367,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 +428,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 +443,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 +459,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 +473,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 +508,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 +548,7 @@ export const make = (
       yield* Client.make({
         acquirer: Pool.get(pool),
         compiler,
+        transactionService: transactionService as any,
         spanAttributes,
         transformRows
       }),
@@ -426,42 +593,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 +683,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,

package/src/Procedure.ts

@@ -1,5 +1,13 @@
 /**
- * @since 1.0.0
+ * Typed metadata builders for Microsoft SQL Server stored procedure calls.
+ *
+ * This module defines the `Procedure` values consumed by `MssqlClient.call`.
+ * `make` starts a procedure definition, `param` and `outputParam` add typed
+ * Tedious parameter metadata, `withRows` sets the expected row type, and
+ * `compile` binds input values before execution. The module also defines the
+ * typed result shape for output parameters and returned rows.
+ *
+ * @since 4.0.0
  */
 import { identity } from "effect/Function"
 import type { Pipeable } from "effect/Pipeable"
@@ -11,20 +19,26 @@ import type { ParameterOptions } from "tedious/lib/request.ts"
 import * as Parameter from "./Parameter.ts"
 
 /**
- * @category type id
- * @since 1.0.0
+ * Runtime type identifier used to mark SQL Server stored procedure definitions.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/sql-mssql/Procedure"
 
 /**
- * @category type id
- * @since 1.0.0
+ * Type-level identifier used to mark SQL Server stored procedure definitions.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/sql-mssql/Procedure"
 
 /**
- * @category model
- * @since 1.0.0
+ * Pipeable definition of a SQL Server stored procedure, tracking its input parameters, output parameters, and result row type.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Procedure<
   I extends Record<string, Parameter.Parameter<any>>,
@@ -41,8 +55,10 @@ export interface Procedure<
 }
 
 /**
- * @category model
- * @since 1.0.0
+ * Stored procedure definition with concrete input values bound for execution.
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface ProcedureWithValues<
   I extends Record<string, Parameter.Parameter<any>>,
@@ -53,11 +69,16 @@ export interface ProcedureWithValues<
 }
 
 /**
- * @since 1.0.0
+ * Namespace containing type helpers and result types for SQL Server stored procedures.
+ *
+ * @since 4.0.0
  */
-export namespace Procedure {
+export declare namespace Procedure {
   /**
-   * @since 1.0.0
+   * Maps a record of `Parameter` metadata to the corresponding record of parameter value types.
+   *
+   * @category utility types
+   * @since 4.0.0
    */
   export type ParametersRecord<
     A extends Record<string, Parameter.Parameter<any>>
@@ -69,8 +90,10 @@ export namespace Procedure {
     & {}
 
   /**
-   * @category model
-   * @since 1.0.0
+   * Result of a SQL Server stored procedure call, containing typed output parameter values and returned rows.
+   *
+   * @category models
+   * @since 4.0.0
    */
   export interface Result<
     O extends Record<string, Parameter.Parameter<any>>,
@@ -94,8 +117,10 @@ const procedureProto = {
 }
 
 /**
- * @category constructor
- * @since 1.0.0
+ * Creates an empty SQL Server stored procedure definition for the given procedure name.
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = (name: string): Procedure<{}, {}> => {
   const procedure = Object.create(procedureProto)
@@ -106,8 +131,10 @@ export const make = (name: string): Procedure<{}, {}> => {
 }
 
 /**
- * @category combinator
- * @since 1.0.0
+ * Adds a typed input parameter to a SQL Server stored procedure definition.
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const param = <A>() =>
 <N extends string, T extends DataType>(
@@ -129,8 +156,10 @@ export const param = <A>() =>
 })
 
 /**
- * @category combinator
- * @since 1.0.0
+ * Adds a typed output parameter to a SQL Server stored procedure definition.
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const outputParam = <A>() =>
 <N extends string, T extends DataType>(
@@ -152,8 +181,10 @@ export const outputParam = <A>() =>
 })
 
 /**
- * @category combinator
- * @since 1.0.0
+ * Sets the expected row type for a SQL Server stored procedure definition.
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const withRows = <A extends object = Row>() =>
 <
@@ -164,8 +195,10 @@ export const withRows = <A extends object = Row>() =>
 ): Procedure<I, O, A> => self as any
 
 /**
- * @category combinator
- * @since 1.0.0
+ * Binds input values to a SQL Server stored procedure definition, producing a value that can be executed with `MssqlClient.call`.
+ *
+ * @category combinators
+ * @since 4.0.0
  */
 export const compile = <
   I extends Record<string, Parameter.Parameter<any>>,