@effect/sql-mssql 4.0.0-beta.66 → 4.0.0-beta.68

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/dist/MssqlClient.d.ts +60 -13
  2. package/dist/MssqlClient.d.ts.map +1 -1
  3. package/dist/MssqlClient.js +50 -9
  4. package/dist/MssqlClient.js.map +1 -1
  5. package/dist/MssqlMigrator.d.ts +30 -5
  6. package/dist/MssqlMigrator.d.ts.map +1 -1
  7. package/dist/MssqlMigrator.js +8 -4
  8. package/dist/MssqlMigrator.js.map +1 -1
  9. package/dist/Parameter.d.ts +14 -6
  10. package/dist/Parameter.d.ts.map +1 -1
  11. package/dist/Parameter.js +28 -4
  12. package/dist/Parameter.js.map +1 -1
  13. package/dist/Procedure.d.ts +41 -16
  14. package/dist/Procedure.d.ts.map +1 -1
  15. package/dist/Procedure.js +37 -8
  16. package/dist/Procedure.js.map +1 -1
  17. package/dist/index.d.ts +90 -6
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +90 -6
  20. package/dist/index.js.map +1 -1
  21. package/package.json +3 -3
  22. package/src/MssqlClient.ts +60 -13
  23. package/src/MssqlMigrator.ts +30 -5
  24. package/src/Parameter.ts +35 -7
  25. package/src/Procedure.ts +59 -17
  26. package/src/index.ts +90 -6
package/dist/Procedure.d.ts CHANGED
@@ -5,18 +5,24 @@ import type { DataType } from "tedious/lib/data-type.ts";
5
5
  import type { ParameterOptions } from "tedious/lib/request.ts";
6
6
  import * as Parameter from "./Parameter.ts";
7
7
  /**
8
+ * Runtime type identifier used to mark SQL Server stored procedure definitions.
9
+ *
8
10
  * @category type id
9
- * @since 1.0.0
11
+ * @since 4.0.0
10
12
  */
11
13
  export declare const TypeId: TypeId;
12
14
  /**
15
+ * Type-level identifier used to mark SQL Server stored procedure definitions.
16
+ *
13
17
  * @category type id
14
- * @since 1.0.0
18
+ * @since 4.0.0
15
19
  */
16
20
  export type TypeId = "~@effect/sql-mssql/Procedure";
17
21
  /**
18
- * @category model
19
- * @since 1.0.0
22
+ * Pipeable definition of a SQL Server stored procedure, tracking its input parameters, output parameters, and result row type.
23
+ *
24
+ * @category models
25
+ * @since 4.0.0
20
26
  */
