@dvirus-js/utils 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0 (2026-02-17)
+
+This was a version bump only for utils to align it with other projects, there were no code changes.

package/README.md

@@ -0,0 +1,99 @@
+# Utils Library
+
+This package provides a collection of utility functions for string manipulation, data transformation, async handling, HTTP requests, and more. It is designed to be a shared resource for other packages in the monorepo.
+
+## Available Utilities
+
+### `convert-cases.ts`
+Convert strings between various case formats (camelCase, PascalCase, snake_case, kebab-case, etc.) and normalize strings.
+
+```typescript
+import { convertCase, normalizeString } from './lib/convert-cases';
+
+const input = 'HelloWorld_example-string';
+console.log(normalizeString(input)); // 'hello world example string'
+console.log(convertCase(input, 'snake_case')); // 'hello_world_example_string'
+console.log(convertCase(input, 'camelCase')); // 'helloWorldExampleString'
+```
+
+### `tryCatch.ts`
+Async error handling for promises, returning a tuple of [result, error].
+
+```typescript
+import { tryCatch } from './lib/tryCatch';
+
+const [data, error] = await tryCatch(fetch('/api/data'));
+if (error) {
+  // handle error
+}
+```
+
+### `http.ts`
+Simple HTTP client for GET, POST, PUT, PATCH, DELETE requests using fetch.
+
+```typescript
+import { http } from './lib/http';
+
+const data = await http.get('/api/data');
+const created = await http.post('/api/data', { name: 'test' });
+```
+
+### `group-by.ts`
+Group array items by a key.
+
+```typescript
+import { groupBy } from './lib/group-by';
+
+const arr = [ { type: 'a', v: 1 }, { type: 'b', v: 2 }, { type: 'a', v: 3 } ];
+const grouped = groupBy(arr, x => x.type);
+// { a: [{type:'a',v:1},{type:'a',v:3}], b: [{type:'b',v:2}] }
+```
+
+### `delay.ts`
+Delay execution, clamp values, and debounce functions.
+
+```typescript
+import { delay, clamp, debounce } from './lib/delay';
+
+await delay(500); // waits 500ms
+const clamped = clamp(0, 10, 5); // 5
+const debounced = debounce(() => console.log('run'), 300);
+debounced();
+```
+
+### `getProp.ts`
+Get a deeply nested property from an object using a string path, with type safety.
+
+```typescript
+import { getProp } from './lib/getProp';
+
+const obj = { a: { b: { c: 42 } } };
+const value = getProp(obj, 'a.b.c'); // 42
+```
+
+### `Result.ts`
+A Result type for functional error handling (ok/err pattern).
+
+```typescript
+import { Result } from './lib/Result';
+
+const res = Result.func(() => JSON.parse('{bad json}'));
+if (res.isErr()) {
+  console.error(res.error);
+}
+```
+
+### `toObject.ts`
+Convert an array to an object by key, or ensure a value is always an array.
+
+```typescript
+import { toObject, toArray } from './lib/toObject';
+
+const arr = [{ id: 1 }, { id: 2 }];
+const obj = toObject(arr, x => x.id); // { '1': {id:1}, '2': {id:2} }
+const arr2 = toArray('foo'); // ['foo']
+```
+
+---
+
+This library was generated with [Nx](https://nx.dev).

package/index.d.ts

@@ -0,0 +1,8 @@
+export * from './lib/convert-cases';
+export * from './lib/tryCatch';
+export * from './lib/http';
+export * from './lib/group-by';
+export * from './lib/delay';
+export * from './lib/getProp';
+export * from './lib/Result';
+export * from './lib/toObject';

package/index.js

@@ -0,0 +1,326 @@
+function u(t) {
+  return t.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+}
+function l(t, e) {
+  const r = u(t);
+  switch (e) {
+    case "lowercase":
+      return r.toLowerCase();
+    case "UPPERCASE":
+      return r.toUpperCase();
+    case "Title Case":
+      return r.split(" ").map(
+        (n) => n.charAt(0).toUpperCase() + n.slice(1).toLowerCase()
+      ).join(" ");
+    case "kebab-case":
+      return r.replace(/\s+/g, "-");
+    case "snake_case":
+      return r.replace(/\s+/g, "_");
+    case "camelCase": {
+      const n = r.split(" ");
+      return n.length === 0 ? "" : n[0].toLowerCase() + n.slice(1).map(
+        (s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()
+      ).join("");
+    }
+    case "PascalCase":
+      return r.split(" ").map(
+        (n) => n.charAt(0).toUpperCase() + n.slice(1).toLowerCase()
+      ).join("");
+    case "dot.case":
+      return r.replace(/\s+/g, ".");
+    case "path/case":
+      return r.replace(/\s+/g, "/");
+    case "Sentence case":
+      return r.replace(/(^\s*\w|[.!?]\s*\w)/g, (n) => n.toUpperCase()).replace(/\bi\b/g, "I");
+    case "Header-Case":
+      return r.split(" ").map(
+        (n) => n.charAt(0).toUpperCase() + n.slice(1).toLowerCase()
+      ).join("-");
+    case "reverse":
+      return r.split("").reverse().join("");
+    default:
+      throw new Error(`Unsupported case type: ${e}`);
+  }
+}
+async function p(t) {
+  try {
+    return [await t, null];
+  } catch (e) {
+    return [null, e];
+  }
+}
+const h = {
+  /**
+   * Makes a GET request to the specified URL.
+   *
+   * @param {string} url - The URL to send the GET request to.
+   * @param {RequestInit} [options] - Optional request options.
+   * @returns {Promise<any>} The response data.
+   * @throws {Error} If the response is not ok.
+   */
+  get: async function(t, e) {
+    const r = await fetch(t, e);
+    return await o(r);
+  },
+  /**
+   * Makes a POST request to the specified URL with the given data.
+   *
+   * @template R
+   * @param {string} url - The URL to send the POST request to.
+   * @param {unknown} data - The data to send in the request body.
+   * @param {RequestInit} [options] - Optional request options.
+   * @returns {Promise<R>} The response data.
+   * @throws {Error} If the response is not ok.
+   */
+  post: async function(t, e, r) {
+    const n = await fetch(t, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...r?.headers
+      },
+      body: JSON.stringify(e),
+      ...r
+    });
+    return await o(n);
+  },
+  /**
+   * Makes a DELETE request to the specified URL with the given ID.
+   *
+   * @template R
+   * @param {string} url - The URL to send the DELETE request to.
+   * @param {string} id - The ID to send in the request body.
+   * @param {RequestInit} [options] - Optional request options.
+   * @returns {Promise<R>} The response data.
+   * @throws {Error} If the response is not ok.
+   */
+  delete: async function(t, e, r) {
+    const n = await fetch(t, {
+      method: "DELETE",
+      headers: {
+        "Content-Type": "application/json",
+        ...r?.headers
+      },
+      body: JSON.stringify({ id: e }),
+      ...r
+    });
+    return await o(n);
+  },
+  /**
+   * Makes a PATCH request to the specified URL with the given data.
+   *
+   * @template R
+   * @param {string} url - The URL to send the PATCH request to.
+   * @param {unknown} data - The data to send in the request body.
+   * @param {RequestInit} [options] - Optional request options.
+   * @returns {Promise<R>} The response data.
+   * @throws {Error} If the response is not ok.
+   */
+  patch: async function(t, e, r) {
+    const n = await fetch(t, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        ...r?.headers
+      },
+      body: JSON.stringify(e),
+      ...r
+    });
+    return await o(n);
+  },
+  /**
+   * Makes a PUT request to the specified URL with the given data.
+   *
+   * @template R
+   * @param {string} url - The URL to send the PUT request to.
+   * @param {unknown} data - The data to send in the request body.
+   * @param {RequestInit} [options] - Optional request options.
+   * @returns {Promise<R>} The response data.
+   * @throws {Error} If the response is not ok.
+   */
+  put: async function(t, e, r) {
+    const n = await fetch(t, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        ...r?.headers
+      },
+      body: JSON.stringify(e),
+      ...r
+    });
+    return await o(n);
+  }
+};
+async function o(t) {
+  if (!t.ok) throw new Error(`Error: ${t.statusText}`);
+  return await t.json();
+}
+function f(t, e) {
+  const r = {};
+  return t?.forEach((n, s) => {
+    const a = e(n, s, t);
+    a && (r[a] ??= [], r[a].push(n));
+  }), r;
+}
+async function w(t) {
+  return await new Promise((e) => setTimeout(e, t));
+}
+function d(t, e, r) {
+  return e < t ? t : e > r ? r : e;
+}
+function y(t, e) {
+  let r;
+  return (...n) => {
+    clearTimeout(r), r = setTimeout(() => t(...n), e);
+  };
+}
+function g(t, e) {
+  if (!e || typeof e != "string" || typeof t != "object" || t === null)
+    return;
+  const r = e.split(".");
+  function n(s, a) {
+    if (!a || typeof a != "object")
+      return;
+    const c = s[0];
+    if (c in a)
+      return s.length === 1 ? a[c] : n(s.slice(1), a[c]);
+  }
+  return n(r, t);
+}
+class i {
+  #e = null;
+  #r = null;
+  /**
+   * Creates a successful result.
+   * @param {T} val - The success value.
+   * @returns {Result<T, never>} A Result instance representing a success.
+   */
+  static ok(e) {
+    return new i(e, null);
+  }
+  /**
+   * Creates a failed result.
+   * @param {E | string} err - The error value or message.
+   * @returns {Result<never, E>} A Result instance representing a failure.
+   */
+  static err(e) {
+    return typeof e == "string" ? new i(null, new Error(e)) : new i(null, e);
+  }
+  /**
+   * Wraps a promise in a Result.
+   * @param {Promise<T>} promise - The promise to wrap.
+   * @returns {Promise<Result<T, E>>} A promise that resolves to a Result.
+   */
+  static async promise(e) {
+    return e.then((r) => i.ok(r ?? "void")).catch((r) => i.err(r));
+  }
+  /**
+   * Wraps a function call in a Result.
+   * @param {(...args: any[]) => T} func - The function to call.
+   * @param {...any[]} args - The arguments to pass to the function.
+   * @returns {Result<T, E>} A Result instance representing the function call result.
+   */
+  static func(e, ...r) {
+    try {
+      const n = e(...r);
+      return i.ok(n);
+    } catch (n) {
+      return i.err(n);
+    }
+  }
+  /**
+   * @param {T | null} ok - The success value.
+   * @param {E | null} err - The error value.
+   * @throws {Error} If both ok and err are provided or neither is provided.
+   */
+  constructor(e, r) {
+    if (!e && !r)
+      throw new Error("Result must be initialized with either an ok or an err value");
+    if (e && r)
+      throw new Error("Result can't be initialized with both an ok and an err value");
+    e != null ? this.#e = e : this.#r = r;
+  }
+  /**
+   * Gets the success value, throwing an error if the result is a failure.
+   * @returns {T} The success value.
+   * @throws {Error} If the result is a failure.
+   */
+  get value() {
+    return this.expect("add error handling");
+  }
+  /**
+   * Unwraps the result, returning the success value or throwing the error.
+   * @returns {T} The success value.
+   * @throws {E} If the result is a failure.
+   */
+  unwrap() {
+    if (this.isOk())
+      return this.#e;
+    throw this.isErr() ? this.#r : new Error("Unknown error");
+  }
+  /**
+   * Unwraps the result, returning the success value or a default value if the result is a failure.
+   * @param {T} defaultValue - The default value to return if the result is a failure.
+   * @returns {T} The success value or the default value.
+   */
+  unwrapOr(e) {
+    return this.isOk() ? this.#e : e;
+  }
+  /**
+   * Gets the success value, throwing a custom error message if the result is a failure.
+   * @param {string} msg - The custom error message.
+   * @returns {T} The success value.
+   * @throws {Error} If the result is a failure.
+   */
+  expect(e) {
+    if (this.isOk())
+      return this.#e;
+    if (this.isErr()) {
+      const r = this.#r;
+      throw new Error(e + `:
+` + r.message);
+    }
+    throw new Error(e);
+  }
+  /**
+   * Checks if the result is a success.
+   * @returns {boolean} True if the result is a success, false otherwise.
+   */
+  isOk() {
+    return this.#e != null;
+  }
+  /**
+   * Checks if the result is a failure.
+   * @returns {boolean} True if the result is a failure, false otherwise.
+   */
+  isErr() {
+    return this.#r != null;
+  }
+  /**
+   * Gets the error value.
+   * @returns {E | null} The error value, or null if the result is a success.
+   */
+  get error() {
+    return this.#r;
+  }
+}
+function C(t, e) {
+  return t.reduce((r, n) => (r[e(n).toString()] = n, r), {});
+}
+function E(t, e = []) {
+  return t == null ? e : Array.isArray(t) ? t : [t];
+}
+export {
+  i as Result,
+  d as clamp,
+  l as convertCase,
+  y as debounce,
+  w as delay,
+  g as getProp,
+  f as groupBy,
+  h as http,
+  u as normalizeString,
+  E as toArray,
+  C as toObject,
+  p as tryCatch
+};

