@brianbuie/node-kit 0.15.0 → 0.16.0

package/README.md

@@ -14,7 +14,7 @@ npm add @brianbuie/node-kit
 import { Fetcher, Log } from '@brianbuie/node-kit';
 ```
 
-# Extending Config
+## Extending Config
 
 ### tsconfig.json
 
@@ -43,6 +43,34 @@ const config = {
 export default config;
 ```
 
+# Changelog
+
+## 0.16
+
+- `Log` rewritten using [pino](https://github.com/pinojs/pino) under the hood. Will require updates in projects:
+  - `message` is still first argument, but second argument should include all details, instead of using an arbitrary number of args
+  - Errors should use the `err` key in the details object, instead of passing the error as an argument
+  - Dev defaults to `debug` level, prod defaults to `info`, use `LOG_LEVEL=info` env variable
+  - Removed `alert` and `notice` levels
+  - New `fatal` level above `error`
+  - New `trace` level, below `debug`
+- `Dir.txtFiles` renamed from `Dir.textFiles`, for consistency with other file types
+- `JsonFileType` & `NdJsonFileType` no longer user the `snapshot` hack to stringify special objects. Will remove `snapshot` in the future.
+- `FileTypeCsv`
+  - Second argument changed from `keys` array to options object (`keys` can be provided as option)
+  - Automatic parsing of numbers, booleans, and nulls can be disabled (`parseNumbers`, `parseBooleans`, `parseNulls`)
+- Removed `@types/node` as peer dependency
+- Added explicit return types for everything
+
+## 0.15.1
+
+- `Dir` uses YYYYMMDD as default name
+- `File` uses YYYYMMDD-HHmmss as default name
+
+## 0.15
+
+- `TypeWriter` option for `outFile`, defaults to `[moduleName].types.ts`
+
 # API
 
 <!--#region ts2md-api-merged-here-->
@@ -77,8 +105,11 @@ so stale data can still be used if needed.
 
 ```ts
 export class Cache<T> {
-    file;
-    ttl;
+    file: FileTypeJson<{
+        savedAt: string;
+        data: T;
+    }>;
+    ttl: Duration;
     constructor(key: string, ttl: number | Duration, initialData?: T) 
     write(data: T) 
     read(): [
@@ -88,6 +119,8 @@ export class Cache<T> {
 }
 ```
 
+See also: [FileTypeJson](#class-filetypejson)
+
 Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -97,32 +130,32 @@ Reference to a specific directory with methods to create and list files.
 
 ```ts
 export class Dir {
-    #inputPath;
+    #inputPath: string;
     #resolved?: string;
-    isTemp;
-    constructor(inputPath: string, options: DirOptions = {}) 
-    get pathUnsafe() 
-    get path() 
-    get name() 
-    dir(subPath: string, options: DirOptions = { temp: this.isTemp }) 
-    tempDir(subPath: string) 
-    sanitize(filename: string) 
-    filepath(base: string) 
-    file(base: string) 
+    isTemp: boolean;
+    constructor(inputPath = Format.date("ymd"), options: DirOptions = {}) 
+    get pathUnsafe(): string 
+    get path(): string 
+    get name(): string 
+    dir(subPath = Format.date("ymd"), options: DirOptions = { temp: this.isTemp }): Dir 
+    tempDir(subPath?: string): Dir 
+    sanitize(filename: string): string 
+    filepath(base: string): string 
+    file(base = Format.date("ymd-hms")): File 
     get contents(): (Dir | File)[] 
-    get dirs() 
-    get files() 
-    get videos() 
-    get images() 
-    get jsonFiles() 
-    get ndjsonFiles() 
-    get csvFiles() 
-    get textFiles() 
-    clear() 
+    get dirs(): Dir[] 
+    get files(): File[] 
+    get videos(): File[] 
+    get images(): File[] 
+    get jsonFiles(): File[] 
+    get ndjsonFiles(): File[] 
+    get csvFiles(): File[] 
+    get txtFiles(): File[] 
+    clear(): void 
 }
 ```
 
-See also: [DirOptions](#type-diroptions), [File](#class-file), [temp](#variable-temp)
+See also: [DirOptions](#type-diroptions), [File](#class-file), [Format](#class-format), [temp](#variable-temp)
 
 <details>
 
@@ -131,9 +164,9 @@ See also: [DirOptions](#type-diroptions), [File](#class-file), [temp](#variable-
 ### Constructor
 
 ```ts
-constructor(inputPath: string, options: DirOptions = {}) 
+constructor(inputPath = Format.date("ymd"), options: DirOptions = {}) 
 ```
-See also: [DirOptions](#type-diroptions)
+See also: [DirOptions](#type-diroptions), [Format](#class-format)
 
 Argument Details
 
@@ -145,7 +178,7 @@ Argument Details
 Deletes the contents of the directory. Only allowed if created with `temp` option set to `true` (or created with `dir.tempDir` method).
 
 ```ts
-clear() 
+clear(): void 
 ```
 
 ### Method dir
@@ -153,9 +186,9 @@ clear()
 Create a new Dir inside the current Dir
 
 ```ts
-dir(subPath: string, options: DirOptions = { temp: this.isTemp }) 
+dir(subPath = Format.date("ymd"), options: DirOptions = { temp: this.isTemp }): Dir 
 ```
-See also: [DirOptions](#type-diroptions), [temp](#variable-temp)
+See also: [Dir](#class-dir), [DirOptions](#type-diroptions), [Format](#class-format), [temp](#variable-temp)
 
 Argument Details
 
@@ -175,16 +208,17 @@ const child = folder.dir('path/to/dir');
 
 ### Method file
 
-Create a new file in this directory
+Create a new file in this directory. Filename defaults to `YYYYMMDD-HHMMSS` if not provided
 
 ```ts
-file(base: string) 
+file(base = Format.date("ymd-hms")): File 
 ```
+See also: [File](#class-file), [Format](#class-format)
 
 ### Method filepath
 
 ```ts
-filepath(base: string) 
+filepath(base: string): string 
 ```
 
 Argument Details
@@ -197,7 +231,7 @@ Example
 ```ts
 const folder = new Dir('example');
 const filepath = folder.resolve('file.json');
-// 'example/file.json'
+// '/path/to/example/file.json'
 ```
 
 ### Method tempDir
@@ -205,8 +239,9 @@ const filepath = folder.resolve('file.json');
 Creates a new temp directory inside current Dir
 
 ```ts
-tempDir(subPath: string) 
+tempDir(subPath?: string): Dir 
 ```
+See also: [Dir](#class-dir)
 
 Argument Details
 
@@ -226,13 +261,13 @@ Includes basic methods for requesting and parsing responses
 
 ```ts
 export class Fetcher {
-    defaultOptions;
+    defaultOptions: FetchOptions;
     constructor(opts: FetchOptions = {}) 
     buildUrl(route: Route, opts: FetchOptions = {}): [
         URL,
         string
     ] 
-    buildHeaders(route: Route, opts: FetchOptions = {}) 
+    buildHeaders(route: Route, opts: FetchOptions = {}): HeadersInit & Record<string, string> 
     buildRequest(route: Route, opts: FetchOptions = {}): [
         Request,
         FetchOptions,
@@ -266,7 +301,7 @@ See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
 Merges options to get headers. Useful when extending the Fetcher class to add custom auth.
 
 ```ts
-buildHeaders(route: Route, opts: FetchOptions = {}) 
+buildHeaders(route: Route, opts: FetchOptions = {}): HeadersInit & Record<string, string> 
 ```
 See also: [FetchOptions](#type-fetchoptions), [Route](#type-route)
 
@@ -326,33 +361,35 @@ Represents a file on the file system. If the file doesn't exist, it is created t
 
 ```ts
 export class File {
-    path;
-    root;
-    dir;
-    base;
-    name;
-    ext;
-    type;
+    path: string;
+    root: string;
+    dir: string;
+    base: string;
+    name: string;
+    ext: string;
+    type?: string;
     constructor(filepath: string) 
-    #resolve(filepath: string) 
-    get exists() 
+    #resolve(filepath: string): string 
+    get exists(): boolean 
     get stats(): Partial<fs.Stats> 
-    delete() 
-    read() 
-    lines() 
-    get readStream() 
-    get writeStream() 
-    write(contents: string | ReadableStream) 
-    append(lines: string | string[]) 
-    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() 
+    delete(): void 
+    read(): string | undefined 
+    lines(): string[] 
+    get readStream(): fs.ReadStream | Readable 
+    get writeStream(): fs.WriteStream 
+    write(contents: string | ReadableStream): void | Promise<void> 
+    append(lines: string | string[]): void 
+    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 
+    async csv<T extends object>(rows?: T[], options?: FileTypeCsvOptions<T>): Promise<FileTypeCsv<T>> 
+    static get csv(): typeof FileTypeCsv 
 }
 ```
 
+See also: [FileTypeCsv](#class-filetypecsv), [FileTypeJson](#class-filetypejson), [FileTypeNdjson](#class-filetypendjson)
+
 <details>
 
 <summary>Class File Details</summary>
@@ -363,14 +400,15 @@ creates file if it doesn't exist, appends string or array of strings as new line
 File always ends with '\n', so contents don't need to be read before appending
 
 ```ts
-append(lines: string | string[]) 
+append(lines: string | string[]): void 
 ```
 
 ### Method csv
 
 ```ts
-async csv<T extends object>(rows?: T[], keys?: (keyof T)[]) 
+async csv<T extends object>(rows?: T[], options?: FileTypeCsvOptions<T>): Promise<FileTypeCsv<T>> 
 ```
+See also: [FileTypeCsv](#class-filetypecsv)
 
 Returns
 
@@ -390,14 +428,15 @@ await file.write([{ col: 'val2' }, { col: 'val3' }]); // ✅ Writes multiple row
 Deletes the file if it exists
 
 ```ts
-delete() 
+delete(): void 
 ```
 
 ### Method json
 
 ```ts
-json<T>(contents?: T) 
+json<T>(contents?: T): FileTypeJson<T> 
 ```
+See also: [FileTypeJson](#class-filetypejson)
 
 Returns
 
@@ -419,7 +458,7 @@ file.write({ something: 'else' }) // ✅ data is typed as object
 ### Method lines
 
 ```ts
-lines() 
+lines(): string[] 
 ```
 
 Returns
@@ -429,8 +468,9 @@ lines as strings, removes trailing '\n'
 ### Method ndjson
 
 ```ts
-ndjson<T extends object>(lines?: T | T[]) 
+ndjson<T extends object>(lines?: T | T[]): FileTypeNdjson<T> 
 ```
+See also: [FileTypeNdjson](#class-filetypendjson)
 
 Returns
 
@@ -439,7 +479,7 @@ FileTypeNdjson adaptor for current File, adds '.ndjson' extension if not present
 ### Method read
 
 ```ts
-read() 
+read(): string | undefined 
 ```
 
 Returns
@@ -457,23 +497,25 @@ A generic file adaptor, extended by specific file type implementations
 
 ```ts
 export class FileType {
-    file;
+    file: File;
     constructor(filepath: string, contents?: string) 
-    get path() 
-    get root() 
-    get dir() 
-    get base() 
-    get name() 
-    get ext() 
-    get type() 
-    get exists() 
-    get stats() 
-    delete() 
-    get readStream() 
-    get writeStream() 
+    get path(): string 
+    get root(): string 
+    get dir(): string 
+    get base(): string 
+    get name(): string 
+    get ext(): string 
+    get type(): string | undefined 
+    get exists(): boolean 
+    get stats(): Partial<fs.Stats> 
+    delete(): void 
+    get readStream(): fs.ReadStream | Readable 
+    get writeStream(): fs.WriteStream 
 }
 ```
 
+See also: [File](#class-file)
+
 Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---
@@ -484,10 +526,11 @@ Input rows as objects, keys are used as column headers
 
 ```ts
 export class FileTypeCsv<Row extends object> extends FileType {
-    constructor(filepath: string) 
-    async write(rows: Row[], keys?: Key<Row>[]) 
-    #parseVal(val: string) 
-    async read() 
+    options: FileTypeCsvOptions<Row>;
+    constructor(filepath: string, options: FileTypeCsvOptions<Row> = {}) 
+    async write(rows: Row[]): Promise<void> 
+    #parseVal(val: string): string | number | boolean | null 
+    async read(): Promise<Row[]> 
 }
 ```
 
@@ -499,7 +542,7 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ## Class: FileTypeJson
 
 A .json file that maintains data type when reading/writing.
-> ⚠️ This is mildly unsafe, important/foreign json files should be validated at runtime!
+> ⚠️ This is mildly unsafe, json files should be validated at runtime!
 
 Examples
 
@@ -517,8 +560,8 @@ file.write({ something: 'else' }) // ✅ data is typed as object
 ```ts
 export class FileTypeJson<T> extends FileType {
     constructor(filepath: string, contents?: T) 
-    read() 
-    write(contents: T) 
+    read(): T | undefined 
+    write(contents: T): void 
 }
 ```
 
@@ -534,8 +577,8 @@ New-line delimited json file (.ndjson)
 ```ts
 export class FileTypeNdjson<T extends object> extends FileType {
     constructor(filepath: string, lines?: T | T[]) 
-    append(lines: T | T[]) 
-    lines() 
+    append(lines: T | T[]): void 
+    lines(): T[] 
 }
 ```
 
@@ -550,11 +593,11 @@ Helpers for formatting dates, times, and numbers as strings
 
 ```ts
 export class Format {
-    static date(formatStr: "iso" | "ymd" | "ymd-hm" | "ymd-hms" | "h:m:s" | string = "iso", d: DateArg<Date> = new Date()) 
-    static round(n: number, places = 0) 
-    static plural(amount: number, singular: string, multiple?: string) 
-    static ms(ms: number, style?: "digital") 
-    static bytes(b: number) 
+    static date(formatStr: "iso" | "ymd" | "ymd-hm" | "ymd-hms" | "h:m:s" | string = "iso", d: DateArg<Date> = new Date()): string 
+    static round(n: number, places = 0): string 
+    static plural(amount: number, singular: string, multiple?: string): string 
+    static ms(ms: number, style?: "digital"): string 
+    static bytes(b: number): string 
 }
 ```
 
@@ -567,7 +610,7 @@ export class Format {
 date-fns format() with some shortcuts
 
 ```ts
-static date(formatStr: "iso" | "ymd" | "ymd-hm" | "ymd-hms" | "h:m:s" | string = "iso", d: DateArg<Date> = new Date()) 
+static date(formatStr: "iso" | "ymd" | "ymd-hm" | "ymd-hms" | "h:m:s" | string = "iso", d: DateArg<Date> = new Date()): string 
 ```
 
 Argument Details
@@ -592,7 +635,7 @@ Format.date('h:m:s') // '13:56:45'
 Make millisecond durations actually readable (eg "123ms", "3.56s", "1m 34s", "3h 24m", "2d 4h")
 
 ```ts
-static ms(ms: number, style?: "digital") 
+static ms(ms: number, style?: "digital"): string 
 ```
 
 Argument Details
@@ -607,7 +650,7 @@ Argument Details
 Round a number to a specific set of places
 
 ```ts
-static round(n: number, places = 0) 
+static round(n: number, places = 0): string 
 ```
 
 </details>
@@ -617,125 +660,60 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ---
 ## Class: Log
 
+Wrapper for [pino](https://github.com/pinojs/pino)
+Levels: fatal, error, warn, info, debug, trace
+Use `LOG_LEVL=info` to limit what's printed to console
+Use `Log.configure` to customize the pino instance
+
 ```ts
 export class Log {
-    static getStack() 
-    static #toGcloud(entry: Entry) 
-    static #toConsole(entry: Entry, color: ChalkInstance) 
-    static #log({ severity, color }: Options, ...input: unknown[]) 
-    static prepare(...input: unknown[]): {
-        message?: string;
-        details: unknown[];
-    } 
-    static alert(...input: unknown[]) 
-    static error(...input: unknown[]) 
-    static warn(...input: unknown[]) 
-    static notice(...input: unknown[]) 
-    static info(...input: unknown[]) 
-    static debug(...input: unknown[]) 
+    static #logger?: Logger;
+    static #options: LogOptions;
+    static createLogger(): Logger 
+    static configure(options: LogOptions = {}): void 
+    static #getLogger(): Logger 
+    static #write(level: LogLevel, message: string, details?: LogDetails): void 
+    static trace(message: string, details?: LogDetails): void 
+    static debug(message: string, details?: LogDetails): void 
+    static info(message: string, details?: LogDetails): void 
+    static warn(message: string, details?: LogDetails): void 
+    static error(message: string, details?: LogDetails): void 
+    static fatal(message: string, details?: LogDetails): void 
 }
 ```
 
-<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 alert
-
-Events that require action or attention immediately
-
-```ts
-static alert(...input: unknown[]) 
-```
-
-### Method debug
-
-Debug or trace information
-
-```ts
-static debug(...input: unknown[]) 
-```
-
-### Method error
-
-Events that cause problems
-
-```ts
-static error(...input: unknown[]) 
-```
-
-### Method info
-
-Routine information, such as ongoing status or performance
-
-```ts
-static info(...input: unknown[]) 
-```
-
-### Method notice
+See also: [LogDetails](#type-logdetails), [LogLevel](#type-loglevel), [LogOptions](#type-logoptions)
 
-Normal but significant events, such as start up, shut down, or a configuration change
-
-```ts
-static notice(...input: unknown[]) 
-```
-
-### Method prepare
-
-Handle first argument being a string or an object with a 'message' prop
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
-```ts
-static prepare(...input: unknown[]): {
-    message?: string;
-    details: unknown[];
-} 
-```
+---
+## Class: TypeWriter
 
-### Method warn
+Wrapper for [quicktype-core](https://github.com/glideapps/quicktype)
 
-Events that might cause problems
+Example
 
 ```ts
-static warn(...input: unknown[]) 
+const group = new TypeWriter('Group');
+await types.addMember('Thing', [{ a: 1 }, { a: 2, b: 1 }]);
+await types.toFile();
+// type def for `Thing` saved in `types/Group.types.ts`
 ```
 
-</details>
-
-Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
-
----
-## Class: TypeWriter
-
 ```ts
 export class TypeWriter {
-    moduleName;
+    moduleName: string;
     input = qt.jsonInputForTargetLanguage("typescript");
-    outDir;
-    outFile;
-    qtSettings;
+    outDir: string;
+    outFile: string;
+    qtSettings: Partial<qt.Options>;
     constructor(moduleName: string, settings: {
         outDir?: string;
         outFile?: string;
     } & Partial<qt.Options> = {}) 
-    async addMember(name: string, _samples: any[]) 
-    async toString() 
-    async toFile() 
+    async addMember(name: string, _samples: any[]): Promise<void> 
+    async toString(): Promise<string> 
+    async toFile(): Promise<void> 
 }
 ```
 
@@ -748,7 +726,7 @@ export class TypeWriter {
 function toString() { [native code] }
 
 ```ts
-async toString() 
+async toString(): Promise<string> 
 ```
 
 </details>
@@ -769,9 +747,6 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 
 ## 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 
 ```
@@ -782,7 +757,7 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 ## Function: timeout
 
 ```ts
-export async function timeout(ms: number) 
+export async function timeout(ms: number): Promise<void> 
 ```
 
 Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
@@ -794,6 +769,9 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 | --- |
 | [DirOptions](#type-diroptions) |
 | [FetchOptions](#type-fetchoptions) |
+| [LogDetails](#type-logdetails) |
+| [LogLevel](#type-loglevel) |
+| [LogOptions](#type-logoptions) |
 | [Query](#type-query) |
 | [Route](#type-route) |
 
@@ -832,6 +810,35 @@ See also: [Query](#type-query), [timeout](#function-timeout)
 
 Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
+---
+## Type: LogDetails
+
+```ts
+export type LogDetails = Record<string, unknown>
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Type: LogLevel
+
+```ts
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
+---
+## Type: LogOptions
+
+```ts
+export type LogOptions = pino.LoggerOptions & {
+    environment?: string;
+}
+```
+
+Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
+
 ---
 ## Type: Query
 
@@ -892,13 +899,13 @@ Links: [API](#api), [Classes](#classes), [Functions](#functions), [Types](#types
 Typecheck and run all tests from `*.test.ts` files
 
 ```
-pnpm test
+npm run test
 ```
 
 Format with Prettier, generate API docs for this Readme
 
 ```
-pnpm build
+npm run build
 ```
 
 Release a new version