@ribbon-studios/js-utils 1.1.1 → 1.2.0

package/README.md

@@ -19,6 +19,13 @@ Collection of generic javascript utilities curated by the Rainbow Cafe~
   - [`assert`](#assert)
     - [`assert.defined`](#assertdefined)
   - [`never`](#never)
+- [Fetch](#fetch)
+  - [`rfetch`](#rfetch)
+    - [`rfetch.get`](#rfetchget)
+    - [`rfetch.put`](#rfetchput)
+    - [`rfetch.post`](#rfetchpost)
+    - [`rfetch.patch`](#rfetchpatch)
+    - [`rfetch.remove`](#rfetchremove)
 
 ## Promises
 
@@ -96,6 +103,94 @@ const promise = never(); // Returns a promise that never resolves
 const promise = never(Promise.resolve('hello')); // Returns a promise that never resolves
 ```
 
+## 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

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

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

package/dist/index.cjs

@@ -32,6 +32,84 @@ async function never(p) {
   return new Promise(() => {
   });
 }
+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.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

@@ -30,8 +30,86 @@ async function never(p) {
   return new Promise(() => {
   });
 }
+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,
+  rfetch
 };

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.2.0",
   "description": "Collection of generic javascript utilities curated by the Rainbow Cafe~",
   "type": "module",
   "source": "src/*.ts",