@brianbuie/node-kit 0.15.0 → 0.16.0

package/src/File.ts

@@ -10,13 +10,13 @@ import { snapshot } from './snapshot.ts';
  * Represents a file on the file system. If the file doesn't exist, it is created the first time it is written to.
  */
 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) {
     this.path = this.#resolve(filepath);
@@ -29,7 +29,7 @@ export class File {
     this.type = mime.lookup(ext) || undefined;
   }
 
-  #resolve(filepath: string) {
+  #resolve(filepath: string): string {
     if (filepath[0] === '~') {
       if (process.env.HOME) {
         return path.join(process.env.HOME, filepath.slice(1));
@@ -40,7 +40,7 @@ export class File {
     return path.resolve(filepath);
   }
 
-  get exists() {
+  get exists(): boolean {
     return fs.existsSync(this.path);
   }
 
@@ -51,35 +51,35 @@ export class File {
   /**
    * Deletes the file if it exists
    */
-  delete() {
+  delete(): void {
     fs.rmSync(this.path, { force: true });
   }
 
   /**
    * @returns the contents of the file as a string, or undefined if the file doesn't exist
    */
-  read() {
+  read(): string | undefined {
     return this.exists ? fs.readFileSync(this.path, 'utf8') : undefined;
   }
 
   /**
    * @returns lines as strings, removes trailing '\n'
    */
-  lines() {
+  lines(): string[] {
     const contents = (this.read() || '').split('\n');
     return contents.at(-1)?.length ? contents : contents.slice(0, contents.length - 1);
   }
 
-  get readStream() {
+  get readStream(): fs.ReadStream | Readable {
     return this.exists ? fs.createReadStream(this.path) : Readable.from([]);
   }
 
-  get writeStream() {
+  get writeStream(): fs.WriteStream {
     fs.mkdirSync(this.dir, { recursive: true });
     return fs.createWriteStream(this.path);
   }
 
-  write(contents: string | ReadableStream) {
+  write(contents: string | ReadableStream): void | Promise<void> {
     fs.mkdirSync(this.dir, { recursive: true });
     if (typeof contents === 'string') return fs.writeFileSync(this.path, contents);
     if (contents instanceof ReadableStream) return finished(Readable.from(contents).pipe(this.writeStream));
@@ -90,7 +90,7 @@ export class File {
    * 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[]) {
+  append(lines: string | string[]): void {
     if (!this.exists) this.write('');
     const contents = Array.isArray(lines) ? lines.join('\n') : lines;
     fs.appendFileSync(this.path, contents + '\n');
@@ -106,7 +106,7 @@ export class File {
    * const file = new File('./data').json<object>({ key: 'val' }); // FileTypeJson<object>
    * file.write({ something: 'else' }) // ✅ data is typed as object
    */
-  json<T>(contents?: T) {
+  json<T>(contents?: T): FileTypeJson<T> {
     return new FileTypeJson<T>(this.path, contents);
   }
 
@@ -114,14 +114,14 @@ export class File {
    * @example
    * const file = new File.json('data.json', { key: 'val' }); // FileTypeJson<{ key: string; }>
    */
-  static get json() {
+  static get json(): typeof FileTypeJson {
     return FileTypeJson;
   }
 
   /**
    * @returns FileTypeNdjson adaptor for current File, adds '.ndjson' extension if not present.
    */
-  ndjson<T extends object>(lines?: T | T[]) {
+  ndjson<T extends object>(lines?: T | T[]): FileTypeNdjson<T> {
     return new FileTypeNdjson<T>(this.path, lines);
   }
   /**
@@ -129,7 +129,7 @@ export class File {
    * const file = new File.ndjson('log', { key: 'val' }); // FileTypeNdjson<{ key: string; }>
    * console.log(file.path) // /path/to/cwd/log.ndjson
    */
-  static get ndjson() {
+  static get ndjson(): typeof FileTypeNdjson {
     return FileTypeNdjson;
   }
 
@@ -141,13 +141,13 @@ export class File {
    * await file.write({ col: 'val' }); // ✅ Writes one row
    * await file.write([{ col: 'val2' }, { col: 'val3' }]); // ✅ Writes multiple rows
    */
-  async csv<T extends object>(rows?: T[], keys?: (keyof T)[]) {
-    const csvFile = new FileTypeCsv<T>(this.path);
-    if (rows) await csvFile.write(rows, keys);
+  async csv<T extends object>(rows?: T[], options?: FileTypeCsvOptions<T>): Promise<FileTypeCsv<T>> {
+    const csvFile = new FileTypeCsv<T>(this.path, options);
+    if (rows) await csvFile.write(rows);
     return csvFile;
   }
 
-  static get csv() {
+  static get csv(): typeof FileTypeCsv {
     return FileTypeCsv;
   }
 }
@@ -156,65 +156,65 @@ export class File {
  * A generic file adaptor, extended by specific file type implementations
  */
 export class FileType {
-  file;
+  file: File;
 
   constructor(filepath: string, contents?: string) {
     this.file = new File(filepath);
     if (contents) this.file.write(contents);
   }
 
-  get path() {
+  get path(): string {
     return this.file.path;
   }
 
-  get root() {
+  get root(): string {
     return this.file.root;
   }
 
-  get dir() {
+  get dir(): string {
     return this.file.dir;
   }
 
-  get base() {
+  get base(): string {
     return this.file.base;
   }
 
-  get name() {
+  get name(): string {
     return this.file.name;
   }
 
-  get ext() {
+  get ext(): string {
     return this.file.ext;
   }
 
-  get type() {
+  get type(): string | undefined {
     return this.file.type;
   }
 
-  get exists() {
+  get exists(): boolean {
     return this.file.exists;
   }
 
-  get stats() {
+  get stats(): Partial<fs.Stats> {
     return this.file.stats;
   }
 
-  delete() {
+  delete(): void {
     this.file.delete();
   }
 
-  get readStream() {
+  get readStream(): fs.ReadStream | Readable {
     return this.file.readStream;
   }
 
-  get writeStream() {
+  get writeStream(): fs.WriteStream {
     return this.file.writeStream;
   }
 }
 
 /**
  * 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!
  * @example
  * const file = new FileTypeJson('./data', { key: 'val' }); // FileTypeJson<{ key: string; }>
  * console.log(file.path) // '/path/to/cwd/data.json'
@@ -229,13 +229,13 @@ export class FileTypeJson<T> extends FileType {
     if (contents) this.write(contents);
   }
 
-  read() {
+  read(): T | undefined {
     const contents = this.file.read();
     return contents ? (JSON.parse(contents) as T) : undefined;
   }
 
-  write(contents: T) {
-    this.file.write(JSON.stringify(snapshot(contents), null, 2));
+  write(contents: T): void {
+    this.file.write(JSON.stringify(contents, null, 2));
   }
 }
 
@@ -249,32 +249,45 @@ export class FileTypeNdjson<T extends object> extends FileType {
     if (lines) this.append(lines);
   }
 
-  append(lines: T | T[]) {
-    this.file.append(
-      Array.isArray(lines) ? lines.map(l => JSON.stringify(snapshot(l))) : JSON.stringify(snapshot(lines)),
-    );
+  append(lines: T | T[]): void {
+    this.file.append(Array.isArray(lines) ? lines.map(l => JSON.stringify(l)) : JSON.stringify(lines));
   }
 
-  lines() {
+  lines(): T[] {
     return this.file.lines().map(l => JSON.parse(l) as T);
   }
 }
 
 type Key<T extends object> = keyof T;
 
+type FileTypeCsvOptions<Row extends object> = {
+  parseNumbers?: boolean;
+  parseBooleans?: boolean;
+  parseNulls?: boolean;
+  keys?: Key<Row>[];
+};
+
 /**
  * Comma separated values (.csv).
  * Input rows as objects, keys are used as column headers
  */
 export class FileTypeCsv<Row extends object> extends FileType {
-  constructor(filepath: string) {
+  options: FileTypeCsvOptions<Row>;
+
+  constructor(filepath: string, options: FileTypeCsvOptions<Row> = {}) {
     super(filepath.endsWith('.csv') ? filepath : filepath + '.csv');
+    this.options = {
+      parseNumbers: true,
+      parseBooleans: true,
+      parseNulls: true,
+      ...options,
+    };
   }
 
-  async write(rows: Row[], keys?: Key<Row>[]) {
+  async write(rows: Row[]): Promise<void> {
     const headerSet = new Set<Key<Row>>();
-    if (keys) {
-      for (const key of keys) headerSet.add(key);
+    if (this.options.keys) {
+      for (const key of this.options.keys) headerSet.add(key);
     } else {
       for (const row of rows) {
         for (const key in row) headerSet.add(key);
@@ -285,15 +298,16 @@ export class FileTypeCsv<Row extends object> extends FileType {
     return finished(writeToStream(this.file.writeStream, [headers, ...outRows]));
   }
 
-  #parseVal(val: string) {
-    if (val.toLowerCase() === 'false') return false;
-    if (val.toLowerCase() === 'true') return true;
-    if (val.length === 0) return null;
-    if (/^[\.0-9]+$/.test(val)) return Number(val);
+  #parseVal(val: string): string | number | boolean | null {
+    const { parseNumbers, parseBooleans, parseNulls } = this.options;
+    if (parseBooleans && val.toLowerCase() === 'false') return false;
+    if (parseBooleans && val.toLowerCase() === 'true') return true;
+    if (parseNulls && (val.length === 0 || val.toLowerCase() === 'null')) return null;
+    if (parseNumbers && /^[\.0-9]+$/.test(val)) return Number(val);
     return val;
   }
 
-  async read() {
+  async read(): Promise<Row[]> {
     return new Promise<Row[]>((resolve, reject) => {
       const parsed: Row[] = [];
       parseStream(this.file.readStream, { headers: true })

package/src/Format.ts

@@ -20,7 +20,7 @@ export class Format {
   static date(
     formatStr: 'iso' | 'ymd' | 'ymd-hm' | 'ymd-hms' | 'h:m:s' | string = 'iso',
     d: DateArg<Date> = new Date(),
-  ) {
+  ): string {
     if (formatStr === 'iso') return formatISO(d);
     if (formatStr === 'ymd') return format(d, 'yyyyMMdd');
     if (formatStr === 'ymd-hm') return format(d, 'yyyyMMdd-HHmm');
@@ -32,11 +32,11 @@ export class Format {
   /**
    * Round a number to a specific set of places
    */
-  static round(n: number, places = 0) {
+  static round(n: number, places = 0): string {
     return new Intl.NumberFormat('en-US', { maximumFractionDigits: places }).format(n);
   }
 
-  static plural(amount: number, singular: string, multiple?: string) {
+  static plural(amount: number, singular: string, multiple?: string): string {
     return amount === 1 ? `${amount} ${singular}` : `${amount} ${multiple || singular + 's'}`;
   }
 
@@ -47,7 +47,7 @@ export class Format {
    * @see details on 'digital' format https://github.com/ungoldman/format-duration
    * @see waiting on `Intl.DurationFormat({ style: 'digital' })` types https://github.com/microsoft/TypeScript/issues/60608
    */
-  static ms(ms: number, style?: 'digital') {
+  static ms(ms: number, style?: 'digital'): string {
     if (style === 'digital') return formatDuration(ms, { leading: true });
     if (ms < 1000) return `${this.round(ms)}ms`;
     const s = ms / 1000;
@@ -60,7 +60,7 @@ export class Format {
     return `${d}d ${h % 24}h`;
   }
 
-  static bytes(b: number) {
+  static bytes(b: number): string {
     const labels = ['b', 'KB', 'MB', 'GB', 'TB'];
     let factor = 0;
     while (b >= 1024 && labels[factor + 1]) {

package/src/Log.test.ts

@@ -3,13 +3,23 @@ import assert from 'node:assert';
 import { Log } from './Log.ts';
 
 describe('Log', () => {
-  it('Uses first argument as message when string', () => {
-    const result = Log.prepare('test', { something: 'else' });
-    assert(result.message === 'test');
+  function allLevels() {
+    Log.trace('trace');
+    Log.debug('debug');
+    Log.info('info');
+    Log.warn('warn');
+    try {
+      // Log.error('error', { err: new Error('error') });
+    } catch (e) {}
+    Log.fatal('fatal');
+  }
+
+  it('Logs for dev', () => {
+    allLevels();
   });
 
-  it('Uses message prop when provided', () => {
-    const result = Log.prepare({ message: 'test', something: 'else' });
-    assert(result.message === 'test');
+  it('Logs for production', () => {
+    Log.configure({ environment: 'production' });
+    allLevels();
   });
 });

package/src/Log.ts

@@ -1,126 +1,86 @@
-import { inspect } from 'node:util';
-import { isObjectLike } from 'lodash-es';
-import chalk, { type ChalkInstance } from 'chalk';
-import { snapshot } from './snapshot.ts';
-import { Format } from './Format.ts';
+import { merge } from 'lodash-es';
+import { default as pino, type Logger } from 'pino';
 
-// https://docs.cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
-type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
+export type LogDetails = Record<string, unknown>;
 
-type Options = {
-  severity: Severity;
-  color: ChalkInstance;
-};
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 
-type Entry = {
-  message?: string;
-  severity: Severity;
-  stack?: string;
-  details?: unknown[];
+export type LogOptions = pino.LoggerOptions & {
+  environment?: string;
 };
 
+/**
+ * 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
+ */
 export class Log {
-  static getStack() {
-    const details = { stack: '' };
-    // replaces details.stack with current stack trace, excluding this Log.getStack call
-    Error.captureStackTrace(details, Log.getStack);
-    // remove 'Error' on first line
-    return details.stack
-      .split('\n')
-      .map(l => l.trim())
-      .filter(l => l !== 'Error');
-  }
+  static #logger?: Logger;
+  static #options: LogOptions;
 
-  /**
-   * Gcloud parses JSON in stdout
-   */
-  static #toGcloud(entry: Entry) {
-    const details = entry.details?.length === 1 ? entry.details[0] : entry.details;
-    const output = { ...entry, details, stack: entry.stack || this.getStack() };
-    console.log(JSON.stringify(snapshot(output)));
+  static createLogger(): Logger {
+    const isProduction = this.#options?.environment === 'production' || process.env.NODE_ENV === 'production';
+    const defaultOptions: LogOptions = {
+      level: process.env.LOG_LEVEL ?? (isProduction ? 'info' : 'debug'),
+      timestamp: pino.stdTimeFunctions.isoTime,
+      formatters: {
+        level(label: string) {
+          return { level: label };
+        },
+      },
+      transport: isProduction
+        ? undefined
+        : {
+            target: 'pino-pretty',
+            options: {
+              colorize: true,
+              singleLine: true,
+              ignore: 'pid,hostname',
+            },
+          },
+    };
+    return pino(merge(defaultOptions, this.#options));
   }
 
-  /**
-   * Includes colors and better inspection for logging during dev
-   */
-  static #toConsole(entry: Entry, color: ChalkInstance) {
-    if (entry.message) console.log(color(`${Format.date('h:m:s')} [${entry.severity}] ${entry.message}`));
-    entry.details?.forEach(detail => {
-      console.log(inspect(detail, { depth: 10, breakLength: 100, compact: true, colors: true }));
-    });
+  static configure(options: LogOptions = {}): void {
+    this.#options = options;
+    this.#logger = this.createLogger();
   }
 
-  static #log({ severity, color }: Options, ...input: unknown[]) {
-    const { message, details } = this.prepare(...input);
-    const entry: Entry = { message, severity, details };
-    // https://cloud.google.com/run/docs/container-contract#env-vars
-    const isGcloud = process.env.K_SERVICE !== undefined || process.env.CLOUD_RUN_JOB !== undefined;
-    if (isGcloud) {
-      this.#toGcloud(entry);
-    } else {
-      this.#toConsole(entry, color);
-    }
-    return entry;
+  static #getLogger(): Logger {
+    return (this.#logger ??= this.createLogger());
   }
 
-  /**
-   * Handle first argument being a string or an object with a 'message' prop
-   */
-  static prepare(...input: unknown[]): { message?: string; details: unknown[] } {
-    let [firstArg, ...rest] = input;
-    // First argument is a string, use that as the message
-    if (typeof firstArg === 'string') {
-      return { message: firstArg, details: rest };
-    }
-    // First argument is an object with a `message` property
-    // @ts-ignore
-    if (isObjectLike(firstArg) && typeof firstArg['message'] === 'string') {
-      const { message, ...firstDetails } = firstArg as { message: string };
-      return { message, details: [firstDetails, ...rest] };
+  static #write(level: LogLevel, message: string, details?: LogDetails): void {
+    if (details === undefined) {
+      Log.#getLogger()[level](message);
+    } else {
+      Log.#getLogger()[level](details, message);
     }
-    // No message found, log all args as details
-    return { details: input };
   }
 
-  /**
-   * Events that require action or attention immediately
-   */
-  static alert(...input: unknown[]) {
-    return this.#log({ severity: 'ALERT', color: chalk.bgRed }, ...input);
+  static trace(message: string, details?: LogDetails): void {
+    Log.#write('trace', message, details);
   }
 
-  /**
-   * Events that cause problems
-   */
-  static error(...input: unknown[]) {
-    return this.#log({ severity: 'ERROR', color: chalk.red }, ...input);
+  static debug(message: string, details?: LogDetails): void {
+    Log.#write('debug', message, details);
   }
 
-  /**
-   * Events that might cause problems
-   */
-  static warn(...input: unknown[]) {
-    return this.#log({ severity: 'WARNING', color: chalk.yellow }, ...input);
+  static info(message: string, details?: LogDetails): void {
+    Log.#write('info', message, details);
   }
 
-  /**
-   * Normal but significant events, such as start up, shut down, or a configuration change
-   */
-  static notice(...input: unknown[]) {
-    return this.#log({ severity: 'NOTICE', color: chalk.cyan }, ...input);
+  static warn(message: string, details?: LogDetails): void {
+    Log.#write('warn', message, details);
   }
 
-  /**
-   * Routine information, such as ongoing status or performance
-   */
-  static info(...input: unknown[]) {
-    return this.#log({ severity: 'INFO', color: chalk.white }, ...input);
+  static error(message: string, details?: LogDetails): void {
+    Log.#write('error', message, details);
   }
 
-  /**
-   * Debug or trace information
-   */
-  static debug(...input: unknown[]) {
-    return this.#log({ severity: 'DEBUG', color: chalk.gray }, ...input);
+  static fatal(message: string, details?: LogDetails): void {
+    Log.#write('fatal', message, details);
   }
 }

package/src/TypeWriter.ts

@@ -2,12 +2,20 @@ import * as fs from 'node:fs';
 import { merge } from 'lodash-es';
 import * as qt from 'quicktype-core';
 
+/**
+ * Wrapper for [quicktype-core](https://github.com/glideapps/quicktype)
+ * @example
+ * 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`
+ */
 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> = {}) {
     this.moduleName = moduleName;
@@ -26,12 +34,12 @@ export class TypeWriter {
     this.qtSettings = merge(defaultSettings, qtSettings);
   }
 
-  async addMember(name: string, _samples: any[]) {
+  async addMember(name: string, _samples: any[]): Promise<void> {
     const samples = _samples.map(s => (typeof s === 'string' ? s : JSON.stringify(s)));
     await this.input.addSource({ name, samples });
   }
 
-  async toString() {
+  async toString(): Promise<string> {
     const inputData = new qt.InputData();
     inputData.addInput(this.input);
     const result = await qt.quicktype({
@@ -41,7 +49,7 @@ export class TypeWriter {
     return result.lines.join('\n');
   }
 
-  async toFile() {
+  async toFile(): Promise<void> {
     const result = await this.toString();
     fs.mkdirSync(this.outDir, { recursive: true });
     fs.writeFileSync(`${this.outDir}/${this.outFile}`, result);

package/src/snapshot.ts

@@ -1,8 +1,9 @@
 import { isObjectLike } from 'lodash-es';
 
 /**
- * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output.
- * Functions are removed
+ * @deprecated
+ * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output. Functions are removed.
+ * ⚠️ This is bad! Only use it for debugging!
  */
 export function snapshot(i: unknown, max = 50, depth = 0): any {
   if (Array.isArray(i)) {

package/src/timeout.ts

@@ -1,4 +1,4 @@
-export async function timeout(ms: number) {
+export async function timeout(ms: number): Promise<void> {
   return new Promise(resolve => {
     setTimeout(resolve, ms);
   });