@brianbuie/node-kit 0.12.4 → 0.13.0

package/src/Dir.ts

@@ -3,20 +3,28 @@ import * as path from 'node:path';
 import sanitizeFilename from 'sanitize-filename';
 import { File } from './File.ts';
 
+export type DirOptions = {
+  temp?: boolean;
+};
+
 /**
  * Reference to a specific directory with methods to create and list files.
- * Default path: '.'
- * > Created on file system the first time .path is read or any methods are used
+ * @param inputPath
+ * The path of the directory, created on file system the first time `.path` is read or any methods are used
+ * @param options
+ * include `{ temp: true }` to enable the `.clear()` method
  */
 export class Dir {
   #inputPath;
   #resolved?: string;
+  isTemp;
 
   /**
    * @param path can be relative to workspace or absolute
    */
-  constructor(inputPath = '.') {
+  constructor(inputPath: string, options: DirOptions = {}) {
     this.#inputPath = inputPath;
+    this.isTemp = Boolean(options.temp);
   }
 
   /**
@@ -32,23 +40,26 @@ export class Dir {
 
   /**
    * Create a new Dir inside the current Dir
-   * @param subPath joined with parent Dir's path to make new Dir
+   * @param subPath
+   * joined with parent Dir's path to make new Dir
+   * @param options
+   * include `{ temp: true }` to enable the `.clear()` method. If current Dir is temporary, child directories will also be temporary.
    * @example
    * const folder = new Dir('example');
    * // folder.path = '/path/to/cwd/example'
    * const child = folder.dir('path/to/dir');
    * // child.path = '/path/to/cwd/example/path/to/dir'
    */
-  dir(subPath: string) {
-    return new Dir(path.join(this.path, subPath));
+  dir(subPath: string, options: DirOptions = { temp: this.isTemp }) {
+    return new (this.constructor as typeof Dir)(path.join(this.path, subPath), options) as this;
   }
 
   /**
-   * Creates a new TempDir inside current Dir
+   * Creates a new temp directory inside current Dir
    * @param subPath joined with parent Dir's path to make new TempDir
    */
   tempDir(subPath: string) {
-    return new TempDir(path.join(this.path, subPath));
+    return this.dir(subPath, { temp: true });
   }
 
   sanitize(filename: string) {
@@ -72,29 +83,21 @@ export class Dir {
   }
 
   get files() {
-    return fs.readdirSync(this.path).map((filename) => this.file(filename));
-  }
-}
-
-/**
- * Extends Dir class with method to `clear()` contents.
- * Default path: `./.temp`
- */
-export class TempDir extends Dir {
-  constructor(inputPath = `./.temp`) {
-    super(inputPath);
+    return fs.readdirSync(this.path).map(filename => this.file(filename));
   }
 
-  /**
-   * > ⚠️ Warning! This deletes the directory!
-   */
   clear() {
+    if (!this.isTemp) throw new Error('Dir is not temporary');
     fs.rmSync(this.path, { recursive: true, force: true });
     fs.mkdirSync(this.path, { recursive: true });
   }
 }
 
 /**
- * './.temp' in current working directory
+ * Current working directory
+ */
+export const cwd = new Dir('./');
+/**
+ * ./.temp in current working directory
  */
-export const temp = new TempDir();
+export const temp = cwd.tempDir('.temp');

package/src/Fetcher.ts

@@ -43,7 +43,7 @@ export class Fetcher {
     Object.entries(mergedOptions.query || {}).forEach(([key, val]) => {
       if (val === undefined) return;
       if (Array.isArray(val)) {
-        val.forEach((v) => {
+        val.forEach(v => {
           params.push([key, `${v}`]);
         });
       } else {
@@ -98,15 +98,15 @@ export class Fetcher {
       attempt++;
       const [req] = this.buildRequest(route, opts);
       const res = await fetch(req)
-        .then((r) => {
+        .then(r => {
           if (!r.ok) throw new Error(r.statusText);
           return r;
         })
-        .catch(async (error) => {
+        .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));
+            await new Promise(resolve => setTimeout(resolve, wait));
           } else {
             throw new Error(error);
           }

package/src/File.test.ts

@@ -17,7 +17,7 @@ const thing = {
 describe('File', () => {
   it('Handles request body as stream input', async () => {
     const img = testDir.file('image.jpg');
-    await fetch('https://testingbot.com/free-online-tools/random-avatar/300').then((res) => {
+    await fetch('https://testingbot.com/free-online-tools/random-avatar/300').then(res => {
       if (!res.body) throw new Error('No response body');
       return img.write(res.body);
     });
@@ -74,7 +74,7 @@ describe('FileTypeNdjson', () => {
     assert(file.lines().length === 2);
     file.append(thing);
     assert(file.lines().length === 3);
-    file.lines().forEach((line) => {
+    file.lines().forEach(line => {
       assert.deepStrictEqual(line, thing);
     });
   });
@@ -93,7 +93,7 @@ describe('FileTypeCsv', () => {
     const things = [thing, thing, thing];
     const file = await testDir.file('csv-data').csv(things);
     const parsed = await file.read();
-    parsed.forEach((row) => {
+    parsed.forEach(row => {
       assert.deepEqual(row, thing);
     });
   });

package/src/Format.ts

@@ -1,4 +1,5 @@
-import { format, formatISO, type DateArg } from 'date-fns';
+import { format, formatISO, type DateArg, type Duration } from 'date-fns';
+import formatDuration from 'format-duration';
 
 /**
  * Helpers for formatting dates, times, and numbers as strings
@@ -6,12 +7,25 @@ import { format, formatISO, type DateArg } from 'date-fns';
 export class Format {
   /**
    * date-fns format() with some shortcuts
-   * @param formatStr
-   * 'iso' to get ISO date, 'ymd' to format as 'yyyy-MM-dd', full options: https://date-fns.org/v4.1.0/docs/format
+   * @param formatStr the format to use
+   * @param date the date to format, default `new Date()`
+   * @example
+   * Format.date('iso') // '2026-04-08T13:56:45Z'
+   * Format.date('ymd') // '20260408'
+   * Format.date('ymd-hm') // '20260408-1356'
+   * Format.date('ymd-hms') // '20260408-135645'
+   * Format.date('h:m:s') // '13:56:45'
+   * @see more format options https://date-fns.org/v4.1.0/docs/format
    */
-  static date(formatStr: 'iso' | 'ymd' | 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(),
+  ) {
     if (formatStr === 'iso') return formatISO(d);
-    if (formatStr === 'ymd') return format(d, 'yyyy-MM-dd');
+    if (formatStr === 'ymd') return format(d, 'yyyyMMdd');
+    if (formatStr === 'ymd-hm') return format(d, 'yyyyMMdd-HHmm');
+    if (formatStr === 'ymd-hms') return format(d, 'yyyyMMdd-HHmmss');
+    if (formatStr === 'h:m:s') return format(d, 'HH:mm:ss');
     return format(d, formatStr);
   }
 
@@ -22,10 +36,19 @@ export class Format {
     return new Intl.NumberFormat('en-US', { maximumFractionDigits: places }).format(n);
   }
 
+  static plural(amount: number, singular: string, multiple?: string) {
+    return amount === 1 ? `${amount} ${singular}` : `${amount} ${multiple || singular + 's'}`;
+  }
+
   /**
    * Make millisecond durations actually readable (eg "123ms", "3.56s", "1m 34s", "3h 24m", "2d 4h")
+   * @param ms milliseconds
+   * @param style 'digital' to output as 'HH:MM:SS'
+   * @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) {
+  static ms(ms: number, style?: 'digital') {
+    if (style === 'digital') return formatDuration(ms, { leading: true });
     if (ms < 1000) return `${this.round(ms)}ms`;
     const s = ms / 1000;
     if (s < 60) return `${this.round(s, 2)}s`;

package/src/Log.test.ts

@@ -3,19 +3,6 @@ import assert from 'node:assert';
 import { Log } from './Log.ts';
 
 describe('Log', () => {
-  it('Throws error', () => {
-    try {
-      Log.error('Test error');
-    } catch (e) {
-      return;
-    }
-    assert(false, 'Did not throw error');
-  });
-
-  it('Recognizes this is a test', () => {
-    assert(Log.isTest);
-  });
-
   it('Uses first argument as message when string', () => {
     const result = Log.prepare('test', { something: 'else' });
     assert(result.message === 'test');

package/src/Log.ts

@@ -2,7 +2,9 @@ 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';
 
+// https://docs.cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
 type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
 
 type Options = {
@@ -13,89 +15,112 @@ type Options = {
 type Entry = {
   message?: string;
   severity: Severity;
+  stack?: string;
   details?: unknown[];
 };
 
 export class Log {
-  // Only silence logs when THIS package is running its own tests
-  static isTest = process.env.npm_package_name === '@brianbuie/node-kit' && process.env.npm_lifecycle_event === 'test';
+  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');
+  }
 
   /**
    * Gcloud parses JSON in stdout
    */
   static #toGcloud(entry: Entry) {
-    if (entry.details?.length === 1) {
-      console.log(JSON.stringify(snapshot({ ...entry, details: entry.details[0] })));
-    } else {
-      console.log(JSON.stringify(snapshot(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)));
   }
 
   /**
    * Includes colors and better inspection for logging during dev
    */
   static #toConsole(entry: Entry, color: ChalkInstance) {
-    if (entry.message) console.log(color(`[${entry.severity}] ${entry.message}`));
-    entry.details?.forEach((detail) => {
+    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 #log(options: Options, ...input: unknown[]) {
+  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({ message, severity: options.severity, details });
-      return { message, details, options };
-    }
-    // Hide output while testing this package
-    if (!this.isTest) {
-      this.#toConsole({ message, severity: options.severity, details }, options.color);
+      this.#toGcloud(entry);
+    } else {
+      this.#toConsole(entry, color);
     }
-    return { message, details, options };
+    return entry;
   }
 
   /**
    * Handle first argument being a string or an object with a 'message' prop
    */
   static prepare(...input: unknown[]): { message?: string; details: unknown[] } {
-    let [first, ...rest] = input;
-    if (typeof first === 'string') {
-      return { message: first, details: rest };
+    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(first) && typeof first['message'] === 'string') {
-      const { message, ...firstDetails } = first as { message: string };
+    if (isObjectLike(firstArg) && typeof firstArg['message'] === 'string') {
+      const { message, ...firstDetails } = firstArg as { message: string };
       return { message, details: [firstDetails, ...rest] };
     }
+    // No message found, log all args as details
     return { details: input };
   }
 
   /**
-   * Logs error details before throwing
+   * Events that require action or attention immediately
+   */
+  static alert(...input: unknown[]) {
+    return this.#log({ severity: 'ALERT', color: chalk.bgRed }, ...input);
+  }
+
+  /**
+   * Events that cause problems
    */
   static error(...input: unknown[]) {
-    const { message } = this.#log({ severity: 'ERROR', color: chalk.red }, ...input);
-    throw new Error(message);
+    return this.#log({ severity: 'ERROR', color: chalk.red }, ...input);
   }
 
+  /**
+   * Events that might cause problems
+   */
   static warn(...input: unknown[]) {
     return this.#log({ severity: 'WARNING', color: chalk.yellow }, ...input);
   }
 
+  /**
+   * 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);
   }
 
+  /**
+   * Routine information, such as ongoing status or performance
+   */
   static info(...input: unknown[]) {
     return this.#log({ severity: 'INFO', color: chalk.white }, ...input);
   }
 
+  /**
+   * Debug or trace information
+   */
   static debug(...input: unknown[]) {
-    const debugging = process.argv.some((arg) => arg.includes('--debug')) || process.env.DEBUG !== undefined;
-    if (debugging || process.env.NODE_ENV !== 'production') {
-      return this.#log({ severity: 'DEBUG', color: chalk.gray }, ...input);
-    }
+    return this.#log({ severity: 'DEBUG', color: chalk.gray }, ...input);
   }
 }

package/src/TypeWriter.ts

@@ -25,7 +25,7 @@ export class TypeWriter {
   }
 
   async addMember(name: string, _samples: any[]) {
-    const samples = _samples.map((s) => (typeof s === 'string' ? s : JSON.stringify(s)));
+    const samples = _samples.map(s => (typeof s === 'string' ? s : JSON.stringify(s)));
     await this.input.addSource({ name, samples });
   }
 

package/src/index.ts

@@ -1,4 +1,4 @@
-export { Dir, TempDir, temp } from './Dir.ts';
+export { Dir, type DirOptions, temp, cwd } 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';

package/src/snapshot.ts

@@ -1,13 +1,13 @@
 import { isObjectLike } from 'lodash-es';
 
 /**
- * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output
- * functions are removed
+ * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output.
+ * Functions are removed
  */
 export function snapshot(i: unknown, max = 50, depth = 0): any {
   if (Array.isArray(i)) {
     if (depth === max) return [];
-    return i.map((c) => snapshot(c, max, depth + 1));
+    return i.map(c => snapshot(c, max, depth + 1));
   }
   if (typeof i === 'function') return undefined;
   if (!isObjectLike(i)) return i;
@@ -32,7 +32,7 @@ export function snapshot(i: unknown, max = 50, depth = 0): any {
   }
 
   // Get Non-enumberable, own properties
-  Object.getOwnPropertyNames(obj).forEach((key) => {
+  Object.getOwnPropertyNames(obj).forEach(key => {
     output[key] = snapshot(obj[key], max, depth + 1);
   });
 

package/src/timeout.ts

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

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "esnext",
     "module": "nodenext",
     "moduleResolution": "nodenext",
+    "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
     "allowImportingTsExtensions": true,