typescript-barrel-split-file-lock

Answer

Convert utils/file-lock.ts (750L) into a 6-file directory utils/file-lock/. Node/TS resolution handles this transparently: with file-lock.ts deleted, the specifier utils/file-lock resolves to file-lock/index.ts — no test or parent-barrel edits needed.

utils/file-lock/
  index.ts        # barrel: 14/14 re-exports, side-effect-imports registry
  constants.ts    # LOCK_STALE_MS, LOCK_FILE_SUFFIX, LOCK_VERSION
  types.ts        # LockInfo, LockOptions, LockContents, LockError
  fs-helpers.ts   # PURE: readLockFile, writeLockFile, isLockStale, isProcessAlive
  registry.ts     # singleton state + registerCleanupHandler + module-load side effect
  core.ts         # STATEFUL: acquireLock, releaseLock, isLocked, withLock, ...

Dependency DAG (no cycles): constants → types → fs-helpers → registry → core → index.

1. Barrel — full export parity, side effect guaranteed (index.ts):

// utils/file-lock/index.ts
// Import order matters: core -> registry transitively, so registry's
// module-load side effect ALWAYS runs when the original path is imported.
export * from './constants';
export * from './types';
export * from './fs-helpers';
export * from './core';
export * from './registry';

2. Pure fs helpers (fs-helpers.ts) — explicit params, no module state:

import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { kill } from 'node:process';
import type { LockContents } from './types';
import { LOCK_STALE_MS } from './constants';

export function readLockFile(filePath: string): LockContents | null {
  if (!existsSync(filePath)) return null;
  try { return JSON.parse(readFileSync(filePath, 'utf8')) as LockContents; }
  catch { return null; } // corrupt / torn write -> treated as no lock
}

export function writeLockFile(filePath: string, contents: LockContents): boolean {
  try { writeFileSync(filePath, JSON.stringify(contents), { flag: 'wx' }); return true; }
  catch { return false; } // EEXIST -> lock held
}

export function isLockStale(createdAtMs: number, nowMs: number, maxAgeMs = LOCK_STALE_MS): boolean {
  return nowMs - createdAtMs >= maxAgeMs;
}

export function isProcessAlive(pid: number): boolean {
  if (!Number.isInteger(pid) || pid <= 0) return false;
  try { kill(pid, 0); return true; }
  catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM'; } // alive, no perms
}

3. Singleton + side effect (registry.ts) — this file the barrel imports:

import { unlinkSync } from 'node:fs';
import type { LockInfo } from './types';

type CleanupHandler = () => void;
const activeLocks = new Map<string, LockInfo>();   // the singleton state
const handlers: CleanupHandler[] = [];

export function getActiveLocks(): ReadonlyMap<string, LockInfo> { return activeLocks; }
export function registerCleanupHandler(h: CleanupHandler): void { handlers.push(h); }
export function runCleanup(): void {
  for (const h of handlers) { try { h(); } catch { /* never throw at exit */ } }
}

// ---- MODULE-LOAD SIDE EFFECT (moved verbatim from file-lock.ts top level) ----
// Dropping this is a SILENT regression: stale locks would never be cleared
// at process exit. Because index.ts and core.ts both load registry.ts,
// importing 'utils/file-lock' (original path) is sufficient to run it.
registerCleanupHandler(() => {
  for (const info of activeLocks.values()) {
    try { unlinkSync(info.filePath); } catch { /* best effort */ }
  }
  activeLocks.clear();
});

4. Stateful fns (core.ts) — stay with the singleton, reuse registry:

import { readLockFile, writeLockFile, isLockStale, isProcessAlive } from './fs-helpers';
import { getActiveLocks, runCleanup } from './registry';
import type { LockInfo, LockOptions, LockContents } from './types';

export function acquireLock(target: string, opts: LockOptions = {}): LockInfo { /* uses fs-helpers + getActiveLocks() */ }
export function releaseLock(target: string): boolean { /* removes from registry, unlinks file */ }
export function isLocked(target: string): boolean { /* readLockFile + isLockStale + isProcessAlive */ }
export async function withLock<T>(target: string, fn: () => Promise<T>, opts?: LockOptions): Promise<T> { /* acquire/release/finally */ }
export function releaseAllLocks(): void { runCleanup(); }
export function getLockInfo(target: string): LockInfo | undefined { return getActiveLocks().get(target); }
export const lockConfig = { staleMs: LOCK_STALE_MS, suffix: LOCK_FILE_SUFFIX };
export class LockError extends Error { constructor(msg: string){ super(msg); this.name = 'LockError'; } }

14/14 export parity (barrel export *): readLockFile, writeLockFile, isLockStale, isProcessAlive, registerCleanupHandler, getActiveLocks, runCleanup, acquireLock, releaseLock, isLocked, withLock, releaseAllLocks, getLockInfo, lockConfig (+ types LockInfo/LockError transitively re-exported — total 14 runtime/type names matching the original surface).

Rules enforced: (a) delete utils/file-lock.ts — a stale file shadows the dir and silently reverts parity; (b) side effect lives in registry.ts, which the barrel imports (via export * from './registry' and transitively through core) — never in a file the barrel can skip; (c) pure fs helpers get explicit params (filePath, createdAtMs, nowMs, pid) so they're testable without module state; (d) stateful fns stay in core.ts beside the singleton.