@brianbuie/node-kit 0.0.4 → 0.1.1

package/.dist/Jwt.d.ts

@@ -0,0 +1,16 @@
+import { type JwtPayload, type SignOptions } from 'jsonwebtoken';
+export declare class Jwt {
+    #private;
+    payload: JwtPayload;
+    options: SignOptions;
+    seconds: number;
+    key: string;
+    constructor({ payload, options, seconds, key, }: {
+        payload: JwtPayload;
+        options: SignOptions;
+        seconds: number;
+        key: string;
+    });
+    get now(): number;
+    get token(): string;
+}

package/.dist/Jwt.js

@@ -0,0 +1,35 @@
+import { default as jsonwebtoken } from 'jsonwebtoken';
+import { merge } from 'lodash-es';
+export class Jwt {
+    payload;
+    options;
+    seconds;
+    key;
+    #saved;
+    constructor({ payload, options, seconds, key, }) {
+        this.payload = payload;
+        this.options = options;
+        this.seconds = seconds;
+        this.key = key;
+        this.#createToken();
+    }
+    get now() {
+        return Math.floor(Date.now() / 1000);
+    }
+    get token() {
+        if (this.#saved && this.#saved.exp > this.now) {
+            return this.#saved.token;
+        }
+        return this.#createToken();
+    }
+    #createToken() {
+        const exp = this.now + this.seconds;
+        const payload = merge({
+            iat: this.now,
+            exp,
+        }, this.payload);
+        const token = jsonwebtoken.sign(payload, this.key, this.options);
+        this.#saved = { token, exp };
+        return token;
+    }
+}

package/.dist/Log.d.ts

@@ -0,0 +1,43 @@
+import { type ChalkInstance } from 'chalk';
+type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
+type Options = {
+    severity: Severity;
+    color: ChalkInstance;
+};
+export declare class Log {
+    #private;
+    static isTest: boolean;
+    /**
+     * Handle first argument being a string or an object with a 'message' prop
+     * Also snapshots special objects (eg Error, Response) to keep props in later JSON.stringify output
+     */
+    static prepare(...input: unknown[]): {
+        message?: string;
+        details: unknown[];
+    };
+    /**
+     * Logs error details before throwing
+     */
+    static error(...input: unknown[]): void;
+    static warn(...input: unknown[]): {
+        message: string | undefined;
+        details: unknown[];
+        options: Options;
+    };
+    static notice(...input: unknown[]): {
+        message: string | undefined;
+        details: unknown[];
+        options: Options;
+    };
+    static info(...input: unknown[]): {
+        message: string | undefined;
+        details: unknown[];
+        options: Options;
+    };
+    static debug(...input: unknown[]): {
+        message: string | undefined;
+        details: unknown[];
+        options: Options;
+    } | undefined;
+}
+export {};

package/.dist/Log.js

@@ -0,0 +1,81 @@
+import fs from 'fs';
+import { inspect } from 'util';
+import { isObjectLike } from 'lodash-es';
+import chalk from 'chalk';
+import { snapshot } from './snapshot.js';
+const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+export class Log {
+    static isTest = process.env.npm_package_name === packageJson.name && process.env.npm_lifecycle_event === 'test';
+    /**
+     * Gcloud parses JSON in stdout
+     */
+    static #toGcloud(entry) {
+        if (entry.details?.length === 1) {
+            console.log(JSON.stringify({ ...entry, details: entry.details[0] }));
+        }
+        else {
+            console.log(JSON.stringify(entry));
+        }
+    }
+    /**
+     * Includes colors and better inspection for logging during dev
+     */
+    static #toConsole(entry, color) {
+        if (entry.message)
+            console.log(color(`[${entry.severity}] ${entry.message}`));
+        entry.details?.forEach(detail => {
+            console.log(inspect(detail, { depth: 10, breakLength: 100, compact: true, colors: true }));
+        });
+    }
+    static #log(options, ...input) {
+        const { message, details } = this.prepare(...input);
+        // 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);
+        }
+        return { message, details, options };
+    }
+    /**
+     * Handle first argument being a string or an object with a 'message' prop
+     * Also snapshots special objects (eg Error, Response) to keep props in later JSON.stringify output
+     */
+    static prepare(...input) {
+        let [first, ...rest] = input.map(snapshot);
+        if (typeof first === 'string')
+            return { message: first, details: rest };
+        // @ts-ignore
+        if (isObjectLike(first) && typeof first['message'] === 'string') {
+            const { message, ...firstDetails } = first;
+            return { message, details: [firstDetails, ...rest] };
+        }
+        return { details: input };
+    }
+    /**
+     * Logs error details before throwing
+     */
+    static error(...input) {
+        const { message } = this.#log({ severity: 'ERROR', color: chalk.red }, ...input);
+        throw new Error(message);
+    }
+    static warn(...input) {
+        return this.#log({ severity: 'WARNING', color: chalk.yellow }, ...input);
+    }
+    static notice(...input) {
+        return this.#log({ severity: 'NOTICE', color: chalk.cyan }, ...input);
+    }
+    static info(...input) {
+        return this.#log({ severity: 'INFO', color: chalk.white }, ...input);
+    }
+    static debug(...input) {
+        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);
+        }
+    }
+}

