@oscarpalmer/mora 0.22.0 → 0.24.0

package/src/helpers/proxy.ts

@@ -4,50 +4,76 @@ import type {
 	PlainObject,
 } from '@oscarpalmer/atoms/models';
 import {startBatch, stopBatch} from '../batch';
+import {PROPERTY_LENGTH} from '../constants';
+import type {
+	InternalComputed,
+	ReactiveState,
+	SetValueInProxyParameters,
+} from '../models';
 import type {ReactiveArray} from '../value/array';
 import {type Computed, computed} from '../value/computed';
-import type {ReactiveState} from '../value/reactive';
-import type {Signal} from '../value/signal';
 import type {Store} from '../value/store';
 import {emitValue} from './value';
 
+export function emityProxyValues<Value>(
+	state: ReactiveState<Value, Value>,
+	mapped: Map<Key, Computed<unknown>>,
+): void;
+
+export function emityProxyValues<Value>(
+	state: ReactiveState<Value[], Value>,
+	mapped: Map<Key, Computed<unknown>>,
+): void;
+
+export function emityProxyValues(
+	state: ReactiveState<unknown, unknown>,
+	mapped: Map<Key, Computed<unknown>>,
+): void {
+	const values = [...mapped.values()];
+	const {length} = values;
+
+	for (let index = 0; index < length; index += 1) {
+		(values[index] as unknown as InternalComputed).effect.dirty = true;
+	}
+
+	emitValue(state);
+}
+
 export function getReactiveValueInProxy<Value>(
-		array: ReactiveArray<Value>,
-		mapped: Map<Key, Computed<unknown>>,
-		index: number,
-		isArray: true,
-	): Computed<unknown>;
+	array: ReactiveArray<Value>,
+	mapped: Map<Key, Computed<unknown>>,
+	index: number,
+	isArray: true,
+): Computed<unknown>;
 
 export function getReactiveValueInProxy<Value extends PlainObject>(
-		store: Store<Value>,
-		mapped: Map<Key, Computed<unknown>>,
-		key: Key,
-		isArray: false,
-	): Computed<unknown>;
+	store: Store<Value>,
+	mapped: Map<Key, Computed<unknown>>,
+	key: Key,
+	isArray: false,
+): Computed<unknown>;
 
 export function getReactiveValueInProxy(
-		reactive: ReactiveArray<unknown> | Store<PlainObject>,
-		mapped: Map<Key, Computed<unknown>>,
-		key: Key,
-		isArray: boolean,
-	): Computed<unknown> {
-		let item = mapped.get(key);
-
-		if (item == null) {
-			item = computed(() => {
-				const value = reactive.get();
-
-				return isArray
-					? (value as unknown[]).at(key as number)
-					: (value as PlainObject)[key];
-			}) as Computed<unknown>;
-
-			mapped.set(key, item);
-		}
+	reactive: ReactiveArray<unknown> | Store<PlainObject>,
+	mapped: Map<Key, Computed<unknown>>,
+	key: Key,
+	isArray: boolean,
+): Computed<unknown> {
+	let item = mapped.get(key);
+
+	if (item == null) {
+		item = computed(() =>
+			isArray
+				? (reactive.get() as unknown[]).at(key as number)
+				: (reactive.get() as PlainObject)[key],
+		) as Computed<unknown>;
 
-		return item;
+		mapped.set(key, item);
 	}
 
+	return item;
+}
+
 export function setProxyValue(
 	proxy: ArrayOrPlainObject,
 	value: ArrayOrPlainObject,
@@ -83,18 +109,15 @@ export function setProxyValue(
 }
 
 export function setValueInProxy<Value extends ArrayOrPlainObject, Equal>(
-	target: Value,
-	property: PropertyKey,
-	value: unknown,
-	state: ReactiveState<Value, Equal>,
-	isArray: boolean,
-	length?: Signal<number>,
+	parameters: SetValueInProxyParameters<Value, Equal>,
 ): boolean {
+	const {isArray, length, property, state, target, value} = parameters;
+
 	if (isArray) {
 		const isIndex = !Number.isNaN(Number(property));
-		const isLength = property === 'length';
+		const isLength = property === PROPERTY_LENGTH;
 
-		if (!isIndex && !isLength) {
+		if (!(isIndex || isLength)) {
 			return Reflect.set(target, property, value);
 		}
 	}

package/src/helpers/value.ts

@@ -1,7 +1,12 @@
-import {batchDepth, batchedHandlers, flushHandlers} from '../batch';
-import {activeEffect} from '../effect';
-import {activeComputed, type InternalComputed} from '../value/computed';
-import type {ReactiveState} from '../value/reactive';
+import {flushHandlers} from '../batch';
+import {
+	ACTIVE,
+	ARRAY_OFFSET,
+	ARRAY_PEEK,
+	ARRAY_THRESHOLD,
+	BATCH,
+} from '../constants';
+import type {InternalComputed, ReactiveState} from '../models';
 
 export function emitValue<Value>(state: ReactiveState<Value, never>): void {
 	for (const computed of state.computeds) {
@@ -9,14 +14,14 @@ export function emitValue<Value>(state: ReactiveState<Value, never>): void {
 	}
 
 	for (const effect of state.effects) {
-		batchedHandlers.add(effect);
+		BATCH.handlers.add(effect);
 	}
 
 	for (const [, subscription] of state.subscriptions) {
-		batchedHandlers.add(subscription as never);
+		BATCH.handlers.add(subscription);
 	}
 
-	if (batchDepth === 0) {
+	if (BATCH.depth === 0) {
 		flushHandlers();
 	}
 }
@@ -34,9 +39,9 @@ export function equalArrays<Value>(
 
 	let offset = 0;
 
-	if (length >= 100) {
-		offset = Math.round(length / 10);
-		offset = offset > 25 ? 25 : offset;
+	if (length >= ARRAY_THRESHOLD) {
+		offset = Math.round(length / ARRAY_PEEK);
+		offset = offset > ARRAY_OFFSET ? ARRAY_OFFSET : offset;
 
 		for (let index = 0; index < offset; index += 1) {
 			if (!state.equal(first[index], second[index])) {
@@ -57,12 +62,12 @@ export function equalArrays<Value>(
 }
 
 export function getValue<Value>(state: ReactiveState<Value, never>): Value {
-	if (activeComputed != null) {
-		state.computeds.add(activeComputed);
+	if (ACTIVE.computed != null) {
+		state.computeds.add(ACTIVE.computed);
 	}
 
-	if (activeEffect != null) {
-		state.effects.add(activeEffect);
+	if (ACTIVE.effect != null) {
+		state.effects.add(ACTIVE.effect);
 	}
 
 	return state.value;

package/src/index.ts

@@ -7,6 +7,7 @@ export {
 	isReactive,
 	isSignal,
 } from './helpers/is';
+export type {Unsubscribe} from './models';
 export {array, type ReactiveArray} from './value/array';
 export {computed, type Computed} from './value/computed';
 export type {Reactive} from './value/reactive';

package/src/models.ts

@@ -0,0 +1,66 @@
+import type {GenericCallback} from '@oscarpalmer/atoms/models';
+import type {Effect} from './effect';
+import type {Subscription} from './subscription';
+import type {Computed} from './value/computed';
+import type {Signal} from './value/signal';
+
+export type Active = {
+	computed?: Computed<unknown>;
+	effect?: Effect;
+};
+
+export type Batch = {
+	depth: number;
+	handlers: Set<Effect | Subscription>;
+};
+
+export type ComputedEffect = {
+	dirty: boolean;
+	instance: Effect;
+};
+
+export type EffectState = {
+	callback: GenericCallback;
+};
+
+export type InternalComputed = {
+	readonly effect: ComputedEffect;
+	readonly state: ReactiveState<unknown, unknown>;
+};
+
+export type InternalEffect = {
+	state: EffectState;
+};
+
+export type ReactiveOptions<Value> = {
+	/**
+	 * Method for comparing values for equality
+	 * @param first First value
+	 * @param second Second value
+	 * @returns Are the values equal?
+	 * @default Object.is
+	 */
+	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;
+};
+
+export type SetValueInProxyParameters<Value, Equal> = {
+	target: Value;
+	property: PropertyKey;
+	value: unknown;
+	state: ReactiveState<Value, Equal>;
+	isArray: boolean;
+	length?: Signal<number>;
+};
+
+/**
+ * Unsubscribe from changes
+ */
+export type Unsubscribe = () => void;

package/src/subscription.ts

@@ -1,19 +1,22 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import type {ReactiveState} from './value/reactive';
+import type {ReactiveState, Unsubscribe} from './models';
 
 export class Subscription {
-	constructor(
-		public state: ReactiveState<unknown, never>,
-		public callback: GenericCallback,
-	) {
+	callback: GenericCallback;
+	state: ReactiveState<unknown, never>;
+
+	constructor(state: ReactiveState<unknown, never>, callback: GenericCallback) {
+		this.state = state;
+		this.callback = callback;
+
 		callback(state.value);
 	}
-}
 
-/**
- * Unsubscribe from changes
- */
-export type Unsubscribe = () => void;
+	destroy(): void {
+		this.callback = noop;
+		this.state = undefined as never;
+	}
+}
 
 export function noop(): void {}
 
@@ -36,12 +39,7 @@ export function unsubscribe<Value>(
 	state: ReactiveState<Value, never>,
 	callback: (value: Value) => void,
 ): void {
-	const subscription = state.subscriptions.get(callback);
+	state.subscriptions.get(callback)?.destroy();
 
 	state.subscriptions.delete(callback);
-
-	if (subscription != null) {
-		subscription.callback = noop;
-		subscription.state = undefined as never;
-	}
 }

package/src/value/array.ts

@@ -1,15 +1,22 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import {arrayName} from '../helpers/is';
-import {getReactiveValueInProxy, setValueInProxy} from '../helpers/proxy';
+import {
+	METHODS_AFFECTING_LENGTH,
+	METHODS_UPDATE,
+	NAME_ARRAY,
+	PROPERTY_LENGTH,
+} from '../constants';
+import {emityProxyValues, 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 +40,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 +69,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 +87,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;
 
@@ -82,24 +103,13 @@ export class ReactiveArray<Item> extends Reactive<Item[], Item> {
 			return getReactiveValueInProxy(this, this.#indiced, first, true).get();
 		}
 
-		if (first === 'length') {
-			return this.length;
-		}
-
-		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));
+		return first === PROPERTY_LENGTH ? this.length : getValue(this.state);
 	}
 
 	/**
 	 * 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,32 +117,47 @@ 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 {
+		emityProxyValues(this.state, this.#indiced);
+	}
+
 	/**
 	 * @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();
 		}
 
-		if (typeof value === 'number') {
-			return this.state.value.at(value);
-		}
-
-		return [...this.state.value];
+		return typeof value === 'number'
+			? this.state.value.at(value)
+			: [...this.state.value];
 	}
 
 	/**
 	 * 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 +165,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 +174,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 +196,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 +211,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 +231,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 +258,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 +267,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 +280,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 +297,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 +320,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;
+	}
+}