@bomb.sh/tools/dist/test-utils/fixture.d.mts

The internal dev, build, and lint CLI for Bombshell projects

import { HfsImpl } from "@humanfs/types";

//#region src/test-utils/fixture.d.ts
interface ScopedHfsImpl extends Required<HfsImpl> {
  text(file: string | URL): Promise<string | undefined>;
  json(file: string | URL): Promise<unknown | undefined>;
}
/**
 * A temporary fixture directory with a scoped `hfs` filesystem.
 *
 * Includes all `hfs` methods — paths are resolved relative to the fixture root.
 */
interface Fixture extends ScopedHfsImpl {
  /** The fixture root as a `file://` URL. */
  root: URL;
  /** Resolve a relative path within the fixture root. */
  resolve: (...segments: string[]) => URL;
  /** Delete the fixture directory. Also runs automatically via `onTestFinished`. */
  cleanup: () => Promise<void>;
}
/** Context passed to dynamic file content functions. */
interface FileContext {
  /**
   * Metadata about the fixture root, analogous to `import.meta`.
   *
   * - `url` — the fixture root as a `file://` URL string
   * - `filename` — absolute filesystem path to the fixture root
   * - `dirname` — same as `filename` (root is a directory)
   * - `resolve(path)` — resolve a relative path against the fixture root
   */
  importMeta: {
    url: string;
    filename: string;
    dirname: string;
    resolve: (path: string) => string;
  };
  /**
   * Create a symbolic link to `target`.
   *
   * Returns a `SymlinkMarker` — the fixture will create the symlink on disk.
   *
   * @example
   * ```ts
   * { 'link.txt': ({ symlink }) => symlink('./target.txt') }
   * ```
   */
  symlink: (target: string) => SymlinkMarker;
}
declare const SYMLINK: unique symbol;
/** Opaque marker returned by `ctx.symlink()`. */
interface SymlinkMarker {
  [SYMLINK]: true;
  target: string;
}
/**
 * A value in the file tree.
 *
 * | Type | Example |
 * |------|---------|
 * | `string` | `'file content'` |
 * | `object` / `array` | `{ name: 'cool' }` — auto-serialized as JSON for `.json` keys |
 * | `Buffer` | `Buffer.from([0x89, 0x50])` |
 * | Nested directory | `{ dir: { 'file.txt': 'content' } }` |
 * | Function | `({ importMeta, symlink }) => symlink('./target')` |
 */
type FileTreeValue = string | Buffer | Record<string, unknown> | unknown[] | FileTree | ((ctx: FileContext) => string | Buffer | SymlinkMarker);
/** A recursive tree of files and directories. */
interface FileTree {
  [key: string]: FileTreeValue;
}
/**
 * Create a temporary fixture directory from an inline file tree.
 *
 * Returns a {@link Fixture} with all `hfs` methods scoped to the fixture root.
 *
 * @example
 * ```ts
 * const fixture = await createFixture({
 *   'hello.txt': 'hello world',
 *   'package.json': { name: 'test', version: '1.0.0' },
 *   'icon.png': Buffer.from([0x89, 0x50]),
 *   src: {
 *     'index.ts': 'export default 1',
 *   },
 *   'link.txt': ({ symlink }) => symlink('./hello.txt'),
 *   'info.txt': ({ importMeta }) => `Root: ${importMeta.url}`,
 * })
 *
 * const text = await fixture.text('hello.txt')
 * const json = await fixture.json('package.json')
 * ```
 */
declare function createFixture(files: FileTree): Promise<Fixture>;
//#endregion
export { FileContext, FileTree, FileTreeValue, Fixture, SymlinkMarker, createFixture };
//# sourceMappingURL=fixture.d.mts.map