fs-fixture 2.8.1 → 2.10.0

package/README.md

@@ -7,23 +7,51 @@
 	<a href="https://npm.im/fs-fixture"><img src="https://badgen.net/npm/v/fs-fixture"></a> <a href="https://npm.im/fs-fixture"><img src="https://badgen.net/npm/dm/fs-fixture"></a>
 </h1>
 
-Simple API to create disposable test fixtures on disk.
+Simple API to create disposable test fixtures on disk. Tiny (`1.1 kB` gzipped) with zero dependencies!
 
-Tiny (`560 B` gzipped) and no dependencies!
+### Features
+- 📁 Create files & directories from simple objects
+- 🧹 Automatic cleanup with `using` keyword
+- 📝 Built-in JSON read/write support
+- 🔗 Symlink support
+- 💾 Binary file support with Buffers
+- 🎯 TypeScript-first with full type safety
+- 🔄 File methods inherit types directly from Node.js `fs` module
+
+## Installation
+
+```sh
+npm install fs-fixture
+```
+
+## Quick start
 
-### Example
 ```ts
-import fs from 'node:fs/promises'
 import { createFixture } from 'fs-fixture'
 
+// Create a temporary fixture
 const fixture = await createFixture({
-    'dir-a': {
-        'file-b': 'hello world'
-    }
+    'package.json': JSON.stringify({ name: 'my-app' }),
+    'src/index.js': 'console.log("Hello world")'
+})
+
+// Read files
+const content = await fixture.readFile('src/index.js', 'utf8')
+
+// Cleanup when done
+await fixture.rm()
+```
+
+### Auto cleanup with `using` keyword
+
+Uses TypeScript 5.2+ [Explicit Resource Management](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html) for automatic cleanup:
+
+```ts
+await using fixture = await createFixture({
+    'config.json': '{ "setting": true }'
 })
 
-const content = await fs.readFile(fixture.getPath('dir-a/file-b'))
-console.log(content)
+// Fixture is automatically cleaned up when exiting scope
 ```
 
 <p align="center">
@@ -34,163 +62,166 @@ console.log(content)
 
 ## Usage
 
-Pass in an object representing the file structure:
+### Creating fixtures
 
+**From an object:**
 ```ts
-import { createFixture } from 'fs-fixture'
-
 const fixture = await createFixture({
-    // Nested directory syntax
-    'dir-a': {
-        'file-a.txt': 'hello world',
-        'dir-b': {
-            'file-b.txt': ({ fixturePath }) => `Fixture path: ${fixturePath}`,
-            'symlink-c': ({ symlink }) => symlink('../file-a.txt')
-        }
-    },
-
-    // Alternatively, use the directory path syntax - Same as above
-    'dir-a/dir-b/file-b.txt': 'goodbye world'
+    'package.json': '{ "name": "test" }',
+    'src/index.js': 'export default () => {}',
+    'src/utils': {
+        'helper.js': 'export const help = () => {}'
+    }
 })
+```
 
-// Interact with the fixture
-console.log(fixture.path)
+**From a template directory:**
+```ts
+// Copies an existing directory structure
+const fixture = await createFixture('./test-templates/basic')
+```
 
-// Cleanup fixture
-await fixture.rm()
+**Empty fixture:**
+```ts
+// Create an empty temporary directory
+const fixture = await createFixture()
 ```
 
-### Template path input
+### Working with files
 
-Pass in a path to a test fixture template directory to make a copy of it.
+File methods (`readFile`, `writeFile`, `readdir`) inherit their type signatures directly from Node.js `fs/promises`, preserving all overloads and type narrowing behavior.
 
+**Read files:**
 ```ts
-// Pass in a path to a fixture template path, and it will make a copy of it
-const fixture = await createFixture('./fixtures/template-a')
-
-/* Your test code here... */
+// Read as string (type: Promise<string>)
+const text = await fixture.readFile('config.txt', 'utf8')
 
-// Cleanup fixture
-await fixture.rm()
+// Read as buffer (type: Promise<Buffer>)
+const binary = await fixture.readFile('image.png')
 ```
 
-### `using` keyword (Explicit Resource Management)
-
-[TypeScript 5.2](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html) supports the [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) feature, which allows you to instantiate the fixture via `using`. When the fixture is declared this way, it gets automatically cleaned up when exiting the scope.
+**Write files:**
+```ts
+await fixture.writeFile('output.txt', 'Hello world')
+await fixture.writeFile('data.bin', Buffer.from([0x89, 0x50]))
+```
 
+**JSON operations:**
 ```ts
-await using fixture = await createFixture({ file: 'hello' })
+// Write JSON with formatting
+await fixture.writeJson('config.json', { port: 3000 })
 
-// No need to run fixture.rm()
+// Read and parse JSON with type safety
+type Config = { port: number }
+const config = await fixture.readJson<Config>('config.json')
 ```
 
-## API
-
-### createFixture(source, options)
+### Working with directories
 
