@outfitter/file-ops 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/index.d.ts

@@ -87,6 +87,33 @@ interface FileLock {
 	timestamp: number;
 }
 /**
+* Represents an acquired shared (reader) file lock.
+*
+* Extends FileLock with a lock type discriminator. Multiple processes can
+* hold shared locks simultaneously, but shared locks block exclusive locks.
+*/
+interface SharedFileLock extends FileLock {
+	/** Discriminator indicating this is a shared/reader lock */
+	lockType: "shared";
+	/** Unique identifier for this reader (allows multiple readers from same PID) */
+	readerId: string;
+}
+/**
+* Options for lock acquisition.
+*/
+interface LockOptions {
+	/**
+	* Maximum time in milliseconds to wait for lock acquisition.
+	* If not specified, fails immediately if lock cannot be acquired.
+	*/
+	timeout?: number;
+	/**
+	* Interval in milliseconds between retry attempts when waiting.
+	* @defaultValue 50
+	*/
+	retryInterval?: number;
+}
+/**
 * Finds the workspace root by searching upward for marker files/directories.
 *
 * Searches from startPath up to the filesystem root (or stopAt if specified),
@@ -193,20 +220,24 @@ declare function glob(pattern: string, options?: GlobOptions): Promise<Result<st
 */
 declare function globSync(pattern: string, options?: GlobOptions): Result<string[], InstanceType<typeof InternalError>>;
 /**
-* Acquires an advisory lock on a file.
+* Acquires an exclusive advisory lock on a file.
 *
 * Creates a .lock file next to the target file with lock metadata (PID, timestamp).
 * Uses atomic file creation (wx flag) to prevent race conditions.
 *
+* Exclusive locks block and are blocked by both shared and exclusive locks.
+* Use shared locks (acquireSharedLock) for read-only operations.
+*
 * Important: This is advisory locking. All processes must cooperate by using
 * these locking APIs. The filesystem does not enforce the lock.
 *
 * Prefer using withLock for automatic lock release.
 *
 * @param path - Absolute path to the file to lock
+* @param options - Lock options including timeout and retry interval
 * @returns Result containing FileLock on success, or ConflictError if already locked
 */
-declare function acquireLock(path: string): Promise<Result<FileLock, InstanceType<typeof ConflictError>>>;
+declare function acquireLock(path: string, options?: LockOptions): Promise<Result<FileLock, InstanceType<typeof ConflictError>>>;
 /**
 * Releases a file lock by removing the .lock file.
 *
@@ -273,4 +304,45 @@ declare function atomicWrite(path: string, content: string, options?: AtomicWrit
 * @returns Result indicating success, ValidationError if serialization fails, or InternalError on write failure
 */
 declare function atomicWriteJson<T>(path: string, data: T, options?: AtomicWriteOptions): Promise<Result<void, InstanceType<typeof InternalError> | InstanceType<typeof ValidationError>>>;
-export { withLock, securePath, resolveSafePath, releaseLock, isPathSafe, isLocked, isInsideWorkspace, globSync, glob, getRelativePath, findWorkspaceRoot, atomicWriteJson, atomicWrite, acquireLock, GlobOptions, FindWorkspaceRootOptions, FileLock, AtomicWriteOptions };
+/**
+* Acquires a shared (reader) lock on a file.
+*
+* Multiple readers can hold shared locks simultaneously. Shared locks are
+* blocked by exclusive locks. Uses the same .lock file as exclusive locks
+* with a JSON format that distinguishes lock types.
+*
+* Important: This is advisory locking. All processes must cooperate by using
+* these locking APIs. The filesystem does not enforce the lock.
+*
+* @param path - Absolute path to the file to lock
+* @param options - Lock options including timeout and retry interval
+* @returns Result containing SharedFileLock on success, or ConflictError if blocked by exclusive lock
+*/
+declare function acquireSharedLock(path: string, options?: LockOptions): Promise<Result<SharedFileLock, InstanceType<typeof ConflictError>>>;
+/**
+* Releases a shared (reader) lock.
+*
+* Removes this process from the list of readers in the lock file.
+* If this is the last reader, the lock file is deleted.
+*
+* @param lock - Shared lock object returned from acquireSharedLock
+* @returns Result indicating success, or InternalError if lock file cannot be modified
+*/
+declare function releaseSharedLock(lock: SharedFileLock): Promise<Result<void, InstanceType<typeof InternalError>>>;
+/**
+* Executes a callback while holding a shared (reader) lock on a file.
+*
+* Lock is automatically released after callback completes, whether it
+* succeeds or throws an error. This is the recommended way to use shared locks.
+*
+* Multiple readers can hold shared locks simultaneously. Use this for
+* read-only operations that should not block other readers.
+*
+* @typeParam T - Return type of the callback
+* @param path - Absolute path to the file to lock
+* @param callback - Async callback to execute while holding lock
+* @param options - Lock options including timeout and retry interval
+* @returns Result containing callback return value, ConflictError if blocked, or InternalError on failure
+*/
+declare function withSharedLock<T>(path: string, callback: () => Promise<T>, options?: LockOptions): Promise<Result<T, InstanceType<typeof ConflictError> | InstanceType<typeof InternalError>>>;
+export { withSharedLock, withLock, securePath, resolveSafePath, releaseSharedLock, releaseLock, isPathSafe, isLocked, isInsideWorkspace, globSync, glob, getRelativePath, findWorkspaceRoot, atomicWriteJson, atomicWrite, acquireSharedLock, acquireLock, SharedFileLock, LockOptions, GlobOptions, FindWorkspaceRootOptions, FileLock, AtomicWriteOptions };