package/lib/Result.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A class representing a result of an operation that can either be a success (ok) or a failure (err).
+ * @template T - The type of the success value.
+ * @template E - The type of the error value, extending Error.
+ */
+export declare class Result<T, E extends Error = Error> {
+    #private;
+    /**
+     * Creates a successful result.
+     * @param {T} val - The success value.
+     * @returns {Result<T, never>} A Result instance representing a success.
+     */
+    static ok<T>(val: T): Result<T, never>;
+    /**
+     * Creates a failed result.
+     * @param {E | string} err - The error value or message.
+     * @returns {Result<never, E>} A Result instance representing a failure.
+     */
+    static err<E extends Error>(err: E | string): Result<never, E>;
+    /**
+     * Wraps a promise in a Result.
+     * @param {Promise<T>} promise - The promise to wrap.
+     * @returns {Promise<Result<T, E>>} A promise that resolves to a Result.
+     */
+    static promise<T, E extends Error = Error>(promise: Promise<T>): Promise<Result<T, E>>;
+    /**
+     * Wraps a function call in a Result.
+     * @param {(...args: any[]) => T} func - The function to call.
+     * @param {...any[]} args - The arguments to pass to the function.
+     * @returns {Result<T, E>} A Result instance representing the function call result.
+     */
+    static func<T, E extends Error = Error, TParam extends Array<unknown> = []>(func: (...args: TParam) => T, ...args: TParam): Result<T, E>;
+    /**
+     * @param {T | null} ok - The success value.
+     * @param {E | null} err - The error value.
+     * @throws {Error} If both ok and err are provided or neither is provided.
+     */
+    constructor(ok: T | null, err: E | null);
+    /**
+     * Gets the success value, throwing an error if the result is a failure.
+     * @returns {T} The success value.
+     * @throws {Error} If the result is a failure.
+     */
+    get value(): T;
+    /**
+     * Unwraps the result, returning the success value or throwing the error.
+     * @returns {T} The success value.
+     * @throws {E} If the result is a failure.
+     */
+    unwrap(): T;
+    /**
+     * Unwraps the result, returning the success value or a default value if the result is a failure.
+     * @param {T} defaultValue - The default value to return if the result is a failure.
+     * @returns {T} The success value or the default value.
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Gets the success value, throwing a custom error message if the result is a failure.
+     * @param {string} msg - The custom error message.
+     * @returns {T} The success value.
+     * @throws {Error} If the result is a failure.
+     */
+    expect(msg: string): T;
+    /**
+     * Checks if the result is a success.
+     * @returns {boolean} True if the result is a success, false otherwise.
+     */
+    isOk(): this is Result<T, never>;
+    /**
+     * Checks if the result is a failure.
+     * @returns {boolean} True if the result is a failure, false otherwise.
+     */
+    isErr(): this is Result<never, E>;
+    /**
+     * Gets the error value.
+     * @returns {E | null} The error value, or null if the result is a success.
+     */
+    get error(): this extends Result<never, E> ? E : E | null;
+}

