@brianbuie/node-kit 0.9.0 → 0.9.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Brian Buie
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -1,28 +1,27 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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 && npm run docs",
+    "build": "tsdown && node ./node_modules/ts2md/out/src/ts2md.js --firstHeadingLevel=1",
+    "test": "tsc && node --test \"src/*.test.ts\" --quiet",
+    "preversion": "npm test && npm run build",
     "postversion": "git push --follow-tags"
   },
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "default": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
     }
   },
   "files": [
     "src",
     "dist",
-    "!dist/**/*.test.*",
     "README.md"
   ],
   "engines": {
@@ -41,6 +40,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.9.1",
     "ts2md": "^0.2.8",
+    "tsdown": "^0.16.6",
     "typescript": "^5.9.3"
   }
 }

package/src/Cache.ts

@@ -1,5 +1,5 @@
 import { type Duration, isAfter, add } from 'date-fns';
-import { temp } from './Dir.js';
+import { temp } from './Dir.ts';
 
 const cacheDir = temp.dir('cache');
 

package/src/Dir.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Dir, TempDir, temp } from './Dir.js';
+import { Dir, TempDir, temp } from './Dir.ts';
 
 describe('Dir', () => {
   const testDir = temp.dir('dir-test');

package/src/Dir.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import sanitizeFilename from 'sanitize-filename';
-import { File } from './File.js';
+import { File } from './File.ts';
 
 /**
  * Reference to a specific directory with helpful methods for resolving filepaths,

package/src/Fetcher.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Fetcher } from './Fetcher.js';
+import { Fetcher } from './Fetcher.ts';
 
 describe('Fetcher', () => {
   const statusApi = new Fetcher({ base: 'https://mock.httpstatus.io' });

package/src/File.test.ts

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { temp } from './Dir.js';
-import { File } from './File.js';
+import { temp } from './Dir.ts';
+import { File } from './File.ts';
 
 const testDir = temp.dir('file-test');
 testDir.clear();

package/src/File.ts

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { Readable } from 'node:stream';
 import { finished } from 'node:stream/promises';
 import { writeToStream, parseStream } from 'fast-csv';
-import { snapshot } from './snapshot.js';
+import { snapshot } from './snapshot.ts';
 
 /**
  * WARNING: API will change!

package/src/Log.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { Log } from './Log.js';
+import { Log } from './Log.ts';
 
 describe('Log', () => {
   it('Throws error', () => {

package/src/Log.ts

@@ -1,7 +1,7 @@
 import { inspect } from 'node:util';
 import { isObjectLike } from 'lodash-es';
 import chalk, { type ChalkInstance } from 'chalk';
-import { snapshot } from './snapshot.js';
+import { snapshot } from './snapshot.ts';
 
 type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
 

package/src/TypeWriter.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { TypeWriter } from './TypeWriter.js';
+import { TypeWriter } from './TypeWriter.ts';
 
 describe('TypeWriter', () => {
   const test = new TypeWriter('Test');

package/src/index.ts

@@ -1,8 +1,8 @@
-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, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.js';
-export { Log } from './Log.js';
-export { snapshot } from './snapshot.js';
-export { timeout } from './timeout.js';
-export { TypeWriter } from './TypeWriter.js';
+export { Dir, TempDir, temp } from './Dir.ts';
+export { Cache } from './Cache.ts';
+export { Fetcher, type Route, type Query, type FetchOptions } from './Fetcher.ts';
+export { File, FileType, FileTypeJson, FileTypeNdjson, FileTypeCsv } from './File.ts';
+export { Log } from './Log.ts';
+export { snapshot } from './snapshot.ts';
+export { timeout } from './timeout.ts';
+export { TypeWriter } from './TypeWriter.ts';

package/src/snapshot.test.ts

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { snapshot } from './snapshot.js';
-import { temp } from './Dir.js';
+import { snapshot } from './snapshot.ts';
+import { temp } from './Dir.ts';
 
 describe('snapshot', () => {
   it('Captures Error details', () => {

package/src/timeout.test.ts

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { timeout } from './timeout.js';
+import { timeout } from './timeout.ts';
 
 describe('timeout', () => {
   it('Waits correct amount of time', async () => {

package/dist/Cache.d.ts

@@ -1,16 +0,0 @@
-import { type Duration } from 'date-fns';
-/**
- * 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 declare class Cache<T> {
-    file: import("./File.js").FileTypeJson<{
-        savedAt: string;
-        data: T;
-    }>;
-    ttl: Duration;
-    constructor(key: string, ttl: number | Duration, initialData?: T);
-    write(data: T): void;
-    read(): [T | undefined, boolean];
-}

package/dist/Cache.js

@@ -1,26 +0,0 @@
-import { 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 {
-    file;
-    ttl;
-    constructor(key, ttl, initialData) {
-        this.file = cacheDir.file(key).json();
-        this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
-        if (initialData)
-            this.write(initialData);
-    }
-    write(data) {
-        this.file.write({ savedAt: new Date().toUTCString(), data });
-    }
-    read() {
-        const { savedAt, data } = this.file.read() || {};
-        const isFresh = Boolean(savedAt && isAfter(add(savedAt, this.ttl), new Date()));
-        return [data, isFresh];
-    }
-}

package/dist/Dir.d.ts

@@ -1,44 +0,0 @@
-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'
-     */
-    dir(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 {
-    dir(subPath: string): TempDir;
-    clear(): void;
-}
-/**
- * Common temp dir location
- */
-export declare const temp: TempDir;

package/dist/Dir.js

@@ -1,64 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node: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'
-     */
-    dir(subPath) {
-        return new Dir(path.resolve(this.path, subPath));
-    }
-    sanitize(name) {
-        return sanitizeFilename(name.replace('https://', '').replace('www.', ''), { replacement: '_' }).slice(-200);
-    }
-    /**
-     * @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 {
-    dir(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/Fetcher.d.ts

@@ -1,65 +0,0 @@
-export type Route = string | URL;
-type QueryVal = string | number | boolean | null | undefined;
-export type Query = Record<string, QueryVal | QueryVal[]>;
-export type FetchOptions = RequestInit & {
-    base?: string;
-    query?: Query;
-    headers?: Record<string, string>;
-    data?: any;
-    timeout?: number;
-    retries?: number;
-    retryDelay?: number;
-};
-/**
- * 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
- */
-export declare class Fetcher {
-    defaultOptions: {
-        body?: BodyInit | null;
-        cache?: RequestCache;
-        credentials?: RequestCredentials;
-        headers?: (HeadersInit & Record<string, string>) | undefined;
-        integrity?: string;
-        keepalive?: boolean;
-        method?: string;
-        mode?: RequestMode;
-        priority?: RequestPriority;
-        redirect?: RequestRedirect;
-        referrer?: string;
-        referrerPolicy?: ReferrerPolicy;
-        signal?: AbortSignal | null;
-        window?: null;
-        base?: string;
-        query?: Query;
-        data?: any;
-        timeout: number;
-        retries: number;
-        retryDelay: number;
-    };
-    constructor(opts?: FetchOptions);
-    /**
-     * Build URL with URLSearchParams if query is provided.
-     * Also returns domain, to help with cookies
-     */
-    buildUrl(route: Route, opts?: FetchOptions): [URL, string];
-    /**
-     * Merges options to get headers. Useful when extending the Fetcher class to add custom auth.
-     */
-    buildHeaders(route: Route, opts?: FetchOptions): HeadersInit & Record<string, string>;
-    /**
-     * 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.
-     */
-    fetch(route: Route, opts?: FetchOptions): Promise<[Response, Request]>;
-    fetchText(route: Route, opts?: FetchOptions): Promise<[string, Response, Request]>;
-    fetchJson<T>(route: Route, opts?: FetchOptions): Promise<[T, Response, Request]>;
-}
-export {};

package/dist/Fetcher.js

@@ -1,111 +0,0 @@
-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.
- * Includes basic methods for requesting and parsing responses
- */
-export class Fetcher {
-    defaultOptions;
-    constructor(opts = {}) {
-        this.defaultOptions = {
-            timeout: 60000,
-            retries: 0,
-            retryDelay: 3000,
-            ...opts,
-        };
-    }
-    /**
-     * Build URL with URLSearchParams if query is provided.
-     * Also returns domain, to help with cookies
-     */
-    buildUrl(route, opts = {}) {
-        const mergedOptions = merge({}, this.defaultOptions, opts);
-        const params = [];
-        Object.entries(mergedOptions.query || {}).forEach(([key, val]) => {
-            if (val === undefined)
-                return;
-            if (Array.isArray(val)) {
-                val.forEach((v) => {
-                    params.push([key, `${v}`]);
-                });
-            }
-            else {
-                params.push([key, `${val}`]);
-            }
-        });
-        const search = params.length > 0 ? '?' + new URLSearchParams(params).toString() : '';
-        const url = new URL(route + search, this.defaultOptions.base);
-        const domain = extractDomain(url.href);
-        return [url, domain];
-    }
-    /**
-     * Merges options to get headers. Useful when extending the Fetcher class to add custom auth.
-     */
-    buildHeaders(route, opts = {}) {
-        const { headers } = merge({}, this.defaultOptions, opts);
-        return headers || {};
-    }
-    /**
-     * Builds request, merging defaultOptions and provided options.
-     * Includes Abort signal for timeout
-     */
-    buildRequest(route, opts = {}) {
-        const mergedOptions = merge({}, this.defaultOptions, opts);
-        const { query, data, timeout, retries, ...init } = mergedOptions;
-        init.headers = this.buildHeaders(route, mergedOptions);
-        if (data) {
-            init.headers['content-type'] = init.headers['content-type'] || 'application/json';
-            init.method = init.method || 'POST';
-            init.body = JSON.stringify(data);
-        }
-        if (timeout) {
-            init.signal = AbortSignal.timeout(timeout);
-        }
-        const [url, domain] = this.buildUrl(route, mergedOptions);
-        const req = new Request(url, init);
-        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.
-     */
-    async fetch(route, opts = {}) {
-        const [_req, options] = this.buildRequest(route, opts);
-        const maxAttempts = (options.retries || 0) + 1;
-        let attempt = 0;
-        while (attempt < maxAttempts) {
-            attempt++;
-            const [req] = this.buildRequest(route, opts);
-            const res = await fetch(req)
-                .then((r) => {
-                if (!r.ok)
-                    throw new Error(r.statusText);
-                return r;
-            })
-                .catch(async (error) => {
-                if (attempt < maxAttempts) {
-                    const wait = attempt * 3000;
-                    console.warn(`${req.method} ${req.url} (attempt ${attempt} of ${maxAttempts})`, error);
-                    await new Promise((resolve) => setTimeout(resolve, wait));
-                }
-                else {
-                    throw new Error(error);
-                }
-            });
-            if (res)
-                return [res, req];
-        }
-        throw new Error(`Failed to fetch ${_req.url}`);
-    }
-    async fetchText(route, opts = {}) {
-        return this.fetch(route, opts).then(async ([res, req]) => {
-            const text = await res.text();
-            return [text, res, req];
-        });
-    }
-    async fetchJson(route, opts = {}) {
-        return this.fetchText(route, opts).then(([txt, res, req]) => [JSON.parse(txt), res, req]);
-    }
-}

package/dist/File.d.ts

@@ -1,71 +0,0 @@
-import * as fs from 'node:fs';
-import { Readable } from 'node:stream';
-/**
- * WARNING: API will change!
- */
-export declare class File {
-    path: string;
-    constructor(filepath: string);
-    get exists(): boolean;
-    delete(): void;
-    read(): string | undefined;
-    /**
-     * @returns lines as strings, removes trailing '\n'
-     */
-    lines(): string[];
-    get readStream(): fs.ReadStream | Readable;
-    get writeStream(): fs.WriteStream;
-    write(contents: string | ReadableStream): void | Promise<void>;
-    /**
-     * creates file if it doesn't exist, appends string or array of strings as new lines.
-     * File always ends with '\n', so contents don't need to be read before appending
-     */
-    append(lines: string | string[]): void;
-    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;
-}
-/**
- * A generic file adaptor, extended by specific file type implementations
- */
-export declare class FileType {
-    file: File;
-    constructor(filepath: string, contents?: string);
-    get exists(): boolean;
-    get path(): string;
-    delete(): void;
-}
-/**
- * A .json file that maintains data type when reading/writing.
- * This is unsafe! Type is not checked at runtime, avoid using on files manipulated outside of your application.
- */
-export declare class FileTypeJson<T> extends FileType {
-    constructor(filepath: string, contents?: T);
-    read(): T | undefined;
-    write(contents: T): void;
-}
-/**
- * New-line delimited json file (.ndjson)
- * @see https://jsonltools.com/ndjson-format-specification
- */
-export declare class FileTypeNdjson<T extends object> extends FileType {
-    constructor(filepath: string, lines?: T | T[]);
-    append(lines: T | T[]): void;
-    lines(): T[];
-}
-type Key<T extends object> = keyof T;
-/**
- * Comma separated values (.csv).
- * Input rows as objects, keys are used as column headers
- */
-export declare class FileTypeCsv<Row extends object> extends FileType {
-    #private;
-    constructor(filepath: string);
-    write(rows: Row[], keys?: Key<Row>[]): Promise<void>;
-    read(): Promise<Row[]>;
-}
-export {};