atomic-lockfile 0.0.1-security → 1.4.2

package/src/compat/esm.ts

@@ -0,0 +1,11 @@
+export { acquireLock as lock } from '../core/acquire.js';
+export { isLocked as check } from '../core/check.js';
+export { withLock } from '../promise/withLock.js';
+export { lockSync } from '../sync/lock.js';
+export { unlockSync } from '../sync/unlock.js';
+export { checkSync } from '../sync/check.js';
+
+export { LockError } from '../errors/LockError.js';
+export { ConflictError } from '../errors/ConflictError.js';
+export { TimeoutError } from '../errors/TimeoutError.js';
+export { StaleError } from '../errors/StaleError.js';

package/src/compat/index.ts

@@ -0,0 +1,3 @@
+export * from './v1.js';
+export * as cjs from './cjs.js';
+export * as esm from './esm.js';

package/src/compat/v1.ts

@@ -0,0 +1,35 @@
+import { acquireLock } from '../core/acquire.js';
+import { releaseLock } from '../core/release.js';
+import { isLocked } from '../core/check.js';
+import type { LockHandle } from '../types/lock.js';
+
+export interface V1LockOptions {
+  wait?: number;
+  stale?: number;
+  retries?: number;
+  retryWait?: number;
+}
+
+export async function lock(file: string, options: V1LockOptions = {}): Promise<() => Promise<void>> {
+  const handle: LockHandle = await acquireLock(file, {
+    ...(options.wait !== undefined ? { timeout: options.wait } : {}),
+    ...(options.stale !== undefined ? { staleAge: options.stale } : {}),
+    ...(options.retries !== undefined ? { retries: options.retries } : {}),
+    ...(options.retryWait !== undefined ? { retryDelay: options.retryWait } : {}),
+    removeStale: true,
+  });
+  return () => handle.release();
+}
+
+export async function unlock(file: string): Promise<void> {
+  const { unlinkSafe } = await import('../utils/fs.js');
+  await unlinkSafe(file + '.lock');
+}
+
+export async function check(file: string, options: V1LockOptions = {}): Promise<boolean> {
+  return isLocked(file, {
+    ...(options.stale !== undefined ? { staleAge: options.stale } : {}),
+  });
+}
+
+export const v1 = { lock, unlock, check };

package/src/config/defaults.ts

@@ -0,0 +1,20 @@
+import type { GlobalOptions } from '../types/options.js';
+import {
+  DEFAULT_LOCK_EXTENSION,
+  DEFAULT_TTL,
+  DEFAULT_STALE_AGE,
+  DEFAULT_RETRIES,
+  DEFAULT_STRATEGY,
+  DEFAULT_ADAPTER,
+} from '../constants/defaults.js';
+
+export const DEFAULT_GLOBAL_OPTIONS: Required<GlobalOptions> = {
+  lockExtension: DEFAULT_LOCK_EXTENSION,
+  defaultTtl: DEFAULT_TTL,
+  defaultStaleAge: DEFAULT_STALE_AGE,
+  defaultRetries: DEFAULT_RETRIES,
+  defaultStrategy: DEFAULT_STRATEGY,
+  defaultAdapter: DEFAULT_ADAPTER,
+  logLevel: 'silent',
+  tmpDir: process.env['TMPDIR'] ?? '/tmp',
+};

package/src/config/index.ts

@@ -0,0 +1,24 @@
+export { DEFAULT_GLOBAL_OPTIONS } from './defaults.js';
+export { CONFIG_SCHEMA } from './schema.js';
+export type { ConfigSchema } from './schema.js';
+
+import type { GlobalOptions } from '../types/options.js';
+import { DEFAULT_GLOBAL_OPTIONS } from './defaults.js';
+
+let globalConfig: Required<GlobalOptions> = { ...DEFAULT_GLOBAL_OPTIONS };
+
+export function getConfig(): Required<GlobalOptions> {
+  return { ...globalConfig };
+}
+
+export function setConfig(options: Partial<GlobalOptions>): void {
+  globalConfig = { ...globalConfig, ...options };
+}
+
+export function resetConfig(): void {
+  globalConfig = { ...DEFAULT_GLOBAL_OPTIONS };
+}
+
+export function getConfigValue<K extends keyof GlobalOptions>(key: K): Required<GlobalOptions>[K] {
+  return globalConfig[key];
+}

package/src/config/schema.ts

