@ribbon-studios/js-utils 1.1.1 → 1.3.0

package/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Then this is the perfect place for you!
 
 ## Prerequisites
 
-- NodeJS 18
+- NodeJS 22
 
 ## Setting Up Locally
 

package/README.md

@@ -19,6 +19,14 @@ Collection of generic javascript utilities curated by the Rainbow Cafe~
   - [`assert`](#assert)
     - [`assert.defined`](#assertdefined)
   - [`never`](#never)
+  - [`retry`](#retry)
+- [Fetch](#fetch)
+  - [`rfetch`](#rfetch)
+    - [`rfetch.get`](#rfetchget)
+    - [`rfetch.put`](#rfetchput)
+    - [`rfetch.post`](#rfetchpost)
+    - [`rfetch.patch`](#rfetchpatch)
+    - [`rfetch.remove`](#rfetchremove)
 
 ## Promises
 
@@ -96,6 +104,106 @@ const promise = never(); // Returns a promise that never resolves
 const promise = never(Promise.resolve('hello')); // Returns a promise that never resolves
 ```
 
+### `retry`
+
+Retries a function `n` times until it resolves successfully.
+This can be useful for requests that tend to be flaky.
+
+```tsx
+import { retry } from '@ribbon-studios/js-utils';
+
+// Returns a promise that resolves when the request is successful or fails after its exceeded that maximum attempts.
+const promise = retry(() => getMaps(), 5);
+```
+
+## Fetch
+
+### `rfetch`
+
+Lightweight wrapper around fetch that automatically handles:
+
+- Query Params
+- Form Data & JSON bodies
+- JSON Responses (fallsback to text)
+- Type Casting
+- Errors
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+try {
+  const response = await rfetch<MyExpectedResponse>('https://ribbonstudios.com', {
+    params: {
+      hello: 'world',
+    },
+    body: {
+      hallo: 'welt',
+    },
+  });
+
+  console.log(response);
+  // => MyExpectedResponse
+} catch (error: RibbonFetchError<MyExpectedErrorResponse>) {
+  console.error(error);
+  // => { status: number; content: MyExpectedErrorResponse; }
+}
+```
+
+### `rfetch.get`
+
+Shorthand for GET requests.
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+// Shorthand for GET requests.
+await rfetch.get<MyExpectedResponse>('https://ribbonstudios.com');
+```
+
+### `rfetch.put`
+
+Shorthand for PUT requests.
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+// Shorthand for PUT requests.
+await rfetch.put<MyExpectedResponse>('https://ribbonstudios.com');
+```
+
+### `rfetch.post`
+
+Shorthand for POST requests.
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+// Shorthand for POST requests.
+await rfetch.post<MyExpectedResponse>('https://ribbonstudios.com');
+```
+
+### `rfetch.patch`
+
+Shorthand for PATCH requests.
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+// Shorthand for PATCH requests.
+await rfetch.patch<MyExpectedResponse>('https://ribbonstudios.com');
+```
+
+### `rfetch.remove`
+
+Shorthand for DELETE requests.
+
+```tsx
+import { rfetch, type RibbonFetchError } from '@ribbon-studios/js-utils';
+
+// Shorthand for DELETE requests.
+await rfetch.remove<MyExpectedResponse>('https://ribbonstudios.com');
+```
+
 [_**Want to Contribute?**_](/CONTRIBUTING.md)
 
 [npm-version-image]: https://img.shields.io/npm/v/@ribbon-studios/js-utils.svg
@@ -107,7 +215,7 @@ const promise = never(Promise.resolve('hello')); // Returns a promise that never
 [coveralls-url]: https://coveralls.io/github/ribbon-studios/js-utils?branch=main
 [code-style-image]: https://img.shields.io/badge/code%20style-prettier-ff69b4.svg
 [code-style-url]: https://prettier.io
-[maintainability-image]: https://img.shields.io/codeclimate/maintainability/ribbon-studios/refreshly
-[maintainability-url]: https://codeclimate.com/github/ribbon-studios/refreshly/maintainability
+[maintainability-image]: https://img.shields.io/codeclimate/maintainability/ribbon-studios/js-utils
+[maintainability-url]: https://codeclimate.com/github/ribbon-studios/js-utils/maintainability
 [semantic-release-url]: https://github.com/semantic-release/semantic-release
 [semantic-release-image]: https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079

package/dist/__tests__/rfetch.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.cjs

@@ -2,8 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 async function assert(p, predicate, message) {
   const value = await p;
-  if (predicate(value))
-    return value;
+  if (predicate(value)) return value;
   throw new Error(message ?? "Value does not satisfy predicate");
 }
 ((assert2) => {
@@ -27,11 +26,100 @@ async function delay(promise, ms) {
   delay2.fallback = fallback;
 })(delay || (delay = {}));
 async function never(p) {
-  if (p)
-    console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
+  if (p) console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
   return new Promise(() => {
   });
 }
+async function retry(fn, n) {
+  let attempts = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (++attempts < n) continue;
+      throw error;
+    }
+  }
+}
+async function rfetch(url, options) {
+  var _a, _b;
+  const { params, headers, body, ...internalOptions } = {
+    method: "GET",
+    headers: {},
+    ...options
+  };
+  const internalURL = url instanceof URL ? url : new URL(url, url.startsWith("/") ? location.origin : void 0);
+  if (params) {
+    for (const [key, values] of Object.entries(params)) {
+      if (Array.isArray(values)) {
+        for (const value of values) {
+          internalURL.searchParams.append(key, value.toString());
+        }
+      } else {
+        internalURL.searchParams.append(key, values.toString());
+      }
+    }
+  }
+  let internalBody = void 0;
+  if (body) {
+    internalBody = body instanceof FormData ? body : JSON.stringify(body);
+  }
+  const response = await fetch(internalURL, {
+    ...internalOptions,
+    headers: {
+      "Content-Type": internalBody instanceof FormData ? "application/x-www-form-urlencoded" : "application/json",
+      ...headers
+    },
+    body: internalBody
+  });
+  const content = ((_b = (_a = response.headers.get("Content-Type")) == null ? void 0 : _a.toLowerCase()) == null ? void 0 : _b.includes("json")) ? await response.json() : await response.text();
+  if (response.ok) {
+    return content;
+  }
+  return Promise.reject({
+    status: response.status,
+    content
+  });
+}
+((rfetch2) => {
+  async function get(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "GET"
+    });
+  }
+  rfetch2.get = get;
+  async function put(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "PUT"
+    });
+  }
+  rfetch2.put = put;
+  async function post(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "POST"
+    });
+  }
+  rfetch2.post = post;
+  async function patch(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "PATCH"
+    });
+  }
+  rfetch2.patch = patch;
+  async function remove(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "DELETE"
+    });
+  }
+  rfetch2.remove = remove;
+})(rfetch || (rfetch = {}));
 exports.assert = assert;
 exports.delay = delay;
 exports.never = never;
