@oscarpalmer/mora 0.21.0 → 0.23.0

package/src/value/array.ts

@@ -1,15 +1,21 @@
-import type {GenericCallback} from '@oscarpalmer/atoms';
-import {arrayName} from '../helpers/is';
+import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import {
+	METHODS_AFFECTING_LENGTH,
+	METHODS_UPDATE,
+	NAME_ARRAY,
+} from '../constants';
 import {getReactiveValueInProxy, setValueInProxy} from '../helpers/proxy';
 import {emitValue, equalArrays, getValue} from '../helpers/value';
-import {type Unsubscribe, noop, subscribe} from '../subscription';
+import type {ReactiveOptions, ReactiveState, Unsubscribe} from '../models';
+import {noop, subscribe} from '../subscription';
 import {type Computed, computed} from './computed';
-import {Reactive, type ReactiveOptions, type ReactiveState} from './reactive';
+import {Reactive} from './reactive';
 import {type Signal, signal} from './signal';
 
 export class ReactiveArray<Item> extends Reactive<Item[], Item> {
-	#indiced = new Map<number, Computed<unknown>>();
-	#size = signal(0);
+	readonly #indiced = new Map<number, Computed<unknown>>();
+
+	readonly #size = signal(0);
 
 	/**
 	 * The length of the array
@@ -33,21 +39,21 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	constructor(value: Item[], options?: ReactiveOptions<Item>) {
 		super(
-			arrayName,
+			NAME_ARRAY,
 			new Proxy(value, {
-				get: (target, property) =>
-					updateMethods.has(property as string)
+				get: (target: Item[], property: PropertyKey) =>
+					METHODS_UPDATE.has(property as string)
 						? updateArray(property as string, target, this.state, this.#size)
 						: Reflect.get(target, property),
-				set: (target, property, value) =>
-					setValueInProxy(
-						target,
+				set: (target: Item[], property: PropertyKey, value: Item) =>
+					setValueInProxy({
 						property,
+						target,
 						value,
-						this.state,
-						true,
-						this.#size,
-					),
+						isArray: true,
+						state: this.state,
+						length: this.#size,
+					}),
 			}),
 			options,
 		);
@@ -62,6 +68,17 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 		this.length = 0;
 	}
 
+	/**
+	 * Create a computed, filtered array
+	 * @param callback Callback to evaluate each item
+	 * @return Computed array of filtered items
+	 */
+	filter(
+		callback: (item: Item, index: number, array: Item[]) => boolean,
+	): Computed<Item[]> {
+		return computed(() => this.get().filter(callback));
+	}
+
 	/**
 	 * @inheritdoc
 	 */
@@ -69,11 +86,14 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Get the value at an index
+	 * @param index Index of item to get _(if negative, starts from the end)_
+	 * @returns Item at index, or `undefined` if it doesn't exist
 	 */
 	get(index: number): Item | undefined;
 
 	/**
 	 * Get the length of the array
+	 * @returns Length of the array
 	 */
 	get(property: 'length'): number;
 
@@ -89,17 +109,10 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 		return getValue(this.state);
 	}
 
-	/**
-	 * Create a computed, filtered array
-	 */
-	filter(
-		callback: (item: Item, index: number, array: Item[]) => boolean,
-	): Computed<Item[]> {
-		return computed(() => this.get().filter(callback));
-	}
-
 	/**
 	 * Create a computed, mapped array
+	 * @param callback Callback to transform each item
+	 * @return Computed array of mapped items
 	 */
 	map<Mapped>(
 		callback: (item: Item, index: number, array: Item[]) => Mapped,
@@ -107,20 +120,36 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 		return computed(() => this.get().map(callback));
 	}
 
+	/**
+	 * Notify dependents of changes
+	 *
+	 * _This bypasses equality checks and will immediately notify dependents.
+	 * Use this only if you're modifying nested data that would be ignored by equality checks._
+	 */
+	notify(): void {
+		emitValue(this.state);
+	}
+
 	/**
 	 * @inheritdoc
 	 */
 	peek(): Item[];
 
+	/**
+	 * Get the value at an index _(without reactivity)_
+	 * @param index Index of item to get _(if negative, starts from the end)_
+	 * @returns Item at index, or `undefined` if it doesn't exist
+	 */
 	peek(index: number): Item | undefined;
 
 	/**
 	 * Get the length of the array _(without reactivity)_
+	 * @returns Length of the array
 	 */
