@brianbuie/node-kit 0.2.5 → 0.4.0

package/.dist/Cache.d.ts

@@ -0,0 +1,20 @@
+export declare class Cache<T> {
+    file: {
+        read(): {
+            createdAt: number;
+            value: T;
+        } | undefined;
+        write(contents: {
+            createdAt: number;
+            value: T;
+        }): void;
+        file: import("./File.js").File;
+        get exists(): boolean;
+        get path(): string;
+    };
+    ttl: number;
+    refresh: () => T | Promise<T>;
+    constructor(key: string, ttl: number, refresh: () => T | Promise<T>);
+    read(): Promise<T>;
+    write(): Promise<T>;
+}

package/.dist/Cache.js

@@ -0,0 +1,23 @@
+import { temp } from './Dir.js';
+const cacheDir = temp.subDir('cache');
+export class Cache {
+    file;
+    ttl;
+    refresh;
+    constructor(key, ttl, refresh) {
+        this.file = cacheDir.file(key).json();
+        this.ttl = ttl;
+        this.refresh = refresh;
+    }
+    async read() {
+        const { createdAt, value } = this.file.read() || {};
+        if (value && createdAt && createdAt + this.ttl > Date.now())
+            return value;
+        return this.write();
+    }
+    async write() {
+        const value = await this.refresh();
+        this.file.write({ createdAt: Date.now(), value });
+        return value;
+    }
+}

package/.dist/Dir.d.ts

@@ -1,3 +1,4 @@
+import { File } from './File.js';
 /**
  * Reference to a specific directory with helpful methods for resolving filepaths,
  * sanitizing filenames, and saving files
@@ -8,7 +9,7 @@ export declare class Dir {
      * @param path can be relative to workspace or absolute
      */
     constructor(_path: string);
-    make(): void;
+    create(): void;
     /**
      * Create a new Dir inside the current Dir
      * @param subPath to create in current Dir
@@ -27,14 +28,8 @@ export declare class Dir {
      * const filepath = folder.resolve('file.json');
      * // 'example/file.json'
      */
-    resolve(base: string): string;
-    /**
-     * Save something in this Dir
-     * @param base filename with extension. `.json` will be used if base doesn't include an ext.
-     * @param contents `string`, or `any` if it's a json file
-     * @returns the filepath of the saved file
-     */
-    save(base: string, contents: any): string;
+    filepath(base: string): string;
+    file(base: string): File;
 }
 /**
  * Extends Dir class with method to `clear()` contents

package/.dist/Dir.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import sanitizeFilename from 'sanitize-filename';
-import { snapshot } from './snapshot.js';
+import { File } from './File.js';
 /**
  * Reference to a specific directory with helpful methods for resolving filepaths,
  * sanitizing filenames, and saving files
@@ -14,7 +14,7 @@ export class Dir {
     constructor(_path) {
         this.path = _path;
     }
-    make() {
+    create() {
         fs.mkdirSync(this.path, { recursive: true });
     }
     /**
@@ -39,25 +39,11 @@ export class Dir {
      * const filepath = folder.resolve('file.json');
      * // 'example/file.json'
      */
