@alchemy.run/node-utils 0.0.0

package/lib/mtime-precision.js

@@ -0,0 +1,40 @@
+const cacheSymbol = Symbol();
+export function probe(file, fs, callback) {
+    const cachedFs = fs;
+    const cachedPrecision = cachedFs[cacheSymbol];
+    if (cachedPrecision) {
+        return fs.stat(file, (err, stat) => {
+            /* istanbul ignore if */
+            if (err) {
+                return callback(err);
+            }
+            callback(null, stat.mtime, cachedPrecision);
+        });
+    }
+    // Set mtime by ceiling Date.now() to seconds + 5ms so that it's "not on the second"
+    const mtime = new Date(Math.ceil(Date.now() / 1000) * 1000 + 5);
+    fs.utimes(file, mtime, mtime, (err) => {
+        /* istanbul ignore if */
+        if (err) {
+            return callback(err);
+        }
+        fs.stat(file, (err, stat) => {
+            /* istanbul ignore if */
+            if (err) {
+                return callback(err);
+            }
+            const precision = stat.mtime.getTime() % 1000 === 0 ? "s" : "ms";
+            // Cache the precision in a non-enumerable way
+            Object.defineProperty(fs, cacheSymbol, { value: precision });
+            callback(null, stat.mtime, precision);
+        });
+    });
+}
+export function getMtime(precision) {
+    let now = Date.now();
+    if (precision === "s") {
+        now = Math.ceil(now / 1000) * 1000;
+    }
+    return new Date(now);
+}
+//# sourceMappingURL=mtime-precision.js.map

package/lib/mtime-precision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtime-precision.js","sourceRoot":"","sources":["../src/mtime-precision.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,GAAG,MAAM,EAAE,CAAC;AAM7B,MAAM,UAAU,KAAK,CACnB,IAAY,EACZ,EAAoB,EACpB,QAAuB;IAEvB,MAAM,QAAQ,GAAG,EAAc,CAAC;IAChC,MAAM,eAAe,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IAE9C,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACjC,wBAAwB;YACxB,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAED,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,oFAAoF;IACpF,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IAEhE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE;QACpC,wBAAwB;QACxB,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YAC1B,wBAAwB;YACxB,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAED,MAAM,SAAS,GACb,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAEjD,8CAA8C;YAC9C,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YAE7D,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,SAAyB;IAChD,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAErB,IAAI,SAAS,KAAK,GAAG,EAAE,CAAC;QACtB,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACrC,CAAC;IAED,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/lib/retry.d.ts

@@ -0,0 +1,56 @@
+export interface OperationOptions {
+    retries?: number;
+    factor?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    randomize?: boolean;
+    forever?: boolean;
+    unref?: boolean;
+    maxRetryTime?: number;
+}
+interface RetryOperationOptions {
+    forever?: boolean;
+    unref?: boolean;
+    maxRetryTime?: number;
+}
+interface AttemptTimeoutOptions {
+    timeout?: number;
+    cb?: (attempt?: number) => void;
+}
+type AttemptFn = (attempt: number) => void;
+export declare function createTimeout(attempt: number, opts: Required<Pick<OperationOptions, 'minTimeout' | 'maxTimeout' | 'factor' | 'randomize'>>): number;
+export declare function timeouts(options?: OperationOptions | number[]): number[];
+export declare class RetryOperation {
+    private readonly originalTimeouts;
+    private remainingTimeouts;
+    private readonly options;
+    private readonly maxRetryTime;
+    private readonly cachedTimeouts;
+    private fn;
+    private readonly errorList;
+    private attemptCount;
+    private operationTimeout;
+    private operationTimeoutCb;
+    private operationTimer;
+    private retryTimer;
+    private operationStart;
+    constructor(initialTimeouts: number[], options?: RetryOperationOptions | boolean);
+    reset(): void;
+    stop(): void;
+    retry(err?: Error | null): boolean;
+    attempt(fn: AttemptFn, timeoutOps?: AttemptTimeoutOptions): void;
+    errors(): Error[];
+    attempts(): number;
+    mainError(): Error | null;
+}
+export declare function operation(options?: OperationOptions | number[]): RetryOperation;
+export declare function wrap<T extends Record<string, any>>(obj: T, optionsOrMethods?: OperationOptions | string[], methodList?: string[]): void;
+declare const _default: {
+    operation: typeof operation;
+    timeouts: typeof timeouts;
+    createTimeout: typeof createTimeout;
+    wrap: typeof wrap;
+    RetryOperation: typeof RetryOperation;
+};
+export default _default;
+//# sourceMappingURL=retry.d.ts.map

