@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/value/freeze.ts

@@ -1,3 +1,4 @@
+import {noop} from '../function';
 import {isPlainObject} from '../is';
 import type {ArrayOrPlainObject, GenericCallback, PlainObject} from '../models';
 
@@ -6,51 +7,180 @@ import type {ArrayOrPlainObject, GenericCallback, PlainObject} from '../models';
 /**
  * A frozen value with readonly properties _(going as deep as possible)_
  */
-export type Frozen<Value extends ArrayOrPlainObject> = {
-	readonly [Key in keyof Value]: Value[Key] extends ArrayOrPlainObject
-		? Frozen<Value[Key]>
-		: Value[Key];
-};
+export type Frozen<Value> = Value extends unknown[]
+	? Readonly<Value>
+	: Value extends PlainObject
+		? {
+				readonly [Key in keyof Value]: Frozen<Value[Key]>;
+			}
+		: Value extends Map<infer Key, infer Value>
+			? ReadonlyMap<Key, Frozen<Value>>
+			: Value extends Set<infer Item>
+				? ReadonlySet<Frozen<Item>>
+				: Readonly<Value>;
 
 // #endregion
 
 // #region Functions
 
+function fakeDelete(): boolean {
+	return false;
+}
+
 /**
- * Freeze an array and all its indices recursively
+ * Freeze an array and its indiced values, but not any nested values
+ *
+ * _Available as `flatFreeze` and `freeze.flat`_
+ *
+ * @param array Array to freeze
+ * @returns Frozen array
+ */
+export function flatFreeze<Item>(array: Item[]): ReadonlyArray<Item>;
+
+/**
+ * Freeze a map and its values, but not any nested values
+ *
+ * _Available as `flatFreeze` and `freeze.flat`_
+ *
+ * @param map Map to freeze
+ * @returns Frozen map
+ */
+export function flatFreeze<Key, Value>(map: Map<Key, Value>): ReadonlyMap<Key, Value>;
+
+/**
+ * Freeze an object and its properties, but not any nested values
+ *
+ * _Available as `flatFreeze` and `freeze.flat`_
+ *
+ * @param object Object to freeze
+ * @returns Frozen object
+ */
+export function flatFreeze<Value extends PlainObject>(object: Value): Readonly<Value>;
+
+/**
+ * Freeze a set and its values, but not any nested values
+ *
+ * _Available as `flatFreeze` and `freeze.flat`_
+ *
+ * @param set Set to freeze
+ * @returns Frozen set
+ */
+export function flatFreeze<Item>(set: Set<Item>): ReadonlySet<Item>;
+
+/**
+ * Freeze any value, if possible
+ *
+ * _(Only arrays, maps, plain objects, and sets are freezable)_
+ *
+ * _Available as `flatFreeze` and `freeze.flat`_
+ *
+ * @param value Value to freeze
+ * @returns Frozen value
+ */
+export function flatFreeze<Value>(value: Value): Value;
+
+export function flatFreeze(value: unknown): unknown {
+	return freezeValue(value, new WeakSet(), true);
+}
+
+/**
+ * Freeze an array and its values _(but not any nested values)_, preventing modifications
+ *
+ * @param array Array to freeze
+ * @param flat Freeze _only_ the array, not any nested values
+ * @returns Frozen array
+ */
+export function freeze<Item>(array: Item[], flat: true): ReadonlyArray<Item>;
+
+/**
+ * Freeze a map and its values _(but not any nested values)_, preventing modifications
+ *
+ * @param map Map to freeze
+ * @param flat Freeze _only_ the map, not any nested values
+ * @returns Frozen map
+ */
+export function freeze<Key, Value>(map: Map<Key, Value>, flat: true): ReadonlyMap<Key, Value>;
+
+/**
+ * Freeze an object and its properties _(but not any nested values)_, preventing modifications
+ *
+ * @param object Object to freeze
+ * @param flat Freeze _only_ the object, not any nested values
+ * @returns Frozen object
+ */
+export function freeze<Value extends PlainObject>(object: Value, flat: true): Readonly<Value>;
+
+/**
+ * Freeze a set and its values _(but not any nested values)_, preventing modifications
+ *
+ * @param set Set to freeze
+ * @param flat Freeze _only_ the set, not any nested values
+ * @returns Frozen set
+ */
+export function freeze<Item>(set: Set<Item>, flat: true): ReadonlySet<Item>;
+
+/**
+ * Freeze an array and its values recursively, preventing modifications
+ *
+ * _(If you only want to freeze the array itself, but not any nested values, use `freeze(array, true)`, `freeze.flat(array)`, or `flatFreeze(array)` instead)_
+ *
  * @param array Array to freeze
  * @returns Frozen array
  */
 export function freeze<Item>(array: Item[]): Frozen<Item[]>;
 
 /**
- * Freeze a function
- * @param fn Function to freeze
- * @returns Frozen function
+ * Freeze a map and its values recursively, preventing modifications
+ *
+ * _(If you only want to freeze the map itself, but not any nested values, use `freeze(map, true)`, `freeze.flat(map)`, or `flatFreeze(map)` instead)_
+ *
+ * @param map Map to freeze
+ * @returns Frozen map
  */
