@abapify/adt-locks 0.4.0 → 0.4.1

package/dist/index.d.mts

@@ -0,0 +1,183 @@
+//#region src/types.d.ts
+/**
+ * ADT Lock Types
+ *
+ * Shared type definitions for lock handles and persisted lock entries.
+ */
+/**
+ * Lock handle returned by SAP `_action=LOCK` operations.
+ *
+ * The handle is required for subsequent PUT (save) and `_action=UNLOCK` calls.
+ */
+interface LockHandle {
+  /** Opaque lock token from SAP (LOCK_HANDLE) */
+  handle: string;
+  /** Transport request assigned to this object (CORRNR) */
+  correlationNumber?: string;
+  /** User who owns the transport (CORRUSER) */
+  correlationUser?: string;
+}
+/**
+ * A persisted lock entry — written to the lock store so handles survive process crashes.
+ */
+interface LockEntry {
+  /** ADT object URI (e.g., /sap/bc/adt/oo/classes/zcl_my_class) */
+  objectUri: string;
+  /** Human-readable object name */
+  objectName: string;
+  /** ADT object type (e.g., CLAS/OC, INTF/OI, DTEL) */
+  objectType?: string;
+  /** The lock handle returned by SAP */
+  lockHandle: string;
+  /** Transport request from lock response */
+  transport?: string;
+  /** SAP system host */
+  host?: string;
+  /** ISO timestamp when lock was acquired */
+  lockedAt: string;
+}
+//#endregion
+//#region src/store.d.ts
+/**
+ * Lock store interface — opt-in persistence for ADT lock handles.
+ *
+ * Implementations can be file-based, in-memory, or backed by any storage.
+ */
+interface LockStore {
+  /** Persist a lock entry after successful LOCK */
+  register(entry: LockEntry): void;
+  /** Remove a lock entry after successful UNLOCK */
+  deregister(objectUri: string): void;
+  /** List all persisted lock entries */
+  list(): LockEntry[];
+  /** Remove all entries */
+  clear(): void;
+}
+/**
+ * File-based lock store.
+ *
+ * Persists lock entries to a JSON file (default: `~/.adt/locks.json`).
+ * Each entry is keyed by objectUri — re-locking the same URI overwrites.
+ * File permissions are 0o600 (owner read/write only).
+ */
+declare class FileLockStore implements LockStore {
+  private readonly filePath;
+  constructor(baseDir?: string);
+  register(entry: LockEntry): void;
+  deregister(objectUri: string): void;
+  list(): LockEntry[];
+  clear(): void;
+  private load;
+  private save;
+}
+//#endregion
+//#region src/service.d.ts
+/** Minimal client interface — anything with an authenticated fetch() */
+interface LockClient {
+  fetch(url: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }): Promise<unknown>;
+}
+interface LockServiceOptions {
+  /** Optional lock store for persistence */
+  store?: LockStore;
+}
+interface LockOptions {
+  /** Transport request */
+  transport?: string;
+  /** Object name (for store metadata) */
+  objectName?: string;
+  /** Object type (for store metadata) */
+  objectType?: string;
+}
+interface UnlockOptions {
+  /** Lock handle — REQUIRED. SAP always requires an explicit handle for unlock. */
+  lockHandle: string;
+}
+/**
+ * Parse SAP lock response XML to extract lock handle and correlation info.
+ *
+ * Response format:
+ * ```xml
+ * <asx:abap>...<DATA>
+ *   <LOCK_HANDLE>xxx</LOCK_HANDLE>
+ *   <CORRNR>yyy</CORRNR>
+ *   <CORRUSER>zzz</CORRUSER>
+ * </DATA>...</asx:abap>
+ * ```
+ */
+declare function parseLockResponse(xml: string): LockHandle;
+interface LockService {
+  /** Acquire a lock on an ADT object */
+  lock(objectUri: string, options?: LockOptions): Promise<LockHandle>;
+  /** Release a lock on an ADT object (lock handle required) */
+  unlock(objectUri: string, options: UnlockOptions): Promise<void>;
+  /**
+   * Force-unlock: acquire a lock to recover the handle, then immediately unlock.
+   * Works when the object is locked by the current user but the handle was lost
+   * (e.g., crashed session). If the object is locked by another user, the lock
+   * call will fail with 403/409.
+   */
+  forceUnlock(objectUri: string, options?: LockOptions): Promise<void>;
+  /** List all persisted lock entries (from store) */
+  list(): LockEntry[];
+  /** Try to UNLOCK every persisted entry, removing successful ones from store */
+  cleanup(): Promise<{
+    ok: number;
+    failed: number;
+  }>;
+  /** Clear the store without sending any UNLOCK requests */
+  clear(): void;
+}
+declare function createLockService(client: LockClient, serviceOptions?: LockServiceOptions): LockService;
+//#endregion
+//#region src/batch/batch-lock-session.d.ts
+interface BatchLockTarget {
+  /** ADT object URI — e.g. `/sap/bc/adt/oo/classes/zcl_foo` */
+  objectUri: string;
+  /** Per-target lock options (transport, object name/type for the store). */
+  options?: LockOptions;
+}
+interface BatchLockAcquisition {
+  target: BatchLockTarget;
+  handle: LockHandle;
+}
+interface BatchReleaseResult {
+  released: number;
+  failed: Array<{
+    objectUri: string;
+    error: string;
+  }>;
+}
+interface BatchLockSessionOptions {
+  /**
+   * When true, `begin()` stops on the first failure and rolls back locks
+   * already acquired in this session. When false (rare), errors are
+   * collected and returned but already-acquired locks are kept — use only
+   * for diagnostic tooling. Default: true.
+   */
+  rollbackOnError?: boolean;
+}
+interface BatchLockSession {
+  /** Acquire all configured locks. Rollback on failure (by default). */
+  begin(): Promise<BatchLockAcquisition[]>;
+  /** Release every currently held handle. Safe to call multiple times. */
+  release(): Promise<BatchReleaseResult>;
+  /** Snapshot of currently held handles. */
+  handles(): ReadonlyArray<BatchLockAcquisition>;
+  /** Has `begin()` completed successfully? */
+  readonly active: boolean;
+}
+/**
+ * Create a batch lock session over a set of targets.
+ *
+ * The session does NOT auto-begin; callers drive the lifecycle explicitly so
+ * error handling stays visible at the call-site (`try { begin(); … } finally
+ * { release(); }`).
+ */
+declare function createBatchLockSession(lockService: Pick<LockService, 'lock' | 'unlock'>, targets: BatchLockTarget[], options?: BatchLockSessionOptions): BatchLockSession;
+//#endregion
+export { type BatchLockAcquisition, type BatchLockSession, type BatchLockSessionOptions, type BatchLockTarget, type BatchReleaseResult, FileLockStore, type LockClient, type LockEntry, type LockHandle, type LockOptions, type LockService, type LockStore, type UnlockOptions, createBatchLockSession, createLockService, parseLockResponse };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/store.ts","../src/service.ts","../src/batch/batch-lock-session.ts"],"mappings":";;AAWA;;;;;;;;;UAAiB,UAAA;EAYS;EAVxB,MAAA;EAUwB;EARxB,iBAAA;EAYA;EAVA,eAAA;AAAA;;;;UAMe,SAAA;EAcP;EAZR,SAAA;;EAEA,UAAA;ECVe;EDYf,UAAA;;EAEA,UAAA;ECZA;EDcA,SAAA;ECdS;EDgBT,IAAA;ECdW;EDgBX,QAAA;AAAA;;;;;;AAdF;;UCNiB,SAAA;EDMS;ECJxB,QAAA,CAAS,KAAA,EAAO,SAAA;EDQhB;ECNA,UAAA,CAAW,SAAA;EDUX;ECRA,IAAA,IAAQ,SAAA;EDYR;ECVA,KAAA;AAAA;;;;;AARF;;;cAkBa,aAAA,YAAyB,SAAA;EAAA,iBACnB,QAAA;cAEL,OAAA;EAKZ,QAAA,CAAS,KAAA,EAAO,SAAA;EAQhB,UAAA,CAAW,SAAA;EAQX,IAAA,CAAA,GAAQ,SAAA;EAIR,KAAA,CAAA;EAAA,QAIQ,IAAA;EAAA,QASA,IAAA;AAAA;;;;UC1DO,UAAA;EACf,KAAA,CACE,GAAA,UACA,OAAA;IACE,MAAA;IACA,OAAA,GAAU,MAAA;IACV,IAAA;EAAA,IAED,OAAA;AAAA;AAAA,UAGY,kBAAA;;EAEf,KAAA,GAAQ,SAAA;AAAA;AAAA,UAGO,WAAA;;EAEf,SAAA;EDjBA;ECmBA,UAAA;EDnBS;ECqBT,UAAA;AAAA;AAAA,UAGe,aAAA;EDpBP;ECsBR,UAAA;AAAA;;ADVF;;;;;;;;;;;iBCyBgB,iBAAA,CAAkB,GAAA,WAAc,UAAA;AAAA,UAiB/B,WAAA;EDlCC;ECoChB,IAAA,CAAK,SAAA,UAAmB,OAAA,GAAU,WAAA,GAAc,OAAA,CAAQ,UAAA;ED5BxD;EC8BA,MAAA,CAAO,SAAA,UAAmB,OAAA,EAAS,aAAA,GAAgB,OAAA;EDtBnD;;;;;;EC6BA,WAAA,CAAY,SAAA,UAAmB,OAAA,GAAU,WAAA,GAAc,OAAA;;EAEvD,IAAA,IAAQ,SAAA;;EAER,OAAA,IAAW,OAAA;IAAU,EAAA;IAAY,MAAA;EAAA;EAzEjC;EA2EA,KAAA;AAAA;AAAA,iBAGc,iBAAA,CACd,MAAA,EAAQ,UAAA,EACR,cAAA,GAAiB,kBAAA,GAChB,WAAA;;;UCrEc,eAAA;EFZC;EEchB,SAAA;EFZA;EEcA,OAAA,GAAU,WAAA;AAAA;AAAA,UAGK,oBAAA;EACf,MAAA,EAAQ,eAAA;EACR,MAAA,EAAQ,UAAA;AAAA;AAAA,UAGO,kBAAA;EACf,QAAA;EACA,MAAA,EAAQ,KAAA;IAAQ,SAAA;IAAmB,KAAA;EAAA;AAAA;AAAA,UAGpB,uBAAA;EFbqB;;;;;;EEoBpC,eAAA;AAAA;AAAA,UAGe,gBAAA;EFCf;EECA,KAAA,IAAS,OAAA,CAAQ,oBAAA;EFGjB;EEDA,OAAA,IAAW,OAAA,CAAQ,kBAAA;EFcX;EEZR,OAAA,IAAW,aAAA,CAAc,oBAAA;EFYb;EAAA,SEVH,MAAA;AAAA;;ADhDX;;;;;;iBC0DgB,sBAAA,CACd,WAAA,EAAa,IAAA,CAAK,WAAA,sBAClB,OAAA,EAAS,eAAA,IACT,OAAA,GAAU,uBAAA,GACT,gBAAA"}

