@oscarpalmer/atoms 0.193.0 → 0.194.0

package/src/herald.ts

@@ -1,216 +0,0 @@
-import {noop} from './internal/function/misc';
-import type {GenericCallback, Unsubscriber} from './models';
-
-// #region Types
-
-export type Events<Map extends Record<string, GenericCallback>> = {
-	/**
-	 * Subscribe to an event with a callback
-	 *
-	 * @param event Event name
-	 * @param callback Callback function
-	 * @returns Unsubscriber function
-	 */
-	subscribe<Event extends keyof Map>(event: Event, callback: Map[Event]): Unsubscriber;
-
-	/**
-	 * Unsubscribe from an event with a callback _(or all callbacks, if no callback is provided)_
-	 *
-	 * @param event Event name
-	 * @param callback Callback function
-	 * @returns Unsubscriber function
-	 */
-	unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void;
-};
-
-export type Herald<Map extends Record<string, GenericCallback>> = {
-	readonly events: Events<Map>;
-
-	/**
-	 * Remove all event subscribers
-	 */
-	clear(): void;
-
-	/**
-	 * Emit an event with parameters
-	 *
-	 * @param event Event name
-	 * @param parameters Event parameters
-	 */
-	emit<Event extends keyof Map>(event: Event, ...parameters: Parameters<Map[Event]>): void;
-
-	/**
-	 * Subscribe to an event with a callback
-	 *
-	 * @param event Event name
-	 * @param callback Callback function
-	 * @returns Unsubscriber function
-	 */
-	subscribe<Event extends keyof Map>(event: Event, callback: Map[Event]): Unsubscriber;
-
-	/**
-	 * Unsubscribe from an event with a callback _(or all callbacks, if no callback is provided)_
-	 *
-	 * @param event Event name
-	 * @param callback Callback function
-	 */
-	unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void;
-};
-
-// #endregion
-
-// #region Functions
-
-function getEvents<Map extends Record<string, GenericCallback>>(herald: Herald<Map>): Events<Map> {
-	const events = {
-		subscribe: (event: string, callback: GenericCallback) =>
-			herald.subscribe(event, callback as Map[keyof Map]),
-		unsubscribe: (event: string, callback?: GenericCallback) =>
-			herald.unsubscribe(event, callback as Map[keyof Map]),
-	};
-
-	Object.defineProperty(events, KEY_HERALD, {
-		enumerable: false,
-		value: NAME_EVENTS,
-	});
-
-	return Object.freeze(events) as Events<Map>;
-}
-
-/**
- * Create a _Herald_ for announcing named events
- *
- * @param names Event names
- * @returns _Herald_ instance
- */
-export function herald<Events extends Record<string, GenericCallback>>(
-	names: (keyof Events)[],
-): Herald<Events> {
-	if (
-		!Array.isArray(names) ||
-		names.length === 0 ||
-		!names.every(name => typeof name === 'string')
-	) {
-		throw new Error(MESSAGE);
-	}
-
-	const set = new Set<keyof Events>(names);
-	const subscribers = new Map<keyof Events, Set<Events[keyof Events]>>();
-
-	const instance = {
-		clear() {
-			subscribers.clear();
-		},
-		emit<Event extends keyof Events>(event: Event, ...parameters: Parameters<Events[Event]>) {
-			const callbacks = subscribers.get(event);
-
-			if (callbacks == null) {
-				return;
-			}
-
-			for (const callback of callbacks) {
-				callback(...parameters);
-			}
-		},
-		subscribe<Event extends keyof Events>(event: Event, callback: Events[Event]): Unsubscriber {
-			if (!set.has(event) || typeof callback !== 'function') {
-				return noop;
-			}
-
-			let eventSubscribers = subscribers.get(event);
-
-			if (eventSubscribers == null) {
-				eventSubscribers = new Set();
-
-				subscribers.set(event, eventSubscribers);
-			}
-
-			eventSubscribers.add(callback);
-
-			return () => {
-				eventSubscribers?.delete(callback);
-			};
-		},
-		unsubscribe<Event extends keyof Events>(event: Event, callback?: Events[Event]): void {
-			if (!set.has(event) || (callback != null ? typeof callback !== 'function' : false)) {
-				return;
-			}
-
-			const eventSubscribers = subscribers.get(event);
-
-			if (eventSubscribers == null) {
-				return;
-			}
-
-			if (callback == null) {
-				eventSubscribers.clear();
-			} else {
-				eventSubscribers.delete(callback);
-			}
-
-			if (callback == null || eventSubscribers.size === 0) {
-				subscribers.delete(event);
-			}
-		},
-	};
-
-	Object.defineProperties(instance, {
-		[KEY_HERALD]: {
-			enumerable: false,
-			value: NAME_HERALD,
-		},
-		events: {
-			enumerable: true,
-			value: getEvents<Events>(instance as Herald<Events>),
-		},
-	});
-
-	return Object.freeze(instance) as Herald<Events>;
-}
-
-/**
- * Is the value events for a herald?
- *
- * @param value Value to check
- * @returns `true` if the value is events for a herald, otherwise `false`
- */
-export function isEvents<
-	Map extends Record<string, GenericCallback> = Record<string, GenericCallback>,
->(value: unknown): value is Events<Map> {
-	return isHeraldInstance(NAME_EVENTS, value);
-}
-
-/**
- * Is the value a herald?
- *
- * @param value Value to check
- * @returns `true` if the value is a herald, otherwise `false`
- */
-export function isHerald<
-	Events extends Record<string, GenericCallback> = Record<string, GenericCallback>,
->(value: unknown): value is Herald<Events> {
-	return isHeraldInstance(NAME_HERALD, value);
-}
-
-function isHeraldInstance<Instance>(name: string, value: unknown): value is Instance {
-	return (
-		typeof value === 'object' &&
-		value != null &&
-		KEY_HERALD in value &&
-		(value as Record<string, unknown>)[KEY_HERALD] === name
-	);
-}
-
-// #endregion
-
-// #region Variables
-
-const KEY_HERALD = '$herald';
-
-const MESSAGE = 'Herald requires an array of event names.';
-
-const NAME_EVENTS = 'events';
-
-const NAME_HERALD = 'herald';
-
-// #endregion