21
27
  export interface Procedure<I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>, A = never> extends Pipeable {
22
28
  readonly [TypeId]: {
@@ -28,25 +34,34 @@ export interface Procedure<I extends Record<string, Parameter.Parameter<any>>, O
28
34
  readonly outputParams: O;
29
35
  }
30
36
  /**
31
- * @category model
32
- * @since 1.0.0
37
+ * Stored procedure definition with concrete input values bound for execution.
38
+ *
39
+ * @category models
40
+ * @since 4.0.0
33
41
  */
34
42
  export interface ProcedureWithValues<I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>, A> extends Procedure<I, O, A> {
35
43
  readonly values: Procedure.ParametersRecord<I>;
36
44
  }
37
45
  /**
38
- * @since 1.0.0
46
+ * Namespace containing type helpers and result types for SQL Server stored procedures.
47
+ *
48
+ * @since 4.0.0
39
49
  */
40
50
  export declare namespace Procedure {
41
51
  /**
42
- * @since 1.0.0
52
+ * Maps a record of `Parameter` metadata to the corresponding record of parameter value types.
53
+ *
54
+ * @category utility types
55
+ * @since 4.0.0
43
56
  */
44
57
  type ParametersRecord<A extends Record<string, Parameter.Parameter<any>>> = {
45
58
  readonly [K in keyof A]: A[K] extends Parameter.Parameter<infer T> ? T : never;
46
59
  } & {};
47
60
  /**
48
- * @category model
49
- * @since 1.0.0
61
+ * Result of a SQL Server stored procedure call, containing typed output parameter values and returned rows.
62
+ *
63
+ * @category models
64
+ * @since 4.0.0
50
65
  */
51
66
  interface Result<O extends Record<string, Parameter.Parameter<any>>, A> {
52
67
  readonly output: ParametersRecord<O>;
@@ -57,28 +72,38 @@ type Simplify<A> = {
57
72
  [K in keyof A]: A[K];
58
73
  } & {};
59
74
  /**
60
- * @category constructor
61
- * @since 1.0.0
75
+ * Creates an empty SQL Server stored procedure definition for the given procedure name.
76
+ *
77
+ * @category constructors
78
+ * @since 4.0.0
62
79
  */
63
80
  export declare const make: (name: string) => Procedure<{}, {}>;
64
81
  /**
82
+ * Adds a typed input parameter to a SQL Server stored procedure definition.
83
+ *
65
84
  * @category combinator
66
- * @since 1.0.0
85
+ * @since 4.0.0
67
86
  */
68
87
  export declare const param: <A>() => <N extends string, T extends DataType>(name: N, type: T, options?: ParameterOptions) => <I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>>(self: Procedure<I, O>) => Procedure<Simplify<I & { [K in N]: Parameter.Parameter<A>; }>, O>;
69
88
  /**
89
+ * Adds a typed output parameter to a SQL Server stored procedure definition.
90
+ *
70
91
  * @category combinator
71
- * @since 1.0.0
92
+ * @since 4.0.0
72
93
  */
73
94
  export declare const outputParam: <A>() => <N extends string, T extends DataType>(name: N, type: T, options?: ParameterOptions) => <I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>>(self: Procedure<I, O>) => Procedure<I, Simplify<O & { [K in N]: Parameter.Parameter<A>; }>>;
74
95
  /**
96
+ * Sets the expected row type for a SQL Server stored procedure definition.
97
+ *
75
98
  * @category combinator
76
- * @since 1.0.0
99
+ * @since 4.0.0
77
100
  */
78
101
  export declare const withRows: <A extends object = Row>() => <I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>>(self: Procedure<I, O>) => Procedure<I, O, A>;
79
102
  /**
103
+ * Binds input values to a SQL Server stored procedure definition, producing a value that can be executed with `MssqlClient.call`.
104
+ *
80
105
  * @category combinator
81
- * @since 1.0.0
106
+ * @since 4.0.0
82
107
  */
83
108
  export declare const compile: <I extends Record<string, Parameter.Parameter<any>>, O extends Record<string, Parameter.Parameter<any>>, A>(self: Procedure<I, O, A>) => (input: Procedure.ParametersRecord<I>) => ProcedureWithValues<I, O, A>;
84
109
  export {};
package/dist/Procedure.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"Procedure.d.ts","sourceRoot":"","sources":["../src/Procedure.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Procedure.d.ts","sourceRoot":"","sources":["../src/Procedure.ts"],"names":[],"mappings":"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"}
package/dist/Procedure.js CHANGED
@@ -1,12 +1,31 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Typed builders for Microsoft SQL Server stored procedure definitions.
3
+ *
4
+ * This module describes the metadata consumed by `MssqlClient.call`: create a
5
+ * definition with `make`, add input and output parameters with their Tedious
6
+ * data types and `ParameterOptions`, optionally describe the returned row shape
7
+ * with `withRows`, and use `compile` to bind the input values before execution.
8
+ * It is useful when application code calls stored procedures for commands,
9
+ * reports, migrations, or workflows that return both result sets and output
10
+ * parameters.
11
+ *
12
+ * Parameter value types are supplied explicitly through `param<A>()` and
13
+ * `outputParam<A>()`; they are not inferred from the Tedious data type. Input
14
+ * values must be keyed by the parameter names in the definition, output
15
+ * parameters are collected separately from returned rows, and `withRows` only
16
+ * records the expected TypeScript row type, so row names and transforms still
17
+ * follow the configured `MssqlClient` result handling.
18
+ *
19
+ * @since 4.0.0
3
20
  */
4
21
  import { identity } from "effect/Function";
5
22
  import { pipeArguments } from "effect/Pipeable";
6
23
  import * as Parameter from "./Parameter.js";
7
24
  /**
25
+ * Runtime type identifier used to mark SQL Server stored procedure definitions.
26
+ *
8
27
  * @category type id
9
- * @since 1.0.0
28
+ * @since 4.0.0
10
29
  */
11
30
  export const TypeId = "~@effect/sql-mssql/Procedure";
12
31
  const procedureProto = {
@@ -19,8 +38,10 @@ const procedureProto = {
19
38
  }
20
39
  };
21
40
  /**
22
- * @category constructor
23
- * @since 1.0.0
41
+ * Creates an empty SQL Server stored procedure definition for the given procedure name.
42
+ *
43
+ * @category constructors
44
+ * @since 4.0.0
24
45
  */
25
46
  export const make = name => {
26
47
  const procedure = Object.create(procedureProto);
@@ -30,8 +51,10 @@ export const make = name => {
30
51
  return procedure;
31
52
  };
32
53
  /**
54
+ * Adds a typed input parameter to a SQL Server stored procedure definition.
55
+ *
33
56
  * @category combinator
34
- * @since 1.0.0
57
+ * @since 4.0.0
35
58
  */
36
59
  export const param = () => (name, type, options) => self => ({
37
60
  ...self,
@@ -41,8 +64,10 @@ export const param = () => (name, type, options) => self => ({
41
64
  }
42
65
  });
43
66
  /**
67
+ * Adds a typed output parameter to a SQL Server stored procedure definition.
68
+ *
44
69
  * @category combinator
45
- * @since 1.0.0
70
+ * @since 4.0.0
46
71
  */
47
72
  export const outputParam = () => (name, type, options) => self => ({
48
73
  ...self,
@@ -52,13 +77,17 @@ export const outputParam = () => (name, type, options) => self => ({
52
77
  }
53
78
  });
54
79
  /**
80
+ * Sets the expected row type for a SQL Server stored procedure definition.
81
+ *
55
82
  * @category combinator
56
- * @since 1.0.0
83
+ * @since 4.0.0
57
84
  */
58
85
  export const withRows = () => self => self;
59
86
  /**
87
+ * Binds input values to a SQL Server stored procedure definition, producing a value that can be executed with `MssqlClient.call`.
88
+ *
60
89
  * @category combinator
61
- * @since 1.0.0
90
+ * @since 4.0.0
62
91
  */
63
92
  export const compile = self => input => ({
64
93
  ...self,
package/dist/Procedure.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"Procedure.js","names":["identity","pipeArguments","Parameter","TypeId","procedureProto","_A","_tag","pipe","arguments","make","name","procedure","Object","create","params","outputParams","param","type","options","self","outputParam","withRows","compile","input","values"],"sources":["../src/Procedure.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,SAASA,QAAQ,QAAQ,iBAAiB;AAE1C,SAASC,aAAa,QAAQ,iBAAiB;AAK/C,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;AAIA,OAAO,MAAMC,MAAM,GAAW,8BAA8B;AAqE5D,MAAMC,cAAc,GAAG;EACrB,CAACD,MAAM,GAAG;IACRE,EAAE,EAAEL;GACL;EACDM,IAAI,EAAE,WAAW;EACjBC,IAAIA,CAAA;IACF,OAAON,aAAa,CAAC,IAAI,EAAEO,SAAS,CAAC;EACvC;CACD;AAED;;;;AAIA,OAAO,MAAMC,IAAI,GAAIC,IAAY,IAAuB;EACtD,MAAMC,SAAS,GAAGC,MAAM,CAACC,MAAM,CAACT,cAAc,CAAC;EAC/CO,SAAS,CAACD,IAAI,GAAGA,IAAI;EACrBC,SAAS,CAACG,MAAM,GAAG,EAAE;EACrBH,SAAS,CAACI,YAAY,GAAG,EAAE;EAC3B,OAAOJ,SAAS;AAClB,CAAC;AAED;;;;AAIA,OAAO,MAAMK,KAAK,GAAGA,CAAA,KACrB,CACEN,IAAO,EACPO,IAAO,EACPC,OAA0B,KAM1BC,IAAqB,KACiD;EACtE,GAAGA,IAAI;EACPL,MAAM,EAAE;IACN,GAAGK,IAAI,CAACL,MAAM;IACd,CAACJ,IAAI,GAAGR,SAAS,CAACO,IAAI,CAACC,IAAI,EAAEO,IAAI,EAAEC,OAAO;;CAE7C,CAAC;AAEF;;;;AAIA,OAAO,MAAME,WAAW,GAAGA,CAAA,KAC3B,CACEV,IAAO,EACPO,IAAO,EACPC,OAA0B,KAM1BC,IAAqB,KACiD;EACtE,GAAGA,IAAI;EACPJ,YAAY,EAAE;IACZ,GAAGI,IAAI,CAACJ,YAAY;IACpB,CAACL,IAAI,GAAGR,SAAS,CAACO,IAAI,CAACC,IAAI,EAAEO,IAAI,EAAEC,OAAO;;CAE7C,CAAC;AAEF;;;;AAIA,OAAO,MAAMG,QAAQ,GAAGA,CAAA,KAKtBF,IAAqB,IACEA,IAAW;AAEpC;;;;AAIA,OAAO,MAAMG,OAAO,GAKlBH,IAAwB,IAEzBI,KAAoC,KAAoC;EACvE,GAAGJ,IAAI;EACPK,MAAM,EAAED;CACT,CAAC","ignoreList":[]}
1
+ {"version":3,"file":"Procedure.js","names":["identity","pipeArguments","Parameter","TypeId","procedureProto","_A","_tag","pipe","arguments","make","name","procedure","Object","create","params","outputParams","param","type","options","self","outputParam","withRows","compile","input","values"],"sources":["../src/Procedure.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;AAoBA,SAASA,QAAQ,QAAQ,iBAAiB;AAE1C,SAASC,aAAa,QAAQ,iBAAiB;AAK/C,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,8BAA8B;AAkF5D,MAAMC,cAAc,GAAG;EACrB,CAACD,MAAM,GAAG;IACRE,EAAE,EAAEL;GACL;EACDM,IAAI,EAAE,WAAW;EACjBC,IAAIA,CAAA;IACF,OAAON,aAAa,CAAC,IAAI,EAAEO,SAAS,CAAC;EACvC;CACD;AAED;;;;;;AAMA,OAAO,MAAMC,IAAI,GAAIC,IAAY,IAAuB;EACtD,MAAMC,SAAS,GAAGC,MAAM,CAACC,MAAM,CAACT,cAAc,CAAC;EAC/CO,SAAS,CAACD,IAAI,GAAGA,IAAI;EACrBC,SAAS,CAACG,MAAM,GAAG,EAAE;EACrBH,SAAS,CAACI,YAAY,GAAG,EAAE;EAC3B,OAAOJ,SAAS;AAClB,CAAC;AAED;;;;;;AAMA,OAAO,MAAMK,KAAK,GAAGA,CAAA,KACrB,CACEN,IAAO,EACPO,IAAO,EACPC,OAA0B,KAM1BC,IAAqB,KACiD;EACtE,GAAGA,IAAI;EACPL,MAAM,EAAE;IACN,GAAGK,IAAI,CAACL,MAAM;IACd,CAACJ,IAAI,GAAGR,SAAS,CAACO,IAAI,CAACC,IAAI,EAAEO,IAAI,EAAEC,OAAO;;CAE7C,CAAC;AAEF;;;;;;AAMA,OAAO,MAAME,WAAW,GAAGA,CAAA,KAC3B,CACEV,IAAO,EACPO,IAAO,EACPC,OAA0B,KAM1BC,IAAqB,KACiD;EACtE,GAAGA,IAAI;EACPJ,YAAY,EAAE;IACZ,GAAGI,IAAI,CAACJ,YAAY;IACpB,CAACL,IAAI,GAAGR,SAAS,CAACO,IAAI,CAACC,IAAI,EAAEO,IAAI,EAAEC,OAAO;;CAE7C,CAAC;AAEF;;;;;;AAMA,OAAO,MAAMG,QAAQ,GAAGA,CAAA,KAKtBF,IAAqB,IACEA,IAAW;AAEpC;;;;;;AAMA,OAAO,MAAMG,OAAO,GAKlBH,IAAwB,IAEzBI,KAAoC,KAAoC;EACvE,GAAGJ,IAAI;EACPK,MAAM,EAAED;CACT,CAAC","ignoreList":[]}
package/dist/index.d.ts CHANGED
@@ -1,25 +1,109 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
  export {
5
5
  /**
6
- * @since 1.0.0
6
+ * @since 4.0.0
7
7
  */
8
8
  TYPES as MssqlTypes } from "tedious";
9
9
  /**
10
- * @since 1.0.0
10
+ * Microsoft SQL Server client implementation for Effect SQL, backed by the
11
+ * `tedious` driver.
12
+ *
13
+ * This module provides the `MssqlClient` service and layers that also satisfy
14
+ * the generic `SqlClient` service. It is intended for server applications,
15
+ * background workers, migrations, and tests that need SQL Server query
16
+ * compilation, Tedious parameter typing, scoped connection management,
17
+ * transactions, and typed stored procedure calls.
18
+ *
19
+ * Clients own a scoped pool of Tedious connections and validate startup with
20
+ * `SELECT 1`. Regular queries borrow a pooled connection per operation, while
21
+ * transactions keep one pooled connection for their lifetime and use SQL Server
22
+ * savepoints for nested transactions. Long-running transactions therefore
23
+ * reduce available pool capacity; size `maxConnections`, `connectionTTL`, and
24
+ * `connectTimeout` accordingly.
25
+ *
26
+ * Tedious permits one active request per connection. This client compiles
27
+ * statements with named `@1`-style parameters, maps Effect SQL primitive values
28
+ * to Tedious `DataType`s unless `param` is used, and does not implement
29
+ * streaming queries. Be deliberate about TLS options: `encrypt` defaults to
30
+ * `false` and `trustServerCertificate` defaults to `true` unless overridden.
31
+ * Stored procedure calls go through `callProcedure`; define input and output
32
+ * parameters with the `Procedure` and `Parameter` helpers so Tedious receives
33
+ * the correct data types and output values can be collected from `returnValue`
34
+ * events.
35
+ *
36
+ * @since 4.0.0
11
37
  */
12
38
  export * as MssqlClient from "./MssqlClient.ts";
13
39
  /**
14
- * @since 1.0.0
40
+ * Utilities for applying Effect SQL migrations to Microsoft SQL Server.
41
+ *
42
+ * This module re-exports the shared `Migrator` loaders and error types, then
43
+ * provides `run` and `layer` helpers for applying ordered migrations through
44
+ * the current SQL Server `SqlClient`. It is typically used at application
45
+ * startup, during deployment, in integration tests that provision temporary SQL
46
+ * Server databases, or in layer graphs that need the database schema to be
47
+ * current before dependent services are acquired.
48
+ *
49
+ * Applied migrations are stored in `effect_sql_migrations` by default and use
50
+ * the shared `<id>_<name>` loader convention. Only migrations with ids greater
51
+ * than the latest recorded id are run, so avoid inserting older migration ids
52
+ * after a later migration has reached production. SQL Server migrations run
53
+ * inside the shared migrator transaction and this adapter does not add a
54
+ * dialect-specific table lock, so coordinate concurrent startup runners and
55
+ * write T-SQL that is valid inside an explicit transaction. Remember that `GO`
56
+ * is a client-side batch separator rather than a T-SQL statement, and split
57
+ * migrations when SQL Server requires an object definition such as `CREATE
58
+ * VIEW`, `CREATE PROCEDURE`, or `CREATE TRIGGER` to start its own batch. This
59
+ * adapter also does not emit SQL Server schema dumps for `schemaDirectory`.
60
+ *
61
+ * @since 4.0.0
15
62
  */
16
63
  export * as MssqlMigrator from "./MssqlMigrator.ts";
17
64
  /**
18
- * @since 1.0.0
65
+ * Typed metadata for SQL Server stored procedure parameters.
66
+ *
67
+ * This module records the bare parameter name, Tedious `DataType`, Tedious
68
+ * `ParameterOptions`, and phantom TypeScript value type used by
69
+ * `Procedure.param` and `Procedure.outputParam`. `MssqlClient.call` later
70
+ * forwards input parameters to Tedious with `Request.addParameter` and output
71
+ * parameters with `Request.addOutputParameter`, so names should match the
72
+ * stored procedure parameter name without a leading `@`.
73
+ *
74
+ * Use these values when defining stored procedures that need explicit SQL
75
+ * Server parameter metadata, such as sized strings or binary values, decimal
76
+ * precision/scale, table-valued parameters, and output parameters. The generic
77
+ * type parameter is only a compile-time guide for the value record accepted by
78
+ * `Procedure.compile`; Tedious still validates and encodes the runtime value.
79
+ * In particular, TVP values must use Tedious' table shape with `name`,
80
+ * optional `schema`, `columns`, and `rows`, and output parameters are registered
81
+ * with no initial value, so SQL Server input-output parameters need separate
82
+ * care rather than assuming an output parameter is populated from compiled
83
+ * input values.
84
+ *
85
+ * @since 4.0.0
19
86
  */
20
87
  export * as Parameter from "./Parameter.ts";
21
88
  /**
22
- * @since 1.0.0
89
+ * Typed builders for Microsoft SQL Server stored procedure definitions.
90
+ *
91
+ * This module describes the metadata consumed by `MssqlClient.call`: create a
92
+ * definition with `make`, add input and output parameters with their Tedious
93
+ * data types and `ParameterOptions`, optionally describe the returned row shape
94
+ * with `withRows`, and use `compile` to bind the input values before execution.
95
+ * It is useful when application code calls stored procedures for commands,
96
+ * reports, migrations, or workflows that return both result sets and output
97
+ * parameters.
98
+ *
99
+ * Parameter value types are supplied explicitly through `param<A>()` and
100
+ * `outputParam<A>()`; they are not inferred from the Tedious data type. Input
101
+ * values must be keyed by the parameter names in the definition, output
102
+ * parameters are collected separately from returned rows, and `withRows` only
103
+ * records the expected TypeScript row type, so row names and transforms still
104
+ * follow the configured `MssqlClient` result handling.
105
+ *
106
+ * @since 4.0.0
23
107
  */
24
108
  export * as Procedure from "./Procedure.ts";
25
109
  //# sourceMappingURL=index.d.ts.map
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO;AACL;;GAEG;AACH,KAAK,IAAI,UAAU,EACpB,MAAM,SAAS,CAAA;AAIhB;;GAEG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;GAEG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO;AACL;;GAEG;AACH,KAAK,IAAI,UAAU,EACpB,MAAM,SAAS,CAAA;AAIhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA"}
package/dist/index.js CHANGED
@@ -1,26 +1,110 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * @since 4.0.0
3
3
  */
4
4
  export {
5
5
  /**
6
- * @since 1.0.0
6
+ * @since 4.0.0
7
7
  */
8
8
  TYPES as MssqlTypes } from "tedious";
9
9
  // @barrel: Auto-generated exports. Do not edit manually.
10
10
  /**
11
- * @since 1.0.0
11
+ * Microsoft SQL Server client implementation for Effect SQL, backed by the
12
+ * `tedious` driver.
13
+ *
14
+ * This module provides the `MssqlClient` service and layers that also satisfy
15
+ * the generic `SqlClient` service. It is intended for server applications,
16
+ * background workers, migrations, and tests that need SQL Server query
17
+ * compilation, Tedious parameter typing, scoped connection management,
18
+ * transactions, and typed stored procedure calls.
19
+ *
20
+ * Clients own a scoped pool of Tedious connections and validate startup with
21
+ * `SELECT 1`. Regular queries borrow a pooled connection per operation, while
22
+ * transactions keep one pooled connection for their lifetime and use SQL Server
23
+ * savepoints for nested transactions. Long-running transactions therefore
24
+ * reduce available pool capacity; size `maxConnections`, `connectionTTL`, and
25
+ * `connectTimeout` accordingly.
26
+ *
27
+ * Tedious permits one active request per connection. This client compiles
28
+ * statements with named `@1`-style parameters, maps Effect SQL primitive values
29
+ * to Tedious `DataType`s unless `param` is used, and does not implement
30
+ * streaming queries. Be deliberate about TLS options: `encrypt` defaults to
31
+ * `false` and `trustServerCertificate` defaults to `true` unless overridden.
32
+ * Stored procedure calls go through `callProcedure`; define input and output
33
+ * parameters with the `Procedure` and `Parameter` helpers so Tedious receives
34
+ * the correct data types and output values can be collected from `returnValue`
35
+ * events.
36
+ *
37
+ * @since 4.0.0
12
38
  */
13
39
  export * as MssqlClient from "./MssqlClient.js";
14
40
  /**
15
- * @since 1.0.0
41
+ * Utilities for applying Effect SQL migrations to Microsoft SQL Server.
42
+ *
43
+ * This module re-exports the shared `Migrator` loaders and error types, then
44
+ * provides `run` and `layer` helpers for applying ordered migrations through
45
+ * the current SQL Server `SqlClient`. It is typically used at application
46
+ * startup, during deployment, in integration tests that provision temporary SQL
47
+ * Server databases, or in layer graphs that need the database schema to be
48
+ * current before dependent services are acquired.
49
+ *
50
+ * Applied migrations are stored in `effect_sql_migrations` by default and use
51
+ * the shared `<id>_<name>` loader convention. Only migrations with ids greater
52
+ * than the latest recorded id are run, so avoid inserting older migration ids
53
+ * after a later migration has reached production. SQL Server migrations run
54
+ * inside the shared migrator transaction and this adapter does not add a
55
+ * dialect-specific table lock, so coordinate concurrent startup runners and
56
+ * write T-SQL that is valid inside an explicit transaction. Remember that `GO`
57
+ * is a client-side batch separator rather than a T-SQL statement, and split
58
+ * migrations when SQL Server requires an object definition such as `CREATE
59
+ * VIEW`, `CREATE PROCEDURE`, or `CREATE TRIGGER` to start its own batch. This
60
+ * adapter also does not emit SQL Server schema dumps for `schemaDirectory`.
61
+ *
62
+ * @since 4.0.0
16
63
  */
17
64
  export * as MssqlMigrator from "./MssqlMigrator.js";
18
65
  /**
19
- * @since 1.0.0
66
+ * Typed metadata for SQL Server stored procedure parameters.
67
+ *
68
+ * This module records the bare parameter name, Tedious `DataType`, Tedious
69
+ * `ParameterOptions`, and phantom TypeScript value type used by
70
+ * `Procedure.param` and `Procedure.outputParam`. `MssqlClient.call` later
71
+ * forwards input parameters to Tedious with `Request.addParameter` and output
72
+ * parameters with `Request.addOutputParameter`, so names should match the
73
+ * stored procedure parameter name without a leading `@`.
74
+ *
75
+ * Use these values when defining stored procedures that need explicit SQL
76
+ * Server parameter metadata, such as sized strings or binary values, decimal
77
+ * precision/scale, table-valued parameters, and output parameters. The generic
78
+ * type parameter is only a compile-time guide for the value record accepted by
79
+ * `Procedure.compile`; Tedious still validates and encodes the runtime value.
80
+ * In particular, TVP values must use Tedious' table shape with `name`,
81
+ * optional `schema`, `columns`, and `rows`, and output parameters are registered
82
+ * with no initial value, so SQL Server input-output parameters need separate
83
+ * care rather than assuming an output parameter is populated from compiled
84
+ * input values.
85
+ *
86
+ * @since 4.0.0
20
87
  */
21
88
  export * as Parameter from "./Parameter.js";
22
89
  /**
23
- * @since 1.0.0
90
+ * Typed builders for Microsoft SQL Server stored procedure definitions.
91
+ *
92
+ * This module describes the metadata consumed by `MssqlClient.call`: create a
93
+ * definition with `make`, add input and output parameters with their Tedious
94
+ * data types and `ParameterOptions`, optionally describe the returned row shape
95
+ * with `withRows`, and use `compile` to bind the input values before execution.
96
+ * It is useful when application code calls stored procedures for commands,
97
+ * reports, migrations, or workflows that return both result sets and output
98
+ * parameters.
99
+ *
100
+ * Parameter value types are supplied explicitly through `param<A>()` and
101
+ * `outputParam<A>()`; they are not inferred from the Tedious data type. Input
102
+ * values must be keyed by the parameter names in the definition, output
103
+ * parameters are collected separately from returned rows, and `withRows` only
104
+ * records the expected TypeScript row type, so row names and transforms still
105
+ * follow the configured `MssqlClient` result handling.
106
+ *
107
+ * @since 4.0.0
24
108
  */
25
109
  export * as Procedure from "./Procedure.js";
26
110
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","names":["TYPES","MssqlTypes","MssqlClient","MssqlMigrator","Parameter","Procedure"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AACE;;;AAGAA,KAAK,IAAIC,UAAU,QACd,SAAS;AAEhB;AAEA;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB","ignoreList":[]}
1
+ {"version":3,"file":"index.js","names":["TYPES","MssqlTypes","MssqlClient","MssqlMigrator","Parameter","Procedure"],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AACE;;;AAGAA,KAAK,IAAIC,UAAU,QACd,SAAS;AAEhB;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB","ignoreList":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effect/sql-mssql",
3
- "version": "4.0.0-beta.66",
3
+ "version": "4.0.0-beta.68",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "description": "A Microsoft SQL Server toolkit for Effect",
@@ -43,10 +43,10 @@
43
43
  "provenance": true
44
44
  },
45
45
  "devDependencies": {
46
- "effect": "^4.0.0-beta.66"
46
+ "effect": "^4.0.0-beta.68"
47
47
  },
48
48
  "peerDependencies": {
49
- "effect": "^4.0.0-beta.66"
49
+ "effect": "^4.0.0-beta.68"
50
50
  },
51
51
  "dependencies": {
52
52
  "tedious": "^19.2.1"
package/src/MssqlClient.ts CHANGED
@@ -1,5 +1,31 @@
1
1
  /**
2
- * @since 1.0.0
2
+ * Microsoft SQL Server client implementation for Effect SQL, backed by the
3
+ * `tedious` driver.
4
+ *
5
+ * This module provides the `MssqlClient` service and layers that also satisfy
6
+ * the generic `SqlClient` service. It is intended for server applications,
7
+ * background workers, migrations, and tests that need SQL Server query
8
+ * compilation, Tedious parameter typing, scoped connection management,
9
+ * transactions, and typed stored procedure calls.
10
+ *
11
+ * Clients own a scoped pool of Tedious connections and validate startup with
12
+ * `SELECT 1`. Regular queries borrow a pooled connection per operation, while
13
+ * transactions keep one pooled connection for their lifetime and use SQL Server
14
+ * savepoints for nested transactions. Long-running transactions therefore
15
+ * reduce available pool capacity; size `maxConnections`, `connectionTTL`, and
16
+ * `connectTimeout` accordingly.
17
+ *
18
+ * Tedious permits one active request per connection. This client compiles
19
+ * statements with named `@1`-style parameters, maps Effect SQL primitive values
20
+ * to Tedious `DataType`s unless `param` is used, and does not implement
21
+ * streaming queries. Be deliberate about TLS options: `encrypt` defaults to
22
+ * `false` and `trustServerCertificate` defaults to `true` unless overridden.
23
+ * Stored procedure calls go through `callProcedure`; define input and output
24
+ * parameters with the `Procedure` and `Parameter` helpers so Tedious receives
25
+ * the correct data types and output values can be collected from `returnValue`
26
+ * events.
27
+ *
28
+ * @since 4.0.0
3
29
  */
4
30
  import * as Config from "effect/Config"
5
31
  import * as Context from "effect/Context"
@@ -130,20 +156,26 @@ const classifyError = (
130
156
  }
131
157
 
132
158
  /**
133
- * @category type ids
134
- * @since 1.0.0
159
+ * Runtime type identifier used to mark `MssqlClient` values.
160
+ *
161
+ * @category type IDs
162
+ * @since 4.0.0
135
163
  */
136
164
  export const TypeId: unique symbol = Symbol.for("@effect/sql-mssql/MssqlClient")
137
165
 
138
166
  /**
139
- * @category type ids
140
- * @since 1.0.0
167
+ * Type-level identifier used to mark `MssqlClient` values.
168
+ *
169
+ * @category type IDs
170
+ * @since 4.0.0
141
171
  */
142
172
  export type TypeId = typeof TypeId
143
173
 
144
174
  /**
175
+ * Microsoft SQL Server client service, extending `SqlClient` with typed parameter fragments and stored procedure calls.
176
+ *
145
177
  * @category models
146
- * @since 1.0.0
178
+ * @since 4.0.0
147
179
  */
148
180
  export interface MssqlClient extends Client.SqlClient {
149
181
  readonly [TypeId]: TypeId
@@ -166,14 +198,18 @@ export interface MssqlClient extends Client.SqlClient {
166
198
  }
167
199
 
168
200
  /**
201
+ * Context tag used to access the `MssqlClient` service.
202
+ *
169
203
  * @category tags
170
- * @since 1.0.0
204
+ * @since 4.0.0
171
205
  */
172
206
  export const MssqlClient = Context.Service<MssqlClient>("@effect/sql-mssql/MssqlClient")
173
207
 
174
208
  /**
209
+ * Configuration for a Microsoft SQL Server client, including connection, authentication, pool, parameter type, span attribute, and query/result name transform options.
210
+ *
175
211
  * @category models
176
- * @since 1.0.0
212
+ * @since 4.0.0
177
213
  */
178
214
  export interface MssqlClientConfig {
179
215
  readonly domain?: string | undefined
@@ -220,8 +256,10 @@ const TransactionConnection = Client.TransactionConnection as unknown as (client
220
256
  let clientIdCounter = 0
221
257
 
222
258
  /**
259
+ * Creates a scoped Microsoft SQL Server client backed by a connection pool, with transaction and stored procedure support. Streaming queries are not implemented.
260
+ *
223
261
  * @category constructors
224
- * @since 1.0.0
262
+ * @since 4.0.0
225
263
  */
226
264
  export const make = (
227
265
  options: MssqlClientConfig
@@ -565,8 +603,10 @@ export const make = (
565
603
  })
566
604
 
567
605
  /**
606
+ * Creates a layer from a `Config`-wrapped SQL Server client configuration, providing both `MssqlClient` and `SqlClient`.
607
+ *
568
608
  * @category layers
569
- * @since 1.0.0
609
+ * @since 4.0.0
570
610
  */
571
611
  export const layerConfig: (
572
612
  config: Config.Wrap<MssqlClientConfig>
@@ -585,8 +625,10 @@ export const layerConfig: (
585
625
  ).pipe(Layer.provide(Reactivity.layer))
586
626
 
587
627
  /**
628
+ * Creates a layer from a concrete SQL Server client configuration, providing both `MssqlClient` and `SqlClient`.
629
+ *
588
630
  * @category layers
589
- * @since 1.0.0
631
+ * @since 4.0.0
590
632
  */
591
633
  export const layer = (
592
634
  config: MssqlClientConfig
@@ -599,8 +641,10 @@ export const layer = (
599
641
  ).pipe(Layer.provide(Reactivity.layer))
600
642
 
601
643
  /**
644
+ * Creates the SQL Server statement compiler, using `@1`-style placeholders, bracket-escaped identifiers, and SQL Server `OUTPUT INSERTED` returning clauses.
645
+ *
602
646
  * @category compiler
603
- * @since 1.0.0
647
+ * @since 4.0.0
604
648
  */
605
649
  export const makeCompiler = (transform?: (_: string) => string) =>
606
650
  Statement.makeCompiler<MssqlCustom>({
@@ -649,7 +693,10 @@ function numberToParamName(n: number) {
649
693
  }
650
694
 
651
695
  /**
652
- * @since 1.0.0
696
+ * Default mapping from Effect SQL primitive value kinds to Tedious SQL Server parameter data types.
697
+ *
698
+ * @category configuration
699
+ * @since 4.0.0
653
700
  */
654
701
  export const defaultParameterTypes: Record<Statement.PrimitiveKind, DataType> = {
655
702
  string: Tedious.TYPES.VarChar,