package/.dist/_index.d.ts

@@ -1 +1,4 @@
 export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';
+export { Jwt } from './Jwt.js';
+export { snapshot } from './snapshot.js';
+export { Log } from './Log.js';

package/.dist/_index.js

@@ -1 +1,4 @@
 export { Fetcher } from './Fetcher.js';
+export { Jwt } from './Jwt.js';
+export { snapshot } from './snapshot.js';
+export { Log } from './Log.js';

package/.dist/snapshot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output
+ * functions are removed
+ */
+export declare function snapshot(i: unknown): any;

package/.dist/snapshot.js

@@ -0,0 +1,33 @@
+import { isObjectLike } from 'lodash-es';
+/**
+ * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output
+ * functions are removed
+ */
+export function snapshot(i) {
+    if (Array.isArray(i))
+        return i.map(snapshot);
+    if (typeof i === 'function')
+        return undefined;
+    if (!isObjectLike(i))
+        return i;
+    let output = {};
+    // @ts-ignore If it has an 'entries' function, use that for looping (eg. Set, Map, Headers)
+    if (typeof i.entries === 'function') {
+        // @ts-ignore
+        for (let [k, v] of i.entries()) {
+            output[k] = snapshot(v);
+        }
+        return output;
+    }
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties
+    // Get Enumerable, inherited properties
+    const obj = i;
+    for (let key in obj) {
+        output[key] = snapshot(obj[key]);
+    }
+    // Get Non-enumberable, own properties
+    Object.getOwnPropertyNames(obj).forEach(key => {
+        output[key] = snapshot(obj[key]);
+    });
+    return output;
+}

package/README.md

@@ -1,8 +1,8 @@
-# Node Kit
+# Node Kit • ![NPM Version](https://img.shields.io/npm/v/%40brianbuie%2Fnode-kit)
 
 Basic tools for quick node.js projects
 
-## Using in other projects
+## Installing
 
 ```
 npm add @brianbuie/node-kit
@@ -12,17 +12,100 @@ npm add @brianbuie/node-kit
 import { thing } from '@brianbuie/node-kit';
 ```
 
+## Features
+
+### Fetcher
+
+```ts
+import { Fetcher } from '@brianbuie/node-kit';
+
+// All requests will include Authorization header
+const api = new Fetcher({
+  base: 'https://www.example.com',
+  headers: {
+    Authorization: `Bearer ${process.env.EXAMPLE_SECRET}`,
+  },
+});
+
+// GET https://www.example.com/route
+// returns [Response, Request]
+const [res] = await api.fetch('/route');
+
+// GET https://www.example.com/other-route
+// returns [string, Response, Request]
+const [text] = await api.fetchText('/other-route');
+
+// GET https://www.example.com/thing?page=1
+// returns [Thing, Response, Request]
+const [data] = await api.fetchJson<Thing>('/thing', { query: { page: 1 } });
+
+// POST https://www.example.com/thing (data is sent as JSON in body)
+// returns [Thing, Response, Request]
+const [result] = await api.fetchJson<Thing>('/thing', { data: { example: 1 } });
+```
+
+### Jwt
+
+Save a JSON Web Token in memory and reuse it throughout the process.
+
+```js
+import { Jwt, Fetcher } from '@brianbuie/node-kit';
+
+const apiJwt = new Jwt({
+  payload: {
+    example: 'value',
+  },
+  options: {
+    algorithm: 'HS256',
+  },
+  seconds: 60,
+  key: process.env.JWT_KEY,
+});
+
+const api = new Fetcher({
+  base: 'https://example.com',
+  headers: {
+    Authorization: `Bearer ${apiJwt.token}`,
+  },
+});
+```
+
+> TODO: expiration is not checked again when provided in a header
+
+### Log
+
+Chalk output in development, structured JSON when running in gcloud
+
+```js
+import { Log } from '@brianbuie/node-kit';
+
+Log.info('message', { other: 'details' });
+
+// Print in development, or if process.env.DEBUG or --debug argument is present
+Log.debug('message', Response);
+
+// Log details and throw
+Log.error('Something happened', details, moreDetails);
+```
+
+### snapshot
+
+Gets all enumerable and non-enumerable properties, so they can be included in JSON.stringify. Helpful for built-in objects, like Error, Request, Response, Headers, Map, etc.
+
+```js
+fs.writeFileSync('result.json', JSON.stringify(snapshot(response), null, 2));
+```
+
 ## Publishing changes to this package
 
