@brianbuie/node-kit 0.15.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "license": "Unlicense",
   "description": "Basic tools for quick node.js projects",
   "author": "Brian Buie <brian@buie.dev>",
@@ -30,19 +30,18 @@
   "engines": {
     "node": ">=24"
   },
-  "peerDependencies": {
-    "@types/node": "^24.9.1"
-  },
   "dependencies": {
     "@types/lodash-es": "^4.17.12",
     "@types/mime-types": "^3.0.1",
-    "chalk": "^5.6.2",
+    "@types/node": "^24.9.1",
     "date-fns": "^4.1.0",
     "extract-domain": "^5.0.2",
     "fast-csv": "^5.0.5",
     "format-duration": "^3.0.2",
     "lodash-es": "^4.17.23",
     "mime-types": "^3.0.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
     "quicktype-core": "^23.2.6",
     "sanitize-filename": "^1.6.3"
   },

package/src/Cache.ts

@@ -1,4 +1,5 @@
 import { type Duration, isAfter, add } from 'date-fns';
+import { type FileTypeJson } from './File.ts';
 import { Dir } from './Dir.ts';
 
 /**
@@ -7,12 +8,12 @@ import { Dir } from './Dir.ts';
  * so stale data can still be used if needed.
  */
 export class Cache<T> {
-  file;
-  ttl;
+  file: FileTypeJson<{ savedAt: string; data: T }>;
+  ttl: Duration;
 
   constructor(key: string, ttl: number | Duration, initialData?: T) {
     const dir = new Dir('.cache', { temp: true });
-    this.file = dir.file(key).json<{ savedAt: string; data: T }>();
+    this.file = dir.file(key).json();
     this.ttl = typeof ttl === 'number' ? { minutes: ttl } : ttl;
     if (initialData) this.write(initialData);
   }

package/src/Dir.ts

@@ -16,9 +16,9 @@ export type DirOptions = {
  * include `{ temp: true }` to enable the `.clear()` method
  */
 export class Dir {
-  #inputPath;
+  #inputPath: string;
   #resolved?: string;
-  isTemp;
+  isTemp: boolean;
 
   /**
    * @param path can be relative to workspace or absolute
@@ -31,7 +31,7 @@ export class Dir {
   /**
    * The path of the directory, which might not exist yet.
    */
-  get pathUnsafe() {
+  get pathUnsafe(): string {
     if (this.#resolved) return this.#resolved;
     if (this.#inputPath[0] === '~') {
       if (process.env.HOME) {
@@ -47,7 +47,7 @@ export class Dir {
    * The path of this Dir instance. Created on file system the first time this property is read/used.
    * Safe to use the directory immediately, without calling mkdir separately.
    */
-  get path() {
+  get path(): string {
     // avoids calling mkdir every time path is read
     if (!this.#resolved) {
       this.#resolved = this.pathUnsafe;
@@ -62,7 +62,7 @@ export class Dir {
    * const example = new Dir('/path/to/folder');
    * console.log(example.name); // "folder"
    */
-  get name() {
+  get name(): string {
     return this.pathUnsafe.split(path.sep).at(-1)!;
   }
 
@@ -78,7 +78,7 @@ export class Dir {
    * const child = folder.dir('path/to/dir');
    * // child.path = '/path/to/cwd/example/path/to/dir'
    */
-  dir(subPath = Format.date('ymd'), options: DirOptions = { temp: this.isTemp }) {
+  dir(subPath = Format.date('ymd'), options: DirOptions = { temp: this.isTemp }): Dir {
     return new (this.constructor as typeof Dir)(path.join(this.path, subPath), options) as this;
   }
 
@@ -86,11 +86,11 @@ export class Dir {
    * Creates a new temp directory inside current Dir
    * @param subPath joined with parent Dir's path to make new TempDir
    */
-  tempDir(subPath?: string) {
+  tempDir(subPath?: string): Dir {
     return this.dir(subPath, { temp: true });
   }
 
-  sanitize(filename: string) {
+  sanitize(filename: string): string {
     const notUrl = filename.replace('https://', '').replace('www.', '');
     return sanitizeFilename(notUrl, { replacement: '_' }).slice(-200);
   }
@@ -102,14 +102,14 @@ export class Dir {
    * const filepath = folder.resolve('file.json');
    * // '/path/to/example/file.json'
    */
-  filepath(base: string) {
+  filepath(base: string): string {
     return path.resolve(this.path, this.sanitize(base));
   }
 
   /**
    * Create a new file in this directory. Filename defaults to `YYYYMMDD-HHMMSS` if not provided
    */
-  file(base = Format.date('ymd-hms')) {
+  file(base = Format.date('ymd-hms')): File {
     return new File(this.filepath(base));
   }
 
@@ -125,28 +125,28 @@ export class Dir {
   /**
    * All subdirectories in this directory
    */
-  get dirs() {
+  get dirs(): Dir[] {
     return this.contents.filter(f => f instanceof Dir);
   }
 
   /**
    * All files in this directory
    */
-  get files() {
+  get files(): File[] {
     return this.contents.filter(f => f instanceof File);
   }
 
   /**
    * All files with MIME type that includes "video"
    */
-  get videos() {
+  get videos(): File[] {
     return this.files.filter(f => f.type?.includes('video'));
   }
 
   /**
    * All files with MIME type that includes "image"
    */
-  get images() {
+  get images(): File[] {
     return this.files.filter(f => f.type?.includes('image'));
   }
 
@@ -157,7 +157,7 @@ export class Dir {
    * const dataFiles = dataDir.jsonFiles.map(f => f.json<ExampleType>());
    * // dataFiles: FileTypeJson<ExampleType>[]
    */
-  get jsonFiles() {
+  get jsonFiles(): File[] {
     return this.files.filter(f => f.ext === '.json');
   }
 
@@ -168,7 +168,7 @@ export class Dir {
    * const dataFiles = dataDir.ndjsonFiles.map(f => f.ndjson<ExampleType>());
    * // dataFiles: FileTypeNdjson<ExampleType>[]
    */
-  get ndjsonFiles() {
+  get ndjsonFiles(): File[] {
     return this.files.filter(f => f.ext === '.ndjson');
   }
 
@@ -179,21 +179,21 @@ export class Dir {
    * const dataFiles = dataDir.csvFile.map(f => f.csv<ExampleType>());
    * // dataFiles: FileTypeCsv<ExampleType>[]
    */
-  get csvFiles() {
+  get csvFiles(): File[] {
     return this.files.filter(f => f.ext === '.csv');
   }
 
   /**
    * All files with ext ".txt"
    */
-  get textFiles() {
+  get txtFiles(): File[] {
     return this.files.filter(f => f.ext === '.txt');
   }
 
   /**
    * Deletes the contents of the directory. Only allowed if created with `temp` option set to `true` (or created with `dir.tempDir` method).
    */
-  clear() {
+  clear(): void {
     if (!this.isTemp) throw new Error('Dir is not temporary');
     fs.rmSync(this.path, { recursive: true, force: true });
     fs.mkdirSync(this.path, { recursive: true });

package/src/Fetcher.ts

@@ -22,7 +22,7 @@ export type FetchOptions = RequestInit & {
  * Includes basic methods for requesting and parsing responses
  */
 export class Fetcher {
-  defaultOptions;
+  defaultOptions: FetchOptions;
 
   constructor(opts: FetchOptions = {}) {
     this.defaultOptions = {
@@ -65,7 +65,7 @@ export class Fetcher {
   /**
    * Merges options to get headers. Useful when extending the Fetcher class to add custom auth.
    */
-  buildHeaders(route: Route, opts: FetchOptions = {}) {
+  buildHeaders(route: Route, opts: FetchOptions = {}): HeadersInit & Record<string, string> {
     const { headers } = merge({}, this.defaultOptions, opts);
     return headers || {};
   }

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();
   });
 });