-An async function that creates a fixture from the `source` you pass in, and returns a `FsFixture` instance.
+```ts
+// Create directories
+await fixture.mkdir('nested/folders')
 
-#### source
-Type: `string | FileTree`
+// List directory contents
+const files = await fixture.readdir('src')
 
-Path to a template fixture path, or a `FileTree` object that represents the fixture content.
+// Copy files into fixture
+await fixture.cp('/path/to/file.txt', 'copied-file.txt')
 
+// Check if path exists
+if (await fixture.exists('optional-file.txt')) {
+    // ...
+}
+```
 
-#### options
+### Advanced features
 
-##### tempDir
+**Dynamic content with functions:**
+```ts
+const fixture = await createFixture({
+    'target.txt': 'original file',
+    'info.txt': ({ fixturePath }) => `Created at: ${fixturePath}`,
+    'link.txt': ({ symlink }) => symlink('./target.txt')
+})
+```
 
-Type: `string`
+**Binary files:**
+```ts
+const fixture = await createFixture({
+    'image.png': Buffer.from(imageData),
+    'generated.bin': () => Buffer.from('dynamic binary content')
+})
+```
 
-Default: `os.tmpdir()`
+**Path syntax:**
+```ts
+const fixture = await createFixture({
+    // Nested object syntax
+    src: {
+        utils: {
+            'helper.js': 'export const help = () => {}'
+        }
+    },
 
-The directory where the fixture will be created.
+    // Or path syntax (creates same structure)
+    'src/utils/helper.js': 'export const help = () => {}'
+})
+```
 
+## API
 
-##### templateFilter
+### `createFixture(source?, options?)`
 
-Type: `(source: string, destination: string) => boolean | Promise<boolean>`
+Creates a temporary fixture directory and returns a `FsFixture` instance.
 
-Function to filter files to copy when using a template path. Return `true` to copy the item, `false` to ignore it.
+**Parameters:**
+- `source` (optional): String path to template directory, or `FileTree` object defining the structure
+- `options.tempDir` (optional): Custom temp directory. Defaults to `os.tmpdir()`
+- `options.templateFilter` (optional): Filter function when copying from template directory
 
-### Types
-#### FileTree
+**Returns:** `Promise<FsFixture>`
 
 ```ts
-type FileTree = {
-    [path: string]: string | FileTree | ((api: Api) => string)
-}
+const fixture = await createFixture()
+const fixture = await createFixture({ 'file.txt': 'content' })
+const fixture = await createFixture('./template-dir')
+const fixture = await createFixture({}, { tempDir: './custom-temp' })
+```
 