-Commit all changes, then run
+Commit all changes, then run:
 
 ```
 npm version [patch|minor|major] [-m "custom commit message"]
 ```
 
 - Bumps version in `package.json`
-- Runs tests
-- Commits changes
-- Tags commit with new version
-- Pushes commit and tags to github
-- The new tag will trigger github action to publish to npm
+- Runs tests (`"preversion"` script in `package.json`)
+- Creates new commit, tagged with version
+- Pushes commit and tags to github (`"postversion"` script in `package.json`)
+- The new tag will trigger github action to publish to npm (`.github/actions/publish.yml`)

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/brianbuie/node-kit.git"
   },
   "scripts": {
-    "test": "tsc && node --test \".dist/**/*.test.js\"",
+    "test": "tsc && node --test \".dist/**/*.test.js\" --quiet",
     "preversion": "npm test",
     "postversion": "git push --follow-tags"
   },
@@ -25,8 +25,11 @@
     "node": ">=24"
   },
   "dependencies": {
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.9.1",
+    "chalk": "^5.6.2",
+    "jsonwebtoken": "^9.0.2",
     "lodash-es": "^4.17.21"
   },
   "devDependencies": {

package/src/Jwt.test.ts

@@ -0,0 +1,22 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import jsonwebtoken from 'jsonwebtoken';
+import { Jwt } from './Jwt.js';
+
+describe('Jwt', () => {
+  it('should create a valid JWT', () => {
+    const key = 'test';
+    const jwt = new Jwt({
+      payload: {
+        example: 'value',
+      },
+      options: {
+        algorithm: 'HS256',
+      },
+      seconds: 60,
+      key,
+    });
+    const result = jsonwebtoken.verify(jwt.token, key);
+    assert(typeof result !== 'string' && result.example === 'value');
+  });
+});

package/src/Jwt.ts

@@ -0,0 +1,56 @@
+import { default as jsonwebtoken, type JwtPayload, type SignOptions } from 'jsonwebtoken';
+import { merge } from 'lodash-es';
+
+export class Jwt {
+  payload: JwtPayload;
+  options: SignOptions;
+  seconds: number;
+  key: string;
+  #saved?: {
+    exp: number;
+    token: string;
+  };
+
+  constructor({
+    payload,
+    options,
+    seconds,
+    key,
+  }: {
+    payload: JwtPayload;
+    options: SignOptions;
+    seconds: number;
+    key: string;
+  }) {
+    this.payload = payload;
+    this.options = options;
+    this.seconds = seconds;
+    this.key = key;
+    this.#createToken();
+  }
+
+  get now() {
+    return Math.floor(Date.now() / 1000);
+  }
+
+  get token() {
+    if (this.#saved && this.#saved.exp > this.now) {
+      return this.#saved.token;
+    }
+    return this.#createToken();
+  }
+
+  #createToken() {
+    const exp = this.now + this.seconds;
+    const payload: JwtPayload = merge(
+      {
+        iat: this.now,
+        exp,
+      },
+      this.payload
+    );
+    const token = jsonwebtoken.sign(payload, this.key, this.options);
+    this.#saved = { token, exp };
+    return token;
+  }
+}

package/src/Log.test.ts

@@ -0,0 +1,28 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { Log } from './Log.js';
+
+describe('Log', () => {
+  it('should throw error', () => {
+    try {
+      Log.error('Test error');
+    } catch (e) {
+      return;
+    }
+    assert(false, 'Did not throw error');
+  });
+
+  it('should recognize this is a test', () => {
+    assert(Log.isTest);
+  });
+
+  it('should use first argument as message when string', () => {
+    const result = Log.prepare('test', { something: 'else' });
+    assert(result.message === 'test');
+  });
+
+  it('should use message prop when provided', () => {
+    const result = Log.prepare({ message: 'test', something: 'else' });
+    assert(result.message === 'test');
+  });
+});

package/src/Log.ts