package/dist/index.mjs

@@ -0,0 +1,226 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+//#region src/store.ts
+/**
+* Lock Store — persistence layer for ADT lock handles
+*
+* Provides an interface for registering/deregistering lock entries
+* and a file-based implementation that persists to `~/.adt/locks.json`.
+*/
+/**
+* File-based lock store.
+*
+* Persists lock entries to a JSON file (default: `~/.adt/locks.json`).
+* Each entry is keyed by objectUri — re-locking the same URI overwrites.
+* File permissions are 0o600 (owner read/write only).
+*/
+var FileLockStore = class {
+	filePath;
+	constructor(baseDir) {
+		this.filePath = join(baseDir ?? join(homedir(), ".adt"), "locks.json");
+	}
+	register(entry) {
+		const entries = this.load();
+		const idx = entries.findIndex((e) => e.objectUri === entry.objectUri);
+		if (idx >= 0) entries[idx] = entry;
+		else entries.push(entry);
+		this.save(entries);
+	}
+	deregister(objectUri) {
+		const entries = this.load();
+		const filtered = entries.filter((e) => e.objectUri !== objectUri);
+		if (filtered.length !== entries.length) this.save(filtered);
+	}
+	list() {
+		return this.load();
+	}
+	clear() {
+		this.save([]);
+	}
+	load() {
+		if (!existsSync(this.filePath)) return [];
+		try {
+			return JSON.parse(readFileSync(this.filePath, "utf8"));
+		} catch {
+			return [];
+		}
+	}
+	save(entries) {
+		const dir = dirname(this.filePath);
+		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+		writeFileSync(this.filePath, JSON.stringify(entries, null, 2), { mode: 384 });
+	}
+};
+
+//#endregion
+//#region src/service.ts
+/**
+* Parse SAP lock response XML to extract lock handle and correlation info.
+*
+* Response format:
+* ```xml
+* <asx:abap>...<DATA>
+*   <LOCK_HANDLE>xxx</LOCK_HANDLE>
+*   <CORRNR>yyy</CORRNR>
+*   <CORRUSER>zzz</CORRUSER>
+* </DATA>...</asx:abap>
+* ```
+*/
+function parseLockResponse(xml) {
+	const handleMatch = xml.match(/<LOCK_HANDLE>([^<]+)<\/LOCK_HANDLE>/);
+	if (!handleMatch) throw new Error("Failed to parse lock handle from SAP response. The response format may have changed.");
+	const corrNrMatch = xml.match(/<CORRNR>([^<]+)<\/CORRNR>/);
+	const corrUserMatch = xml.match(/<CORRUSER>([^<]+)<\/CORRUSER>/);
+	return {
+		handle: handleMatch[1],
+		correlationNumber: corrNrMatch?.[1],
+		correlationUser: corrUserMatch?.[1]
+	};
+}
+function createLockService(client, serviceOptions) {
+	const store = serviceOptions?.store;
+	/** Headers for lock operations — stateful session with security session reuse */
+	const lockHeaders = {
+		"X-sap-adt-sessiontype": "stateful",
+		"x-sap-security-session": "use",
+		Accept: "application/*,application/vnd.sap.as+xml;charset=UTF-8;dataname=com.sap.adt.lock.result"
+	};
+	/** Headers for unlock operations */
+	const unlockHeaders = {
+		"X-sap-adt-sessiontype": "stateful",
+		"x-sap-security-session": "use"
+	};
+	return {
+		async lock(objectUri, options) {
+			const query = options?.transport ? `?_action=LOCK&accessMode=MODIFY&corrNr=${options.transport}` : "?_action=LOCK&accessMode=MODIFY";
+			const response = await client.fetch(`${objectUri}${query}`, {
+				method: "POST",
+				headers: lockHeaders
+			});
+			const handle = parseLockResponse(typeof response === "string" ? response : response?.text ? await response.text() : JSON.stringify(response));
+			store?.register({
+				objectUri,
+				objectName: options?.objectName ?? objectUri.split("/").pop() ?? objectUri,
+				objectType: options?.objectType,
+				lockHandle: handle.handle,
+				transport: handle.correlationNumber,
+				lockedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return handle;
+		},
+		async unlock(objectUri, options) {
+			const query = `?_action=UNLOCK&accessMode=MODIFY&lockHandle=${encodeURIComponent(options.lockHandle)}`;
+			await client.fetch(`${objectUri}${query}`, {
+				method: "POST",
+				headers: unlockHeaders
+			});
+			store?.deregister(objectUri);
+		},
+		async forceUnlock(objectUri, options) {
+			const handle = await this.lock(objectUri, options);
+			await this.unlock(objectUri, { lockHandle: handle.handle });
+		},
+		list() {
+			return store?.list() ?? [];
+		},
+		async cleanup() {
+			const entries = store?.list() ?? [];
+			let ok = 0;
+			let failed = 0;
+			for (const entry of entries) try {
+				const query = `?_action=UNLOCK&accessMode=MODIFY&lockHandle=${encodeURIComponent(entry.lockHandle)}`;
+				await client.fetch(`${entry.objectUri}${query}`, {
+					method: "POST",
+					headers: unlockHeaders
+				});
+				store?.deregister(entry.objectUri);
+				ok++;
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				if (msg.includes("not locked") || msg.includes("not enqueued")) {
+					store?.deregister(entry.objectUri);
+					ok++;
+				} else failed++;
+			}
+			return {
+				ok,
+				failed
+			};
+		},
+		clear() {
+			store?.clear();
+		}
+	};
+}
+
+//#endregion
+//#region src/batch/batch-lock-session.ts
+/**
+* Create a batch lock session over a set of targets.
+*
+* The session does NOT auto-begin; callers drive the lifecycle explicitly so
+* error handling stays visible at the call-site (`try { begin(); … } finally
+* { release(); }`).
+*/
+function createBatchLockSession(lockService, targets, options) {
+	const rollback = options?.rollbackOnError ?? true;
+	const acquired = [];
+	let beganOnce = false;
+	let released = false;
+	return {
+		async begin() {
+			if (beganOnce) throw new Error("BatchLockSession.begin() called more than once");
+			beganOnce = true;
+			for (const target of targets) try {
+				const handle = await lockService.lock(target.objectUri, target.options);
+				acquired.push({
+					target,
+					handle
+				});
+			} catch (err) {
+				if (rollback) {
+					for (const a of acquired.splice(0).reverse()) try {
+						await lockService.unlock(a.target.objectUri, { lockHandle: a.handle.handle });
+					} catch {}
+					released = true;
+				}
+				throw err instanceof Error ? err : /* @__PURE__ */ new Error(`Batch lock failed: ${String(err)}`);
+			}
+			return [...acquired];
+		},
+		async release() {
+			if (released) return {
+				released: 0,
+				failed: []
+			};
+			released = true;
+			const failed = [];
+			let ok = 0;
+			for (const a of acquired.splice(0).reverse()) try {
+				await lockService.unlock(a.target.objectUri, { lockHandle: a.handle.handle });
+				ok++;
+			} catch (err) {
+				failed.push({
+					objectUri: a.target.objectUri,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+			return {
+				released: ok,
+				failed
+			};
+		},
+		handles() {
+			return [...acquired];
+		},
+		get active() {
+			return beganOnce && !released;
+		}
+	};
+}
+
+//#endregion
+export { FileLockStore, createBatchLockSession, createLockService, parseLockResponse };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/store.ts","../src/service.ts","../src/batch/batch-lock-session.ts"],"sourcesContent":["/**\n * Lock Store — persistence layer for ADT lock handles\n *\n * Provides an interface for registering/deregistering lock entries\n * and a file-based implementation that persists to `~/.adt/locks.json`.\n */\n\nimport { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';\nimport { join, dirname } from 'node:path';\nimport { homedir } from 'node:os';\nimport type { LockEntry } from './types';\n\n/**\n * Lock store interface — opt-in persistence for ADT lock handles.\n *\n * Implementations can be file-based, in-memory, or backed by any storage.\n */\nexport interface LockStore {\n  /** Persist a lock entry after successful LOCK */\n  register(entry: LockEntry): void;\n  /** Remove a lock entry after successful UNLOCK */\n  deregister(objectUri: string): void;\n  /** List all persisted lock entries */\n  list(): LockEntry[];\n  /** Remove all entries */\n  clear(): void;\n}\n\n/**\n * File-based lock store.\n *\n * Persists lock entries to a JSON file (default: `~/.adt/locks.json`).\n * Each entry is keyed by objectUri — re-locking the same URI overwrites.\n * File permissions are 0o600 (owner read/write only).\n */\nexport class FileLockStore implements LockStore {\n  private readonly filePath: string;\n\n  constructor(baseDir?: string) {\n    const dir = baseDir ?? join(homedir(), '.adt');\n    this.filePath = join(dir, 'locks.json');\n  }\n\n  register(entry: LockEntry): void {\n    const entries = this.load();\n    const idx = entries.findIndex((e) => e.objectUri === entry.objectUri);\n    if (idx >= 0) entries[idx] = entry;\n    else entries.push(entry);\n    this.save(entries);\n  }\n\n  deregister(objectUri: string): void {\n    const entries = this.load();\n    const filtered = entries.filter((e) => e.objectUri !== objectUri);\n    if (filtered.length !== entries.length) {\n      this.save(filtered);\n    }\n  }\n\n  list(): LockEntry[] {\n    return this.load();\n  }\n\n  clear(): void {\n    this.save([]);\n  }\n\n  private load(): LockEntry[] {\n    if (!existsSync(this.filePath)) return [];\n    try {\n      return JSON.parse(readFileSync(this.filePath, 'utf8')) as LockEntry[];\n    } catch {\n      return [];\n    }\n  }\n\n  private save(entries: LockEntry[]): void {\n    const dir = dirname(this.filePath);\n    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });\n    writeFileSync(this.filePath, JSON.stringify(entries, null, 2), {\n      mode: 0o600,\n    });\n  }\n}\n","/**\n * Lock Service — lock/unlock ADT objects via REST API\n *\n * Provides standalone lock/unlock operations that work with any\n * object URI. Optionally integrates with a LockStore for persistence.\n *\n * Usage:\n *   import { createLockService, FileLockStore } from '@abapify/adt-locks';\n *\n *   const locks = createLockService(client, { store: new FileLockStore() });\n *   const handle = await locks.lock('/sap/bc/adt/oo/classes/zcl_test');\n *   await locks.unlock('/sap/bc/adt/oo/classes/zcl_test', handle);\n */\n\nimport type { LockHandle, LockEntry } from './types';\nimport type { LockStore } from './store';\n\n/** Minimal client interface — anything with an authenticated fetch() */\nexport interface LockClient {\n  fetch(\n    url: string,\n    options?: {\n      method?: string;\n      headers?: Record<string, string>;\n      body?: string;\n    },\n  ): Promise<unknown>;\n}\n\nexport interface LockServiceOptions {\n  /** Optional lock store for persistence */\n  store?: LockStore;\n}\n\nexport interface LockOptions {\n  /** Transport request */\n  transport?: string;\n  /** Object name (for store metadata) */\n  objectName?: string;\n  /** Object type (for store metadata) */\n  objectType?: string;\n}\n\nexport interface UnlockOptions {\n  /** Lock handle — REQUIRED. SAP always requires an explicit handle for unlock. */\n  lockHandle: string;\n}\n\n/**\n * Parse SAP lock response XML to extract lock handle and correlation info.\n *\n * Response format:\n * ```xml\n * <asx:abap>...<DATA>\n *   <LOCK_HANDLE>xxx</LOCK_HANDLE>\n *   <CORRNR>yyy</CORRNR>\n *   <CORRUSER>zzz</CORRUSER>\n * </DATA>...</asx:abap>\n * ```\n */\nexport function parseLockResponse(xml: string): LockHandle {\n  const handleMatch = xml.match(/<LOCK_HANDLE>([^<]+)<\\/LOCK_HANDLE>/);\n  if (!handleMatch) {\n    throw new Error(\n      'Failed to parse lock handle from SAP response. The response format may have changed.',\n    );\n  }\n  const corrNrMatch = xml.match(/<CORRNR>([^<]+)<\\/CORRNR>/);\n  const corrUserMatch = xml.match(/<CORRUSER>([^<]+)<\\/CORRUSER>/);\n\n  return {\n    handle: handleMatch[1],\n    correlationNumber: corrNrMatch?.[1],\n    correlationUser: corrUserMatch?.[1],\n  };\n}\n\nexport interface LockService {\n  /** Acquire a lock on an ADT object */\n  lock(objectUri: string, options?: LockOptions): Promise<LockHandle>;\n  /** Release a lock on an ADT object (lock handle required) */\n  unlock(objectUri: string, options: UnlockOptions): Promise<void>;\n  /**\n   * Force-unlock: acquire a lock to recover the handle, then immediately unlock.\n   * Works when the object is locked by the current user but the handle was lost\n   * (e.g., crashed session). If the object is locked by another user, the lock\n   * call will fail with 403/409.\n   */\n  forceUnlock(objectUri: string, options?: LockOptions): Promise<void>;\n  /** List all persisted lock entries (from store) */\n  list(): LockEntry[];\n  /** Try to UNLOCK every persisted entry, removing successful ones from store */\n  cleanup(): Promise<{ ok: number; failed: number }>;\n  /** Clear the store without sending any UNLOCK requests */\n  clear(): void;\n}\n\nexport function createLockService(\n  client: LockClient,\n  serviceOptions?: LockServiceOptions,\n): LockService {\n  const store = serviceOptions?.store;\n\n  /** Headers for lock operations — stateful session with security session reuse */\n  const lockHeaders = {\n    'X-sap-adt-sessiontype': 'stateful',\n    'x-sap-security-session': 'use',\n    Accept:\n      'application/*,application/vnd.sap.as+xml;charset=UTF-8;dataname=com.sap.adt.lock.result',\n  };\n\n  /** Headers for unlock operations */\n  const unlockHeaders = {\n    'X-sap-adt-sessiontype': 'stateful',\n    'x-sap-security-session': 'use',\n  };\n\n  return {\n    async lock(objectUri, options) {\n      const query = options?.transport\n        ? `?_action=LOCK&accessMode=MODIFY&corrNr=${options.transport}`\n        : '?_action=LOCK&accessMode=MODIFY';\n\n      const response = await client.fetch(`${objectUri}${query}`, {\n        method: 'POST',\n        headers: lockHeaders,\n      });\n\n      // The adapter may return a string (text/xml) or a parsed object;\n      // parseLockResponse needs the raw XML string.\n      const body =\n        typeof response === 'string'\n          ? response\n          : (response as Response)?.text\n            ? await (response as Response).text()\n            : JSON.stringify(response);\n      const handle = parseLockResponse(body);\n\n      store?.register({\n        objectUri,\n        objectName:\n          options?.objectName ?? objectUri.split('/').pop() ?? objectUri,\n        objectType: options?.objectType,\n        lockHandle: handle.handle,\n        transport: handle.correlationNumber,\n        lockedAt: new Date().toISOString(),\n      });\n\n      return handle;\n    },\n\n    async unlock(objectUri, options) {\n      const query = `?_action=UNLOCK&accessMode=MODIFY&lockHandle=${encodeURIComponent(options.lockHandle)}`;\n\n      await client.fetch(`${objectUri}${query}`, {\n        method: 'POST',\n        headers: unlockHeaders,\n      });\n\n      store?.deregister(objectUri);\n    },\n\n    async forceUnlock(objectUri, options) {\n      // Lock to recover/acquire the handle, then immediately unlock\n      const handle = await this.lock(objectUri, options);\n      await this.unlock(objectUri, { lockHandle: handle.handle });\n    },\n\n    list() {\n      return store?.list() ?? [];\n    },\n\n    async cleanup() {\n      const entries = store?.list() ?? [];\n      let ok = 0;\n      let failed = 0;\n\n      for (const entry of entries) {\n        try {\n          const query = `?_action=UNLOCK&accessMode=MODIFY&lockHandle=${encodeURIComponent(entry.lockHandle)}`;\n          await client.fetch(`${entry.objectUri}${query}`, {\n            method: 'POST',\n            headers: unlockHeaders,\n          });\n          store?.deregister(entry.objectUri);\n          ok++;\n        } catch (err: unknown) {\n          const msg = err instanceof Error ? err.message : String(err);\n          if (msg.includes('not locked') || msg.includes('not enqueued')) {\n            store?.deregister(entry.objectUri);\n            ok++;\n          } else {\n            failed++;\n          }\n        }\n      }\n\n      return { ok, failed };\n    },\n\n    clear() {\n      store?.clear();\n    },\n  };\n}\n","/**\n * BatchLockSession — acquire and release N locks with best-effort rollback.\n *\n * SAP ADT has no transactional multi-object save. A \"batch lock\" is therefore\n * a **best-effort** construct:\n *\n *   - `begin()` sequentially acquires a lock on every target. If any lock\n *     acquisition fails, every previously acquired lock in this session is\n *     released before the error is rethrown — leaving the backend in the\n *     same state it was before `begin()` was called.\n *\n *   - `release()` unlocks every successfully acquired handle, swallowing\n *     per-object unlock failures (they are surfaced through the returned\n *     result for the caller to inspect).\n *\n *   - `handles()` exposes the acquired handles so callers can thread them\n *     into downstream save/PUT flows without re-locking.\n *\n * The session is **single-use**: once released (explicitly or via rollback),\n * it cannot be reused. Tests exercise acquire/release/partial-failure paths.\n *\n * Consumer rationale: ADK's per-object `save({mode:'update'})` already owns\n * its own lock/unlock cycle. `BatchLockSession` is therefore positioned as an\n * outer pre-flight primitive — acquire across a whole ChangePlan to catch\n * conflicts BEFORE we start mutating SAP, release before handing off to ADK.\n * When ADK's save cycle later re-locks per object it simply re-uses the same\n * security session (the CSRF token survives), so the double lock is cheap.\n */\nimport type { LockHandle } from '../types';\nimport type { LockService, LockOptions } from '../service';\n\nexport interface BatchLockTarget {\n  /** ADT object URI — e.g. `/sap/bc/adt/oo/classes/zcl_foo` */\n  objectUri: string;\n  /** Per-target lock options (transport, object name/type for the store). */\n  options?: LockOptions;\n}\n\nexport interface BatchLockAcquisition {\n  target: BatchLockTarget;\n  handle: LockHandle;\n}\n\nexport interface BatchReleaseResult {\n  released: number;\n  failed: Array<{ objectUri: string; error: string }>;\n}\n\nexport interface BatchLockSessionOptions {\n  /**\n   * When true, `begin()` stops on the first failure and rolls back locks\n   * already acquired in this session. When false (rare), errors are\n   * collected and returned but already-acquired locks are kept — use only\n   * for diagnostic tooling. Default: true.\n   */\n  rollbackOnError?: boolean;\n}\n\nexport interface BatchLockSession {\n  /** Acquire all configured locks. Rollback on failure (by default). */\n  begin(): Promise<BatchLockAcquisition[]>;\n  /** Release every currently held handle. Safe to call multiple times. */\n  release(): Promise<BatchReleaseResult>;\n  /** Snapshot of currently held handles. */\n  handles(): ReadonlyArray<BatchLockAcquisition>;\n  /** Has `begin()` completed successfully? */\n  readonly active: boolean;\n}\n\n/**\n * Create a batch lock session over a set of targets.\n *\n * The session does NOT auto-begin; callers drive the lifecycle explicitly so\n * error handling stays visible at the call-site (`try { begin(); … } finally\n * { release(); }`).\n */\nexport function createBatchLockSession(\n  lockService: Pick<LockService, 'lock' | 'unlock'>,\n  targets: BatchLockTarget[],\n  options?: BatchLockSessionOptions,\n): BatchLockSession {\n  const rollback = options?.rollbackOnError ?? true;\n  const acquired: BatchLockAcquisition[] = [];\n  let beganOnce = false;\n  let released = false;\n\n  return {\n    async begin() {\n      if (beganOnce) {\n        throw new Error('BatchLockSession.begin() called more than once');\n      }\n      beganOnce = true;\n\n      for (const target of targets) {\n        try {\n          const handle = await lockService.lock(\n            target.objectUri,\n            target.options,\n          );\n          acquired.push({ target, handle });\n        } catch (err) {\n          if (rollback) {\n            // Best-effort: release what we already have, then propagate.\n            for (const a of acquired.splice(0).reverse()) {\n              try {\n                await lockService.unlock(a.target.objectUri, {\n                  lockHandle: a.handle.handle,\n                });\n              } catch {\n                /* swallow — primary failure is the real signal */\n              }\n            }\n            // Session is done — no further release() work possible.\n            released = true;\n          }\n          throw err instanceof Error\n            ? err\n            : new Error(`Batch lock failed: ${String(err)}`);\n        }\n      }\n      return [...acquired];\n    },\n\n    async release() {\n      if (released) return { released: 0, failed: [] };\n      released = true;\n\n      const failed: BatchReleaseResult['failed'] = [];\n      let ok = 0;\n      // Release in reverse acquisition order — symmetric with begin()'s\n      // rollback path and avoids surprising the SAP enqueue server.\n      for (const a of acquired.splice(0).reverse()) {\n        try {\n          await lockService.unlock(a.target.objectUri, {\n            lockHandle: a.handle.handle,\n          });\n          ok++;\n        } catch (err) {\n          failed.push({\n            objectUri: a.target.objectUri,\n            error: err instanceof Error ? err.message : String(err),\n          });\n        }\n      }\n      return { released: ok, failed };\n    },\n\n    handles() {\n      return [...acquired];\n    },\n\n    get active() {\n      return beganOnce && !released;\n    },\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abapify/adt-locks",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "ADT lock/unlock operations and lock store management",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@abapify/adt-client": "0.4.0"
+    "@abapify/adt-client": "0.4.1"
   },
   "publishConfig": {
     "access": "public"