@oscarpalmer/atoms 0.179.0 → 0.180.0

package/dist/string/fuzzy.mjs

@@ -33,7 +33,7 @@ var Fuzzy = class {
 		this.#state = state;
 	}
 	search(value, options) {
-		return search(this.#state.items, this.#state.strings, value, options == null ? this.#state : getOptions(options, this.#state));
+		return search(this.#state.items, this.#state.strings, value, options == null ? this.#state : getFuzzyOptions(options, this.#state));
 	}
 };
 function getHandler(input) {
@@ -49,18 +49,17 @@ function getHandler(input) {
 function getItems(items) {
 	return items.sort((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
 }
-function getOptions(input, state) {
+function getFuzzyOptions(input, state) {
 	const options = isPlainObject(input) ? input : {};
 	const limit = typeof input === "number" ? input : options.limit;
 	if (typeof limit === "number" && !Number.isNaN(limit) && limit >= 1) options.limit = Math.floor(limit);
 	else options.limit = state?.limit;
-	if (typeof options.tolerance === "number" && !Number.isNaN(options.tolerance)) options.tolerance = options.tolerance < 0 ? 0 : Math.floor(options.tolerance);
-	else options.tolerance = state?.tolerance ?? PROXIMITY_THRESHOLD;
+	options.tolerance = getTolerance(options.tolerance, state);
 	return options;
 }
 function getState(items, input) {
 	const handler = getHandler(input);
-	const options = getOptions(input);
+	const options = getFuzzyOptions(input);
 	return {
 		handler,
 		items: items.slice(),
@@ -69,10 +68,27 @@ function getState(items, input) {
 		tolerance: options.tolerance
 	};
 }
+function getTolerance(input, state) {
+	if (typeof input === "number" && !Number.isNaN(input)) return input < 0 ? 0 : Math.floor(input);
+	return state?.tolerance ?? PROXIMITY_THRESHOLD;
+}
 function fuzzy(items, configuration) {
 	if (!Array.isArray(items)) throw new TypeError(MESSAGE_ARRAY);
 	return new Fuzzy(getState(items, configuration));
 }
+fuzzy.match = fuzzyMatch;
+/**
+* Does the needle match the haystack in a fuzzy way?
+* @param haystack Haystack to search through
+* @param needle Needle to search for
+* @returns `true` if the needle matches the haystack in a fuzzy way, `false` otherwise
+*/
+function fuzzyMatch(haystack, needle) {
+	if (typeof haystack !== "string" || typeof needle !== "string") return false;
+	const trimmed = needle.trim();
+	if (includes(haystack, trimmed, true)) return true;
+	return getScore(haystack, trimmed) > -1;
+}
 function isSubsequence(haystack, needle) {
 	const lowerCaseHaystack = lowerCase(haystack);
 	const lowerCaseNeedle = lowerCase(needle);
@@ -162,4 +178,4 @@ const MESSAGE_ARRAY = "Fuzzy requires an array of items";
 const MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
 const PROXIMITY_THRESHOLD = 5;
 //#endregion
-export { fuzzy };
+export { fuzzy, fuzzyMatch };

package/dist/string/template.d.mts

@@ -23,6 +23,8 @@ type TemplateOptions = {
 type Templater = (value: string, variables?: PlainObject) => string;
 /**
  * Create a templater with predefined options
+ *
+ * Available as `initializeTemplater` and `template.initialize`
  * @param options Templating options
  * @returns Templater function
  */
@@ -39,4 +41,4 @@ declare namespace template {
   var initialize: typeof initializeTemplater;
 }
 //#endregion
-export { TemplateOptions, template };
+export { TemplateOptions, initializeTemplater, template };

package/dist/string/template.mjs

@@ -23,6 +23,8 @@ function handleTemplate(value, pattern, ignoreCase, variables) {
 }
 /**
 * Create a templater with predefined options
+*
+* Available as `initializeTemplater` and `template.initialize`
 * @param options Templating options
 * @returns Templater function
 */
@@ -46,4 +48,4 @@ function template(value, variables, options) {
 template.initialize = initializeTemplater;
 const EXPRESSION_VARIABLE = /{{([\s\S]+?)}}/g;
 //#endregion
-export { template };
+export { initializeTemplater, template };

package/dist/value/clone.d.mts

@@ -9,23 +9,27 @@ import { Constructor, GenericCallback } from "../models.mjs";
 declare function clone<Value>(value: Value): Value;
 declare namespace clone {
   var handlers: {
-    register: (constructor: Constructor, handler?: string | GenericCallback) => void;
-    unregister: (constructor: Constructor) => void;
+    deregister(constructor: Constructor): void;
     handle(value: unknown, ...parameters: unknown[]): any;
+    register(constructor: Constructor, handler?: string | GenericCallback): void;
   };
+  var deregister: typeof deregisterCloner;
   var register: typeof registerCloner;
-  var unregister: typeof unregisterCloner;
 }
 /**
- * Register a clone handler for a specific class
+ * Deregister a clone handler for a specific class
+ *
+ * Available as `deregisterCloner` and `template.deregister`
  * @param constructor Class constructor
- * @param handler Method name or clone function _(defaults to `clone`)_
  */
-declare function registerCloner<Instance>(constructor: Constructor<Instance>, handler?: string | ((value: Instance) => Instance)): void;
+declare function deregisterCloner<Instance>(constructor: Constructor<Instance>): void;
 /**
- * Unregister a clone handler for a specific class
+ * Register a clone handler for a specific class
+ *
+ * Available as `registerCloner` and `template.register`
  * @param constructor Class constructor
+ * @param handler Method name or clone function _(defaults to `clone`)_
  */
-declare function unregisterCloner<Instance>(constructor: Constructor<Instance>): void;
+declare function registerCloner<Instance>(constructor: Constructor<Instance>, handler?: string | ((value: Instance) => Instance)): void;
 //#endregion
-export { clone };
+export { clone, deregisterCloner, registerCloner };

package/dist/value/clone.mjs

@@ -9,23 +9,8 @@ clone.handlers = getSelfHandlers(clone, {
 	callback: tryStructuredClone,
 	method: CLONE_NAME
 });
+clone.deregister = deregisterCloner;
 clone.register = registerCloner;
-clone.unregister = unregisterCloner;
-/**
-* Register a clone handler for a specific class
-* @param constructor Class constructor
-* @param handler Method name or clone function _(defaults to `clone`)_
-*/
-function registerCloner(constructor, handler) {
-	clone.handlers.register(constructor, handler);
-}
-/**
-* Unregister a clone handler for a specific class
-* @param constructor Class constructor
-*/
-function unregisterCloner(constructor) {
-	clone.handlers.unregister(constructor);
-}
 function cloneArrayBuffer(value, depth, references) {
 	if (typeof depth === "number" && depth >= MAX_CLONE_DEPTH) return value;
 	const cloned = new ArrayBuffer(value.byteLength);
@@ -110,6 +95,25 @@ function cloneValue(value, depth, references) {
 		default: return clone.handlers.handle(value, depth, references);
 	}
 }
+/**
+* Deregister a clone handler for a specific class
+*
+* Available as `deregisterCloner` and `template.deregister`
+* @param constructor Class constructor
+*/
+function deregisterCloner(constructor) {
+	clone.handlers.deregister(constructor);
+}
+/**
+* Register a clone handler for a specific class
+*
+* Available as `registerCloner` and `template.register`
+* @param constructor Class constructor
+* @param handler Method name or clone function _(defaults to `clone`)_
+*/
+function registerCloner(constructor, handler) {
+	clone.handlers.register(constructor, handler);
+}
 function tryStructuredClone(value, depth, references) {
 	if (depth >= MAX_CLONE_DEPTH) return value;
 	try {
@@ -123,4 +127,4 @@ function tryStructuredClone(value, depth, references) {
 }
 const MAX_CLONE_DEPTH = 100;
 //#endregion
-export { clone };
+export { clone, deregisterCloner, registerCloner };

package/dist/value/merge.d.mts

@@ -27,6 +27,14 @@ type MergeOptions = {
  * @returns Merged value
  */
 type Merger<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (values: NestedPartial<Model>[]) => Model;
+/**
+ * Create a merger with predefined options
+ *
+ * Available as `initializeMerger` and `merge.initialize`
+ * @param options Merging options
+ * @returns Merger function
+ */
+declare function initializeMerger(options?: MergeOptions): Merger;
 /**
  * Merge multiple arrays or objects into a single one
  * @param values Values to merge
@@ -44,11 +52,5 @@ declare function merge(values: NestedPartial<ArrayOrPlainObject>[], options?: Me
 declare namespace merge {
   var initialize: typeof initializeMerger;
 }
-/**
- * Create a merger with predefined options
- * @param options Merging options
- * @returns Merger function
- */
-declare function initializeMerger(options?: MergeOptions): Merger;
 //#endregion
-export { MergeOptions, Merger, merge };
+export { MergeOptions, Merger, initializeMerger, merge };

package/dist/value/merge.mjs

@@ -20,12 +20,10 @@ function getReplaceableObjects(value) {
 function handleMerge(values, options) {
 	return !Array.isArray(values) || values.length === 0 ? {} : mergeValues(values, options, true);
 }
-function merge(values, options) {
-	return handleMerge(values, getMergeOptions(options));
-}
-merge.initialize = initializeMerger;
 /**
 * Create a merger with predefined options
+*
+* Available as `initializeMerger` and `merge.initialize`
 * @param options Merging options
 * @returns Merger function
 */
@@ -33,6 +31,10 @@ function initializeMerger(options) {
 	const actual = getMergeOptions(options);
 	return (values) => handleMerge(values, actual);
 }
+function merge(values, options) {
+	return handleMerge(values, getMergeOptions(options));
+}
+merge.initialize = initializeMerger;
 function mergeObjects(values, options, prefix) {
 	const { length } = values;
 	const isArray = values.every(Array.isArray);
@@ -58,4 +60,4 @@ function mergeValues(values, options, validate, prefix) {
 	return actual.length > 1 ? mergeObjects(actual, options, prefix) : actual[0] ?? {};
 }
 //#endregion
-export { merge };
+export { initializeMerger, merge };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.179.0",
+	"version": "0.180.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -245,7 +245,7 @@
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.60",
+		"@oxlint/plugins": "^1.61",
 		"@types/node": "^25.6",
 		"@vitest/coverage-istanbul": "^4.1",
 		"eslint": "^10.2",
@@ -257,4 +257,4 @@
 		"vitest": "npm:@voidzero-dev/vite-plus-test@latest"
 	},
 	"packageManager": "npm@11.11.1"
-}
+}

package/plugin/helpers.js

@@ -177,7 +177,7 @@ function isInstanceMethod(type, context, node, methods) {
  * @param {Set<string>} methods
  * @returns {boolean}
  */
-function isLiteralMethod(type, context, node, methods) {
+function isLiteralMethod(_, __, ___, ____) {
 	// TODO: check literal value
 
 	return false;
@@ -190,7 +190,7 @@ function isLiteralMethod(type, context, node, methods) {
  * @param {Set<string>} methods
  * @returns {boolean}
  */
-function isStaticMethod(type, context, node, methods) {
+function isStaticMethod(type, context, node, _) {
 	const {object, property} = node.callee;
 
 	if (object.type !== identifierExpression || object.name !== objects[type]) {

package/src/array/filter.ts

@@ -4,101 +4,109 @@ import type {PlainObject} from '../models';
 // #region Functions
 
 /**
- * Get a filtered array of items
+ * Get a filtered array of items that do not match the filter
+ *
+ * Available as `exclude` and `filter.remove`
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
- * @returns Filtered array of items
+ * @returns Filtered array of items that do not match the filter
  */
-export function filter<
+export function exclude<
 	Item,
 	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
+>(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
 
 /**
- * Get a filtered array of items
+ * Get a filtered array of items that do not match the filter
+ *
+ * Available as `exclude` and `filter.remove`
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
- * @returns Filtered array of items
+ * @returns Filtered array of items that do not match the filter
  */
-export function filter<Item extends PlainObject, ItemKey extends keyof Item>(
+export function exclude<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	key: ItemKey,
 	value: Item[ItemKey],
-): Item[];
+): unknown[];
 
 /**
- * Get a filtered array of items matching the filter
+ * Get a filtered array of items that do not match the filter
+ *
+ * Available as `exclude` and `filter.remove`
  * @param array Array to search in
  * @param filter Filter callback to match items
- * @returns Filtered array of items
+ * @returns Filtered array of items that do not match the filter
  */
-export function filter<Item>(
+export function exclude<Item>(
 	array: Item[],
 	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item[];
+): unknown[];
 
 /**
- * Get a filtered array of items matching the given item
+ * Get a filtered array of items that do not match the given item
+ *
+ * Available as `exclude` and `filter.remove`
  * @param array Array to search in
  * @param item Item to match against
- * @returns Filtered array of items
+ * @returns Filtered array of items that do not match the given item
  */
-export function filter<Item>(array: Item[], item: Item): Item[];
+export function exclude<Item>(array: Item[], item: Item): unknown[];
 
-export function filter(array: unknown[], ...parameters: unknown[]): unknown[] {
-	return findValues(FIND_VALUES_ALL, array, parameters).matched;
+export function exclude(array: unknown[], ...parameters: unknown[]): unknown[] {
+	return findValues(FIND_VALUES_ALL, array, parameters).notMatched;
 }
 
-filter.remove = removeFiltered;
-
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
- * @returns Filtered array of items that do not match the filter
+ * @returns Filtered array of items
  */
-function removeFiltered<
+export function filter<
 	Item,
 	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
+>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
 
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
- * @returns Filtered array of items that do not match the filter
+ * @returns Filtered array of items
  */
-function removeFiltered<Item extends PlainObject, ItemKey extends keyof Item>(
+export function filter<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	key: ItemKey,
 	value: Item[ItemKey],
-): unknown[];
+): Item[];
 
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items matching the filter
  * @param array Array to search in
  * @param filter Filter callback to match items
- * @returns Filtered array of items that do not match the filter
+ * @returns Filtered array of items
  */
-function removeFiltered<Item>(
+export function filter<Item>(
 	array: Item[],
 	filter: (item: Item, index: number, array: Item[]) => boolean,
-): unknown[];
+): Item[];
 
 /**
- * Get a filtered array of items that do not match the given item
+ * Get a filtered array of items matching the given item
  * @param array Array to search in
  * @param item Item to match against
- * @returns Filtered array of items that do not match the given item
+ * @returns Filtered array of items
  */
-function removeFiltered<Item>(array: Item[], item: Item): unknown[];
+export function filter<Item>(array: Item[], item: Item): Item[];
 
-function removeFiltered(array: unknown[], ...parameters: unknown[]): unknown[] {
-	return findValues(FIND_VALUES_ALL, array, parameters).notMatched;
+export function filter(array: unknown[], ...parameters: unknown[]): unknown[] {
+	return findValues(FIND_VALUES_ALL, array, parameters).matched;
 }
 
+filter.remove = exclude;
+
 // #endregion

package/src/array/first.ts

@@ -54,27 +54,32 @@ export function first(array: unknown[], ...parameters: unknown[]): unknown {
 first.default = firstOrDefault;
 
 /**
- * Get the first item matching the given value
+ * Get the first item matching the given value, or a default value if no match is found
+ *
+ * Available as `firstOrDefault` and `first.default`
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or the default value if no match is found
  */
-function firstOrDefault<
+export function firstOrDefault<
 	Item,
 	Callback extends (item: Item, index: number, array: Item[]) => unknown,
 >(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
 
 /**
- * Get the first item matching the given value by key
+ * Get the first item matching the given value by key, or a default value if no match is found
+ *
+ * Available as `firstOrDefault` and `first.default`
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or the default value if no match is found
  */
-function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
+
+export function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	defaultValue: Item,
 	key: ItemKey,
@@ -82,27 +87,31 @@ function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
 ): Item;
 
 /**
- * Get the first item matching the filter
+ * Get the first item matching the filter, or a default value if no match is found
+ *
+ * Available as `firstOrDefault` and `first.default`
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or the default value if no match is found
  */
-function firstOrDefault<Item>(
+export function firstOrDefault<Item>(
 	array: Item[],
 	defaultValue: Item,
 	filter: (item: Item, index: number, array: Item[]) => boolean,
 ): Item;
 
 /**
- * Get the first item from an array
+ * Get the first item from an array, or a default value if the array is empty
+ *
+ * Available as `firstOrDefault` and `first.default`
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
  * @return First item from the array, or the default value if the array is empty
  */
-function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
+export function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
 
-function firstOrDefault(
+export function firstOrDefault(
 	array: unknown[],
 	defaultValue: unknown,
 	...parameters: unknown[]

package/src/array/group-by.ts

@@ -120,12 +120,14 @@ groupBy.arrays = groupArraysBy;
 
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Record of keyed values
  */
-function groupArraysBy<
+export function groupArraysBy<
 	Item,
 	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
 	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
@@ -137,12 +139,14 @@ function groupArraysBy<
 
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Record of keyed values
  */
-function groupArraysBy<
+export function groupArraysBy<
 	Item extends PlainObject,
 	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
 	ItemValue extends keyof Item,
@@ -154,12 +158,14 @@ function groupArraysBy<
 
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Record of keyed values
  */
-function groupArraysBy<
+export function groupArraysBy<
 	Item extends PlainObject,
 	ItemKey extends keyof Item,
 	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
@@ -171,12 +177,14 @@ function groupArraysBy<
 
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Record of keyed values
  */
-function groupArraysBy<
+export function groupArraysBy<
 	Item extends PlainObject,
 	ItemKey extends keyof Item,
 	ItemValue extends keyof Item,
@@ -188,27 +196,31 @@ function groupArraysBy<
 
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
  * @returns Record of keyed items
  */
-function groupArraysBy<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(
-	array: Item[],
-	callback: Callback,
-): Record<ReturnType<Callback>, Item[]>;
+export function groupArraysBy<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], callback: Callback): Record<ReturnType<Callback>, Item[]>;
 
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
+ *
+ * Available as `groupArraysBy` and `groupBy.arrays`
  * @param array Array to group
  * @param key Key to use for grouping
  * @returns Record of keyed items
  */
-function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item>(
+export function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	key: ItemKey,
 ): Simplify<Record<KeyedValue<Item, ItemKey>, Item[]>>;
 
-function groupArraysBy(array: unknown[], first?: unknown, second?: unknown): unknown {
+export function groupArraysBy(array: unknown[], first?: unknown, second?: unknown): unknown {
 	return groupValues(array, first, second, true);
 }