@brianbuie/node-kit 0.0.0

package/.dist/Fetcher.d.ts

@@ -0,0 +1,41 @@
+export type Route = string | URL;
+export type Query = Record<string, string | number | boolean | undefined>;
+export type FetchOptions = RequestInit & {
+    base?: string;
+    query?: Query;
+    headers?: Record<string, string>;
+    data?: any;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+};
+/**
+ * Fetcher provides a quick way to set up a basic API connection
+ * with options applied to every request
+ * Includes basic methods for requesting and parsing responses
+ */
+export declare class Fetcher {
+    defaultOptions: {
+        timeout: number;
+        retries: number;
+        retryDelay: number;
+    } & RequestInit & {
+        base?: string;
+        query?: Query;
+        headers?: Record<string, string>;
+        data?: any;
+        timeout?: number;
+        retries?: number;
+        retryDelay?: number;
+    };
+    constructor(opts?: FetchOptions);
+    makeUrl(route: Route, query?: Query): URL;
+    /**
+     * 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
+     * Retries on local or network error, with increasing backoff
+     */
+    fetch(route: Route, opts?: FetchOptions): Promise<[Response, Request]>;
+    fetchText(route: Route, opts?: FetchOptions): Promise<[string, Response, Request]>;
+    fetchJson<T>(route: Route, opts?: FetchOptions): Promise<[T, Response, Request]>;
+}

package/.dist/Fetcher.js

@@ -0,0 +1,70 @@
+import { merge } from 'lodash-es';
+/**
+ * Fetcher provides a quick way to set up a basic API connection
+ * with options applied to every request
+ * Includes basic methods for requesting and parsing responses
+ */
+export class Fetcher {
+    defaultOptions;
+    constructor(opts = {}) {
+        const defaultOptions = {
+            timeout: 60000,
+            retries: 3,
+            retryDelay: 3000,
+        };
+        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);
+    }
+    /**
+     * 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
+     * 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 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);
+                    await new Promise(resolve => setTimeout(resolve, wait));
+                }
+            });
+            if (res)
+                return [res, req];
+        }
+        throw new Error(`Failed to fetch ${url.href}`);
+    }
+    async fetchText(route, opts = {}) {
+        return this.fetch(route, opts).then(async ([res, req]) => {
+            const text = await res.text();
+            return [text, res, req];
+        });
+    }
+    async fetchJson(route, opts = {}) {
+        return this.fetchText(route, opts).then(([txt, res, req]) => [JSON.parse(txt), res, req]);
+    }
+}

package/.dist/_index.d.ts

@@ -0,0 +1 @@
+export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';

package/.dist/_index.js

@@ -0,0 +1 @@
+export { Fetcher } from './Fetcher.js';

package/README.md

@@ -0,0 +1,28 @@
+# Node Kit
+
+Basic tools for quick node.js projects
+
+## Using in other projects
+
+```
+npm add @brianbuie/node-kit
+```
+
+```js
+import { thing } from '@brianbuie/node-kit';
+```
+
+## Publishing changes to this package
+
+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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@brianbuie/node-kit",
+  "version": "0.0.0",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brianbuie/node-kit.git"
+  },
+  "scripts": {
+    "test": "tsc && node --test \".dist/**/*.test.js\"",
+    "preversion": "npm test",
+    "postversion": "git push --follow-tags"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./.dist/_index.js"
+  },
+  "files": [
+    "src",
+    ".dist",
+    "!.dist/**/*.test.*",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^24.9.1",
+    "lodash-es": "^4.17.21"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/Fetcher.test.ts

@@ -0,0 +1,48 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { Fetcher } from './Fetcher.js';
+
+describe('Fetcher', () => {
+  const statusApi = new Fetcher({ base: 'https://mock.httpstatus.io' });
+
+  it('should make URL', () => {
+    const route = '/example/route';
+    const url = statusApi.makeUrl(route);
+    assert(url.href.includes(route));
+  });
+
+  it('should throw when no base', () => {
+    try {
+      const empty = new Fetcher();
+      empty.makeUrl('/');
+    } catch (e) {
+      return;
+    }
+    throw new Error('Ignored invalid URL');
+  });
+
+  it('should handle query parameters', () => {
+    const url = statusApi.makeUrl('/', { key: 'value' });
+    assert(url.href.includes('?key=value'));
+  });
+
+  it('should handle undefined query params', () => {
+    const url = statusApi.makeUrl('/', { key: undefined });
+    assert(!url.href.includes('key'));
+  });
+
+  it('should handle no query params', () => {
+    const route = '/';
+    const url = statusApi.makeUrl(route);
+    assert(url.href === statusApi.defaultOptions.base + route);
+  });
+
+  it('should throw on bad request', async () => {
+    try {
+      await statusApi.fetch('/404', { retries: 0 });
+    } catch (e) {
+      return;
+    }
+    throw new Error('Ignored bad request');
+  });
+});

package/src/Fetcher.ts

@@ -0,0 +1,91 @@
+import { merge } from 'lodash-es';
+
+export type Route = string | URL;
+
+export type Query = Record<string, string | number | boolean | undefined>;
+
+export type FetchOptions = RequestInit & {
+  base?: string;
+  query?: Query;
+  headers?: Record<string, string>;
+  data?: any;
+  timeout?: number;
+  retries?: number;
+  retryDelay?: number;
+};
+
+/**
+ * Fetcher provides a quick way to set up a basic API connection
+ * with options applied to every request
+ * Includes basic methods for requesting and parsing responses
+ */
+export class Fetcher {
+  defaultOptions;
+
+  constructor(opts: FetchOptions = {}) {
+    const defaultOptions = {
+      timeout: 60000,
+      retries: 3,
+      retryDelay: 3000,
+    };
+    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);
+  }
+
+  /**
+   * 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
+   * 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 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);
+            await new Promise(resolve => setTimeout(resolve, wait));
+          }
+        });
+      if (res) return [res, req];
+    }
+    throw new Error(`Failed to fetch ${url.href}`);
+  }
+
+  async fetchText(route: Route, opts: FetchOptions = {}): Promise<[string, Response, Request]> {
+    return this.fetch(route, opts).then(async ([res, req]) => {
+      const text = await res.text();
+      return [text, res, req];
+    });
+  }
+
+  async fetchJson<T>(route: Route, opts: FetchOptions = {}): Promise<[T, Response, Request]> {
+    return this.fetchText(route, opts).then(([txt, res, req]) => [JSON.parse(txt) as T, res, req]);
+  }
+}

package/src/_index.ts

@@ -0,0 +1 @@
+export { Fetcher, type Route, Query, FetchOptions } from './Fetcher.js';