@oscarpalmer/mora 0.22.0 → 0.23.0

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;

package/types/helpers/is.d.ts

@@ -7,24 +7,37 @@ import type { Signal } from '../value/signal';
 import type { Store } from '../value/store';
 /**
  * Is the value a reactive array?
+ * @param value Value to check
+ * @returns True if value is a {@link ReactiveArray}
  */
-export declare function isArray(value: unknown): value is ReactiveArray<unknown>;
+export declare function isArray<Item>(value: unknown): value is ReactiveArray<Item>;
 /**
  * Is the value a computed signal?
+ * @param value Value to check
+ * @returns True if value is a {@link Computed}
  */
-export declare function isComputed(value: unknown): value is Computed<unknown>;
+export declare function isComputed<Value>(value: unknown): value is Computed<Value>;
 /**
  * Is the value an effect?
+ * @param value Value to check
+ * @returns True if value is an {@link Effect}
  */
 export declare function isEffect(value: unknown): value is Effect;
-export declare function isReactive(value: unknown): value is Reactive<unknown>;
+/**
+ * Is the value reactive?
+ * @param value Value to check
+ * @returns True if value is a {@link Reactive}
+ */
+export declare function isReactive<Value, Equal = Value>(value: unknown): value is Reactive<Value, Equal>;
 /**
  * Is the value a signal?
+ * @param value Value to check
+ * @returns True if value is a {@link Signal}
+ */
+export declare function isSignal<Value>(value: unknown): value is Signal<Value>;
+/**
+ * Is the value a reactive store?
+ * @param value Value to check
+ * @returns True if value is a {@link Store}
  */
-export declare function isSignal(value: unknown): value is Signal<unknown>;
-export declare function isStore(value: unknown): value is Store<PlainObject>;
-export declare const arrayName = "array";
-export declare const computedName = "computed";
-export declare const effectName = "effect";
-export declare const signalName = "signal";
-export declare const storeName = "store";
+export declare function isStore<Value extends PlainObject>(value: unknown): value is Store<Value>;

package/types/helpers/proxy.d.ts

@@ -1,10 +1,9 @@
 import type { ArrayOrPlainObject, Key, PlainObject } from '@oscarpalmer/atoms/models';
+import type { SetValueInProxyParameters } from '../models';
 import type { ReactiveArray } from '../value/array';
 import { type Computed } from '../value/computed';
-import type { ReactiveState } from '../value/reactive';
-import type { Signal } from '../value/signal';
 import type { Store } from '../value/store';
 export declare function getReactiveValueInProxy<Value>(array: ReactiveArray<Value>, mapped: Map<Key, Computed<unknown>>, index: number, isArray: true): Computed<unknown>;
 export declare function getReactiveValueInProxy<Value extends PlainObject>(store: Store<Value>, mapped: Map<Key, Computed<unknown>>, key: Key, isArray: false): Computed<unknown>;
 export declare function setProxyValue(proxy: ArrayOrPlainObject, value: ArrayOrPlainObject): void;
-export declare function setValueInProxy<Value extends ArrayOrPlainObject, Equal>(target: Value, property: PropertyKey, value: unknown, state: ReactiveState<Value, Equal>, isArray: boolean, length?: Signal<number>): boolean;
+export declare function setValueInProxy<Value extends ArrayOrPlainObject, Equal>(parameters: SetValueInProxyParameters<Value, Equal>): boolean;

package/types/helpers/value.d.ts

@@ -1,4 +1,4 @@
-import type { ReactiveState } from '../value/reactive';
+import type { ReactiveState } from '../models';
 export declare function emitValue<Value>(state: ReactiveState<Value, never>): void;
 export declare function equalArrays<Value>(state: ReactiveState<Value[], Value>, first: Value[], second: Value[]): boolean;
 export declare function getValue<Value>(state: ReactiveState<Value, never>): Value;

package/types/index.d.ts