package/src/index.ts

@@ -1,68 +0,0 @@
-export * from './array/filter';
-export * from './array/first';
-export * from './array/group-by';
-export * from './array/index';
-export * from './array/last';
-export * from './array/move';
-export * from './array/sort';
-export * from './array/swap';
-export * from './array/to-map';
-export * from './array/to-record';
-export * from './array/unique';
-
-export * from './function/assert';
-export * from './function/index';
-export * from './function/limit';
-export * from './function/once';
-export * from './function/retry';
-export * from './function/work';
-
-export * from './herald';
-
-export * from './internal/function/misc';
-export * from './internal/string';
-export {isSubscription, type Subscription} from './internal/subscription';
-export * from './internal/value/compare';
-export * from './internal/value/equal';
-export * from './internal/value/get';
-export * from './internal/value/has';
-export * from './internal/value/set';
-
-export * from './string/case';
-export * from './string/fuzzy';
-export * from './string/index';
-export * from './string/match';
-export * from './string/normalize';
-export * from './string/template';
-
-export * from './value/clone';
-export * from './value/collection';
-export * from './value/diff';
-export * from './value/freeze';
-export * from './value/index';
-export * from './value/merge';
-export * from './value/transform';
-
-export * from './beacon';
-export * from './color';
-export * from './is';
-export * from './logger';
-export * from './math';
-export * from './models';
-export * from './number';
-export * from './promise/delay';
-export * from './promise/index';
-export * from './promise/misc';
-export * from './promise/models';
-export * from './promise/timed';
-export * from './query';
-export * from './queue';
-export * from './random';
-export * from './result/index';
-export * from './result/match';
-export * from './result/misc';
-export * from './result/models';
-export * from './result/work/flow';
-export * from './result/work/pipe';
-export * from './sized/map';
-export * from './sized/set';

package/src/internal/array/callbacks.ts

@@ -1,46 +0,0 @@
-import type {GenericCallback, PlainObject} from '../../models';
-
-// #region Types
-
-export type Callbacks = {
-	bool?: GenericCallback;
-	keyed?: GenericCallback;
-	value?: GenericCallback;
-};
-
-// #endregion
-
-// #region Functions
-
-export function getArrayCallback(value: unknown): GenericCallback | undefined {
-	switch (typeof value) {
-		case 'function':
-			return value as GenericCallback;
-
-		case 'number':
-		case 'string':
-			return typeof value === 'string' && value.includes('.')
-				? undefined
-				: (obj: PlainObject) => obj[value];
-
-		default:
-			break;
-	}
-}
-
-export function getArrayCallbacks(
-	bool?: unknown,
-	key?: unknown,
-	value?: unknown,
-): Callbacks | undefined {
-	if (typeof bool === 'function') {
-		return {bool: bool as GenericCallback};
-	}
-
-	return {
-		keyed: getArrayCallback(key),
-		value: getArrayCallback(value),
-	};
-}
-
-// #endregion

package/src/internal/array/chunk.ts