package/dist/index.js

@@ -227,31 +227,64 @@ function globSync(pattern, options) {
     }));
   }
 }
-async function acquireLock(path) {
+async function acquireLock(path, options) {
   const lockPath = `${path}.lock`;
-  const lockFile = Bun.file(lockPath);
-  if (await lockFile.exists()) {
-    return Result.err(new ConflictError({
-      message: `File is already locked: ${path}`
-    }));
-  }
-  const lock = {
-    path,
-    lockPath,
-    pid: process.pid,
-    timestamp: Date.now()
-  };
-  try {
-    await fsWriteFile(lockPath, JSON.stringify({ pid: lock.pid, timestamp: lock.timestamp }), { flag: "wx" });
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+  const startTime = Date.now();
+  const timeout = options?.timeout ?? 0;
+  const retryInterval = options?.retryInterval ?? 50;
+  while (true) {
+    const lockFile = Bun.file(lockPath);
+    if (await lockFile.exists()) {
+      try {
+        const lockContent = await lockFile.text();
+        const lockData = JSON.parse(lockContent);
+        if (lockData.type === "shared" && lockData.readers.length > 0) {
+          if (timeout > 0 && Date.now() - startTime < timeout) {
+            await Bun.sleep(retryInterval);
+            continue;
+          }
+          return Result.err(new ConflictError({
+            message: `File has shared locks: ${path}`
+          }));
+        }
+      } catch {}
+      if (timeout > 0 && Date.now() - startTime < timeout) {
+        await Bun.sleep(retryInterval);
+        continue;
+      }
       return Result.err(new ConflictError({
         message: `File is already locked: ${path}`
       }));
     }
-    throw error;
+    const lock = {
+      path,
+      lockPath,
+      pid: process.pid,
+      timestamp: Date.now()
+    };
+    const exclusiveLockData = {
+      type: "exclusive",
+      pid: lock.pid,
+      timestamp: lock.timestamp
+    };
+    try {
+      await fsWriteFile(lockPath, JSON.stringify(exclusiveLockData), {
+        flag: "wx"
+      });
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+        if (timeout > 0 && Date.now() - startTime < timeout) {
+          await Bun.sleep(retryInterval);
+          continue;
+        }
+        return Result.err(new ConflictError({
+          message: `File is already locked: ${path}`
+        }));
+      }
+      throw error;
+    }
+    return Result.ok(lock);
   }
-  return Result.ok(lock);
 }
 async function releaseLock(lock) {
   try {
@@ -331,10 +364,181 @@ async function atomicWriteJson(path, data, options) {
     }));
   }
 }
