@oscarpalmer/mora 0.22.0 → 0.23.0

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,21 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import {arrayName} from '../helpers/is';
+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,