-type Api = {
-    // Fixture root path
-    fixturePath: string
+### `FsFixture` Methods
+
+| Method | Description |
+|--------|-------------|
+| `fixture.path` | Absolute path to the fixture directory |
+| `getPath(...paths)` | Get absolute path to file/directory in fixture |
+| `exists(path?)` | Check if file/directory exists |
+| `rm(path?)` | Delete file/directory (or entire fixture if no path) |
+| `readFile(path, encoding?)` | Read file as string or Buffer |
+| `writeFile(path, content)` | Write string or Buffer to file |
+| `readJson<T>(path)` | Read and parse JSON file |
+| `writeJson(path, data, space?)` | Write JSON with optional formatting |
+| `readdir(path, options?)` | List directory contents |
+| `mkdir(path)` | Create directory (recursive) |
+| `cp(source, dest?)` | Copy file/directory into fixture |
 
-    // Current file path
-    filePath: string
+### Types
 
-    // Get path from the root of the fixture
-    getPath: (...subpaths: string[]) => string
+<details>
+<summary><strong>FileTree</strong></summary>
 
-    // Create a symlink
-    symlink: (target: string) => Symlink
+```ts
+type FileTree = {
+    [path: string]: string | Buffer | FileTree | ((api: Api) => string | Buffer | Symlink)
 }
-```
 
-#### FsFixture
-
-```ts
-class FsFixture {
-    /**
-    Path to the fixture directory.
-    */
-    readonly path: string
-
-    /**
-    Create a Fixture instance from a path. Does not create the fixture directory.
-    */
-    constructor(fixturePath: string)
-
-    /**
-    Get the full path to a subpath in the fixture directory.
-    */
-    getPath(...subpaths: string[]): string
-
-    /**
-    Check if the fixture exists. Pass in a subpath to check if it exists.
-    */
-    exists(subpath?: string): Promise<boolean>
-
-    /**
-    Delete the fixture directory. Pass in a subpath to delete it.
-    */
-    rm(subpath?: string): Promise<void>
-
-    /**
-    Copy a path into the fixture directory.
-    */
-    cp(sourcePath: string, destinationSubpath?: string): Promise<void>
-
-    /**
-    Create a new folder in the fixture directory.
-    */
-    mkdir(folderPath: string): Promise<void>
-
-    /**
-    Create a file in the fixture directory.
-    */
-    writeFile(filePath: string, content: string): Promise<void>
-
-    /**
-    Create a JSON file in the fixture directory.
-    */
-    writeJson(filePath: string, json: unknown): Promise<void>
-
-    /**
-    Read a file from the fixture directory.
-    */
-    readFile(filePath: string, encoding?: BufferEncoding): Promise<string | Buffer>
+type Api = {
+    fixturePath: string // Fixture root path
+    filePath: string // Current file path
+    getPath: (...paths: string[]) => string // Get path from fixture root
+    symlink: (target: string) => Symlink // Create a symlink
 }
 ```
+</details>
 
 ## Related
 

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var d=Object.defineProperty;var n=(s,t)=>d(s,"name",{value:t,configurable:!0});var a=require("node:fs/promises"),c=require("node:path"),v=require("node:fs"),F=require("node:os");typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class b{static{n(this,"FsFixture")}path;constructor(t){this.path=t}getPath(...t){return c.join(this.path,...t)}exists(t=""){return a.access(this.getPath(t)).then(()=>!0,()=>!1)}rm(t=""){return a.rm(this.getPath(t),{recursive:!0,force:!0})}cp(t,r,i){return r?r.endsWith(c.sep)&&(r+=c.basename(t)):r=c.basename(t),a.cp(t,this.getPath(r),i)}mkdir(t){return a.mkdir(this.getPath(t),{recursive:!0})}writeFile(t,r){return a.writeFile(this.getPath(t),r)}writeJson(t,r){return this.writeFile(t,JSON.stringify(r,null,2))}readFile(t,r){return a.readFile(this.getPath(t),r)}async[Symbol.asyncDispose](){await this.rm()}}const P=v.realpathSync(F.tmpdir()),D=`fs-fixture-${Date.now()}-${process.pid}`;let p=0;const j=n(()=>(p+=1,p),"getId");class y{static{n(this,"Path")}path;constructor(t){this.path=t}}class f extends y{static{n(this,"Directory")}}class m extends y{static{n(this,"File")}content;constructor(t,r){super(t),this.content=r}}class l{static{n(this,"Symlink")}target;type;path;constructor(t,r){this.target=t,this.type=r}}const w=n((s,t,r)=>{const i=[];for(const u in s){if(!Object.hasOwn(s,u))continue;const e=c.join(t,u);let o=s[u];if(typeof o=="function"){const g=Object.assign(Object.create(r),{filePath:e}),h=o(g);if(h instanceof l){h.path=e,i.push(h);continue}else o=h}typeof o=="string"?i.push(new m(e,o)):i.push(new f(e),...w(o,e,r))}return i},"flattenFileTree"),k=n(async(s,t)=>{const r=t?.tempDir?c.resolve(t.tempDir):P,i=c.join(r,`${D}-${j()}/`);if(await a.mkdir(i,{recursive:!0}),s){if(typeof s=="string")await a.cp(s,i,{recursive:!0,filter:t?.templateFilter});else if(typeof s=="object"){const u={fixturePath:i,getPath:n((...e)=>c.join(i,...e),"getPath"),symlink:n((e,o)=>new l(e,o),"symlink")};await Promise.all(w(s,i,u).map(async e=>{e instanceof f?await a.mkdir(e.path,{recursive:!0}):e instanceof l?(await a.mkdir(c.dirname(e.path),{recursive:!0}),await a.symlink(e.target,e.path,e.type)):e instanceof m&&(await a.mkdir(c.dirname(e.path),{recursive:!0}),await a.writeFile(e.path,e.content))}))}}return new b(i)},"createFixture");exports.createFixture=k;
+"use strict";var g=Object.defineProperty;var a=(s,e)=>g(s,"name",{value:e,configurable:!0});var n=require("node:fs/promises"),o=require("node:path"),F=require("node:url"),v=require("node:fs"),P=require("node:os");typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class b{static{a(this,"FsFixture")}path;constructor(e){this.path=e}getPath(...e){return o.join(this.path,...e)}exists(e=""){return n.access(this.getPath(e)).then(()=>!0,()=>!1)}rm(e=""){return n.rm(this.getPath(e),{recursive:!0,force:!0})}cp(e,r,i){return r?r.endsWith(o.sep)&&(r+=o.basename(e)):r=o.basename(e),n.cp(e,this.getPath(r),i)}mkdir(e){return n.mkdir(this.getPath(e),{recursive:!0})}readFile=a(((e,r)=>n.readFile(this.getPath(e),r)),"readFile");readdir=a(((e,r)=>n.readdir(this.getPath(e||""),r)),"readdir");writeFile=a(((e,r,...i)=>n.writeFile(this.getPath(e),r,...i)),"writeFile");async readJson(e){const r=await this.readFile(e,"utf8");return JSON.parse(r)}writeJson(e,r,i=2){return this.writeFile(e,JSON.stringify(r,null,i))}async[Symbol.asyncDispose](){await this.rm()}}const D=v.realpathSync(P.tmpdir());class p{static{a(this,"PathBase")}constructor(e){this.path=e}}class y extends p{static{a(this,"Directory")}}class m extends p{static{a(this,"File")}constructor(e,r){super(e),this.content=r}}class u extends p{static{a(this,"Symlink")}constructor(e,r,i){super(i??""),this.target=e,this.type=r}}const w=a((s,e,r)=>{const i=[];for(const l in s){if(!Object.hasOwn(s,l))continue;const c=o.join(e,l);let t=s[l];if(typeof t=="function"){const h=Object.assign(Object.create(r),{filePath:c}),f=t(h);if(f instanceof u){const d=new u(f.target,f.type,c);i.push(d);continue}else t=f}if(typeof t=="string"||Buffer.isBuffer(t))i.push(new m(c,t));else if(t&&typeof t=="object"&&!Array.isArray(t))i.push(new y(c),...w(t,c,r));else throw new TypeError(`Invalid file content for path "${c}". Functions must return a string, Buffer, Symlink, or a nested FileTree object. Received: ${String(t)}`)}return i},"flattenFileTree"),j=a(async(s,e)=>{const r=e?.tempDir?o.resolve(typeof e.tempDir=="string"?e.tempDir:F.fileURLToPath(e.tempDir)):D;e?.tempDir&&await n.mkdir(r,{recursive:!0});const i=await n.mkdtemp(o.join(r,"fs-fixture-"));if(s){if(typeof s=="string")await n.cp(s,i,{recursive:!0,filter:e?.templateFilter});else if(typeof s=="object"){const c=w(s,i,{fixturePath:i,getPath:a((...t)=>o.join(i,...t),"getPath"),symlink:a((t,h)=>new u(t,h),"symlink")});await Promise.all(c.filter(t=>t instanceof y).map(t=>n.mkdir(t.path,{recursive:!0}))),await Promise.all(c.map(async t=>{t instanceof u?await n.symlink(t.target,t.path,t.type):t instanceof m&&await n.writeFile(t.path,t.content)}))}}return new b(i)},"createFixture");exports.createFixture=j;

package/dist/index.d.cts

@@ -1,47 +1,128 @@
 import { CopyOptions } from 'node:fs';
+import fs from 'node:fs/promises';
 
 declare class FsFixture {
     /**
-    Path to the fixture directory.
-    */
+     * Path to the fixture directory.
+     */
     readonly path: string;
     /**
-    Create a Fixture instance from a path. Does not create the fixture directory.
-    */
+     * Create a Fixture instance from a path. Does not create the fixture directory.
+     *
+     * @param fixturePath - The path to the fixture directory
+     */
     constructor(fixturePath: string);
     /**
-    Get the full path to a subpath in the fixture directory.
-    */
+     * Get the full path to a subpath in the fixture directory.
+     *
+     * @param subpaths - Path segments to join with the fixture directory
+     * @returns The absolute path to the subpath
+     *
+     * @example
+     * ```ts
+     * fixture.getPath('dir', 'file.txt')
+     * // => '/tmp/fs-fixture-123/dir/file.txt'
+     * ```
+     */
     getPath(...subpaths: string[]): string;
     /**
-    Check if the fixture exists. Pass in a subpath to check if it exists.
-    */
+     * Check if the fixture exists. Pass in a subpath to check if it exists.
+     *
+     * @param subpath - Optional subpath to check within the fixture directory
+     * @returns Promise resolving to true if the path exists, false otherwise
+     */
     exists(subpath?: string): Promise<boolean>;
     /**
-    Delete the fixture directory. Pass in a subpath to delete it.
-    */
+     * Delete the fixture directory or a subpath within it.
+     *
+     * @param subpath - Optional subpath to delete within the fixture directory.
+     *   Defaults to deleting the entire fixture.
+     * @returns Promise that resolves when deletion is complete
+     */
     rm(subpath?: string): Promise<void>;
     /**
-    Copy a path into the fixture directory.
-    */
+     * Copy a file or directory into the fixture directory.
+     *
+     * @param sourcePath - The source path to copy from
+     * @param destinationSubpath - Optional destination path within the fixture.
+     *   If omitted, uses the basename of sourcePath.
+     *   If ends with path separator, appends basename of sourcePath.
+     * @param options - Copy options (e.g., recursive, filter)
+     * @returns Promise that resolves when copy is complete
+     */
     cp(sourcePath: string, destinationSubpath?: string, options?: CopyOptions): Promise<void>;
     /**
-    Create a new folder in the fixture directory.
-    */
+     * Create a new folder in the fixture directory (including parent directories).
+     *
+     * @param folderPath - The folder path to create within the fixture
+     * @returns Promise that resolves when directory is created
+     */
     mkdir(folderPath: string): Promise<string | undefined>;
     /**
-    Create a file in the fixture directory.
-    */
-    writeFile(filePath: string, content: string): Promise<void>;
+     * Read a file from the fixture directory.
+     *
+     * @param filePath - The file path within the fixture to read
+     * @param options - Optional encoding or read options.
+     *   When encoding is specified, returns a string; otherwise returns a Buffer.
+     * @returns Promise resolving to file contents as string or Buffer
+     */
+    readFile: typeof fs.readFile;
     /**
-    Create a JSON file in the fixture directory.
-    */
-    writeJson(filePath: string, json: unknown): Promise<void>;
+     * Read the contents of a directory in the fixture.
+     *
+     * @param directoryPath - The directory path within the fixture to read.
+     *   Defaults to the fixture root when empty string is passed.
+     * @param options - Optional read directory options.
+     *   Use `{ withFileTypes: true }` to get Dirent objects.
+     * @returns Promise resolving to array of file/directory names or Dirent objects
+     */
+    readdir: typeof fs.readdir;
     /**
-    Read a file from the fixture directory.
-    */
-    readFile(filePath: string, encoding?: null): Promise<Buffer>;
-    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+     * Create or overwrite a file in the fixture directory.
+     *
+     * @param filePath - The file path within the fixture to write
+     * @param data - The content to write (string or Buffer)
+     * @param options - Optional encoding or write options
+     * @returns Promise that resolves when file is written
+     */
+    writeFile: typeof fs.writeFile;
+    /**
+     * Read and parse a JSON file from the fixture directory.
+     *
+     * @param filePath - The JSON file path within the fixture to read
+     * @returns Promise resolving to the parsed JSON content
+     *
+     * @example
+     * ```ts
+     * const data = await fixture.readJson<{ name: string }>('config.json')
+     * console.log(data.name) // Typed as string
+     * ```
+     */
+    readJson<T = unknown>(filePath: string): Promise<T>;
+    /**
+     * Create or overwrite a JSON file in the fixture directory.
+     *
+     * @param filePath - The JSON file path within the fixture to write
+     * @param json - The data to serialize as JSON
+     * @param space - Number of spaces or string to use for indentation. Defaults to 2.
+     * @returns Promise that resolves when file is written
+     *
+     * @example
+     * ```ts
+     * // Default 2-space indentation
+     * await fixture.writeJson('config.json', { key: 'value' })
+     *
+     * // 4-space indentation
+     * await fixture.writeJson('config.json', { key: 'value' }, 4)
+     *
+     * // Tab indentation
+     * await fixture.writeJson('config.json', { key: 'value' }, '\t')
+     *
+     * // Minified (no formatting)
+     * await fixture.writeJson('config.json', { key: 'value' }, 0)
+     * ```
+     */
+    writeJson(filePath: string, json: unknown, space?: string | number): Promise<void>;
     /**
      * Resource management cleanup
      * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
@@ -50,27 +131,32 @@ declare class FsFixture {
 }
 type FsFixtureType = FsFixture;
 
+declare class PathBase {
+    readonly path: string;
+    constructor(path: string);
+}
+
 type SymlinkType = 'file' | 'dir' | 'junction';
-declare class Symlink {
-    target: string;
-    type?: SymlinkType;
-    path?: string;
-    constructor(target: string, type?: SymlinkType);
+declare class Symlink extends PathBase {
+    readonly target: string;
+    readonly type?: SymlinkType | undefined;
+    constructor(target: string, type?: SymlinkType | undefined, filePath?: string);
 }
+
 type ApiBase = {
     fixturePath: string;
     getPath(...subpaths: string[]): string;
     symlink(targetPath: string, 
     /**
-         * Symlink type for Windows. Defaults to auto-detect by Node.
-         */
+     * Symlink type for Windows. Defaults to auto-detect by Node.
+     */
     type?: SymlinkType): Symlink;
 };
 type Api = ApiBase & {
     filePath: string;
 };
 type FileTree = {
-    [path: string]: string | FileTree | ((api: Api) => string | Symlink);
+    [path: string]: string | Buffer | FileTree | ((api: Api) => string | Buffer | Symlink);
 };
 
 type FilterFunction = CopyOptions['filter'];
