@brianbuie/node-kit 0.6.0 → 0.8.0

package/dist/Dir.js

@@ -4,7 +4,7 @@ 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
+ * sanitizing filenames, and saving files.
  */
 export class Dir {
     path;
@@ -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/Fetcher.d.ts

@@ -12,7 +12,7 @@ export type FetchOptions = RequestInit & {
 };
 /**
  * Fetcher provides a quick way to set up a basic API connection
- * with options applied to every request
+ * with options applied to every request.
  * Includes basic methods for requesting and parsing responses
  */
 export declare class Fetcher {
@@ -40,7 +40,7 @@ export declare class Fetcher {
     };
     constructor(opts?: FetchOptions);
     /**
-     * Build URL with URLSearchParams if query is provided
+     * Build URL with URLSearchParams if query is provided.
      * Also returns domain, to help with cookies
      */
     buildUrl(route: Route, opts?: FetchOptions): [URL, string];
@@ -49,14 +49,14 @@ export declare class Fetcher {
      */
     buildHeaders(route: Route, opts?: FetchOptions): HeadersInit & Record<string, string>;
     /**
-     * Builds request, merging defaultOptions and provided options
+     * Builds request, merging defaultOptions and provided options.
      * Includes Abort signal for timeout
      */
     buildRequest(route: Route, opts?: FetchOptions): [Request, FetchOptions, string];
     /**
-     * Builds and performs the request, merging provided options with defaultOptions
-     * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body
-     * Retries on local or network error, with increasing backoff
+     * Builds and performs the request, merging provided options with defaultOptions.
+     * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body.
+     * Retries on local or network error, with increasing backoff.
      */
     fetch(route: Route, opts?: FetchOptions): Promise<[Response, Request]>;
     fetchText(route: Route, opts?: FetchOptions): Promise<[string, Response, Request]>;

package/dist/Fetcher.js

@@ -2,7 +2,7 @@ import { merge } from 'lodash-es';
 import extractDomain from 'extract-domain';
 /**
  * Fetcher provides a quick way to set up a basic API connection
- * with options applied to every request
+ * with options applied to every request.
  * Includes basic methods for requesting and parsing responses
  */
 export class Fetcher {
@@ -16,7 +16,7 @@ export class Fetcher {
         };
     }
     /**
-     * Build URL with URLSearchParams if query is provided
+     * Build URL with URLSearchParams if query is provided.
      * Also returns domain, to help with cookies
      */
     buildUrl(route, opts = {}) {
@@ -47,7 +47,7 @@ export class Fetcher {
         return headers || {};
     }
     /**
-     * Builds request, merging defaultOptions and provided options
+     * Builds request, merging defaultOptions and provided options.
      * Includes Abort signal for timeout
      */
     buildRequest(route, opts = {}) {
@@ -67,9 +67,9 @@ export class Fetcher {
         return [req, mergedOptions, domain];
     }
     /**
-     * Builds and performs the request, merging provided options with defaultOptions
-     * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body
-     * Retries on local or network error, with increasing backoff
+     * Builds and performs the request, merging provided options with defaultOptions.
+     * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body.
+     * Retries on local or network error, with increasing backoff.
      */
     async fetch(route, opts = {}) {
         const [_req, options] = this.buildRequest(route, opts);

package/dist/File.d.ts

@@ -1,4 +1,4 @@
-import * as fs from 'node:fs';
+import { Readable } from 'node:stream';
 /**
  * WARNING: API will change!
  */
@@ -6,10 +6,10 @@ 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;
+    streamFrom(...options: Parameters<(typeof Readable)['from']>): 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
@@ -19,33 +19,33 @@ export declare class File {
      * @returns lines as strings, removes trailing '\n'
      */
     lines(): string[];
-    static get Adaptor(): typeof Adaptor;
-    json<T>(contents?: T): JsonFile<T>;
-    static get json(): typeof JsonFile;
-    ndjson<T extends object>(lines?: T | T[]): NdjsonFile<T>;
-    static get ndjson(): typeof NdjsonFile;
-    csv<T extends object>(rows?: T[], keys?: (keyof T)[]): Promise<CsvFile<T>>;
-    static get csv(): typeof CsvFile;
+    static get FileType(): typeof FileType;
+    json<T>(contents?: T): FileTypeJson<T>;
+    static get json(): typeof FileTypeJson;
+    ndjson<T extends object>(lines?: T | T[]): FileTypeNdjson<T>;
+    static get ndjson(): typeof FileTypeNdjson;
+    csv<T extends object>(rows?: T[], keys?: (keyof T)[]): Promise<FileTypeCsv<T>>;
+    static get csv(): typeof FileTypeCsv;
 }
-declare class Adaptor<T = string> {
+export declare class FileType<T = string> {
     file: File;
     constructor(filepath: string, contents?: T);
     get exists(): boolean;
     delete(): void;
     get path(): string;
 }
-declare class JsonFile<T> extends Adaptor {
+export declare class FileTypeJson<T> extends FileType {
     constructor(filepath: string, contents?: T);
     read(): T | undefined;
     write(contents: T): void;
 }
-declare class NdjsonFile<T extends object> extends Adaptor {
+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;
-declare class CsvFile<Row extends object> extends Adaptor {
+export declare class FileTypeCsv<Row extends object> extends FileType {
     constructor(filepath: string);
     write(rows: Row[], keys?: Key<Row>[]): Promise<void>;
     read(): Promise<Row[]>;

package/dist/File.js

@@ -1,5 +1,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 { snapshot } from './snapshot.js';
 /**
@@ -13,9 +15,6 @@ 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 });
     }
@@ -26,6 +25,9 @@ export class File {
         fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
         fs.writeFileSync(this.path, contents);
     }
+    async streamFrom(...options) {
+        return finished(Readable.from(...options).pipe(fs.createWriteStream(this.path)));
+    }
     /**
      * 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
@@ -43,32 +45,32 @@ export class File {
         const contents = (this.read() || '').split('\n');
         return contents.slice(0, contents.length - 1);
     }
-    static get Adaptor() {
-        return Adaptor;
+    static get FileType() {
+        return FileType;
     }
     json(contents) {
-        return new JsonFile(this.path, contents);
+        return new FileTypeJson(this.path, contents);
     }
     static get json() {
-        return JsonFile;
+        return FileTypeJson;
     }
     ndjson(lines) {
-        return new NdjsonFile(this.path, lines);
+        return new FileTypeNdjson(this.path, lines);
     }
     static get ndjson() {
-        return NdjsonFile;
+        return FileTypeNdjson;
     }
     async csv(rows, keys) {
-        const csvFile = new CsvFile(this.path);
+        const csvFile = new FileTypeCsv(this.path);
         if (rows)
             await csvFile.write(rows, keys);
         return csvFile;
     }
     static get csv() {
-        return CsvFile;
+        return FileTypeCsv;
     }
 }
-class Adaptor {
+export class FileType {
     file;
     constructor(filepath, contents) {
         this.file = new File(filepath);
@@ -89,7 +91,7 @@ class Adaptor {
         return this.file.path;
     }
 }
-class JsonFile extends Adaptor {
+export class FileTypeJson extends FileType {
     constructor(filepath, contents) {
         super(filepath.endsWith('.json') ? filepath : filepath + '.json');
         if (contents)
@@ -103,7 +105,7 @@ class JsonFile extends Adaptor {
         this.file.write(JSON.stringify(snapshot(contents), null, 2));
     }
 }
-class NdjsonFile extends Adaptor {
+export class FileTypeNdjson extends FileType {
     constructor(filepath, lines) {
         super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
         if (lines)
@@ -116,7 +118,7 @@ class NdjsonFile extends Adaptor {
         return this.file.lines().map((l) => JSON.parse(l));
     }
 }
-class CsvFile extends Adaptor {
+export class FileTypeCsv extends FileType {
     constructor(filepath) {
         super(filepath.endsWith('.csv') ? filepath : filepath + '.csv');
     }

package/{src/_index.ts → dist/index.d.ts}

@@ -1,8 +1,7 @@
 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 } from './File.js';
-export { Jwt } from './Jwt.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';

package/dist/{_index.js → index.js}

@@ -1,8 +1,7 @@
 export { Dir, TempDir, temp } from './Dir.js';
 export { Cache } from './Cache.js';
 export { Fetcher } from './Fetcher.js';
-export { File } from './File.js';
-export { Jwt } from './Jwt.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';

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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",
+    "preversion": "npm test && npm run docs",
     "postversion": "git push --follow-tags"
   },
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/_index.d.ts",
-      "default": "./dist/_index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -29,17 +30,17 @@
   },
   "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",
     "typescript": "^5.9.3"
   }
 }

package/src/Cache.ts

@@ -1,27 +1,30 @@
+import { type Duration, 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<T> {
   file;
   ttl;
-  refresh;
 
-  constructor(key: string, ttl: number, refresh: () => T | Promise<T>) {
-    this.file = cacheDir.file(key).json<{ createdAt: number; value: T }>();
-    this.ttl = ttl;
-    this.refresh = refresh;
+  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.refresh();
-    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

@@ -5,7 +5,7 @@ import { File } from './File.js';
 
 /**
  * Reference to a specific directory with helpful methods for resolving filepaths,
- * sanitizing filenames, and saving files
+ * sanitizing filenames, and saving files.
  */
 export class Dir {
   path;
@@ -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/Fetcher.ts

@@ -18,7 +18,7 @@ export type FetchOptions = RequestInit & {
 
 /**
  * Fetcher provides a quick way to set up a basic API connection
- * with options applied to every request
+ * with options applied to every request.
  * Includes basic methods for requesting and parsing responses
  */
 export class Fetcher {
@@ -34,7 +34,7 @@ export class Fetcher {
   }
 
   /**
-   * Build URL with URLSearchParams if query is provided
+   * Build URL with URLSearchParams if query is provided.
    * Also returns domain, to help with cookies
    */
   buildUrl(route: Route, opts: FetchOptions = {}): [URL, string] {
@@ -65,7 +65,7 @@ export class Fetcher {
   }
 
   /**
-   * Builds request, merging defaultOptions and provided options
+   * Builds request, merging defaultOptions and provided options.
    * Includes Abort signal for timeout
    */
   buildRequest(route: Route, opts: FetchOptions = {}): [Request, FetchOptions, string] {
@@ -86,9 +86,9 @@ export class Fetcher {
   }
 
   /**
-   * Builds and performs the request, merging provided options with defaultOptions
-   * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body
-   * Retries on local or network error, with increasing backoff
+   * Builds and performs the request, merging provided options with defaultOptions.
+   * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body.
+   * Retries on local or network error, with increasing backoff.
    */
   async fetch(route: Route, opts: FetchOptions = {}): Promise<[Response, Request]> {
     const [_req, options] = this.buildRequest(route, opts);

package/src/File.test.ts

@@ -14,9 +14,9 @@ const thing = {
   e: null,
 };
 
-describe('FileAdaptor', () => {
+describe('FileType', () => {
   it('Creates instances', () => {
-    const test1 = new File.Adaptor(testDir.filepath('test1.txt'));
+    const test1 = new File.FileType(testDir.filepath('test1.txt'));
     assert(test1.file.path.includes('test1.txt'));
     const base = 'test2';
     const eg1 = new File.json(testDir.filepath(base));
@@ -35,6 +35,19 @@ describe('FileAdaptor', () => {
   });
 });
 
+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('File.ndjson', () => {
   it('Appends new lines correctly', () => {
     const file = testDir.file('appends-lines').ndjson();

package/src/File.ts

@@ -1,5 +1,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 { 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 });
   }
@@ -34,6 +32,10 @@ export class File {
     fs.writeFileSync(this.path, contents);
   }
 
+  async streamFrom(...options: Parameters<(typeof Readable)['from']>) {
+    return finished(Readable.from(...options).pipe(fs.createWriteStream(this.path)));
+  }
+
   /**
    * 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
@@ -52,38 +54,38 @@ export class File {
     return contents.slice(0, contents.length - 1);
   }
 
-  static get Adaptor() {
-    return Adaptor;
+  static get FileType() {
+    return FileType;
   }
 
   json<T>(contents?: T) {
-    return new JsonFile<T>(this.path, contents);
+    return new FileTypeJson<T>(this.path, contents);
   }
 
   static get json() {
-    return JsonFile;
+    return FileTypeJson;
   }
 
   ndjson<T extends object>(lines?: T | T[]) {
-    return new NdjsonFile<T>(this.path, lines);
+    return new FileTypeNdjson<T>(this.path, lines);
   }
 
   static get ndjson() {
-    return NdjsonFile;
+    return FileTypeNdjson;
   }
 
   async csv<T extends object>(rows?: T[], keys?: (keyof T)[]) {
-    const csvFile = new CsvFile<T>(this.path);
+    const csvFile = new FileTypeCsv<T>(this.path);
     if (rows) await csvFile.write(rows, keys);
     return csvFile;
   }
 
   static get csv() {
-    return CsvFile;
+    return FileTypeCsv;
   }
 }
 
-class Adaptor<T = string> {
+export class FileType<T = string> {
   file;
 
   constructor(filepath: string, contents?: T) {
@@ -109,7 +111,7 @@ class Adaptor<T = string> {
   }
 }
 
-class JsonFile<T> extends Adaptor {
+export class FileTypeJson<T> extends FileType {
   constructor(filepath: string, contents?: T) {
     super(filepath.endsWith('.json') ? filepath : filepath + '.json');
     if (contents) this.write(contents);
@@ -125,7 +127,7 @@ class JsonFile<T> extends Adaptor {
   }
 }
 
-class NdjsonFile<T extends object> extends Adaptor {
+export class FileTypeNdjson<T extends object> extends FileType {
   constructor(filepath: string, lines?: T | T[]) {
     super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
     if (lines) this.append(lines);
@@ -133,7 +135,7 @@ class NdjsonFile<T extends object> extends Adaptor {
 
   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,7 +146,7 @@ class NdjsonFile<T extends object> extends Adaptor {
 
 type Key<T extends object> = keyof T;
 
-class CsvFile<Row extends object> extends Adaptor {
+export class FileTypeCsv<Row extends object> extends FileType {
   constructor(filepath: string) {
     super(filepath.endsWith('.csv') ? filepath : filepath + '.csv');
   }
@@ -186,8 +188,8 @@ class CsvFile<Row extends object> extends Adaptor {
                 ...all,
                 [key]: parseVal(val as string),
               }),
-              {} as Row
-            )
+              {} as Row,
+            ),
           );
         });
     });

package/{dist/_index.d.ts → src/index.ts}

@@ -1,8 +1,7 @@
 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 } from './File.js';
-export { Jwt } from './Jwt.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';

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');
-  });
-});