@brianbuie/node-kit 0.1.0 → 0.2.0

package/.dist/Fetcher.d.ts

@@ -1,5 +1,5 @@
 export type Route = string | URL;
-export type Query = Record<string, string | number | boolean | undefined>;
+export type Query = Record<string, string | number | boolean | null | undefined>;
 export type FetchOptions = RequestInit & {
     base?: string;
     query?: Query;
@@ -29,7 +29,16 @@ export declare class Fetcher {
         retryDelay?: number;
     };
     constructor(opts?: FetchOptions);
-    makeUrl(route: Route, query?: Query): URL;
+    /**
+     * Build URL with URLSearchParams if query is provided
+     * Also returns domain, to help with cookies
+     */
+    buildUrl(route: Route, opts?: FetchOptions): [URL, string];
+    /**
+     * Builds request, merging defaultOptions and provided options
+     * Includes Abort signal for timeout
+     */
+    buildRequest(route: Route, opts?: FetchOptions): [Request, FetchOptions, string];
     /**
      * Builds and performs the request, merging provided options with defaultOptions
      * If `opts.data` is provided, method is updated to POST, content-type json, data is stringified in the body

package/.dist/Fetcher.js

@@ -1,4 +1,5 @@
 import { merge } from 'lodash-es';
+import extractDomain from 'extract-domain';
 /**
  * Fetcher provides a quick way to set up a basic API connection
  * with options applied to every request
@@ -14,12 +15,39 @@ export class Fetcher {
         };
         this.defaultOptions = merge(defaultOptions, opts);
     }
-    makeUrl(route, query = {}) {
-        const params = new URLSearchParams(Object.entries(query)
-            .filter(([_k, val]) => Boolean(val))
-            .map(([key, val]) => [key, `${val}`])).toString();
-        const search = params ? '?' + params : '';
-        return new URL(route + search, this.defaultOptions.base);
+    /**
+     * Build URL with URLSearchParams if query is provided
+     * Also returns domain, to help with cookies
+     */
+    buildUrl(route, opts = {}) {
+        const mergedOptions = merge({}, this.defaultOptions, opts);
+        const params = Object.entries(mergedOptions.query || {})
+            .filter(([_k, val]) => val !== undefined)
+            .map(([key, val]) => [key, `${val}`]);
+        const search = params.length > 0 ? '?' + new URLSearchParams(params).toString() : '';
+        const url = new URL(route + search, this.defaultOptions.base);
+        const domain = extractDomain(url.href);
+        return [url, domain];
+    }
+    /**
+     * Builds request, merging defaultOptions and provided options
+     * Includes Abort signal for timeout
+     */
+    buildRequest(route, opts = {}) {
+        const mergedOptions = merge({}, this.defaultOptions, opts);
+        const { query, data, timeout, retries, ...init } = mergedOptions;
+        if (data) {
+            init.headers = init.headers || {};
+            init.headers['content-type'] = init.headers['content-type'] || 'application/json';
+            init.method = init.method || 'POST';
+            init.body = JSON.stringify(data);
+        }
+        if (timeout) {
+            init.signal = AbortSignal.timeout(timeout);
+        }
+        const [url, domain] = this.buildUrl(route, mergedOptions);
+        const req = new Request(url, init);
+        return [req, mergedOptions, domain];
     }
     /**
      * Builds and performs the request, merging provided options with defaultOptions
@@ -27,19 +55,13 @@ export class Fetcher {
      * Retries on local or network error, with increasing backoff
      */
     async fetch(route, opts = {}) {
-        const { query, data, timeout, retries, ...o } = merge({}, this.defaultOptions, opts);
-        if (data) {
-            o.headers = o.headers || {};
-            o.headers['content-type'] = o.headers['content-type'] || 'application/json';
-            o.method = o.method || 'POST';
-            o.body = JSON.stringify(data);
-        }
-        const url = this.makeUrl(route, query);
-        const attempts = retries + 1;
-        let attempted = 0;
-        while (attempted < attempts) {
-            attempted++;
-            const req = new Request(url, { ...o, signal: AbortSignal.timeout(timeout) });
+        const [_req, options] = this.buildRequest(route, opts);
+        const maxAttempts = (options.retries || 0) + 1;
+        let attempt = 0;
+        while (attempt < maxAttempts) {
+            attempt++;
+            // Rebuild request on every attempt to reset AbortSignal.timeout
+            const [req] = this.buildRequest(route, opts);
             const res = await fetch(req)
                 .then(r => {
                 if (!r.ok)
@@ -47,16 +69,16 @@ export class Fetcher {
                 return r;
             })
                 .catch(async (error) => {
-                if (attempted < attempts) {
-                    const wait = attempted * 3000;
-                    console.warn(`Fetcher (attempt ${attempted} of ${attempts})`, 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));
                 }
             });
             if (res)
                 return [res, req];
         }
-        throw new Error(`Failed to fetch ${url.href}`);
+        throw new Error(`Failed to fetch ${_req.url}`);
     }
     async fetchText(route, opts = {}) {
         return this.fetch(route, opts).then(async ([res, req]) => {

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,6 +1,6 @@
 {
   "name": "@brianbuie/node-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -29,6 +29,7 @@
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.9.1",
     "chalk": "^5.6.2",
+    "extract-domain": "^5.0.2",
     "jsonwebtoken": "^9.0.2",
     "lodash-es": "^4.17.21"
   },

package/src/Fetcher.test.ts

@@ -7,33 +7,46 @@ describe('Fetcher', () => {
 
   it('should make URL', () => {
     const route = '/example/route';
-    const url = statusApi.makeUrl(route);
+    const [url] = statusApi.buildUrl(route);
     assert(url.href.includes(route));
   });
 
-  it('should throw when no base', () => {
+  it('should throw when URL is invalid', () => {
     try {
       const empty = new Fetcher();
-      empty.makeUrl('/');
+      empty.buildUrl('/');
     } catch (e) {
       return;
     }
     throw new Error('Ignored invalid URL');
   });
 
+  it('should identify the correct domain', () => {
+    const test = new Fetcher({ base: 'https://subdomain.example.org' });
+    const [_, domain] = test.buildUrl('');
+    assert(domain === 'example.org');
+  });
+
   it('should handle query parameters', () => {
-    const url = statusApi.makeUrl('/', { key: 'value' });
+    const [url] = statusApi.buildUrl('/', { query: { key: 'value' } });
     assert(url.href.includes('?key=value'));
   });
 
   it('should handle undefined query params', () => {
-    const url = statusApi.makeUrl('/', { key: undefined });
+    const [url] = statusApi.buildUrl('/', { query: { key: undefined } });
     assert(!url.href.includes('key'));
   });
 
+  it('should keep falsey query params', () => {
+    const [url] = statusApi.buildUrl('/', { query: { zero: 0, false: false, null: null } });
+    assert(url.href.includes('zero=0'));
+    assert(url.href.includes('false=false'));
+    assert(url.href.includes('null=null'));
+  });
+
   it('should handle no query params', () => {
     const route = '/';
-    const url = statusApi.makeUrl(route);
+    const [url] = statusApi.buildUrl(route);
     assert(url.href === statusApi.defaultOptions.base + route);
   });
 

package/src/Fetcher.ts

@@ -1,8 +1,9 @@
 import { merge } from 'lodash-es';
+import extractDomain from 'extract-domain';
 
 export type Route = string | URL;
 
-export type Query = Record<string, string | number | boolean | undefined>;
+export type Query = Record<string, string | number | boolean | null | undefined>;
 
 export type FetchOptions = RequestInit & {
   base?: string;
@@ -31,14 +32,40 @@ export class Fetcher {
     this.defaultOptions = merge(defaultOptions, opts);
   }
 
-  makeUrl(route: Route, query: Query = {}) {
-    const params = new URLSearchParams(
-      Object.entries(query)
-        .filter(([_k, val]) => Boolean(val))
-        .map(([key, val]) => [key, `${val}`])
-    ).toString();
-    const search = params ? '?' + params : '';
-    return new URL(route + search, this.defaultOptions.base);
+  /**
+   * Build URL with URLSearchParams if query is provided
+   * Also returns domain, to help with cookies
+   */
+  buildUrl(route: Route, opts: FetchOptions = {}): [URL, string] {
+    const mergedOptions = merge({}, this.defaultOptions, opts);
+    const params = Object.entries(mergedOptions.query || {})
+      .filter(([_k, val]) => val !== undefined)
+      .map(([key, val]) => [key, `${val}`]);
+    const search = params.length > 0 ? '?' + new URLSearchParams(params).toString() : '';
+    const url = new URL(route + search, this.defaultOptions.base);
+    const domain = extractDomain(url.href) as string;
+    return [url, domain];
+  }
+
+  /**
+   * Builds request, merging defaultOptions and provided options
+   * Includes Abort signal for timeout
+   */
+  buildRequest(route: Route, opts: FetchOptions = {}): [Request, FetchOptions, string] {
+    const mergedOptions = merge({}, this.defaultOptions, opts);
+    const { query, data, timeout, retries, ...init } = mergedOptions;
+    if (data) {
+      init.headers = init.headers || {};
+      init.headers['content-type'] = init.headers['content-type'] || 'application/json';
+      init.method = init.method || 'POST';
+      init.body = JSON.stringify(data);
+    }
+    if (timeout) {
+      init.signal = AbortSignal.timeout(timeout);
+    }
+    const [url, domain] = this.buildUrl(route, mergedOptions);
+    const req = new Request(url, init);
+    return [req, mergedOptions, domain];
   }
 
   /**
@@ -47,35 +74,28 @@ export class Fetcher {
    * Retries on local or network error, with increasing backoff
    */
   async fetch(route: Route, opts: FetchOptions = {}): Promise<[Response, Request]> {
-    const { query, data, timeout, retries, ...o } = merge({}, this.defaultOptions, opts);
-    if (data) {
-      o.headers = o.headers || {};
-      o.headers['content-type'] = o.headers['content-type'] || 'application/json';
-      o.method = o.method || 'POST';
-      o.body = JSON.stringify(data);
-    }
-    const url = this.makeUrl(route, query);
-
-    const attempts = retries + 1;
-    let attempted = 0;
-    while (attempted < attempts) {
-      attempted++;
-      const req = new Request(url, { ...o, signal: AbortSignal.timeout(timeout) });
+    const [_req, options] = this.buildRequest(route, opts);
+    const maxAttempts = (options.retries || 0) + 1;
+    let attempt = 0;
+    while (attempt < maxAttempts) {
+      attempt++;
+      // Rebuild request on every attempt to reset AbortSignal.timeout
+      const [req] = this.buildRequest(route, opts);
       const res = await fetch(req)
         .then(r => {
           if (!r.ok) throw new Error(r.statusText);
           return r;
         })
         .catch(async error => {
-          if (attempted < attempts) {
-            const wait = attempted * 3000;
-            console.warn(`Fetcher (attempt ${attempted} of ${attempts})`, 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));
           }
         });
       if (res) return [res, req];
     }
-    throw new Error(`Failed to fetch ${url.href}`);
+    throw new Error(`Failed to fetch ${_req.url}`);
   }
 
   async fetchText(route: Route, opts: FetchOptions = {}): Promise<[string, Response, Request]> {