@oscarpalmer/atoms 0.147.0 → 0.149.0

package/src/index.ts

@@ -42,7 +42,7 @@ export * from './promise';
 export * from './query';
 export * from './queue';
 export * from './random';
-export * from './result';
+export * from './result/index';
 export * from './sized/map';
 export * from './sized/set';
 

package/src/internal/result.ts

@@ -0,0 +1,80 @@
+import type {Err, ExtendedErr, Ok, Result} from '../result/models';
+import {isPlainObject} from './is';
+
+// #region Functions
+
+function _isResult(value: unknown, okValue: boolean): value is Result<unknown, unknown> {
+	if (!isPlainObject(value)) {
+		return false;
+	}
+
+	return value.ok === okValue && (okValue ? 'value' : 'error') in value;
+}
+
+/**
+ * Is the result an extended error?
+ * @param result Result to check
+ * @returns `true` if the result is an extended error, `false` otherwise
+ */
+export function isError<Value, E = Error>(
+	value: ExtendedErr<E> | Result<Value, E>,
+	extended: true,
+): value is ExtendedErr<E>;
+
+/**
+ * Is the result an error?
+ * @param result Result to check
+ * @returns `true` if the result is an error, `false` otherwise
+ */
+export function isError<Value, E = Error>(value: Result<Value, E>): value is Err<E>;
+
+/**
+ * Is the value an error?
+ * @param value Value to check
+ * @returns `true` if the value is an error, `false` otherwise
+ */
+export function isError(value: unknown): value is Err<unknown> | ExtendedErr<unknown>;
+
+export function isError(
+	value: unknown,
+	extended?: boolean,
+): value is Err<unknown> | ExtendedErr<unknown> {
+	return (
+		_isResult(value, false) &&
+		(extended === true ? (value as ExtendedErr<unknown>).original instanceof Error : true)
+	);
+}
+
+/**
+ * Is the result ok?
+ * @param value Result to check
+ * @returns `true` if the result is ok, `false` otherwise
+ */
+export function isOk<Value, E = Error>(value: Result<Value, E>): value is Ok<Value>;
+
+/**
+ * Is the value ok?
+ * @param value Value to check
+ * @returns `true` if the value is ok, `false` otherwise
+ */
+export function isOk(value: unknown): value is Ok<unknown>;
+
+/**
+ * Is the result ok?
+ * @param result Result to check
+ * @returns `true` if the result is ok, `false` otherwise
+ */
+export function isOk(value: unknown): value is Ok<unknown> {
+	return _isResult(value, true);
+}
+
+/**
+ * Is the value a result?
+ * @param value Value to check
+ * @returns `true` if the value is a result, `false` otherwise
+ */
+export function isResult(value: unknown): value is ExtendedErr<unknown> | Result<unknown, unknown> {
+	return _isResult(value, true) || _isResult(value, false);
+}
+
+// #endregion

package/src/{result.ts → result/index.ts}

@@ -1,53 +1,12 @@
-import {isPlainObject} from './internal/is';
-import {attemptPromise} from './promise';
-
-// #region Types
-
-/**
- * An error result
- */
-export type Err<Error> = {
-	ok: false;
-	error: Error;
-};
-
-/**
- * An extended error result
- */
-export type ExtendedErr<E> = Err<E> & {
-	original: Error;
-};
-
-/**
- * An extended, unknown result
- */
-export type ExtendedResult<Value, E> = ExtendedErr<E> | Ok<Value>;
-
-/**
- * A successful result
- */
-export type Ok<Value> = {
-	ok: true;
-	value: Value;
-};
-
-/**
- * An unknown result
- */
-export type Result<Value, E = Error> = Err<E> | Ok<Value>;
-
-// #endregion
+import {isOk} from '../internal/result';
+import {attemptPromise} from '../promise';
+import {matchResult} from './match';
+import type {Err, ExtendedErr, ExtendedResult, Ok, Result} from './models';
+import {attemptFlow} from './work/flow';
+import {attemptPipe} from './work/pipe';
 
 // #region Functions
 
-function _isResult(value: unknown, okValue: boolean): value is Result<unknown, unknown> {
-	if (!isPlainObject(value)) {
-		return false;
-	}
-
-	return value.ok === okValue && (okValue ? 'value' : 'error') in value;
-}
-
 /**
  * Executes a promise, catching any errors, and returns a result
  * @param promise Promise to execute
@@ -107,7 +66,7 @@ async function asyncAttempt<Value, E>(
  * @param error Error value
  * @returns Callback result
  */
