@oscarpalmer/atoms 0.180.0 → 0.182.0

package/src/internal/math/aggregate.ts

@@ -1,5 +1,5 @@
 import type {NumericalValues, PlainObject} from '../../models';
-import {isNumber} from '../is';
+import {isNonNumber} from '../is';
 
 // #region Types
 
@@ -40,7 +40,7 @@ export function aggregate(type: AggregationType, array: unknown[], key: unknown)
 
 		const value = callback == null ? item : callback(item as never, index, array);
 
-		if (!isNumber(value)) {
+		if (isNonNumber(value)) {
 			continue;
 		}
 

package/src/internal/result.ts

@@ -1,14 +1,17 @@
+import type {PlainObject} from '../models';
 import type {Err, ExtendedErr, Ok, Result} from '../result/models';
-import {isPlainObject} from './is';
+import {isNonPlainObject} from './is';
 
 // #region Functions
 
 function _isResult(value: unknown, okValue: boolean): value is Result<unknown, unknown> {
-	if (!isPlainObject(value)) {
+	if (isNonPlainObject(value)) {
 		return false;
 	}
 
-	return value.ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value;
+	return (
+		(value as PlainObject).ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value
+	);
 }
 
 /**

package/src/internal/string.ts

@@ -1,5 +1,3 @@
-import {compact} from './array/compact';
-
 // #region Functions
 
 /**
@@ -36,15 +34,35 @@ export function ignoreKey(key: string): boolean {
 }
 
 /**
- * Join an array of values into a string
- * @param value Array of values
+ * Join an array of values into a string _(while ignoring empty values)_
+ *
+ * _(`null`, `undefined`, and any values that become whitespace-only strings are considered empty)_
+ * @param array Array of values
  * @param delimiter Delimiter to use between values
  * @returns Joined string
  */
-export function join(value: unknown[], delimiter?: string): string {
-	return compact(value)
-		.map(getString)
-		.join(typeof delimiter === 'string' ? delimiter : '');
+export function join(array: unknown[], delimiter?: string): string {
+	if (!Array.isArray(array)) {
+		return '';
+	}
+
+	const {length} = array;
+
+	if (length === 0) {
+		return '';
+	}
+
+	const values: string[] = [];
+
+	for (let index = 0; index < length; index += 1) {
+		const item = getString(array[index]);
+
+		if (item.trim().length > 0) {
+			values.push(item);
+		}
+	}
+
+	return values.join(typeof delimiter === 'string' ? delimiter : '');
 }
 
 function tryCallback<T, U>(value: T, callback: (value: T) => U): U {

package/src/internal/value/equal.ts

@@ -1,5 +1,5 @@
 import type {ArrayOrPlainObject, Constructor, PlainObject, TypedArray} from '../../models';
-import {isPlainObject, isPrimitive, isTypedArray} from '../is';
+import {isNonPlainObject, isPlainObject, isPrimitive, isTypedArray} from '../is';
 import {getCompareHandlers} from './handlers';
 
 // #region Types
@@ -377,7 +377,7 @@ function getEqualOptions(input?: boolean | EqualOptions): Options {
 		return options;
 	}
 
-	if (!isPlainObject(input)) {
+	if (isNonPlainObject(input)) {
 		return options;
 	}
 

package/src/internal/value/handlers.ts

@@ -1,5 +1,5 @@
 import type {Constructor, GenericCallback} from '../../models';
-import {isConstructor} from '../is';
+import {isNonConstructor} from '../is';
 
 type Options = {
 	callback: GenericCallback;
@@ -47,7 +47,7 @@ function getHandlers(owner: GenericCallback, options: Options) {
 			}
 		},
 		register(constructor: Constructor, handler?: string | GenericCallback) {
-			if (!isConstructor(constructor) || handler === owner) {
+			if (isNonConstructor(constructor) || handler === owner) {
 				return;
 			}
 

package/src/kalas.ts

@@ -0,0 +1,167 @@
+import {noop} from './internal/function/misc';
+import type {GenericCallback} from './models';
+
+// #region Types
+
+class Events<Map extends Record<string, GenericCallback>> {
+	readonly #kalas: Kalas<Map>;
+
+	constructor(kalas: Kalas<Map>) {
+		this.#kalas = kalas;
+	}
+
+	/**
+	 * 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 {
+		return this.#kalas.subscribe(event, callback);
+	}
+
+	/**
+	 * 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 {
+		return this.#kalas.unsubscribe(event, callback);
+	}
+}
+
+class Kalas<Map extends Record<string, GenericCallback>> {
+	readonly #names: Set<keyof Map>;
+
+	readonly #subscribers = new Map<keyof Map, Set<Map[keyof Map]>>();
+
+	/**
+	 * Events interface for subscribing and unsubscribing to events
+	 */
+	declare readonly events: Events<Map>;
+
+	constructor(names: (keyof Map)[]) {
+		this.#names = new Set(names);
+
+		Object.defineProperty(this, 'events', {
+			value: new Events(this),
+		});
+	}
+
+	/**
+	 * Remove all event subscribers
+	 */
+	clear(): void {
+		this.#subscribers.clear();
+	}
+
+	/**
+	 * Emit an event with parameters
+	 * @param event Event name
+	 * @param parameters Event parameters
+	 */
+	emit<Event extends keyof Map>(event: Event, ...parameters: Parameters<Map[Event]>) {
+		const subscribers = this.#subscribers.get(event);
+
+		if (subscribers == null) {
+			return;
+		}
+
+		for (const callback of subscribers) {
+			callback(...parameters);
+		}
+	}
+
+	/**
+	 * 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 {
+		if (!this.#names.has(event) || typeof callback !== 'function') {
+			return noop;
+		}
+
+		let subscribers = this.#subscribers.get(event);
+
+		if (subscribers == null) {
+			subscribers = new Set();
+
+			this.#subscribers.set(event, subscribers);
+		}
+
+		subscribers.add(callback);
+
+		return () => {
+			subscribers?.delete(callback);
+		};
+	}
+
+	/**
+	 * 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 {
+		if (!this.#names.has(event) || (callback != null ? typeof callback !== 'function' : false)) {
+			return;
+		}
+
+		const subscribers = this.#subscribers.get(event);
+
+		if (subscribers == null) {
+			return;
+		}
+
+		if (callback == null) {
+			subscribers.clear();
+		} else {
+			subscribers.delete(callback);
+		}
+
+		if (callback == null || subscribers.size === 0) {
+			this.#subscribers.delete(event);
+		}
+	}
+}
+
+export type Unsubscriber = () => void;
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Create a Kalas _(party)_ for named events
+ * @param names Event names
+ * @returns Kalas instance
+ */
+export function kalas<Events extends Record<string, GenericCallback>>(
+	names: (keyof Events)[],
+): Kalas<Events> {
+	if (
+		!Array.isArray(names) ||
+		names.length === 0 ||
+		!names.every(name => typeof name === 'string')
+	) {
+		throw new Error(MESSAGE);
+	}
+
+	return new Kalas<Events>(names);
+}
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE = 'Kalas requires an array of event names.';
+
+// #endregion
+
+// #region Exports
+
+export {type Events, type Kalas};
+
+// #endregion

package/src/string/case.ts

@@ -58,7 +58,13 @@ export function kebabCase(value: string): string {
  * @returns Lower-cased string
  */
 export function lowerCase(value: string): string {
-	return typeof value === 'string' ? value.toLocaleLowerCase() : '';
+	if (typeof value !== 'string') {
+		return '';
+	}
+
+	memoizedLowerCase ??= memoize(v => v.toLocaleLowerCase());
+
+	return memoizedLowerCase.run(value);
 }
 
 /**
@@ -85,12 +91,12 @@ export function snakeCase(value: string): string {
  * @returns Title-cased string
  */
 export function titleCase(value: string): string {
-	if (typeof value !== 'string') {
+	if (typeof value !== 'string' || value.length === 0) {
 		return '';
 	}
 
 	memoizedTitleCase ??= memoize(v =>
-		v.length < 1 ? capitalize(v) : join(words(v).map(capitalize), ' '),
+		v.length < 2 ? capitalize(v) : join(words(v).map(capitalize), ' '),
 	);
 
 	return memoizedTitleCase.run(value);
@@ -167,7 +173,13 @@ function toCaseCallback(this: Options, value: string): string {
  * @returns Upper-cased string
  */
 export function upperCase(value: string): string {
-	return typeof value === 'string' ? value.toLocaleUpperCase() : '';
+	if (typeof value !== 'string' || value.length === 0) {
+		return '';
+	}
+
+	memoizedUpperCase ??= memoize(v => v.toLocaleUpperCase());
+
+	return memoizedUpperCase.run(value);
 }
 
 // #endregion
@@ -207,6 +219,10 @@ const delimiters: Record<Case, string> = {
 
 let memoizedCapitalize: Memoized<(value: string) => string>;
 
+let memoizedLowerCase: Memoized<(value: string) => string>;
+
 let memoizedTitleCase: Memoized<(value: string) => string>;
 
+let memoizedUpperCase: Memoized<(value: string) => string>;
+
 // #endregion

package/src/string/normalize.ts

@@ -0,0 +1,169 @@
+import {memoize, type Memoized} from '../function/memoize';
+import {isPlainObject} from '../internal/is';
+import {lowerCase} from './case';
+
+// #region Types
+
+/**
+ * Options for normalizing a string
+ */
+export type NormalizeOptions = {
+	/**
+	 * Remove diacritical marks from the string? _(defaults to `true`)_
+	 */
+	deburr?: boolean;
+	/**
+	 * Convert the string to lower case? _(defaults to `true`)_
+	 */
+	lowerCase?: boolean;
+	/**
+	 * Trim the string? _(defaults to `true`)_
+	 */
+	trim?: boolean;
+};
+
+/**
+ * String normalizer function
+ */
+export type Normalizer = {
+	/**
+	 * Normalize a string
+	 * @param value String to normalize
+	 * @returns Normalized string
+	 */
+	(value: string): string;
+};
+
+type Options = Required<NormalizeOptions>;
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Deburr a string, removing diacritical marks
+ * @param value String to deburr
+ * @returns Deburred string
+ */
+export function deburr(value: string): string {
+	if (typeof value !== 'string') {
+		return '';
+	}
+
+	deburrMemoizer ??= memoize(value => {
+		let deburred = value.normalize(DEBURR_NORMALIZATION).replace(DEBURR_PATTERN_SIMPLE, '');
+
+		deburred = deburred.replace(
+			DEBURR_PATTERN_CHARACTERS,
+			(_, character) => DEBURR_CHARACTERS[character as keyof typeof DEBURR_CHARACTERS],
+		);
+
+		return deburred;
+	});
+
+	return deburrMemoizer.run(value);
+}
+
+function getNormalizeOptions(input?: NormalizeOptions): Options {
+	const options = isPlainObject(input) ? input : {};
+
+	return {
+		deburr: options.deburr !== false,
+		lowerCase: options.lowerCase !== false,
+		trim: options.trim !== false,
+	};
+}
+
+/**
+ * Initialize a string normalizer
+ * @param options Normalization options
+ * @returns Normalizer function
+ */
+export function initializeNormalizer(options?: NormalizeOptions): Normalizer {
+	const normalization = getNormalizeOptions(options);
+
+	return (value: string) => normalizeString(value, normalization);
+}
+
+/**
+ * Normalize a string
+ *
+ * By default, the string will be trimmed, deburred, and then lowercased
+ * @param value String to normalize
+ * @param options Normalization options
+ * @returns Normalized string
+ */
+export function normalize(value: string, options?: NormalizeOptions): string {
+	return normalizeString(value, getNormalizeOptions(options));
+}
+
+normalize.initialize = initializeNormalizer;
+
+function normalizeString(value: string, options: Options): string {
+	if (typeof value !== 'string') {
+		return '';
+	}
+
+	let result = value;
+
+	if (options.trim) {
+		result = result.trim();
+	}
+
+	if (options.deburr) {
+		result = deburr(result);
+	}
+
+	if (options.lowerCase) {
+		result = lowerCase(result);
+	}
+
+	return result;
+}
+
+// #endregion
+
+// #region Variables
+
+const DEBURR_CHARACTERS = {
+	Æ: 'AE',
+	æ: 'ae',
+	Ð: 'D',
+	ð: 'd',
+	Đ: 'D',
+	đ: 'd',
+	Ħ: 'H',
+	ħ: 'h',
+	IJ: 'IJ',
+	ij: 'ij',
+	İ: 'I',
+	ı: 'i',
+	ĸ: 'k',
+	Ŀ: 'L',
+	ŀ: 'l',
+	Ł: 'L',
+	ł: 'l',
+	Ŋ: 'N',
+	ŋ: 'n',
+	ʼn: "'n",
+	Œ: 'OE',
+	œ: 'oe',
+	Ø: 'O',
+	ø: 'o',
+	ſ: 's',
+	ß: 'ss',
+	Þ: 'TH',
+	þ: 'th',
+	Ŧ: 'T',
+	ŧ: 't',
+};
+
+const DEBURR_NORMALIZATION = 'NFD';
+
+const DEBURR_PATTERN_CHARACTERS = new RegExp(`(${Object.keys(DEBURR_CHARACTERS).join('|')})`, 'g');
+
+const DEBURR_PATTERN_SIMPLE = /[\u0300-\u036f]/g;
+
+let deburrMemoizer: Memoized<typeof deburr>;
+
+// #endregion

package/src/value/index.ts

@@ -1,4 +1,5 @@
 export {omit} from './omit';
 export {pick} from './pick';
+export {shake, type Shaken} from './shake';
 export {smush, type Smushed} from './smush';
 export {unsmush, type Unsmushed} from './unsmush';

package/src/value/merge.ts

@@ -8,16 +8,29 @@ import type {ArrayOrPlainObject, NestedPartial, PlainObject} from '../models';
  * Options for merging values
  */
 export type MergeOptions = {
+	/**
+	 * Assign values to the first array or object instead of creating a new one?
+	 */
+	assignValues?: boolean;
 	/**
 	 * Key _(or key epxressions)_ for values that should be replaced
+	 *
 	 * ```ts
 	 * merge([{items: [1, 2, 3]}, {items: [99]}]); // {items: [99]}
 	 * ```
 	 */
 	replaceableObjects?: string | RegExp | Array<string | RegExp>;
+	/**
+	 * Skip nullable values when merging objects?
+	 *
+	 * ```ts
+	 * merge({a: 1, b: 2}, {b: null, c: 3}, {d: null}); // {a: 1, b: 2, c: 3}
+	 * ```
+	 */
 	skipNullableAny?: boolean;
 	/**
 	 * Skip nullable values when merging arrays?
+	 *
 	 * ```ts
 	 * merge([1, 2, 3], [null, null, 99]); // [1, 2, 99]
 	 * ```
@@ -35,6 +48,7 @@ export type Merger<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (
 ) => Model;
 
 type Options = {
+	assignValues: boolean;
 	replaceableObjects: ReplaceableObjectsCallback | undefined;
 	skipNullableAny: boolean;
 	skipNullableInArrays: boolean;
@@ -48,6 +62,7 @@ type ReplaceableObjectsCallback = (name: string) => boolean;
 
 function getMergeOptions(options?: MergeOptions): Options {
 	const actual: Options = {
+		assignValues: false,
 		replaceableObjects: undefined,
 		skipNullableAny: false,
 		skipNullableInArrays: false,
@@ -59,6 +74,7 @@ function getMergeOptions(options?: MergeOptions): Options {
 
 	actual.replaceableObjects = getReplaceableObjects(options.replaceableObjects);
 
+	actual.assignValues = options.assignValues === true;
 	actual.skipNullableAny = options.skipNullableAny === true;
 	actual.skipNullableInArrays = options.skipNullableInArrays === true;
 
@@ -132,7 +148,7 @@ function mergeObjects(
 ): ArrayOrPlainObject {
 	const {length} = values;
 	const isArray = values.every(Array.isArray);
-	const merged = (isArray ? [] : {}) as PlainObject;
+	const merged = (options.assignValues ? values[0] : isArray ? [] : {}) as PlainObject;
 
 	for (let outerIndex = 0; outerIndex < length; outerIndex += 1) {
 		const item = values[outerIndex] as PlainObject;

package/src/value/shake.ts

@@ -0,0 +1,36 @@
+import {isNonPlainObject} from '../is';
+import type {PlainObject} from '../models';
+
+// #region Types
+
+export type Shaken<Value extends PlainObject> = {
+	[Key in keyof Value]: Value[Key] extends undefined ? never : Value[Key];
+};
+
+// #endregion
+
+// #region Functions
+
+export function shake<Value extends PlainObject>(value: Value): Shaken<Value> {
+	const shaken: PlainObject = {};
+
+	if (isNonPlainObject(value)) {
+		return shaken as Shaken<Value>;
+	}
+
+	const keys = Object.keys(value) as (keyof Value)[];
+	const {length} = keys;
+
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+		const val = value[key];
+
+		if (val !== undefined) {
+			shaken[key] = val;
+		}
+	}
+
+	return shaken as Shaken<Value>;
+}
+
+// #endregion