-export function freeze<Fn extends GenericCallback>(fn: Fn): Readonly<Fn>;
+export function freeze<Key, Value>(map: Map<Key, Value>): Frozen<Map<Key, Value>>;
 
 /**
  * Freeze an object and all its properties recursively
+ *
+ * _(If you only want to freeze the object itself, but not any nested values, use `freeze(object, true)`, `freeze.flat(object)`, or `flatFreeze(object)` instead)_
+ *
  * @param object Object to freeze
  * @returns Frozen object
  */
 export function freeze<Value extends PlainObject>(object: Value): Frozen<Value>;
 
+/**
+ * Freeze a set and its values recursively
+ *
+ * _(If you only want to freeze the set itself, but not any nested values, use `freeze(set, true)`, `freeze.flat(set)`, or `flatFreeze(set)` instead)_
+ *
+ * @param set Set to freeze
+ * @returns Frozen set
+ */
+export function freeze<Item>(set: Set<Item>): Frozen<Set<Item>>;
+
 /**
  * Freeze any value, if possible
  *
- * _(Only arrays, functions, and plain objects are freezable)_
+ * _(Only arrays, maps, plain objects, and sets are freezable)_
+ *
  * @param value Value to freeze
  * @returns Frozen value
  */
 export function freeze<Value>(value: Value): Value;
 