package/lib/convert-cases.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalizes any string to lowercase with spaces
+ * Handles various cases like special characters, extra spaces, and different formats
+ * @param input - The string to normalize
+ * @returns A normalized string in lowercase with single spaces
+ */
+export declare function normalizeString(input: string): string;
+/**
+ * Converts a string to various cases
+ * @param input - The string to convert
+ * @param caseType - The target case type
+ * @returns The string converted to the specified case
+ */
+export type CaseType = 'lowercase' | 'UPPERCASE' | 'Title Case' | 'kebab-case' | 'snake_case' | 'camelCase' | 'PascalCase' | 'dot.case' | 'path/case' | 'Sentence case' | 'Header-Case' | 'reverse';
+export declare function convertCase(input: string, caseType: CaseType): string;

package/lib/delay.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Delay for a given time
+ * @param ms - Time in milliseconds
+ * @returns Promise
+ */
+export declare function delay(ms: number): Promise<unknown>;
+/**
+ * Clamp a value between a minimum and maximum value
+ * @param min - Minimum value
+ * @param value - Value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+export declare function clamp(min: number, value: number, max: number): number;
+/**
+ * Debounce a function
+ * @param func - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: any[]) => void>(func: T, delay: number): (...args: Parameters<T>) => void;

package/lib/getProp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A utility type to get the value type at a given path in an object.
+ *
+ * @template T - The type of the object.
+ * @template P - The path as a string.
+ */
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : undefined : P extends keyof T ? T[P] : undefined;
+/**
+ * Retrieves the value at a given path in an object.
+ *
+ * @template T - The type of the object.
+ * @template P - The path as a string.
+ * @param {T} obj - The object to retrieve the value from.
+ * @param {P} path - The path to the value in the object.
+ * @returns {PathValue<T, P>} The value at the given path, or undefined if the path is invalid.
+ */
+export declare function getProp<T, P extends string>(obj: T, path: P): PathValue<T, P>;

