@brianbuie/node-kit 0.6.0 → 0.8.0

package/README.md

@@ -4,110 +4,563 @@
 
 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) |
+| [Log](#class-log) |
+| [TempDir](#class-tempdir) |
+| [TypeWriter](#class-typewriter) |
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+
+## Class: 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.
 
 ```ts
-import { Fetcher } from '@brianbuie/node-kit';
+export class Cache<T> {
+    file;
+    ttl;
+    constructor(key: string, ttl: number | Duration, initialData?: T) 
+    write(data: T) 
+    read(): [
+        T | undefined,
+        boolean
+    ] 
+}
+```
+
+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
 
-// GET https://www.example.com/route
-// returns [Response, Request]
-const [res] = await api.fetch('/route');
+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/other-route
-// returns [string, Response, Request]
-const [text] = await api.fetchText('/other-route');
+<details>
 
-// GET https://www.example.com/thing?page=1
-// returns [Thing, Response, Request]
-const [data] = await api.fetchJson<Thing>('/thing', { query: { page: 1 } });
+<summary>Class Dir Details</summary>
 
-// 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 } });
+### Constructor
+
+```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) 
+```
 
-Log.info('message', { other: 'details' });
+Argument Details
 
-// Print in development, or if process.env.DEBUG or --debug argument is present
-Log.debug('message', Response);
++ **base**
+  + The file name with extension
 
-// Log details and throw
-Log.error('Something happened', details, moreDetails);
+Example
+
+```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)
+
+### Method buildUrl
+
+Build URL with URLSearchParams if query is provided.
+Also returns domain, to help with cookies
+
+```ts
+buildUrl(route: Route, opts: FetchOptions = {}): [
+    URL,
+    string
+] 
+```
+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() 
+    delete() 
+    read() 
+    write(contents: string) 
+    async streamFrom(...options: Parameters<(typeof Readable)["from"]>) 
+    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: 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;
+}
 ```
 
-## Publishing changes to this package
+See also: [Query](#type-query), [timeout](#function-timeout)
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
-Commit all changes, then run:
+---
+## Type: Query
 
+```ts
+export type Query = Record<string, QueryVal | QueryVal[]>
 ```
-npm version [patch|minor|major] [-m "custom commit message"]
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Type: Route
+
+```ts
+export type Route = string | URL
 ```
 
-- 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`)
+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)
+
+---
+
+<!--#endregion ts2md-api-merged-here-->

package/dist/Cache.d.ts

@@ -1,21 +1,16 @@
+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: {
-        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;
-    };
-    ttl: number;
-    refresh: () => T | Promise<T>;
-    constructor(key: string, ttl: number, refresh: () => T | Promise<T>);
-    read(): Promise<T>;
-    write(): Promise<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,23 +1,26 @@
+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;
-    refresh;
-    constructor(key, ttl, refresh) {
+    constructor(key, ttl, initialData) {
         this.file = cacheDir.file(key).json();
-        this.ttl = ttl;
-        this.refresh = refresh;
+        this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
+        if (initialData)
+            this.write(initialData);
     }
-    async read() {
-        const { createdAt, value } = this.file.read() || {};
-        if (value && createdAt && createdAt + this.ttl > Date.now())
-            return value;
-        return this.write();
+    write(data) {
+        this.file.write({ savedAt: new Date().toUTCString(), data });
     }
-    async write() {
-        const value = await this.refresh();
-        this.file.write({ createdAt: Date.now(), value });
-        return value;
+    read() {
+        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,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;