@brianbuie/node-kit 0.12.5 → 0.14.0

package/src/Dir.ts

@@ -3,52 +3,82 @@ 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);
+  }
+
+  /**
+   * The path of the directory, which might not exist yet.
+   */
+  get pathUnsafe() {
+    return this.#resolved || path.resolve(this.#inputPath);
   }
 
   /**
    * 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() {
+    // avoids calling mkdir every time path is read
     if (!this.#resolved) {
-      this.#resolved = path.resolve(this.#inputPath);
+      this.#resolved = this.pathUnsafe;
       fs.mkdirSync(this.#resolved, { recursive: true });
     }
     return this.#resolved;
   }
 
+  /**
+   * The last segment in the path. Doesn't read this.path, to avoid creating directory on file system before it's needed.
+   * @example
+   * const example = new Dir('/path/to/folder');
+   * console.log(example.name); // "folder"
+   */
+  get name() {
+    return this.pathUnsafe.split(path.sep).at(-1)!;
+  }
+
   /**
    * 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) {
@@ -67,28 +97,95 @@ export class Dir {
     return path.resolve(this.path, this.sanitize(base));
   }
 
+  /**
+   * Create a new file in this directory
+   */
   file(base: string) {
     return new File(this.filepath(base));
   }
 
+  /**
+   * All files and subdirectories in in this directory, returned as Dir and File instances
+   */
+  get contents(): (Dir | File)[] {
+    return fs
+      .readdirSync(this.path)
+      .map(name => (fs.statSync(path.join(this.path, name)).isDirectory() ? this.dir(name) : this.file(name)));
+  }
+
+  /**
+   * All subdirectories in this directory
+   */
+  get dirs() {
+    return this.contents.filter(f => f instanceof Dir);
+  }
+
+  /**
+   * All files in this directory
+   */
   get files() {
-    return fs.readdirSync(this.path).map(filename => this.file(filename));
+    return this.contents.filter(f => f instanceof File);
   }
-}
 
-/**
- * Extends Dir class with method to `clear()` contents.
- * Default path: `./.temp`
- */
-export class TempDir extends Dir {
-  constructor(inputPath = `./.temp`) {
-    super(inputPath);
+  /**
+   * All files with MIME type that includes "video"
+   */
+  get videos() {
+    return this.files.filter(f => f.type?.includes('video'));
+  }
+
+  /**
+   * All files with MIME type that includes "image"
+   */
+  get images() {
+    return this.files.filter(f => f.type?.includes('image'));
+  }
+
+  /**
+   * All files with ext ".json"
+   * @example
+   * // Directory of json files with the same shape
+   * const dataFiles = dataDir.jsonFiles.map(f => f.json<ExampleType>());
+   * // dataFiles: FileTypeJson<ExampleType>[]
+   */
+  get jsonFiles() {
+    return this.files.filter(f => f.ext === '.json');
+  }
+
+  /**
+   * All files with ext ".ndjson"
+   * @example
+   * // Directory of ndjson files with the same shape
+   * const dataFiles = dataDir.ndjsonFiles.map(f => f.ndjson<ExampleType>());
+   * // dataFiles: FileTypeNdjson<ExampleType>[]
+   */
+  get ndjsonFiles() {
+    return this.files.filter(f => f.ext === '.ndjson');
+  }
+
+  /**
+   * All files with ext ".csv"
+   * @example
+   * // Directory of csv files with the same shape
+   * const dataFiles = dataDir.csvFile.map(f => f.csv<ExampleType>());
+   * // dataFiles: FileTypeCsv<ExampleType>[]
+   */
+  get csvFiles() {
+    return this.files.filter(f => f.ext === '.csv');
+  }
+
+  /**
+   * All files with ext ".txt"
+   */
+  get textFiles() {
+    return this.files.filter(f => f.ext === '.txt');
   }
 
   /**
-   * > ⚠️ Warning! This deletes the directory!
+   * Deletes the contents of the directory. Only allowed if created with `temp` option set to `true` (or created with `dir.tempDir` method).
    */
   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 });
   }

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/Log.ts

@@ -4,6 +4,7 @@ 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 = {
@@ -82,25 +83,43 @@ export class Log {
   }
 
   /**
-   * 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[]) {
     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,

package/prettier.config.ts

@@ -1,6 +0,0 @@
-export default {
-  printWidth: 120,
-  singleQuote: true,
-  quoteProps: 'consistent',
-  arrowParens: 'avoid',
-};