sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy-test/ src/ Registry.ts

/**
 * Per-file registration state.
 *
 * While a test file's module body is evaluating, `describe`/`test`/hook
 * calls register nodes against that file's collector. The runner may call
 * `collect` for many files at once, but collections run one at a time: each
 * waits its turn on a process-wide queue, sets the collector in a plain slot,
 * imports the file and flushes the microtasks it queued, then clears the slot.
 * Attribution therefore never depends on the runtime carrying async context
 * through `import()` (Bun 1.4 does not), including registrations deferred with
 * `queueMicrotask` and module bodies that use top-level `await`.
 *
 * The state lives on `globalThis` so that a duplicated module instance
 * (e.g. two resolutions of the package) still shares one registry.
 */
import { makeFileSuite, type FileSuite, type Suite } from "./Model.ts";

interface FileContext {
  /** Suite that `describe`/`test` calls currently attach to. */
  current: Suite;
}

interface RegistryState {
  /** The collector of the file being collected, if any. */
  active: FileContext | undefined;
  /** The tail of the collection queue. */
  tail: Promise<unknown>;
}

const key = Symbol.for("alchemy-test/registry@2");

const state: RegistryState = ((globalThis as any)[key] ??= {
  active: undefined,
  tail: Promise.resolve(),
} satisfies RegistryState);

/**
 * Collect one file: once every earlier collection has finished, run `f` (the
 * file's dynamic import + microtask flush) with `root` (a fresh one by
 * default) as the active collector, and return it.
 */
export const collect = (
  file: string,
  f: () => Promise<void>,
  root: FileSuite = makeFileSuite(file),
): Promise<FileSuite> => {
  const run = state.tail.then(async () => {
    state.active = { current: root };
    try {
      await f();
    } finally {
      state.active = undefined;
    }
    return root;
  });
  state.tail = run.catch(() => undefined);
  return run;
};

const currentContext = (): FileContext => {
  const context = state.active;
  if (context === undefined) {
    throw new Error(
      "alchemy-test: describe/test/hook called outside of a test file collection. " +
        "Run tests with the `alchemy-test` CLI.",
    );
  }
  return context;
};

export const currentSuite = (): Suite => currentContext().current;

export const currentFileSuite = (): FileSuite => {
  let suite = currentSuite();
  while (suite.parent !== undefined) suite = suite.parent;
  return suite as FileSuite;
};

/**
 * The file currently being collected (path relative to the run root, e.g.
 * `test/Cloudflare/R2/Bucket.test.ts`), or `undefined` when called outside
 * of a collection (e.g. from a non-alchemy-test runner). Adapters use this
 * at registration time to namespace per-test durable state by file.
 */
export const currentFile = (): string | undefined => {
  let suite: Suite | undefined = state.active?.current;
  while (suite?.parent !== undefined) suite = suite.parent;
  return suite !== undefined && "file" in suite ? (suite as FileSuite).file : undefined;
};

/** Run `f` with `suite` as the current registration target. */
export const withSuite = (suite: Suite, f: () => void): void => {
  const context = currentContext();
  const previous = context.current;
  context.current = suite;
  try {
    f();
  } finally {
    context.current = previous;
  }
};