@oscarpalmer/atoms 0.179.0 → 0.180.0

package/src/internal/value/equal.ts

@@ -1,6 +1,5 @@
-import {isPrimitive} from '../is';
 import type {ArrayOrPlainObject, Constructor, PlainObject, TypedArray} from '../../models';
-import {isPlainObject, isTypedArray} from '../is';
+import {isPlainObject, isPrimitive, isTypedArray} from '../is';
 import {getCompareHandlers} from './handlers';
 
 // #region Types
@@ -24,6 +23,15 @@ export type EqualOptions = {
 };
 
 type Equalizer = {
+	/**
+	 * Are two strings equal?
+	 * @param first First string
+	 * @param second Second string
+	 * @param ignoreCase If `true`, comparison will be case-insensitive
+	 * @returns `true` if the strings are equal, otherwise `false`
+	 */
+	(first: string, second: string, ignoreCase?: boolean): boolean;
+
 	/**
 	 * Are two values equal?
 	 * @param first First value
@@ -32,21 +40,21 @@ type Equalizer = {
 	 */
 	(first: unknown, second: unknown): boolean;
 
+	/**
+	 * Deregister a equality comparison handler for a specific class
+	 * @param constructor Class constructor
+	 */
+	deregister: <Instance>(constructor: Constructor<Instance>) => void;
+
 	/**
 	 * Register a equality comparison function for a specific class
 	 * @param constructor Class constructor
-	 * @param fn Comparison function
+	 * @param handler Comparison function
 	 */
 	register: <Instance>(
 		constructor: Constructor<Instance>,
 		handler: (first: Instance, second: Instance) => boolean,
 	) => void;
-
-	/**
-	 * Unregister a equality comparison handler for a specific class
-	 * @param constructor Class constructor
-	 */
-	unregister: <Instance>(constructor: Constructor<Instance>) => void;
 };
 
 type Options = {
@@ -65,6 +73,35 @@ type OptionsKeys<Values> = {
 
 // #region Functions
 
+/**
+ * Deregister a equality comparison handler for a specific class
+ *
+ * Available as `deregisterEqualizer` and `equal.deregister`
+ * @param constructor Class constructor
+ */
+export function deregisterEqualizer<Instance>(constructor: Constructor<Instance>): void {
+	equal.handlers.deregister(constructor);
+}
+
+function filterKey(key: string | symbol, options: Options): boolean {
+	if (typeof key !== 'string') {
+		return true;
+	}
+
+	if (
+		options.ignoreExpressions.enabled &&
+		options.ignoreExpressions.values.some(expression => expression.test(key))
+	) {
+		return false;
+	}
+
+	if (options.ignoreKeys.enabled && options.ignoreKeys.values.has(key)) {
+		return false;
+	}
+
+	return true;
+}
+
 /**
  * Are two strings equal?
  * @param first First string
@@ -91,12 +128,10 @@ equal.handlers = getCompareHandlers<boolean>(equal, {
 	callback: Object.is,
 });
 
+equal.deregister = deregisterEqualizer;
 equal.initialize = initializeEqualizer;
-
 equal.register = registerEqualizer;
 
-equal.unregister = unregisterEqualizer;
-
 function equalArray(first: unknown[], second: unknown[], options: Options): boolean {
 	const {length} = first;
 
@@ -322,61 +357,6 @@ function equalValue(first: unknown, second: unknown, options: Options): boolean
 	}
 }
 
-/**
- * Create an equalizer with predefined options
- * @param options Comparison options
- * @returns Equalizer function
- */
-function initializeEqualizer(options?: EqualOptions): Equalizer {
-	const actual = getEqualOptions(options);
-
-	const equalizer = (first: unknown, second: unknown): boolean => equalValue(first, second, actual);
-
-	equalizer.register = registerEqualizer;
-	equalizer.unregister = unregisterEqualizer;
-
-	return equalizer;
-}
-
-/**
- * Register a equality comparison function for a specific class
- * @param constructor Class constructor
- * @param fn Comparison function
- */
-function registerEqualizer<Instance>(
-	constructor: Constructor<Instance>,
-	handler: (first: Instance, second: Instance) => boolean,
-): void {
-	equal.handlers.register(constructor, handler);
-}
-
-/**
- * Unregister a equality comparison handler for a specific class
- * @param constructor Class constructor
- */
-function unregisterEqualizer<Instance>(constructor: Constructor<Instance>): void {
-	equal.handlers.unregister(constructor);
-}
-
-function filterKey(key: string | symbol, options: Options): boolean {
-	if (typeof key !== 'string') {
-		return true;
-	}
-
-	if (
-		options.ignoreExpressions.enabled &&
-		options.ignoreExpressions.values.some(expression => expression.test(key))
-	) {
-		return false;
-	}
-
-	if (options.ignoreKeys.enabled && options.ignoreKeys.values.has(key)) {
-		return false;
-	}
-
-	return true;
-}
-
 function getEqualOptions(input?: boolean | EqualOptions): Options {
 	const options: Options = {
 		ignoreCase: false,
@@ -422,6 +402,38 @@ function getEqualOptions(input?: boolean | EqualOptions): Options {
 	return options;
 }
 
+/**
+ * Create an equalizer with predefined options
+ *
+ * Available as `initializeEqualizer` and `equal.initialize`
+ * @param options Comparison options
+ * @returns Equalizer function
+ */
+export function initializeEqualizer(options?: EqualOptions): Equalizer {
+	const actual = getEqualOptions(options);
+
+	const equalizer = (first: unknown, second: unknown): boolean => equalValue(first, second, actual);
+
+	equalizer.deregister = deregisterEqualizer;
+	equalizer.register = registerEqualizer;
+
+	return equalizer;
+}
+
+/**
+ * Register a equality comparison function for a specific class
+ *
+ * Available as `registerEqualizer` and `equal.register`
+ * @param constructor Class constructor
+ * @param handler Comparison function
+ */
+export function registerEqualizer<Instance>(
+	constructor: Constructor<Instance>,
+	handler: (first: Instance, second: Instance) => boolean,
+): void {
+	equal.handlers.register(constructor, handler);
+}
+
 // #endregion
 
 // #region Variables

package/src/internal/value/handlers.ts

@@ -7,13 +7,14 @@ type Options = {
 };
 
 export function getCompareHandlers<Value>(owner: GenericCallback, options: Options) {
-	const {get, register, unregister} = getHandlers(owner, options);
+	const handlers = getHandlers(owner, options);
 
 	return {
-		register,
-		unregister,
+		deregister(constructor: Constructor) {
+			handlers.deregister(constructor);
+		},
 		handle(first: unknown, second: unknown, ...parameters: unknown[]): Value {
-			const handler = get(first, second);
+			const handler = handlers.get(first, second);
 
 			if (handler == null) {
 				return options.callback(first, second, ...parameters);
@@ -23,6 +24,9 @@ export function getCompareHandlers<Value>(owner: GenericCallback, options: Optio
 				? handler(first, second)
 				: (first as any)[handler](second);
 		},
+		register(constructor: Constructor, handler?: string | GenericCallback) {
+			handlers.register(constructor, handler);
+		},
 	};
 }
 
@@ -30,6 +34,9 @@ function getHandlers(owner: GenericCallback, options: Options) {
 	const handlers = new WeakMap<Constructor, string | GenericCallback>();
 
 	return {
+		deregister(constructor: Constructor) {
+			handlers.delete(constructor);
+		},
 		get(first: unknown, second: unknown): string | GenericCallback | undefined {
 			if (
 				isConstructable(first) &&
@@ -58,20 +65,18 @@ function getHandlers(owner: GenericCallback, options: Options) {
 				handlers.set(constructor, actual);
 			}
 		},
-		unregister(constructor: Constructor) {
-			handlers.delete(constructor);
-		},
 	};
 }
 
 export function getSelfHandlers(owner: GenericCallback, options: Options) {
-	const {get, register, unregister} = getHandlers(owner, options);
+	const handlers = getHandlers(owner, options);
 
 	return {
-		register,
-		unregister,
+		deregister(constructor: Constructor) {
+			handlers.deregister(constructor);
+		},
 		handle(value: unknown, ...parameters: unknown[]) {
-			const handler = get(value, value);
+			const handler = handlers.get(value, value);
 
 			if (handler == null) {
 				return options.callback(value, ...parameters);
@@ -79,6 +84,9 @@ export function getSelfHandlers(owner: GenericCallback, options: Options) {
 
 			return typeof handler === 'function' ? handler(value) : (value as any)[handler]();
 		},
+		register(constructor: Constructor, handler?: string | GenericCallback) {
+			handlers.register(constructor, handler);
+		},
 	};
 }
 

package/src/internal/value/has.ts

@@ -1,15 +1,7 @@
 import type {NestedKeys, NestedValue, PlainObject, ToString} from '../../models';
+import type {Result} from '../../result/models';
 import {getNestedValue} from './misc';
 
-// #region Types
-
-export type HasValue<Value> = {
-	exists: boolean;
-	value: Value;
-};
-
-// #endregion
-
 // #region Functions
 
 /**
@@ -37,38 +29,46 @@ export function hasValue<Data extends PlainObject>(
 ): boolean;
 
 export function hasValue(data: PlainObject, path: string, ignoreCase?: boolean): boolean {
-	return getNestedValue(data, path, ignoreCase === true).exists;
+	return getNestedValue(data, path, ignoreCase === true).ok;
 }
 
-hasValue.get = getWithHasValue;
+hasValue.get = hasValueResult;
 
 /**
  * Check if a nested property is defined in an object, and get its value if it is
+ *
+ * Available as `hasValueResult` and `hasValue.get`
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
  * @return Result object
  */
-function getWithHasValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
+function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
 	path: Path,
 	ignoreCase?: boolean,
-): HasValue<NestedValue<Data, ToString<Path>>>;
+): Result<NestedValue<Data, ToString<Path>>, undefined>;
 
 /**
  * Check if a nested property is defined in an object, and get its value if it is
+ *
+ * Available as `hasValueResult` and `hasValue.get`
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
  * @return Result object
  */
-function getWithHasValue<Data extends PlainObject>(
+function hasValueResult<Data extends PlainObject>(
 	data: Data,
 	path: string,
 	ignoreCase?: boolean,
-): HasValue<unknown>;
+): Result<unknown, undefined>;
 
-function getWithHasValue(data: PlainObject, path: string, ignoreCase?: boolean): HasValue<unknown> {
+function hasValueResult(
+	data: PlainObject,
+	path: string,
+	ignoreCase?: boolean,
+): Result<unknown, undefined> {
 	return getNestedValue(data, path, ignoreCase === true);
 }
 

package/src/internal/value/misc.ts

@@ -1,4 +1,6 @@
 import type {PlainObject} from '../../models';
+import {error, ok} from '../../result/misc';
+import type {Result} from '../../result/models';
 import {ignoreKey} from '../string';
 
 // #region Functions
@@ -15,14 +17,14 @@ export function getNestedValue(
 	data: object,
 	path: string,
 	ignoreCase: boolean,
-): {exists: boolean; value: unknown} {
+): Result<unknown, undefined> {
 	if (
 		typeof data !== 'object' ||
 		data === null ||
 		typeof path !== 'string' ||
 		path.trim().length === 0
 	) {
-		return {exists: false, value: undefined};
+		return error(undefined);
 	}
 
 	const shouldIgnoreCase = ignoreCase === true;
@@ -41,14 +43,14 @@ export function getNestedValue(
 
 		const handled = handleValue(current, part, null, true, shouldIgnoreCase);
 
-		if (!handled.exists) {
+		if (!handled.ok) {
 			return handled;
 		}
 
 		current = handled.value as object;
 	}
 
-	return {exists: true, value: current};
+	return ok(current);
 }
 
 export function getPaths(path: string, lowercase: boolean): string | string[] {
@@ -67,7 +69,7 @@ export function handleValue(
 	value: unknown,
 	get: true,
 	ignoreCase: boolean,
-): {exists: boolean; value: unknown};
+): Result<unknown, undefined>;
 
 export function handleValue(
 	data: object,
@@ -83,19 +85,19 @@ export function handleValue(
 	value: unknown,
 	get: boolean,
 	ignoreCase: boolean,
-): {exists: boolean; value: unknown} | void {
+): Result<unknown, undefined> | void {
 	if (typeof data === 'object' && data !== null && !ignoreKey(path)) {
 		const key = ignoreCase ? findKey(path, data) : path;
 
 		if (get) {
-			return {exists: key in data, value: data[key as never]};
+			return key in data ? ok(data[key as never]) : error(undefined);
 		}
 
 		(data as PlainObject)[key] = typeof value === 'function' ? value(data[key as never]) : value;
 	}
 
 	if (get) {
-		return {exists: false, value: undefined};
+		return error(undefined);
 	}
 }
 

package/src/promise/index.ts

@@ -24,6 +24,8 @@ import {getTimedPromise} from './timed';
 
 /**
  * Wrap a promise with safety handlers, with optional abort capabilities and timeout
+ *
+ * Available as `attemptPromise` and `attempt.promise`
  * @param promise Promise to wrap
  * @param options Options for the promise
  * @returns Wrapped promise
@@ -35,6 +37,8 @@ export async function attemptPromise<Value>(
 
 /**
  * Wrap a promise-returning callback with safety handlers, with optional abort capabilities and timeout
+ *
+ * Available as `attemptPromise` and `attempt.promise`
  * @param callback Callback to wrap
  * @param options Options for the promise
  * @returns Promise-wrapped callback
@@ -46,6 +50,8 @@ export async function attemptPromise<Value>(
 
 /**
  * Wrap a callback with a promise and safety handlers, with optional abort capabilities and timeout
+ *
+ * Available as `attemptPromise` and `attempt.promise`
  * @param callback Callback to wrap
  * @param options Options for the promise
  * @returns Promise-wrapped callback
@@ -99,7 +105,7 @@ export async function attemptPromise<Value>(
 	const promise = new Promise<Value>((resolve, reject) => {
 		rejector = reject;
 
-		handler(resolve, reject);
+		void handler(resolve, reject);
 	});
 
 	return time > 0 ? getTimedPromise(promise, time, signal) : promise;
@@ -253,11 +259,13 @@ promises.result = resultPromises;
  * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
  *
  * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
+ *
+ * Available as `resultPromises` and `promises.result`
  * @param items List of promises
  * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
  * @returns List of results
  */
-async function resultPromises<Items extends unknown[]>(
+export async function resultPromises<Items extends unknown[]>(
 	items: [...Items],
 	signal?: AbortSignal,
 ): Promise<PromisesResult<PromisesItems<Items>>>;
@@ -266,16 +274,18 @@ async function resultPromises<Items extends unknown[]>(
  * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
  *
  * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
+ *
+ * Available as `resultPromises` and `promises.result`
  * @param items List of promises
  * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
  * @returns List of results
  */
-async function resultPromises<Value>(
+export async function resultPromises<Value>(
 	items: Promise<Value>[],
 	signal?: AbortSignal,
 ): Promise<Result<Awaited<Value>>[]>;
 
-async function resultPromises(
+export async function resultPromises(
 	items: Promise<unknown>[],
 	signal?: AbortSignal,
 ): Promise<Result<unknown>[]> {

package/src/result/index.ts

@@ -9,41 +9,51 @@ import {attemptPipe} from './work/pipe';
 
 /**
  * Executes a promise, catching any errors, and returns a result
+ *
+ * Available as `asyncAttempt` and `attempt.async`
  * @param promise Promise to execute
  * @param error Error value
  * @returns Callback result
  */
-async function asyncAttempt<Value, E>(
+export async function asyncAttempt<Value, E>(
 	promise: Promise<Value>,
 	error: E,
 ): Promise<ExtendedResult<Awaited<Value>, E>>;
 
 /**
  * Executes a callback asynchronously, catching any errors, and returns a result
+ *
+ * Available as `asyncAttempt` and `attempt.async`
  * @param callback Callback to execute
  * @param error Error value
  * @returns Callback result
  */
-async function asyncAttempt<Value, E>(
+export async function asyncAttempt<Value, E>(
 	callback: () => Promise<Value>,
 	error: E,
 ): Promise<ExtendedResult<Awaited<Value>, E>>;
 
 /**
  * Executes a promise, catching any errors, and returns a result
+ *
+ * Available as `asyncAttempt` and `attempt.async`
  * @param promise Promise to execute
  * @returns Callback result
  */
-async function asyncAttempt<Value>(promise: Promise<Value>): Promise<Result<Awaited<Value>>>;
+export async function asyncAttempt<Value>(promise: Promise<Value>): Promise<Result<Awaited<Value>>>;
 
 /**
  * Executes a callback asynchronously, catching any errors, and returns a result
+ *
+ * Available as `asyncAttempt` and `attempt.async`
  * @param callback Callback to execute
  * @returns Callback result
  */
-async function asyncAttempt<Value>(callback: () => Promise<Value>): Promise<Result<Awaited<Value>>>;
+export async function asyncAttempt<Value>(
+	callback: () => Promise<Value>,
+): Promise<Result<Awaited<Value>>>;
 
-async function asyncAttempt<Value, E>(
+export async function asyncAttempt<Value, E>(
 	value: Promise<Value> | (() => Promise<Value>),
 	err?: E,
 ): Promise<unknown> {

package/src/result/match.ts

@@ -8,7 +8,7 @@ import type {AnyResult, ExtendedErr, ResultMatch} from './models';
  * @param result Result to handle
  * @param handler Match callbacks
  */
-async function asyncMatchResult<Value, Returned, E = Error>(
+export 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>;
@@ -19,13 +19,13 @@ async function asyncMatchResult<Value, Returned, E = Error>(
  * @param ok Ok callback
  * @param error Error callback
  */
-async function asyncMatchResult<Value, Returned, E = Error>(
+export 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>(
+export 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'],
@@ -58,6 +58,8 @@ async function asyncMatchResult<Value, Returned, E = Error>(
 
 /**
  * Handles a result with match callbacks
+ *
+ * Available as `matchResult` and `attempt.match`
  * @param result Result to handle
  * @param handler Match callbacks
  */
@@ -68,6 +70,8 @@ export function matchResult<Value, Returned, E = Error>(
 
 /**
  * Handles a result with match callbacks
+ *
+ * Available as `matchResult` and `attempt.match`
  * @param result Result to handle
  * @param ok Ok callback
  * @param error Error callback

package/src/result/misc.ts

@@ -5,7 +5,7 @@ import type {AnyResult, Err, ExtendedErr, Ok, Result} from './models';
 
 /**
  * Creates an extended error result
- * @param error Error value
+ * @param value Error value
  * @param original Original error
  * @returns Error result
  */
@@ -13,7 +13,7 @@ export function error<E>(value: E, original: Error): ExtendedErr<E>;
 
 /**
  * Creates an error result
- * @param error Error value
+ * @param value Error value
  * @returns Error result
  */
 export function error<E>(value: E): Err<E>;
@@ -51,7 +51,7 @@ export function ok<Value>(value: Value): Ok<Value> {
  * Converts a result to a promise
  *
  * Resolves if ok, rejects for error
- * @param result Result to convert
+ * @param callback Callback to get the result
  * @returns Promised result
  */
 export async function toPromise<Value, E = Error>(