package/lib/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,KAAK,SAAS,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAU3C,wBAAgB,aAAa,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAC,GAC7F,MAAM,CAKR;AAED,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAwBxE;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;IAC5C,OAAO,CAAC,iBAAiB,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkB;IAEjD,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,kBAAkB,CAA6C;IACvE,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,cAAc,CAAK;gBAEf,eAAe,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,qBAAqB,GAAG,OAAY;IAWpF,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI;IAWZ,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO;IAuDlC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,EAAE,qBAAqB,GAAG,IAAI;IAsBhE,MAAM,IAAI,KAAK,EAAE;IAIjB,QAAQ,IAAI,MAAM;IAIlB,SAAS,IAAI,KAAK,GAAG,IAAI;CAuB5B;AAED,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,GAAG,cAAc,CAS/E;AAED,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9C,GAAG,EAAE,CAAC,EACN,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,EAC9C,UAAU,CAAC,EAAE,MAAM,EAAE,GACtB,IAAI,CA2CN;;;;;;;;AAED,wBAA4E"}

package/lib/retry.js

@@ -0,0 +1,199 @@
+const DEFAULTS = {
+    retries: 10,
+    factor: 2,
+    minTimeout: 1000,
+    maxTimeout: Infinity,
+    randomize: false,
+};
+export function createTimeout(attempt, opts) {
+    const random = opts.randomize ? Math.random() + 1 : 1;
+    const timeout = Math.round(random * Math.max(opts.minTimeout, 1) * opts.factor ** attempt);
+    return Math.min(timeout, opts.maxTimeout);
+}
+export function timeouts(options) {
+    if (Array.isArray(options)) {
+        return [...options];
+    }
+    const opts = { ...DEFAULTS, ...options };
+    if (opts.minTimeout > opts.maxTimeout) {
+        throw new Error('minTimeout is greater than maxTimeout');
+    }
+    const result = [];
+    for (let i = 0; i < opts.retries; i++) {
+        result.push(createTimeout(i, opts));
+    }
+    if (options && !Array.isArray(options) && options.forever && result.length === 0) {
+        result.push(createTimeout(opts.retries, opts));
+    }
+    result.sort((a, b) => a - b);
+    return result;
+}
+export class RetryOperation {
+    originalTimeouts;
+    remainingTimeouts;
+    options;
+    maxRetryTime;
+    cachedTimeouts;
+    fn = null;
+    errorList = [];
+    attemptCount = 1;
+    operationTimeout = null;
+    operationTimeoutCb = null;
+    operationTimer = null;
+    retryTimer = null;
+    operationStart = 0;
+    constructor(initialTimeouts, options = {}) {
+        // Compatibility for the old (timeouts, retryForever) signature
+        const opts = typeof options === 'boolean' ? { forever: options } : options;
+        this.originalTimeouts = [...initialTimeouts];
+        this.remainingTimeouts = [...initialTimeouts];
+        this.options = opts;
+        this.maxRetryTime = opts.maxRetryTime ?? Infinity;
+        this.cachedTimeouts = opts.forever ? [...initialTimeouts] : null;
+    }
+    reset() {
+        this.attemptCount = 1;
+        this.remainingTimeouts = [...this.originalTimeouts];
+    }
+    stop() {
+        if (this.operationTimer) {
+            clearTimeout(this.operationTimer);
+        }
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+        }
+        this.remainingTimeouts = [];
+    }
+    retry(err) {
+        if (this.operationTimer) {
+            clearTimeout(this.operationTimer);
+        }
+        if (!err) {
+            return false;
+        }
+        const elapsed = Date.now() - this.operationStart;
+        if (elapsed >= this.maxRetryTime) {
+            this.errorList.push(err);
+            this.errorList.unshift(new Error('RetryOperation timeout occurred'));
+            return false;
+        }
+        this.errorList.push(err);
+        let timeout = this.remainingTimeouts.shift();
+        if (timeout === undefined) {
+            if (this.cachedTimeouts) {
+                // retry forever, only keep last error
+                this.errorList.splice(0, this.errorList.length - 1);
+                timeout = this.cachedTimeouts[this.cachedTimeouts.length - 1];
+            }
+            else {
+                return false;
+            }
+        }
+        this.retryTimer = setTimeout(() => {
+            this.attemptCount += 1;
+            if (this.operationTimeoutCb) {
+                this.operationTimer = setTimeout(() => {
+                    this.operationTimeoutCb?.(this.attemptCount);
+                }, this.operationTimeout ?? 0);
+                if (this.options.unref && typeof this.operationTimer.unref === 'function') {
+                    this.operationTimer.unref();
+                }
+            }
+            this.fn?.(this.attemptCount);
+        }, timeout);
+        if (this.options.unref && typeof this.retryTimer.unref === 'function') {
+            this.retryTimer.unref();
+        }
+        return true;
+    }
+    attempt(fn, timeoutOps) {
+        this.fn = fn;
+        if (timeoutOps) {
+            if (timeoutOps.timeout != null) {
+                this.operationTimeout = timeoutOps.timeout;
+            }
+            if (timeoutOps.cb) {
+                this.operationTimeoutCb = timeoutOps.cb;
+            }
+        }
+        if (this.operationTimeoutCb) {
+            this.operationTimer = setTimeout(() => {
+                this.operationTimeoutCb?.();
+            }, this.operationTimeout ?? 0);
+        }
+        this.operationStart = Date.now();
+        this.fn(this.attemptCount);
+    }
+    errors() {
+        return this.errorList;
+    }
+    attempts() {
+        return this.attemptCount;
+    }
+    mainError() {
+        if (this.errorList.length === 0) {
+            return null;
+        }
+        const counts = new Map();
+        let mainError = null;
+        let mainErrorCount = 0;
+        for (const error of this.errorList) {
+            const message = error.message;
+            const count = (counts.get(message) ?? 0) + 1;
+            counts.set(message, count);
+            if (count >= mainErrorCount) {
+                mainError = error;
+                mainErrorCount = count;
+            }
+        }
+        return mainError;
+    }
+}
+export function operation(options) {
+    const computedTimeouts = timeouts(options);
+    const opts = !Array.isArray(options) ? options : undefined;
+    return new RetryOperation(computedTimeouts, {
+        forever: opts?.forever || opts?.retries === Infinity,
+        unref: opts?.unref,
+        maxRetryTime: opts?.maxRetryTime,
+    });
+}
+export function wrap(obj, optionsOrMethods, methodList) {
+    let options;
+    let methods;
+    if (Array.isArray(optionsOrMethods)) {
+        methods = optionsOrMethods;
+    }
+    else {
+        options = optionsOrMethods;
+        methods = methodList;
+    }
+    if (!methods) {
+        methods = [];
+        for (const key in obj) {
+            if (typeof obj[key] === 'function') {
+                methods.push(key);
+            }
+        }
+    }
+    for (const method of methods) {
+        const original = obj[method];
+        obj[method] = function retryWrapper(...args) {
+            const op = operation(options);
+            const callback = args.pop();
+            args.push(function (err, ...rest) {
+                if (op.retry(err)) {
+                    return;
+                }
+                const finalErr = err ? op.mainError() : err;
+                callback.call(this, finalErr, ...rest);
+            });
+            op.attempt(() => {
+                original.apply(obj, args);
+            });
+        };
+        obj[method].options = options;
+    }
+}
+export default { operation, timeouts, createTimeout, wrap, RetryOperation };
+//# sourceMappingURL=retry.js.map