@@ -0,0 +1,66 @@
+import type { GlobalOptions } from '../types/options.js';
+
+export type ConfigSchema = {
+  [K in keyof GlobalOptions]: {
+    type: string;
+    required: boolean;
+    default?: GlobalOptions[K];
+    description: string;
+    validate?: (value: unknown) => boolean;
+  };
+};
+
+export const CONFIG_SCHEMA: ConfigSchema = {
+  lockExtension: {
+    type: 'string',
+    required: false,
+    default: '.lock',
+    description: 'File extension appended to the target path to form the lock path',
+    validate: (v) => typeof v === 'string' && v.startsWith('.'),
+  },
+  defaultTtl: {
+    type: 'number',
+    required: false,
+    default: 30_000,
+    description: 'Default TTL in milliseconds for all locks',
+    validate: (v) => typeof v === 'number' && v > 0,
+  },
+  defaultStaleAge: {
+    type: 'number',
+    required: false,
+    default: 30_000,
+    description: 'Default stale age threshold in milliseconds',
+    validate: (v) => typeof v === 'number' && v > 0,
+  },
+  defaultRetries: {
+    type: 'number',
+    required: false,
+    default: 5,
+    description: 'Default number of retries when acquiring a lock',
+    validate: (v) => typeof v === 'number' && v >= 0,
+  },
+  defaultStrategy: {
+    type: 'string',
+    required: false,
+    default: 'exclusive',
+    description: 'Default locking strategy',
+  },
+  defaultAdapter: {
+    type: 'string',
+    required: false,
+    default: 'atomic',
+    description: 'Default adapter to use for lock file operations',
+  },
+  logLevel: {
+    type: 'string',
+    required: false,
+    default: 'silent',
+    description: 'Log level for internal logging',
+  },
+  tmpDir: {
+    type: 'string',
+    required: false,
+    description: 'Temporary directory for atomic write operations',
+    validate: (v) => typeof v === 'string' && v.length > 0,
+  },
+};

package/src/constants/defaults.ts

@@ -0,0 +1,14 @@
+export const DEFAULT_LOCK_EXTENSION = '.lock';
+export const DEFAULT_TTL = 30_000;
+export const DEFAULT_STALE_AGE = 30_000;
+export const DEFAULT_RETRIES = 5;
+export const DEFAULT_RETRY_DELAY = 100;
+export const DEFAULT_RETRY_MAX_DELAY = 5_000;
+export const DEFAULT_HEARTBEAT_INTERVAL = 5_000;
+export const DEFAULT_TIMEOUT = 60_000;
+export const DEFAULT_STRATEGY = 'exclusive';
+export const DEFAULT_ADAPTER = 'atomic';
+export const DEFAULT_LOCK_VERSION = 1;
+export const DEFAULT_NONCE_LENGTH = 16;
+export const DEFAULT_CONCURRENCY = 1;
+export const DEFAULT_META = {} as const;

package/src/constants/errors.ts

