@oscarpalmer/atoms 0.180.0 → 0.182.0

package/dist/kalas.d.mts

@@ -0,0 +1,61 @@
+import { GenericCallback } from "./models.mjs";
+
+//#region src/kalas.d.ts
+declare class Events<Map extends Record<string, GenericCallback>> {
+  #private;
+  constructor(kalas: Kalas<Map>);
+  /**
+   * 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;
+}
+declare class Kalas<Map extends Record<string, GenericCallback>> {
+  #private;
+  /**
+   * Events interface for subscribing and unsubscribing to events
+   */
+  readonly events: Events<Map>;
+  constructor(names: (keyof 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;
+}
+type Unsubscriber = () => void;
+/**
+ * Create a Kalas _(party)_ for named events
+ * @param names Event names
+ * @returns Kalas instance
+ */
+declare function kalas<Events extends Record<string, GenericCallback>>(names: (keyof Events)[]): Kalas<Events>;
+//#endregion
+export { type Events, type Kalas, Unsubscriber, kalas };

package/dist/kalas.mjs

@@ -0,0 +1,93 @@
+import { noop } from "./internal/function/misc.mjs";
+//#region src/kalas.ts
+var Events = class {
+	#kalas;
+	constructor(kalas) {
+		this.#kalas = kalas;
+	}
+	/**
+	* Subscribe to an event with a callback
+	* @param event Event name
+	* @param callback Callback function
+	* @returns Unsubscriber function
+	*/
+	subscribe(event, callback) {
+		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, callback) {
+		return this.#kalas.unsubscribe(event, callback);
+	}
+};
+var Kalas = class {
+	#names;
+	#subscribers = /* @__PURE__ */ new Map();
+	constructor(names) {
+		this.#names = new Set(names);
+		Object.defineProperty(this, "events", { value: new Events(this) });
+	}
+	/**
+	* Remove all event subscribers
+	*/
+	clear() {
+		this.#subscribers.clear();
+	}
+	/**
+	* Emit an event with parameters
+	* @param event Event name
+	* @param parameters Event parameters
+	*/
+	emit(event, ...parameters) {
+		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, callback) {
+		if (!this.#names.has(event) || typeof callback !== "function") return noop;
+		let subscribers = this.#subscribers.get(event);
+		if (subscribers == null) {
+			subscribers = /* @__PURE__ */ 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, callback) {
+		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);
+	}
+};
+/**
+* Create a Kalas _(party)_ for named events
+* @param names Event names
+* @returns Kalas instance
+*/
+function kalas(names) {
+	if (!Array.isArray(names) || names.length === 0 || !names.every((name) => typeof name === "string")) throw new Error(MESSAGE);
+	return new Kalas(names);
+}
+const MESSAGE = "Kalas requires an array of event names.";
+//#endregion
+export { kalas };

package/dist/string/case.mjs

@@ -33,7 +33,9 @@ function kebabCase(value) {
 * @returns Lower-cased string
 */
 function lowerCase(value) {
-	return typeof value === "string" ? value.toLocaleLowerCase() : "";
+	if (typeof value !== "string") return "";
+	memoizedLowerCase ??= memoize((v) => v.toLocaleLowerCase());
+	return memoizedLowerCase.run(value);
 }
 /**
 * Convert a string to pascal case _(ThisIsPascalCase)_
@@ -57,8 +59,8 @@ function snakeCase(value) {
 * @returns Title-cased string
 */
 function titleCase(value) {
-	if (typeof value !== "string") return "";
-	memoizedTitleCase ??= memoize((v) => v.length < 1 ? capitalize(v) : join(words(v).map(capitalize), " "));
+	if (typeof value !== "string" || value.length === 0) return "";
+	memoizedTitleCase ??= memoize((v) => v.length < 2 ? capitalize(v) : join(words(v).map(capitalize), " "));
 	return memoizedTitleCase.run(value);
 }
 function toCase(type, value, capitalizeAny, capitalizeFirst) {
@@ -98,7 +100,9 @@ function toCaseCallback(value) {
 * @returns Upper-cased string
 */
 function upperCase(value) {
-	return typeof value === "string" ? value.toLocaleUpperCase() : "";
+	if (typeof value !== "string" || value.length === 0) return "";
+	memoizedUpperCase ??= memoize((v) => v.toLocaleUpperCase());
+	return memoizedUpperCase.run(value);
 }
 const CASE_CAMEL = "camel";
 const CASE_KEBAB = "kebab";
@@ -119,6 +123,8 @@ const delimiters = {
 	[CASE_SNAKE]: DELIMITER_UNDERSCORE
 };
 let memoizedCapitalize;
+let memoizedLowerCase;
 let memoizedTitleCase;
+let memoizedUpperCase;
 //#endregion
 export { camelCase, capitalize, kebabCase, lowerCase, pascalCase, snakeCase, titleCase, upperCase };

package/dist/string/normalize.d.mts

@@ -0,0 +1,55 @@
+//#region src/string/normalize.d.ts
+/**
+ * Options for normalizing a string
+ */
+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
+ */
+type Normalizer = {
+  /**
+   * Normalize a string
+   * @param value String to normalize
+   * @returns Normalized string
+   */
+  (value: string): string;
+};
+/**
+ * Deburr a string, removing diacritical marks
+ * @param value String to deburr
+ * @returns Deburred string
+ */
+declare function deburr(value: string): string;
+/**
+ * Initialize a string normalizer
+ * @param options Normalization options
+ * @returns Normalizer function
+ */
+declare function initializeNormalizer(options?: NormalizeOptions): Normalizer;
+/**
+ * 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
+ */
+declare function normalize(value: string, options?: NormalizeOptions): string;
+declare namespace normalize {
+  var initialize: typeof initializeNormalizer;
+}
+//#endregion
+export { NormalizeOptions, Normalizer, deburr, initializeNormalizer, normalize };

package/dist/string/normalize.mjs

@@ -0,0 +1,93 @@
+import { isPlainObject } from "../internal/is.mjs";
+import { memoize } from "../function/memoize.mjs";
+import { lowerCase } from "./case.mjs";
+//#region src/string/normalize.ts
+/**
+* Deburr a string, removing diacritical marks
+* @param value String to deburr
+* @returns Deburred string
+*/
+function deburr(value) {
+	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]);
+		return deburred;
+	});
+	return deburrMemoizer.run(value);
+}
+function getNormalizeOptions(input) {
+	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
+*/
+function initializeNormalizer(options) {
+	const normalization = getNormalizeOptions(options);
+	return (value) => 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
+*/
+function normalize(value, options) {
+	return normalizeString(value, getNormalizeOptions(options));
+}
+normalize.initialize = initializeNormalizer;
+function normalizeString(value, options) {
+	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;
+}
+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;
+//#endregion
+export { deburr, initializeNormalizer, normalize };

package/dist/value/index.d.mts

@@ -1,5 +1,6 @@
 import { omit } from "./omit.mjs";
 import { pick } from "./pick.mjs";
+import { Shaken, shake } from "./shake.mjs";
 import { Smushed, smush } from "./smush.mjs";
 import { Unsmushed, unsmush } from "./unsmush.mjs";
-export { type Smushed, type Unsmushed, omit, pick, smush, unsmush };
+export { type Shaken, type Smushed, type Unsmushed, omit, pick, shake, smush, unsmush };

package/dist/value/index.mjs

@@ -1,5 +1,6 @@
 import { omit } from "./omit.mjs";
 import { pick } from "./pick.mjs";
+import { shake } from "./shake.mjs";
 import { smush } from "./smush.mjs";
 import { unsmush } from "./unsmush.mjs";
-export { omit, pick, smush, unsmush };
+export { omit, pick, shake, smush, unsmush };

package/dist/value/merge.d.mts

@@ -5,16 +5,29 @@ import { ArrayOrPlainObject, NestedPartial } from "../models.mjs";
  * Options for merging values
  */
 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]
    * ```

package/dist/value/merge.mjs

@@ -3,12 +3,14 @@ import { join } from "../internal/string.mjs";
 //#region src/value/merge.ts
 function getMergeOptions(options) {
 	const actual = {
+		assignValues: false,
 		replaceableObjects: void 0,
 		skipNullableAny: false,
 		skipNullableInArrays: false
 	};
 	if (typeof options !== "object" || options == null) return actual;
 	actual.replaceableObjects = getReplaceableObjects(options.replaceableObjects);
+	actual.assignValues = options.assignValues === true;
 	actual.skipNullableAny = options.skipNullableAny === true;
 	actual.skipNullableInArrays = options.skipNullableInArrays === true;
 	return actual;
@@ -38,7 +40,7 @@ merge.initialize = initializeMerger;
 function mergeObjects(values, options, prefix) {
 	const { length } = values;
 	const isArray = values.every(Array.isArray);
-	const merged = isArray ? [] : {};
+	const merged = options.assignValues ? values[0] : isArray ? [] : {};
 	for (let outerIndex = 0; outerIndex < length; outerIndex += 1) {
 		const item = values[outerIndex];
 		const keys = Object.keys(item);

package/dist/value/shake.d.mts

@@ -0,0 +1,7 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/value/shake.d.ts
+type Shaken<Value extends PlainObject> = { [Key in keyof Value]: Value[Key] extends undefined ? never : Value[Key] };
+declare function shake<Value extends PlainObject>(value: Value): Shaken<Value>;
+//#endregion
+export { Shaken, shake };

package/dist/value/shake.mjs

@@ -0,0 +1,16 @@
+import { isNonPlainObject } from "../internal/is.mjs";
+//#region src/value/shake.ts
+function shake(value) {
+	const shaken = {};
+	if (isNonPlainObject(value)) return shaken;
+	const keys = Object.keys(value);
+	const { length } = keys;
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+		const val = value[key];
+		if (val !== void 0) shaken[key] = val;
+	}
+	return shaken;
+}
+//#endregion
+export { shake };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.180.0",
+	"version": "0.182.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",

package/src/array/exists.ts

@@ -52,7 +52,7 @@ export function exists(array: unknown[], ...parameters: unknown[]): boolean {
 		return Array.isArray(array) ? array.includes(parameters[0]) : false;
 	}
 
-	return (findValue(FIND_VALUE_INDEX, array, parameters, false) as number) > -1;
+	return findValue(FIND_VALUE_INDEX, array, parameters, false) > -1;
 }
 
 // #endregion

package/src/array/find.ts

@@ -52,4 +52,62 @@ export function find(array: unknown[], ...parameters: unknown[]): unknown {
 	return findValue(FIND_VALUE_ITEM, array, parameters, false);
 }
 
+find.last = findLast;
+
+/**
+ * Get the last item matching the given value
+ *
+ * Available as `findLast` and `find.last`
+ * @param array Array to search in
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or `undefined` if no match is found
+ */
+export function findLast<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => unknown,
+>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
+
+/**
+ * Get the last item matching the given value by key
+ *
+ * Available as `findLast` and `find.last`
+ * @param array Array to search in
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or `undefined` if no match is found
+ */
+export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item | undefined;
+
+/**
+ * Get the last item matching the filter
+ *
+ * Available as `findLast` and `find.last`
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns Last item that matches the filter, or `undefined` if no match is found
+ */
+export function findLast<Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item | undefined;
+
+/**
+ * Get the last item matching the given value
+ *
+ * Available as `findLast` and `find.last`
+ * @param array Array to search in
+ * @param value Value to match against
+ * @returns Last item that matches the value, or `undefined` if no match is found
+ */
+export function findLast<Item>(array: Item[], value: Item): Item | undefined;
+
+export function findLast(array: unknown[], ...parameters: unknown[]): unknown {
+	return findValue(FIND_VALUE_ITEM, array, parameters, true);
+}
+
 // #endregion

package/src/array/get.ts

@@ -1,4 +1,4 @@
-import {isPlainObject} from '../internal/is';
+import {isNonPlainObject} from '../internal/is';
 import type {NumericalKeys, PlainObject} from '../models';
 
 // #region Functions
@@ -50,7 +50,7 @@ export function getArray(value: unknown, indiced?: unknown): unknown[] {
 		return [...value.values()];
 	}
 
-	if (!isPlainObject(value)) {
+	if (isNonPlainObject(value)) {
 		return [value];
 	}
 

package/src/index.ts

@@ -25,10 +25,13 @@ export * from './internal/value/get';
 export * from './internal/value/has';
 export * from './internal/value/set';
 
+export * from './kalas';
+
 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';

package/src/internal/array/find.ts

@@ -21,6 +21,20 @@ type Parameters = {
 
 // #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[],
@@ -38,11 +52,17 @@ export function findValue(
 	const callbacks = getArrayCallbacks(bool, key);
 
 	if (callbacks?.bool == null && callbacks?.keyed == null) {
-		return findIndex ? array.indexOf(value) : array.find(item => Object.is(item, value));
+		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 = array.findIndex(callbacks.bool);
+		const index = reversed ? array.findLastIndex(callbacks.bool) : array.findIndex(callbacks.bool);
 
 		return findIndex ? index : array[index];
 	}
@@ -167,9 +187,9 @@ export function getFindParameters(original: unknown[]): Parameters {
 
 // #region Variables
 
-export const FIND_VALUE_INDEX: FindValueType = 'index';
+export const FIND_VALUE_INDEX = 'index';
 
-export const FIND_VALUE_ITEM: FindValueType = 'item';
+export const FIND_VALUE_ITEM = 'item';
 
 export const FIND_VALUES_ALL: FindValuesType = 'all';
 

package/src/internal/array/index-of.ts

@@ -48,7 +48,65 @@ export function indexOf<Item>(
 export function indexOf<Item>(array: Item[], item: Item): number;
 
 export function indexOf(array: unknown[], ...parameters: unknown[]): number {
-	return findValue(FIND_VALUE_INDEX, array, parameters, false) as number;
+	return findValue(FIND_VALUE_INDEX, array, parameters, false);
+}
+
+indexOf.last = lastIndexOf;
+
+/**
+ * Get the index of the last matching item by callback
+ *
+ * Available as `lastIndexOf` and `indexOf.last`
+ * @param array Array to search in
+ * @param callback Callback to get an item's value
+ * @param value Value to match against
+ * @returns Index of the last matching item, or `-1` if no match is found
+ */
+export function lastIndexOf<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => unknown,
+>(array: Item[], callback: Callback, value: ReturnType<Callback>): number;
+
+/**
+ * Get the index of the last matching item by key
+ *
+ * Available as `lastIndexOf` and `indexOf.last`
+ * @param array Array to search in
+ * @param key Key to match items by
+ * @param value Value to match against
+ * @returns Index of the last matching item, or `-1` if no match is found
+ */
+export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey,
+	value: Item[ItemKey],
+): number;
+
+/**
+ * Get the index of the last item matching the filter
+ *
+ * Available as `lastIndexOf` and `indexOf.last`
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns Index of the last matching item, or `-1` if no match is found
+ */
+export function lastIndexOf<Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): number;
+
+/**
+ * Get the index of the last item matching the given item
+ *
+ * Available as `lastIndexOf` and `indexOf.last`
+ * @param array Array to search in
+ * @param item Item to match against
+ * @returns Index of the last matching item, or `-1` if no match is found
+ */
+export function lastIndexOf<Item>(array: Item[], item: Item): number;
+
+export function lastIndexOf(array: unknown[], ...parameters: unknown[]): number {
+	return findValue(FIND_VALUE_INDEX, array, parameters, true);
 }
 
 // #endregion