@@ -78,14 +164,48 @@ type CreateFixtureOptions = {
     /**
      * The temporary directory to create the fixtures in.
      * Defaults to `os.tmpdir()`.
+     *
+     * Accepts either a string path or a URL object.
+     *
+     * Tip: use `new URL('.', import.meta.url)` to the get the file's directory (not the file).
      */
-    tempDir?: string;
+    tempDir?: string | URL;
     /**
      * Function to filter files to copy when using a template path.
      * Return `true` to copy the item, `false` to ignore it.
      */
     templateFilter?: FilterFunction;
 };
+/**
+ * Create a temporary test fixture directory.
+ *
+ * @param source - Optional source to create the fixture from:
+ *   - If omitted, creates an empty fixture directory
+ *   - If a string, copies the directory at that path to the fixture
+ *   - If a FileTree object, creates files and directories from the object structure
+ * @param options - Optional configuration for fixture creation
+ * @returns Promise resolving to an FsFixture instance
+ *
+ * @example
+ * ```ts
+ * // Create empty fixture
+ * const fixture = await createFixture()
+ *
+ * // Create from object
+ * const fixture = await createFixture({
+ *   'file.txt': 'content',
+ *   'dir/nested.txt': 'nested content',
+ *   'binary.bin': Buffer.from('binary'),
+ * })
+ *
+ * // Create from template directory
+ * const fixture = await createFixture('./my-template')
+ *
+ * // Cleanup
+ * await fixture.rm()
+ * ```
+ */
 declare const createFixture: (source?: string | FileTree, options?: CreateFixtureOptions) => Promise<FsFixture>;
 
