@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/internal/value/equal.ts

@@ -22,6 +22,11 @@ export type EqualOptions = {
 	relaxedNullish?: boolean;
 };
 
+/**
+ * An equalizer function for comparing values for equality, with predefined options
+ *
+ * Can be used to compare values, and register or deregister equality comparison handlers for specific classes
+ */
 type Equalizer = {
 	/**
 	 * Are two strings equal?

package/src/internal/value/get.ts

@@ -1,4 +1,4 @@
-import type {NestedKeys, NestedValue, PlainObject, ToString} from '../../models';
+import type {NestedKeys, NestedValue, PlainObject} from '../../models';
 import type {Ok} from '../../result/models';
 import {getNestedValue} from './misc';
 
@@ -6,20 +6,42 @@ import {getNestedValue} from './misc';
 
 /**
  * Get the value from an object using a known path
+ *
+ * @example
+ * ```typescript
+ * const data = {foo: {bar: {baz: 42}}};
+ *
+ * getValue(data, 'foo');         // {bar: {baz: 42}}
+ * getValue(data, 'foo.bar');     // {baz: 42}
+ * getValue(data, 'foo.bar.baz'); // 42
+ * getValue(data, 'foo.nope');    // undefined
+ * ```
+ *
  * @param data Object to get value from
- * @param path Path for value, e.g., `foo.bar.baz`
+ * @param path Path for value
  * @returns Found value, or `undefined`
  */
 export function getValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
 	path: Path,
-): NestedValue<Data, ToString<Path>>;
+): NestedValue<Data, Path>;
 
 /**
  * Get the value from an object using an unknown path
+ *
+ * @example
+ * ```typescript
+ * const data = {foo: {bar: {baz: 42}}};
+ *
+ * getValue(data, 'foo');               // {bar: {baz: 42}}
+ * getValue(data, 'foo.bar');           // {baz: 42}
+ * getValue(data, 'Foo.Bar.Baz', true); // 42
+ * getValue(data, 'foo.nope');          // undefined
+ * ```
+ *
  * @param data Object to get value from
- * @param path Path for value, e.g., `foo.bar.baz`
- * @param ignoreCase If `true`, the path matching is case-insensitive
+ * @param path Path for value
+ * @param ignoreCase If `true`, path matching is case-insensitive
  * @returns Found value, or `undefined`
  */
 export function getValue<Data extends PlainObject>(

package/src/internal/value/has.ts

@@ -8,7 +8,7 @@ import {getNestedValue} from './misc';
  * Check if a nested property is defined in an object
  * @param data Object to check in
  * @param path Path for property
- * @return `true` if the property exists, `false` otherwise
+ * @returns `true` if the property exists, `false` otherwise
  */
 export function hasValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
@@ -20,7 +20,7 @@ export function hasValue<Data extends PlainObject, Path extends NestedKeys<Data>
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return `true` if the property exists, `false` otherwise
+ * @returns `true` if the property exists, `false` otherwise
  */
 export function hasValue<Data extends PlainObject>(
 	data: Data,
@@ -41,13 +41,13 @@ hasValue.get = hasValueResult;
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return Result object
+ * @returns Result object
  */
-function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
+export function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
 	path: Path,
 	ignoreCase?: boolean,
-): Result<NestedValue<Data, ToString<Path>>, undefined>;
+): Result<NestedValue<Data, ToString<Path>>, string>;
 
 /**
  * Check if a nested property is defined in an object, and get its value if it is
@@ -56,19 +56,19 @@ function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>
  * @param data Object to check in
  * @param path Path for property
  * @param ignoreCase If `true`, the path matching is case-insensitive
- * @return Result object
+ * @returns Result object
  */
-function hasValueResult<Data extends PlainObject>(
+export function hasValueResult<Data extends PlainObject>(
 	data: Data,
 	path: string,
 	ignoreCase?: boolean,
-): Result<unknown, undefined>;
+): Result<unknown, string>;
 
