@brianbuie/node-kit 0.8.0 → 0.9.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Brian Buie
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -249,10 +249,11 @@ export class File {
     get exists() 
     delete() 
     read() 
-    write(contents: string) 
-    async streamFrom(...options: Parameters<(typeof Readable)["from"]>) 
-    append(lines: string | string[]) 
     lines() 
+    get readStream() 
+    get writeStream() 
+    write(contents: string | ReadableStream) 
+    append(lines: string | string[]) 
     static get FileType() 
     json<T>(contents?: T) 
     static get json() 
@@ -295,13 +296,15 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ---
 ## Class: FileType
 
+A generic file adaptor, extended by specific file type implementations
+
 ```ts
-export class FileType<T = string> {
+export class FileType {
     file;
-    constructor(filepath: string, contents?: T) 
+    constructor(filepath: string, contents?: string) 
     get exists() 
-    delete() 
     get path() 
+    delete() 
 }
 ```
 
@@ -310,10 +313,14 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ---
 ## Class: FileTypeCsv
 
+Comma separated values (.csv).
+Input rows as objects, keys are used as column headers
+
 ```ts
 export class FileTypeCsv<Row extends object> extends FileType {
     constructor(filepath: string) 
     async write(rows: Row[], keys?: Key<Row>[]) 
+    #parseVal(val: string) 
     async read() 
 }
 ```
@@ -325,6 +332,9 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ---
 ## Class: FileTypeJson
 
+A .json file that maintains data type when reading/writing.
+This is unsafe! Type is not checked at runtime, avoid using on files manipulated outside of your application.
+
 ```ts
 export class FileTypeJson<T> extends FileType {
     constructor(filepath: string, contents?: T) 
@@ -340,6 +350,8 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ---
 ## Class: FileTypeNdjson
 
+New-line delimited json file (.ndjson)
+
 ```ts
 export class FileTypeNdjson<T extends object> extends FileType {
     constructor(filepath: string, lines?: T | T[]) 

package/package.json

@@ -1,28 +1,27 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/brianbuie/node-kit.git"
   },
   "scripts": {
-    "docs": "node ./node_modules/ts2md/out/src/ts2md.js --firstHeadingLevel=1",
-    "test": "tsc && node --test \"dist/**/*.test.js\" --quiet",
-    "preversion": "npm test && npm run docs",
+    "build": "tsdown && node ./node_modules/ts2md/out/src/ts2md.js --firstHeadingLevel=1",
+    "test": "tsc && node --test \"src/*.test.ts\" --quiet",
+    "preversion": "npm test && npm run build",
     "postversion": "git push --follow-tags"
   },
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "default": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
     }
   },
   "files": [
     "src",
     "dist",
-    "!dist/**/*.test.*",
     "README.md"
   ],
   "engines": {
@@ -41,6 +40,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.9.1",
     "ts2md": "^0.2.8",
+    "tsdown": "^0.16.6",
     "typescript": "^5.9.3"
   }
 }

package/src/Cache.ts

@@ -1,5 +1,5 @@
 import { type Duration, isAfter, add } from 'date-fns';
-import { temp } from './Dir.js';
+import { temp } from './Dir.ts';
 
 const cacheDir = temp.dir('cache');
 

