fs-fixture 2.10.2 → 2.12.0

package/README.md

@@ -128,6 +128,10 @@ const files = await fixture.readdir('src')
 // Copy files into fixture
 await fixture.cp('/path/to/file.txt', 'copied-file.txt')
 
+// Move or rename files
+await fixture.mv('old-name.txt', 'new-name.txt')
+await fixture.mv('file.txt', 'src/file.txt')
+
 // Check if path exists
 if (await fixture.exists('optional-file.txt')) {
     // ...
@@ -145,6 +149,19 @@ const fixture = await createFixture({
 })
 ```
 
+**Symlinks:**
+```ts
+const fixture = await createFixture({
+    'index.js': 'import pkg from \'pkg\'',
+
+    // Symlink individual file or directory
+    'node_modules/pkg': ({ symlink }) => symlink(process.cwd()),
+
+    // Symlink entire directory (useful for sharing node_modules)
+    node_modules: ({ symlink }) => symlink(path.resolve('node_modules'))
+})
+```
+
 **Binary files:**
 ```ts
 const fixture = await createFixture({
@@ -203,6 +220,7 @@ const fixture = await createFixture({}, { tempDir: './custom-temp' })
 | `readdir(path, options?)` | List directory contents |
 | `mkdir(path)` | Create directory (recursive) |
 | `cp(source, dest?)` | Copy file/directory into fixture |
+| `mv(source, dest)` | Move or rename file/directory |
 
 ### Types
 

package/dist/index.cjs

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

package/dist/index.d.cts

@@ -58,6 +58,27 @@ declare class FsFixture {
      * @returns Promise that resolves when directory is created
      */
     mkdir(folderPath: string): Promise<string | undefined>;
+    /**
+     * Move or rename a file or directory within the fixture.
+     * This is a wrapper around `node:fs/promises.rename`.
+     *
+     * @param sourcePath - The source path relative to the fixture root
+     * @param destinationPath - The destination path relative to the fixture root
+     * @returns Promise that resolves when the move is complete
+     *
+     * @example
+     * ```ts
+     * // Rename a file
+     * await fixture.mv('old-name.txt', 'new-name.txt')
+     *
+     * // Move a file into a directory
+     * await fixture.mv('file.txt', 'src/file.txt')
+     *
+     * // Rename a directory
+     * await fixture.mv('src', 'lib')
+     * ```
+     */
+    mv(sourcePath: string, destinationPath: string): Promise<void>;
     /**
      * Read a file from the fixture directory.
      *

package/dist/index.d.mts

@@ -58,6 +58,27 @@ declare class FsFixture {
      * @returns Promise that resolves when directory is created
      */
     mkdir(folderPath: string): Promise<string | undefined>;
+    /**
+     * Move or rename a file or directory within the fixture.
+     * This is a wrapper around `node:fs/promises.rename`.
+     *
+     * @param sourcePath - The source path relative to the fixture root
+     * @param destinationPath - The destination path relative to the fixture root
+     * @returns Promise that resolves when the move is complete
+     *
+     * @example
+     * ```ts
+     * // Rename a file
+     * await fixture.mv('old-name.txt', 'new-name.txt')
+     *
+     * // Move a file into a directory
+     * await fixture.mv('file.txt', 'src/file.txt')
+     *
+     * // Rename a directory
+     * await fixture.mv('src', 'lib')
+     * ```
+     */
+    mv(sourcePath: string, destinationPath: string): Promise<void>;
     /**
      * Read a file from the fixture directory.
      *

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-fixture",
-  "version": "2.10.2",
+  "version": "2.12.0",
   "description": "Easily create test fixtures at a temporary file-system path",
   "keywords": [
     "test",
@@ -20,7 +20,8 @@
     "email": "hiroki.osame@gmail.com"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/skills/fs-fixture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: fs-fixture
+description: Create disposable file system test fixtures from objects, templates, or empty directories with automatic cleanup. Use when writing tests that need temporary files, directories, symlinks, or JSON fixtures on disk. Keywords - fs, tmp, temp, fixture, testing utility, cleanup, dispose.
+---
+
+## Quick Start
+
+```ts
+import { createFixture } from 'fs-fixture'
+
+// From object — keys are paths, values are content
+const fixture = await createFixture({
+    'package.json': JSON.stringify({ name: 'test' }),
+    'src/index.js': 'export default 42',
+})
+
+// Use fixture.path, fixture.readFile(), etc.
+await fixture.rm() // Cleanup when done
+```
+
+Auto-cleanup with `using` (TypeScript 5.2+):
+```ts
+await using fixture = await createFixture({ 'file.txt': 'content' })
+// Automatically cleaned up when scope exits
+```
+
+## createFixture(source?, options?)
+
+| Source | Behavior |
+|--------|----------|
+| `{ path: content }` | Create files from object. Nested objects create directories. |
+| `'./path'` | Copy template directory into fixture |
+| _(omitted)_ | Empty temporary directory |
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tempDir` | `string \| URL` | `os.tmpdir()` | Custom parent directory |
+| `templateFilter` | `(src, dest) => boolean` | — | Filter files when copying template |
+
+## FsFixture Methods
+
+| Method | Description |
+|--------|-------------|
+| `fixture.path` | Absolute path to fixture root |
+| `getPath(...paths)` | Resolve path relative to fixture root |
+| `exists(path?)` | Check existence (returns `boolean`) |
+| `readFile(path, encoding?)` | Read file — `'utf8'` returns `string`, omit for `Buffer` |
+| `writeFile(path, content)` | Write string or Buffer |
+| `readJson<T>(path)` | Read and parse JSON with type parameter |
+| `writeJson(path, data, space?)` | Write JSON (default: 2-space indent, `0` for minified) |
+| `readdir(path, options?)` | List directory (`{ withFileTypes: true }` for Dirent[]) |
+| `mkdir(path)` | Create directory recursively |
+| `cp(source, dest?)` | Copy external file/directory into fixture |
+| `mv(source, dest)` | Move or rename within fixture |
+| `rm(path?)` | Delete path, or entire fixture if omitted |
+
+## FileTree Values
+
+| Type | Example |
+|------|---------|
+| `string` | `'file content'` |
+| `Buffer` | `Buffer.from([0x89, 0x50])` |
+| Nested object | `{ dir: { 'file.txt': 'content' } }` |
+| Function | `({ fixturePath, filePath, getPath, symlink }) => symlink('./target')` |
+
+Path syntax — these are equivalent:
+```ts
+// Nested objects
+{ src: { utils: { 'helper.js': 'code' } } }
+
+// Slash-separated keys
+{ 'src/utils/helper.js': 'code' }
+```
+
+## Patterns
+
+### Symlinks
+```ts
+const fixture = await createFixture({
+    'target.txt': 'real file',
+    'link.txt': ({ symlink }) => symlink('./target.txt'),
+    'node_modules/pkg': ({ symlink }) => symlink(process.cwd()),
+})
+```
+
+### Dynamic content
+```ts
+const fixture = await createFixture({
+    'info.txt': ({ fixturePath }) => `Root: ${fixturePath}`,
+})
+```
+
+## Related
+
+Commonly used with `manten` test framework.