@oscarpalmer/mora 0.29.0 → 0.31.0

package/src/models.ts

@@ -1,37 +1,276 @@
-import type {GenericCallback, Key} 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';
+import type {GenericCallback, Key, PlainObject} from '@oscarpalmer/atoms/models';
+import type {PROPERTY_LENGTH} from './constants';
 
 export type Active = {
-	computed?: Computed<unknown>;
-	effect?: Effect;
+	computed?: ComputedEffect;
+	effect?: EffectState;
 };
 
 export type Batch = {
 	depth: number;
-	handlers: Set<Effect | Subscription>;
+	flushing: boolean;
+	handlers: Set<EffectState | Subscription>;
 };
 
+export type Computed<Value> = Reactive<Value> & SimpleReactive<Value>;
+
 export type ComputedEffect = {
 	dirty: boolean;
-	instance: Effect;
+	instance: EffectState;
 };
 
+export type Effect = {};
+
 export type EffectState = {
 	callback: GenericCallback;
 };
 
-export type InternalComputed = {
-	readonly effect: ComputedEffect;
-	readonly state: ReactiveState<unknown, unknown>;
-};
+export type Reactive<Value> = {
+	/**
+	 * JSON representation of the value
+	 *
+	 * @returns JSON value
+	 */
+	toJSON(): Value;
 
-export type InternalEffect = {
-	state: EffectState;
+	/**
+	 * String representation of the value
+	 *
+	 * @returns Value as string
+	 */
+	toString(): string;
 };
 
+export type ReactiveArray<Item> = {
+	/**
+	 * The length of the array
+	 */
+	get length(): number;
+
+	/**
+	 * Set the length of the array
+	 */
+	set length(value: number);
+
+	/**
+	 * Get a readonly version of the reactive array
+	 *
+	 * @param frozen Freeze the array? _(defaults to `false`)_
+	 * @returns Readonly reactive array
+	 */
+	asReadonly(frozen: true): ReadonlyFrozenSignal<Item[]>;
+
+	/**
+	 * Get a readonly version of the reactive array
+	 *
+	 * @param frozen Freeze the array? _(defaults to `false`)_
+	 * @returns Readonly reactive array
+	 */
+	asReadonly(
+		frozen?: boolean,
+	): typeof frozen extends true ? ReadonlyFrozenSignal<Item[]> : ReadonlySignal<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
+	 */
+	at(index: number): Item | undefined;
+
+	/**
+	 * Clear the array
+	 */
+	clear(): void;
+
+	/**
+	 * Create a computed, filtered array
+	 *
+	 * @param callback Callback to evaluate each item
+	 * @returns Computed array of filtered items
+	 */
+	filter(callback: (item: Item, index: number, array: Item[]) => boolean): Computed<Item[]>;
+
+	/**
+	 * Get the array
+	 *
+	 * @returns Array of items
+	 */
+	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: typeof PROPERTY_LENGTH): number;
+
+	/**
+	 * Create a computed, mapped array
+	 *
+	 * @param callback Callback to transform each item
+	 * @returns 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;
+
+	/**
+	 * Get the array _(without reactivity)_
+	 *
+	 * @param copy Copy the array? _(defaults to `false`)_
+	 * @returns Array of items
+	 */
+	peek(copy?: boolean): Item[];
+
+	/**
+	 * Get the value at an index _(without reactivity)_
+	 *
+	 * @param index Index of item to get _(if negative, starts from the end)_
+	 * @param copy If the item is an array or record, should it be copied? _(defaults to `false`)_
+	 * @returns Item at index, or `undefined` if it doesn't exist
+	 */
+	peek(index: number, copy?: boolean): Item | undefined;
+
+	/**
+	 * Get the length of the array _(without reactivity)_
+	 *
+	 * @returns Length of the array
+	 */
+	peek(property: typeof 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;
+
+	/**
+	 * Create a computed, filtered, and mapped array
+	 *
+	 * @param filter Callback to evaluate each item
+	 * @param map Callback to transform each item
+	 * @returns Computed array of mapped items
+	 */
+	select<Mapped>(
+		filter: (item: Item, index: number, array: Item[]) => boolean,
+		map: (item: Item, index: number, array: Item[]) => Mapped,
+	): Computed<Mapped[]>;
+
+	/**
+	 * Set the value
+	 *
+	 * @param value New array of items _(defaults to an empty array)_
+	 */
+	set(
+		value?:
+			| Item[]
+			| (() => null | undefined | Item[] | Promise<null | undefined | Item[]>)
+			| Promise<null | undefined | 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 | (() => Item | Promise<Item>) | Promise<Item>): void;
+
+	/**
+	 * Set the length of the array
+	 *
+	 * @param value New array length
+	 */
+	set(property: typeof 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[];
+
+	/**
+	 * Subscribe to changes
+	 *
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
+	 */
+	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;
+
+	/**
+	 * Unsubscribe from changes for a specific index
+	 *
+	 * @param index Index of the value to unsubscribe from
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe(index: number, callback: (item: Item | undefined) => void): void;
+
+	/**
+	 * Unsubscribe from changes
+	 *
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe(callback: (array: Item[]) => void): void;
+
+	/**
+	 * Update the value _(based on the current value)_
+	 *
+	 * @param callback Callback to update the value
+	 */
+	update(callback: (value: Item[]) => Item[]): void;
+} & Reactive<Item[]>;
+
 export type ReactiveOptions<Value> = {
 	/**
 	 * Method for comparing values for equality
@@ -44,8 +283,8 @@ export type ReactiveOptions<Value> = {
 };
 
 export type ReactiveState<Value, Equal> = {
-	computeds: Set<Computed<unknown>>;
-	effects: Set<Effect>;
+	computeds: Set<ComputedEffect>;
+	effects: Set<EffectState>;
 	equal: (first: Equal, second: Equal) => boolean;
 	promise?: Promise<Value>;
 	promises?: Map<Key, Promise<never>>;
@@ -53,6 +292,197 @@ export type ReactiveState<Value, Equal> = {
 	value: Value;
 };
 
+export type ReactiveStore<Store> = {
+	/**
+	 * Get a readonly version of the reactive store
+	 *
+	 * @param frozen Freeze the store? _(defaults to `false`)_
+	 * @returns Readonly reactive store
+	 */
+	asReadonly(frozen: true): ReadonlyFrozenSignal<Store>;
+
+	/**
+	 * Get a readonly version of the reactive store
+	 *
+	 * @param frozen Freeze the store? _(defaults to `false`)_
+	 * @returns Readonly reactive store
+	 */
+	asReadonly(
+		frozen?: boolean,
+	): typeof frozen extends true ? ReadonlyFrozenSignal<Store> : ReadonlySignal<Store>;
+
+	/**
+	 * Get the value
+	 *
+	 * @returns Current value
+	 */
+	get(): Store;
+
+	/**
+	 * 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 extends keyof Store>(key: Key): Store[Key];
+
+	/**
+	 * 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;
+
+	/**
+	 * 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;
+
+	/**
+	 * Get the value _(without reactivity)_
+	 *
+	 * @param copy Copy the store? _(defaults to `false`)_
+	 * @returns Current value
+	 */
+	peek(copy?: boolean): Store;
+
+	/**
+	 * Get a value by key _(without reactivity)_
+	 *
+	 * @param key Key of the value to get
+	 * @param copy If the value is an array or record, should it be copied? _(defaults to `false`)_
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
+	 */
+	peek<Key extends keyof Store>(key: Key, copy?: boolean): Store[Key];
+
+	/**
+	 * Get a value by key _(without reactivity)_
+	 *
+	 * @param key Key of the value to get
+	 * @param copy If the value is an array or record, should it be copied? _(defaults to `false`)_
+	 * @returns Value for the specified key, or `undefined` if it doesn't exist
+	 */
+	peek(key: Key, copy?: boolean): unknown;
+
+	/**
+	 * Set the value
+	 *
+	 * @param value New value _(defaults to an empty object)_
+	 */
+	set(
+		value?:
+			| Store
+			| (() => null | undefined | Store | Promise<null | undefined | Store>)
+			| Promise<null | undefined | Store>,
+	): void;
+
+	/**
+	 * Set a value by key
+	 *
+	 * @param key Key of the value to set
+	 * @param value New value
+	 */
+	set<Key extends keyof Store>(
+		key: Key,
+		value: Store[Key] | (() => Store[Key] | Promise<Store[Key]>) | Promise<Store[Key]>,
+	): void;
+
+	/**
+	 * Set a value by key
+	 *
+	 * @param key Key of the value to set
+	 * @param value New value
+	 */
+	set(key: Key, value: unknown): void;
+
+	/**
+	 * Subscribe to changes
+	 *
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
+	 */
+	subscribe(callback: (value: Store) => 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 Store>(
+		key: Key,
+		callback: (value: Store[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;
+
+	/**
+	 * Unsubscribe from changes for a specific key
+	 *
+	 * @param key Key of the value to unsubscribe from
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe<Key extends keyof Store>(
+		key: Key,
+		callback: (value: Store[Key] | undefined) => void,
+	): void;
+
+	/**
+	 * Unsubscribe from changes for a specific key
+	 *
+	 * @param key Key of the value to unsubscribe from
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe(key: Key, callback: (value: unknown | undefined) => void): void;
+
+	/**
+	 * Unsubscribe from changes
+	 *
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe(callback: (value: Store) => void): void;
+
+	/**
+	 * Update the value _(based on the current value)_
+	 *
+	 * @param callback Callback to update the value
+	 */
+	update(callback: (value: Store) => Store): void;
+} & Reactive<Store>;
+
+export type ReadonlyInstances<Value> = {
+	frozen?: ReadonlyFrozenSignal<Value>;
+	original?: ReadonlySignal<Value>;
+};
+
+export type ReadonlyFrozenSignal<Value> = ReadonlySignal<ReadonlySignalValue<Value>>;
+
+export type ReadonlySignal<Value> = {
+	/**
+	 * Is the signal frozen?
+	 */
+	get frozen(): boolean;
+} & Reactive<Value> &
+	SimpleReactive<Value>;
+
+export type ReadonlySignalValue<Value> = Value extends unknown[]
+	? Readonly<Value>
+	: Value extends PlainObject
+		? Readonly<Value>
+		: Value;
+
 export type SetValueInProxyParameters<Value, Equal> = {
 	target: Value;
 	property: PropertyKey;
@@ -62,6 +492,79 @@ export type SetValueInProxyParameters<Value, Equal> = {
 	length?: Signal<number>;
 };
 
+export type Signal<Value> = {
+	/**
+	 * Get a readonly version of the signal
+	 *
+	 * @param frozen Freeze the signal? _(defaults to `false`)_
+	 * @returns Readonly signal
+	 */
+	asReadonly(frozen: true): ReadonlyFrozenSignal<Value>;
+
+	/**
+	 * Get a readonly version of the signal
+	 *
+	 * @param frozen Freeze the signal? _(defaults to `false`)_
+	 * @returns Readonly signal
+	 */
+	asReadonly(
+		frozen?: boolean,
+	): typeof frozen extends true ? ReadonlyFrozenSignal<Value> : ReadonlySignal<Value>;
+
+	/**
+	 * Set the value
+	 *
+	 * @param value New value
+	 */
+	set(value: Value | (() => Value | Promise<Value>) | Promise<Value>): void;
+
+	/**
+	 * Update the value _(based on the current value)_
+	 *
+	 * @param callback Callback to update the value
+	 */
+	update(callback: (value: Value) => Value): void;
+} & Reactive<Value> &
+	SimpleReactive<Value>;
+
+type SimpleReactive<Value> = {
+	/**
+	 * Get the value
+	 *
+	 * @returns Current value
+	 */
+	get(): Value;
+
+	/**
+	 * Get the value _(without reactivity)_
+	 *
+	 * @returns Current value
+	 */
+	peek(): Value;
+
+	/**
+	 * Subscribe to changes
+	 *
+	 * @param callback Callback for changes
+	 * @returns Unsubscribe callback
+	 */
+	subscribe(callback: (value: Value) => void): Unsubscribe;
+
+	/**
+	 * Unsubscribe from changes
+	 *
+	 * @param callback Callback to unsubscribe
+	 */
+	unsubscribe(callback: (value: Value) => void): void;
+};
+
+export type Subscription = {
+	callback: GenericCallback;
+	state: ReactiveState<unknown, never>;
+
+	destroy(): void;
+};
+
 /**
  * Unsubscribe from changes
  */

package/src/subscription.ts

@@ -1,22 +1,4 @@
-import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import type {ReactiveState, Unsubscribe} from './models';
-
-export class Subscription {
-	callback: GenericCallback;
-	state: ReactiveState<unknown, never>;
-
-	constructor(state: ReactiveState<unknown, never>, callback: GenericCallback) {
-		this.state = state;
-		this.callback = callback;
-
-		callback(state.value);
-	}
-
-	destroy(): void {
-		this.callback = noop;
-		this.state = undefined as never;
-	}
-}
+import type {ReactiveState, Subscription, Unsubscribe} from './models';
 
 export function noop(): void {}
 
@@ -28,13 +10,31 @@ export function subscribe<Value>(
 		return noop;
 	}
 
-	state.subscriptions.set(callback, new Subscription(state, callback));
+	state.subscriptions.set(callback, subscription(state, callback));
 
 	return () => {
 		unsubscribe(state, callback);
 	};
 }
 
+function subscription<Value>(
+	state: ReactiveState<Value, never>,
+	callback: (value: Value) => void,
+): Subscription {
+	const instance: Subscription = {
+		callback,
+		state,
+		destroy: () => {
+			instance.callback = noop;
+			instance.state = undefined as never;
+		},
+	};
+
+	callback(state.value);
+
+	return instance;
+}
+
 export function unsubscribe<Value>(
 	state: ReactiveState<Value, never>,
 	callback: (value: Value) => void,