@aiquants/mssql 0.1.2 → 0.1.3

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/README.md CHANGED
@@ -7,10 +7,11 @@ SQL Server が**拒むもの**と、その内側に留まる方法。ドメイ
7
7
  | 何を答えるか | 入口 |
8
8
  | :--- | :--- |
9
9
  | 失敗した作業単位を、もう一度実行してよいか | `runWithTransactionRetry` / `isDeadlockVictim` / `isRolledBackByServer` |
10
+ | 失敗が、SQL Server のどの番号の失敗か (包み直しの奥まで) | `sqlErrorOf` (`SqlServerMessage`) |
10
11
  | 1 文に何件まで載せられるか | `chunkByParameters` / `chunkSizeForParameters` / `chunk` |
11
12
  | 返ってきた日時は、どの瞬間か | `toInstant` |
12
13
 
13
- どちらも**ドライバが押し付けてくる事実**であり、呼び出し側のドメインには属しません。写しを各所に
14
+ いずれも**ドライバが押し付けてくる事実**であり、呼び出し側のドメインには属しません。写しを各所に
14
15
  置くと、片方だけ直る事故が起きます。
15
16
 
16
17
  ---
@@ -42,7 +43,7 @@ SQL Server のトランザクションを、失敗がデッドロックであっ
42
43
 
43
44
  | 失敗 | 再実行 | 根拠 |
44
45
  | :--- | :--- | :--- |
45
- | `number === 1205` (デッドロックの犠牲) | **する** | 必ず巻き戻され、やり直せば通りうる |
46
+ | `sqlErrorOf(error, [1205]) !== null` (デッドロックの犠牲: 番号 `1205` と文面を持つ段) | **する** | 必ず巻き戻され、やり直せば通りうる |
46
47
  | `code === "EABORT"` (サーバが巻き戻した) | しない | 巻き戻ったことしか示さない。原因が決定的なら永久に同じ |
47
48
  | `ETIMEOUT` (要求の時限切れ) | しない | 文がサーバ側でまだ走っていることがある |
48
49
  | 接続断 (`ECONNCLOSED` / `ESOCKET`) | しない | コミットの成否を持ち帰れない |