-export function attempt<Value, E>(callback: () => Value, error: E): ExtendedErr<E> | Ok<Value>;
+export function attempt<Value, E>(callback: () => Value, error: E): ExtendedResult<Value, E>;
 
 /**
  * Executes a callback, catching any errors, and returns a result
@@ -130,6 +89,9 @@ export function attempt<Value, E>(
 }
 
 attempt.async = asyncAttempt;
+attempt.flow = attemptFlow;
+attempt.match = matchResult;
+attempt.pipe = attemptPipe;
 attempt.promise = attemptPromise;
 
 /**
@@ -164,72 +126,6 @@ function getError<E>(value: E, original?: Error): Err<E> | ExtendedErr<E> {
 	return errorResult;
 }
 
-/**
- * Is the result an extended error?
- * @param result Result to check
- * @returns `true` if the result is an extended error, `false` otherwise
- */
-export function isError<Value, E = Error>(
-	value: ExtendedErr<E> | Result<Value, E>,
-	extended: true,
-): value is ExtendedErr<E>;
-
-/**
- * Is the result an error?
- * @param result Result to check
- * @returns `true` if the result is an error, `false` otherwise
- */
-export function isError<Value, E = Error>(value: Result<Value, E>): value is Err<E>;
-
-/**
- * Is the value an error?
- * @param value Value to check
- * @returns `true` if the value is an error, `false` otherwise
- */
-export function isError(value: unknown): value is Err<unknown> | ExtendedErr<unknown>;
-
-export function isError(
-	value: unknown,
-	extended?: boolean,
-): value is Err<unknown> | ExtendedErr<unknown> {
-	return (
-		_isResult(value, false) &&
-		(extended === true ? (value as ExtendedErr<unknown>).original instanceof Error : true)
-	);
-}
-
-/**
- * Is the result ok?
- * @param value Result to check
- * @returns `true` if the result is ok, `false` otherwise
- */
-export function isOk<Value, E = Error>(value: Result<Value, E>): value is Ok<Value>;
-
-/**
- * Is the value ok?
- * @param value Value to check
- * @returns `true` if the value is ok, `false` otherwise
- */
-export function isOk(value: unknown): value is Ok<unknown>;
-
-/**
- * Is the result ok?
- * @param result Result to check
- * @returns `true` if the result is ok, `false` otherwise
- */
-export function isOk(value: unknown): value is Ok<unknown> {
-	return _isResult(value, true);
-}
-
-/**
- * Is the value a result?
- * @param value Value to check
- * @returns `true` if the value is a result, `false` otherwise
- */
-export function isResult(value: unknown): value is ExtendedErr<unknown> | Result<unknown, unknown> {
-	return _isResult(value, true) || _isResult(value, false);
-}
-
 /**
  * Creates an ok result
  * @param value Value
@@ -263,3 +159,10 @@ export function unwrap(value: unknown, defaultValue: unknown): unknown {
 }
 
 // #endregion
+
+// #region Exports
+
+export {isError, isOk, isResult} from '../internal/result';
+export type {Err, ExtendedErr, ExtendedResult, Ok, Result} from './models';
+
+// #endregion

package/src/result/match.ts

@@ -0,0 +1,112 @@
+import {isOk, isResult} from '../internal/result';
+import type {AnyResult, ExtendedErr, ResultMatch} from './models';
+
+// #region Functions
+
+/**
+ * Handles a result with match callbacks
+ * @param result Result to handle
+ * @param handler Match callbacks
+ */
+async function asyncMatchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
+	handler: ResultMatch<Value, Returned, E>,
+): Promise<Returned>;
+
+/**
+ * Handles a result with match callbacks
+ * @param result Result to handle
+ * @param ok Ok callback
+ * @param error Error callback
+ */
+async function asyncMatchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
+	ok: ResultMatch<Value, Returned, E>['ok'],
+	error: ResultMatch<Value, Returned, E>['error'],
+): Promise<Returned>;
+
+async function asyncMatchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
+	first: ResultMatch<Value, Returned, E> | ResultMatch<Value, Returned, E>['ok'],
+	error?: ResultMatch<Value, Returned, E>['error'],
+): Promise<Returned> {
+	let value: AnyResult<Value, E>;
+
+	if (typeof result === 'function') {
+		value = await result();
+	} else if (result instanceof Promise) {
+		value = await result;
+	} else {
+		value = result;
+	}
+
+	if (!isResult(value)) {
+		throw new Error(MESSAGE_RESULT);
+	}
+
+	const hasObj = typeof first === 'object' && first !== null;
+
+	const okHandler = hasObj ? first.ok : first;
+	const errorHandler = hasObj ? first.error : error;
+
+	if (isOk(value)) {
+		return okHandler(value.value);
+	}
+
+	return errorHandler!(value.error, (value as ExtendedErr<E>).original);
+}
+
+/**
+ * Handles a result with match callbacks
+ * @param result Result to handle
+ * @param handler Match callbacks
+ */
+export function matchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
+	handler: ResultMatch<Value, Returned, E>,
+): Returned;
+
+/**
+ * Handles a result with match callbacks
+ * @param result Result to handle
+ * @param ok Ok callback
+ * @param error Error callback
+ */
+export function matchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
+	ok: ResultMatch<Value, Returned, E>['ok'],
+	error: ResultMatch<Value, Returned, E>['error'],
+): Returned;
+
+export function matchResult<Value, Returned, E = Error>(
+	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
+	first: ResultMatch<Value, Returned, E> | ResultMatch<Value, Returned, E>['ok'],
+	error?: ResultMatch<Value, Returned, E>['error'],
+): Returned {
+	const value = typeof result === 'function' ? result() : result;
+
+	if (!isResult(value)) {
+		throw new Error(MESSAGE_RESULT);
+	}
+
+	const hasObj = typeof first === 'object' && first !== null;
+
+	const okHandler = hasObj ? first.ok : first;
+	const errorHandler = hasObj ? first.error : error;
+
+	if (isOk(value)) {
+		return okHandler(value.value);
+	}
+
+	return errorHandler!(value.error, (value as ExtendedErr<E>).original);
+}
+
+matchResult.async = asyncMatchResult;
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE_RESULT = '`result.match` expected a Result or a function that returns a Result';
+
+// #endregion

