@stacksjs/database 0.75.131 → 0.75.133

package/README.md

@@ -66,3 +66,12 @@ canonical numeric string value, so padded numeric inputs cannot reverse lock ord
 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.
+
+`lockRow(tx, table, scope, { mode: 'no_key_update' })` uses PostgreSQL's
+`FOR NO KEY UPDATE` for parent rows whose key will stay fixed. It serializes
+other non-key updates while allowing child inserts to acquire foreign-key
+key-share locks. Acquire the parent before child locks consistently; a strong
+`FOR UPDATE` parent lock can deadlock with a child-first insert. MySQL retains
+its stronger `FOR UPDATE` lock, and SQLite relies on the surrounding transaction.
+The default remains `update`; changing or deleting the parent key needs that
+stronger lock. Group locks accept the same mode.

package/dist/row-lock.d.ts

@@ -1,10 +1,13 @@
 /** Check trusted table/column names before composing a scoped operation. */
 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>;
+export declare function lockRow(connection: { unsafe?: (query: string, params?: unknown[]) => PromiseLike<Record<string, unknown>[]> }, table: string, filters: Record<string, string | number | null>, options?: RowLockOptions): 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 {
+export declare interface RowLockOptions {
+  mode?: 'update' | 'no_key_update'
+}
+export declare interface RowLockGroupOptions extends RowLockOptions {
   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]}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}
+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,options={}){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 mode=options.mode??"update";if(mode!=="update"&&mode!=="no_key_update")throw Error("Unsupported row lock mode");const suffix=dialect.isPostgres&&mode==="no_key_update"?" FOR NO KEY UPDATE":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)},{mode:options.mode}));return rows}

package/package.json

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