-export { type CreateFixtureOptions, type FileTree, type FsFixtureType as FsFixture, createFixture };
+export { createFixture };
+export type { CreateFixtureOptions, FileTree, FsFixtureType as FsFixture };

package/dist/index.d.mts

@@ -1,47 +1,128 @@
 import { CopyOptions } from 'node:fs';
+import fs from 'node:fs/promises';
 
 declare class FsFixture {
     /**
-    Path to the fixture directory.
-    */
+     * Path to the fixture directory.
+     */
     readonly path: string;
     /**
-    Create a Fixture instance from a path. Does not create the fixture directory.
-    */
+     * Create a Fixture instance from a path. Does not create the fixture directory.
+     *
+     * @param fixturePath - The path to the fixture directory
+     */
     constructor(fixturePath: string);
     /**
-    Get the full path to a subpath in the fixture directory.
-    */
+     * Get the full path to a subpath in the fixture directory.
+     *
+     * @param subpaths - Path segments to join with the fixture directory
+     * @returns The absolute path to the subpath
+     *
+     * @example
+     * ```ts
+     * fixture.getPath('dir', 'file.txt')
+     * // => '/tmp/fs-fixture-123/dir/file.txt'
+     * ```
+     */
     getPath(...subpaths: string[]): string;
     /**
-    Check if the fixture exists. Pass in a subpath to check if it exists.
-    */
+     * Check if the fixture exists. Pass in a subpath to check if it exists.
+     *
+     * @param subpath - Optional subpath to check within the fixture directory
+     * @returns Promise resolving to true if the path exists, false otherwise
+     */
     exists(subpath?: string): Promise<boolean>;
     /**
-    Delete the fixture directory. Pass in a subpath to delete it.
-    */
+     * Delete the fixture directory or a subpath within it.
+     *
+     * @param subpath - Optional subpath to delete within the fixture directory.
+     *   Defaults to deleting the entire fixture.
+     * @returns Promise that resolves when deletion is complete
+     */
     rm(subpath?: string): Promise<void>;
     /**
-    Copy a path into the fixture directory.
-    */
+     * Copy a file or directory into the fixture directory.
+     *
+     * @param sourcePath - The source path to copy from
+     * @param destinationSubpath - Optional destination path within the fixture.
+     *   If omitted, uses the basename of sourcePath.
+     *   If ends with path separator, appends basename of sourcePath.
+     * @param options - Copy options (e.g., recursive, filter)
+     * @returns Promise that resolves when copy is complete
+     */
     cp(sourcePath: string, destinationSubpath?: string, options?: CopyOptions): Promise<void>;
     /**
-    Create a new folder in the fixture directory.
-    */
+     * Create a new folder in the fixture directory (including parent directories).
+     *
+     * @param folderPath - The folder path to create within the fixture
+     * @returns Promise that resolves when directory is created
+     */
     mkdir(folderPath: string): Promise<string | undefined>;
     /**
-    Create a file in the fixture directory.
-    */
-    writeFile(filePath: string, content: string): Promise<void>;
+     * Read a file from the fixture directory.
+     *
+     * @param filePath - The file path within the fixture to read
+     * @param options - Optional encoding or read options.
+     *   When encoding is specified, returns a string; otherwise returns a Buffer.
+     * @returns Promise resolving to file contents as string or Buffer
+     */
+    readFile: typeof fs.readFile;
     /**
-    Create a JSON file in the fixture directory.
-    */
-    writeJson(filePath: string, json: unknown): Promise<void>;
+     * Read the contents of a directory in the fixture.
+     *
+     * @param directoryPath - The directory path within the fixture to read.
+     *   Defaults to the fixture root when empty string is passed.
+     * @param options - Optional read directory options.
+     *   Use `{ withFileTypes: true }` to get Dirent objects.
+     * @returns Promise resolving to array of file/directory names or Dirent objects
+     */
+    readdir: typeof fs.readdir;
     /**
-    Read a file from the fixture directory.
-    */
-    readFile(filePath: string, encoding?: null): Promise<Buffer>;
-    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+     * Create or overwrite a file in the fixture directory.
+     *
+     * @param filePath - The file path within the fixture to write
+     * @param data - The content to write (string or Buffer)
+     * @param options - Optional encoding or write options
+     * @returns Promise that resolves when file is written
+     */
+    writeFile: typeof fs.writeFile;
+    /**
+     * Read and parse a JSON file from the fixture directory.
+     *
+     * @param filePath - The JSON file path within the fixture to read
+     * @returns Promise resolving to the parsed JSON content
+     *
+     * @example
+     * ```ts
+     * const data = await fixture.readJson<{ name: string }>('config.json')
+     * console.log(data.name) // Typed as string
+     * ```
+     */
+    readJson<T = unknown>(filePath: string): Promise<T>;
+    /**
+     * Create or overwrite a JSON file in the fixture directory.
+     *
+     * @param filePath - The JSON file path within the fixture to write
+     * @param json - The data to serialize as JSON
+     * @param space - Number of spaces or string to use for indentation. Defaults to 2.
+     * @returns Promise that resolves when file is written
+     *
+     * @example
+     * ```ts
+     * // Default 2-space indentation
+     * await fixture.writeJson('config.json', { key: 'value' })
+     *
+     * // 4-space indentation
+     * await fixture.writeJson('config.json', { key: 'value' }, 4)
+     *
+     * // Tab indentation
+     * await fixture.writeJson('config.json', { key: 'value' }, '\t')
+     *
+     * // Minified (no formatting)
+     * await fixture.writeJson('config.json', { key: 'value' }, 0)
+     * ```
+     */
+    writeJson(filePath: string, json: unknown, space?: string | number): Promise<void>;
     /**
      * Resource management cleanup
      * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
@@ -50,27 +131,32 @@ declare class FsFixture {
 }
 type FsFixtureType = FsFixture;
 
+declare class PathBase {
+    readonly path: string;
+    constructor(path: string);
+}
+
 type SymlinkType = 'file' | 'dir' | 'junction';
-declare class Symlink {
-    target: string;
-    type?: SymlinkType;
-    path?: string;
-    constructor(target: string, type?: SymlinkType);
+declare class Symlink extends PathBase {
+    readonly target: string;
+    readonly type?: SymlinkType | undefined;
+    constructor(target: string, type?: SymlinkType | undefined, filePath?: string);
 }
+
 type ApiBase = {
     fixturePath: string;
     getPath(...subpaths: string[]): string;
     symlink(targetPath: string, 
     /**
-         * Symlink type for Windows. Defaults to auto-detect by Node.
-         */
+     * Symlink type for Windows. Defaults to auto-detect by Node.
+     */
     type?: SymlinkType): Symlink;
 };
 type Api = ApiBase & {
     filePath: string;
 };
 type FileTree = {
-    [path: string]: string | FileTree | ((api: Api) => string | Symlink);
+    [path: string]: string | Buffer | FileTree | ((api: Api) => string | Buffer | Symlink);
 };
 
 type FilterFunction = CopyOptions['filter'];