@@ -92,7 +93,7 @@ pnpm add @aiquants/mssql
92
93
  ```
93
94
 
94
95
  依存はありません。`mssql` / `tedious` / ORM のいずれにも `import` を持たず、ドライバのエラーが
95
- 一様に載せる `code` と `number` の 2 プロパティだけを見ます (duck typing)。
96
+ 一様に載せる `code`・`number`・`message` と、原因の連なり (`cause`) だけを見ます (duck typing)。
96
97
 
97
98
  ## Contract
98
99
 
@@ -133,6 +134,39 @@ import { isDeadlockVictim, isRolledBackByServer } from "@aiquants/mssql"
133
134
 
134
135
  ---
135
136
 
137
+ ## SQL Server のエラー番号を読む
138
+
139
+ 一意違反 (`2601` / `2627`) や制約違反 (`547`) を応答へ写すとき、番号は ORM やアプリの包み直しで
140
+ `cause` の奥へ沈みます。走査を呼び出し側で写して持たないでください。深さを変えた日に「再実行される
141
+ 失敗」と「番号で見分ける失敗」とで届く深さが黙って食い違います。`isDeadlockVictim` と同じ走査を
142
+ `sqlErrorOf` がそのまま公開しています。
143
+
144
+ ```ts
145
+ import { type SqlServerMessage, sqlErrorOf } from "@aiquants/mssql"
146
+
147
+ const violation: SqlServerMessage | null = sqlErrorOf(error, [2601, 2627]) // { number, message }
148
+ if (violation === null) throw error
149
+ ```
150
+
151
+ | 規則 | 内容 |
152
+ | :--- | :--- |
153
+ | 辿る順と深さ | 失敗そのものから `cause` を浅い順に最大 5 段。循環する `cause` もそこで止まる |
154
+ | 返す段 | `numbers` のいずれかを持つ**最も浅い**段。`numbers` の並びは関係しない |
155
+ | SQL Server の失敗と認める段 | `number` が正の整数で `message` が文字列の段だけ。`NaN`・`0`・負数・文字列の番号や、文面の無い段は一致しない |
156
+ | 止まる所 | オブジェクトでない値 (`null`・`undefined`・関数・文字列など) に着いたら、それを段と認めず、その先も探さない |
157
+ | 戻り値 | 段そのもの (ドライバの `Error`) ではなく、番号と文面だけを写した `SqlServerMessage` (`{ number, message }`)。どの段にも無ければ `null` |
158
+
159
+ `isDeadlockVictim(error)` は `sqlErrorOf(error, [1205]) !== null` そのものです。文面の無い段は、
160
+ `1205` を持っていてもデッドロックの犠牲とは認めません。
161
+
162
+ > [!IMPORTANT]
163
+ > **サーバが既に巻き戻したトランザクションの失敗には、番号が残りません。** ORM がそれを原因の無い
164
+ > `EABORT` へ置き換えるため (上の「ORM は原因を破壊します」)、`db.transaction(...)` の失敗へ直接当てると
165
+ > `null` が返ります。番号を読むなら、`capture` で包んだ `runWithTransactionRetry` が送出した失敗に当てて
166
+ > ください。諦めるときは `EABORT` ではなく、押さえた原本が送出されます。
167
+
168
+ ---
169
+
136
170
  ## パラメータ上限
137
171
 
138
172
  > [!CAUTION]
package/dist/index.d.mts CHANGED
@@ -17,8 +17,13 @@ type TransactionRetryOptions = {
17
17
  readonly delay?: (attempt: number) => Promise<void>;
18
18
  readonly onRetry?: (info: TransactionRetryInfo) => void;
19
19
  };
20
+ type SqlServerMessage = {
21
+ readonly number: number;
22
+ readonly message: string;
23
+ };
24
+ declare function sqlErrorOf(error: unknown, numbers: readonly number[]): SqlServerMessage | null;
20
25
  declare function isDeadlockVictim(error: unknown): boolean;
21
26
  declare function isRolledBackByServer(error: unknown): boolean;
22
27
  declare function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T>;
23
28
  declare function toInstant(value: string | Date): Date;
24
- export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, toInstant };
29
+ export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type SqlServerMessage, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, sqlErrorOf, toInstant };
package/dist/index.d.ts CHANGED
@@ -17,8 +17,13 @@ type TransactionRetryOptions = {
17
17
  readonly delay?: (attempt: number) => Promise<void>;
18
18
  readonly onRetry?: (info: TransactionRetryInfo) => void;
19
19
  };
20
+ type SqlServerMessage = {
21
+ readonly number: number;
22
+ readonly message: string;
23
+ };
24
+ declare function sqlErrorOf(error: unknown, numbers: readonly number[]): SqlServerMessage | null;
20
25
  declare function isDeadlockVictim(error: unknown): boolean;
21
26
  declare function isRolledBackByServer(error: unknown): boolean;
22
27
  declare function runWithTransactionRetry<T>(work: (capture: CaptureCause) => Promise<T>, options?: TransactionRetryOptions): Promise<T>;
23
28
  declare function toInstant(value: string | Date): Date;
24
- export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, toInstant };
29
+ export { type CaptureCause, DEFAULT_TRANSACTION_ATTEMPTS, MAX_IN_LIST, MAX_PARAMETERS, RESERVED_PARAMETERS, type SqlServerMessage, type TransactionRetryInfo, type TransactionRetryOptions, chunk, chunkByParameters, chunkSizeForParameters, isDeadlockVictim, isRolledBackByServer, runWithTransactionRetry, sqlErrorOf, toInstant };
package/dist/index.js CHANGED
@@ -1 +1 @@
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});
1
+ "use strict";var c=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var b=(e,n)=>{for(var r in n)c(e,r,{get:n[r],enumerable:!0})},w=(e,n,r,t)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of A(n))!R.call(e,o)&&o!==r&&c(e,o,{get:()=>n[o],enumerable:!(t=f(n,o))||t.enumerable});return e};var S=e=>w(c({},"__esModule",{value:!0}),e);var C={};b(C,{DEFAULT_TRANSACTION_ATTEMPTS:()=>q,MAX_IN_LIST:()=>P,MAX_PARAMETERS:()=>L,RESERVED_PARAMETERS:()=>I,chunk:()=>l,chunkByParameters:()=>_,chunkSizeForParameters:()=>d,isDeadlockVictim:()=>p,isRolledBackByServer:()=>y,runWithTransactionRetry:()=>g,sqlErrorOf:()=>m,toInstant:()=>D});module.exports=S(C);var L=2100,I=100,P=500;function l(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 r=[];for(let t=0;t<e.length;t+=n)r.push(e.slice(t,t+n));return r}function _(e,n,r=100){return l(e,d(n,r))}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 r=2100-n,t=Math.floor(r/e);if(t<1)throw new TypeError(`[@aiquants/mssql] a single item binds ${e} parameters, which exceeds the ${r} available in one statement`);return t}var q=3;var h="EABORT";function*T(e){let n=e;for(let r=0;r<5&&typeof n=="object"&&n!==null;r+=1){let t=n;yield t,n=t.cause}}function m(e,n){for(let r of T(e)){let{number:t,message:o}=r;if(typeof t=="number"&&Number.isInteger(t)&&t>0&&typeof o=="string"&&n.includes(t))return{number:t,message:o}}return null}function p(e){return m(e,[1205])!==null}function y(e){for(let n of T(e))if(n.code===h)return!0;return!1}var k=globalThis.setTimeout;function M(e){let r=50*2**(e-1)*(.75+Math.random()*.5);return new Promise(t=>k(t,Math.round(r)))}async function g(e,n){let r=n?.attempts??3,t=n?.delay??M;for(let o=1;;o+=1){let s,u=!1,E=async a=>{try{return await a()}catch(i){throw s=i,u=!0,i}};try{return await e(E)}catch(a){let i=u?s:void 0;if(o<r&&p(u?s:a)){n?.onRetry?.({attempt:o,attempts:r,error:a,cause:i}),await t(o);continue}throw u&&y(a)?s:a}}}function D(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,sqlErrorOf,toInstant});
package/dist/index.mjs CHANGED
@@ -1 +1 @@
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};
1
+ var R=2100,b=100,w=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 r=[];for(let t=0;t<e.length;t+=n)r.push(e.slice(t,t+n));return r}function S(e,n,r=100){return d(e,T(n,r))}function T(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 r=2100-n,t=Math.floor(r/e);if(t<1)throw new TypeError(`[@aiquants/mssql] a single item binds ${e} parameters, which exceeds the ${r} available in one statement`);return t}var h=3;var m="EABORT";function*c(e){let n=e;for(let r=0;r<5&&typeof n=="object"&&n!==null;r+=1){let t=n;yield t,n=t.cause}}function p(e,n){for(let r of c(e)){let{number:t,message:o}=r;if(typeof t=="number"&&Number.isInteger(t)&&t>0&&typeof o=="string"&&n.includes(t))return{number:t,message:o}}return null}function y(e){return p(e,[1205])!==null}function E(e){for(let n of c(e))if(n.code===m)return!0;return!1}var f=globalThis.setTimeout;function A(e){let r=50*2**(e-1)*(.75+Math.random()*.5);return new Promise(t=>f(t,Math.round(r)))}async function k(e,n){let r=n?.attempts??3,t=n?.delay??A;for(let o=1;;o+=1){let s,u=!1,l=async a=>{try{return await a()}catch(i){throw s=i,u=!0,i}};try{return await e(l)}catch(a){let i=u?s:void 0;if(o<r&&y(u?s:a)){n?.onRetry?.({attempt:o,attempts:r,error:a,cause:i}),await t(o);continue}throw u&&E(a)?s:a}}}function g(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,w as MAX_IN_LIST,R as MAX_PARAMETERS,b as RESERVED_PARAMETERS,d as chunk,S as chunkByParameters,T as chunkSizeForParameters,y as isDeadlockVictim,E as isRolledBackByServer,k as runWithTransactionRetry,p as sqlErrorOf,g as toInstant};
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@aiquants/mssql",
3
- "version": "0.1.2",
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.",
3
+ "version": "0.1.3",
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), read the SQL Server error number through wrapped causes, split statements to fit the 2100-parameter limit, and read offset-less timestamps as UTC. No dependencies.",
5
5
  "sideEffects": false,
6
6
  "main": "dist/index.js",
7
7
  "module": "dist/index.mjs",
@@ -50,9 +50,9 @@
50
50
  "dev": "tsup --watch",
51
51
  "typecheck": "tsc --noEmit",
52
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",
53
+ "publish:patch": "pnpm run typecheck && pnpm run --if-present test && pnpm run build && node ../../.config/scripts/check-publish-leaks.mjs && 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 run build && node ../../.config/scripts/check-publish-leaks.mjs && 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 run build && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
56
56
  "lint": "biome lint src/",
57
57
  "check": "biome check src/",
58
58
  "check:fix": "biome check --write src/",