@brianbuie/node-kit 0.2.4 → 0.3.0

package/.dist/Cache.d.ts

@@ -0,0 +1,21 @@
+export declare class Cache<T> {
+    file: {
+        addExt(filepath: string): string;
+        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

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

package/.dist/Dir.js

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

package/.dist/File.d.ts

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

package/.dist/File.js

@@ -0,0 +1,103 @@
+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() {
+        return new JsonFile(this);
+    }
+    static get json() {
+        return JsonFile;
+    }
+    ndjson() {
+        return new NdjsonFile(this);
+    }
+    static get ndjson() {
+        return NdjsonFile;
+    }
+}
+class FileAdaptor {
+    file;
+    constructor(file) {
+        if (file instanceof File) {
+            const withExt = this.addExt(file.path);
+            if (withExt === file.path) {
+                this.file = file;
+            }
+            else {
+                this.file = new File(withExt);
+            }
+        }
+        else {
+            this.file = new File(this.addExt(file));
+        }
+    }
+    addExt(filepath) {
+        return filepath;
+    }
+    get exists() {
+        return this.file.exists;
+    }
+    get path() {
+        return this.file.path;
+    }
+}
+class JsonFile extends FileAdaptor {
+    addExt(filepath) {
+        return filepath.endsWith('.json') ? filepath : filepath + '.json';
+    }
+    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 {
+    addExt(filepath) {
+        return filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson';
+    }
+    lines() {
+        return this.file.lines().map((l) => JSON.parse(l));
+    }
+    append(lines) {
+        const contents = Array.isArray(lines)
+            ? lines.map((l) => JSON.stringify(snapshot(l)))
+            : JSON.stringify(snapshot(lines));
+        this.file.append(contents);
+    }
+}

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,5 +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 { snapshot } from './snapshot.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,5 +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 { snapshot } from './snapshot.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.4",
+  "version": "0.3.0",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -25,16 +25,17 @@
     "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",
     "lodash-es": "^4.17.21",
-    "quicktype-core": "^23.2.6"
+    "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",
     "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

@@ -0,0 +1,31 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { Dir, TempDir, temp } from './Dir.js';
+
+describe('Dir', () => {
+  const testDir = temp.subDir('dir-test');
+
+  it('Sanitizes filenames', () => {
+    const name = testDir.sanitize(':/something/else.json');
+    assert(!name.includes('/'));
+    assert(!name.includes(':'));
+  });
+
+  it('Creates sub directories', () => {
+    const subPath = 'sub/dir';
+    const sub = testDir.subDir(subPath);
+    assert(sub.path.includes(testDir.path));
+    assert(sub.path.includes(subPath));
+  });
+
+  it('TempDir.subDir returns instance of TempDir', () => {
+    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

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

package/src/File.test.ts

@@ -0,0 +1,67 @@
+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<typeof thing>();
+    file.write(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,123 @@
+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>() {
+    return new JsonFile<T>(this);
+  }
+
+  static get json() {
+    return JsonFile;
+  }
+
+  ndjson<T>() {
+    return new NdjsonFile<T>(this);
+  }
+
+  static get ndjson() {
+    return NdjsonFile;
+  }
+}
+
+class FileAdaptor {
+  file;
+
+  constructor(file: string | File) {
+    if (file instanceof File) {
+      const withExt = this.addExt(file.path);
+      if (withExt === file.path) {
+        this.file = file;
+      } else {
+        this.file = new File(withExt);
+      }
+    } else {
+      this.file = new File(this.addExt(file));
+    }
+  }
+
+  addExt(filepath: string) {
+    return filepath;
+  }
+
+  get exists() {
+    return this.file.exists;
+  }
+
+  get path() {
+    return this.file.path;
+  }
+}
+
+class JsonFile<T> extends FileAdaptor {
+  addExt(filepath: string) {
+    return filepath.endsWith('.json') ? filepath : filepath + '.json';
+  }
+
+  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 {
+  addExt(filepath: string) {
+    return filepath.endsWith('.ndjson') ? filepath : filepath + '.ndjson';
+  }
+
+  lines() {
+    return this.file.lines().map((l) => JSON.parse(l) as T);
+  }
+
+  append(lines: T | T[]) {
+    const contents = Array.isArray(lines)
+      ? lines.map((l) => JSON.stringify(snapshot(l)))
+      : JSON.stringify(snapshot(lines));
+    this.file.append(contents);
+  }
+}

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,5 +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 { snapshot } from './snapshot.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);
+  });
+}