@@ -78,14 +164,48 @@ type CreateFixtureOptions = {
     /**
      * The temporary directory to create the fixtures in.
      * Defaults to `os.tmpdir()`.
+     *
+     * Accepts either a string path or a URL object.
+     *
+     * Tip: use `new URL('.', import.meta.url)` to the get the file's directory (not the file).
      */
-    tempDir?: string;
+    tempDir?: string | URL;
     /**
      * Function to filter files to copy when using a template path.
      * Return `true` to copy the item, `false` to ignore it.
      */
     templateFilter?: FilterFunction;
 };
+/**
+ * Create a temporary test fixture directory.
+ *
+ * @param source - Optional source to create the fixture from:
+ *   - If omitted, creates an empty fixture directory
+ *   - If a string, copies the directory at that path to the fixture
+ *   - If a FileTree object, creates files and directories from the object structure
+ * @param options - Optional configuration for fixture creation
+ * @returns Promise resolving to an FsFixture instance
+ *
+ * @example
+ * ```ts
+ * // Create empty fixture
+ * const fixture = await createFixture()
+ *
+ * // Create from object
+ * const fixture = await createFixture({
+ *   'file.txt': 'content',
+ *   'dir/nested.txt': 'nested content',
+ *   'binary.bin': Buffer.from('binary'),
+ * })
+ *
+ * // Create from template directory
+ * const fixture = await createFixture('./my-template')
+ *
+ * // Cleanup
+ * await fixture.rm()
+ * ```
+ */
 declare const createFixture: (source?: string | FileTree, options?: CreateFixtureOptions) => Promise<FsFixture>;
 
