@brianbuie/node-kit 0.5.2 → 0.7.0

package/README.md

@@ -4,110 +4,579 @@
 
 Basic tools for quick node.js projects
 
-## Installing
+# Installing
 
 ```
 npm add @brianbuie/node-kit
 ```
 
 ```js
-import { thing } from '@brianbuie/node-kit';
+import { Fetcher, Log } from '@brianbuie/node-kit';
 ```
 
-## Features
+# API
 
-### Fetcher
+<!--#region ts2md-api-merged-here-->
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+# Classes
+
+| |
+| --- |
+| [Cache](#class-cache) |
+| [Dir](#class-dir) |
+| [Fetcher](#class-fetcher) |
+| [File](#class-file) |
+| [FileType](#class-filetype) |
+| [FileTypeCsv](#class-filetypecsv) |
+| [FileTypeJson](#class-filetypejson) |
+| [FileTypeNdjson](#class-filetypendjson) |
+| [Jwt](#class-jwt) |
+| [Log](#class-log) |
+| [TempDir](#class-tempdir) |
+| [TypeWriter](#class-typewriter) |
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+## Class: Cache
+
+Save results of a function in a temporary file.
 
 ```ts
-import { Fetcher } from '@brianbuie/node-kit';
+export class Cache<T> {
+    file;
+    ttl;
+    getValue;
+    constructor(key: string, ttl: number, getValue: () => T | Promise<T>) 
+    async read() 
+    async write() 
+}
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
-// All requests will include Authorization header
-const api = new Fetcher({
-  base: 'https://www.example.com',
-  headers: {
-    Authorization: `Bearer ${process.env.EXAMPLE_SECRET}`,
-  },
-});
+---
+## Class: Dir
+
+Reference to a specific directory with helpful methods for resolving filepaths,
+sanitizing filenames, and saving files.
+
+```ts
+export class Dir {
+    path;
+    constructor(_path: string) 
+    create() 
+    dir(subPath: string) 
+    sanitize(name: string) 
+    filepath(base: string) 
+    file(base: string) 
+}
+```
 
-// GET https://www.example.com/route
-// returns [Response, Request]
-const [res] = await api.fetch('/route');
+<details>
 
-// GET https://www.example.com/other-route
-// returns [string, Response, Request]
-const [text] = await api.fetchText('/other-route');
+<summary>Class Dir Details</summary>
 
-// GET https://www.example.com/thing?page=1
-// returns [Thing, Response, Request]
-const [data] = await api.fetchJson<Thing>('/thing', { query: { page: 1 } });
+### Constructor
 
-// POST https://www.example.com/thing (data is sent as JSON in body)
-// returns [Thing, Response, Request]
-const [result] = await api.fetchJson<Thing>('/thing', { data: { example: 1 } });
+```ts
+constructor(_path: string) 
 ```
 
-### Jwt
+Argument Details
 
-Save a JSON Web Token in memory and reuse it throughout the process.
++ **path**
+  + can be relative to workspace or absolute
 
-```js
-import { Jwt, Fetcher } from '@brianbuie/node-kit';
+### Method dir
 
-const apiJwt = new Jwt({
-  payload: {
-    example: 'value',
-  },
-  options: {
-    algorithm: 'HS256',
-  },
-  seconds: 60,
-  key: process.env.JWT_KEY,
-});
+Create a new Dir inside the current Dir
 
-const api = new Fetcher({
-  base: 'https://example.com',
-  headers: {
-    Authorization: `Bearer ${apiJwt.token}`,
-  },
-});
+```ts
+dir(subPath: string) 
 ```
 
-> TODO: expiration is not checked again when provided in a header
+Argument Details
 
-### Log
++ **subPath**
+  + to create in current Dir
 
-Chalk output in development, structured JSON when running in gcloud
+Example
 
-```js
-import { Log } from '@brianbuie/node-kit';
+```ts
+const folder = new Dir('example');
+// folder.path = './example'
+const child = folder.subDir('path/to/dir');
+// child.path = './example/path/to/dir'
+```
+
+### Method filepath
+
+```ts
+filepath(base: string) 
+```
+
+Argument Details
 
-Log.info('message', { other: 'details' });
++ **base**
+  + The file name with extension
 
-// Print in development, or if process.env.DEBUG or --debug argument is present
-Log.debug('message', Response);
+Example
 
-// Log details and throw
-Log.error('Something happened', details, moreDetails);
+```ts
+const folder = new Dir('example');
+const filepath = folder.resolve('file.json');
+// 'example/file.json'
 ```
 
-### snapshot
+</details>
 
-Gets all enumerable and non-enumerable properties, so they can be included in JSON.stringify. Helpful for built-in objects, like Error, Request, Response, Headers, Map, etc.
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
-```js
-fs.writeFileSync('result.json', JSON.stringify(snapshot(response), null, 2));
+---
+## Class: Fetcher
+
+Fetcher provides a quick way to set up a basic API connection
+with options applied to every request.
+Includes basic methods for requesting and parsing responses
+
+```ts
+export class Fetcher {
+    defaultOptions;
+    constructor(opts: FetchOptions = {}) 
+    buildUrl(route: Route, opts: FetchOptions = {}): [
+        URL,
+        string
+    ] 
+    buildHeaders(route: Route, opts: FetchOptions = {}) 
+    buildRequest(route: Route, opts: FetchOptions = {}): [
+        Request,
+        FetchOptions,
+        string
+    ] 
+    async fetch(route: Route, opts: FetchOptions = {}): Promise<[
+        Response,
+        Request
+    ]> 
+    async fetchText(route: Route, opts: FetchOptions = {}): Promise<[
+        string,
+        Response,
+        Request
+    ]> 
+    async fetchJson<T>(route: Route, opts: FetchOptions = {}): Promise<[
+        T,
+        Response,
+        Request
+    ]> 
+}
+```
+
+See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
+
+<details>
+
+<summary>Class Fetcher Details</summary>
+
+### Method buildHeaders
+
+Merges options to get headers. Useful when extending the Fetcher class to add custom auth.
+
+```ts
+buildHeaders(route: Route, opts: FetchOptions = {}) 
+```
+See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
+
+### Method buildRequest
+
+Builds request, merging defaultOptions and provided options.
+Includes Abort signal for timeout
+
+```ts
+buildRequest(route: Route, opts: FetchOptions = {}): [
+    Request,
+    FetchOptions,
+    string
+] 
 ```
+See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
 
-## Publishing changes to this package
+### Method buildUrl
 
-Commit all changes, then run:
+Build URL with URLSearchParams if query is provided.
+Also returns domain, to help with cookies
 
+```ts
+buildUrl(route: Route, opts: FetchOptions = {}): [
+    URL,
+    string
+] 
 ```
-npm version [patch|minor|major] [-m "custom commit message"]
+See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
+
+### Method fetch
+
+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.
+
+```ts
+async fetch(route: Route, opts: FetchOptions = {}): Promise<[
+    Response,
+    Request
+]> 
 ```
+See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
+
+</details>
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: File
+
+WARNING: API will change!
+
+```ts
+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() 
+    static get FileType() 
+    json<T>(contents?: T) 
+    static get json() 
+    ndjson<T extends object>(lines?: T | T[]) 
+    static get ndjson() 
+    async csv<T extends object>(rows?: T[], keys?: (keyof T)[]) 
+    static get csv() 
+}
+```
+
+See also: [FileType](#class-filetype)
+
+<details>
+
+<summary>Class File Details</summary>
+
+### Method append
+
+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
+
+```ts
+append(lines: string | string[]) 
+```
+
+### Method lines
+
+```ts
+lines() 
+```
+
+Returns
+
+lines as strings, removes trailing '\n'
+
+</details>
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: FileType
+
+```ts
+export class FileType<T = string> {
+    file;
+    constructor(filepath: string, contents?: T) 
+    get exists() 
+    delete() 
+    get path() 
+}
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: FileTypeCsv
+
+```ts
+export class FileTypeCsv<Row extends object> extends FileType {
+    constructor(filepath: string) 
+    async write(rows: Row[], keys?: Key<Row>[]) 
+    async read() 
+}
+```
+
+See also: [FileType](#class-filetype)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: FileTypeJson
+
+```ts
+export class FileTypeJson<T> extends FileType {
+    constructor(filepath: string, contents?: T) 
+    read() 
+    write(contents: T) 
+}
+```
+
+See also: [FileType](#class-filetype)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: FileTypeNdjson
+
+```ts
+export class FileTypeNdjson<T extends object> extends FileType {
+    constructor(filepath: string, lines?: T | T[]) 
+    append(lines: T | T[]) 
+    lines() 
+}
+```
+
+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
+
+```ts
+export class Log {
+    static isTest = process.env.npm_package_name === "@brianbuie/node-kit" && process.env.npm_lifecycle_event === "test";
+    static #toGcloud(entry: Entry) 
+    static #toConsole(entry: Entry, color: ChalkInstance) 
+    static #log(options: Options, ...input: unknown[]) 
+    static prepare(...input: unknown[]): {
+        message?: string;
+        details: unknown[];
+    } 
+    static error(...input: unknown[]) 
+    static warn(...input: unknown[]) 
+    static notice(...input: unknown[]) 
+    static info(...input: unknown[]) 
+    static debug(...input: unknown[]) 
+}
+```
+
+<details>
+
+<summary>Class Log Details</summary>
+
+### Method 
+
+Gcloud parses JSON in stdout
+
+```ts
+static #toGcloud(entry: Entry) 
+```
+
+### Method 
+
+Includes colors and better inspection for logging during dev
+
+```ts
+static #toConsole(entry: Entry, color: ChalkInstance) 
+```
+
+### Method error
+
+Logs error details before throwing
+
+```ts
+static error(...input: unknown[]) 
+```
+
+### Method prepare
+
+Handle first argument being a string or an object with a 'message' prop
+Also snapshots special objects (eg Error, Response) to keep props in later JSON.stringify output
+
+```ts
+static prepare(...input: unknown[]): {
+    message?: string;
+    details: unknown[];
+} 
+```
+
+</details>
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: TempDir
+
+Extends Dir class with method to `clear()` contents
+
+```ts
+export class TempDir extends Dir {
+    dir(subPath: string) 
+    clear() 
+}
+```
+
+See also: [Dir](#class-dir)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Class: TypeWriter
+
+```ts
+export class TypeWriter {
+    moduleName;
+    input = qt.jsonInputForTargetLanguage("typescript");
+    outDir;
+    qtSettings;
+    constructor(moduleName: string, settings: {
+        outDir?: string;
+    } & Partial<qt.Options> = {}) 
+    async addMember(name: string, _samples: any[]) 
+    async toString() 
+    async toFile() 
+}
+```
+
+<details>
+
+<summary>Class TypeWriter Details</summary>
+
+### Method toString
+
+function toString() { [native code] }
+
+```ts
+async toString() 
+```
+
+</details>
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+# Functions
+
+| |
+| --- |
+| [snapshot](#function-snapshot) |
+| [timeout](#function-timeout) |
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+## Function: snapshot
+
+Allows special objects (Error, Headers, Set) to be included in JSON.stringify output
+functions are removed
+
+```ts
+export function snapshot(i: unknown, max = 50, depth = 0): any 
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Function: timeout
+
+```ts
+export async function timeout(ms: number) 
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+# Types
+
+| |
+| --- |
+| [FetchOptions](#type-fetchoptions) |
+| [Query](#type-query) |
+| [Route](#type-route) |
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+## Type: FetchOptions
+
+```ts
+export type FetchOptions = RequestInit & {
+    base?: string;
+    query?: Query;
+    headers?: Record<string, string>;
+    data?: any;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+```
+
+See also: [Query](#type-query), [timeout](#function-timeout)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Type: Query
+
+```ts
+export type Query = Record<string, QueryVal | QueryVal[]>
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Type: Route
+
+```ts
+export type Route = string | URL
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+# Variables
+
+## Variable: temp
+
+```ts
+temp = new TempDir(".temp")
+```
+
+See also: [TempDir](#class-tempdir)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
 
-- Bumps version in `package.json`
-- Runs tests (`"preversion"` script in `package.json`)
-- Creates new commit, tagged with version
-- Pushes commit and tags to github (`"postversion"` script in `package.json`)
-- The new tag will trigger github action to publish to npm (`.github/actions/publish.yml`)
+<!--#endregion ts2md-api-merged-here-->

package/dist/Cache.d.ts

@@ -1,21 +1,17 @@
+/**
+ * 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)
+ */
 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;
-        delete(): void;
-        get path(): string;
-    };
+    file: import("./File.js").FileTypeJson<{
+        createdAt: number;
+        value: T;
+    }>;
     ttl: number;
-    refresh: () => T | Promise<T>;
-    constructor(key: string, ttl: number, refresh: () => T | Promise<T>);
+    getValue: () => T | Promise<T>;
+    constructor(key: string, ttl: number, getValue: () => T | Promise<T>);
     read(): Promise<T>;
     write(): Promise<T>;
 }

package/dist/Cache.js

@@ -1,13 +1,19 @@
 import { temp } from './Dir.js';
-const cacheDir = temp.subDir('cache');
+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)
+ */
 export class Cache {
     file;
     ttl;
-    refresh;
-    constructor(key, ttl, refresh) {
+    getValue;
+    constructor(key, ttl, getValue) {
         this.file = cacheDir.file(key).json();
         this.ttl = ttl;
-        this.refresh = refresh;
+        this.getValue = getValue;
     }
     async read() {
         const { createdAt, value } = this.file.read() || {};
@@ -16,7 +22,7 @@ export class Cache {
         return this.write();
     }
     async write() {
-        const value = await this.refresh();
+        const value = await this.getValue();
         this.file.write({ createdAt: Date.now(), value });
         return value;
     }

package/dist/Dir.d.ts

@@ -1,7 +1,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 declare class Dir {
     path: string;
@@ -19,7 +19,7 @@ export declare class Dir {
      * const child = folder.subDir('path/to/dir');
      * // child.path = './example/path/to/dir'
      */
-    subDir(subPath: string): Dir;
+    dir(subPath: string): Dir;
     sanitize(name: string): string;
     /**
      * @param base - The file name with extension
@@ -35,7 +35,7 @@ export declare class Dir {
  * Extends Dir class with method to `clear()` contents
  */
 export declare class TempDir extends Dir {
-    subDir(subPath: string): TempDir;
+    dir(subPath: string): TempDir;
     clear(): void;
 }
 /**

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;
@@ -26,7 +26,7 @@ export class Dir {
      * const child = folder.subDir('path/to/dir');
      * // child.path = './example/path/to/dir'
      */
-    subDir(subPath) {
+    dir(subPath) {
         return new Dir(path.resolve(this.path, subPath));
     }
     sanitize(name) {
@@ -50,7 +50,7 @@ export class Dir {
  * Extends Dir class with method to `clear()` contents
  */
 export class TempDir extends Dir {
-    subDir(subPath) {
+    dir(subPath) {
         return new TempDir(path.resolve(this.path, subPath));
     }
     clear() {

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

@@ -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

@@ -43,32 +43,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 +89,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 +103,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 +116,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/dist/{_index.d.ts → index.d.ts}

@@ -1,7 +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 { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
 export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';

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

@@ -1,7 +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 { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
 export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.5.2",
+  "version": "0.7.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": [
@@ -40,6 +41,7 @@
     "@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,16 +1,22 @@
 import { temp } from './Dir.js';
 
-const cacheDir = temp.subDir('cache');
+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)
+ */
 export class Cache<T> {
   file;
   ttl;
-  refresh;
+  getValue;
 
-  constructor(key: string, ttl: number, refresh: () => T | Promise<T>) {
+  constructor(key: string, ttl: number, getValue: () => T | Promise<T>) {
     this.file = cacheDir.file(key).json<{ createdAt: number; value: T }>();
     this.ttl = ttl;
-    this.refresh = refresh;
+    this.getValue = getValue;
   }
 
   async read() {
@@ -20,7 +26,7 @@ export class Cache<T> {
   }
 
   async write() {
-    const value = await this.refresh();
+    const value = await this.getValue();
     this.file.write({ createdAt: Date.now(), value });
     return value;
   }

package/src/Dir.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert';
 import { Dir, TempDir, temp } from './Dir.js';
 
 describe('Dir', () => {
-  const testDir = temp.subDir('dir-test');
+  const testDir = temp.dir('dir-test');
 
   it('Sanitizes filenames', () => {
     const name = testDir.sanitize(':/something/else.json');
@@ -13,13 +13,13 @@ describe('Dir', () => {
 
   it('Creates sub directories', () => {
     const subPath = 'sub/dir';
-    const sub = testDir.subDir(subPath);
+    const sub = testDir.dir(subPath);
     assert(sub.path.includes(testDir.path));
     assert(sub.path.includes(subPath));
   });
 
-  it('TempDir.subDir returns instance of TempDir', () => {
-    const sub = temp.subDir('example');
+  it('TempDir.dir returns instance of TempDir', () => {
+    const sub = temp.dir('example');
     assert(sub instanceof TempDir);
   });
 

package/src/Dir.ts

@@ -2,11 +2,10 @@ import * as fs from 'node:fs';
 import * as path from 'node: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
+ * sanitizing filenames, and saving files.
  */
 export class Dir {
   path;
@@ -31,7 +30,7 @@ export class Dir {
    * const child = folder.subDir('path/to/dir');
    * // child.path = './example/path/to/dir'
    */
-  subDir(subPath: string) {
+  dir(subPath: string) {
     return new Dir(path.resolve(this.path, subPath));
   }
 
@@ -59,7 +58,7 @@ export class Dir {
  * Extends Dir class with method to `clear()` contents
  */
 export class TempDir extends Dir {
-  subDir(subPath: string) {
+  dir(subPath: string) {
     return new TempDir(path.resolve(this.path, subPath));
   }
 

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

@@ -3,7 +3,7 @@ import assert from 'node:assert';
 import { temp } from './Dir.js';
 import { File } from './File.js';
 
-const testDir = temp.subDir('file-test');
+const testDir = temp.dir('file-test');
 testDir.clear();
 
 const thing = {
@@ -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));

package/src/File.ts

@@ -52,38 +52,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 +109,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 +125,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);
@@ -144,7 +144,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');
   }

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

@@ -1,7 +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 { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
 export { Jwt } from './Jwt.js';
 export { Log } from './Log.js';
 export { snapshot } from './snapshot.js';