@aiquants/mssql 0.1.1
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.
- package/LICENSE +21 -0
- package/README.md +187 -0
- package/dist/index.d.mts +230 -0
- package/dist/index.d.ts +230 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +2 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +62 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 AI Quants / fehde-k
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# @aiquants/mssql
|
|
2
|
+
|
|
3
|
+
What SQL Server refuses, and how to stay inside it. Domain-free, dependency-free.
|
|
4
|
+
|
|
5
|
+
SQL Server が**拒むもの**と、その内側に留まる方法。ドメインにも依存にも縛られません。
|
|
6
|
+
|
|
7
|
+
| 何を答えるか | 入口 |
|
|
8
|
+
| :--- | :--- |
|
|
9
|
+
| 失敗した作業単位を、もう一度実行してよいか | `runWithTransactionRetry` / `isDeadlockVictim` / `isRolledBackByServer` |
|
|
10
|
+
| 1 文に何件まで載せられるか | `chunkByParameters` / `chunkSizeForParameters` / `chunk` |
|
|
11
|
+
| 返ってきた日時は、どの瞬間か | `toInstant` |
|
|
12
|
+
|
|
13
|
+
どちらも**ドライバが押し付けてくる事実**であり、呼び出し側のドメインには属しません。写しを各所に
|
|
14
|
+
置くと、片方だけ直る事故が起きます。
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## トランザクションの再実行
|
|
19
|
+
|
|
20
|
+
Runs a SQL Server transaction again when — and only when — the failure was a deadlock, and keeps the
|
|
21
|
+
original cause the ORM would otherwise destroy.
|
|
22
|
+
|
|
23
|
+
SQL Server のトランザクションを、失敗がデッドロックであった場合に**限って**やり直し、ORM が破壊して
|
|
24
|
+
しまう元の原因を保持します。
|
|
25
|
+
|
|
26
|
+
## Why this is not "retry on failure"
|
|
27
|
+
|
|
28
|
+
再試行が許されるには **2 つの条件が揃わねばならず**、それらは別の問いです。
|
|
29
|
+
|
|
30
|
+
| 条件 | 問い | 揃わないと |
|
|
31
|
+
| :--- | :--- | :--- |
|
|
32
|
+
| 安全 | 何もコミットされていないか | 同じ変更を 2 度適用する |
|
|
33
|
+
| 有効 | 失敗は一時的か | 同じ失敗を 3 倍遅く繰り返し、真の原因を埋める |
|
|
34
|
+
|
|
35
|
+
デッドロックの犠牲 (エラー番号 `1205`) は、その 1 つの事実で両方を満たします。犠牲は必ず巻き戻され、
|
|
36
|
+
かつ競合相手が去れば通ります。**本パッケージが再実行の根拠として認めるのはそれだけです。**
|
|
37
|
+
|
|
38
|
+
> [!CAUTION]
|
|
39
|
+
> **サーバが巻き戻したことは、一時的であることの証拠ではありません。** サーバは `XACT_ABORT ON` 下の
|
|
40
|
+
> 実行時エラーでも重大度 16 以上のエラーでも自分で巻き戻します。それらは何度やり直しても同じ結果に
|
|
41
|
+
> なります。`EABORT` を再実行の根拠にしてはなりません。
|
|
42
|
+
|
|
43
|
+
| 失敗 | 再実行 | 根拠 |
|
|
44
|
+
| :--- | :--- | :--- |
|
|
45
|
+
| `number === 1205` (デッドロックの犠牲) | **する** | 必ず巻き戻され、やり直せば通りうる |
|
|
46
|
+
| `code === "EABORT"` (サーバが巻き戻した) | しない | 巻き戻ったことしか示さない。原因が決定的なら永久に同じ |
|
|
47
|
+
| `ETIMEOUT` (要求の時限切れ) | しない | 文がサーバ側でまだ走っていることがある |
|
|
48
|
+
| 接続断 (`ECONNCLOSED` / `ESOCKET`) | しない | コミットの成否を持ち帰れない |
|
|
49
|
+
| `number === 2627` / `2601` (一意制約違反) | しない | やり直しても同じ結果。そもそも一時的でない |
|
|
50
|
+
| `number === 1222` (ロック待ちの時限切れ) | しない | `XACT_ABORT` が無い限り自動で巻き戻らない |
|
|
51
|
+
|
|
52
|
+
## ORM は原因を破壊します — だから `capture` があります
|
|
53
|
+
|
|
54
|
+
`drizzle-orm` の `node-mssql` セッションはこう書かれています。
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
} catch (err) {
|
|
58
|
+
await mssqlTransaction.rollback(); // サーバが既に巻き戻していれば EABORT を投げる
|
|
59
|
+
throw err; // ← ここへ到達しない
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`mssql` の `TransactionError` は `(message, code)` しか受け取らず `cause` を持たないため、元の失敗
|
|
64
|
+
(`1205` など) は**痕跡なく消えます**。届くのは「Transaction has been aborted.」だけです。
|
|
65
|
+
|
|
66
|
+
そこで本パッケージは閉包を包む `capture` を呼び出し元へ渡します。**トランザクションの閉包の内側を
|
|
67
|
+
これで包んでください。**
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { runWithTransactionRetry } from "@aiquants/mssql"
|
|
71
|
+
|
|
72
|
+
await runWithTransactionRetry(
|
|
73
|
+
(capture) =>
|
|
74
|
+
db.transaction((tx) =>
|
|
75
|
+
capture(async () => {
|
|
76
|
+
const current = await tx.select().from(rows).where(eq(rows.id, id))
|
|
77
|
+
if (current.length === 0) throw new Error("見つかりません")
|
|
78
|
+
await tx.update(rows).set({ value }).where(eq(rows.id, id))
|
|
79
|
+
}),
|
|
80
|
+
),
|
|
81
|
+
{ onRetry: ({ attempt, attempts, cause }) => log.warn(`deadlock victim; retrying ${attempt}/${attempts - 1}`, cause) },
|
|
82
|
+
)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
包み忘れても壊れません。原因を押さえられない以上やり直さないのが正しいため、**再試行が効かなくなる
|
|
86
|
+
だけで安全側に倒れます** (書き込みが二重になることはありません)。
|
|
87
|
+
|
|
88
|
+
## Install
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pnpm add @aiquants/mssql
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
依存はありません。`mssql` / `tedious` / ORM のいずれにも `import` を持たず、ドライバのエラーが
|
|
95
|
+
一様に載せる `code` と `number` の 2 プロパティだけを見ます (duck typing)。
|
|
96
|
+
|
|
97
|
+
## Contract
|
|
98
|
+
|
|
99
|
+
| 項目 | 既定 | 備考 |
|
|
100
|
+
| :--- | :--- | :--- |
|
|
101
|
+
| `attempts` | `3` | 初回を含む。`1` で再試行しない |
|
|
102
|
+
| `delay(attempt)` | 50ms から倍化・±25% のゆらぎ | 同時に犠牲となった要求が揃って再試行することを避けるため。試験では即時解決する関数を渡す |
|
|
103
|
+
| `onRetry(info)` | 何もしない | **黙って再試行しないこと。** 再試行が成功すると利用者からは何も起きなかったように見えるが、競合が起きていること自体は運用上の事実である |
|
|
104
|
+
|
|
105
|
+
`onRetry` が受け取る `info` は、送出された失敗 (`error`、多くは `EABORT`) と押さえた原本 (`cause`) の
|
|
106
|
+
**両方**を運びます。記録すべきは `cause` です。
|
|
107
|
+
|
|
108
|
+
### 諦めるときは、原因の方を送出します
|
|
109
|
+
|
|
110
|
+
`capture` が原本を押さえており、送出された失敗が `EABORT` でそれを覆い隠している場合、本パッケージは
|
|
111
|
+
**原本を送出します**。「Transaction has been aborted.」だけを返すと、呼び出し元の応答に載るのがその
|
|
112
|
+
文字列になり、何が起きたのか誰にも分からなくなるためです。
|
|
113
|
+
|
|
114
|
+
### 判定だけを使う
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
import { isDeadlockVictim, isRolledBackByServer } from "@aiquants/mssql"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`isDeadlockVictim` は「一時的か」、`isRolledBackByServer` は「巻き戻ったか」を答えます。**別の問いで
|
|
121
|
+
あり、同じ失敗に同時には当たりません。** どちらを立てているのかを先に決めてください。
|
|
122
|
+
|
|
123
|
+
### 守るべき前提
|
|
124
|
+
|
|
125
|
+
- **`work` は毎回はじめから走ります。** 部分的な再開はしません — 再試行が正しいのは「何も起き
|
|
126
|
+
なかった」場合だけであり、途中から再開することはその前提を壊します。
|
|
127
|
+
- **`work` は DB の外へ副作用を持ってはなりません。** トランザクションのロールバックで元に戻らない
|
|
128
|
+
ため、これは再試行の有無に関わらず要求される性質です。
|
|
129
|
+
- **既に外側のトランザクションに居るときは呼ばないでください。** 再試行の判断はそれを開いた側が
|
|
130
|
+
持ちます。内側だけをやり直すと、外側が既に書いた分を巻き戻さずに重ねることになります。
|
|
131
|
+
- **1 文単位の送り直しには使えません。** それは「その 1 文は送られたか」という別の問いであり、判定の
|
|
132
|
+
根拠 (`ECONNCLOSED`) も別です。接続基盤層に閉じて解決してください。
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## パラメータ上限
|
|
137
|
+
|
|
138
|
+
> [!CAUTION]
|
|
139
|
+
> **上限は行数ではなくパラメータ数です。** 1 行あたり何個の値を束ねるかは文ごとに違うので、行数だけで
|
|
140
|
+
> 分割すると、列の多い `VALUES` が静かに上限を越えます。しかも越えるのは件数が閾値を跨いだ日だけで、
|
|
141
|
+
> それまでは同じコードが問題なく動いて見えます (7 列 × 500 行 = 3500 で**実行される前に**拒否)。
|
|
142
|
+
|
|
143
|
+
| 定数 | 値 | 意味 |
|
|
144
|
+
| :--- | :--- | :--- |
|
|
145
|
+
| `MAX_PARAMETERS` | `2100` | SQL Server の RPC 1 回あたりの上限 |
|
|
146
|
+
| `RESERVED_PARAMETERS` | `100` | 文自身のスカラー値のための予約枠 |
|
|
147
|
+
| `MAX_IN_LIST` | `500` | 1 行 1 パラメータの `IN` 句 1 本の既定上限 |
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
import { chunkByParameters, chunkSizeForParameters, MAX_IN_LIST } from "@aiquants/mssql"
|
|
151
|
+
|
|
152
|
+
// 7 列の VALUES を 1 文に収まる単位へ分割する
|
|
153
|
+
for (const batch of chunkByParameters(rows, 7)) await db.insert(ledger).values(batch)
|
|
154
|
+
|
|
155
|
+
// 別の上限と併せたいときは、件数だけを取り出して小さい方を採る
|
|
156
|
+
const size = Math.min(MAX_IN_LIST, chunkSizeForParameters(1, RESERVED_PARAMETERS + FIXED_PARAMETERS))
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
> [!IMPORTANT]
|
|
160
|
+
> **予算を呼び出し側で組み直さないでください。** `2100 - 100` を `2000` と書くと、上限や予約枠が
|
|
161
|
+
> 変わってもそこだけ追従しません。引き算は `chunkSizeForParameters` に任せ、文ごとの事情は
|
|
162
|
+
> `reservedParameters` として渡してください。
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 日時の読み取り
|
|
167
|
+
|
|
168
|
+
SQL Server の `datetime2` は時間帯を持ちません。ドライバは通常 `Date` を組み立てて返しますが、設定や
|
|
169
|
+
経路によっては文字列のまま渡ってきて、その文字列には**オフセットが付きません**。
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
import { toInstant } from "@aiquants/mssql"
|
|
173
|
+
|
|
174
|
+
const observedAt = toInstant(row.observedAt) // "2026-09-09 03:04:05.000" → 03:04:05 UTC
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
> [!CAUTION]
|
|
178
|
+
> **オフセットの無い ISO 文字列は、仕様上「実行環境の時間帯」で解釈されます。** JST で走らせれば
|
|
179
|
+
> 9 時間ずれます — しかも**落ちません**。鮮度は「常に古い」と報告され、締切の比較は静かに 9 時間ぶん
|
|
180
|
+
> 甘くなります。読む場所ごとに対処すると必ずどこかが漏れるので、1 つの関数に閉じてください。
|
|
181
|
+
|
|
182
|
+
読めない値は例外ではなく `Invalid Date` として返します。ここで投げると 1 行の壊れた値が一覧全体を
|
|
183
|
+
落とすためで、判定は呼び出し側が `Number.isNaN(d.getTime())` で行います。
|
|
184
|
+
|
|
185
|
+
## License
|
|
186
|
+
|
|
187
|
+
MIT
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SQL Server parameter-limit helpers shared by every batched statement.
|
|
3
|
+
* 一括文が共有する SQL Server のパラメータ上限まわりのヘルパー。
|
|
4
|
+
*
|
|
5
|
+
* ⚠️ 上限は **行数ではなくパラメータ数** である。1 行あたり何個の値を束ねるかは文ごとに違うので、
|
|
6
|
+
* 行数だけで分割すると、列の多い `VALUES` が静かに上限を越える。しかも越えるのは件数が閾値を
|
|
7
|
+
* 跨いだ日だけで、それまでは同じコードが問題なく動いて見える。
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Hard limit of parameters per statement. 1 文あたりのパラメータ数の上限。
|
|
11
|
+
*
|
|
12
|
+
* SQL Server の RPC 1 回あたりのパラメータ上限は 2100。数個は文自身の値 (`SET` 句・スカラー
|
|
13
|
+
* 述語) が使うため、分割の基準にはここから余裕を引いた値を用いる。
|
|
14
|
+
*/
|
|
15
|
+
declare const MAX_PARAMETERS = 2100;
|
|
16
|
+
/** Parameters reserved for the statement's own scalar values. 文自身のスカラー値のための予約枠。 */
|
|
17
|
+
declare const RESERVED_PARAMETERS = 100;
|
|
18
|
+
/**
|
|
19
|
+
* Maximum ids per `IN` list of single-column predicates. 単列述語の `IN` 句 1 回あたりの最大 ID 数。
|
|
20
|
+
*
|
|
21
|
+
* 1 行 1 パラメータの用途 (`inArray(col, ids)`) 専用の既定値である。複数列を束ねる `VALUES` や、
|
|
22
|
+
* 1 文に `IN` を 2 つ描画する `UPDATE` にそのまま使ってはならない — {@link chunkByParameters} を使う。
|
|
23
|
+
*/
|
|
24
|
+
declare const MAX_IN_LIST = 500;
|
|
25
|
+
/**
|
|
26
|
+
* Splits a list into chunks that fit one statement.
|
|
27
|
+
* 1 文に収まる大きさへリストを分割する処理。
|
|
28
|
+
*
|
|
29
|
+
* @param items - Items to split. 分割対象。
|
|
30
|
+
* @param size - Maximum chunk size. 1 チャンクの最大数。
|
|
31
|
+
* @returns Chunks in the original order. 元の順序を保ったチャンク列。
|
|
32
|
+
* @throws {TypeError} When the size is not a positive integer. 正の整数でない場合。
|
|
33
|
+
*/
|
|
34
|
+
declare function chunk<T>(items: readonly T[], size?: number): T[][];
|
|
35
|
+
/**
|
|
36
|
+
* Splits a list so each chunk fits the parameter budget of one statement.
|
|
37
|
+
* 各チャンクが 1 文のパラメータ枠に収まるようリストを分割する処理。
|
|
38
|
+
*
|
|
39
|
+
* `VALUES` は 1 行につき列数ぶんのパラメータを束ねる。7 列の台帳行なら 500 行で 3500 個になり、
|
|
40
|
+
* 上限 2100 を越えて **実行される前に** 拒否される。しかもその失敗は再試行しても同じ場所で起き、
|
|
41
|
+
* そのグループは永久に台帳を持てない。
|
|
42
|
+
*
|
|
43
|
+
* @param items - Items to split. 分割対象。
|
|
44
|
+
* @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。
|
|
45
|
+
* @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。
|
|
46
|
+
* @returns Chunks in the original order. 元の順序を保ったチャンク列。
|
|
47
|
+
* @throws {TypeError} When a single item cannot fit the budget. 1 件すら収まらない場合。
|
|
48
|
+
*/
|
|
49
|
+
declare function chunkByParameters<T>(items: readonly T[], parametersPerItem: number, reservedParameters?: number): T[][];
|
|
50
|
+
/**
|
|
51
|
+
* Reports how many items fit one statement's parameter budget.
|
|
52
|
+
* 1 文のパラメータ枠に収まる件数を返す処理。
|
|
53
|
+
*
|
|
54
|
+
* {@link chunkByParameters} が使う算術を、分割せずに取り出したいときの入口である。呼び出し側が
|
|
55
|
+
* 別の上限 ({@link MAX_IN_LIST} など) と併せて小さい方を採るような場合に使う — **予算そのものを
|
|
56
|
+
* 呼び出し側で組み直してはならない。** `MAX_PARAMETERS` から引き算した値をリテラルで書くと、
|
|
57
|
+
* 上限や予約枠が変わってもそこだけ追従しない。
|
|
58
|
+
*
|
|
59
|
+
* @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。
|
|
60
|
+
* @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。
|
|
61
|
+
* @returns 1 文へ載せられる件数 (1 以上)。
|
|
62
|
+
* @throws {TypeError} When an argument is invalid, or a single item cannot fit the budget.
|
|
63
|
+
* 引数が不正な場合、または 1 件すら収まらない場合。
|
|
64
|
+
*/
|
|
65
|
+
declare function chunkSizeForParameters(parametersPerItem: number, reservedParameters?: number): number;
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* @module retry
|
|
69
|
+
* Runs a SQL Server transaction again when — and only when — the failure was a deadlock.
|
|
70
|
+
* SQL Server のトランザクションを、失敗がデッドロックであった場合に**限って**やり直す処理。
|
|
71
|
+
*
|
|
72
|
+
* A transaction raises the cost of contention. Two units of work whose key ranges overlap can
|
|
73
|
+
* deadlock, and SQL Server resolves a deadlock by rolling one of them back. Under SERIALIZABLE the
|
|
74
|
+
* ranges are widest, so the chance is highest — but nothing here is specific to an isolation level,
|
|
75
|
+
* a schema, or an application.
|
|
76
|
+
* トランザクションは競合の代償を上げる。鍵の範囲が重なる 2 つの作業単位はデッドロックしうるし、
|
|
77
|
+
* SQL Server はデッドロックを片方のロールバックで解く。SERIALIZABLE では範囲が最も広いため確率が
|
|
78
|
+
* 最も高いが、本モジュールは分離レベル・スキーマ・アプリケーションのいずれにも依存しない。
|
|
79
|
+
*
|
|
80
|
+
* **Two conditions must both hold before a unit of work may be run again**, and they are different
|
|
81
|
+
* questions. Nothing may have been committed — otherwise the retry applies the same change twice.
|
|
82
|
+
* And the failure must be transient — otherwise the retry fails identically, three times slower,
|
|
83
|
+
* for nothing.
|
|
84
|
+
* **再実行が許されるには 2 つの条件が揃わねばならず**、それらは別の問いである。何もコミットされて
|
|
85
|
+
* いないこと — さもなくば同じ変更を 2 度適用する。そして失敗が一時的であること — さもなくば同じ
|
|
86
|
+
* 失敗を 3 倍遅く繰り返すだけになる。
|
|
87
|
+
*
|
|
88
|
+
* デッドロックの犠牲 (エラー番号 `1205`) は、その 1 つの事実で両方を満たす。犠牲は必ず巻き戻され、
|
|
89
|
+
* かつ競合相手が去れば通る。だから本モジュールが認める根拠はそれだけである。
|
|
90
|
+
*
|
|
91
|
+
* ⚠️ **サーバが巻き戻したことは、一時的であることの証拠ではない。** サーバは `XACT_ABORT ON` 下の
|
|
92
|
+
* 実行時エラーでも重大度 16 以上のエラーでも自分で巻き戻す。それらは何度やり直しても同じ結果に
|
|
93
|
+
* なる。`EABORT` ({@link isRolledBackByServer}) を再実行の根拠にしてはならない — 判定に使うのは
|
|
94
|
+
* 「何もコミットされていない」ことの確認までである。
|
|
95
|
+
*
|
|
96
|
+
* ⚠️ **ORM は原因を破壊する。** `drizzle-orm` の `node-mssql` セッションは `catch` の中で
|
|
97
|
+
* `rollback()` を先に呼び、サーバが既に巻き戻していればそのロールバックが
|
|
98
|
+
* `TransactionError('EABORT')` を投げる。`mssql` の `TransactionError` は `(message, code)` しか
|
|
99
|
+
* 受け取らず `cause` を持たないため、元の失敗 (`1205` など) は**痕跡なく消える**。そこで本モジュール
|
|
100
|
+
* は閉包を包む {@link CaptureCause} を呼び出し元へ渡し、原因が失われる前に押さえる。押さえた原因は
|
|
101
|
+
* 再実行の判定に使われ、諦めるときは `EABORT` の代わりに送出される。
|
|
102
|
+
*
|
|
103
|
+
* ⚠️ **Driver-agnostic by duck typing.** ドライバのエラー型を `import` しない — `mssql` /
|
|
104
|
+
* `tedious` / ORM のいずれにも依存させないためである。判定は `code` と `number` という、
|
|
105
|
+
* SQL Server 系ドライバが一様に載せる 2 つのプロパティだけを見る。
|
|
106
|
+
*/
|
|
107
|
+
/** 試行回数の既定。初回 1 回 + 再試行 2 回。 */
|
|
108
|
+
declare const DEFAULT_TRANSACTION_ATTEMPTS = 3;
|
|
109
|
+
/**
|
|
110
|
+
* Wraps the transaction body so the original failure is kept before the ORM can replace it.
|
|
111
|
+
* トランザクションの閉包を包み、ORM が置き換える前に元の失敗を押さえる関数の型。
|
|
112
|
+
*
|
|
113
|
+
* 呼び出し元は閉包の**内側**をこれで包む。包まなくても動くが、そのときは原因を押さえられないため、
|
|
114
|
+
* デッドロックであっても再実行されない (安全側に倒れる)。
|
|
115
|
+
*/
|
|
116
|
+
type CaptureCause = <R>(body: () => Promise<R>) => Promise<R>;
|
|
117
|
+
/** 1 回の再試行の内訳。呼び出し元が記録・計数するために受け取る。 */
|
|
118
|
+
type TransactionRetryInfo = {
|
|
119
|
+
/** 失敗した試行の番号 (1 起点)。 */
|
|
120
|
+
readonly attempt: number;
|
|
121
|
+
/** 許された試行の総数。 */
|
|
122
|
+
readonly attempts: number;
|
|
123
|
+
/** 呼び出しが送出した失敗。ORM による置き換えにより `EABORT` であることが多い。 */
|
|
124
|
+
readonly error: unknown;
|
|
125
|
+
/** 閉包が投げた原本。{@link CaptureCause} を通していなければ `undefined`。 */
|
|
126
|
+
readonly cause: unknown;
|
|
127
|
+
};
|
|
128
|
+
/** 再試行の設定。既定のまま使えるが、試験と記録のために各項目を差し替えられる。 */
|
|
129
|
+
type TransactionRetryOptions = {
|
|
130
|
+
/**
|
|
131
|
+
* 試行回数 (初回を含む)。既定は {@link DEFAULT_TRANSACTION_ATTEMPTS}。
|
|
132
|
+
* `1` を与えると再試行しない。
|
|
133
|
+
*/
|
|
134
|
+
readonly attempts?: number;
|
|
135
|
+
/**
|
|
136
|
+
* 次の試行までの待機。既定は倍化 + ゆらぎ。
|
|
137
|
+
*
|
|
138
|
+
* ゆらぎを入れるのは、同時に犠牲となった複数の要求が揃って同じ時刻に再試行し、同じ競合を
|
|
139
|
+
* もう一度起こすことを避けるため。試験では即時解決する関数を渡す。
|
|
140
|
+
*/
|
|
141
|
+
readonly delay?: (attempt: number) => Promise<void>;
|
|
142
|
+
/**
|
|
143
|
+
* 再試行する直前に呼ばれる。既定は何もしない。
|
|
144
|
+
*
|
|
145
|
+
* **黙って再試行してはならない。** 再試行が成功すると利用者からは何も起きなかったように
|
|
146
|
+
* 見えるが、競合が起きていること自体は運用上の事実である。記録の口を呼び出し元へ渡す。
|
|
147
|
+
*/
|
|
148
|
+
readonly onRetry?: (info: TransactionRetryInfo) => void;
|
|
149
|
+
};
|
|
150
|
+
/**
|
|
151
|
+
* Reports whether a failure is SQL Server's deadlock victim.
|
|
152
|
+
*
|
|
153
|
+
* その失敗が SQL Server の選んだデッドロックの犠牲かを判定する処理。
|
|
154
|
+
*
|
|
155
|
+
* 犠牲は必ずロールバックされる (何もコミットされていない) 上に、競合相手が去ればやり直しは通る。
|
|
156
|
+
* **再実行を許してよい唯一の根拠**である。
|
|
157
|
+
*
|
|
158
|
+
* @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。
|
|
159
|
+
* @returns デッドロックの犠牲であれば `true`。
|
|
160
|
+
*/
|
|
161
|
+
declare function isDeadlockVictim(error: unknown): boolean;
|
|
162
|
+
/**
|
|
163
|
+
* Reports whether a failure carries the driver's proof that the server already rolled back.
|
|
164
|
+
*
|
|
165
|
+
* サーバが既にロールバックしたことの証拠を、その失敗が持っているかを判定する処理。
|
|
166
|
+
*
|
|
167
|
+
* ⚠️ **これは再実行の根拠ではない。** サーバは `XACT_ABORT ON` 下の実行時エラーでも重大度 16 以上の
|
|
168
|
+
* エラーでも自分で巻き戻すため、`EABORT` は「一時的である」ことを何も示さない。用途は 2 つだけ —
|
|
169
|
+
* 何もコミットされていないことの確認と、原因が置き換えられた失敗の見分けである。
|
|
170
|
+
*
|
|
171
|
+
* @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。
|
|
172
|
+
* @returns ロールバック済みが確定していれば `true`。
|
|
173
|
+
*/
|
|
174
|
+
declare function isRolledBackByServer(error: unknown): boolean;
|
|
175
|
+
/**
|
|
176
|
+
* Runs a unit of work, running it again while SQL Server keeps choosing it as the deadlock victim.
|
|
177
|
+
*
|
|
178
|
+
* 1 つの作業単位を実行し、SQL Server がデッドロックの犠牲に選び続ける間は実行し直す処理。
|
|
179
|
+
*
|
|
180
|
+
* `work` は {@link CaptureCause} を受け取る。トランザクションの閉包の**内側**をそれで包むこと —
|
|
181
|
+
* ORM が原因を `EABORT` へ置き換える前に押さえるための唯一の手立てであり、包まなければ
|
|
182
|
+
* デッドロックであっても再実行されない。
|
|
183
|
+
*
|
|
184
|
+
* ```ts
|
|
185
|
+
* await runWithTransactionRetry((capture) => db.transaction((tx) => capture(() => work(tx))))
|
|
186
|
+
* ```
|
|
187
|
+
*
|
|
188
|
+
* **`work` は毎回はじめから走る。** 部分的な再開はしない — 再試行が正しいのは「何も起きなかった」
|
|
189
|
+
* 場合だけであり、途中から再開することはその前提を壊す。したがって `work` は DB の外へ副作用を
|
|
190
|
+
* 持ってはならない (トランザクションのロールバックで元に戻らないため、これは再試行の有無に
|
|
191
|
+
* 関わらず要求される性質である)。
|
|
192
|
+
*
|
|
193
|
+
* **既に外側のトランザクションに居るときは呼ばないこと。** 再試行の判断はそれを開いた側が持つ。
|
|
194
|
+
* 内側だけをやり直すと、外側が既に書いた分を巻き戻さずに重ねることになる。
|
|
195
|
+
*
|
|
196
|
+
* @param work - 実行する作業単位。トランザクション全体を含むこと。
|
|
197
|
+
* @param options - 再試行の設定。
|
|
198
|
+
* @returns `work` の戻り値。
|
|
199
|
+
* @throws 押さえた原本があり、送出された失敗が `EABORT` でそれを覆い隠している場合はその原本。
|
|
200
|
+
* それ以外は送出された失敗をそのまま。
|
|
201
|
+
*/
|
|
202
|
+
declare function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T>;
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* @module timestamp
|
|
206
|
+
* Reads what the driver returned for a datetime column as an unambiguous instant.
|
|
207
|
+
* 日時列としてドライバが返した値を、曖昧さなく瞬間として読む処理。
|
|
208
|
+
*
|
|
209
|
+
* SQL Server の `datetime2` は時間帯を持たない。ドライバは通常 `Date` を組み立てて返すが、
|
|
210
|
+
* 設定や経路によっては文字列のまま渡ってくる。その文字列にはオフセットが付かない。
|
|
211
|
+
*/
|
|
212
|
+
/**
|
|
213
|
+
* Reads a driver timestamp as an instant, treating an offset-less string as UTC.
|
|
214
|
+
*
|
|
215
|
+
* ドライバの時刻を瞬間として読む処理 (オフセットの無い文字列は UTC として解釈)。
|
|
216
|
+
*
|
|
217
|
+
* ⚠️ オフセットを持たない ISO 文字列 (`2026-09-09 03:04:05.000`) は仕様上 **実行環境の時間帯**
|
|
218
|
+
* で解釈される。ドライバは通常 `Date` を返すのでこの経路は普段通らないが、通った日に JST なら
|
|
219
|
+
* 9 時間ずれる — 鮮度は「常に古い」と報告され、締切の比較は 9 時間ぶん甘くなる。読む場所ごとに
|
|
220
|
+
* 対処すると必ずどこかが漏れるので、1 つの関数に閉じる。
|
|
221
|
+
*
|
|
222
|
+
* ⚠️ **読めない値は `Invalid Date` として返す。** ここで投げると、1 行の壊れた値が一覧全体を
|
|
223
|
+
* 落とす。判定は呼び出し側が `Number.isNaN(d.getTime())` で行う。
|
|
224
|
+
*
|
|
225
|
+
* @param value - What the driver returned. ドライバが返した値。
|
|
226
|
+
* @returns The instant. その瞬間。
|
|
227
|
+
*/
|
|
228
|
+
declare function toInstant(value: string | Date): Date;
|
|
229
|
+
|
|
230
|
+
export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, toInstant };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SQL Server parameter-limit helpers shared by every batched statement.
|
|
3
|
+
* 一括文が共有する SQL Server のパラメータ上限まわりのヘルパー。
|
|
4
|
+
*
|
|
5
|
+
* ⚠️ 上限は **行数ではなくパラメータ数** である。1 行あたり何個の値を束ねるかは文ごとに違うので、
|
|
6
|
+
* 行数だけで分割すると、列の多い `VALUES` が静かに上限を越える。しかも越えるのは件数が閾値を
|
|
7
|
+
* 跨いだ日だけで、それまでは同じコードが問題なく動いて見える。
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Hard limit of parameters per statement. 1 文あたりのパラメータ数の上限。
|
|
11
|
+
*
|
|
12
|
+
* SQL Server の RPC 1 回あたりのパラメータ上限は 2100。数個は文自身の値 (`SET` 句・スカラー
|
|
13
|
+
* 述語) が使うため、分割の基準にはここから余裕を引いた値を用いる。
|
|
14
|
+
*/
|
|
15
|
+
declare const MAX_PARAMETERS = 2100;
|
|
16
|
+
/** Parameters reserved for the statement's own scalar values. 文自身のスカラー値のための予約枠。 */
|
|
17
|
+
declare const RESERVED_PARAMETERS = 100;
|
|
18
|
+
/**
|
|
19
|
+
* Maximum ids per `IN` list of single-column predicates. 単列述語の `IN` 句 1 回あたりの最大 ID 数。
|
|
20
|
+
*
|
|
21
|
+
* 1 行 1 パラメータの用途 (`inArray(col, ids)`) 専用の既定値である。複数列を束ねる `VALUES` や、
|
|
22
|
+
* 1 文に `IN` を 2 つ描画する `UPDATE` にそのまま使ってはならない — {@link chunkByParameters} を使う。
|
|
23
|
+
*/
|
|
24
|
+
declare const MAX_IN_LIST = 500;
|
|
25
|
+
/**
|
|
26
|
+
* Splits a list into chunks that fit one statement.
|
|
27
|
+
* 1 文に収まる大きさへリストを分割する処理。
|
|
28
|
+
*
|
|
29
|
+
* @param items - Items to split. 分割対象。
|
|
30
|
+
* @param size - Maximum chunk size. 1 チャンクの最大数。
|
|
31
|
+
* @returns Chunks in the original order. 元の順序を保ったチャンク列。
|
|
32
|
+
* @throws {TypeError} When the size is not a positive integer. 正の整数でない場合。
|
|
33
|
+
*/
|
|
34
|
+
declare function chunk<T>(items: readonly T[], size?: number): T[][];
|
|
35
|
+
/**
|
|
36
|
+
* Splits a list so each chunk fits the parameter budget of one statement.
|
|
37
|
+
* 各チャンクが 1 文のパラメータ枠に収まるようリストを分割する処理。
|
|
38
|
+
*
|
|
39
|
+
* `VALUES` は 1 行につき列数ぶんのパラメータを束ねる。7 列の台帳行なら 500 行で 3500 個になり、
|
|
40
|
+
* 上限 2100 を越えて **実行される前に** 拒否される。しかもその失敗は再試行しても同じ場所で起き、
|
|
41
|
+
* そのグループは永久に台帳を持てない。
|
|
42
|
+
*
|
|
43
|
+
* @param items - Items to split. 分割対象。
|
|
44
|
+
* @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。
|
|
45
|
+
* @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。
|
|
46
|
+
* @returns Chunks in the original order. 元の順序を保ったチャンク列。
|
|
47
|
+
* @throws {TypeError} When a single item cannot fit the budget. 1 件すら収まらない場合。
|
|
48
|
+
*/
|
|
49
|
+
declare function chunkByParameters<T>(items: readonly T[], parametersPerItem: number, reservedParameters?: number): T[][];
|
|
50
|
+
/**
|
|
51
|
+
* Reports how many items fit one statement's parameter budget.
|
|
52
|
+
* 1 文のパラメータ枠に収まる件数を返す処理。
|
|
53
|
+
*
|
|
54
|
+
* {@link chunkByParameters} が使う算術を、分割せずに取り出したいときの入口である。呼び出し側が
|
|
55
|
+
* 別の上限 ({@link MAX_IN_LIST} など) と併せて小さい方を採るような場合に使う — **予算そのものを
|
|
56
|
+
* 呼び出し側で組み直してはならない。** `MAX_PARAMETERS` から引き算した値をリテラルで書くと、
|
|
57
|
+
* 上限や予約枠が変わってもそこだけ追従しない。
|
|
58
|
+
*
|
|
59
|
+
* @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。
|
|
60
|
+
* @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。
|
|
61
|
+
* @returns 1 文へ載せられる件数 (1 以上)。
|
|
62
|
+
* @throws {TypeError} When an argument is invalid, or a single item cannot fit the budget.
|
|
63
|
+
* 引数が不正な場合、または 1 件すら収まらない場合。
|
|
64
|
+
*/
|
|
65
|
+
declare function chunkSizeForParameters(parametersPerItem: number, reservedParameters?: number): number;
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* @module retry
|
|
69
|
+
* Runs a SQL Server transaction again when — and only when — the failure was a deadlock.
|
|
70
|
+
* SQL Server のトランザクションを、失敗がデッドロックであった場合に**限って**やり直す処理。
|
|
71
|
+
*
|
|
72
|
+
* A transaction raises the cost of contention. Two units of work whose key ranges overlap can
|
|
73
|
+
* deadlock, and SQL Server resolves a deadlock by rolling one of them back. Under SERIALIZABLE the
|
|
74
|
+
* ranges are widest, so the chance is highest — but nothing here is specific to an isolation level,
|
|
75
|
+
* a schema, or an application.
|
|
76
|
+
* トランザクションは競合の代償を上げる。鍵の範囲が重なる 2 つの作業単位はデッドロックしうるし、
|
|
77
|
+
* SQL Server はデッドロックを片方のロールバックで解く。SERIALIZABLE では範囲が最も広いため確率が
|
|
78
|
+
* 最も高いが、本モジュールは分離レベル・スキーマ・アプリケーションのいずれにも依存しない。
|
|
79
|
+
*
|
|
80
|
+
* **Two conditions must both hold before a unit of work may be run again**, and they are different
|
|
81
|
+
* questions. Nothing may have been committed — otherwise the retry applies the same change twice.
|
|
82
|
+
* And the failure must be transient — otherwise the retry fails identically, three times slower,
|
|
83
|
+
* for nothing.
|
|
84
|
+
* **再実行が許されるには 2 つの条件が揃わねばならず**、それらは別の問いである。何もコミットされて
|
|
85
|
+
* いないこと — さもなくば同じ変更を 2 度適用する。そして失敗が一時的であること — さもなくば同じ
|
|
86
|
+
* 失敗を 3 倍遅く繰り返すだけになる。
|
|
87
|
+
*
|
|
88
|
+
* デッドロックの犠牲 (エラー番号 `1205`) は、その 1 つの事実で両方を満たす。犠牲は必ず巻き戻され、
|
|
89
|
+
* かつ競合相手が去れば通る。だから本モジュールが認める根拠はそれだけである。
|
|
90
|
+
*
|
|
91
|
+
* ⚠️ **サーバが巻き戻したことは、一時的であることの証拠ではない。** サーバは `XACT_ABORT ON` 下の
|
|
92
|
+
* 実行時エラーでも重大度 16 以上のエラーでも自分で巻き戻す。それらは何度やり直しても同じ結果に
|
|
93
|
+
* なる。`EABORT` ({@link isRolledBackByServer}) を再実行の根拠にしてはならない — 判定に使うのは
|
|
94
|
+
* 「何もコミットされていない」ことの確認までである。
|
|
95
|
+
*
|
|
96
|
+
* ⚠️ **ORM は原因を破壊する。** `drizzle-orm` の `node-mssql` セッションは `catch` の中で
|
|
97
|
+
* `rollback()` を先に呼び、サーバが既に巻き戻していればそのロールバックが
|
|
98
|
+
* `TransactionError('EABORT')` を投げる。`mssql` の `TransactionError` は `(message, code)` しか
|
|
99
|
+
* 受け取らず `cause` を持たないため、元の失敗 (`1205` など) は**痕跡なく消える**。そこで本モジュール
|
|
100
|
+
* は閉包を包む {@link CaptureCause} を呼び出し元へ渡し、原因が失われる前に押さえる。押さえた原因は
|
|
101
|
+
* 再実行の判定に使われ、諦めるときは `EABORT` の代わりに送出される。
|
|
102
|
+
*
|
|
103
|
+
* ⚠️ **Driver-agnostic by duck typing.** ドライバのエラー型を `import` しない — `mssql` /
|
|
104
|
+
* `tedious` / ORM のいずれにも依存させないためである。判定は `code` と `number` という、
|
|
105
|
+
* SQL Server 系ドライバが一様に載せる 2 つのプロパティだけを見る。
|
|
106
|
+
*/
|
|
107
|
+
/** 試行回数の既定。初回 1 回 + 再試行 2 回。 */
|
|
108
|
+
declare const DEFAULT_TRANSACTION_ATTEMPTS = 3;
|
|
109
|
+
/**
|
|
110
|
+
* Wraps the transaction body so the original failure is kept before the ORM can replace it.
|
|
111
|
+
* トランザクションの閉包を包み、ORM が置き換える前に元の失敗を押さえる関数の型。
|
|
112
|
+
*
|
|
113
|
+
* 呼び出し元は閉包の**内側**をこれで包む。包まなくても動くが、そのときは原因を押さえられないため、
|
|
114
|
+
* デッドロックであっても再実行されない (安全側に倒れる)。
|
|
115
|
+
*/
|
|
116
|
+
type CaptureCause = <R>(body: () => Promise<R>) => Promise<R>;
|
|
117
|
+
/** 1 回の再試行の内訳。呼び出し元が記録・計数するために受け取る。 */
|
|
118
|
+
type TransactionRetryInfo = {
|
|
119
|
+
/** 失敗した試行の番号 (1 起点)。 */
|
|
120
|
+
readonly attempt: number;
|
|
121
|
+
/** 許された試行の総数。 */
|
|
122
|
+
readonly attempts: number;
|
|
123
|
+
/** 呼び出しが送出した失敗。ORM による置き換えにより `EABORT` であることが多い。 */
|
|
124
|
+
readonly error: unknown;
|
|
125
|
+
/** 閉包が投げた原本。{@link CaptureCause} を通していなければ `undefined`。 */
|
|
126
|
+
readonly cause: unknown;
|
|
127
|
+
};
|
|
128
|
+
/** 再試行の設定。既定のまま使えるが、試験と記録のために各項目を差し替えられる。 */
|
|
129
|
+
type TransactionRetryOptions = {
|
|
130
|
+
/**
|
|
131
|
+
* 試行回数 (初回を含む)。既定は {@link DEFAULT_TRANSACTION_ATTEMPTS}。
|
|
132
|
+
* `1` を与えると再試行しない。
|
|
133
|
+
*/
|
|
134
|
+
readonly attempts?: number;
|
|
135
|
+
/**
|
|
136
|
+
* 次の試行までの待機。既定は倍化 + ゆらぎ。
|
|
137
|
+
*
|
|
138
|
+
* ゆらぎを入れるのは、同時に犠牲となった複数の要求が揃って同じ時刻に再試行し、同じ競合を
|
|
139
|
+
* もう一度起こすことを避けるため。試験では即時解決する関数を渡す。
|
|
140
|
+
*/
|
|
141
|
+
readonly delay?: (attempt: number) => Promise<void>;
|
|
142
|
+
/**
|
|
143
|
+
* 再試行する直前に呼ばれる。既定は何もしない。
|
|
144
|
+
*
|
|
145
|
+
* **黙って再試行してはならない。** 再試行が成功すると利用者からは何も起きなかったように
|
|
146
|
+
* 見えるが、競合が起きていること自体は運用上の事実である。記録の口を呼び出し元へ渡す。
|
|
147
|
+
*/
|
|
148
|
+
readonly onRetry?: (info: TransactionRetryInfo) => void;
|
|
149
|
+
};
|
|
150
|
+
/**
|
|
151
|
+
* Reports whether a failure is SQL Server's deadlock victim.
|
|
152
|
+
*
|
|
153
|
+
* その失敗が SQL Server の選んだデッドロックの犠牲かを判定する処理。
|
|
154
|
+
*
|
|
155
|
+
* 犠牲は必ずロールバックされる (何もコミットされていない) 上に、競合相手が去ればやり直しは通る。
|
|
156
|
+
* **再実行を許してよい唯一の根拠**である。
|
|
157
|
+
*
|
|
158
|
+
* @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。
|
|
159
|
+
* @returns デッドロックの犠牲であれば `true`。
|
|
160
|
+
*/
|
|
161
|
+
declare function isDeadlockVictim(error: unknown): boolean;
|
|
162
|
+
/**
|
|
163
|
+
* Reports whether a failure carries the driver's proof that the server already rolled back.
|
|
164
|
+
*
|
|
165
|
+
* サーバが既にロールバックしたことの証拠を、その失敗が持っているかを判定する処理。
|
|
166
|
+
*
|
|
167
|
+
* ⚠️ **これは再実行の根拠ではない。** サーバは `XACT_ABORT ON` 下の実行時エラーでも重大度 16 以上の
|
|
168
|
+
* エラーでも自分で巻き戻すため、`EABORT` は「一時的である」ことを何も示さない。用途は 2 つだけ —
|
|
169
|
+
* 何もコミットされていないことの確認と、原因が置き換えられた失敗の見分けである。
|
|
170
|
+
*
|
|
171
|
+
* @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。
|
|
172
|
+
* @returns ロールバック済みが確定していれば `true`。
|
|
173
|
+
*/
|
|
174
|
+
declare function isRolledBackByServer(error: unknown): boolean;
|
|
175
|
+
/**
|
|
176
|
+
* Runs a unit of work, running it again while SQL Server keeps choosing it as the deadlock victim.
|
|
177
|
+
*
|
|
178
|
+
* 1 つの作業単位を実行し、SQL Server がデッドロックの犠牲に選び続ける間は実行し直す処理。
|
|
179
|
+
*
|
|
180
|
+
* `work` は {@link CaptureCause} を受け取る。トランザクションの閉包の**内側**をそれで包むこと —
|
|
181
|
+
* ORM が原因を `EABORT` へ置き換える前に押さえるための唯一の手立てであり、包まなければ
|
|
182
|
+
* デッドロックであっても再実行されない。
|
|
183
|
+
*
|
|
184
|
+
* ```ts
|
|
185
|
+
* await runWithTransactionRetry((capture) => db.transaction((tx) => capture(() => work(tx))))
|
|
186
|
+
* ```
|
|
187
|
+
*
|
|
188
|
+
* **`work` は毎回はじめから走る。** 部分的な再開はしない — 再試行が正しいのは「何も起きなかった」
|
|
189
|
+
* 場合だけであり、途中から再開することはその前提を壊す。したがって `work` は DB の外へ副作用を
|
|
190
|
+
* 持ってはならない (トランザクションのロールバックで元に戻らないため、これは再試行の有無に
|
|
191
|
+
* 関わらず要求される性質である)。
|
|
192
|
+
*
|
|
193
|
+
* **既に外側のトランザクションに居るときは呼ばないこと。** 再試行の判断はそれを開いた側が持つ。
|
|
194
|
+
* 内側だけをやり直すと、外側が既に書いた分を巻き戻さずに重ねることになる。
|
|
195
|
+
*
|
|
196
|
+
* @param work - 実行する作業単位。トランザクション全体を含むこと。
|
|
197
|
+
* @param options - 再試行の設定。
|
|
198
|
+
* @returns `work` の戻り値。
|
|
199
|
+
* @throws 押さえた原本があり、送出された失敗が `EABORT` でそれを覆い隠している場合はその原本。
|
|
200
|
+
* それ以外は送出された失敗をそのまま。
|
|
201
|
+
*/
|
|
202
|
+
declare function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T>;
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* @module timestamp
|
|
206
|
+
* Reads what the driver returned for a datetime column as an unambiguous instant.
|
|
207
|
+
* 日時列としてドライバが返した値を、曖昧さなく瞬間として読む処理。
|
|
208
|
+
*
|
|
209
|
+
* SQL Server の `datetime2` は時間帯を持たない。ドライバは通常 `Date` を組み立てて返すが、
|
|
210
|
+
* 設定や経路によっては文字列のまま渡ってくる。その文字列にはオフセットが付かない。
|
|
211
|
+
*/
|
|
212
|
+
/**
|
|
213
|
+
* Reads a driver timestamp as an instant, treating an offset-less string as UTC.
|
|
214
|
+
*
|
|
215
|
+
* ドライバの時刻を瞬間として読む処理 (オフセットの無い文字列は UTC として解釈)。
|
|
216
|
+
*
|
|
217
|
+
* ⚠️ オフセットを持たない ISO 文字列 (`2026-09-09 03:04:05.000`) は仕様上 **実行環境の時間帯**
|
|
218
|
+
* で解釈される。ドライバは通常 `Date` を返すのでこの経路は普段通らないが、通った日に JST なら
|
|
219
|
+
* 9 時間ずれる — 鮮度は「常に古い」と報告され、締切の比較は 9 時間ぶん甘くなる。読む場所ごとに
|
|
220
|
+
* 対処すると必ずどこかが漏れるので、1 つの関数に閉じる。
|
|
221
|
+
*
|
|
222
|
+
* ⚠️ **読めない値は `Invalid Date` として返す。** ここで投げると、1 行の壊れた値が一覧全体を
|
|
223
|
+
* 落とす。判定は呼び出し側が `Number.isNaN(d.getTime())` で行う。
|
|
224
|
+
*
|
|
225
|
+
* @param value - What the driver returned. ドライバが返した値。
|
|
226
|
+
* @returns The instant. その瞬間。
|
|
227
|
+
*/
|
|
228
|
+
declare function toInstant(value: string | Date): Date;
|
|
229
|
+
|
|
230
|
+
export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, toInstant };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
"use strict";var c=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)c(e,t,{get:n[t],enumerable:!0})},b=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of y(n))!A.call(e,o)&&o!==t&&c(e,o,{get:()=>n[o],enumerable:!(r=f(n,o))||r.enumerable});return e};var w=e=>b(c({},"__esModule",{value:!0}),e);var x={};R(x,{DEFAULT_TRANSACTION_ATTEMPTS:()=>N,MAX_IN_LIST:()=>P,MAX_PARAMETERS:()=>g,RESERVED_PARAMETERS:()=>I,chunk:()=>T,chunkByParameters:()=>_,chunkSizeForParameters:()=>d,isDeadlockVictim:()=>l,isRolledBackByServer:()=>p,runWithTransactionRetry:()=>M,toInstant:()=>k});module.exports=w(x);var g=2100,I=100,P=500;function T(e,n=500){if(!Number.isInteger(n)||n<=0)throw new TypeError(`[@aiquants/mssql] chunk size must be a positive integer, received ${String(n)}`);let t=[];for(let r=0;r<e.length;r+=n)t.push(e.slice(r,r+n));return t}function _(e,n,t=100){return T(e,d(n,t))}function d(e,n=100){if(!Number.isInteger(e)||e<=0)throw new TypeError(`[@aiquants/mssql] parametersPerItem must be a positive integer, received ${String(e)}`);if(!Number.isInteger(n)||n<0)throw new TypeError(`[@aiquants/mssql] reservedParameters must be a non-negative integer, received ${String(n)}`);let t=2100-n,r=Math.floor(t/e);if(r<1)throw new TypeError(`[@aiquants/mssql] a single item binds ${e} parameters, which exceeds the ${t} available in one statement`);return r}var N=3;var h="EABORT";function E(e,n){let t=e;for(let r=0;r<5&&t!==null&&t!==void 0;r+=1){if(typeof t!="object")return!1;let o=t;if(n(o))return!0;t=o.cause}return!1}function l(e){return E(e,n=>n.number===1205)}function p(e){return E(e,n=>n.code===h)}var S=globalThis.setTimeout;function D(e){let t=50*2**(e-1)*(.75+Math.random()*.5);return new Promise(r=>S(r,Math.round(t)))}async function M(e,n){let t=n?.attempts??3,r=n?.delay??D;for(let o=1;;o+=1){let u,i=!1,m=async a=>{try{return await a()}catch(s){throw u=s,i=!0,s}};try{return await e(m)}catch(a){let s=i?u:void 0;if(o<t&&l(i?u:a)){n?.onRetry?.({attempt:o,attempts:t,error:a,cause:s}),await r(o);continue}throw i&&p(a)?u:a}}}function k(e){return e instanceof Date?e:new Date(/(?:Z|[+-]\d{2}:?\d{2})$/.test(e)?e:`${e.replace(" ","T")}Z`)}0&&(module.exports={DEFAULT_TRANSACTION_ATTEMPTS,MAX_IN_LIST,MAX_PARAMETERS,RESERVED_PARAMETERS,chunk,chunkByParameters,chunkSizeForParameters,isDeadlockVictim,isRolledBackByServer,runWithTransactionRetry,toInstant});
|
|
2
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/limits.ts","../src/retry.ts","../src/timestamp.ts"],"sourcesContent":["export * from \"./limits\"\nexport * from \"./retry\"\nexport * from \"./timestamp\"\n","/**\n * SQL Server parameter-limit helpers shared by every batched statement.\n * 一括文が共有する SQL Server のパラメータ上限まわりのヘルパー。\n *\n * ⚠️ 上限は **行数ではなくパラメータ数** である。1 行あたり何個の値を束ねるかは文ごとに違うので、\n * 行数だけで分割すると、列の多い `VALUES` が静かに上限を越える。しかも越えるのは件数が閾値を\n * 跨いだ日だけで、それまでは同じコードが問題なく動いて見える。\n */\n\n/**\n * Hard limit of parameters per statement. 1 文あたりのパラメータ数の上限。\n *\n * SQL Server の RPC 1 回あたりのパラメータ上限は 2100。数個は文自身の値 (`SET` 句・スカラー\n * 述語) が使うため、分割の基準にはここから余裕を引いた値を用いる。\n */\nexport const MAX_PARAMETERS = 2100\n\n/** Parameters reserved for the statement's own scalar values. 文自身のスカラー値のための予約枠。 */\nexport const RESERVED_PARAMETERS = 100\n\n/**\n * Maximum ids per `IN` list of single-column predicates. 単列述語の `IN` 句 1 回あたりの最大 ID 数。\n *\n * 1 行 1 パラメータの用途 (`inArray(col, ids)`) 専用の既定値である。複数列を束ねる `VALUES` や、\n * 1 文に `IN` を 2 つ描画する `UPDATE` にそのまま使ってはならない — {@link chunkByParameters} を使う。\n */\nexport const MAX_IN_LIST = 500\n\n/**\n * Splits a list into chunks that fit one statement.\n * 1 文に収まる大きさへリストを分割する処理。\n *\n * @param items - Items to split. 分割対象。\n * @param size - Maximum chunk size. 1 チャンクの最大数。\n * @returns Chunks in the original order. 元の順序を保ったチャンク列。\n * @throws {TypeError} When the size is not a positive integer. 正の整数でない場合。\n */\nexport function chunk<T>(items: readonly T[], size = MAX_IN_LIST): T[][] {\n if (!Number.isInteger(size) || size <= 0) throw new TypeError(`[@aiquants/mssql] chunk size must be a positive integer, received ${String(size)}`)\n const out: T[][] = []\n for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size))\n return out\n}\n\n/**\n * Splits a list so each chunk fits the parameter budget of one statement.\n * 各チャンクが 1 文のパラメータ枠に収まるようリストを分割する処理。\n *\n * `VALUES` は 1 行につき列数ぶんのパラメータを束ねる。7 列の台帳行なら 500 行で 3500 個になり、\n * 上限 2100 を越えて **実行される前に** 拒否される。しかもその失敗は再試行しても同じ場所で起き、\n * そのグループは永久に台帳を持てない。\n *\n * @param items - Items to split. 分割対象。\n * @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。\n * @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。\n * @returns Chunks in the original order. 元の順序を保ったチャンク列。\n * @throws {TypeError} When a single item cannot fit the budget. 1 件すら収まらない場合。\n */\nexport function chunkByParameters<T>(items: readonly T[], parametersPerItem: number, reservedParameters = RESERVED_PARAMETERS): T[][] {\n return chunk(items, chunkSizeForParameters(parametersPerItem, reservedParameters))\n}\n\n/**\n * Reports how many items fit one statement's parameter budget.\n * 1 文のパラメータ枠に収まる件数を返す処理。\n *\n * {@link chunkByParameters} が使う算術を、分割せずに取り出したいときの入口である。呼び出し側が\n * 別の上限 ({@link MAX_IN_LIST} など) と併せて小さい方を採るような場合に使う — **予算そのものを\n * 呼び出し側で組み直してはならない。** `MAX_PARAMETERS` から引き算した値をリテラルで書くと、\n * 上限や予約枠が変わってもそこだけ追従しない。\n *\n * @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。\n * @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。\n * @returns 1 文へ載せられる件数 (1 以上)。\n * @throws {TypeError} When an argument is invalid, or a single item cannot fit the budget.\n * 引数が不正な場合、または 1 件すら収まらない場合。\n */\nexport function chunkSizeForParameters(parametersPerItem: number, reservedParameters = RESERVED_PARAMETERS): number {\n if (!Number.isInteger(parametersPerItem) || parametersPerItem <= 0) {\n throw new TypeError(`[@aiquants/mssql] parametersPerItem must be a positive integer, received ${String(parametersPerItem)}`)\n }\n if (!Number.isInteger(reservedParameters) || reservedParameters < 0) {\n throw new TypeError(`[@aiquants/mssql] reservedParameters must be a non-negative integer, received ${String(reservedParameters)}`)\n }\n const budget = MAX_PARAMETERS - reservedParameters\n const size = Math.floor(budget / parametersPerItem)\n // 1 件すら収まらないなら、分割では解決しない。黙って 1 件ずつ発行すると、実行時に必ず\n // 落ちる文をひたすら送り続けることになる\n if (size < 1) throw new TypeError(`[@aiquants/mssql] a single item binds ${parametersPerItem} parameters, which exceeds the ${budget} available in one statement`)\n return size\n}\n","/**\n * @module retry\n * Runs a SQL Server transaction again when — and only when — the failure was a deadlock.\n * SQL Server のトランザクションを、失敗がデッドロックであった場合に**限って**やり直す処理。\n *\n * A transaction raises the cost of contention. Two units of work whose key ranges overlap can\n * deadlock, and SQL Server resolves a deadlock by rolling one of them back. Under SERIALIZABLE the\n * ranges are widest, so the chance is highest — but nothing here is specific to an isolation level,\n * a schema, or an application.\n * トランザクションは競合の代償を上げる。鍵の範囲が重なる 2 つの作業単位はデッドロックしうるし、\n * SQL Server はデッドロックを片方のロールバックで解く。SERIALIZABLE では範囲が最も広いため確率が\n * 最も高いが、本モジュールは分離レベル・スキーマ・アプリケーションのいずれにも依存しない。\n *\n * **Two conditions must both hold before a unit of work may be run again**, and they are different\n * questions. Nothing may have been committed — otherwise the retry applies the same change twice.\n * And the failure must be transient — otherwise the retry fails identically, three times slower,\n * for nothing.\n * **再実行が許されるには 2 つの条件が揃わねばならず**、それらは別の問いである。何もコミットされて\n * いないこと — さもなくば同じ変更を 2 度適用する。そして失敗が一時的であること — さもなくば同じ\n * 失敗を 3 倍遅く繰り返すだけになる。\n *\n * デッドロックの犠牲 (エラー番号 `1205`) は、その 1 つの事実で両方を満たす。犠牲は必ず巻き戻され、\n * かつ競合相手が去れば通る。だから本モジュールが認める根拠はそれだけである。\n *\n * ⚠️ **サーバが巻き戻したことは、一時的であることの証拠ではない。** サーバは `XACT_ABORT ON` 下の\n * 実行時エラーでも重大度 16 以上のエラーでも自分で巻き戻す。それらは何度やり直しても同じ結果に\n * なる。`EABORT` ({@link isRolledBackByServer}) を再実行の根拠にしてはならない — 判定に使うのは\n * 「何もコミットされていない」ことの確認までである。\n *\n * ⚠️ **ORM は原因を破壊する。** `drizzle-orm` の `node-mssql` セッションは `catch` の中で\n * `rollback()` を先に呼び、サーバが既に巻き戻していればそのロールバックが\n * `TransactionError('EABORT')` を投げる。`mssql` の `TransactionError` は `(message, code)` しか\n * 受け取らず `cause` を持たないため、元の失敗 (`1205` など) は**痕跡なく消える**。そこで本モジュール\n * は閉包を包む {@link CaptureCause} を呼び出し元へ渡し、原因が失われる前に押さえる。押さえた原因は\n * 再実行の判定に使われ、諦めるときは `EABORT` の代わりに送出される。\n *\n * ⚠️ **Driver-agnostic by duck typing.** ドライバのエラー型を `import` しない — `mssql` /\n * `tedious` / ORM のいずれにも依存させないためである。判定は `code` と `number` という、\n * SQL Server 系ドライバが一様に載せる 2 つのプロパティだけを見る。\n */\n\n/** 試行回数の既定。初回 1 回 + 再試行 2 回。 */\nexport const DEFAULT_TRANSACTION_ATTEMPTS = 3\n\n/** 既定の待機の基準値 (ミリ秒)。試行ごとに倍化する。 */\nconst DEFAULT_BASE_DELAY_MS = 50\n\n/** 原因の連鎖を辿る深さの上限。循環する `cause` で止まらなくなることを防ぐ。 */\nconst MAX_CAUSE_DEPTH = 5\n\n/** SQL Server がデッドロックの犠牲として選んだ要求に返すエラー番号。犠牲は必ずロールバックされる。 */\nconst DEADLOCK_VICTIM_NUMBER = 1205\n\n/**\n * The `mssql` driver's code for a transaction the server rolled back on its own.\n * サーバ自身がロールバックしたトランザクションを表す `mssql` ドライバのコード。\n *\n * `tedious` の `rollbackTransaction` イベントを受けて立つ。すなわち「ロールバックが**済んでいる**」\n * ことの表明であって、その原因が一時的であることは何も意味しない。\n */\nconst SERVER_ROLLBACK_CODE = \"EABORT\"\n\n/**\n * Wraps the transaction body so the original failure is kept before the ORM can replace it.\n * トランザクションの閉包を包み、ORM が置き換える前に元の失敗を押さえる関数の型。\n *\n * 呼び出し元は閉包の**内側**をこれで包む。包まなくても動くが、そのときは原因を押さえられないため、\n * デッドロックであっても再実行されない (安全側に倒れる)。\n */\nexport type CaptureCause = <R>(body: () => Promise<R>) => Promise<R>\n\n/** 1 回の再試行の内訳。呼び出し元が記録・計数するために受け取る。 */\nexport type TransactionRetryInfo = {\n /** 失敗した試行の番号 (1 起点)。 */\n readonly attempt: number\n /** 許された試行の総数。 */\n readonly attempts: number\n /** 呼び出しが送出した失敗。ORM による置き換えにより `EABORT` であることが多い。 */\n readonly error: unknown\n /** 閉包が投げた原本。{@link CaptureCause} を通していなければ `undefined`。 */\n readonly cause: unknown\n}\n\n/** 再試行の設定。既定のまま使えるが、試験と記録のために各項目を差し替えられる。 */\nexport type TransactionRetryOptions = {\n /**\n * 試行回数 (初回を含む)。既定は {@link DEFAULT_TRANSACTION_ATTEMPTS}。\n * `1` を与えると再試行しない。\n */\n readonly attempts?: number\n /**\n * 次の試行までの待機。既定は倍化 + ゆらぎ。\n *\n * ゆらぎを入れるのは、同時に犠牲となった複数の要求が揃って同じ時刻に再試行し、同じ競合を\n * もう一度起こすことを避けるため。試験では即時解決する関数を渡す。\n */\n readonly delay?: (attempt: number) => Promise<void>\n /**\n * 再試行する直前に呼ばれる。既定は何もしない。\n *\n * **黙って再試行してはならない。** 再試行が成功すると利用者からは何も起きなかったように\n * 見えるが、競合が起きていること自体は運用上の事実である。記録の口を呼び出し元へ渡す。\n */\n readonly onRetry?: (info: TransactionRetryInfo) => void\n}\n\n/**\n * Walks a failure and its causes, reporting whether any of them matches.\n *\n * 失敗とその原因の連鎖を辿り、いずれかが条件に合うかを判定する処理。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @param matches - 1 段ごとに当てる条件。\n * @returns いずれかの段が条件に合えば `true`。\n */\nfunction anyCause(error: unknown, matches: (candidate: { code?: unknown; number?: unknown }) => boolean): boolean {\n let current = error\n for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== null && current !== undefined; depth += 1) {\n if (typeof current !== \"object\") return false\n const candidate = current as { code?: unknown; number?: unknown; cause?: unknown }\n if (matches(candidate)) return true\n current = candidate.cause\n }\n return false\n}\n\n/**\n * Reports whether a failure is SQL Server's deadlock victim.\n *\n * その失敗が SQL Server の選んだデッドロックの犠牲かを判定する処理。\n *\n * 犠牲は必ずロールバックされる (何もコミットされていない) 上に、競合相手が去ればやり直しは通る。\n * **再実行を許してよい唯一の根拠**である。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @returns デッドロックの犠牲であれば `true`。\n */\nexport function isDeadlockVictim(error: unknown): boolean {\n return anyCause(error, (candidate) => candidate.number === DEADLOCK_VICTIM_NUMBER)\n}\n\n/**\n * Reports whether a failure carries the driver's proof that the server already rolled back.\n *\n * サーバが既にロールバックしたことの証拠を、その失敗が持っているかを判定する処理。\n *\n * ⚠️ **これは再実行の根拠ではない。** サーバは `XACT_ABORT ON` 下の実行時エラーでも重大度 16 以上の\n * エラーでも自分で巻き戻すため、`EABORT` は「一時的である」ことを何も示さない。用途は 2 つだけ —\n * 何もコミットされていないことの確認と、原因が置き換えられた失敗の見分けである。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @returns ロールバック済みが確定していれば `true`。\n */\nexport function isRolledBackByServer(error: unknown): boolean {\n return anyCause(error, (candidate) => candidate.code === SERVER_ROLLBACK_CODE)\n}\n\n/*\n * 本パッケージの `lib` は `ES2020` のみであり `setTimeout` は宣言されない。`DOM` を足せば通るが、\n * それは `document` や `window` まで型として存在させることであり、サーバ側でしか動かない本\n * パッケージに書けてはならないコードを書けるようにしてしまう。`@types/node` を足せば宣言は\n * 得られるが、型のためだけに依存を増やすことになる。必要な 1 つだけを名指しする。\n */\nconst scheduleTimer = (globalThis as unknown as { setTimeout: (handler: () => void, ms: number) => unknown }).setTimeout\n\n/**\n * Waits before the next attempt, doubling with jitter.\n *\n * 次の試行まで待つ処理 (倍化 + ゆらぎ)。\n *\n * @param attempt - 失敗した試行の番号 (1 起点)。\n * @returns 待機が終われば解決。\n */\nfunction defaultDelay(attempt: number): Promise<void> {\n const base = DEFAULT_BASE_DELAY_MS * 2 ** (attempt - 1)\n // ±25% のゆらぎ。同時に犠牲となった要求が揃って再試行することを避ける\n const jittered = base * (0.75 + Math.random() * 0.5)\n return new Promise((resolve) => scheduleTimer(resolve, Math.round(jittered)))\n}\n\n/**\n * Runs a unit of work, running it again while SQL Server keeps choosing it as the deadlock victim.\n *\n * 1 つの作業単位を実行し、SQL Server がデッドロックの犠牲に選び続ける間は実行し直す処理。\n *\n * `work` は {@link CaptureCause} を受け取る。トランザクションの閉包の**内側**をそれで包むこと —\n * ORM が原因を `EABORT` へ置き換える前に押さえるための唯一の手立てであり、包まなければ\n * デッドロックであっても再実行されない。\n *\n * ```ts\n * await runWithTransactionRetry((capture) => db.transaction((tx) => capture(() => work(tx))))\n * ```\n *\n * **`work` は毎回はじめから走る。** 部分的な再開はしない — 再試行が正しいのは「何も起きなかった」\n * 場合だけであり、途中から再開することはその前提を壊す。したがって `work` は DB の外へ副作用を\n * 持ってはならない (トランザクションのロールバックで元に戻らないため、これは再試行の有無に\n * 関わらず要求される性質である)。\n *\n * **既に外側のトランザクションに居るときは呼ばないこと。** 再試行の判断はそれを開いた側が持つ。\n * 内側だけをやり直すと、外側が既に書いた分を巻き戻さずに重ねることになる。\n *\n * @param work - 実行する作業単位。トランザクション全体を含むこと。\n * @param options - 再試行の設定。\n * @returns `work` の戻り値。\n * @throws 押さえた原本があり、送出された失敗が `EABORT` でそれを覆い隠している場合はその原本。\n * それ以外は送出された失敗をそのまま。\n */\nexport async function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T> {\n const attempts = options?.attempts ?? DEFAULT_TRANSACTION_ATTEMPTS\n const delay = options?.delay ?? defaultDelay\n for (let attempt = 1; ; attempt += 1) {\n // 試行ごとに新しい枠を作る。前の試行の原因を引き継ぐと、直った後も再試行し続ける\n let captured: unknown\n let didCapture = false\n const capture: CaptureCause = async (body) => {\n try {\n return await body()\n } catch (error) {\n captured = error\n didCapture = true\n throw error\n }\n }\n try {\n return await work(capture)\n } catch (error) {\n const cause = didCapture ? captured : undefined\n // 原本を押さえられたならそれで判定する。ORM が置き換えた失敗には番号が残らない\n if (attempt < attempts && isDeadlockVictim(didCapture ? captured : error)) {\n options?.onRetry?.({ attempt, attempts, error, cause })\n await delay(attempt)\n continue\n }\n // 握り潰さない。ただし `EABORT` が原因を覆い隠しているなら、原因の方を返す —\n // 「Transaction has been aborted.」だけでは、何が起きたのか誰にも分からない\n if (didCapture && isRolledBackByServer(error)) throw captured\n throw error\n }\n }\n}\n","/**\n * @module timestamp\n * Reads what the driver returned for a datetime column as an unambiguous instant.\n * 日時列としてドライバが返した値を、曖昧さなく瞬間として読む処理。\n *\n * SQL Server の `datetime2` は時間帯を持たない。ドライバは通常 `Date` を組み立てて返すが、\n * 設定や経路によっては文字列のまま渡ってくる。その文字列にはオフセットが付かない。\n */\n\n/**\n * Reads a driver timestamp as an instant, treating an offset-less string as UTC.\n *\n * ドライバの時刻を瞬間として読む処理 (オフセットの無い文字列は UTC として解釈)。\n *\n * ⚠️ オフセットを持たない ISO 文字列 (`2026-09-09 03:04:05.000`) は仕様上 **実行環境の時間帯**\n * で解釈される。ドライバは通常 `Date` を返すのでこの経路は普段通らないが、通った日に JST なら\n * 9 時間ずれる — 鮮度は「常に古い」と報告され、締切の比較は 9 時間ぶん甘くなる。読む場所ごとに\n * 対処すると必ずどこかが漏れるので、1 つの関数に閉じる。\n *\n * ⚠️ **読めない値は `Invalid Date` として返す。** ここで投げると、1 行の壊れた値が一覧全体を\n * 落とす。判定は呼び出し側が `Number.isNaN(d.getTime())` で行う。\n *\n * @param value - What the driver returned. ドライバが返した値。\n * @returns The instant. その瞬間。\n */\nexport function toInstant(value: string | Date): Date {\n if (value instanceof Date) return value\n return new Date(/(?:Z|[+-]\\d{2}:?\\d{2})$/.test(value) ? value : `${value.replace(\" \", \"T\")}Z`)\n}\n"],"mappings":"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","names":["index_exports","__export","DEFAULT_TRANSACTION_ATTEMPTS","MAX_IN_LIST","MAX_PARAMETERS","RESERVED_PARAMETERS","chunk","chunkByParameters","chunkSizeForParameters","isDeadlockVictim","isRolledBackByServer","runWithTransactionRetry","toInstant","__toCommonJS","MAX_PARAMETERS","RESERVED_PARAMETERS","MAX_IN_LIST","chunk","items","size","out","i","chunkByParameters","parametersPerItem","reservedParameters","chunkSizeForParameters","budget","DEFAULT_TRANSACTION_ATTEMPTS","SERVER_ROLLBACK_CODE","anyCause","error","matches","current","depth","candidate","isDeadlockVictim","isRolledBackByServer","scheduleTimer","defaultDelay","attempt","jittered","resolve","runWithTransactionRetry","work","options","attempts","delay","captured","didCapture","capture","body","cause","toInstant","value"]}
|
package/dist/index.mjs
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
var A=2100,R=100,b=500;function d(e,n=500){if(!Number.isInteger(n)||n<=0)throw new TypeError(`[@aiquants/mssql] chunk size must be a positive integer, received ${String(n)}`);let t=[];for(let r=0;r<e.length;r+=n)t.push(e.slice(r,r+n));return t}function w(e,n,t=100){return d(e,E(n,t))}function E(e,n=100){if(!Number.isInteger(e)||e<=0)throw new TypeError(`[@aiquants/mssql] parametersPerItem must be a positive integer, received ${String(e)}`);if(!Number.isInteger(n)||n<0)throw new TypeError(`[@aiquants/mssql] reservedParameters must be a non-negative integer, received ${String(n)}`);let t=2100-n,r=Math.floor(t/e);if(r<1)throw new TypeError(`[@aiquants/mssql] a single item binds ${e} parameters, which exceeds the ${t} available in one statement`);return r}var h=3;var l="EABORT";function c(e,n){let t=e;for(let r=0;r<5&&t!==null&&t!==void 0;r+=1){if(typeof t!="object")return!1;let o=t;if(n(o))return!0;t=o.cause}return!1}function p(e){return c(e,n=>n.number===1205)}function m(e){return c(e,n=>n.code===l)}var f=globalThis.setTimeout;function y(e){let t=50*2**(e-1)*(.75+Math.random()*.5);return new Promise(r=>f(r,Math.round(t)))}async function S(e,n){let t=n?.attempts??3,r=n?.delay??y;for(let o=1;;o+=1){let u,i=!1,T=async a=>{try{return await a()}catch(s){throw u=s,i=!0,s}};try{return await e(T)}catch(a){let s=i?u:void 0;if(o<t&&p(i?u:a)){n?.onRetry?.({attempt:o,attempts:t,error:a,cause:s}),await r(o);continue}throw i&&m(a)?u:a}}}function M(e){return e instanceof Date?e:new Date(/(?:Z|[+-]\d{2}:?\d{2})$/.test(e)?e:`${e.replace(" ","T")}Z`)}export{h as DEFAULT_TRANSACTION_ATTEMPTS,b as MAX_IN_LIST,A as MAX_PARAMETERS,R as RESERVED_PARAMETERS,d as chunk,w as chunkByParameters,E as chunkSizeForParameters,p as isDeadlockVictim,m as isRolledBackByServer,S as runWithTransactionRetry,M as toInstant};
|
|
2
|
+
//# sourceMappingURL=index.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/limits.ts","../src/retry.ts","../src/timestamp.ts"],"sourcesContent":["/**\n * SQL Server parameter-limit helpers shared by every batched statement.\n * 一括文が共有する SQL Server のパラメータ上限まわりのヘルパー。\n *\n * ⚠️ 上限は **行数ではなくパラメータ数** である。1 行あたり何個の値を束ねるかは文ごとに違うので、\n * 行数だけで分割すると、列の多い `VALUES` が静かに上限を越える。しかも越えるのは件数が閾値を\n * 跨いだ日だけで、それまでは同じコードが問題なく動いて見える。\n */\n\n/**\n * Hard limit of parameters per statement. 1 文あたりのパラメータ数の上限。\n *\n * SQL Server の RPC 1 回あたりのパラメータ上限は 2100。数個は文自身の値 (`SET` 句・スカラー\n * 述語) が使うため、分割の基準にはここから余裕を引いた値を用いる。\n */\nexport const MAX_PARAMETERS = 2100\n\n/** Parameters reserved for the statement's own scalar values. 文自身のスカラー値のための予約枠。 */\nexport const RESERVED_PARAMETERS = 100\n\n/**\n * Maximum ids per `IN` list of single-column predicates. 単列述語の `IN` 句 1 回あたりの最大 ID 数。\n *\n * 1 行 1 パラメータの用途 (`inArray(col, ids)`) 専用の既定値である。複数列を束ねる `VALUES` や、\n * 1 文に `IN` を 2 つ描画する `UPDATE` にそのまま使ってはならない — {@link chunkByParameters} を使う。\n */\nexport const MAX_IN_LIST = 500\n\n/**\n * Splits a list into chunks that fit one statement.\n * 1 文に収まる大きさへリストを分割する処理。\n *\n * @param items - Items to split. 分割対象。\n * @param size - Maximum chunk size. 1 チャンクの最大数。\n * @returns Chunks in the original order. 元の順序を保ったチャンク列。\n * @throws {TypeError} When the size is not a positive integer. 正の整数でない場合。\n */\nexport function chunk<T>(items: readonly T[], size = MAX_IN_LIST): T[][] {\n if (!Number.isInteger(size) || size <= 0) throw new TypeError(`[@aiquants/mssql] chunk size must be a positive integer, received ${String(size)}`)\n const out: T[][] = []\n for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size))\n return out\n}\n\n/**\n * Splits a list so each chunk fits the parameter budget of one statement.\n * 各チャンクが 1 文のパラメータ枠に収まるようリストを分割する処理。\n *\n * `VALUES` は 1 行につき列数ぶんのパラメータを束ねる。7 列の台帳行なら 500 行で 3500 個になり、\n * 上限 2100 を越えて **実行される前に** 拒否される。しかもその失敗は再試行しても同じ場所で起き、\n * そのグループは永久に台帳を持てない。\n *\n * @param items - Items to split. 分割対象。\n * @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。\n * @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。\n * @returns Chunks in the original order. 元の順序を保ったチャンク列。\n * @throws {TypeError} When a single item cannot fit the budget. 1 件すら収まらない場合。\n */\nexport function chunkByParameters<T>(items: readonly T[], parametersPerItem: number, reservedParameters = RESERVED_PARAMETERS): T[][] {\n return chunk(items, chunkSizeForParameters(parametersPerItem, reservedParameters))\n}\n\n/**\n * Reports how many items fit one statement's parameter budget.\n * 1 文のパラメータ枠に収まる件数を返す処理。\n *\n * {@link chunkByParameters} が使う算術を、分割せずに取り出したいときの入口である。呼び出し側が\n * 別の上限 ({@link MAX_IN_LIST} など) と併せて小さい方を採るような場合に使う — **予算そのものを\n * 呼び出し側で組み直してはならない。** `MAX_PARAMETERS` から引き算した値をリテラルで書くと、\n * 上限や予約枠が変わってもそこだけ追従しない。\n *\n * @param parametersPerItem - Parameters each item binds. 1 件が束ねるパラメータ数。\n * @param reservedParameters - Parameters the statement itself binds. 文自身が束ねる数。\n * @returns 1 文へ載せられる件数 (1 以上)。\n * @throws {TypeError} When an argument is invalid, or a single item cannot fit the budget.\n * 引数が不正な場合、または 1 件すら収まらない場合。\n */\nexport function chunkSizeForParameters(parametersPerItem: number, reservedParameters = RESERVED_PARAMETERS): number {\n if (!Number.isInteger(parametersPerItem) || parametersPerItem <= 0) {\n throw new TypeError(`[@aiquants/mssql] parametersPerItem must be a positive integer, received ${String(parametersPerItem)}`)\n }\n if (!Number.isInteger(reservedParameters) || reservedParameters < 0) {\n throw new TypeError(`[@aiquants/mssql] reservedParameters must be a non-negative integer, received ${String(reservedParameters)}`)\n }\n const budget = MAX_PARAMETERS - reservedParameters\n const size = Math.floor(budget / parametersPerItem)\n // 1 件すら収まらないなら、分割では解決しない。黙って 1 件ずつ発行すると、実行時に必ず\n // 落ちる文をひたすら送り続けることになる\n if (size < 1) throw new TypeError(`[@aiquants/mssql] a single item binds ${parametersPerItem} parameters, which exceeds the ${budget} available in one statement`)\n return size\n}\n","/**\n * @module retry\n * Runs a SQL Server transaction again when — and only when — the failure was a deadlock.\n * SQL Server のトランザクションを、失敗がデッドロックであった場合に**限って**やり直す処理。\n *\n * A transaction raises the cost of contention. Two units of work whose key ranges overlap can\n * deadlock, and SQL Server resolves a deadlock by rolling one of them back. Under SERIALIZABLE the\n * ranges are widest, so the chance is highest — but nothing here is specific to an isolation level,\n * a schema, or an application.\n * トランザクションは競合の代償を上げる。鍵の範囲が重なる 2 つの作業単位はデッドロックしうるし、\n * SQL Server はデッドロックを片方のロールバックで解く。SERIALIZABLE では範囲が最も広いため確率が\n * 最も高いが、本モジュールは分離レベル・スキーマ・アプリケーションのいずれにも依存しない。\n *\n * **Two conditions must both hold before a unit of work may be run again**, and they are different\n * questions. Nothing may have been committed — otherwise the retry applies the same change twice.\n * And the failure must be transient — otherwise the retry fails identically, three times slower,\n * for nothing.\n * **再実行が許されるには 2 つの条件が揃わねばならず**、それらは別の問いである。何もコミットされて\n * いないこと — さもなくば同じ変更を 2 度適用する。そして失敗が一時的であること — さもなくば同じ\n * 失敗を 3 倍遅く繰り返すだけになる。\n *\n * デッドロックの犠牲 (エラー番号 `1205`) は、その 1 つの事実で両方を満たす。犠牲は必ず巻き戻され、\n * かつ競合相手が去れば通る。だから本モジュールが認める根拠はそれだけである。\n *\n * ⚠️ **サーバが巻き戻したことは、一時的であることの証拠ではない。** サーバは `XACT_ABORT ON` 下の\n * 実行時エラーでも重大度 16 以上のエラーでも自分で巻き戻す。それらは何度やり直しても同じ結果に\n * なる。`EABORT` ({@link isRolledBackByServer}) を再実行の根拠にしてはならない — 判定に使うのは\n * 「何もコミットされていない」ことの確認までである。\n *\n * ⚠️ **ORM は原因を破壊する。** `drizzle-orm` の `node-mssql` セッションは `catch` の中で\n * `rollback()` を先に呼び、サーバが既に巻き戻していればそのロールバックが\n * `TransactionError('EABORT')` を投げる。`mssql` の `TransactionError` は `(message, code)` しか\n * 受け取らず `cause` を持たないため、元の失敗 (`1205` など) は**痕跡なく消える**。そこで本モジュール\n * は閉包を包む {@link CaptureCause} を呼び出し元へ渡し、原因が失われる前に押さえる。押さえた原因は\n * 再実行の判定に使われ、諦めるときは `EABORT` の代わりに送出される。\n *\n * ⚠️ **Driver-agnostic by duck typing.** ドライバのエラー型を `import` しない — `mssql` /\n * `tedious` / ORM のいずれにも依存させないためである。判定は `code` と `number` という、\n * SQL Server 系ドライバが一様に載せる 2 つのプロパティだけを見る。\n */\n\n/** 試行回数の既定。初回 1 回 + 再試行 2 回。 */\nexport const DEFAULT_TRANSACTION_ATTEMPTS = 3\n\n/** 既定の待機の基準値 (ミリ秒)。試行ごとに倍化する。 */\nconst DEFAULT_BASE_DELAY_MS = 50\n\n/** 原因の連鎖を辿る深さの上限。循環する `cause` で止まらなくなることを防ぐ。 */\nconst MAX_CAUSE_DEPTH = 5\n\n/** SQL Server がデッドロックの犠牲として選んだ要求に返すエラー番号。犠牲は必ずロールバックされる。 */\nconst DEADLOCK_VICTIM_NUMBER = 1205\n\n/**\n * The `mssql` driver's code for a transaction the server rolled back on its own.\n * サーバ自身がロールバックしたトランザクションを表す `mssql` ドライバのコード。\n *\n * `tedious` の `rollbackTransaction` イベントを受けて立つ。すなわち「ロールバックが**済んでいる**」\n * ことの表明であって、その原因が一時的であることは何も意味しない。\n */\nconst SERVER_ROLLBACK_CODE = \"EABORT\"\n\n/**\n * Wraps the transaction body so the original failure is kept before the ORM can replace it.\n * トランザクションの閉包を包み、ORM が置き換える前に元の失敗を押さえる関数の型。\n *\n * 呼び出し元は閉包の**内側**をこれで包む。包まなくても動くが、そのときは原因を押さえられないため、\n * デッドロックであっても再実行されない (安全側に倒れる)。\n */\nexport type CaptureCause = <R>(body: () => Promise<R>) => Promise<R>\n\n/** 1 回の再試行の内訳。呼び出し元が記録・計数するために受け取る。 */\nexport type TransactionRetryInfo = {\n /** 失敗した試行の番号 (1 起点)。 */\n readonly attempt: number\n /** 許された試行の総数。 */\n readonly attempts: number\n /** 呼び出しが送出した失敗。ORM による置き換えにより `EABORT` であることが多い。 */\n readonly error: unknown\n /** 閉包が投げた原本。{@link CaptureCause} を通していなければ `undefined`。 */\n readonly cause: unknown\n}\n\n/** 再試行の設定。既定のまま使えるが、試験と記録のために各項目を差し替えられる。 */\nexport type TransactionRetryOptions = {\n /**\n * 試行回数 (初回を含む)。既定は {@link DEFAULT_TRANSACTION_ATTEMPTS}。\n * `1` を与えると再試行しない。\n */\n readonly attempts?: number\n /**\n * 次の試行までの待機。既定は倍化 + ゆらぎ。\n *\n * ゆらぎを入れるのは、同時に犠牲となった複数の要求が揃って同じ時刻に再試行し、同じ競合を\n * もう一度起こすことを避けるため。試験では即時解決する関数を渡す。\n */\n readonly delay?: (attempt: number) => Promise<void>\n /**\n * 再試行する直前に呼ばれる。既定は何もしない。\n *\n * **黙って再試行してはならない。** 再試行が成功すると利用者からは何も起きなかったように\n * 見えるが、競合が起きていること自体は運用上の事実である。記録の口を呼び出し元へ渡す。\n */\n readonly onRetry?: (info: TransactionRetryInfo) => void\n}\n\n/**\n * Walks a failure and its causes, reporting whether any of them matches.\n *\n * 失敗とその原因の連鎖を辿り、いずれかが条件に合うかを判定する処理。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @param matches - 1 段ごとに当てる条件。\n * @returns いずれかの段が条件に合えば `true`。\n */\nfunction anyCause(error: unknown, matches: (candidate: { code?: unknown; number?: unknown }) => boolean): boolean {\n let current = error\n for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== null && current !== undefined; depth += 1) {\n if (typeof current !== \"object\") return false\n const candidate = current as { code?: unknown; number?: unknown; cause?: unknown }\n if (matches(candidate)) return true\n current = candidate.cause\n }\n return false\n}\n\n/**\n * Reports whether a failure is SQL Server's deadlock victim.\n *\n * その失敗が SQL Server の選んだデッドロックの犠牲かを判定する処理。\n *\n * 犠牲は必ずロールバックされる (何もコミットされていない) 上に、競合相手が去ればやり直しは通る。\n * **再実行を許してよい唯一の根拠**である。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @returns デッドロックの犠牲であれば `true`。\n */\nexport function isDeadlockVictim(error: unknown): boolean {\n return anyCause(error, (candidate) => candidate.number === DEADLOCK_VICTIM_NUMBER)\n}\n\n/**\n * Reports whether a failure carries the driver's proof that the server already rolled back.\n *\n * サーバが既にロールバックしたことの証拠を、その失敗が持っているかを判定する処理。\n *\n * ⚠️ **これは再実行の根拠ではない。** サーバは `XACT_ABORT ON` 下の実行時エラーでも重大度 16 以上の\n * エラーでも自分で巻き戻すため、`EABORT` は「一時的である」ことを何も示さない。用途は 2 つだけ —\n * 何もコミットされていないことの確認と、原因が置き換えられた失敗の見分けである。\n *\n * @param error - 判定する失敗。どんな値でもよい (文字列・`null` も受ける)。\n * @returns ロールバック済みが確定していれば `true`。\n */\nexport function isRolledBackByServer(error: unknown): boolean {\n return anyCause(error, (candidate) => candidate.code === SERVER_ROLLBACK_CODE)\n}\n\n/*\n * 本パッケージの `lib` は `ES2020` のみであり `setTimeout` は宣言されない。`DOM` を足せば通るが、\n * それは `document` や `window` まで型として存在させることであり、サーバ側でしか動かない本\n * パッケージに書けてはならないコードを書けるようにしてしまう。`@types/node` を足せば宣言は\n * 得られるが、型のためだけに依存を増やすことになる。必要な 1 つだけを名指しする。\n */\nconst scheduleTimer = (globalThis as unknown as { setTimeout: (handler: () => void, ms: number) => unknown }).setTimeout\n\n/**\n * Waits before the next attempt, doubling with jitter.\n *\n * 次の試行まで待つ処理 (倍化 + ゆらぎ)。\n *\n * @param attempt - 失敗した試行の番号 (1 起点)。\n * @returns 待機が終われば解決。\n */\nfunction defaultDelay(attempt: number): Promise<void> {\n const base = DEFAULT_BASE_DELAY_MS * 2 ** (attempt - 1)\n // ±25% のゆらぎ。同時に犠牲となった要求が揃って再試行することを避ける\n const jittered = base * (0.75 + Math.random() * 0.5)\n return new Promise((resolve) => scheduleTimer(resolve, Math.round(jittered)))\n}\n\n/**\n * Runs a unit of work, running it again while SQL Server keeps choosing it as the deadlock victim.\n *\n * 1 つの作業単位を実行し、SQL Server がデッドロックの犠牲に選び続ける間は実行し直す処理。\n *\n * `work` は {@link CaptureCause} を受け取る。トランザクションの閉包の**内側**をそれで包むこと —\n * ORM が原因を `EABORT` へ置き換える前に押さえるための唯一の手立てであり、包まなければ\n * デッドロックであっても再実行されない。\n *\n * ```ts\n * await runWithTransactionRetry((capture) => db.transaction((tx) => capture(() => work(tx))))\n * ```\n *\n * **`work` は毎回はじめから走る。** 部分的な再開はしない — 再試行が正しいのは「何も起きなかった」\n * 場合だけであり、途中から再開することはその前提を壊す。したがって `work` は DB の外へ副作用を\n * 持ってはならない (トランザクションのロールバックで元に戻らないため、これは再試行の有無に\n * 関わらず要求される性質である)。\n *\n * **既に外側のトランザクションに居るときは呼ばないこと。** 再試行の判断はそれを開いた側が持つ。\n * 内側だけをやり直すと、外側が既に書いた分を巻き戻さずに重ねることになる。\n *\n * @param work - 実行する作業単位。トランザクション全体を含むこと。\n * @param options - 再試行の設定。\n * @returns `work` の戻り値。\n * @throws 押さえた原本があり、送出された失敗が `EABORT` でそれを覆い隠している場合はその原本。\n * それ以外は送出された失敗をそのまま。\n */\nexport async function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T> {\n const attempts = options?.attempts ?? DEFAULT_TRANSACTION_ATTEMPTS\n const delay = options?.delay ?? defaultDelay\n for (let attempt = 1; ; attempt += 1) {\n // 試行ごとに新しい枠を作る。前の試行の原因を引き継ぐと、直った後も再試行し続ける\n let captured: unknown\n let didCapture = false\n const capture: CaptureCause = async (body) => {\n try {\n return await body()\n } catch (error) {\n captured = error\n didCapture = true\n throw error\n }\n }\n try {\n return await work(capture)\n } catch (error) {\n const cause = didCapture ? captured : undefined\n // 原本を押さえられたならそれで判定する。ORM が置き換えた失敗には番号が残らない\n if (attempt < attempts && isDeadlockVictim(didCapture ? captured : error)) {\n options?.onRetry?.({ attempt, attempts, error, cause })\n await delay(attempt)\n continue\n }\n // 握り潰さない。ただし `EABORT` が原因を覆い隠しているなら、原因の方を返す —\n // 「Transaction has been aborted.」だけでは、何が起きたのか誰にも分からない\n if (didCapture && isRolledBackByServer(error)) throw captured\n throw error\n }\n }\n}\n","/**\n * @module timestamp\n * Reads what the driver returned for a datetime column as an unambiguous instant.\n * 日時列としてドライバが返した値を、曖昧さなく瞬間として読む処理。\n *\n * SQL Server の `datetime2` は時間帯を持たない。ドライバは通常 `Date` を組み立てて返すが、\n * 設定や経路によっては文字列のまま渡ってくる。その文字列にはオフセットが付かない。\n */\n\n/**\n * Reads a driver timestamp as an instant, treating an offset-less string as UTC.\n *\n * ドライバの時刻を瞬間として読む処理 (オフセットの無い文字列は UTC として解釈)。\n *\n * ⚠️ オフセットを持たない ISO 文字列 (`2026-09-09 03:04:05.000`) は仕様上 **実行環境の時間帯**\n * で解釈される。ドライバは通常 `Date` を返すのでこの経路は普段通らないが、通った日に JST なら\n * 9 時間ずれる — 鮮度は「常に古い」と報告され、締切の比較は 9 時間ぶん甘くなる。読む場所ごとに\n * 対処すると必ずどこかが漏れるので、1 つの関数に閉じる。\n *\n * ⚠️ **読めない値は `Invalid Date` として返す。** ここで投げると、1 行の壊れた値が一覧全体を\n * 落とす。判定は呼び出し側が `Number.isNaN(d.getTime())` で行う。\n *\n * @param value - What the driver returned. ドライバが返した値。\n * @returns The instant. その瞬間。\n */\nexport function toInstant(value: string | Date): Date {\n if (value instanceof Date) return value\n return new Date(/(?:Z|[+-]\\d{2}:?\\d{2})$/.test(value) ? value : `${value.replace(\" \", \"T\")}Z`)\n}\n"],"mappings":"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","names":["MAX_PARAMETERS","RESERVED_PARAMETERS","MAX_IN_LIST","chunk","items","size","out","i","chunkByParameters","parametersPerItem","reservedParameters","chunkSizeForParameters","budget","DEFAULT_TRANSACTION_ATTEMPTS","SERVER_ROLLBACK_CODE","anyCause","error","matches","current","depth","candidate","isDeadlockVictim","isRolledBackByServer","scheduleTimer","defaultDelay","attempt","jittered","resolve","runWithTransactionRetry","work","options","attempts","delay","captured","didCapture","capture","body","cause","toInstant","value"]}
|
package/package.json
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@aiquants/mssql",
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "What SQL Server refuses, and how to stay inside it: retry a transaction only when it was the deadlock victim (keeping the cause the ORM destroys), split statements to fit the 2100-parameter limit, and read offset-less timestamps as UTC. No dependencies.",
|
|
5
|
+
"sideEffects": false,
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"module": "dist/index.mjs",
|
|
8
|
+
"types": "dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.mjs",
|
|
13
|
+
"require": "./dist/index.js"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md",
|
|
19
|
+
"LICENSE"
|
|
20
|
+
],
|
|
21
|
+
"keywords": [
|
|
22
|
+
"sqlserver",
|
|
23
|
+
"mssql",
|
|
24
|
+
"transaction",
|
|
25
|
+
"deadlock",
|
|
26
|
+
"retry",
|
|
27
|
+
"typescript"
|
|
28
|
+
],
|
|
29
|
+
"author": {
|
|
30
|
+
"name": "fehde-k",
|
|
31
|
+
"url": "https://x.com/fehdek"
|
|
32
|
+
},
|
|
33
|
+
"license": "MIT",
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"rimraf": "^6.1.2",
|
|
36
|
+
"tsup": "^8.5.1",
|
|
37
|
+
"typescript": "^5.9.3",
|
|
38
|
+
"vitest": "^4.1.8"
|
|
39
|
+
},
|
|
40
|
+
"engines": {
|
|
41
|
+
"node": ">=18.0.0",
|
|
42
|
+
"pnpm": ">=8.0.0"
|
|
43
|
+
},
|
|
44
|
+
"publishConfig": {
|
|
45
|
+
"access": "public"
|
|
46
|
+
},
|
|
47
|
+
"scripts": {
|
|
48
|
+
"build": "tsup",
|
|
49
|
+
"build:watch": "tsup --watch",
|
|
50
|
+
"dev": "tsup --watch",
|
|
51
|
+
"typecheck": "tsc --noEmit",
|
|
52
|
+
"clean": "rimraf dist",
|
|
53
|
+
"publish:patch": "pnpm run typecheck && pnpm run --if-present test && pnpm version patch --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
|
|
54
|
+
"publish:minor": "pnpm run typecheck && pnpm run --if-present test && pnpm version minor --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
|
|
55
|
+
"publish:major": "pnpm run typecheck && pnpm run --if-present test && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
|
|
56
|
+
"lint": "biome lint src/",
|
|
57
|
+
"check": "biome check src/",
|
|
58
|
+
"check:fix": "biome check --write src/",
|
|
59
|
+
"test": "vitest run",
|
|
60
|
+
"test:coverage": "vitest run --coverage"
|
|
61
|
+
}
|
|
62
|
+
}
|