-	peek(length: true): number;
+	peek(property: 'length'): number;
 
 	peek(value?: unknown): unknown {
-		if (value === true) {
+		if (value === 'length') {
 			return this.#size.peek();
 		}
 
@@ -133,6 +162,7 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Remove and return the last item of the array
+	 * @returns Removed item, or `undefined` if the array is empty
 	 */
 	pop(): Item | undefined {
 		return this.state.value.pop();
@@ -140,6 +170,8 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Add items to the end of the array
+	 * @param items Items to add
+	 * @returns New array length
 	 */
 	push(...items: Item[]): number {
 		return this.state.value.push(...items);
@@ -147,16 +179,20 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Set the value
+	 * @param value New array of items _(defaults to an empty array)_
 	 */
 	set(value?: Item[]): void;
 
 	/**
 	 * Set the value at an index
+	 * @param index Index of item to set __(if negative, starts from the end)_
+	 * @param value New item
 	 */
 	set(index: number, value: Item): void;
 
 	/**
 	 * Set the length of the array
+	 * @param value New array length
 	 */
 	set(property: 'length', value: number): void;
 
@@ -165,13 +201,14 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 			this.state.value.splice(0, this.state.value.length, ...(first ?? []));
 		} else if (first === 'length') {
 			this.length = second as number;
-		} else if (typeof first === 'number') {
-			this.state.value[first] = second as Item;
+		} else if (typeof first === 'number' && !Number.isNaN(first)) {
+			setAtIndex(this.state.value, first, second as Item);
 		}
 	}
 
 	/**
 	 * Remove and return the first item of the array
+	 * @returns Removed item, or `undefined` if the array is empty
 	 */
 	shift(): Item | undefined {
 		return this.state.value.shift();
@@ -179,6 +216,10 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Remove and return items from the array _(and optionally add new items)_
+	 * @param from Index to start removing items from
+	 * @param to Index to stop removing items at _(defaults to the end of the array)_
+	 * @param items Optional items to add
+	 * @returns Removed items
 	 */
 	splice(from: number, to?: number, ...items: Item[]): Item[] {
 		return this.state.value.splice(
@@ -195,6 +236,9 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Subscribe to changes at a specific index
+	 * @param index Index of item to subscribe to
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
 	 */
 	subscribe(
 		index: number,
@@ -219,6 +263,8 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Add items to the beginning of the array
+	 * @param items Items to add
+	 * @returns New array length
 	 */
 	unshift(...items: Item[]): number {
 		return this.state.value.unshift(...items);
@@ -226,6 +272,7 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 	/**
 	 * Update the value _(based on the current value)_
+	 * @param callback Callback to update the value
 	 */
 	update(callback: (value: Item[]) => Item[]): void {
 		const updated = callback(this.state.value);
@@ -238,6 +285,9 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 
 /**
  * Create a reactive array
+ * @param value Initial array of items
+ * @param options Optional reactivity options
+ * @returns Reactive array
  */
 export function array<Item>(
 	value: Item[],
@@ -252,7 +302,7 @@ function updateArray<Item>(
 	state: ReactiveState<Item[], Item>,
 	length: Signal<number>,
 ): unknown {
-	const affectsLength = lengthAffectingMethods.has(type);
+	const affectsLength = METHODS_AFFECTING_LENGTH.has(type);
 	const previousArray = affectsLength ? [] : [...array];
 	const previousLength = array.length;
 
@@ -275,18 +325,10 @@ function updateArray<Item>(
 	};
 }
 
-const lengthAffectingMethods = new Set<string>([
-	'pop',
-	'push',
-	'shift',
-	'unshift',
-]);
-
-const updateMethods = new Set<string>([
-	...lengthAffectingMethods,
-	'copyWithin',
-	'fill',
-	'reverse',
-	'sort',
-	'splice',
-]);
+function setAtIndex<Item>(array: Item[], index: number, value: Item): void {
+	const actual = index < 0 ? array.length + index : index;
+
+	if (actual > -1) {
+		array[actual] = value;
+	}
+}

package/src/value/computed.ts

@@ -1,19 +1,7 @@
-import {batchDepth, batchedHandlers} from '../batch';
-import {type Effect, activeEffect, effect, runEffect} from '../effect';
-import {computedName} from '../helpers/is';
-import {Reactive, type ReactiveOptions, type ReactiveState} from './reactive';
-
-export type ComputedEffect = {
-	dirty: boolean;
-	instance: Effect;
-};
-
-export type InternalComputed = {
-	readonly effect: ComputedEffect;
-	readonly state: ReactiveState<unknown, unknown>;
-};
-
-export let activeComputed: Computed<unknown> | undefined;
+import {ACTIVE, BATCH, NAME_COMPUTED} from '../constants';
+import {effect, runEffect} from '../effect';
+import type {ComputedEffect, ReactiveOptions} from '../models';
+import {Reactive} from './reactive';
 
 export class Computed<Value> extends Reactive<Value> {
 	private readonly effect: ComputedEffect = {
@@ -22,36 +10,38 @@ export class Computed<Value> extends Reactive<Value> {
 	};
 
 	constructor(callback: () => Value, options?: ReactiveOptions<Value>) {
-		super(computedName, undefined as never, options);
+		super(NAME_COMPUTED, undefined as never, options);
 
 		this.effect.instance = effect(() => {
-			if (this.effect.dirty) {
-				const previousComputed = activeComputed;
+			if (!this.effect.dirty) {
+				return;
+			}
 
-				activeComputed = this as never;
+			const previousComputed = ACTIVE.computed;
 
-				const value = callback();
+			ACTIVE.computed = this as never;
 
-				activeComputed = previousComputed;
+			const value = callback();
 
-				if (!this.state.equal(this.state.value, value)) {
-					this.state.value = value;
+			ACTIVE.computed = previousComputed;
 
-					for (const computed of this.state.computeds) {
-						computed.effect.dirty = true;
-					}
+			if (!this.state.equal(this.state.value, value)) {
+				this.state.value = value;
 
-					for (const effect of this.state.effects) {
-						batchedHandlers.add(effect);
-					}
+				for (const computed of this.state.computeds) {
+					computed.effect.dirty = true;
+				}
 
-					for (const [, subscription] of this.state.subscriptions) {
-						subscription.callback(value);
-					}
+				for (const effect of this.state.effects) {
+					BATCH.handlers.add(effect);
 				}
 
-				this.effect.dirty = false;
+				for (const [, subscription] of this.state.subscriptions) {
+					subscription.callback(value);
+				}
 			}
+
+			this.effect.dirty = false;
 		});
 	}
 
@@ -59,15 +49,15 @@ export class Computed<Value> extends Reactive<Value> {
 	 * @inheritdoc
 	 */
 	get(): Value {
-		if (activeComputed != null && this !== activeComputed) {
-			this.state.computeds.add(activeComputed);
+		if (ACTIVE.computed != null && this !== ACTIVE.computed) {
+			this.state.computeds.add(ACTIVE.computed);
 		}
 
-		if (activeEffect != null && activeEffect !== this.effect.instance) {
-			this.state.effects.add(activeEffect);
+		if (ACTIVE.effect != null && ACTIVE.effect !== this.effect.instance) {
+			this.state.effects.add(ACTIVE.effect);
 		}
 
-		if (this.effect.dirty && batchDepth === 0) {
+		if (this.effect.dirty && BATCH.depth === 0) {
 			runEffect(this.effect.instance);
 		}
 

package/src/value/reactive.ts

@@ -1,12 +1,5 @@
-import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import type {Effect} from '../effect';
-import {
-	type Subscription,
-	type Unsubscribe,
-	subscribe,
-	unsubscribe,
-} from '../subscription';
-import type {Computed} from './computed';
+import type {ReactiveOptions, ReactiveState, Unsubscribe} from '../models';
+import {subscribe, unsubscribe} from '../subscription';
 
 export abstract class Reactive<Value, Equal = Value> {
 	protected readonly state: ReactiveState<Value, Equal> = {
@@ -31,11 +24,13 @@ export abstract class Reactive<Value, Equal = Value> {
 
 	/**
 	 * Get the value
+	 * @return Current value
 	 */
 	abstract get(): Value;
 
 	/**
 	 * Get the value _(without reactivity)_
+	 * @return Current value
 	 */
 	peek(): Value {
 		return this.state.value;
@@ -43,6 +38,8 @@ export abstract class Reactive<Value, Equal = Value> {
 
 	/**
 	 * Subscribe to changes
+	 * @param callback Callback for changes
+	 * @return Unsubscribe callback
 	 */
 	subscribe(callback: (value: Value) => void): Unsubscribe {
 		return subscribe(this.state, callback);
@@ -50,6 +47,7 @@ export abstract class Reactive<Value, Equal = Value> {
 
 	/**
 	 * JSON representation of the value
+	 * @return JSON value
 	 */
 	toJSON(): Value {
 		return this.get();
@@ -57,6 +55,7 @@ export abstract class Reactive<Value, Equal = Value> {
 
 	/**
 	 * String representation of the value
+	 * @return Value as string
 	 */
 	toString(): string {
 		return String(this.get());
@@ -64,23 +63,9 @@ export abstract class Reactive<Value, Equal = Value> {
 
 	/**
 	 * Unsubscribe from changes
+	 * @param callback Callback to unsubscribe
 	 */
 	unsubscribe(callback: (value: Value) => void): void {
 		unsubscribe(this.state, callback);
 	}
 }
-
-export type ReactiveOptions<Value> = {
-	/**
-	 * Method to compare values for equality
-	 */
-	equal?: (first: Value, second: Value) => boolean;
-};
-
-export type ReactiveState<Value, Equal> = {
-	computeds: Set<Computed<unknown>>;
-	effects: Set<Effect>;
-	equal: (first: Equal, second: Equal) => boolean;
-	subscriptions: Map<GenericCallback, Subscription>;
-	value: Value;
-};

package/src/value/signal.ts

@@ -1,10 +1,11 @@
-import {signalName} from '../helpers/is';
+import {NAME_SIGNAL} from '../constants';
 import {emitValue, getValue} from '../helpers/value';
-import {Reactive, type ReactiveOptions} from './reactive';
+import type {ReactiveOptions} from '../models';
+import {Reactive} from './reactive';
 
 export class Signal<Value> extends Reactive<Value> {
 	constructor(value: Value, options?: ReactiveOptions<Value>) {
-		super(signalName, value, options);
+		super(NAME_SIGNAL, value, options);
 	}
 
 	/**
@@ -16,6 +17,7 @@ export class Signal<Value> extends Reactive<Value> {
 
 	/**
 	 * Set the value
+	 * @param value New value
 	 */
 	set(value: Value): void {
 		if (!this.state.equal(this.state.value, value)) {
@@ -27,6 +29,7 @@ export class Signal<Value> extends Reactive<Value> {
 
 	/**
 	 * Update the value _(based on the current value)_
+	 * @param callback Callback to update the value
 	 */
 	update(callback: (value: Value) => Value): void {
 		this.set(callback(this.state.value));
@@ -35,6 +38,9 @@ export class Signal<Value> extends Reactive<Value> {
 
 /**
  * Create a reactive value
+ * @param value Initial value
+ * @param options Optional reactivity options
+ * @returns Reactive value
  */
 export function signal<Value>(
 	value: Value,

package/src/value/store.ts

@@ -4,26 +4,33 @@ import type {
 	Key,
 	PlainObject,
 } from '@oscarpalmer/atoms/models';
-import {storeName} from '../helpers/is';
+import {NAME_STORE} from '../constants';
 import {
 	getReactiveValueInProxy,
 	setProxyValue,
 	setValueInProxy,
 } from '../helpers/proxy';
 import {getValue} from '../helpers/value';
-import {type Unsubscribe, noop, subscribe} from '../subscription';
+import type {ReactiveOptions, Unsubscribe} from '../models';
+import {noop, subscribe} from '../subscription';
 import type {Computed} from './computed';
-import {Reactive, type ReactiveOptions} from './reactive';
+import {Reactive} from './reactive';
 
 export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
-	#keyed = new Map<Key, Computed<unknown>>();
+	readonly #keyed = new Map<Key, Computed<unknown>>();
 
 	constructor(value: Value, options?: ReactiveOptions<Value>) {
 		super(
-			storeName,
+			NAME_STORE,
 			new Proxy(value, {
-				set: (target, property, value) =>
-					setValueInProxy(target, property, value, this.state, false),
+				set: (target: Value, property: PropertyKey, value: unknown) =>
+					setValueInProxy({
+						target,
+						property,
+						value,
+						isArray: false,
+						state: this.state,
+					}),
 			}),
 			options,
 		);
@@ -35,12 +42,16 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 	get(): Value;
 
 	/**
-	 * Get a value by key _(without reactivity)_
+	 * Get a value by key
+	 * @param key Key of the value to get
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
 	 */
 	get(key: keyof Value): Value[keyof Value];
 
 	/**
-	 * Get a value by key _(without reactivity)_
+	 * Get a value by key
+	 * @param key Key of the value to get
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
 	 */
 	get(key: Key): unknown;
 
@@ -52,16 +63,21 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 	/**
 	 * Get the value _(without reactivity)_
+	 * @returns The current value
 	 */
 	peek(): Value;
 
 	/**
 	 * Get a value by key _(without reactivity)_
+	 * @param key Key of the value to get
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
 	 */
 	peek(key: keyof Value): Value[keyof Value];
 
 	/**
 	 * Get a value by key _(without reactivity)_
+	 * @param key Key of the value to get
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
 	 */
 	peek(key: Key): unknown;
 
@@ -71,16 +87,21 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 	/**
 	 * Set the value
+	 * @param value New value _(defaults to an empty object)_
 	 */
 	set(value?: Value): void;
 
 	/**
 	 * Set a value by key
+	 * @param key Key of the value to set
+	 * @param value New value
 	 */
 	set(key: keyof Value, value: Value[keyof Value]): void;
 
 	/**
 	 * Set a value by key
+	 * @param key Key of the value to set
+	 * @param value New value
 	 */
 	set(key: Key, value: unknown): void;
 
@@ -99,6 +120,9 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 	/**
 	 * Subscribe to changes for a specific key
+	 * @param key Key of the value to subscribe to
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
 	 */
 	subscribe<Key extends keyof Value>(
 		key: Key,
@@ -107,6 +131,9 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 	/**
 	 * Subscribe to changes for a specific key
+	 * @param key Key of the value to subscribe to
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
 	 */
 	subscribe(key: Key, callback: (value: unknown) => void): Unsubscribe;
 
@@ -125,6 +152,7 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 	/**
 	 * Update the value _(based on the current value)_
+	 * @param callback Callback to update the value
 	 */
 	update(callback: (value: Value) => Value): void {
 		const updated = callback({...this.state.value});
@@ -137,6 +165,9 @@ export class Store<Value extends PlainObject> extends Reactive<Value, Value> {
 
 /**
  * Create a reactive store
+ * @param value Initial object value
+ * @param options Optional reactivity options
+ * @returns Reactive store
  */
 export function store<Value extends PlainObject>(
 	value: Value,

package/types/batch.d.ts

@@ -1,13 +1,11 @@
-import { type Effect } from './effect';
-import type { Subscription } from './subscription';
 export declare function flushHandlers(): void;
 /**
- * Start batching effects _(use `stopBatch` to flush and run batched effects)_
+ * Start batching effects
+ *
+ * _(Use {@link stopBatch} to flush and run batched effects)_
  */
 export declare function startBatch(): void;
 /**
  * Stop batching effects and flush _(run)_ them
  */
 export declare function stopBatch(): void;
-export declare const batchedHandlers: Set<Subscription | Effect>;
-export declare let batchDepth: number;

package/types/constants.d.ts

@@ -0,0 +1,14 @@
+import type { Active, Batch } from './models';
+export declare const ACTIVE: Active;
+export declare const ARRAY_THRESHOLD = 100;
+export declare const ARRAY_OFFSET = 25;
+export declare const ARRAY_PEEK = 10;
+export declare const BATCH: Batch;
+export declare const METHODS_AFFECTING_LENGTH: Set<string>;
+export declare const METHODS_UPDATE: Set<string>;
+export declare const NAME_ARRAY = "array";
+export declare const NAME_COMPUTED = "computed";
+export declare const NAME_EFFECT = "effect";
+export declare const NAME_SIGNAL = "signal";
+export declare const NAME_STORE = "store";
+export declare const NAMES: Set<string>;

package/types/effect.d.ts

@@ -7,6 +7,7 @@ export declare class Effect {
 export declare function runEffect(effect: Effect): void;
 /**
  * Create an effect
+ * @param callback Callback for handling signal effects
+ * @returns Effect
  */
 export declare function effect(callback: GenericCallback): Effect;
-export declare let activeEffect: Effect | undefined;