@brianbuie/node-kit 0.7.0 → 0.9.0

package/README.md

@@ -32,7 +32,6 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 | [FileTypeCsv](#class-filetypecsv) |
 | [FileTypeJson](#class-filetypejson) |
 | [FileTypeNdjson](#class-filetypendjson) |
-| [Jwt](#class-jwt) |
 | [Log](#class-log) |
 | [TempDir](#class-tempdir) |
 | [TypeWriter](#class-typewriter) |
@@ -43,16 +42,20 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 
 ## Class: Cache
 
-Save results of a function in a temporary file.
+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.
 
 ```ts
 export class Cache<T> {
     file;
     ttl;
-    getValue;
-    constructor(key: string, ttl: number, getValue: () => T | Promise<T>) 
-    async read() 
-    async write() 
+    constructor(key: string, ttl: number | Duration, initialData?: T) 
+    write(data: T) 
+    read(): [
+        T | undefined,
+        boolean
+    ] 
 }
 ```
 
@@ -244,12 +247,13 @@ export class File {
     path;
     constructor(filepath: string) 
     get exists() 
-    createWriteStream(options: Parameters<typeof fs.createWriteStream>[1] = {}) 
     delete() 
     read() 
-    write(contents: string) 
-    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() 
@@ -292,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() 
 }
 ```
 
@@ -307,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() 
 }
 ```
@@ -322,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) 
@@ -337,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[]) 
@@ -349,25 +364,6 @@ See also: [FileType](#class-filetype)
 
 Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
----
-## Class: Jwt
-
-```ts
-export class Jwt {
-    config;
-    #saved?: {
-        exp: number;
-        token: string;
-    };
-    constructor(config: JwtConfig) 
-    get now() 
-    #createToken() 
-    get token() 
-}
-```
-
-Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
-
 ---
 ## Class: Log
 

package/dist/Cache.d.ts

@@ -1,17 +1,16 @@
+import { type Duration } from 'date-fns';
 /**
- * Save results of a function in a temporary file.
- * @param key A unique name for the file
- * @param ttl cache duration in ms
- * @param getValue the function to populate the cache (eg. fetch results, generate key, etc)
+ * 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<{
-        createdAt: number;
-        value: T;
+        savedAt: string;
+        data: T;
     }>;
-    ttl: number;
-    getValue: () => T | Promise<T>;
-    constructor(key: string, ttl: number, getValue: () => T | Promise<T>);
-    read(): Promise<T>;
-    write(): Promise<T>;
+    ttl: Duration;
+    constructor(key: string, ttl: number | Duration, initialData?: T);
+    write(data: T): void;
+    read(): [T | undefined, boolean];
 }

package/dist/Cache.js

@@ -1,29 +1,26 @@
+import { isAfter, add } from 'date-fns';
 import { temp } from './Dir.js';
 const cacheDir = temp.dir('cache');
 /**
- * Save results of a function in a temporary file.
- * @param key A unique name for the file
- * @param ttl cache duration in ms
- * @param getValue the function to populate the cache (eg. fetch results, generate key, etc)
+ * 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;
-    getValue;
-    constructor(key, ttl, getValue) {
+    constructor(key, ttl, initialData) {
         this.file = cacheDir.file(key).json();
-        this.ttl = ttl;
-        this.getValue = getValue;
+        this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
+        if (initialData)
+            this.write(initialData);
     }
-    async read() {
-        const { createdAt, value } = this.file.read() || {};
-        if (value && createdAt && createdAt + this.ttl > Date.now())
-            return value;
-        return this.write();
+    write(data) {
+        this.file.write({ savedAt: new Date().toUTCString(), data });
     }
-    async write() {
-        const value = await this.getValue();
-        this.file.write({ createdAt: Date.now(), value });
-        return value;
+    read() {
+        const { savedAt, data } = this.file.read() || {};
+        const isFresh = Boolean(savedAt && isAfter(add(savedAt, this.ttl), new Date()));
+        return [data, isFresh];
     }
 }

package/dist/Dir.js

@@ -30,7 +30,7 @@ export class Dir {
         return new Dir(path.resolve(this.path, subPath));
     }
     sanitize(name) {
-        return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' });
+        return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' }).slice(-200);
     }
     /**
      * @param base - The file name with extension

package/dist/File.d.ts

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs';
+import { Readable } from 'node:stream';
 /**
  * WARNING: API will change!
  */
@@ -6,19 +7,20 @@ export declare class File {
     path: string;
     constructor(filepath: string);
     get exists(): boolean;
-    createWriteStream(options?: Parameters<typeof fs.createWriteStream>[1]): fs.WriteStream;
     delete(): void;
     read(): string | undefined;
-    write(contents: string): void;
+    /**
+     * @returns lines as strings, removes trailing '\n'
+     */
+    lines(): string[];
+    get readStream(): fs.ReadStream | Readable;
+    get writeStream(): fs.WriteStream;
+    write(contents: string | ReadableStream): void | Promise<void>;
     /**
      * creates file if it doesn't exist, appends string or array of strings as new lines.
      * File always ends with '\n', so contents don't need to be read before appending
      */
     append(lines: string | string[]): void;
-    /**
-     * @returns lines as strings, removes trailing '\n'
-     */
-    lines(): string[];
     static get FileType(): typeof FileType;
     json<T>(contents?: T): FileTypeJson<T>;
     static get json(): typeof FileTypeJson;
@@ -27,25 +29,41 @@ export declare class File {
     csv<T extends object>(rows?: T[], keys?: (keyof T)[]): Promise<FileTypeCsv<T>>;
     static get csv(): typeof FileTypeCsv;
 }
-export declare class FileType<T = string> {
+/**
+ * A generic file adaptor, extended by specific file type implementations
+ */
+export declare class FileType {
     file: File;
-    constructor(filepath: string, contents?: T);
+    constructor(filepath: string, contents?: string);
     get exists(): boolean;
-    delete(): void;
     get path(): string;
+    delete(): void;
 }
+/**
+ * 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 declare class FileTypeJson<T> extends FileType {
     constructor(filepath: string, contents?: T);
     read(): T | undefined;
     write(contents: T): void;
 }
+/**
+ * New-line delimited json file (.ndjson)
+ * @see https://jsonltools.com/ndjson-format-specification
+ */
 export declare class FileTypeNdjson<T extends object> extends FileType {
     constructor(filepath: string, lines?: T | T[]);
     append(lines: T | T[]): void;
     lines(): T[];
 }
 type Key<T extends object> = keyof T;
+/**
+ * Comma separated values (.csv).
+ * Input rows as objects, keys are used as column headers
+ */
 export declare class FileTypeCsv<Row extends object> extends FileType {
+    #private;
     constructor(filepath: string);
     write(rows: Row[], keys?: Key<Row>[]): Promise<void>;
     read(): Promise<Row[]>;

package/dist/File.js

@@ -1,6 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { writeToString, parseString } from 'fast-csv';
+import { Readable } from 'node:stream';
+import { finished } from 'node:stream/promises';
+import { writeToStream, parseStream } from 'fast-csv';
 import { snapshot } from './snapshot.js';
 /**
  * WARNING: API will change!
@@ -13,18 +15,33 @@ export class File {
     get exists() {
         return fs.existsSync(this.path);
     }
-    createWriteStream(options = {}) {
-        return fs.createWriteStream(this.path, options);
-    }
     delete() {
         fs.rmSync(this.path, { force: true });
     }
     read() {
         return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
     }
+    /**
+     * @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 });
+        return fs.createWriteStream(this.path);
+    }
     write(contents) {
         fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
-        fs.writeFileSync(this.path, contents);
+        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}`);
     }
     /**
      * creates file if it doesn't exist, appends string or array of strings as new lines.
@@ -36,13 +53,6 @@ export class File {
         const contents = Array.isArray(lines) ? lines.join('\n') : lines;
         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;
     }
@@ -68,27 +78,30 @@ export class File {
         return FileTypeCsv;
     }
 }
+/**
+ * A generic file adaptor, extended by specific file type implementations
+ */
 export class FileType {
     file;
     constructor(filepath, contents) {
         this.file = new File(filepath);
-        if (contents) {
-            if (typeof contents !== 'string') {
-                throw new Error('File contents must be a string');
-            }
+        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 extends FileType {
     constructor(filepath, contents) {
         super(filepath.endsWith('.json') ? filepath : filepath + '.json');
@@ -103,6 +116,10 @@ export class FileTypeJson extends FileType {
         this.file.write(JSON.stringify(snapshot(contents), null, 2));
     }
 }
+/**
+ * New-line delimited json file (.ndjson)
+ * @see https://jsonltools.com/ndjson-format-specification
+ */
 export class FileTypeNdjson extends FileType {
     constructor(filepath, lines) {
         super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
@@ -116,6 +133,10 @@ export class FileTypeNdjson extends FileType {
         return this.file.lines().map((l) => JSON.parse(l));
     }
 }
+/**
+ * Comma separated values (.csv).
+ * Input rows as objects, keys are used as column headers
+ */
 export class FileTypeCsv extends FileType {
     constructor(filepath) {
         super(filepath.endsWith('.csv') ? filepath : filepath + '.csv');
@@ -134,35 +155,31 @@ export class FileTypeCsv 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) {
+        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((resolve, reject) => {
             const parsed = [];
-            const content = this.file.read();
-            if (!content)
-                return resolve(parsed);
-            function parseVal(val) {
-                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) => {
                 parsed.push(Object.entries(raw).reduce((all, [key, val]) => ({
                     ...all,
-                    [key]: parseVal(val),
+                    [key]: this.#parseVal(val),
                 }), {}));
-            });
+            })
+                .on('end', () => resolve(parsed));
         });
     }
 }

package/dist/index.d.ts

@@ -2,7 +2,6 @@ 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 { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';
 export { timeout } from './timeout.js';

package/dist/index.js

@@ -2,7 +2,6 @@ export { Dir, TempDir, temp } from './Dir.js';
 export { Cache } from './Cache.js';
 export { Fetcher } from './Fetcher.js';
 export { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
-export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';
 export { timeout } from './timeout.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -30,15 +30,14 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
+    "date-fns": "^4.1.0",
     "extract-domain": "^5.0.2",
     "fast-csv": "^5.0.5",
-    "jsonwebtoken": "^9.0.2",
     "lodash-es": "^4.17.21",
     "quicktype-core": "^23.2.6",
     "sanitize-filename": "^1.6.3"
   },
   "devDependencies": {
-    "@types/jsonwebtoken": "^9.0.10",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.9.1",
     "ts2md": "^0.2.8",

package/src/Cache.ts

@@ -1,33 +1,30 @@
+import { type Duration, isAfter, add } from 'date-fns';
 import { temp } from './Dir.js';
 
 const cacheDir = temp.dir('cache');
 
 /**
- * Save results of a function in a temporary file.
- * @param key A unique name for the file
- * @param ttl cache duration in ms
- * @param getValue the function to populate the cache (eg. fetch results, generate key, etc)
+ * 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<T> {
   file;
   ttl;
-  getValue;
 
-  constructor(key: string, ttl: number, getValue: () => T | Promise<T>) {
-    this.file = cacheDir.file(key).json<{ createdAt: number; value: T }>();
-    this.ttl = ttl;
-    this.getValue = getValue;
+  constructor(key: string, ttl: number | Duration, initialData?: T) {
+    this.file = cacheDir.file(key).json<{ savedAt: string; data: T }>();
+    this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
+    if (initialData) this.write(initialData);
   }
 
-  async read() {
-    const { createdAt, value } = this.file.read() || {};
-    if (value && createdAt && createdAt + this.ttl > Date.now()) return value;
-    return this.write();
+  write(data: T) {
+    this.file.write({ savedAt: new Date().toUTCString(), data });
   }
 
-  async write() {
-    const value = await this.getValue();
-    this.file.write({ createdAt: Date.now(), value });
-    return value;
+  read(): [T | undefined, boolean] {
+    const { savedAt, data } = this.file.read() || {};
+    const isFresh = Boolean(savedAt && isAfter(add(savedAt, this.ttl), new Date()));
+    return [data, isFresh];
   }
 }

package/src/Dir.ts

@@ -35,7 +35,7 @@ export class Dir {
   }
 
   sanitize(name: string) {
-    return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' });
+    return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' }).slice(-200);
   }
 
   /**

package/src/File.test.ts

@@ -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,7 +46,23 @@ describe('FileType', () => {
   });
 });
 
-describe('File.ndjson', () => {
+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('FileTypeNdjson', () => {
   it('Appends new lines correctly', () => {
     const file = testDir.file('appends-lines').ndjson();
     file.delete();
@@ -57,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);
@@ -82,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

@@ -1,6 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { writeToString, parseString } from 'fast-csv';
+import { Readable } from 'node:stream';
+import { finished } from 'node:stream/promises';
+import { writeToStream, parseStream } from 'fast-csv';
 import { snapshot } from './snapshot.js';
 
 /**
@@ -17,10 +19,6 @@ export class File {
     return fs.existsSync(this.path);
   }
 
-  createWriteStream(options: Parameters<typeof fs.createWriteStream>[1] = {}) {
-    return fs.createWriteStream(this.path, options);
-  }
-
   delete() {
     fs.rmSync(this.path, { force: true });
   }
@@ -29,9 +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);
+  }
+
+  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}`);
   }
 
   /**
@@ -44,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;
   }
@@ -83,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');
@@ -125,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');
@@ -133,7 +148,7 @@ export class FileTypeNdjson<T extends object> extends FileType {
 
   append(lines: T | T[]) {
     this.file.append(
-      Array.isArray(lines) ? lines.map((l) => JSON.stringify(snapshot(l))) : JSON.stringify(snapshot(lines))
+      Array.isArray(lines) ? lines.map((l) => JSON.stringify(snapshot(l))) : JSON.stringify(snapshot(lines)),
     );
   }
 
@@ -144,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');
@@ -160,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
-            )
+              {} as Row,
+            ),
           );
-        });
+        })
+        .on('end', () => resolve(parsed));
     });
   }
 }

package/src/index.ts

@@ -2,7 +2,6 @@ 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 { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';
 export { timeout } from './timeout.js';

package/dist/Jwt.d.ts

@@ -1,15 +0,0 @@
-import { type JwtPayload, type SignOptions } from 'jsonwebtoken';
-type JwtConfig = {
-    payload: JwtPayload;
-    options: SignOptions;
-    seconds: number;
-    key: string;
-};
-export declare class Jwt {
-    #private;
-    config: JwtConfig;
-    constructor(config: JwtConfig);
-    get now(): number;
-    get token(): string;
-}
-export {};

package/dist/Jwt.js

@@ -1,29 +0,0 @@
-import { default as jsonwebtoken } from 'jsonwebtoken';
-import { merge } from 'lodash-es';
-export class Jwt {
-    config;
-    #saved;
-    constructor(config) {
-        this.config = config;
-        this.#createToken();
-    }
-    get now() {
-        return Math.floor(Date.now() / 1000);
-    }
-    #createToken() {
-        const exp = this.now + this.config.seconds;
-        const payload = merge({
-            iat: this.now,
-            exp,
-        }, this.config.payload);
-        const token = jsonwebtoken.sign(payload, this.config.key, this.config.options);
-        this.#saved = { token, exp };
-        return token;
-    }
-    get token() {
-        if (this.#saved && this.#saved.exp > this.now) {
-            return this.#saved.token;
-        }
-        return this.#createToken();
-    }
-}

package/src/Jwt.test.ts

@@ -1,22 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert';
-import jsonwebtoken from 'jsonwebtoken';
-import { Jwt } from './Jwt.js';
-
-describe('Jwt', () => {
-  it('Creates a valid JWT', () => {
-    const key = 'test';
-    const jwt = new Jwt({
-      payload: {
-        example: 'value',
-      },
-      options: {
-        algorithm: 'HS256',
-      },
-      seconds: 60,
-      key,
-    });
-    const result = jsonwebtoken.verify(jwt.token, key);
-    assert(typeof result !== 'string' && result.example === 'value');
-  });
-});

package/src/Jwt.ts

@@ -1,47 +0,0 @@
-import { default as jsonwebtoken, type JwtPayload, type SignOptions } from 'jsonwebtoken';
-import { merge } from 'lodash-es';
-
-type JwtConfig = {
-  payload: JwtPayload;
-  options: SignOptions;
-  seconds: number;
-  key: string;
-};
-
-export class Jwt {
-  config;
-  #saved?: {
-    exp: number;
-    token: string;
-  };
-
-  constructor(config: JwtConfig) {
-    this.config = config;
-    this.#createToken();
-  }
-
-  get now() {
-    return Math.floor(Date.now() / 1000);
-  }
-
-  #createToken() {
-    const exp = this.now + this.config.seconds;
-    const payload: JwtPayload = merge(
-      {
-        iat: this.now,
-        exp,
-      },
-      this.config.payload
-    );
-    const token = jsonwebtoken.sign(payload, this.config.key, this.config.options);
-    this.#saved = { token, exp };
-    return token;
-  }
-
-  get token() {
-    if (this.#saved && this.#saved.exp > this.now) {
-      return this.#saved.token;
-    }
-    return this.#createToken();
-  }
-}