-function hasValueResult(
+export function hasValueResult(
 	data: PlainObject,
 	path: string,
 	ignoreCase?: boolean,
-): Result<unknown, undefined> {
+): Result<unknown, string> {
 	return getNestedValue(data, path, ignoreCase === true);
 }
 

package/src/internal/value/misc.ts

@@ -17,14 +17,13 @@ export function getNestedValue(
 	data: object,
 	path: string,
 	ignoreCase: boolean,
-): Result<unknown, undefined> {
-	if (
-		typeof data !== 'object' ||
-		data === null ||
-		typeof path !== 'string' ||
-		path.trim().length === 0
-	) {
-		return error(undefined);
+): Result<unknown, string> {
+	if (typeof data !== 'object' || data === null) {
+		return error(NESTED_MESSAGE_INPUT);
+	}
+
+	if (typeof path !== 'string' || path.trim().length === 0) {
+		return error(NESTED_MESSAGE_PATH);
 	}
 
 	const shouldIgnoreCase = ignoreCase === true;
@@ -69,7 +68,7 @@ export function handleValue(
 	value: unknown,
 	get: true,
 	ignoreCase: boolean,
-): Result<unknown, undefined>;
+): Result<unknown, string>;
 
 export function handleValue(
 	data: object,
@@ -85,19 +84,23 @@ export function handleValue(
 	value: unknown,
 	get: boolean,
 	ignoreCase: boolean,
-): Result<unknown, undefined> | void {
-	if (typeof data === 'object' && data !== null && !ignoreKey(path)) {
+): Result<unknown, string> | void {
+	if (typeof data === 'object' && data !== null) {
+		if (ignoreKey(path)) {
+			return error(NESTED_MESSAGE_UNSAFE);
+		}
+
 		const key = ignoreCase ? findKey(path, data) : path;
 
 		if (get) {
-			return key in data ? ok(data[key as never]) : error(undefined);
+			return key in data ? ok(data[key as never]) : error(NESTED_MESSAGE_MISSING);
 		}
 
 		(data as PlainObject)[key] = typeof value === 'function' ? value(data[key as never]) : value;
 	}
 
 	if (get) {
-		return error(undefined);
+		return error(NESTED_MESSAGE_MISSING);
 	}
 }
 
@@ -111,4 +114,12 @@ const EXPRESSION_DOTS = /^\.|\.$/g;
 
 const EXPRESSION_NESTED = /\.|\[\w+\]/;
 
+const NESTED_MESSAGE_INPUT = 'Expected data to be an object';
+
+const NESTED_MESSAGE_MISSING = 'Expected property to exist in object';
+
+const NESTED_MESSAGE_PATH = 'Expected path to be a string';
+
+const NESTED_MESSAGE_UNSAFE = 'Access to this property is not allowed';
+
 // #endregion

package/src/logger.ts

@@ -2,6 +2,11 @@ import {noop} from './internal/function/misc';
 
 // #region Types
 
+/**
+ * A logger that can be used to log messages to the console
+ *
+ * _(Logging can be enabled or disabled by setting the `enabled` property)_
+ */
 class Logger {
 	/**
 	 * Log any number of values at the "debug" log level
@@ -83,12 +88,18 @@ class Logger {
 	}
 }
 
+/**
+ * A named timer that can be used to log durations to the console
+ */
 class Time {
 	#logger: typeof console.timeLog | undefined;
 	#stopper: typeof console.timeEnd | undefined;
 
 	readonly #state: TimeState;
 
+	/**
+	 * Is the timer active? _(i.e. has it been started and not stopped, and is logging enabled?)_
+	 */
 	get active(): boolean {
 		return this.#state.started && !this.#state.stopped && enabled;
 	}

package/src/models.ts

@@ -260,4 +260,22 @@ export type TypedArray =
 	| BigInt64Array
 	| BigUint64Array;
 
+/**
+ * Converts a union type to an intersection type
+ *
+ * @example
+ * ```typescript
+ * type A = {a: string};
+ * type B = {b: number};
+ * type C = UnionToIntersection<A | B>; // {a: string} & {b: number}
+ * ```
+ *
+ * Thanks, type-fest!
+ */
+export type UnionToIntersection<Union> = (
+	Union extends unknown ? (distributedUnion: Union) => void : never
+) extends (mergedIntersection: infer Intersection) => void
+	? Intersection & Union
+	: never;
+
 // #endregion

package/src/promise/index.ts

@@ -24,8 +24,6 @@ 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
@@ -37,8 +35,6 @@ 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
@@ -50,8 +46,6 @@ 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

package/src/promise/models.ts

@@ -3,6 +3,9 @@ import type {Result} from '../result/models';
 
 // #region Types
 
+/**
+ * A promise that can be canceled
+ */
 export class CancelablePromise<Value = void> extends Promise<Value> {
 	#rejector!: (reason: unknown) => void;
 
@@ -29,8 +32,17 @@ export class CancelablePromise<Value = void> extends Promise<Value> {
 	}
 }
 
+/**
+ * A promise that was fulfilled
+ */
 export type FulfilledPromise<Value> = {
+	/**
+	 * Status of the promise
+	 */
 	status: typeof PROMISE_TYPE_FULFILLED;
+	/**
+	 * Value of the promise
+	 */
 	value: Awaited<Value>;
 };
 
@@ -44,6 +56,9 @@ export type PromiseHandlers = {
 	reject: (reason: unknown) => void;
 };
 
+/**
+ * Options for a promise-handling function
+ */
 export type PromiseOptions = {
 	/**
 	 * AbortSignal for aborting the promise; when aborted, the promise will reject with the reason of the signal
@@ -75,6 +90,9 @@ export type PromiseParameters = {
  */
 export type PromiseStrategy = 'complete' | 'first';
 
+/**
+ * An error thrown when a promise times out
+ */
 export class PromiseTimeoutError extends Error {
 	constructor() {
 		super(PROMISE_MESSAGE_TIMEOUT);
@@ -93,8 +111,17 @@ export type PromisesItems<Items extends unknown[]> = {
 			: Promise<Items[ItemsKey]>;
 };
 
+/**
+ * Options for handling multiple promises
+ */
 export type PromisesOptions = {
+	/**
+	 * AbortSignal for aborting the promises; when aborted, the promises will reject with the reason of the signal
+	 */
 	signal?: AbortSignal;
+	/**
+	 * Strategy for handling the promises; defaults to `complete`
+	 */
 	strategy?: PromiseStrategy;
 };
 
@@ -126,8 +153,17 @@ export type PromisesValues<Items extends unknown[]> = {
 			: never;
 };
 
+/**
+ * A promise that was rejected
+ */
 export type RejectedPromise = {
+	/**
+	 * Status of the promise
+	 */
 	status: typeof PROMISE_TYPE_REJECTED;
+	/**
+	 * Reason for the rejection
+	 */
 	reason: unknown;
 };
 

package/src/queue.ts

@@ -5,6 +5,9 @@ import type {GenericAsyncCallback, GenericCallback} from './models';
 
 type HandleType = 'clear' | 'pause' | 'resume';
 
+/**
+ * A queue that can be used to manage (a)synchronous tasks with a specific key
+ */
 class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
 	readonly #callback: GenericAsyncCallback;
 
@@ -240,6 +243,9 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 	}
 }
 
+/**
+ * A queue that can be used to manage (a)synchronous tasks
+ */
 class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
 	readonly #callback: GenericAsyncCallback;
 
@@ -487,6 +493,9 @@ class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, Callbac
 	}
 }
 
+/**
+ * An error thrown by the Queue when an operation fails
+ */
 class QueueError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -510,9 +519,12 @@ type QueueOptions = {
 	maximum?: number;
 };
 
+/**
+ * A queued item
+ */
 type Queued<Value> = {
 	/**
-	 * ID of the queued promise _(can be used to remove it from the queue)_
+	 * ID of the queued item _(can be used to remove it from the queue)_
 	 */
 	readonly id: number;
 	/**

package/src/result/index.ts

@@ -1,9 +1,5 @@
-import {attemptPromise} from '../promise';
-import {matchResult} from './match';
 import {getError, ok} from './misc';
 import type {ExtendedErr, ExtendedResult, Result} from './models';
-import {attemptFlow} from './work/flow';
-import {attemptPipe} from './work/pipe';
 
 // #region Functions
 
@@ -99,9 +95,5 @@ export function attempt<Value, E>(
 }
 
 attempt.async = asyncAttempt;
-attempt.flow = attemptFlow;
-attempt.match = matchResult;
-attempt.pipe = attemptPipe;
-attempt.promise = attemptPromise;
 
 // #endregion

package/src/result/match.ts

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

@@ -29,7 +29,7 @@ export type AttemptFlowPromise<Callback extends GenericCallback, Value> = (
 /**
  * Create an asynchronous Flow, a function that attempts to pipe a value through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<Fn extends GenericCallback>(
@@ -39,7 +39,7 @@ export function attemptAsyncFlow<Fn extends GenericCallback>(
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<First extends GenericCallback, Second>(
@@ -50,7 +50,7 @@ export function attemptAsyncFlow<First extends GenericCallback, Second>(
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<First extends GenericCallback, Second, Third>(
@@ -62,7 +62,7 @@ export function attemptAsyncFlow<First extends GenericCallback, Second, Third>(
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<First extends GenericCallback, Second, Third, Fourth>(
@@ -75,7 +75,7 @@ export function attemptAsyncFlow<First extends GenericCallback, Second, Third, F
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth>(
@@ -89,7 +89,7 @@ export function attemptAsyncFlow<First extends GenericCallback, Second, Third, F
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<
@@ -111,7 +111,7 @@ export function attemptAsyncFlow<
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<
@@ -135,7 +135,7 @@ export function attemptAsyncFlow<
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<
@@ -161,7 +161,7 @@ export function attemptAsyncFlow<
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<
@@ -189,7 +189,7 @@ export function attemptAsyncFlow<
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<
@@ -219,7 +219,7 @@ export function attemptAsyncFlow<
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow<Fn extends GenericCallback>(
@@ -230,7 +230,7 @@ export function attemptAsyncFlow<Fn extends GenericCallback>(
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
  *
- * Available as `attemptAsyncFlow` and `attempt.flow.async`
+ * Available as `attemptAsyncFlow` and `attemptFlow.async`
  * @returns Flow function
  */
 export function attemptAsyncFlow(
@@ -264,16 +264,12 @@ export function attemptAsyncFlow(
 
 /**
  * Create a Flow, a function that attempts to pipe values through a function
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<Fn extends GenericCallback>(fn: Fn): AttemptFlow<Fn, ReturnType<Fn>>;
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback, Second>(
@@ -283,8 +279,6 @@ export function attemptFlow<First extends GenericCallback, Second>(
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback, Second, Third>(
@@ -295,8 +289,6 @@ export function attemptFlow<First extends GenericCallback, Second, Third>(
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback, Second, Third, Fourth>(
@@ -308,8 +300,6 @@ export function attemptFlow<First extends GenericCallback, Second, Third, Fourth
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback, Second, Third, Fourth, Fifth>(
@@ -322,8 +312,6 @@ export function attemptFlow<First extends GenericCallback, Second, Third, Fourth
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback, Second, Third, Fourth, Fifth, Sixth>(
@@ -337,8 +325,6 @@ export function attemptFlow<First extends GenericCallback, Second, Third, Fourth
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<
@@ -361,8 +347,6 @@ export function attemptFlow<
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<
@@ -387,8 +371,6 @@ export function attemptFlow<
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<
@@ -415,8 +397,6 @@ export function attemptFlow<
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<
@@ -445,8 +425,6 @@ export function attemptFlow<
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow<First extends GenericCallback>(
@@ -456,8 +434,6 @@ export function attemptFlow<First extends GenericCallback>(
 
 /**
  * Create a Flow, a function that attempts to pipe values through a series of functions
- *
- * Available as `attemptFlow` and `attempt.flow`
  * @returns Flow function
  */
 export function attemptFlow(...fns: GenericCallback[]): (...args: unknown[]) => Result<unknown>;