@oscarpalmer/mora 0.29.0 → 0.31.0

package/dist/models.d.mts

@@ -1,32 +1,229 @@
-import { Effect } from "./effect.mjs";
-import { Subscription } from "./subscription.mjs";
-import { Computed } from "./value/computed.mjs";
-import { Signal } from "./value/signal.mjs";
-import { GenericCallback, Key } from "@oscarpalmer/atoms/models";
-
+import { PROPERTY_LENGTH } from "./constants.mjs";
+import { GenericCallback, Key, PlainObject } from "@oscarpalmer/atoms/models";
 //#region src/models.d.ts
 type Active = {
-  computed?: Computed<unknown>;
-  effect?: Effect;
+  computed?: ComputedEffect;
+  effect?: EffectState;
 };
 type Batch = {
   depth: number;
-  handlers: Set<Effect | Subscription>;
+  flushing: boolean;
+  handlers: Set<EffectState | Subscription>;
 };
+type Computed<Value> = Reactive<Value> & SimpleReactive<Value>;
 type ComputedEffect = {
   dirty: boolean;
-  instance: Effect;
+  instance: EffectState;
 };
+type Effect = {};
 type EffectState = {
   callback: GenericCallback;
 };
-type InternalComputed = {
-  readonly effect: ComputedEffect;
-  readonly state: ReactiveState<unknown, unknown>;
-};
-type InternalEffect = {
-  state: EffectState;
+type Reactive<Value> = {
+  /**
+   * JSON representation of the value
+   *
+   * @returns JSON value
+   */
+  toJSON(): Value;
+  /**
+   * String representation of the value
+   *
+   * @returns Value as string
+   */
+  toString(): string;
 };
+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[]>;
 type ReactiveOptions<Value> = {
   /**
    * Method for comparing values for equality
@@ -38,14 +235,161 @@ type ReactiveOptions<Value> = {
   equal?: (first: Value, second: Value) => boolean;
 };
 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>>;
   subscriptions: Map<GenericCallback, Subscription>;
   value: Value;
 };
+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>;
+type ReadonlyInstances<Value> = {
+  frozen?: ReadonlyFrozenSignal<Value>;
+  original?: ReadonlySignal<Value>;
+};
+type ReadonlyFrozenSignal<Value> = ReadonlySignal<ReadonlySignalValue<Value>>;
+type ReadonlySignal<Value> = {
+  /**
+   * Is the signal frozen?
+   */
+  get frozen(): boolean;
+} & Reactive<Value> & SimpleReactive<Value>;
+type ReadonlySignalValue<Value> = Value extends unknown[] ? Readonly<Value> : Value extends PlainObject ? Readonly<Value> : Value;
 type SetValueInProxyParameters<Value, Equal> = {
   target: Value;
   property: PropertyKey;
@@ -54,9 +398,69 @@ type SetValueInProxyParameters<Value, Equal> = {
   isArray: boolean;
   length?: Signal<number>;
 };
+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;
+};
+type Subscription = {
+  callback: GenericCallback;
+  state: ReactiveState<unknown, never>;
+  destroy(): void;
+};
 /**
  * Unsubscribe from changes
  */
 type Unsubscribe = () => void;
 //#endregion
-export { Active, Batch, ComputedEffect, EffectState, InternalComputed, InternalEffect, ReactiveOptions, ReactiveState, SetValueInProxyParameters, Unsubscribe };
+export { Active, Batch, Computed, ComputedEffect, Effect, EffectState, Reactive, ReactiveArray, ReactiveOptions, ReactiveState, ReactiveStore, ReadonlyFrozenSignal, ReadonlyInstances, ReadonlySignal, ReadonlySignalValue, SetValueInProxyParameters, Signal, Subscription, Unsubscribe };