package/src/result/models.ts

@@ -0,0 +1,81 @@
+import type {GenericCallback} from '../models';
+
+// #region Types
+
+/**
+ * An unknown result
+ */
+export type AnyResult<Value, E> = Err<E> | ExtendedErr<E> | Ok<Value>;
+
+/**
+ * An error result
+ */
+export type Err<Error> = {
+	ok: false;
+	error: Error;
+};
+
+/**
+ * An extended error result
+ */
+export type ExtendedErr<E> = Err<E> & {
+	original: Error;
+};
+
+/**
+ * An extended, unknown result
+ */
+export type ExtendedResult<Value, E> = ExtendedErr<E> | Ok<Value>;
+
+/**
+ * A successful result
+ */
+export type Ok<Value> = {
+	ok: true;
+	value: Value;
+};
+
+/**
+ * An unknown result
+ */
+export type Result<Value, E = Error> = Err<E> | Ok<Value>;
+
+/**
+ * Match callbacks for a result
+ */
+export type ResultMatch<Value, Returned, E = Error> = {
+	/**
+	 * Callback for error result
+	 * @param error Error value
+	 * @param original Original error, if available
+	 * @returns Value to return
+	 */
+	error: (error: E, original?: Error) => Returned;
+	/**
+	 * Callback for ok result
+	 * @param value Ok value
+	 * @returns Value to return
+	 */
+	ok: (value: Value) => Returned;
+};
+
+/**
+ * Unwrap a result value
+ */
+type UnwrapResult<Original extends Result<unknown, unknown>> =
+	Original extends Ok<infer Value> ? Value : never;
+
+/**
+ * Unwrap any value
+ */
+export type UnwrapValue<Original> = Original extends GenericCallback
+	? ReturnType<Original> extends Result<unknown, unknown>
+		? UnwrapResult<ReturnType<Original>>
+		: ReturnType<Original>
+	: Original extends Result<unknown, unknown>
+		? UnwrapResult<Original>
+		: Original extends Promise<infer Value>
+			? Awaited<Value>
+			: Original;
+
+// #endregion