@brianbuie/node-kit 0.8.0 → 0.9.0

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/dist/File.d.ts

@@ -1,3 +1,4 @@
+import * as fs from 'node:fs';
 import { Readable } from 'node:stream';
 /**
  * WARNING: API will change!
@@ -8,17 +9,18 @@ export declare class File {
     get exists(): boolean;
     delete(): void;
     read(): string | undefined;
-    write(contents: string): void;
-    streamFrom(...options: Parameters<(typeof Readable)['from']>): Promise<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

@@ -2,7 +2,7 @@ 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 { writeToStream, parseStream } from 'fast-csv';
 import { snapshot } from './snapshot.js';
 /**
  * WARNING: API will change!
@@ -21,12 +21,27 @@ export class File {
     read() {
         return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
     }
-    write(contents) {
+    /**
+     * @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) {
-        return finished(Readable.from(...options).pipe(fs.createWriteStream(this.path)));
+    write(contents) {
+        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}`);
     }
     /**
      * creates file if it doesn't exist, appends string or array of strings as new lines.
@@ -38,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;
     }
@@ -70,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');
@@ -105,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');
@@ -118,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');
@@ -136,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "ISC",
   "repository": {
     "type": "git",

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,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,7 +2,7 @@ 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 { writeToStream, parseStream } from 'fast-csv';
 import { snapshot } from './snapshot.js';
 
 /**
@@ -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));
     });
   }
 }