utilful 1.2.1 → 2.0.0

package/README.md

@@ -10,10 +10,10 @@ A collection of TypeScript utilities that I use across my projects.
   - [CSV](#csv)
   - [Emitter](#emitter)
   - [JSON](#json)
-  - [Lazy](#lazy)
   - [Module](#module)
   - [Object](#object)
   - [Path](#path)
+  - [Result](#result)
   - [String](#string)
 
 ## Installation
@@ -168,29 +168,6 @@ Clones the given JSON value.
 declare function cloneJSON<T>(value: T): T
 ```
 
-### Lazy
-
-A simple general purpose memoizer utility.
-
-- Lazily computes a value when accessed
-- Auto-caches the result by overwriting the getter
-- Typesafe
-
-Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
-
-```ts
-declare function lazy<T>(getter: () => T): { value: T }
-```
-
-**Example:**
-
-```ts
-const myValue = lazy(() => 'Hello, World!')
-console.log(myValue.value) // Computes value, overwrites getter
-console.log(myValue.value) // Returns cached value
-console.log(myValue.value) // Returns cached value
-```
-
 ### Module
 
 #### `interopDefault`
@@ -215,6 +192,28 @@ async function loadModule() {
 
 ### Object
 
+#### `memoize`
+
+A simple general purpose memoizer utility.
+
+- Lazily computes a value when accessed
+- Auto-caches the result by overwriting the getter
+
+Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+
+```ts
+declare function memoize<T>(getter: () => T): { value: T }
+```
+
+**Example:**
+
+```ts
+const myValue = lazy(() => 'Hello, World!')
+console.log(myValue.value) // Computes value, overwrites getter
+console.log(myValue.value) // Returns cached value
+console.log(myValue.value) // Returns cached value
+```
+
 #### `objectKeys`
 
 Strictly typed `Object.keys`.
@@ -327,6 +326,133 @@ const url = withQuery('https://example.com', {
 })
 ```
 
+### Result
+
+The `Result` type that represents either success (`Ok`) or failure (`Err`). It helps to handle errors in a more explicit and type-safe way, without relying on exceptions.
+
+A common use case for `Result` is error handling in functions that might fail. Here's an example of a function that divides two numbers and returns a `Result`:
+
+```ts
+import { err, ok } from 'utilful'
+
+function divide(a: number, b: number) {
+  if (b === 0) {
+    return err('Division by zero')
+  }
+  return ok(a / b)
+}
+
+const result = divide(10, 2)
+if (result.ok)
+  console.log('Result:', result.value)
+else
+  console.error('Error:', result.error)
+```
+
+#### `Result`
+
+The `Result` type represents either success (`Ok`) or failure (`Err`).
+
+**Type Definition:**
+
+```ts
+type Result<T, E> = Ok<T> | Err<E>
+```
+
+#### `Ok`
+
+The `Ok` type wraps a successful value.
+
+**Example:**
+
+```ts
+const result = new Ok(42)
+```
+
+#### `Err`
+
+The `Err` type wraps an error value.
+
+**Example:**
+
+```ts
+const result = new Err('Something went wrong')
+```
+
+#### `ok`
+
+Shorthand function to create an `Ok` result. Use it to wrap a successful value.
+
+**Type Definition:**
+
+```ts
+function ok<T>(value: T): Ok<T>
+```
+
+#### `err`
+
+Shorthand function to create an `Err` result. Use it to wrap an error value.
+
+**Type Definition:**
+
+```ts
+function err<E extends string = string>(err: E): Err<E>
+function err<E = unknown>(err: E): Err<E>
+```
+
+#### `toResult`
+
+Wraps a function that might throw an error and returns a `Result` with the result of the function.
+
+**Type Definition:**
+
+```ts
+function toResult<T, E = unknown>(fn: () => T): Result<T, E>
+function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>
+```
+
+#### `unwrapResult`
+
+Unwraps a `Result`, `Ok`, or `Err` value and returns the value or error in an object. If the result is an `Ok`, the object contains the value and an `undefined` error. If the result is an `Err`, the object contains an `undefined` value and the error.
+
+**Example:**
+
+```ts
+const result = toResult(() => JSON.parse('{"foo":"bar"}'))
+const { value, error } = unwrapResult(result)
+```
+
+**Type Definition:**
+
+```ts
+function unwrapResult<T>(result: Ok<T>): { value: T, error: undefined }
+function unwrapResult<E>(result: Err<E>): { value: undefined, error: E }
+function unwrapResult<T, E>(result: Result<T, E>): { value: T, error: undefined } | { value: undefined, error: E }
+```
+
+#### `tryCatch`
+
+A simpler alternative to `toResult` + `unwrapResult`. It executes a function that might throw an error and directly returns the result in a `ResultData` format. Works with both synchronous functions and promises.
+
+**Example:**
+
+```ts
+import { tryCatch } from 'utilful'
+
+// Synchronous usage
+const { value, error } = tryCatch(() => JSON.parse('{"foo":"bar"}'))
+
+// Asynchronous usage
+const { value, error } = await tryCatch(fetch('https://api.example.com/data').then(r => r.json()))
+```
+
+**Type Definition:**
+
+```ts
+function tryCatch<T, E = unknown>(fn: () => T): { value: T, error: undefined } | { value: undefined, error: E }
+function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<{ value: T, error: undefined } | { value: undefined, error: E }>
+```
+
 ### String
 
 #### `template`

package/dist/csv.d.mts

@@ -34,8 +34,8 @@ declare function createCSV<T extends Record<string, unknown>>(data: T[], columns
  * Within quoted values, double quotes are escaped by doubling them.
  *
  * @example
- * escapeCSVValue('hello, world'); // "hello, world"
- * escapeCSVValue('contains "quotes"'); // "contains ""quotes"""
+ * escapeCSVValue('hello, world') // "hello, world"
+ * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
  */
 declare function escapeCSVValue(value: unknown, options?: {
     /** @default ',' */

package/dist/csv.d.ts

@@ -34,8 +34,8 @@ declare function createCSV<T extends Record<string, unknown>>(data: T[], columns
  * Within quoted values, double quotes are escaped by doubling them.
  *
  * @example
- * escapeCSVValue('hello, world'); // "hello, world"
- * escapeCSVValue('contains "quotes"'); // "contains ""quotes"""
+ * escapeCSVValue('hello, world') // "hello, world"
+ * escapeCSVValue('contains "quotes"') // "contains ""quotes"""
  */
 declare function escapeCSVValue(value: unknown, options?: {
     /** @default ',' */

package/dist/index.d.mts

@@ -2,9 +2,9 @@ export { MaybeArray, toArray } from './array.mjs';
 export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
 export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from './emitter.mjs';
 export { cloneJSON, tryParseJSON } from './json.mjs';
-export { lazy } from './lazy.mjs';
 export { interopDefault } from './module.mjs';
-export { deepApply, objectEntries, objectKeys } from './object.mjs';
+export { deepApply, memoize, objectEntries, objectKeys } from './object.mjs';
 export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.mjs';
+export { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from './result.mjs';
 export { generateRandomId, template } from './string.mjs';
 export { AutocompletableString, LooseAutocomplete, UnifyIntersection } from './types.mjs';

package/dist/index.d.ts

@@ -2,9 +2,9 @@ export { MaybeArray, toArray } from './array.js';
 export { CSVRow, createCSV, escapeCSVValue, parseCSV } from './csv.js';
 export { Emitter, EventHandlerList, EventHandlerMap, EventType, Handler, WildCardEventHandlerList, WildcardHandler, createEmitter } from './emitter.js';
 export { cloneJSON, tryParseJSON } from './json.js';
-export { lazy } from './lazy.js';
 export { interopDefault } from './module.js';
-export { deepApply, objectEntries, objectKeys } from './object.js';
+export { deepApply, memoize, objectEntries, objectKeys } from './object.js';
 export { QueryObject, QueryValue, getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.js';
+export { Err, ErrData, Ok, OkData, Result, ResultData, err, ok, toResult, tryCatch, unwrapResult } from './result.js';
 export { generateRandomId, template } from './string.js';
 export { AutocompletableString, LooseAutocomplete, UnifyIntersection } from './types.js';

package/dist/index.mjs

@@ -2,8 +2,8 @@ export { toArray } from './array.mjs';
 export { createCSV, escapeCSVValue, parseCSV } from './csv.mjs';
 export { createEmitter } from './emitter.mjs';
 export { cloneJSON, tryParseJSON } from './json.mjs';
-export { lazy } from './lazy.mjs';
 export { interopDefault } from './module.mjs';
-export { deepApply, objectEntries, objectKeys } from './object.mjs';
+export { deepApply, memoize, objectEntries, objectKeys } from './object.mjs';
 export { getPathname, joinURL, withBase, withLeadingSlash, withQuery, withTrailingSlash, withoutBase, withoutLeadingSlash, withoutTrailingSlash } from './path.mjs';
+export { Err, Ok, err, ok, toResult, tryCatch, unwrapResult } from './result.mjs';
 export { generateRandomId, template } from './string.mjs';

package/dist/object.d.mts

@@ -1,3 +1,20 @@
+/**
+ * A simple general purpose memoizer utility.
+ * - Lazily computes a value when accessed
+ * - Auto-caches the result by overwriting the getter
+ *
+ * @remarks
+ * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+ *
+ * @example
+ * const myValue = lazy(() => 'Hello, World!')
+ * console.log(myValue.value) // Computes value, overwrites getter
+ * console.log(myValue.value) // Returns cached value
+ * console.log(myValue.value) // Returns cached value
+ */
+declare function memoize<T>(getter: () => T): {
+    value: T;
+};
 /**
  * Strictly typed `Object.keys`.
  */
@@ -11,4 +28,4 @@ declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof
  */
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
 
-export { deepApply, objectEntries, objectKeys };
+export { deepApply, memoize, objectEntries, objectKeys };

package/dist/object.d.ts

@@ -1,3 +1,20 @@
+/**
+ * A simple general purpose memoizer utility.
+ * - Lazily computes a value when accessed
+ * - Auto-caches the result by overwriting the getter
+ *
+ * @remarks
+ * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
+ *
+ * @example
+ * const myValue = lazy(() => 'Hello, World!')
+ * console.log(myValue.value) // Computes value, overwrites getter
+ * console.log(myValue.value) // Returns cached value
+ * console.log(myValue.value) // Returns cached value
+ */
+declare function memoize<T>(getter: () => T): {
+    value: T;
+};
 /**
  * Strictly typed `Object.keys`.
  */
@@ -11,4 +28,4 @@ declare function objectEntries<T extends Record<any, any>>(obj: T): Array<[keyof
  */
 declare function deepApply<T extends Record<any, any>>(data: T, callback: (item: T, key: keyof T, value: T[keyof T]) => void): void;
 
-export { deepApply, objectEntries, objectKeys };
+export { deepApply, memoize, objectEntries, objectKeys };

package/dist/object.mjs

@@ -1,3 +1,12 @@
+function memoize(getter) {
+  return {
+    get value() {
+      const value = getter();
+      Object.defineProperty(this, "value", { value });
+      return value;
+    }
+  };
+}
 function objectKeys(obj) {
   return Object.keys(obj);
 }
@@ -22,4 +31,4 @@ function isObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
 
-export { deepApply, objectEntries, objectKeys };
+export { deepApply, memoize, objectEntries, objectKeys };

package/dist/result.d.mts

@@ -0,0 +1,32 @@
+type Result<T, E> = Ok<T> | Err<E>;
+interface OkData<T> {
+    value: T;
+    error: undefined;
+}
+interface ErrData<E> {
+    value: undefined;
+    error: E;
+}
+type ResultData<T, E> = OkData<T> | ErrData<E>;
+declare class Ok<T> {
+    readonly value: T;
+    readonly ok = true;
+    constructor(value: T);
+}
+declare class Err<E> {
+    readonly error: E;
+    readonly ok = false;
+    constructor(error: E);
+}
+declare function ok<T>(value: T): Ok<T>;
+declare function err<E extends string = string>(error: E): Err<E>;
+declare function err<E = unknown>(error: E): Err<E>;
+declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>;
+declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>;
+declare function unwrapResult<T>(result: Ok<T>): OkData<T>;
+declare function unwrapResult<E>(result: Err<E>): ErrData<E>;
+declare function unwrapResult<T, E>(result: Result<T, E>): ResultData<T, E>;
+declare function tryCatch<T, E = unknown>(fn: () => T): ResultData<T, E>;
+declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<ResultData<T, E>>;
+
+export { Err, type ErrData, Ok, type OkData, type Result, type ResultData, err, ok, toResult, tryCatch, unwrapResult };

package/dist/result.d.ts

@@ -0,0 +1,32 @@
+type Result<T, E> = Ok<T> | Err<E>;
+interface OkData<T> {
+    value: T;
+    error: undefined;
+}
+interface ErrData<E> {
+    value: undefined;
+    error: E;
+}
+type ResultData<T, E> = OkData<T> | ErrData<E>;
+declare class Ok<T> {
+    readonly value: T;
+    readonly ok = true;
+    constructor(value: T);
+}
+declare class Err<E> {
+    readonly error: E;
+    readonly ok = false;
+    constructor(error: E);
+}
+declare function ok<T>(value: T): Ok<T>;
+declare function err<E extends string = string>(error: E): Err<E>;
+declare function err<E = unknown>(error: E): Err<E>;
+declare function toResult<T, E = unknown>(fn: () => T): Result<T, E>;
+declare function toResult<T, E = unknown>(promise: Promise<T>): Promise<Result<T, E>>;
+declare function unwrapResult<T>(result: Ok<T>): OkData<T>;
+declare function unwrapResult<E>(result: Err<E>): ErrData<E>;
+declare function unwrapResult<T, E>(result: Result<T, E>): ResultData<T, E>;
+declare function tryCatch<T, E = unknown>(fn: () => T): ResultData<T, E>;
+declare function tryCatch<T, E = unknown>(promise: Promise<T>): Promise<ResultData<T, E>>;
+
+export { Err, type ErrData, Ok, type OkData, type Result, type ResultData, err, ok, toResult, tryCatch, unwrapResult };

package/dist/result.mjs

@@ -0,0 +1,43 @@
+class Ok {
+  value;
+  ok = true;
+  constructor(value) {
+    this.value = value;
+  }
+}
+class Err {
+  error;
+  ok = false;
+  constructor(error) {
+    this.error = error;
+  }
+}
+function ok(value) {
+  return new Ok(value);
+}
+function err(error) {
+  return new Err(error);
+}
+function toResult(fnOrPromise) {
+  if (fnOrPromise instanceof Promise) {
+    return fnOrPromise.then(ok).catch(err);
+  }
+  try {
+    return ok(fnOrPromise());
+  } catch (error) {
+    return err(error);
+  }
+}
+function unwrapResult(result) {
+  return result.ok ? { value: result.value, error: void 0 } : { value: void 0, error: result.error };
+}
+function tryCatch(fnOrPromise) {
+  if (fnOrPromise instanceof Promise) {
+    return toResult(fnOrPromise).then(
+      (result) => unwrapResult(result)
+    );
+  }
+  return unwrapResult(toResult(fnOrPromise));
+}
+
+export { Err, Ok, err, ok, toResult, tryCatch, unwrapResult };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "utilful",
   "type": "module",
-  "version": "1.2.1",
+  "version": "2.0.0",
   "packageManager": "pnpm@10.5.2",
   "description": "A collection of TypeScript utilities",
   "author": "Johann Schopplich <hello@johannschopplich.com>",
@@ -36,10 +36,6 @@
       "types": "./dist/json.d.mts",
       "default": "./dist/json.mjs"
     },
-    "./lazy": {
-      "types": "./dist/lazy.d.mts",
-      "default": "./dist/lazy.mjs"
-    },
     "./module": {
       "types": "./dist/module.d.mts",
       "default": "./dist/module.mjs"
@@ -52,6 +48,10 @@
       "types": "./dist/path.d.mts",
       "default": "./dist/path.mjs"
     },
+    "./result": {
+      "types": "./dist/result.d.mts",
+      "default": "./dist/result.mjs"
+    },
     "./string": {
       "types": "./dist/string.d.mts",
       "default": "./dist/string.mjs"
@@ -61,7 +61,7 @@
       "default": "./dist/types.mjs"
     }
   },
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],

package/dist/lazy.d.mts

@@ -1,20 +0,0 @@
-/**
- * A simple general purpose memoizer utility.
- * - Lazily computes a value when accessed
- * - Auto-caches the result by overwriting the getter
- * - Typesafe
- *
- * @remarks
- * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
- *
- * @example
- * const myValue = lazy(() => 'Hello, World!')
- * console.log(myValue.value) // Computes value, overwrites getter
- * console.log(myValue.value) // Returns cached value
- * console.log(myValue.value) // Returns cached value
- */
-declare function lazy<T>(getter: () => T): {
-    value: T;
-};
-
-export { lazy };

package/dist/lazy.d.ts

@@ -1,20 +0,0 @@
-/**
- * A simple general purpose memoizer utility.
- * - Lazily computes a value when accessed
- * - Auto-caches the result by overwriting the getter
- * - Typesafe
- *
- * @remarks
- * Useful for deferring initialization or expensive operations. Unlike a simple getter, there is no runtime overhead after the first invokation, since the getter itself is overwritten with the memoized value.
- *
- * @example
- * const myValue = lazy(() => 'Hello, World!')
- * console.log(myValue.value) // Computes value, overwrites getter
- * console.log(myValue.value) // Returns cached value
- * console.log(myValue.value) // Returns cached value
- */
-declare function lazy<T>(getter: () => T): {
-    value: T;
-};
-
-export { lazy };

package/dist/lazy.mjs

@@ -1,11 +0,0 @@
-function lazy(getter) {
-  return {
-    get value() {
-      const value = getter();
-      Object.defineProperty(this, "value", { value });
-      return value;
-    }
-  };
-}
-
-export { lazy };