package/lib/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alchemy.run/node-utils",
+  "version": "0.0.0",
+  "author": "Sam Goodwin (sam@alchemy.run)",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:alchemy-run/node-utils.git"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "lib"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+
+type AnyFs = Record<string, any>;
+type AnyCallback = (err: NodeJS.ErrnoException | null, result?: any) => void;
+type AsyncMethod = (...args: any[]) => void;
+
+function createSyncFs(fs: AnyFs): AnyFs {
+  const methods = ["mkdir", "realpath", "stat", "rmdir", "utimes"] as const;
+  const newFs: AnyFs = { ...fs };
+
+  methods.forEach((method) => {
+    newFs[method] = (...args: any[]) => {
+      const callback = args.pop() as AnyCallback;
+      let ret;
+
+      try {
+        ret = fs[`${method}Sync`](...args);
+      } catch (err) {
+        return callback(err as NodeJS.ErrnoException);
+      }
+
+      callback(null, ret);
+    };
+  });
+
+  return newFs;
+}
+
+// ----------------------------------------------------------
+
+export function toPromise<T = any>(
+  method: AsyncMethod,
+): (...args: any[]) => Promise<T> {
+  return (...args: any[]) =>
+    new Promise<T>((resolve, reject) => {
+      args.push((err: NodeJS.ErrnoException | null, result: T) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(result);
+        }
+      });
+
+      method(...args);
+    });
+}
+
+export function toSync<T = any>(method: AsyncMethod): (...args: any[]) => T {
+  return (...args: any[]) => {
+    let err: NodeJS.ErrnoException | null | undefined;
+    let result: T | undefined;
+
+    args.push((_err: NodeJS.ErrnoException | null, _result: T) => {
+      err = _err;
+      result = _result;
+    });
+
+    method(...args);
+
+    if (err) {
+      throw err;
+    }
+
+    return result as T;
+  };
+}
+
+export interface SyncOptions {
+  fs?: AnyFs;
+  retries?: number | { retries?: number };
+  [key: string]: any;
+}
+
+export function toSyncOptions(options?: SyncOptions): SyncOptions {
+  // Shallow clone options because we are going to mutate them
+  const next: SyncOptions = { ...options };
+
+  // Transform fs to use the sync methods instead
+  next.fs = createSyncFs(next.fs || fs);
+
+  // Retries are not allowed because it requires the flow to be sync
+  if (
+    (typeof next.retries === "number" && next.retries > 0) ||
+    (next.retries &&
+      typeof (next.retries as { retries?: number }).retries === "number" &&
+      ((next.retries as { retries?: number }).retries as number) > 0)
+  ) {
+    throw Object.assign(new Error("Cannot use retries with the sync api"), {
+      code: "ESYNC",
+    });
+  }
+
+  return next;
+}