+exports.retry = retry;
+exports.rfetch = rfetch;

package/dist/index.d.cts

@@ -1 +1,2 @@
 export * from './promises';
+export * from './rfetch';

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from './promises';
+export * from './rfetch';

package/dist/index.js

@@ -1,7 +1,6 @@
 async function assert(p, predicate, message) {
   const value = await p;
-  if (predicate(value))
-    return value;
+  if (predicate(value)) return value;
   throw new Error(message ?? "Value does not satisfy predicate");
 }
 ((assert2) => {
@@ -25,13 +24,102 @@ async function delay(promise, ms) {
   delay2.fallback = fallback;
 })(delay || (delay = {}));
 async function never(p) {
-  if (p)
-    console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
+  if (p) console.warn(`Promise is being called via "never", please ensure this doesn't get deployed!`, p);
   return new Promise(() => {
   });
 }
+async function retry(fn, n) {
+  let attempts = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (++attempts < n) continue;
+      throw error;
+    }
+  }
+}
+async function rfetch(url, options) {
+  var _a, _b;
+  const { params, headers, body, ...internalOptions } = {
+    method: "GET",
+    headers: {},
+    ...options
+  };
+  const internalURL = url instanceof URL ? url : new URL(url, url.startsWith("/") ? location.origin : void 0);
+  if (params) {
+    for (const [key, values] of Object.entries(params)) {
+      if (Array.isArray(values)) {
+        for (const value of values) {
+          internalURL.searchParams.append(key, value.toString());
+        }
+      } else {
+        internalURL.searchParams.append(key, values.toString());
+      }
+    }
+  }
+  let internalBody = void 0;
+  if (body) {
+    internalBody = body instanceof FormData ? body : JSON.stringify(body);
+  }
+  const response = await fetch(internalURL, {
+    ...internalOptions,
+    headers: {
+      "Content-Type": internalBody instanceof FormData ? "application/x-www-form-urlencoded" : "application/json",
+      ...headers
+    },
+    body: internalBody
+  });
+  const content = ((_b = (_a = response.headers.get("Content-Type")) == null ? void 0 : _a.toLowerCase()) == null ? void 0 : _b.includes("json")) ? await response.json() : await response.text();
+  if (response.ok) {
+    return content;
+  }
+  return Promise.reject({
+    status: response.status,
+    content
+  });
+}
+((rfetch2) => {
+  async function get(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "GET"
+    });
+  }
+  rfetch2.get = get;
+  async function put(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "PUT"
+    });
+  }
+  rfetch2.put = put;
+  async function post(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "POST"
+    });
+  }
+  rfetch2.post = post;
+  async function patch(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "PATCH"
+    });
+  }
+  rfetch2.patch = patch;
+  async function remove(url, options) {
+    return rfetch2(url, {
+      ...options,
+      method: "DELETE"
+    });
+  }
+  rfetch2.remove = remove;
+})(rfetch || (rfetch = {}));
 export {
   assert,
   delay,
-  never
+  never,
+  retry,
+  rfetch
 };