-    resolve(base) {
+    filepath(base) {
         return path.resolve(this.path, this.sanitize(base));
     }
-    /**
-     * Save something in this Dir
-     * @param base filename with extension. `.json` will be used if base doesn't include an ext.
-     * @param contents `string`, or `any` if it's a json file
-     * @returns the filepath of the saved file
-     */
-    save(base, contents) {
-        if (typeof contents !== 'string') {
-            if (!/\.json$/.test(base))
-                base += '.json';
-            contents = JSON.stringify(snapshot(contents), null, 2);
-        }
-        const filepath = this.resolve(base);
-        this.make();
-        fs.writeFileSync(filepath, contents);
-        return filepath;
+    file(base) {
+        return new File(this.filepath(base));
     }
 }
 /**
@@ -69,6 +55,7 @@ export class TempDir extends Dir {
     }
     clear() {
         fs.rmSync(this.path, { recursive: true, force: true });
+        this.create();
     }
 }
 /**

package/.dist/Fetcher.js

@@ -10,7 +10,7 @@ export class Fetcher {
     constructor(opts = {}) {
         const defaultOptions = {
             timeout: 60000,
-            retries: 3,
+            retries: 0,
             retryDelay: 3000,
         };
         this.defaultOptions = merge(defaultOptions, opts);

package/.dist/File.d.ts

@@ -0,0 +1,38 @@
+export declare class File {
+    path: string;
+    constructor(filepath: string);
+    get exists(): boolean;
+    read(): string | undefined;
+    write(contents: string): 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 Adaptor(): typeof FileAdaptor;
+    json<T>(contents?: T): JsonFile<T>;
+    static get json(): typeof JsonFile;
+    ndjson<T>(contents?: T): NdjsonFile<T>;
+    static get ndjson(): typeof NdjsonFile;
+}
+declare class FileAdaptor<T = string> {
+    file: File;
+    constructor(filepath: string, contents?: T);
+    get exists(): boolean;
+    get path(): string;
+}
+declare class JsonFile<T> extends FileAdaptor {
+    constructor(filepath: string, contents?: T);
+    read(): T | undefined;
+    write(contents: T): void;
+}
+declare class NdjsonFile<T> extends FileAdaptor {
+    constructor(filepath: string, contents?: T);
+    append(lines: T | T[]): void;
+    lines(): T[];
+}
+export {};

package/.dist/File.js

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import { snapshot } from './snapshot.js';
+export class File {
+    path;
+    constructor(filepath) {
+        this.path = filepath;
+    }
+    get exists() {
+        return fs.existsSync(this.path);
+    }
+    read() {
+        return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
+    }
+    write(contents) {
+        fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
+        fs.writeFileSync(this.path, contents);
+    }
+    /**
+     * 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) {
+        if (!this.exists)
+            this.write('');
+        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 Adaptor() {
+        return FileAdaptor;
+    }
+    json(contents) {
+        return new JsonFile(this.path, contents);
+    }
+    static get json() {
+        return JsonFile;
+    }
+    ndjson(contents) {
+        return new NdjsonFile(this.path, contents);
+    }
+    static get ndjson() {
+        return NdjsonFile;
+    }
+}
+class FileAdaptor {
+    file;
+    constructor(filepath, contents) {
+        this.file = new File(filepath);
+        if (contents) {
+            if (typeof contents !== 'string') {
+                throw new Error('File contents must be a string');
+            }
+            this.file.write(contents);
+        }
+    }
+    get exists() {
+        return this.file.exists;
+    }
+    get path() {
+        return this.file.path;
+    }
+}
+class JsonFile extends FileAdaptor {
+    constructor(filepath, contents) {
+        super(filepath.endsWith('.json') ? filepath : filepath + '.json');
+        if (contents)
+            this.write(contents);
+    }
+    read() {
+        const contents = this.file.read();
+        return contents ? JSON.parse(contents) : undefined;
+    }
+    write(contents) {
+        this.file.write(JSON.stringify(snapshot(contents), null, 2));
+    }
+}
+class NdjsonFile extends FileAdaptor {
+    constructor(filepath, contents) {
+        super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
+        if (contents)
+            this.append(contents);
+    }
+    append(lines) {
+        this.file.append(Array.isArray(lines) ? lines.map((l) => JSON.stringify(snapshot(l))) : JSON.stringify(snapshot(lines)));
+    }
+    lines() {
+        return this.file.lines().map((l) => JSON.parse(l));
+    }
+}

package/.dist/Jwt.d.ts

@@ -1,16 +1,15 @@
 import { type JwtPayload, type SignOptions } from 'jsonwebtoken';
-export declare class Jwt {
-    #private;
+type JwtConfig = {
     payload: JwtPayload;
     options: SignOptions;
     seconds: number;
     key: string;
-    constructor({ payload, options, seconds, key, }: {
-        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,35 +1,29 @@
 import { default as jsonwebtoken } from 'jsonwebtoken';
 import { merge } from 'lodash-es';
 export class Jwt {
-    payload;
-    options;
-    seconds;
-    key;
+    config;
     #saved;
-    constructor({ payload, options, seconds, key, }) {
-        this.payload = payload;
-        this.options = options;
-        this.seconds = seconds;
-        this.key = key;
+    constructor(config) {
+        this.config = config;
         this.#createToken();
     }
     get now() {
         return Math.floor(Date.now() / 1000);
     }
-    get token() {
-        if (this.#saved && this.#saved.exp > this.now) {
-            return this.#saved.token;
-        }
-        return this.#createToken();
-    }
     #createToken() {
-        const exp = this.now + this.seconds;
+        const exp = this.now + this.config.seconds;
         const payload = merge({
             iat: this.now,
             exp,
-        }, this.payload);
-        const token = jsonwebtoken.sign(payload, this.key, this.options);
+        }, 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/.dist/_index.d.ts

@@ -1,6 +1,9 @@
 export { Dir, TempDir, temp } from './Dir.js';
+export { Cache } from './Cache.js';
 export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';
+export { File } from './File.js';
 export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';
+export { timeout } from './timeout.js';
 export { TypeWriter } from './TypeWriter.js';

package/.dist/_index.js

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

package/.dist/timeout.d.ts

@@ -0,0 +1 @@
+export declare function timeout(ms: number): Promise<unknown>;

package/.dist/timeout.js

@@ -0,0 +1,5 @@
+export async function timeout(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.2.5",
+  "version": "0.4.0",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -25,9 +25,6 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@types/jsonwebtoken": "^9.0.10",
-    "@types/lodash-es": "^4.17.12",
-    "@types/node": "^24.9.1",
     "chalk": "^5.6.2",
     "extract-domain": "^5.0.2",
     "jsonwebtoken": "^9.0.2",
@@ -36,6 +33,9 @@
     "sanitize-filename": "^1.6.3"
   },
   "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^24.9.1",
     "typescript": "^5.9.3"
   }
 }

package/src/Cache.ts

@@ -0,0 +1,27 @@
+import { temp } from './Dir.js';
+
+const cacheDir = temp.subDir('cache');
+
+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;
+  }
+
+  async read() {
+    const { createdAt, value } = this.file.read() || {};
+    if (value && createdAt && createdAt + this.ttl > Date.now()) return value;
+    return this.write();
+  }
+
+  async write() {
+    const value = await this.refresh();
+    this.file.write({ createdAt: Date.now(), value });
+    return value;
+  }
+}

package/src/Dir.test.ts

@@ -3,18 +3,18 @@ import assert from 'node:assert';
 import { Dir, TempDir, temp } from './Dir.js';
 
 describe('Dir', () => {
-  const test = new Dir('test');
+  const testDir = temp.subDir('dir-test');
 
   it('Sanitizes filenames', () => {
-    const name = test.sanitize(':/something/else.json');
+    const name = testDir.sanitize(':/something/else.json');
     assert(!name.includes('/'));
     assert(!name.includes(':'));
   });
 
   it('Creates sub directories', () => {
     const subPath = 'sub/dir';
-    const sub = test.subDir(subPath);
-    assert(sub.path.includes(test.path));
+    const sub = testDir.subDir(subPath);
+    assert(sub.path.includes(testDir.path));
     assert(sub.path.includes(subPath));
   });
 
@@ -22,4 +22,10 @@ describe('Dir', () => {
     const sub = temp.subDir('example');
     assert(sub instanceof TempDir);
   });
+
+  it('Resolves filenames in folder', () => {
+    const txt = temp.filepath('test.txt');
+    assert(txt.includes(temp.path));
+    assert(txt.includes('test.txt'));
+  });
 });

package/src/Dir.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import sanitizeFilename from 'sanitize-filename';
+import { File } from './File.js';
 import { snapshot } from './snapshot.js';
 
 /**
@@ -17,7 +18,7 @@ export class Dir {
     this.path = _path;
   }
 
-  make() {
+  create() {
     fs.mkdirSync(this.path, { recursive: true });
   }
 
@@ -45,25 +46,12 @@ export class Dir {
    * const filepath = folder.resolve('file.json');
    * // 'example/file.json'
    */
-  resolve(base: string) {
+  filepath(base: string) {
     return path.resolve(this.path, this.sanitize(base));
   }
 
-  /**
-   * Save something in this Dir
-   * @param base filename with extension. `.json` will be used if base doesn't include an ext.
-   * @param contents `string`, or `any` if it's a json file
-   * @returns the filepath of the saved file
-   */
-  save(base: string, contents: any) {
-    if (typeof contents !== 'string') {
-      if (!/\.json$/.test(base)) base += '.json';
-      contents = JSON.stringify(snapshot(contents), null, 2);
-    }
-    const filepath = this.resolve(base);
-    this.make();
-    fs.writeFileSync(filepath, contents);
-    return filepath;
+  file(base: string) {
+    return new File(this.filepath(base));
   }
 }
 
@@ -77,6 +65,7 @@ export class TempDir extends Dir {
 
   clear() {
     fs.rmSync(this.path, { recursive: true, force: true });
+    this.create();
   }
 }
 

package/src/Fetcher.ts

@@ -27,7 +27,7 @@ export class Fetcher {
   constructor(opts: FetchOptions = {}) {
     const defaultOptions = {
       timeout: 60000,
-      retries: 3,
+      retries: 0,
       retryDelay: 3000,
     };
     this.defaultOptions = merge(defaultOptions, opts);

package/src/File.test.ts

@@ -0,0 +1,66 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { isEqual } from 'lodash-es';
+import { temp } from './Dir.js';
+import { File } from './File.js';
+
+const testDir = temp.subDir('file-test');
+testDir.clear();
+
+const thing = {
+  a: 'string',
+  b: 2,
+  c: true,
+  d: null,
+};
+
+describe('FileAdaptor', () => {
+  it('Instances can be created', () => {
+    const test1 = new File.Adaptor(testDir.filepath('test1.txt'));
+    assert(test1.file.path.includes('test1.txt'));
+
+    const base = 'test2';
+    const eg1 = new File.json(testDir.filepath(base));
+    const eg2 = testDir.file(base).json();
+    const eg3File = new File(testDir.filepath(base));
+    const eg3 = eg3File.json();
+    assert(eg1.path === eg2.path && eg2.path === eg3.path);
+  });
+});
+
+describe('File.ndjson', () => {
+  it('Appends new lines correctly', () => {
+    const file = testDir.file('empty-lines').ndjson();
+    file.append([thing, thing]);
+    assert(file.lines().length === 2);
+    file.append(thing);
+    assert(file.lines().length === 3);
+    file.lines().forEach((line) => {
+      assert(isEqual(line, thing));
+    });
+  });
+
+  it('Adds file extension when needed', () => {
+    const test = testDir.file('test').ndjson();
+    assert(test.path.includes(testDir.path));
+    assert(test.path.includes('.ndjson'));
+    const test2 = testDir.file('test2').ndjson();
+    assert(!test2.path.includes('.ndjson.ndjson'));
+  });
+});
+
+describe('File.json', () => {
+  it('Saves data as json', () => {
+    const file = testDir.file('jsonfile-data').json(thing);
+    assert(isEqual(file.read(), thing));
+    file.write(thing);
+    assert(isEqual(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);
+  });
+});

package/src/File.ts

@@ -0,0 +1,117 @@
+import fs from 'fs';
+import path from 'path';
+import { snapshot } from './snapshot.js';
+
+export class File {
+  path;
+
+  constructor(filepath: string) {
+    this.path = filepath;
+  }
+
+  get exists() {
+    return fs.existsSync(this.path);
+  }
+
+  read() {
+    return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
+  }
+
+  write(contents: string) {
+    fs.mkdirSync(path.parse(this.path).dir, { recursive: true });
+    fs.writeFileSync(this.path, contents);
+  }
+
+  /**
+   * 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[]) {
+    if (!this.exists) this.write('');
+    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 Adaptor() {
+    return FileAdaptor;
+  }
+
+  json<T>(contents?: T) {
+    return new JsonFile<T>(this.path, contents);
+  }
+
+  static get json() {
+    return JsonFile;
+  }
+
+  ndjson<T>(contents?: T) {
+    return new NdjsonFile<T>(this.path, contents);
+  }
+
+  static get ndjson() {
+    return NdjsonFile;
+  }
+}
+
+class FileAdaptor<T = string> {
+  file;
+
+  constructor(filepath: string, contents?: T) {
+    this.file = new File(filepath);
+    if (contents) {
+      if (typeof contents !== 'string') {
+        throw new Error('File contents must be a string');
+      }
+      this.file.write(contents);
+    }
+  }
+
+  get exists() {
+    return this.file.exists;
+  }
+
+  get path() {
+    return this.file.path;
+  }
+}
+
+class JsonFile<T> extends FileAdaptor {
+  constructor(filepath: string, contents?: T) {
+    super(filepath.endsWith('.json') ? filepath : filepath + '.json');
+    if (contents) this.write(contents);
+  }
+
+  read() {
+    const contents = this.file.read();
+    return contents ? (JSON.parse(contents) as T) : undefined;
+  }
+
+  write(contents: T) {
+    this.file.write(JSON.stringify(snapshot(contents), null, 2));
+  }
+}
+
+class NdjsonFile<T> extends FileAdaptor {
+  constructor(filepath: string, contents?: T) {
+    super(filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson');
+    if (contents) this.append(contents);
+  }
+
+  append(lines: T | T[]) {
+    this.file.append(
+      Array.isArray(lines) ? lines.map((l) => JSON.stringify(snapshot(l))) : JSON.stringify(snapshot(lines))
+    );
+  }
+
+  lines() {
+    return this.file.lines().map((l) => JSON.parse(l) as T);
+  }
+}

package/src/Jwt.ts

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

@@ -1,6 +1,9 @@
 export { Dir, TempDir, temp } from './Dir.js';
+export { Cache } from './Cache.js';
 export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';
+export { File } from './File.js';
 export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';
+export { timeout } from './timeout.js';
 export { TypeWriter } from './TypeWriter.js';

package/src/timeout.test.ts

@@ -0,0 +1,11 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { timeout } from './timeout.js';
+
+describe('timeout', () => {
+  it('Waits correct amount of time', async () => {
+    const start = Date.now();
+    await timeout(500);
+    assert(Date.now() - start >= 500);
+  });
+});

package/src/timeout.ts

@@ -0,0 +1,5 @@
+export async function timeout(ms: number) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}