@oh-my-pi/pi-utils 17.2.5 → 17.2.7

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [17.2.6] - 2026-08-03
+
+### Added
+
+- Added a shared `file-lock` utility backed by process-owned native OS locks with automatic crash release and bounded asynchronous retry.
+
 ## [17.2.5] - 2026-08-03
 
 ### Added

package/dist/types/file-lock.d.ts

@@ -0,0 +1,21 @@
+import { FileLock as NativeFileLock } from "@oh-my-pi/pi-natives";
+/** Controls bounded waiting when an advisory file lock is contended. */
+export interface FileLockOptions {
+    /** Maximum acquisition attempts, including the initial attempt. */
+    retries?: number;
+    /** Delay between acquisition attempts. */
+    retryDelayMs?: number;
+}
+declare function getLockPath(filePath: string): string;
+declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
+/** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Test-only acquisition handle for forcing ownership handoffs. This is not
+ * part of the supported package API.
+ */
+export declare const __internalsForTesting: {
+    tryAcquireLock: typeof tryAcquireLock;
+    getLockPath: typeof getLockPath;
+};
+export {};

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export * from "./color.js";
 export * from "./dirs.js";
 export * from "./env.js";
 export * from "./fetch-retry.js";
+export * from "./file-lock.js";
 export * from "./format.js";
 export * from "./frontmatter.js";
 export * from "./fs-error.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "17.2.5",
+	"version": "17.2.7",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.2.5",
+		"@oh-my-pi/pi-natives": "17.2.7",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "5.0.0"

package/src/file-lock.ts

@@ -0,0 +1,66 @@
+/**
+ * Cross-process advisory lock for packages that serialize access to an
+ * on-disk resource. The native handle is process-owned and automatically
+ * released on exit: Linux uses abstract Unix sockets, Windows uses named
+ * mutexes, and other Unix platforms use `flock(2)` on `${filePath}.lock`.
+ */
+import * as path from "node:path";
+import { FileLock as NativeFileLock } from "@oh-my-pi/pi-natives";
+
+/** Controls bounded waiting when an advisory file lock is contended. */
+export interface FileLockOptions {
+	/** Maximum acquisition attempts, including the initial attempt. */
+	retries?: number;
+	/** Delay between acquisition attempts. */
+	retryDelayMs?: number;
+}
+
+const DEFAULT_OPTIONS: Required<FileLockOptions> = {
+	retries: 50,
+	retryDelayMs: 100,
+};
+
+function getLockPath(filePath: string): string {
+	return `${path.resolve(filePath)}.lock`;
+}
+
+function tryAcquireLock(lockPath: string): NativeFileLock | null {
+	const lock = NativeFileLock.tryAcquire(lockPath);
+	return lock.acquired ? lock : null;
+}
+
+async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<NativeFileLock> {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const lockPath = getLockPath(filePath);
+
+	for (let attempt = 0; attempt < opts.retries; attempt++) {
+		const lock = tryAcquireLock(lockPath);
+		if (lock) return lock;
+		if (attempt + 1 < opts.retries) await Bun.sleep(opts.retryDelayMs);
+	}
+
+	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+}
+
+/** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export async function withFileLock<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+	options: FileLockOptions = {},
+): Promise<T> {
+	const lock = await acquireLock(filePath, options);
+	try {
+		return await fn();
+	} finally {
+		lock.release();
+	}
+}
+
+/**
+ * Test-only acquisition handle for forcing ownership handoffs. This is not
+ * part of the supported package API.
+ */
+export const __internalsForTesting = {
+	tryAcquireLock,
+	getLockPath,
+};

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./color";
 export * from "./dirs";
 export * from "./env";
 export * from "./fetch-retry";
+export * from "./file-lock";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";