+async function acquireSharedLock(path, options) {
+  const lockPath = `${path}.lock`;
+  const metaLockPath = `${lockPath}.meta`;
+  const startTime = Date.now();
+  const timeout = options?.timeout ?? 0;
+  const retryInterval = options?.retryInterval ?? 50;
+  while (true) {
+    const metaLockResult = await acquireLock(metaLockPath, {
+      timeout: retryInterval,
+      retryInterval: 10
+    });
+    if (metaLockResult.isErr()) {
+      if (timeout > 0 && Date.now() - startTime < timeout) {
+        await Bun.sleep(retryInterval);
+        continue;
+      }
+      return Result.err(new ConflictError({
+        message: `Failed to acquire shared lock: ${path}`
+      }));
+    }
+    const metaLock = metaLockResult.value;
+    const lockFile = Bun.file(lockPath);
+    const exists = await lockFile.exists();
+    if (exists) {
+      try {
+        const lockContent = await lockFile.text();
+        const lockData = JSON.parse(lockContent);
+        if (lockData.type === "exclusive") {
+          await releaseLock(metaLock);
+          if (timeout > 0 && Date.now() - startTime < timeout) {
+            await Bun.sleep(retryInterval);
+            continue;
+          }
+          return Result.err(new ConflictError({
+            message: `File is exclusively locked: ${path}`
+          }));
+        }
+        const readerId2 = Bun.randomUUIDv7();
+        const newReader = {
+          id: readerId2,
+          pid: process.pid,
+          timestamp: Date.now()
+        };
+        lockData.readers.push(newReader);
+        await fsWriteFile(lockPath, JSON.stringify(lockData));
+        await releaseLock(metaLock);
+        return Result.ok({
+          path,
+          lockPath,
+          pid: process.pid,
+          timestamp: newReader.timestamp,
+          lockType: "shared",
+          readerId: readerId2
+        });
+      } catch {
+        await releaseLock(metaLock);
+        if (timeout > 0 && Date.now() - startTime < timeout) {
+          await Bun.sleep(retryInterval);
+          continue;
+        }
+        return Result.err(new ConflictError({
+          message: `File is locked: ${path}`
+        }));
+      }
+    }
+    const readerId = Bun.randomUUIDv7();
+    const timestamp = Date.now();
+    const sharedLockData = {
+      type: "shared",
+      readers: [
+        {
+          id: readerId,
+          pid: process.pid,
+          timestamp
+        }
+      ]
+    };
+    try {
+      await fsWriteFile(lockPath, JSON.stringify(sharedLockData), {
+        flag: "wx"
+      });
+      await releaseLock(metaLock);
+      return Result.ok({
+        path,
+        lockPath,
+        pid: process.pid,
+        timestamp,
+        lockType: "shared",
+        readerId
+      });
+    } catch (error) {
+      await releaseLock(metaLock);
+      if (error instanceof Error && "code" in error && error.code === "EEXIST" && timeout > 0 && Date.now() - startTime < timeout) {
+        await Bun.sleep(retryInterval);
+        continue;
+      }
+      return Result.err(new ConflictError({
+        message: `Failed to acquire shared lock: ${path}`
+      }));
+    }
+  }
+}
+async function releaseSharedLock(lock) {
+  const metaLockPath = `${lock.lockPath}.meta`;
+  const metaLockResult = await acquireLock(metaLockPath, {
+    timeout: 5000,
+    retryInterval: 10
+  });
+  if (metaLockResult.isErr()) {
+    return Result.err(new InternalError({
+      message: "Failed to acquire meta-lock for shared lock release"
+    }));
+  }
+  const metaLock = metaLockResult.value;
+  try {
+    const lockFile = Bun.file(lock.lockPath);
+    const exists = await lockFile.exists();
+    if (!exists) {
+      await releaseLock(metaLock);
+      return Result.ok(undefined);
+    }
+    const lockContent = await lockFile.text();
+    const lockData = JSON.parse(lockContent);
+    if (lockData.type !== "shared") {
+      await releaseLock(metaLock);
+      return Result.err(new InternalError({
+        message: "Lock file is not a shared lock"
+      }));
+    }
+    lockData.readers = lockData.readers.filter((reader) => reader.id !== lock.readerId);
+    if (lockData.readers.length === 0) {
+      await unlink(lock.lockPath);
+    } else {
+      await fsWriteFile(lock.lockPath, JSON.stringify(lockData));
+    }
+    await releaseLock(metaLock);
+    return Result.ok(undefined);
+  } catch (error) {
+    await releaseLock(metaLock);
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Failed to release shared lock"
+    }));
+  }
+}
+async function withSharedLock(path, callback, options) {
+  const lockResult = await acquireSharedLock(path, options);
+  if (lockResult.isErr()) {
+    return lockResult;
+  }
+  const lock = lockResult.value;
+  try {
+    const result = await callback();
+    const releaseResult = await releaseSharedLock(lock);
+    if (releaseResult.isErr()) {
+      return releaseResult;
+    }
+    return Result.ok(result);
+  } catch (error) {
+    const releaseResult = await releaseSharedLock(lock);
+    if (releaseResult.isErr()) {
+      return Result.err(new InternalError({
+        message: `Callback failed: ${error instanceof Error ? error.message : "Unknown error"}; lock release also failed: ${releaseResult.error.message}`
+      }));
+    }
+    return Result.err(new InternalError({
+      message: error instanceof Error ? error.message : "Callback failed"
+    }));
+  }
+}
 export {
+  withSharedLock,
   withLock,
   securePath,
   resolveSafePath,
+  releaseSharedLock,
   releaseLock,
   isPathSafe,
   isLocked,
@@ -345,5 +549,6 @@ export {
   findWorkspaceRoot,
   atomicWriteJson,
   atomicWrite,
+  acquireSharedLock,
   acquireLock
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/file-ops",
   "description": "Workspace detection, secure path handling, and file locking for Outfitter",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "type": "module",
   "files": [
     "dist"