@@ -1,6 +1,7 @@
 export { startBatch, stopBatch } from './batch';
 export { effect, type Effect } from './effect';
 export { isArray, isComputed, isEffect, 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/types/models.d.ts

@@ -0,0 +1,56 @@
+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/types/subscription.d.ts

@@ -1,14 +1,11 @@
 import type { GenericCallback } from '@oscarpalmer/atoms/models';
-import type { ReactiveState } from './value/reactive';
+import type { ReactiveState, Unsubscribe } from './models';
 export declare class Subscription {
-    state: ReactiveState<unknown, never>;
     callback: GenericCallback;
+    state: ReactiveState<unknown, never>;
     constructor(state: ReactiveState<unknown, never>, callback: GenericCallback);
+    destroy(): void;
 }
-/**
- * Unsubscribe from changes
- */
-export type Unsubscribe = () => void;
 export declare function noop(): void;
 export declare function subscribe<Value>(state: ReactiveState<Value, never>, callback: (value: Value) => void): Unsubscribe;
 export declare function unsubscribe<Value>(state: ReactiveState<Value, never>, callback: (value: Value) => void): void;

package/types/value/array.d.ts

@@ -1,6 +1,6 @@
-import { type Unsubscribe } from '../subscription';
+import type { ReactiveOptions, Unsubscribe } from '../models';
 import { type Computed } from './computed';
-import { Reactive, type ReactiveOptions } from './reactive';
+import { Reactive } from './reactive';
 export declare class ReactiveArray<Item> extends Reactive<Item[], Item> {
     #private;
     /**
@@ -16,61 +16,93 @@ export declare class ReactiveArray<Item> extends Reactive<Item[], Item> {
      * Clear the array
      */
     clear(): void;
+    /**
+     * 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[]>;
     /**
      * @inheritdoc
      */
     get(): 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;
-    /**
-     * Create a computed, filtered array
-     */
-    filter(callback: (item: Item, index: number, array: Item[]) => boolean): Computed<Item[]>;
     /**
      * 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): Computed<Mapped[]>;
+    /**
+     * 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;
     /**
      * @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;
     /**
      * Remove and return the last item of the array
+     * @returns Removed item, or `undefined` if the array is empty
      */
     pop(): Item | undefined;
     /**
      * Add items to the end of the array
+     * @param items Items to add
+     * @returns New array length
      */
     push(...items: Item[]): number;
     /**
      * 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;
     /**
      * Remove and return the first item of the array
+     * @returns Removed item, or `undefined` if the array is empty
      */
     shift(): Item | undefined;
     /**
      * 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[];
     /**
@@ -79,18 +111,27 @@ export declare class ReactiveArray<Item> extends Reactive<Item[], Item> {
     subscribe(callback: (value: Item[]) => void): Unsubscribe;
     /**
      * 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, callback: (value: Item | undefined) => void): Unsubscribe;
     /**
      * Add items to the beginning of the array
+     * @param items Items to add
+     * @returns New array length
      */
     unshift(...items: Item[]): number;
     /**
      * Update the value _(based on the current value)_
+     * @param callback Callback to update the value
      */
     update(callback: (value: Item[]) => Item[]): void;
 }
 /**
  * Create a reactive array
+ * @param value Initial array of items
+ * @param options Optional reactivity options
+ * @returns Reactive array
  */
 export declare function array<Item>(value: Item[], options?: ReactiveOptions<Item>): ReactiveArray<Item>;

package/types/value/computed.d.ts

@@ -1,14 +1,5 @@
-import { type Effect } from '../effect';
-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 declare let activeComputed: Computed<unknown> | undefined;
+import type { ReactiveOptions } from '../models';
+import { Reactive } from './reactive';
 export declare class Computed<Value> extends Reactive<Value> {
     private readonly effect;
     constructor(callback: () => Value, options?: ReactiveOptions<Value>);

package/types/value/reactive.d.ts

@@ -1,45 +1,36 @@
-import type { GenericCallback } from '@oscarpalmer/atoms/models';
-import type { Effect } from '../effect';
-import { type Subscription, type Unsubscribe } from '../subscription';
-import type { Computed } from './computed';
+import type { ReactiveOptions, ReactiveState, Unsubscribe } from '../models';
 export declare abstract class Reactive<Value, Equal = Value> {
     protected readonly state: ReactiveState<Value, Equal>;
     constructor(name: string, value: Value, options?: ReactiveOptions<Equal>);
     /**
      * Get the value
+     * @return Current value
      */
     abstract get(): Value;
     /**
      * Get the value _(without reactivity)_
+     * @return Current value
      */
     peek(): Value;
     /**
      * Subscribe to changes
+     * @param callback Callback for changes
+     * @return Unsubscribe callback
      */
     subscribe(callback: (value: Value) => void): Unsubscribe;
     /**
      * JSON representation of the value
+     * @return JSON value
      */
     toJSON(): Value;
     /**
      * String representation of the value
+     * @return Value as string
      */
     toString(): string;
     /**
      * Unsubscribe from changes
+     * @param callback Callback to unsubscribe
      */
     unsubscribe(callback: (value: Value) => void): void;
 }
-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/types/value/signal.d.ts

@@ -1,4 +1,5 @@
-import { Reactive, type ReactiveOptions } from './reactive';
+import type { ReactiveOptions } from '../models';
+import { Reactive } from './reactive';
 export declare class Signal<Value> extends Reactive<Value> {
     constructor(value: Value, options?: ReactiveOptions<Value>);
     /**
@@ -7,14 +8,19 @@ export declare class Signal<Value> extends Reactive<Value> {
     get(): Value;
     /**
      * Set the value
+     * @param value New value
      */
     set(value: Value): void;
     /**
      * Update the value _(based on the current value)_
+     * @param callback Callback to update the value
      */
     update(callback: (value: Value) => Value): void;
 }
 /**
  * Create a reactive value
+ * @param value Initial value
+ * @param options Optional reactivity options
+ * @returns Reactive value
  */
 export declare function signal<Value>(value: Value, options?: ReactiveOptions<Value>): Signal<Value>;

package/types/value/store.d.ts

@@ -1,6 +1,6 @@
 import type { Key, PlainObject } from '@oscarpalmer/atoms/models';
-import { type Unsubscribe } from '../subscription';
-import { Reactive, type ReactiveOptions } from './reactive';
+import type { ReactiveOptions, Unsubscribe } from '../models';
+import { Reactive } from './reactive';
 export declare class Store<Value extends PlainObject> extends Reactive<Value, Value> {
     #private;
     constructor(value: Value, options?: ReactiveOptions<Value>);
@@ -9,35 +9,49 @@ export declare class Store<Value extends PlainObject> extends Reactive<Value, Va
      */
     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;
     /**
      * 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;
     /**
      * 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;
     /**
@@ -46,18 +60,28 @@ export declare class Store<Value extends PlainObject> extends Reactive<Value, Va
     subscribe(callback: (value: Value) => void): Unsubscribe;
     /**
      * 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, callback: (value: Value[Key] | undefined) => void): Unsubscribe;
     /**
      * 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;
     /**
      * Update the value _(based on the current value)_
+     * @param callback Callback to update the value
      */
     update(callback: (value: Value) => Value): void;
 }
 /**
  * Create a reactive store
+ * @param value Initial object value
+ * @param options Optional reactivity options
+ * @returns Reactive store
  */
 export declare function store<Value extends PlainObject>(value: Value, options?: ReactiveOptions<Value>): Store<Value>;