-export { type CreateFixtureOptions, type FileTree, type FsFixtureType as FsFixture, createFixture };
+export { createFixture };
+export type { CreateFixtureOptions, FileTree, FsFixtureType as FsFixture };

package/dist/index.mjs

@@ -1 +1 @@
-var d=Object.defineProperty;var n=(s,t)=>d(s,"name",{value:t,configurable:!0});import a from"node:fs/promises";import c from"node:path";import b from"node:fs";import F from"node:os";typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class P{static{n(this,"FsFixture")}path;constructor(t){this.path=t}getPath(...t){return c.join(this.path,...t)}exists(t=""){return a.access(this.getPath(t)).then(()=>!0,()=>!1)}rm(t=""){return a.rm(this.getPath(t),{recursive:!0,force:!0})}cp(t,r,i){return r?r.endsWith(c.sep)&&(r+=c.basename(t)):r=c.basename(t),a.cp(t,this.getPath(r),i)}mkdir(t){return a.mkdir(this.getPath(t),{recursive:!0})}writeFile(t,r){return a.writeFile(this.getPath(t),r)}writeJson(t,r){return this.writeFile(t,JSON.stringify(r,null,2))}readFile(t,r){return a.readFile(this.getPath(t),r)}async[Symbol.asyncDispose](){await this.rm()}}const v=b.realpathSync(F.tmpdir()),D=`fs-fixture-${Date.now()}-${process.pid}`;let m=0;const j=n(()=>(m+=1,m),"getId");class u{static{n(this,"Path")}path;constructor(t){this.path=t}}class f extends u{static{n(this,"Directory")}}class y extends u{static{n(this,"File")}content;constructor(t,r){super(t),this.content=r}}class l{static{n(this,"Symlink")}target;type;path;constructor(t,r){this.target=t,this.type=r}}const w=n((s,t,r)=>{const i=[];for(const p in s){if(!Object.hasOwn(s,p))continue;const e=c.join(t,p);let o=s[p];if(typeof o=="function"){const g=Object.assign(Object.create(r),{filePath:e}),h=o(g);if(h instanceof l){h.path=e,i.push(h);continue}else o=h}typeof o=="string"?i.push(new y(e,o)):i.push(new f(e),...w(o,e,r))}return i},"flattenFileTree"),k=n(async(s,t)=>{const r=t?.tempDir?c.resolve(t.tempDir):v,i=c.join(r,`${D}-${j()}/`);if(await a.mkdir(i,{recursive:!0}),s){if(typeof s=="string")await a.cp(s,i,{recursive:!0,filter:t?.templateFilter});else if(typeof s=="object"){const p={fixturePath:i,getPath:n((...e)=>c.join(i,...e),"getPath"),symlink:n((e,o)=>new l(e,o),"symlink")};await Promise.all(w(s,i,p).map(async e=>{e instanceof f?await a.mkdir(e.path,{recursive:!0}):e instanceof l?(await a.mkdir(c.dirname(e.path),{recursive:!0}),await a.symlink(e.target,e.path,e.type)):e instanceof y&&(await a.mkdir(c.dirname(e.path),{recursive:!0}),await a.writeFile(e.path,e.content))}))}}return new P(i)},"createFixture");export{k as createFixture};
+var d=Object.defineProperty;var a=(s,e)=>d(s,"name",{value:e,configurable:!0});import n from"node:fs/promises";import c from"node:path";import{fileURLToPath as F}from"node:url";import P from"node:fs";import b from"node:os";typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class D{static{a(this,"FsFixture")}path;constructor(e){this.path=e}getPath(...e){return c.join(this.path,...e)}exists(e=""){return n.access(this.getPath(e)).then(()=>!0,()=>!1)}rm(e=""){return n.rm(this.getPath(e),{recursive:!0,force:!0})}cp(e,r,i){return r?r.endsWith(c.sep)&&(r+=c.basename(e)):r=c.basename(e),n.cp(e,this.getPath(r),i)}mkdir(e){return n.mkdir(this.getPath(e),{recursive:!0})}readFile=a(((e,r)=>n.readFile(this.getPath(e),r)),"readFile");readdir=a(((e,r)=>n.readdir(this.getPath(e||""),r)),"readdir");writeFile=a(((e,r,...i)=>n.writeFile(this.getPath(e),r,...i)),"writeFile");async readJson(e){const r=await this.readFile(e,"utf8");return JSON.parse(r)}writeJson(e,r,i=2){return this.writeFile(e,JSON.stringify(r,null,i))}async[Symbol.asyncDispose](){await this.rm()}}const j=P.realpathSync(b.tmpdir());class h{static{a(this,"PathBase")}constructor(e){this.path=e}}class u extends h{static{a(this,"Directory")}}class y extends h{static{a(this,"File")}constructor(e,r){super(e),this.content=r}}class p extends h{static{a(this,"Symlink")}constructor(e,r,i){super(i??""),this.target=e,this.type=r}}const w=a((s,e,r)=>{const i=[];for(const f in s){if(!Object.hasOwn(s,f))continue;const o=c.join(e,f);let t=s[f];if(typeof t=="function"){const m=Object.assign(Object.create(r),{filePath:o}),l=t(m);if(l instanceof p){const g=new p(l.target,l.type,o);i.push(g);continue}else t=l}if(typeof t=="string"||Buffer.isBuffer(t))i.push(new y(o,t));else if(t&&typeof t=="object"&&!Array.isArray(t))i.push(new u(o),...w(t,o,r));else throw new TypeError(`Invalid file content for path "${o}". Functions must return a string, Buffer, Symlink, or a nested FileTree object. Received: ${String(t)}`)}return i},"flattenFileTree"),k=a(async(s,e)=>{const r=e?.tempDir?c.resolve(typeof e.tempDir=="string"?e.tempDir:F(e.tempDir)):j;e?.tempDir&&await n.mkdir(r,{recursive:!0});const i=await n.mkdtemp(c.join(r,"fs-fixture-"));if(s){if(typeof s=="string")await n.cp(s,i,{recursive:!0,filter:e?.templateFilter});else if(typeof s=="object"){const o=w(s,i,{fixturePath:i,getPath:a((...t)=>c.join(i,...t),"getPath"),symlink:a((t,m)=>new p(t,m),"symlink")});await Promise.all(o.filter(t=>t instanceof u).map(t=>n.mkdir(t.path,{recursive:!0}))),await Promise.all(o.map(async t=>{t instanceof p?await n.symlink(t.target,t.path,t.type):t instanceof y&&await n.writeFile(t.path,t.content)}))}}return new D(i)},"createFixture");export{k as createFixture};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-fixture",
-  "version": "2.8.1",
+  "version": "2.10.0",
   "description": "Easily create test fixtures at a temporary file-system path",
   "keywords": [
     "test",