//#region src/utils/runOnce.d.ts
/**
 * Context handed to the callback so it can interact with the lock it runs under.
 */
export type RunOnceContext = {
  /**
   * Re-create the sentinel file after an operation that may have deleted it —
   * typically cleaning the output directory, which wipes the cache directory the
   * sentinel lives in. Without this, concurrent processes would see no lock and
   * start a competing run while this one is still writing.
   */
  renewLock: () => Promise<void>;
};
type RunOnceOptions = {
  /**
   * The function to execute when the sentinel is not found or is older than the cache timeout.
   */
  onIsCached?: () => void | Promise<void>;
  /**
   * The time window in milliseconds during which the sentinel is considered valid.
   *
   * @default 60000 = 1 minute
   */
  cacheTimeoutMs?: number;
  /**
   * If true, the callback will always run. If undefined, the callback will run only if the sentinel is older than the cache timeout.
   *
   * @default false
   */
  forceRun?: boolean;
  /**
   * How long to wait for another process to release the sentinel before
   * considering its run abandoned and taking the lock over.
   *
   * @default 300000 = 5 minutes
   */
  lockWaitTimeoutMs?: number;
};
/**
 * Ensures a callback function runs only once within a specified time window across multiple processes.
 * Uses a sentinel file to coordinate execution and prevent duplicate work.
 *
 * Processes that lose the race for the sentinel wait for the owner to finish
 * rather than running a competing copy of the callback — concurrent runs would
 * otherwise write to (and clean) the same output directory at the same time.
 *
 * @param sentinelFilePath - Path to the sentinel file used for coordination
 * @param callback - The function to execute (should be async)
 * @param options - The options for the runOnce function
 *
 * @example
 * ```typescript
 * await runOnce(
 *   '/tmp/intlayer-sentinel',
 *   async ({ renewLock }) => {
 *     await cleanOutputDir(configuration); // may delete the sentinel
 *     await renewLock();
 *     await prepareIntlayer();
 *   },
 *   { cacheTimeoutMs: 30 * 1000 } // 30 seconds cache
 * );
 * ```
 *
 * @throws {Error} When there are unexpected filesystem errors
 */
export declare const runOnce: (sentinelFilePath: string, callback: (context: RunOnceContext) => void | Promise<void>, options?: RunOnceOptions) => Promise<void>;
//#endregion
//# sourceMappingURL=runOnce.d.ts.map