package/dist/promises/__tests__/retry.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/promises/index.d.ts

@@ -1,3 +1,4 @@
 export * from './assert';
 export * from './delay';
 export * from './never';
+export * from './retry';

package/dist/promises/retry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Attempts a request {@link n} times until it resolves.
+ *
+ * @param fn The function to invoke.
+ * @param n The maximum number of attempts
+ * @returns A resolved promise if it succeeds or the rejected promise if it exceeds {@link n}
+ */
+export declare function retry<T>(fn: () => Promise<T>, n: number): Promise<T>;

package/dist/rfetch.d.ts

@@ -0,0 +1,65 @@
+type RibbonFetchParamType = string | number | boolean;
+export type RibbonFetchOptions = {
+    method?: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE';
+    params?: Record<string, RibbonFetchParamType | RibbonFetchParamType[]>;
+    body?: any;
+    headers?: HeadersInit;
+} & Omit<RequestInit, 'body' | 'headers' | 'method'>;
+export type RibbonFetchBasicOptions = Omit<RibbonFetchOptions, 'method' | 'body'>;
+export type RibbonFetchBodyOptions = Omit<RibbonFetchOptions, 'method'>;
+export type RibbonFetchError<R> = {
+    status: number;
+    content: R;
+};
+/**
+ * A lightweight wrapper around fetch to simplify its usage.
+ *
+ * @param url The url you wish to fetch.
+ * @param options The request options.
+ * @returns The typed response or an error containing the `status` and the `content`
+ */
+export declare function rfetch<T = any>(url: string | URL, options?: RibbonFetchOptions): Promise<T>;
+export declare namespace rfetch {
+    /**
+     * Shorthand method for a GET request
+     *
+     * @param url The url you wish to fetch.
+     * @param options The request options.
+     * @returns The typed response or an error containing the `status` and the `content`
+     */
+    function get<T>(url: string | URL, options?: RibbonFetchBasicOptions): Promise<T>;
+    /**
+     * Shorthand method for a PUT request
+     *
+     * @param url The url you wish to fetch.
+     * @param options The request options.
+     * @returns The typed response or an error containing the `status` and the `content`
+     */
+    function put<T>(url: string | URL, options?: RibbonFetchBodyOptions): Promise<T>;
+    /**
+     * Shorthand method for a POST request
+     *
+     * @param url The url you wish to fetch.
+     * @param options The request options.
+     * @returns The typed response or an error containing the `status` and the `content`
+     */
+    function post<T>(url: string | URL, options?: RibbonFetchBodyOptions): Promise<T>;
+    /**
+     * Shorthand method for a PATCH request
+     *
+     * @param url The url you wish to fetch.
+     * @param options The request options.
+     * @returns The typed response or an error containing the `status` and the `content`
+     */
+    function patch<T>(url: string | URL, options?: RibbonFetchBodyOptions): Promise<T>;
+    /**
+     * Shorthand method for a DELETE request
+     *
+     * @param url The url you wish to fetch.
+     * @param options The request options.
+     * @returns The typed response or an error containing the `status` and the `content`
+     * @note This is named `remove` purely because `delete` is a reserved key
+     */
+    function remove<T>(url: string | URL, options?: RibbonFetchBodyOptions): Promise<T>;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ribbon-studios/js-utils",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Collection of generic javascript utilities curated by the Rainbow Cafe~",
   "type": "module",
   "source": "src/*.ts",
@@ -28,20 +28,23 @@
     "build": "rm -rf dist && vite build"
   },
   "devDependencies": {
-    "@types/node": "^20.11.20",
-    "@typescript-eslint/eslint-plugin": "^7.0.2",
-    "@typescript-eslint/parser": "^7.0.2",
-    "@vitest/coverage-v8": "^1.3.1",
-    "chance": "^1.1.11",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-unused-imports": "^3.1.0",
-    "happy-dom": "^13.5.0",
-    "typescript": "^5.3.3",
-    "vite": "^5.1.4",
-    "vite-plugin-dts": "^3.7.3",
-    "vite-plugin-lib-types": "^3.0.9",
-    "vitest": "^1.3.1",
+    "@eslint/js": "^9.22.0",
+    "@types/chance": "^1.1.6",
+    "@types/node": "^22.13.10",
+    "@typescript-eslint/eslint-plugin": "^8.26.0",
+    "@typescript-eslint/parser": "^8.26.0",
+    "@vitest/coverage-v8": "^3.0.8",
+    "ajv": "^8.17.1",
+    "chance": "^1.1.12",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "happy-dom": "^17.4.1",
+    "jiti": "^2.4.2",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.0",
+    "vite": "^6.2.1",
+    "vite-plugin-dts": "^4.5.3",
+    "vite-plugin-lib-types": "^3.1.2",
+    "vitest": "^3.0.8",
     "vitest-dom": "^0.1.1"
   },
   "publishConfig": {