@stacksjs/database 0.75.115 → 0.75.117

package/README.md

@@ -57,3 +57,12 @@ For casual chit-chat with others using this package:
 The MIT License (MIT). Please see [LICENSE](https://github.com/stacksjs/stacks/tree/main/LICENSE.md) for more information.
 
 Made with 💙
+
+## Group row locks
+
+lockRows(tx, table, ids, { key?, scope? }) from database/runtime acquires
+unique numeric primary keys in deterministic order and returns a map keyed by their
+canonical numeric string value, so padded numeric inputs cannot reverse lock order. Missing scoped rows map to undefined. The caller must supply a
+transaction handle and choose ownership filters; reads, writes and validation
+remain on that handle. This prevents opposite input order from creating a
+lock-order cycle during a transfer, merge or multi-item stock reservation.

package/dist/row-lock.d.ts

@@ -2,3 +2,9 @@
 export declare function assertSqlIdentifier(name: string): void;
 /** Lock a scoped row until the caller's transaction commits. SQLite transactions serialize writers. */
 export declare function lockRow(connection: { unsafe?: (query: string, params?: unknown[]) => PromiseLike<Record<string, unknown>[]> }, table: string, filters: Record<string, string | number | null>): Promise<Record<string, unknown> | undefined>;
+/** Lock a group in one deterministic order, independent of the request's ordering. */
+export declare function lockRows(connection: Parameters<typeof lockRow>[0], table: string, ids: readonly (string | number)[], options?: RowLockGroupOptions): Promise<Map<string, Record<string, unknown> | undefined>>;
+export declare interface RowLockGroupOptions {
+  key?: string
+  scope?: Record<string, string | number | null>
+}

package/dist/row-lock.js

@@ -1 +1 @@
-import{sqlHelpers}from"./sql-helpers";import{getDatabaseDialect}from"./utils";export function assertSqlIdentifier(name){if(!/^[a-z_][a-z_0-9]*$/i.test(name))throw Error(`Invalid SQL identifier: ${name}`)}export async function lockRow(connection,table,filters){const dialect=sqlHelpers(getDatabaseDialect()),quote=dialect.isMysql?"`":'"',identifier=(name)=>{assertSqlIdentifier(name);return`${quote}${name}${quote}`},values=[],conditions=Object.entries(filters).map(([name,value])=>{if(value===null)return`${identifier(name)} IS NULL`;values.push(value);return`${identifier(name)} = ${dialect.param(values.length)}`});if(!conditions.length)throw Error("A row lock requires a scope");const suffix=dialect.isPostgres||dialect.isMysql?" FOR UPDATE":"";if(!connection.unsafe)throw Error("Row locks require a database connection");const rows=await connection.unsafe(`SELECT * FROM ${identifier(table)} WHERE ${conditions.join(" AND ")}${suffix}`,values);if(rows.length>1)throw Error("A row lock requires a unique scope");return rows[0]}
+import{sqlHelpers}from"./sql-helpers";import{getDatabaseDialect}from"./utils";export function assertSqlIdentifier(name){if(!/^[a-z_][a-z_0-9]*$/i.test(name))throw Error(`Invalid SQL identifier: ${name}`)}export async function lockRow(connection,table,filters){const dialect=sqlHelpers(getDatabaseDialect()),quote=dialect.isMysql?"`":'"',identifier=(name)=>{assertSqlIdentifier(name);return`${quote}${name}${quote}`},values=[],conditions=Object.entries(filters).map(([name,value])=>{if(value===null)return`${identifier(name)} IS NULL`;values.push(value);return`${identifier(name)} = ${dialect.param(values.length)}`});if(!conditions.length)throw Error("A row lock requires a scope");const suffix=dialect.isPostgres||dialect.isMysql?" FOR UPDATE":"";if(!connection.unsafe)throw Error("Row locks require a database connection");const rows=await connection.unsafe(`SELECT * FROM ${identifier(table)} WHERE ${conditions.join(" AND ")}${suffix}`,values);if(rows.length>1)throw Error("A row lock requires a unique scope");return rows[0]}export async function lockRows(connection,table,ids,options={}){const key=options.key??"id";assertSqlIdentifier(table);assertSqlIdentifier(key);if(Object.prototype.hasOwnProperty.call(options.scope??{},key))throw Error("The group scope cannot replace its primary key");const unique=new Map;for(const id of ids){if(typeof id!=="number"&&(typeof id!=="string"||!/^\d+$/.test(id)))throw Error("Group locks require numeric primary keys");const number=Number(id);if(!Number.isSafeInteger(number)||number<=0)throw Error("Invalid row key");unique.set(String(number),number)}const rows=new Map;for(const name of[...unique.keys()].sort())rows.set(name,await lockRow(connection,table,{...options.scope,[key]:unique.get(name)}));return rows}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.115",
+  "version": "0.75.117",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -66,26 +66,26 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.115",
-    "@stacksjs/env": "0.75.115",
-    "@stacksjs/error-handling": "0.75.115",
-    "@stacksjs/faker": "^0.75.115",
-    "@stacksjs/features": "0.75.115",
-    "@stacksjs/logging": "0.75.115",
-    "@stacksjs/model-meta": "0.75.115",
-    "@stacksjs/path": "0.75.115",
-    "@stacksjs/query-builder": "^0.75.115",
-    "@stacksjs/security": "0.75.115",
-    "@stacksjs/storage": "0.75.115",
-    "@stacksjs/strings": "0.75.115",
+    "@stacksjs/config": "0.75.117",
+    "@stacksjs/env": "0.75.117",
+    "@stacksjs/error-handling": "0.75.117",
+    "@stacksjs/faker": "^0.75.117",
+    "@stacksjs/features": "0.75.117",
+    "@stacksjs/logging": "0.75.117",
+    "@stacksjs/model-meta": "0.75.117",
+    "@stacksjs/path": "0.75.117",
+    "@stacksjs/query-builder": "^0.75.117",
+    "@stacksjs/security": "0.75.117",
+    "@stacksjs/storage": "0.75.117",
+    "@stacksjs/strings": "0.75.117",
     "@stacksjs/ts-validation": "^0.5.6",
     "bun-query-builder": "^0.3.5",
     "dynamodb-tooling": "^0.3.6"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.75.115",
-    "@stacksjs/router": "0.75.115",
-    "@stacksjs/utils": "0.75.115",
+    "@stacksjs/cli": "0.75.117",
+    "@stacksjs/router": "0.75.117",
+    "@stacksjs/utils": "0.75.117",
     "better-dx": "^0.2.24"
   }
 }