fs-fixture 1.2.0 → 2.1.0

package/README.md

@@ -1,45 +1,62 @@
-# fs-fixture
+<p align="center">
+	<img width="160" src=".github/logo.webp">
+</p>
+<h1 align="center">
+	<sup>fs-fixture</sup>
+	<br>
+	<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>
 
-Easily create test fixtures at a temporary file-system path.
+Simple API to create disposable test fixtures on disk.
 
-<sub>Support this project by ⭐️ starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on! ❤️</sub>
-
-## Usage
-
-### JSON input
-
-Pass in an object representing the test fixture.
+Tiny (`560 B` gzipped) and no dependencies!
 
+### Example
 ```ts
+import fs from 'fs/promises'
 import { createFixture } from 'fs-fixture'
 
-test('my test using json fixture', async () => {
-    // Pass in a JSON representing the test fixture
-    const fixture = await createFixture({
-        // Nested directory syntax
-        directoryA: {
-            directoryB: {
-                fileNameA: 'fileContent'
-            }
-        },
+const fixture = await createFixture({
+    'dir-a': {
+        'file-b': 'hello world'
+    }
+})
+
+const content = await fs.readFile(fixture.getPath('dir-a/file-b'))
+console.log(content)
+```
 
-        // Directory path syntax - Same as above
-        'directoryA/directoryB/fileNameB': 'fileContent'
-    })
+<p align="center">
+	<a href="https://github.com/sponsors/privatenumber/sponsorships?tier_id=398771"><img width="412" src="https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/donate.webp"></a>
+	<a href="https://github.com/sponsors/privatenumber/sponsorships?tier_id=397608"><img width="412" src="https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/sponsor.webp"></a>
+</p>
+<p align="center"><sup><i>Already a sponsor?</i> Join the discussion in the <a href="https://github.com/pvtnbr/fs-fixture">Development repo</a>!</sup></p>
 
-    /*
-    Your test code here...
+## Usage
 
-    // Log fixture path
-    console.log(fixture.path)
+Pass in an object representing the file structure:
 
-    // Check if relative path exists
-    console.log(await fixture.exists('./file'))
-    */
+```ts
+import { createFixture } from 'fs-fixture'
 
-    // Cleanup fixture
-    await fixture.rm()
+const fixture = await createFixture({
+    // Nested directory syntax
+    'dir-a': {
+        'dir-b': {
+            'file-a.txt': 'hello world',
+            'file-b.txt': ({ fixturePath }) => `Fixture path: ${fixturePath}`
+        }
+    },
+
+    // Alternatively, use the directory path syntax - Same as above
+    'dir-a/dir-b/file-b.txt': 'goodbye world'
 })
+
+// Interact with the fixture
+console.log(fixture.path)
+
+// Cleanup fixture
+await fixture.rm()
 ```
 
 ### Template path input