@@ -1,51 +0,0 @@
-// #region Functions
-
-/**
- * Chunk an array into smaller arrays
- *
- * @param array Array to chunk
- * @param size Size of each chunk _(minimum is `1`, maximum is `5000`; defaults to `5000`)_
- * @returns Array of arrays
- *
- * @example
- * ```typescript
- * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
- * ```
- */
-export function chunk<Item>(array: Item[], size?: number): Item[][] {
-	if (!Array.isArray(array)) {
-		return [];
-	}
-
-	if (array.length === 0) {
-		return [];
-	}
-
-	const {length} = array;
-
-	const actualSize = typeof size === 'number' && size > 0 && size <= MAX_SIZE ? size : MAX_SIZE;
-
-	if (length <= actualSize) {
-		return [array];
-	}
-
-	const chunks: Item[][] = [];
-
-	let index = 0;
-
-	while (index < length) {
-		chunks.push(array.slice(index, index + actualSize));
-
-		index += actualSize;
-	}
-
-	return chunks;
-}
-
-// #endregion
-
-// #region Variables
-
-const MAX_SIZE = 5_000;
-
-// #endregion

package/src/internal/array/compact.ts

@@ -1,56 +0,0 @@
-// #region Functions
-
-/**
- * Compact an array _(removing all false-y values)_
- *
- * @param array Array to compact
- * @param strict True to remove all false-y values
- * @returns Compacted array
- *
- * @example
- * ```typescript
- * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [1, 'hello', true]
- * ```
- */
-export function compact<Item>(
-	array: Item[],
-	strict: true,
-): Exclude<Item, 0 | '' | false | null | undefined>[];
-
-/**
- * Compact an array _(removing all `null` and `undefined` values)_
- *
- * @param array Array to compact
- * @returns Compacted array
- *
- * @example
- * ```typescript
- * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [0, 1, '', 'hello', false, true]
- * ```
- */
-export function compact<Item>(array: Item[]): Exclude<Item, null | undefined>[];
-
-export function compact<Item>(array: Item[], strict?: unknown): Item[] {
-	if (!Array.isArray(array)) {
-		return [];
-	}
-
-	if (strict === true) {
-		return array.filter(Boolean);
-	}
-
-	const {length} = array;
-	const compacted: Item[] = [];
-
-	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
-
-		if (item != null) {
-			compacted.push(item);
-		}
-	}
-
-	return compacted;
-}
-
-// #endregion

package/src/internal/array/find.ts