package/lib/group-by.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Groups the elements of an array based on the provided keyGetter function.
+ *
+ * @param value - The array to group.
+ * @param {function(item T, number, array T[]): string | number} keyGetter - A function that takes an element, its
+ * index, and
+ * the array, and returns a key to group by.
+ * @returns {Record<string, array T>} - An object where the keys are the results of the keyGetter function and the
+ * values are arrays of elements that correspond to those keys.
+ */
+export declare function groupBy<T>(value: T[], keyGetter: (item: T, index: number, array: T[]) => string | number): Record<string, T[]>;

package/lib/http.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A utility object for making HTTP requests.
+ */
+export declare const http: {
+    /**
+     * Makes a GET request to the specified URL.
+     *
+     * @param {string} url - The URL to send the GET request to.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<any>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    get: <R = any>(url: string, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a POST request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the POST request to.
+     * @param {unknown} data - The data to send in the request body.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<R>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    post: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a DELETE request to the specified URL with the given ID.
+     *
+     * @template R
+     * @param {string} url - The URL to send the DELETE request to.
+     * @param {string} id - The ID to send in the request body.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<R>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    delete: <R = any>(url: string, id: string, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a PATCH request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the PATCH request to.
+     * @param {unknown} data - The data to send in the request body.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<R>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    patch: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+    /**
+     * Makes a PUT request to the specified URL with the given data.
+     *
+     * @template R
+     * @param {string} url - The URL to send the PUT request to.
+     * @param {unknown} data - The data to send in the request body.
+     * @param {RequestInit} [options] - Optional request options.
+     * @returns {Promise<R>} The response data.
+     * @throws {Error} If the response is not ok.
+     */
+    put: <R = any>(url: string, data: unknown, options?: RequestInit) => Promise<R>;
+};

package/lib/toObject.d.ts

@@ -0,0 +1,4 @@
+export declare function toObject<T extends Record<string, any> | string | number>(list: T[], keyGetter: (item: T) => string | number | {
+    toString: () => string;
+}): Record<string, T>;
+export declare function toArray<T>(obj: T | T[] | undefined | null, defaultValue?: T[]): T[];

package/lib/tryCatch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Types for the result tuple with discriminated union
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ */
+export type TryResult<T, E = Error> = [T, null] | [null, E];
+/**
+ * Main wrapper function to handle promise with try-catch
+ * @template T - Type of the successful result
+ * @template E - Type of the error, defaults to Error
+ * @param {Promise<T>} promise - The promise to handle
+ * @returns {Promise<TryResult<T, E>>} - A promise that resolves to a tuple with either the result or the error
+ */
+export declare function tryCatch<T, E = Error>(promise: Promise<T>): Promise<TryResult<T, E>>;

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@dvirus-js/utils",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}