@@ -47,15 +64,23 @@ test('my test using json fixture', async () => {
 Pass in a path to a test fixture template directory to make a copy of it.
 
 ```ts
-test('my test using template path', async () => {
-    // Pass in a path to a fixture template path, and it will make a copy of it
-    const fixture = await createFixture('./fixtures/template-a')
+// 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... */
+/* Your test code here... */
 
-    // Cleanup fixture
-    await fixture.rm()
-})
+// Cleanup fixture
+await fixture.rm()
+```
+
+### `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.
+
+```ts
+await using fixture = await createFixture({ file: 'hello' })
+
+// No need to run fixture.rm()
 ```
 
 ## API
@@ -86,13 +111,18 @@ class FsFixture {
     /**
     Path to the fixture directory.
     */
-    path: string
+    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(subpath: string): string
+
     /**
     Check if the fixture exists. Pass in a subpath to check if it exists.
     */
@@ -111,7 +141,7 @@ class FsFixture {
     /**
     Create a JSON file in the fixture directory.
     */
-    writeJson(filePath: string, json: any): Promise<void>
+    writeJson(filePath: string, json: unknown): Promise<void>
 
     /**
     Read a file from the fixture directory.

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var i=require("fs"),c=require("path"),l=require("os");function o(e){return e&&typeof e=="object"&&"default"in e?e:{default:e}}var p=o(i),a=o(c),d=o(l);class h{path;constructor(t){this.path=t}exists(t=""){return i.promises.access(a.default.join(this.path,t)).then(()=>!0,()=>!1)}rm(t=""){return i.promises.rm(a.default.join(this.path,t),{recursive:!0,force:!0})}writeFile(t,r){return i.promises.writeFile(a.default.join(this.path,t),r)}writeJson(t,r){return this.writeFile(t,JSON.stringify(r,null,2))}readFile(t,r){return i.promises.readFile(a.default.join(this.path,t),r)}}const m=p.default.realpathSync(d.default.tmpdir()),y=`fs-fixture-${Date.now()}`;let u=0;function w(){return u+=1,u}const{hasOwnProperty:j}=Object.prototype,v=(e,t)=>j.call(e,t);function f(e,t){const r=[];for(const s in e){if(!v(e,s))continue;const n=e[s];typeof n=="string"?r.push({path:a.default.join(t,s),content:n}):r.push(...f(n,a.default.join(t,s)))}return r}async function F(e){const t=a.default.join(m,`${y}-${w()}`);return await i.promises.mkdir(t,{recursive:!0}),e&&(typeof e=="string"?await i.promises.cp(e,t,{recursive:!0}):typeof e=="object"&&await Promise.all(f(e,t).map(async r=>{await i.promises.mkdir(a.default.dirname(r.path),{recursive:!0}),await i.promises.writeFile(r.path,r.content)}))),new h(t)}exports.createFixture=F;
+"use strict";var i=require("fs/promises"),a=require("path"),l=require("fs"),f=require("os");typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class h{path;constructor(t){this.path=t}getPath(t){return a.join(this.path,t)}exists(t=""){return i.access(this.getPath(t)).then(()=>!0,()=>!1)}rm(t=""){return i.rm(this.getPath(t),{recursive:!0,force:!0})}writeFile(t,e){return i.writeFile(this.getPath(t),e)}writeJson(t,e){return this.writeFile(t,JSON.stringify(e,null,2))}readFile(t,e){return i.readFile(this.getPath(t),e)}async[Symbol.asyncDispose](){await this.rm()}}const p=l.realpathSync(f.tmpdir()),y=`fs-fixture-${Date.now()}`;let c=0;const m=()=>(c+=1,c),u=(r,t,e)=>{const o=[];for(const n in r){if(!Object.hasOwn(r,n))continue;let s=r[n];typeof s=="function"&&(s=s(e)),typeof s=="string"?o.push({path:a.join(t,n),content:s}):o.push(...u(s,a.join(t,n),e))}return o},w=async r=>{const t=a.join(p,`${y}-${m()}/`);return await i.mkdir(t,{recursive:!0}),r&&(typeof r=="string"?await i.cp(r,t,{recursive:!0}):typeof r=="object"&&await Promise.all(u(r,t,{fixturePath:t}).map(async e=>{await i.mkdir(a.dirname(e.path),{recursive:!0}),await i.writeFile(e.path,e.content)}))),new h(t)};exports.createFixture=w;

package/dist/index.d.cts

@@ -2,12 +2,16 @@ declare class FsFixture {
     /**
     Path to the fixture directory.
     */
-    path: string;
+    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(subpath: string): string;
+    /**
     Check if the fixture exists. Pass in a subpath to check if it exists.
     */
     exists(subpath?: string): Promise<boolean>;
@@ -22,16 +26,25 @@ declare class FsFixture {
     /**
     Create a JSON file in the fixture directory.
     */
-    writeJson(filePath: string, json: any): Promise<void>;
+    writeJson(filePath: string, json: unknown): Promise<void>;
     /**
     Read a file from the fixture directory.
     */
-    readFile(filePath: string, encoding?: BufferEncoding): Promise<string | Buffer>;
+    readFile(filePath: string, encoding?: null): Promise<Buffer>;
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+    /**
+     * Resource management cleanup
+     * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 
+type Api = {
+    fixturePath: string;
+};
 type FileTree = {
-    [path: string]: string | FileTree;
+    [path: string]: string | FileTree | ((api: Api) => string);
 };
-declare function createFixture(source?: string | FileTree): Promise<FsFixture>;
+declare const createFixture: (source?: string | FileTree) => Promise<FsFixture>;
 
-export { FileTree, FsFixture, createFixture };
+export { type FileTree, FsFixture, createFixture };

package/dist/index.d.mts

@@ -2,12 +2,16 @@ declare class FsFixture {
     /**
     Path to the fixture directory.
     */
-    path: string;
+    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(subpath: string): string;
+    /**
     Check if the fixture exists. Pass in a subpath to check if it exists.
     */
     exists(subpath?: string): Promise<boolean>;
@@ -22,16 +26,25 @@ declare class FsFixture {
     /**
     Create a JSON file in the fixture directory.
     */
-    writeJson(filePath: string, json: any): Promise<void>;
+    writeJson(filePath: string, json: unknown): Promise<void>;
     /**
     Read a file from the fixture directory.
     */
-    readFile(filePath: string, encoding?: BufferEncoding): Promise<string | Buffer>;
+    readFile(filePath: string, encoding?: null): Promise<Buffer>;
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+    /**
+     * Resource management cleanup
+     * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 
+type Api = {
+    fixturePath: string;
+};
 type FileTree = {
-    [path: string]: string | FileTree;
+    [path: string]: string | FileTree | ((api: Api) => string);
 };
-declare function createFixture(source?: string | FileTree): Promise<FsFixture>;
+declare const createFixture: (source?: string | FileTree) => Promise<FsFixture>;
 
-export { FileTree, FsFixture, createFixture };
+export { type FileTree, FsFixture, createFixture };

package/dist/index.mjs

@@ -1 +1 @@
-import p,{promises as i}from"fs";import n from"path";import u from"os";class h{path;constructor(t){this.path=t}exists(t=""){return i.access(n.join(this.path,t)).then(()=>!0,()=>!1)}rm(t=""){return i.rm(n.join(this.path,t),{recursive:!0,force:!0})}writeFile(t,e){return i.writeFile(n.join(this.path,t),e)}writeJson(t,e){return this.writeFile(t,JSON.stringify(e,null,2))}readFile(t,e){return i.readFile(n.join(this.path,t),e)}}const f=p.realpathSync(u.tmpdir()),l=`fs-fixture-${Date.now()}`;let a=0;function m(){return a+=1,a}const{hasOwnProperty:w}=Object.prototype,y=(r,t)=>w.call(r,t);function c(r,t){const e=[];for(const o in r){if(!y(r,o))continue;const s=r[o];typeof s=="string"?e.push({path:n.join(t,o),content:s}):e.push(...c(s,n.join(t,o)))}return e}async function F(r){const t=n.join(f,`${l}-${m()}`);return await i.mkdir(t,{recursive:!0}),r&&(typeof r=="string"?await i.cp(r,t,{recursive:!0}):typeof r=="object"&&await Promise.all(c(r,t).map(async e=>{await i.mkdir(n.dirname(e.path),{recursive:!0}),await i.writeFile(e.path,e.content)}))),new h(t)}export{F as createFixture};
+import i from"fs/promises";import a from"path";import l from"fs";import p from"os";typeof Symbol.asyncDispose!="symbol"&&Object.defineProperty(Symbol,"asyncDispose",{configurable:!1,enumerable:!1,writable:!1,value:Symbol.for("asyncDispose")});class u{path;constructor(t){this.path=t}getPath(t){return a.join(this.path,t)}exists(t=""){return i.access(this.getPath(t)).then(()=>!0,()=>!1)}rm(t=""){return i.rm(this.getPath(t),{recursive:!0,force:!0})}writeFile(t,e){return i.writeFile(this.getPath(t),e)}writeJson(t,e){return this.writeFile(t,JSON.stringify(e,null,2))}readFile(t,e){return i.readFile(this.getPath(t),e)}async[Symbol.asyncDispose](){await this.rm()}}const h=l.realpathSync(p.tmpdir()),m=`fs-fixture-${Date.now()}`;let c=0;const y=()=>(c+=1,c),f=(r,t,e)=>{const o=[];for(const n in r){if(!Object.hasOwn(r,n))continue;let s=r[n];typeof s=="function"&&(s=s(e)),typeof s=="string"?o.push({path:a.join(t,n),content:s}):o.push(...f(s,a.join(t,n),e))}return o},w=async r=>{const t=a.join(h,`${m}-${y()}/`);return await i.mkdir(t,{recursive:!0}),r&&(typeof r=="string"?await i.cp(r,t,{recursive:!0}):typeof r=="object"&&await Promise.all(f(r,t,{fixturePath:t}).map(async e=>{await i.mkdir(a.dirname(e.path),{recursive:!0}),await i.writeFile(e.path,e.content)}))),new u(t)};export{w as createFixture};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-fixture",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "Easily create test fixtures at a temporary file-system path",
   "keywords": [
     "test",
@@ -43,6 +43,6 @@
     }
   },
   "engines": {
-    "node": ">=16.7.0"
+    "node": ">=18.0.0"
   }
 }