fs-fixture 1.1.0 → 2.0.0

package/README.md

@@ -1,45 +1,54 @@
-# fs-fixture
+# fs-fixture [![Latest version](https://badgen.net/npm/v/fs-fixture)](https://npm.im/fs-fixture) [![npm downloads](https://badgen.net/npm/dm/fs-fixture)](https://npm.im/fs-fixture)
 
-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'
+    }
+})
 
-        // Directory path syntax - Same as above
-        'directoryA/directoryB/fileNameB': 'fileContent'
-    })
+const content = await fs.readFile(fixture.getPath('dir-a/file-b'))
+console.log(content)
+```
 
-    /*
-    Your test code here...
+<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>
 
-    // Log fixture path
-    console.log(fixture.path)
+## Usage
 
-    // Check if relative path exists
-    console.log(await fixture.exists('./file'))
-    */
+Pass in an object representing the file structure:
+
+```ts
+import { createFixture } from 'fs-fixture'
+
+const fixture = await createFixture({
+    // Nested directory syntax
+    'dir-a': {
+        'dir-b': {
+            'file-a.txt': 'hello world'
+        }
+    },
 
-    // Cleanup fixture
-    await fixture.rm()
+    // 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 +56,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
@@ -93,6 +110,11 @@ class FsFixture {
     */
     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 +133,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.
@@ -119,3 +141,9 @@ class FsFixture {
     readFile(filePath: string, encoding?: BufferEncoding): Promise<string | Buffer>
 }
 ```
+
+## Related
+
+### [manten](https://github.com/privatenumber/manten)
+
+Lightweight testing library for Node.js

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var i=require("fs/promises"),s=require("path"),u=require("fs"),l=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 s.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 f=u.realpathSync(l.tmpdir()),p=`fs-fixture-${Date.now()}`;let o=0;const y=()=>(o+=1,o),c=(r,t)=>{const e=[];for(const a in r){if(!Object.hasOwn(r,a))continue;const n=r[a];typeof n=="string"?e.push({path:s.join(t,a),content:n}):e.push(...c(n,s.join(t,a)))}return e},m=async r=>{const t=s.join(f,`${p}-${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(c(r,t).map(async e=>{await i.mkdir(s.dirname(e.path),{recursive:!0}),await i.writeFile(e.path,e.content)}))),new h(t)};exports.createFixture=m;

package/dist/{index.d.ts → index.d.cts}

@@ -8,6 +8,10 @@ declare class FsFixture {
     */
     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,21 @@ 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>;
+    /**
+     * Resource management cleanup
+     * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
+     */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 
-declare type FileTree = {
+type FileTree = {
     [path: string]: string | FileTree;
 };
-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

@@ -0,0 +1,46 @@
+declare class FsFixture {
+    /**
+    Path to the fixture directory.
+    */
+    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>;
+    /**
+    Delete the fixture directory. Pass in a subpath to delete it.
+    */
+    rm(subpath?: 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>;
+    /**
+     * Resource management cleanup
+     * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+type FileTree = {
+    [path: string]: string | FileTree;
+};
+declare const createFixture: (source?: string | FileTree) => Promise<FsFixture>;
+
+export { type FileTree, FsFixture, createFixture };

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fs-fixture",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Easily create test fixtures at a temporary file-system path",
   "keywords": [
     "test",
@@ -22,13 +22,18 @@
   "files": [
     "dist"
   ],
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.cts",
   "exports": {
-    "require": "./dist/index.js",
-    "import": "./dist/index.mjs",
-    "types": "./dist/index.d.ts"
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    },
+    "import": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
   },
   "imports": {
     "#fs-fixture": {
@@ -36,5 +41,8 @@
       "development": "./src/index.ts",
       "default": "./dist/index.mjs"
     }
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/dist/index.js

@@ -1 +0,0 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var i=require("fs"),l=require("path"),p=require("os");function u(e){return e&&typeof e=="object"&&"default"in e?e:{default:e}}var c=u(i),a=u(l),d=u(p);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=a.default.join(c.default.realpathSync(d.default.tmpdir()),"test-fixtures",Date.now().toString());let o=0;function w(){return o+=1,o}const{hasOwnProperty:y}=Object.prototype,j=(e,t)=>y.call(e,t);function f(e,t){const r=[];for(const s in e){if(!j(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 v(e){const t=a.default.join(m,`fixture-${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=v;