@@ -0,0 +1,102 @@
+import fs from 'fs';
+import { inspect } from 'util';
+import { isObjectLike } from 'lodash-es';
+import chalk, { type ChalkInstance } from 'chalk';
+import { snapshot } from './snapshot.js';
+
+const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+
+type Severity = 'DEFAULT' | 'DEBUG' | 'INFO' | 'NOTICE' | 'WARNING' | 'ERROR' | 'CRITICAL' | 'ALERT' | 'EMERGENCY';
+
+type Options = {
+  severity: Severity;
+  color: ChalkInstance;
+};
+
+type Entry = {
+  message?: string;
+  severity: Severity;
+  details?: unknown[];
+};
+
+export class Log {
+  static isTest = process.env.npm_package_name === packageJson.name && process.env.npm_lifecycle_event === 'test';
+
+  /**
+   * Gcloud parses JSON in stdout
+   */
+  static #toGcloud(entry: Entry) {
+    if (entry.details?.length === 1) {
+      console.log(JSON.stringify({ ...entry, details: entry.details[0] }));
+    } else {
+      console.log(JSON.stringify(entry));
+    }
+  }
+
+  /**
+   * 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 => {
+      console.log(inspect(detail, { depth: 10, breakLength: 100, compact: true, colors: true }));
+    });
+  }
+
+  static #log(options: Options, ...input: unknown[]) {
+    const { message, details } = this.prepare(...input);
+    // 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);
+    }
+    return { message, details, options };
+  }
+
+  /**
+   * Handle first argument being a string or an object with a 'message' prop
+   * Also snapshots special objects (eg Error, Response) to keep props in later JSON.stringify output
+   */
+  static prepare(...input: unknown[]): { message?: string; details: unknown[] } {
+    let [first, ...rest] = input.map(snapshot);
+    if (typeof first === 'string') return { message: first, details: rest };
+    // @ts-ignore
+    if (isObjectLike(first) && typeof first['message'] === 'string') {
+      const { message, ...firstDetails } = first as { message: string };
+      return { message, details: [firstDetails, ...rest] };
+    }
+    return { details: input };
+  }
+
+  /**
+   * Logs error details before throwing
+   */
+  static error(...input: unknown[]) {
+    const { message } = this.#log({ severity: 'ERROR', color: chalk.red }, ...input);
+    throw new Error(message);
+  }
+
+  static warn(...input: unknown[]) {
+    return this.#log({ severity: 'WARNING', color: chalk.yellow }, ...input);
+  }
+
+  static notice(...input: unknown[]) {
+    return this.#log({ severity: 'NOTICE', color: chalk.cyan }, ...input);
+  }
+
+  static info(...input: unknown[]) {
+    return this.#log({ severity: 'INFO', color: chalk.white }, ...input);
+  }
+
+  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);
+    }
+  }
+}

package/src/_index.ts

@@ -1 +1,4 @@
 export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';
+export { Jwt } from './Jwt.js';
+export { snapshot } from './snapshot.js';
+export { Log } from './Log.js';

package/src/snapshot.test.ts

@@ -0,0 +1,35 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { snapshot } from './snapshot.js';
+
+describe('snapshot', () => {
+  it('should capture Error details', () => {
+    try {
+      throw new Error('Test Error');
+    } catch (e) {
+      const result = snapshot(e) as Error;
+      assert(result.message !== undefined);
+      assert(result.stack !== undefined);
+    }
+  });
+
+  it('should capture Map values', () => {
+    const test = new Map<string, string>();
+    test.set('key', 'value');
+    const shot = JSON.parse(JSON.stringify(snapshot(test))) as Record<string, string>;
+    assert(shot.key === 'value');
+  });
+
+  it('should capture Request values', () => {
+    const test = new Request('https://www.google.com', { headers: { example: 'value' } });
+    const shot = JSON.parse(JSON.stringify(snapshot(test))) as Record<string, any>;
+    assert(shot.url !== undefined);
+    assert(shot.headers.example === 'value');
+  });
+
+  it('should ignore functions', () => {
+    const test = { func: () => null };
+    const shot = snapshot(test) as Record<string, any>;
+    assert(shot.func === undefined);
+  });
+});

package/src/snapshot.ts

@@ -0,0 +1,36 @@
+import { isObjectLike } from 'lodash-es';
+
+/**
+ * Allows special objects (Error, Headers, Set) to be included in JSON.stringify output
+ * functions are removed
+ */
+export function snapshot(i: unknown): any {
+  if (Array.isArray(i)) return i.map(snapshot);
+  if (typeof i === 'function') return undefined;
+  if (!isObjectLike(i)) return i;
+
+  let output: Record<string, any> = {};
+  // @ts-ignore If it has an 'entries' function, use that for looping (eg. Set, Map, Headers)
+  if (typeof i.entries === 'function') {
+    // @ts-ignore
+    for (let [k, v] of i.entries()) {
+      output[k] = snapshot(v);
+    }
+    return output;
+  }
+
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties
+
+  // Get Enumerable, inherited properties
+  const obj: Record<string, any> = i!;
+  for (let key in obj) {
+    output[key] = snapshot(obj[key]);
+  }
+
+  // Get Non-enumberable, own properties
+  Object.getOwnPropertyNames(obj).forEach(key => {
+    output[key] = snapshot(obj[key]);
+  });
+
+  return output;
+}