-export function freeze(value: unknown): unknown {
-	return freezeValue(value, new WeakSet());
+export function freeze(value: unknown, flat?: unknown): unknown {
+	return freezeValue(value, new WeakSet(), flat === true);
 }
 
-function freezeArray(array: unknown[], references: WeakSet<any>): Frozen<unknown[]> {
+freeze.flat = flatFreeze;
+freeze.is = isFrozen;
+
+function freezeArray(array: unknown[], references: WeakSet<any>, flat: boolean): Frozen<unknown[]> {
+	if (flat) {
+		return Object.freeze(array) as Frozen<unknown[]>;
+	}
+
 	references.add(array);
 
 	const {length} = array;
@@ -59,20 +189,50 @@ function freezeArray(array: unknown[], references: WeakSet<any>): Frozen<unknown
 		const value = array[index];
 
 		if (!references.has(value)) {
-			array[index] = freezeValue(array[index], references);
+			array[index] = freezeValue(array[index], references, false);
 		}
 	}
 
 	return Object.freeze(array) as Frozen<unknown[]>;
 }
 
-function freezeFunction(fn: Function, references: WeakSet<any>): Readonly<Function> {
-	references.add(fn);
+function freezeMap(
+	map: Map<unknown, unknown>,
+	references: WeakSet<any>,
+	flat: boolean,
+): ReadonlyMap<unknown, unknown> {
+	frozenValues.add(map);
+
+	map.clear = noop;
+	map.delete = fakeDelete;
+	map.set = () => map;
+
+	if (flat) {
+		return map as ReadonlyMap<unknown, unknown>;
+	}
+
+	references.add(map);
 
-	return Object.freeze(fn);
+	const entries = map.entries();
+
+	for (const [key, value] of entries) {
+		if (!references.has(value)) {
+			map.set(key, freezeValue(value, references, false));
+		}
+	}
+
+	return map as ReadonlyMap<unknown, unknown>;
 }
 
-function freezeObject(object: PlainObject, references: WeakSet<any>): Frozen<PlainObject> {
+function freezeObject(
+	object: PlainObject,
+	references: WeakSet<any>,
+	flat: boolean,
+): Frozen<PlainObject> {
+	if (flat) {
+		return Object.freeze(object) as Frozen<PlainObject>;
+	}
+
 	references.add(object);
 
 	const keys = Object.keys(object);
@@ -82,27 +242,81 @@ function freezeObject(object: PlainObject, references: WeakSet<any>): Frozen<Pla
 		const key = keys[index];
 
 		if (!references.has(object[key])) {
-			object[key] = freezeValue(object[key], references);
+			object[key] = freezeValue(object[key], references, false);
 		}
 	}
 
 	return Object.freeze(object) as Frozen<PlainObject>;
 }
 
-function freezeValue(value: unknown, references: WeakSet<any>): unknown {
+function freezeSet(
+	set: Set<unknown>,
+	references: WeakSet<any>,
+	flat: boolean,
+): ReadonlySet<unknown> {
+	frozenValues.add(set);
+
+	set.clear = noop;
+	set.delete = fakeDelete;
+	set.add = () => set;
+
+	if (flat) {
+		return set as ReadonlySet<unknown>;
+	}
+
+	references.add(set);
+
+	const values = set.values();
+
+	for (const value of values) {
+		if (!references.has(value)) {
+			set.add(freezeValue(value, references, false));
+		}
+	}
+
+	return set as ReadonlySet<unknown>;
+}
+
+function freezeValue(value: unknown, references: WeakSet<any>, flat: boolean): unknown {
 	switch (true) {
-		case typeof value === 'function':
-			return freezeFunction(value, references);
+		case isFrozen(value):
+			return value;
+
+		case value instanceof Map:
+			return freezeMap(value, references, flat);
+
+		case value instanceof Set:
+			return freezeSet(value, references, flat);
 
 		case Array.isArray(value):
-			return freezeArray(value, references);
+			return freezeArray(value, references, flat);
 
 		case isPlainObject(value):
-			return freezeObject(value, references);
+			return freezeObject(value, references, flat);
 
 		default:
 			return value;
 	}
 }
 
+/**
+ * Is the value frozen?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is frozen, otherwise `false`
+ */
+export function isFrozen(value: unknown): boolean {
+	if (value instanceof Map || value instanceof Set) {
+		return frozenValues.has(value);
+	}
+
+	return typeof value === 'object' && value !== null && Object.isFrozen(value);
+}
+
+// #endregion
+
+// #region Variables
+
+const frozenValues = new WeakSet();
+
 // #endregion

package/src/value/index.ts

@@ -1,4 +1,3 @@
-export {freeze, type Frozen} from './freeze';
 export {omit} from './omit';
 export {pick} from './pick';
 export {shake, type Shaken} from './shake';

package/src/value/merge.ts

@@ -8,6 +8,9 @@ import type {ArrayOrPlainObject, NestedPartial, PlainObject, UnionToIntersection
  */
 export type AssignOptions = Omit<MergeOptions, 'assignValues'>;
 
+/**
+ * An assigner function for assigning values from one or more objects to the first one
+ */
 export type Assigner = {
 	/**
 	 * Assign values from one or more objects to the first one
@@ -34,7 +37,7 @@ export type MergeOptions = {
 	 * Key _(or key epxressions)_ for values that should be replaced
 	 *
 	 * ```ts
-	 * merge([{items: [1, 2, 3]}, {items: [99]}]); // {items: [99]}
+	 * merge([{items: [1, 2, 3]}, {items: [99]}]); // => {items: [99]}
 	 * ```
 	 */
 	replaceableObjects?: string | RegExp | Array<string | RegExp>;
@@ -42,7 +45,7 @@ export type MergeOptions = {
 	 * Skip nullable values when merging objects?
 	 *
 	 * ```ts
-	 * merge({a: 1, b: 2}, {b: null, c: 3}, {d: null}); // {a: 1, b: 2, c: 3}
+	 * merge({a: 1, b: 2}, {b: null, c: 3}, {d: null}); // => {a: 1, b: 2, c: 3}
 	 * ```
 	 */
 	skipNullableAny?: boolean;
@@ -50,12 +53,15 @@ export type MergeOptions = {
 	 * Skip nullable values when merging arrays?
 	 *
 	 * ```ts
-	 * merge([1, 2, 3], [null, null, 99]); // [1, 2, 99]
+	 * merge([1, 2, 3], [null, null, 99]); // => [1, 2, 99]
 	 * ```
 	 */
 	skipNullableInArrays?: boolean;
 };
 
+/**
+ * A merger function for merging multiple arrays or objects into a single one
+ */
 export type Merger = {
 	/**
 	 * Merge multiple arrays or objects into a single one
@@ -138,7 +144,7 @@ function getReplaceableObjects(value: unknown): ReplaceableObjectsCallback | und
 /**
  * Create an assigner with predefined options
  *
- * Available as `initializeAssigner` and `assign.initialize`
+ * _Available as `initializeAssigner` and `assign.initialize`_
  *
  * @param options Assigning options
  * @returns Assigner function
@@ -155,7 +161,7 @@ export function initializeAssigner(options?: AssignOptions): Assigner {
 /**
  * Create a merger with predefined options
  *
- * Available as `initializeMerger` and `merge.initialize`
+ * _Available as `initializeMerger` and `merge.initialize`_
  *
  * @param options Merging options
  * @returns Merger function

package/src/value/omit.ts

@@ -5,6 +5,7 @@ import type {PlainObject} from '../models';
 
 /**
  * Create a new object without the specified keys
+ *
  * @param value Original object
  * @param keys Keys to omit
  * @returns Partial object without the specified keys

package/src/value/pick.ts

@@ -5,6 +5,7 @@ import type {PlainObject} from '../models';
 
 /**
  * Create a new object with only the specified keys
+ *
  * @param value Original object
  * @param keys Keys to use
  * @returns Partial object with only the specified keys

package/src/value/shake.ts

@@ -16,6 +16,7 @@ export type Shaken<Value extends PlainObject> = {
 
 /**
  * Shake an object, removing all keys with `undefined` values
+ *
  * @param value Object to shake
  * @returns Shaken object
  */

package/src/value/smush.ts

@@ -70,6 +70,7 @@ function flattenObject(
 
 /**
  * Smush an object into a flat object that uses dot notation keys
+ *
  * @param value Object to smush
  * @returns Smushed object with dot notation keys
  */

package/src/value/transform.ts

@@ -62,7 +62,8 @@ function getTransformer<Value extends PlainObject, Key extends keyof Value>(
 /**
  * Initialize a transformer for an object with a transformer function
  *
- * Available as `initializeTransformer` and `transform.initialize`
+ * _Available as `initializeTransformer` and `transform.initialize`_
+ *
  * @param transform Transformer function
  * @returns Transformer
  */
@@ -73,7 +74,8 @@ export function initializeTransformer<Value extends PlainObject>(
 /**
  * Initialize a transformer for an object with transformer functions
  *
- * Available as `initializeTransformer` and `transform.initialize`
+ * _Available as `initializeTransformer` and `transform.initialize`_
+ *
  * @param transformers Keyed transformer functions
  * @returns Transformer
  */
@@ -90,7 +92,8 @@ export function initializeTransformer<Value extends PlainObject>(
 }
 
 /**
- * Transform and objects properties using a transformer functior
+ * Transform and objects properties using a transformer function
+ *
  * @param value Object to transform
  * @param transform Transformer function
  * @returns Transformed object
@@ -102,6 +105,7 @@ export function transform<Value extends PlainObject, Key extends keyof Value>(
 
 /**
  * Transform and objects properties using a transformer object
+ *
  * @param value Object to transform
  * @param transformers Keyed transformer functions
  * @returns Transformed object

package/src/value/unsmush.ts

@@ -52,6 +52,7 @@ function getKeys(value: PlainObject): OrderedKey[] {
 
 /**
  * Unsmush a smushed object _(turning dot notation keys into nested keys)_
+ *
  * @param value Object to unsmush
  * @returns Unsmushed object with nested keys
  */