package/src/Dir.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Dir, TempDir, temp } from './Dir.js';
+import { Dir, TempDir, temp } from './Dir.ts';
 
 describe('Dir', () => {
   const testDir = temp.dir('dir-test');

package/src/Dir.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import sanitizeFilename from 'sanitize-filename';
-import { File } from './File.js';
+import { File } from './File.ts';
 
 /**
  * Reference to a specific directory with helpful methods for resolving filepaths,

package/src/Fetcher.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Fetcher } from './Fetcher.js';
+import { Fetcher } from './Fetcher.ts';
 
 describe('Fetcher', () => {
   const statusApi = new Fetcher({ base: 'https://mock.httpstatus.io' });

package/src/File.test.ts

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { temp } from './Dir.js';
-import { File } from './File.js';
+import { temp } from './Dir.ts';
+import { File } from './File.ts';
 
 const testDir = temp.dir('file-test');
 testDir.clear();
@@ -14,6 +14,17 @@ const thing = {
   e: null,
 };
 
+describe('File', () => {
+  it('Handles request body as stream input', async () => {
+    const img = testDir.file('image.jpg');
+    await fetch('https://testingbot.com/free-online-tools/random-avatar/300').then((res) => {
+      if (!res.body) throw new Error('No response body');
+      return img.write(res.body);
+    });
+    assert(img.exists);
+  });
+});
+
 describe('FileType', () => {
   it('Creates instances', () => {
     const test1 = new File.FileType(testDir.filepath('test1.txt'));
@@ -35,20 +46,23 @@ describe('FileType', () => {
   });
 });
 
-describe('File', () => {
-  it('Handles request body as stream input', async () => {
-    const res = await fetch('https://testingbot.com/free-online-tools/random-avatar/300');
-    const img = testDir.file('image.jpg');
-    if (res.body) {
-      await img.streamFrom(res.body);
-      assert(img.exists);
-    } else {
-      assert(false, 'No response body');
-    }
+describe('FileTypeJson', () => {
+  it('Saves data as json', () => {
+    const file = testDir.file('jsonfile-data').json(thing);
+    assert.deepStrictEqual(file.read(), thing);
+    file.write(thing);
+    assert.deepStrictEqual(file.read(), thing);
+  });
+
+  it('Does not create file when reading', () => {
+    const file = testDir.file('test123').json();
+    const contents = file.read();
+    assert(contents === undefined);
+    assert(!file.exists);
   });
 });
 
-describe('File.ndjson', () => {
+describe('FileTypeNdjson', () => {
   it('Appends new lines correctly', () => {
     const file = testDir.file('appends-lines').ndjson();
     file.delete();
@@ -70,23 +84,7 @@ describe('File.ndjson', () => {
   });
 });
 
-describe('File.json', () => {
-  it('Saves data as json', () => {
-    const file = testDir.file('jsonfile-data').json(thing);
-    assert.deepStrictEqual(file.read(), thing);
-    file.write(thing);
-    assert.deepStrictEqual(file.read(), thing);
-  });
-
-  it('Does not create file when reading', () => {
-    const file = testDir.file('test123').json();
-    const contents = file.read();
-    assert(contents === undefined);
-    assert(!file.exists);
-  });
-});
-
-describe('File.csv', () => {
+describe('FileTypeCsv', () => {
   it('Saves data as csv', async () => {
     const things = [thing, thing, thing];
     const file = await testDir.file('csv-data').csv(things);
@@ -95,4 +93,10 @@ describe('File.csv', () => {
       assert.deepEqual(row, thing);
     });
   });
+  it('Reads file that does not exist', async () => {
+    const file = await testDir.file('bogus').csv();
+    const contents = await file.read();
+    assert(Array.isArray(contents));
+    assert(contents.length === 0);
+  });
 });

package/src/File.ts

@@ -2,8 +2,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
-import { writeToString, parseString } from 'fast-csv';
-import { snapshot } from './snapshot.js';
+import { writeToStream, parseStream } from 'fast-csv';
+import { snapshot } from './snapshot.ts';
 
 /**
  * WARNING: API will change!
@@ -27,13 +27,28 @@ export class File {
     return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
   }
 
-  write(contents: string) {
+  /**
+   * @returns lines as strings, removes trailing '\n'
+   */
+  lines() {
+    const contents = (this.read() || '').split('\n');
+    return contents.slice(0, contents.length - 1);
+  }
+
+  get readStream() {
+    return this.exists ? fs.createReadStream(this.path) : Readable.from([]);
+  }
+
+  get writeStream() {
     fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
-    fs.writeFileSync(this.path, contents);
+    return fs.createWriteStream(this.path);
   }
 
-  async streamFrom(...options: Parameters<(typeof Readable)['from']>) {
-    return finished(Readable.from(...options).pipe(fs.createWriteStream(this.path)));
+  write(contents: string | ReadableStream) {
+    fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
+    if (typeof contents === 'string') return fs.writeFileSync(this.path, contents);
+    if (contents instanceof ReadableStream) return finished(Readable.from(contents).pipe(this.writeStream));
+    throw new Error(`Invalid content type: ${typeof contents}`);
   }
 
   /**
@@ -46,14 +61,6 @@ export class File {
     fs.appendFileSync(this.path, contents + '\n');
   }
 
-  /**
-   * @returns lines as strings, removes trailing '\n'
-   */
-  lines() {
-    const contents = (this.read() || '').split('\n');
-    return contents.slice(0, contents.length - 1);
-  }
-
   static get FileType() {
     return FileType;
   }
@@ -85,32 +92,34 @@ export class File {
   }
 }
 
-export class FileType<T = string> {
+/**
+ * A generic file adaptor, extended by specific file type implementations
+ */
+export class FileType {
   file;
 
-  constructor(filepath: string, contents?: T) {
+  constructor(filepath: string, contents?: string) {
     this.file = new File(filepath);
-    if (contents) {
-      if (typeof contents !== 'string') {
-        throw new Error('File contents must be a string');
-      }
-      this.file.write(contents);
-    }
+    if (contents) this.file.write(contents);
   }
 
   get exists() {
     return this.file.exists;
   }
 
-  delete() {
-    this.file.delete();
-  }
-
   get path() {
     return this.file.path;
   }
+
+  delete() {
+    this.file.delete();
+  }
 }
 
+/**
+ * A .json file that maintains data type when reading/writing.
+ * This is unsafe! Type is not checked at runtime, avoid using on files manipulated outside of your application.
+ */
 export class FileTypeJson<T> extends FileType {
   constructor(filepath: string, contents?: T) {
     super(filepath.endsWith('.json') ? filepath : filepath + '.json');
@@ -127,6 +136,10 @@ export class FileTypeJson<T> extends FileType {
   }
 }
 
+/**
+ * New-line delimited json file (.ndjson)
+ * @see https://jsonltools.com/ndjson-format-specification
+ */
 export class FileTypeNdjson<T extends object> extends FileType {
   constructor(filepath: string, lines?: T | T[]) {
     super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
@@ -146,6 +159,10 @@ export class FileTypeNdjson<T extends object> extends FileType {
 
 type Key<T extends object> = keyof T;
 
+/**
+ * Comma separated values (.csv).
+ * Input rows as objects, keys are used as column headers
+ */
 export class FileTypeCsv<Row extends object> extends FileType {
   constructor(filepath: string) {
     super(filepath.endsWith('.csv') ? filepath : filepath + '.csv');
@@ -162,36 +179,34 @@ export class FileTypeCsv<Row extends object> extends FileType {
     }
     const headers = Array.from(headerSet);
     const outRows = rows.map((row) => headers.map((key) => row[key]));
-    const contents = await writeToString([headers, ...outRows]);
-    this.file.write(contents);
+    return finished(writeToStream(this.file.writeStream, [headers, ...outRows]));
+  }
+
+  #parseVal(val: string) {
+    if (val.toLowerCase() === 'false') return false;
+    if (val.toLowerCase() === 'true') return true;
+    if (val.length === 0) return null;
+    if (/^[\.0-9]+$/.test(val)) return Number(val);
+    return val;
   }
 
   async read() {
     return new Promise<Row[]>((resolve, reject) => {
       const parsed: Row[] = [];
-      const content = this.file.read();
-      if (!content) return resolve(parsed);
-      function parseVal(val: string) {
-        if (val.toLowerCase() === 'false') return false;
-        if (val.toLowerCase() === 'true') return true;
-        if (val.length === 0) return null;
-        if (/^[\.0-9]+$/.test(val)) return Number(val);
-        return val;
-      }
-      parseString(content, { headers: true })
+      parseStream(this.file.readStream, { headers: true })
         .on('error', (e) => reject(e))
-        .on('end', () => resolve(parsed))
         .on('data', (raw: Record<Key<Row>, string>) => {
           parsed.push(
             Object.entries(raw).reduce(
               (all, [key, val]) => ({
                 ...all,
-                [key]: parseVal(val as string),
+                [key]: this.#parseVal(val as string),
               }),
               {} as Row,
             ),
           );
-        });
+        })
+        .on('end', () => resolve(parsed));
     });
   }
 }

package/src/Log.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Log } from './Log.js';
+import { Log } from './Log.ts';
 
 describe('Log', () => {
   it('Throws error', () => {

package/src/Log.ts

@@ -1,7 +1,7 @@
 import { inspect } from 'node:util';
 import { isObjectLike } from 'lodash-es';
 import chalk, { type ChalkInstance } from 'chalk';
-import { snapshot } from './snapshot.js';
+import { snapshot } from './snapshot.ts';
 
 type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
 

package/src/TypeWriter.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { TypeWriter } from './TypeWriter.js';
+import { TypeWriter } from './TypeWriter.ts';
 
 describe('TypeWriter', () => {
   const test = new TypeWriter('Test');

package/src/index.ts

@@ -1,8 +1,8 @@
-export { Dir, TempDir, temp } from './Dir.js';
-export { Cache } from './Cache.js';
-export { Fetcher, type Route, type Query, type FetchOptions } from './Fetcher.js';
-export { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
-export { Log } from './Log.js';
-export { snapshot } from './snapshot.js';
-export { timeout } from './timeout.js';
-export { TypeWriter } from './TypeWriter.js';
+export { Dir, TempDir, temp } from './Dir.ts';
+export { Cache } from './Cache.ts';
+export { Fetcher, type Route, type Query, type FetchOptions } from './Fetcher.ts';
+export { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.ts';
+export { Log } from './Log.ts';
+export { snapshot } from './snapshot.ts';
+export { timeout } from './timeout.ts';
+export { TypeWriter } from './TypeWriter.ts';

package/src/snapshot.test.ts

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { snapshot } from './snapshot.js';
-import { temp } from './Dir.js';
+import { snapshot } from './snapshot.ts';
+import { temp } from './Dir.ts';
 
 describe('snapshot', () => {
   it('Captures Error details', () => {

package/src/timeout.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { timeout } from './timeout.js';
+import { timeout } from './timeout.ts';
 
 describe('timeout', () => {
   it('Waits correct amount of time', async () => {

package/dist/Cache.d.ts

@@ -1,16 +0,0 @@
-import { type Duration } from 'date-fns';
-/**
- * Save data to a local file with an expiration.
- * Fresh/stale data is returned with a flag for if it's fresh or not,
- * so stale data can still be used if needed.
- */
-export declare class Cache<T> {
-    file: import("./File.js").FileTypeJson<{
-        savedAt: string;
-        data: T;
-    }>;
-    ttl: Duration;
-    constructor(key: string, ttl: number | Duration, initialData?: T);
-    write(data: T): void;
-    read(): [T | undefined, boolean];
-}

package/dist/Cache.js

@@ -1,26 +0,0 @@
-import { isAfter, add } from 'date-fns';
-import { temp } from './Dir.js';
-const cacheDir = temp.dir('cache');
-/**
- * Save data to a local file with an expiration.
- * Fresh/stale data is returned with a flag for if it's fresh or not,
- * so stale data can still be used if needed.
- */
-export class Cache {
-    file;
-    ttl;
-    constructor(key, ttl, initialData) {
-        this.file = cacheDir.file(key).json();
-        this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
-        if (initialData)
-            this.write(initialData);
-    }
-    write(data) {
-        this.file.write({ savedAt: new Date().toUTCString(), data });
-    }
-    read() {
-        const { savedAt, data } = this.file.read() || {};
-        const isFresh = Boolean(savedAt && isAfter(add(savedAt, this.ttl), new Date()));
-        return [data, isFresh];
-    }
-}

package/dist/Dir.d.ts

@@ -1,44 +0,0 @@
-import { File } from './File.js';
-/**
- * Reference to a specific directory with helpful methods for resolving filepaths,
- * sanitizing filenames, and saving files.
- */
-export declare class Dir {
-    path: string;
-    /**
-     * @param path can be relative to workspace or absolute
-     */
-    constructor(_path: string);
-    create(): void;
-    /**
-     * Create a new Dir inside the current Dir
-     * @param subPath to create in current Dir
-     * @example
-     * const folder = new Dir('example');
-     * // folder.path = './example'
-     * const child = folder.subDir('path/to/dir');
-     * // child.path = './example/path/to/dir'
-     */
-    dir(subPath: string): Dir;
-    sanitize(name: string): string;
-    /**
-     * @param base - The file name with extension
-     * @example
-     * const folder = new Dir('example');
-     * const filepath = folder.resolve('file.json');
-     * // 'example/file.json'
-     */
-    filepath(base: string): string;
-    file(base: string): File;
-}
-/**
- * Extends Dir class with method to `clear()` contents
- */
-export declare class TempDir extends Dir {
-    dir(subPath: string): TempDir;
-    clear(): void;
-}
-/**
- * Common temp dir location
- */
-export declare const temp: TempDir;

package/dist/Dir.js

@@ -1,64 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import sanitizeFilename from 'sanitize-filename';
-import { File } from './File.js';
-/**
- * Reference to a specific directory with helpful methods for resolving filepaths,
- * sanitizing filenames, and saving files.
- */
-export class Dir {
-    path;
-    /**
-     * @param path can be relative to workspace or absolute
-     */
-    constructor(_path) {
-        this.path = _path;
-    }
-    create() {
-        fs.mkdirSync(this.path, { recursive: true });
-    }
-    /**
-     * Create a new Dir inside the current Dir
-     * @param subPath to create in current Dir
-     * @example
-     * const folder = new Dir('example');
-     * // folder.path = './example'
-     * const child = folder.subDir('path/to/dir');
-     * // child.path = './example/path/to/dir'
-     */
-    dir(subPath) {
-        return new Dir(path.resolve(this.path, subPath));
-    }
-    sanitize(name) {
-        return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' }).slice(-200);
-    }
-    /**
-     * @param base - The file name with extension
-     * @example
-     * const folder = new Dir('example');
-     * const filepath = folder.resolve('file.json');
-     * // 'example/file.json'
-     */
-    filepath(base) {
-        return path.resolve(this.path, this.sanitize(base));
-    }
-    file(base) {
-        return new File(this.filepath(base));
-    }
-}
-/**
- * Extends Dir class with method to `clear()` contents
- */
-export class TempDir extends Dir {
-    dir(subPath) {
-        return new TempDir(path.resolve(this.path, subPath));
-    }
-    clear() {
-        fs.rmSync(this.path, { recursive: true, force: true });
-        this.create();
-    }
-}
-/**
- * Common temp dir location
- */
-export const temp = new TempDir('.temp');