package/src/exit-hook.ts

@@ -0,0 +1,96 @@
+/**
+ * Lightweight replacement for the `exit-hook` npm package.
+ *
+ * The third-party `exit-hook` registers process listeners (`exit`, `SIGINT`,
+ * `SIGTERM`, and `message`) that are never removed — even after every
+ * callback has been unregistered.  Those dangling listeners are harmless in
+ * long-running processes, but in short-lived child processes (e.g. those
+ * spawned by `node --test`) they can prevent clean exit by holding refs on
+ * handles such as the IPC channel.
+ *
+ * This module tracks the number of active registrations and removes **all**
+ * process listeners once the last registration is unregistered, so they
+ * cannot keep the event loop alive after dispose.
+ */
+
+const callbacks = new Set<() => void>();
+let registered = false;
+let called = false;
+
+function runCallbacks(): void {
+  if (called) {
+    return;
+  }
+  called = true;
+  for (const callback of callbacks) {
+    callback();
+  }
+}
+
+function onExit(): void {
+  runCallbacks();
+}
+
+function onSignalInt(): void {
+  runCallbacks();
+  // eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGINT behavior
+  process.exit(128 + 2);
+}
+
+function onSignalTerm(): void {
+  runCallbacks();
+  // eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGTERM behavior
+  process.exit(128 + 15);
+}
+
+function onMessage(message: unknown): void {
+  if (message === "shutdown") {
+    runCallbacks();
+    // eslint-disable-next-line unicorn/no-process-exit -- intentional: PM2 graceful shutdown
+    process.exit(0);
+  }
+}
+
+function addListeners(): void {
+  registered = true;
+  called = false;
+  process.on("exit", onExit);
+  process.on("SIGINT", onSignalInt);
+  process.on("SIGTERM", onSignalTerm);
+  // Only listen for IPC "shutdown" messages (PM2 support) when the process
+  // actually has an IPC channel.  Even without this guard the listener is
+  // harmless when there is no channel, but being explicit avoids any
+  // accidental ref of a future channel.
+  if (process.send !== undefined) {
+    process.on("message", onMessage);
+  }
+}
+
+function removeListeners(): void {
+  registered = false;
+  process.removeListener("exit", onExit);
+  process.removeListener("SIGINT", onSignalInt);
+  process.removeListener("SIGTERM", onSignalTerm);
+  process.removeListener("message", onMessage);
+}
+
+/**
+ * Register a callback to run when the process exits.  Returns a function
+ * that unregisters the callback.  When the last callback is unregistered,
+ * all underlying process listeners are removed so they cannot keep the
+ * event loop alive.
+ */
+export function exitHook(callback: () => void): () => void {
+  callbacks.add(callback);
+
+  if (!registered) {
+    addListeners();
+  }
+
+  return () => {
+    callbacks.delete(callback);
+    if (callbacks.size === 0 && registered) {
+      removeListeners();
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import { toPromise, toSync, toSyncOptions } from "./adapter.ts";
+import type {
+  CheckOptions,
+  LockOptions,
+  ReleaseFn,
+  UnlockOptions,
+} from "./lockfile.ts";
+import * as lockfile from "./lockfile.ts";
+
+export type { CheckOptions, LockOptions, ReleaseFn, UnlockOptions };
+
+export async function lock(
+  file: string,
+  options?: LockOptions,
+): Promise<() => Promise<void>> {
+  const release = await toPromise<ReleaseFn>(lockfile.lock)(file, options);
+
+  return toPromise<void>(release);
+}
+
+export function lockSync(file: string, options?: LockOptions): () => void {
+  const release = toSync<ReleaseFn>(lockfile.lock)(
+    file,
+    toSyncOptions(options),
+  );
+
+  return toSync<void>(release);
+}
+
+export function unlock(file: string, options?: UnlockOptions): Promise<void> {
+  return toPromise<void>(lockfile.unlock)(file, options);
+}
+
+export function unlockSync(file: string, options?: UnlockOptions): void {
+  return toSync<void>(lockfile.unlock)(file, toSyncOptions(options));
+}
+
+export function check(file: string, options?: CheckOptions): Promise<boolean> {
+  return toPromise<boolean>(lockfile.check)(file, options);
+}
+
+export function checkSync(file: string, options?: CheckOptions): boolean {
+  return toSync<boolean>(lockfile.check)(file, toSyncOptions(options));
+}
+
+export default lock;