@@ -0,0 +1,39 @@
+export const ERROR_CODES = {
+  LOCK_CONFLICT: 'ELOCK_CONFLICT',
+  LOCK_TIMEOUT: 'ELOCK_TIMEOUT',
+  LOCK_STALE: 'ELOCK_STALE',
+  LOCK_EXPIRED: 'ELOCK_EXPIRED',
+  LOCK_NOT_OWNED: 'ELOCK_NOT_OWNED',
+  LOCK_NOT_FOUND: 'ELOCK_NOT_FOUND',
+  LOCK_INVALID: 'ELOCK_INVALID',
+  LOCK_CORRUPT: 'ELOCK_CORRUPT',
+  LOCK_PERMISSION: 'ELOCK_PERMISSION',
+  LOCK_IO: 'ELOCK_IO',
+  LOCK_VALIDATION: 'ELOCK_VALIDATION',
+  LOCK_ABORTED: 'ELOCK_ABORTED',
+  LOCK_NOT_ACQUIRED: 'ELOCK_NOT_ACQUIRED',
+  LOCK_ALREADY_ACQUIRED: 'ELOCK_ALREADY_ACQUIRED',
+  LOCK_REFRESH_FAILED: 'ELOCK_REFRESH_FAILED',
+  LOCK_RELEASE_FAILED: 'ELOCK_RELEASE_FAILED',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+export const ERROR_MESSAGES: Record<ErrorCode, string> = {
+  ELOCK_CONFLICT: 'Lock is already held by another process',
+  ELOCK_TIMEOUT: 'Timed out waiting to acquire lock',
+  ELOCK_STALE: 'Lock file is stale',
+  ELOCK_EXPIRED: 'Lock file has expired',
+  ELOCK_NOT_OWNED: 'Lock is not owned by this process',
+  ELOCK_NOT_FOUND: 'Lock file not found',
+  ELOCK_INVALID: 'Lock file is invalid',
+  ELOCK_CORRUPT: 'Lock file is corrupt or unreadable',
+  ELOCK_PERMISSION: 'Insufficient permissions to acquire lock',
+  ELOCK_IO: 'I/O error while operating on lock',
+  ELOCK_VALIDATION: 'Lock path or options failed validation',
+  ELOCK_ABORTED: 'Lock acquisition was aborted',
+  ELOCK_NOT_ACQUIRED: 'No lock has been acquired',
+  ELOCK_ALREADY_ACQUIRED: 'Lock has already been acquired',
+  ELOCK_REFRESH_FAILED: 'Failed to refresh lock heartbeat',
+  ELOCK_RELEASE_FAILED: 'Failed to release lock',
+};

package/src/constants/index.ts

@@ -0,0 +1,14 @@
+export * from './defaults.js';
+export * from './errors.js';
+export * from './timeouts.js';
+export * from './signals.js';
+
+export const LOCK_FILE_MAGIC = 'atomic-lockfile/v1';
+export const LOCK_DATA_ENCODING = 'utf-8' as const;
+export const LOCK_FILE_MODE = 0o644;
+export const LOCK_DIR_MODE = 0o755;
+export const LOCK_OPEN_FLAGS_EXCLUSIVE = 'wx';
+export const LOCK_OPEN_FLAGS_READ = 'r';
+export const LOCK_TMP_PREFIX = '.atomic-lockfile-tmp-';
+export const LOCK_PID_FILE_SUFFIX = '.pid';
+export const LOCK_BACKUP_SUFFIX = '.bak';

package/src/constants/signals.ts

@@ -0,0 +1,26 @@
+export const CLEANUP_SIGNALS = [
+  'SIGINT',
+  'SIGTERM',
+  'SIGHUP',
+  'SIGQUIT',
+  'SIGABRT',
+] as const;
+
+export type CleanupSignal = (typeof CLEANUP_SIGNALS)[number];
+
+export const PROCESS_EXIT_EVENTS = [
+  'exit',
+  'beforeExit',
+  'uncaughtException',
+  'unhandledRejection',
+] as const;
+
+export type ProcessExitEvent = (typeof PROCESS_EXIT_EVENTS)[number];
+
+export const SIGNAL_DESCRIPTIONS: Record<CleanupSignal, string> = {
+  SIGINT: 'Interrupt from keyboard (Ctrl+C)',
+  SIGTERM: 'Termination signal',
+  SIGHUP: 'Hangup detected on controlling terminal',
+  SIGQUIT: 'Quit from keyboard',
+  SIGABRT: 'Abort signal from abort()',
+};

package/src/constants/timeouts.ts

@@ -0,0 +1,18 @@
+export const TIMEOUT_ACQUIRE = 60_000;
+export const TIMEOUT_RELEASE = 10_000;
+export const TIMEOUT_REFRESH = 5_000;
+export const TIMEOUT_CHECK = 2_000;
+export const TIMEOUT_LIST = 5_000;
+export const TIMEOUT_CLEANUP = 30_000;
+
+export const INTERVAL_HEARTBEAT = 5_000;
+export const INTERVAL_POLL = 50;
+export const INTERVAL_STALE_CHECK = 10_000;
+
+export const DELAY_INITIAL_RETRY = 100;
+export const DELAY_MAX_RETRY = 5_000;
+export const DELAY_BACKOFF_FACTOR = 2;
+export const DELAY_JITTER_MAX = 50;
+
+export const AGE_STALE_DEFAULT = 30_000;
+export const AGE_EXPIRED_DEFAULT = 60_000;

package/src/core/acquire.ts

@@ -0,0 +1,54 @@
+import type { AcquireOptions } from '../types/options.js';
+import type { LockHandle } from '../types/lock.js';
+import { resolveLockPath } from '../utils/path.js';
+import { getAdapter } from '../adapters/index.js';
+import { serializeLockData } from '../utils/serialize.js';
+import { withRetry } from '../utils/retry.js';
+import { buildLockData } from './buildLockData.js';
+import { checkStale } from '../plugins/stale.js';
+import { unlinkSafe } from '../utils/fs.js';
+import { readFileSafe, fileExists } from '../utils/fs.js';
+import { safeDeserializeLockData } from '../utils/serialize.js';
+import { createHandle } from './handle.js';
+import { ConflictError } from '../errors/ConflictError.js';
+import { DEFAULT_STALE_AGE, DEFAULT_ADAPTER, DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+
+export async function acquireLock(filePath: string, options: AcquireOptions = {}): Promise<LockHandle> {
+  const lockPath = resolveLockPath(filePath, options.lockExtension ?? DEFAULT_LOCK_EXTENSION);
+  const adapter = getAdapter(options.adapter ?? DEFAULT_ADAPTER);
+  const staleAge = options.staleAge ?? DEFAULT_STALE_AGE;
+
+  const data = buildLockData(options);
+  const content = serializeLockData(data);
+
+  const tryAcquire = async (): Promise<void> => {
+    const exists = await fileExists(lockPath);
+    if (exists) {
+      if (options.removeStale) {
+        const raw = await readFileSafe(lockPath, filePath, lockPath).catch(() => null);
+        const existing = raw ? safeDeserializeLockData(raw) : null;
+        if (existing) {
+          const staleResult = checkStale(existing, staleAge);
+          if (staleResult.isStale) {
+            options.onStale?.(lockPath);
+            await unlinkSafe(lockPath);
+          } else {
+            throw new ConflictError(filePath, lockPath, existing);
+          }
+        } else {
+          await unlinkSafe(lockPath);
+        }
+      } else {
+        const raw = await readFileSafe(lockPath, filePath, lockPath).catch(() => null);
+        const existing = raw ? safeDeserializeLockData(raw) : null;
+        throw new ConflictError(filePath, lockPath, existing);
+      }
+    }
+    await adapter.acquire(lockPath, content);
+  };
+
+  await withRetry(tryAcquire, options);
+  options.onAcquired?.(lockPath);
+
+  return createHandle(filePath, lockPath, data, options);
+}

package/src/core/buildLockData.ts

@@ -0,0 +1,25 @@
+import type { LockData } from '../types/lock.js';
+import type { AcquireOptions } from '../types/options.js';
+import { getUid, getGid } from '../utils/platform.js';
+import { getHostname } from '../utils/hostname.js';
+import { generateNonce } from '../utils/random.js';
+import { DEFAULT_LOCK_VERSION } from '../constants/defaults.js';
+
+export function buildLockData(options: AcquireOptions): LockData {
+  const now = Date.now();
+  const ttl = options.ttl ?? null;
+  return {
+    pid: process.pid,
+    hostname: getHostname(),
+    uid: getUid(),
+    gid: getGid(),
+    created: now,
+    updated: now,
+    expires: ttl !== null ? now + ttl : null,
+    ttl,
+    nonce: generateNonce(),
+    version: DEFAULT_LOCK_VERSION,
+    strategy: options.strategy ?? 'exclusive',
+    meta: options.meta ?? {},
+  };
+}

package/src/core/check.ts

@@ -0,0 +1,66 @@
+import type { CheckOptions } from '../types/options.js';
+import type { LockFile, LockState } from '../types/lock.js';
+import { resolveLockPath } from '../utils/path.js';
+import { fileExists, getFileMtimeMs } from '../utils/fs.js';
+import { readFileSafe } from '../utils/fs.js';
+import { safeDeserializeLockData } from '../utils/serialize.js';
+import { checkStale } from '../plugins/stale.js';
+import { DEFAULT_LOCK_EXTENSION, DEFAULT_STALE_AGE } from '../constants/defaults.js';
+
+export async function checkLock(filePath: string, options: CheckOptions = {}): Promise<LockFile> {
+  const lockPath = resolveLockPath(filePath, options.staleAge !== undefined ? DEFAULT_LOCK_EXTENSION : DEFAULT_LOCK_EXTENSION);
+  const exists = await fileExists(lockPath);
+
+  if (!exists) {
+    return {
+      path: filePath,
+      lockPath,
+      data: null,
+      exists: false,
+      readable: false,
+      writable: false,
+      stale: false,
+      expired: false,
+      ageMs: 0,
+    };
+  }
+
+  const raw = await readFileSafe(lockPath, filePath, lockPath).catch(() => null);
+  const data = raw ? safeDeserializeLockData(raw) : null;
+  const mtimeMs = await getFileMtimeMs(lockPath);
+  const ageMs = mtimeMs !== null ? Date.now() - mtimeMs : 0;
+
+  let stale = false;
+  let expired = false;
+  if (data) {
+    const staleResult = checkStale(data, options.staleAge ?? DEFAULT_STALE_AGE);
+    stale = staleResult.isStale && staleResult.reason === 'age';
+    expired = staleResult.isStale && staleResult.reason === 'expired';
+  }
+
+  return {
+    path: filePath,
+    lockPath,
+    data,
+    exists: true,
+    readable: raw !== null,
+    writable: true,
+    stale,
+    expired,
+    ageMs,
+  };
+}
+
+export async function isLocked(filePath: string, options: CheckOptions = {}): Promise<boolean> {
+  const result = await checkLock(filePath, options);
+  return result.exists && !result.stale && !result.expired;
+}
+
+export async function getLockState(filePath: string, options: CheckOptions = {}): Promise<LockState> {
+  const result = await checkLock(filePath, options);
+  if (!result.exists) return 'unlocked';
+  if (result.expired) return 'expired';
+  if (result.stale) return 'stale';
+  if (!result.readable) return 'unknown';
+  return 'locked';
+}

package/src/core/cleanup.ts

@@ -0,0 +1,53 @@
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+import { checkStale } from '../plugins/stale.js';
+import { safeDeserializeLockData } from '../utils/serialize.js';
+import { DEFAULT_LOCK_EXTENSION, DEFAULT_STALE_AGE } from '../constants/defaults.js';
+
+export interface CleanupResult {
+  removed: string[];
+  errors: Array<{ path: string; error: Error }>;
+  scanned: number;
+}
+
+export async function cleanupLocks(
+  directory: string,
+  options: { extension?: string; staleAge?: number; dryRun?: boolean } = {},
+): Promise<CleanupResult> {
+  const ext = options.extension ?? DEFAULT_LOCK_EXTENSION;
+  const staleAge = options.staleAge ?? DEFAULT_STALE_AGE;
+  const result: CleanupResult = { removed: [], errors: [], scanned: 0 };
+
+  let entries;
+  try {
+    entries = await fsp.readdir(directory, { withFileTypes: true, encoding: 'utf-8' });
+  } catch (err) {
+    result.errors.push({ path: directory, error: err as Error });
+    return result;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(ext)) continue;
+    const lockPath = join(directory, entry.name);
+    result.scanned++;
+
+    try {
+      const raw = await fsp.readFile(lockPath, 'utf-8');
+      const data = safeDeserializeLockData(raw);
+      if (!data) {
+        if (!options.dryRun) await fsp.unlink(lockPath);
+        result.removed.push(lockPath);
+        continue;
+      }
+      const staleResult = checkStale(data, staleAge);
+      if (staleResult.isStale) {
+        if (!options.dryRun) await fsp.unlink(lockPath);
+        result.removed.push(lockPath);
+      }
+    } catch (err) {
+      result.errors.push({ path: lockPath, error: err as Error });
+    }
+  }
+
+  return result;
+}

package/src/core/handle.ts

@@ -0,0 +1,62 @@
+import type { LockHandle, LockData } from '../types/lock.js';
+import type { AcquireOptions } from '../types/options.js';
+import { releaseLock } from './release.js';
+import { startHeartbeat } from '../plugins/heartbeat.js';
+import type { HeartbeatHandle } from '../plugins/heartbeat.js';
+import { checkStale } from '../plugins/stale.js';
+import { isLockExpiredByTtl } from '../plugins/ttl.js';
+import { DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_STALE_AGE } from '../constants/defaults.js';
+import { promises as fsp } from 'node:fs';
+import { serializeLockData } from '../utils/serialize.js';
+
+export function createHandle(
+  filePath: string,
+  lockPath: string,
+  data: LockData,
+  options: AcquireOptions,
+): LockHandle {
+  let acquired = true;
+  let heartbeat: HeartbeatHandle | null = null;
+  let currentData = { ...data };
+
+  if (options.heartbeatInterval !== undefined || options.ttl !== undefined) {
+    heartbeat = startHeartbeat(
+      lockPath,
+      () => currentData,
+      options.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL,
+    );
+  }
+
+  const handle: LockHandle = {
+    get path() { return filePath; },
+    get lockPath() { return lockPath; },
+    get data() { return { ...currentData }; },
+    get acquired() { return acquired; },
+
+    async release() {
+      if (!acquired) return;
+      heartbeat?.stop();
+      await releaseLock(filePath, lockPath, currentData, {});
+      acquired = false;
+    },
+
+    async refresh() {
+      currentData = { ...currentData, updated: Date.now() };
+      await fsp.writeFile(lockPath, serializeLockData(currentData), 'utf-8');
+    },
+
+    isStale() {
+      return checkStale(currentData, options.staleAge ?? DEFAULT_STALE_AGE).isStale;
+    },
+
+    isExpired() {
+      return isLockExpiredByTtl(currentData);
+    },
+
+    toJSON() {
+      return { ...currentData };
+    },
+  };
+
+  return handle;
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export { acquireLock } from './acquire.js';
+export { releaseLock } from './release.js';
+export { checkLock, isLocked, getLockState } from './check.js';
+export { createHandle } from './handle.js';
+export { listLocks } from './list.js';
+export { cleanupLocks } from './cleanup.js';
+export type { CleanupResult } from './cleanup.js';
+export { buildLockData } from './buildLockData.js';

package/src/core/list.ts

@@ -0,0 +1,38 @@
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+import type { ListOptions } from '../types/options.js';
+import type { LockFile } from '../types/lock.js';
+import { checkLock } from './check.js';
+import { DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+
+export async function listLocks(options: ListOptions = {}): Promise<LockFile[]> {
+  const dir = options.directory ?? process.cwd();
+  const ext = options.lockExtension ?? DEFAULT_LOCK_EXTENSION;
+  const lockFiles: LockFile[] = [];
+
+  const scanDir = async (directory: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await fsp.readdir(directory, { withFileTypes: true, encoding: 'utf-8' });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(directory, entry.name);
+      if (entry.isDirectory() && options.recursive) {
+        await scanDir(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(ext)) {
+        const filePath = fullPath.slice(0, -ext.length);
+        const lockFile = await checkLock(filePath).catch(() => null);
+        if (!lockFile) continue;
+        if (!options.includeStale && lockFile.stale) continue;
+        if (!options.includeExpired && lockFile.expired) continue;
+        lockFiles.push(lockFile);
+      }
+    }
+  };
+
+  await scanDir(dir);
+  return lockFiles;
+}

package/src/core/release.ts

@@ -0,0 +1,35 @@
+import type { ReleaseOptions } from '../types/options.js';
+import type { LockData } from '../types/lock.js';
+import { getAdapter } from '../adapters/index.js';
+import { fileExists, readFileSafe } from '../utils/fs.js';
+import { safeDeserializeLockData } from '../utils/serialize.js';
+import { LockError } from '../errors/LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+import { DEFAULT_ADAPTER, DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+
+export async function releaseLock(
+  filePath: string,
+  lockPath: string,
+  ownData: LockData,
+  options: ReleaseOptions = {},
+): Promise<void> {
+  const adapter = getAdapter(DEFAULT_ADAPTER);
+
+  const exists = await fileExists(lockPath);
+  if (!exists) return;
+
+  if (!options.force) {
+    const raw = await readFileSafe(lockPath, filePath, lockPath).catch(() => null);
+    const current = raw ? safeDeserializeLockData(raw) : null;
+    if (current && current.nonce !== ownData.nonce) {
+      throw new LockError(
+        ERROR_CODES.LOCK_NOT_OWNED,
+        filePath,
+        lockPath,
+        `Cannot release lock owned by nonce ${current.nonce} (ours: ${ownData.nonce})`,
+      );
+    }
+  }
+
+  await adapter.release(lockPath);
+}

package/src/errors/AbortError.ts

@@ -0,0 +1,25 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class AbortError extends LockError {
+  public override name = 'AbortError';
+  public readonly attempt: number;
+
+  constructor(path: string, lockPath: string, attempt: number) {
+    super(
+      ERROR_CODES.LOCK_ABORTED,
+      path,
+      lockPath,
+      `Lock acquisition on "${path}" was aborted after ${attempt} attempt(s)`,
+    );
+    this.attempt = attempt;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      attempt: this.attempt,
+    };
+  }
+}