@@ -1,200 +0,0 @@
-import {getArrayCallback, getArrayCallbacks} from './callbacks';
-
-// #region Types
-
-type FindValueType = 'index' | 'item';
-
-type FindValuesResult = {
-	matched: unknown[];
-	notMatched: unknown[];
-};
-
-type FindValuesType = 'all' | 'unique';
-
-type Parameters = {
-	bool?: unknown;
-	key?: unknown;
-	value?: unknown;
-};
-
-// #endregion
-
-// #region Functions
-
-export function findValue(
-	type: Exclude<FindValueType, 'item'>,
-	array: unknown[],
-	parameters: unknown[],
-	reversed: boolean,
-): number;
-
-export function findValue(
-	type: Exclude<FindValueType, 'index'>,
-	array: unknown[],
-	parameters: unknown[],
-	reversed: boolean,
-): unknown;
-
-export function findValue(
-	type: FindValueType,
-	array: unknown[],
-	parameters: unknown[],
-	reversed: boolean,
-): unknown {
-	const findIndex = type === FIND_VALUE_INDEX;
-
-	if (!Array.isArray(array) || array.length === 0) {
-		return findIndex ? -1 : undefined;
-	}
-
-	const {bool, key, value} = getFindParameters(parameters);
-
-	const callbacks = getArrayCallbacks(bool, key);
-
-	if (callbacks?.bool == null && callbacks?.keyed == null) {
-		if (findIndex) {
-			return reversed ? array.lastIndexOf(value) : array.indexOf(value);
-		}
-
-		return reversed
-			? array.findLast(item => Object.is(item, value))
-			: array.find(item => Object.is(item, value));
-	}
-
-	if (callbacks.bool != null) {
-		const index = reversed ? array.findLastIndex(callbacks.bool) : array.findIndex(callbacks.bool);
-
-		return findIndex ? index : array[index];
-	}
-
-	return findValueInArray(array, callbacks.keyed, value, findIndex, reversed);
-}
-
-function findValueInArray(
-	array: unknown[],
-	callback: ((item: unknown, index: number, array: unknown[]) => boolean) | undefined,
-	value: unknown,
-	findIndex: boolean,
-	reversed: boolean,
-): unknown {
-	const {length} = array;
-
-	for (let index = 0; index < length; index += 1) {
-		const item = reversed ? array.at(-(index + 1)) : array[index];
-
-		if (Object.is(callback?.(item, index, array), value)) {
-			return findIndex ? index : item;
-		}
-	}
-
-	return findIndex ? -1 : undefined;
-}
-
-export function findAbsoluteValueOrDefault(
-	array: unknown[],
-	parameters: unknown[],
-	defaultValue: unknown,
-	useDefaultValue: boolean,
-	reversed: boolean,
-): unknown {
-	if (parameters.length === 0) {
-		if (Array.isArray(array) && array.length > 0) {
-			return reversed ? array.at(-1) : array[0];
-		}
-
-		return useDefaultValue ? defaultValue : undefined;
-	}
-
-	const index = findValue(FIND_VALUE_INDEX, array, parameters, reversed) as number;
-
-	return index > -1 ? array[index] : useDefaultValue ? defaultValue : undefined;
-}
-
-export function findValues(
-	type: FindValuesType,
-	array: unknown[],
-	parameters: unknown[],
-	mapper?: unknown,
-): FindValuesResult {
-	const result: FindValuesResult = {
-		matched: [],
-		notMatched: [],
-	};
-
-	if (!Array.isArray(array) || array.length === 0) {
-		return result;
-	}
-
-	const {length} = array;
-	const {bool, key, value} = getFindParameters(parameters);
-	const callbacks = getArrayCallbacks(bool, key);
-
-	if (type === FIND_VALUES_UNIQUE && callbacks?.keyed == null && length >= UNIQUE_THRESHOLD) {
-		result.matched = [...new Set(array)];
-
-		return result;
-	}
-
-	const mapCallback = getArrayCallback(mapper);
-
-	if (callbacks?.bool != null || (type === FIND_VALUES_ALL && key == null)) {
-		const callback = callbacks?.bool ?? (item => Object.is(item, value));
-
-		for (let index = 0; index < length; index += 1) {
-			const item = array[index];
-
-			if (callback(item, index, array)) {
-				result.matched.push(mapCallback?.(item, index, array) ?? item);
-			} else {
-				result.notMatched.push(item);
-			}
-		}
-
-		return result;
-	}
-
-	const keys = new Set();
-
-	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
-		const keyed = callbacks?.keyed?.(item, index, array) ?? item;
-
-		if (
-			(type === FIND_VALUES_ALL && Object.is(keyed, value)) ||
-			(type === FIND_VALUES_UNIQUE && !keys.has(keyed))
-		) {
-			keys.add(keyed);
-			result.matched.push(mapCallback?.(item, index, array) ?? item);
-		} else {
-			result.notMatched.push(item);
-		}
-	}
-
-	return result;
-}
-
-export function getFindParameters(original: unknown[]): Parameters {
-	const {length} = original;
-
-	return {
-		bool: length === 1 && typeof original[0] === 'function' ? original[0] : undefined,
-		key: length === 2 ? original[0] : undefined,
-		value: length === 1 && typeof original[0] !== 'function' ? original[0] : original[1],
-	};
-}
-
-// #endregion
-
-// #region Variables
-
-export const FIND_VALUE_INDEX = 'index';
-
-export const FIND_VALUE_ITEM = 'item';
-
-export const FIND_VALUES_ALL: FindValuesType = 'all';
-
-export const FIND_VALUES_UNIQUE: FindValuesType = 'unique';
-
-const UNIQUE_THRESHOLD = 100;
-
-// #endregion

package/src/internal/array/group.ts

@@ -1,42 +0,0 @@
-import type {Key} from '../../models';
-import {getArrayCallbacks} from './callbacks';
-
-// #region Functions
-
-export function groupValues(
-	array: unknown[],
-	key: unknown,
-	value: unknown,
-	arrays: boolean,
-): Record<Key, unknown> {
-	if (!Array.isArray(array) || array.length === 0) {
-		return {};
-	}
-
-	const {length} = array;
-	const callbacks = getArrayCallbacks(undefined, key, value);
-	const record: Record<Key, unknown> = {};
-
-	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
-
-		const keyed = callbacks?.keyed?.(item, index, array) ?? index;
-		const valued = callbacks?.value?.(item, index, array) ?? item;
-
-		if (arrays) {
-			const existing = record[keyed];
-
-			if (existing == null) {
-				record[keyed] = [valued];
-			} else {
-				(existing as unknown[]).push(valued);
-			}
-		} else {
-			record[keyed] = valued;
-		}
-	}
-
-	return record;
-}
-
-// #endregion