@expressive/mvc 0.52.1 → 0.53.0

package/dist/index.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Update callback function.
+ *
+ * @param key -
+ *   - `string` - property which has updated.
+ *   - `false` - a normal update has completed.
+ *   - `true` - initial event; instance is ready.
+ *   - `null` - terminal event; instance is expired.
+ * @param source - Instance of Model for which update has occured.
+ */
+type OnUpdate<T extends Model = any> = (this: T, key: unknown, source: T) => (() => void) | null | void;
+type OnAccess<T extends Model = any, R = unknown> = (from: T, key: string | number, value: R) => unknown;
+type Effect<T extends Model> = (this: T, proxy: T) => ((update: boolean | null) => void) | Promise<void> | null | void;
+type Event = number | string | null | boolean | symbol;
+declare function addListener<T extends Model>(subject: T, callback: OnUpdate<T>, select?: Event): () => boolean;
+declare function createProxy<T extends Model>(from: T, observer: OnAccess<T>): T;
+/**
+ * Create a side-effect which will update whenever values accessed change.
+ * Callback is called immediately and if ever values are stale.
+ *
+ * @param target - Instance of Model to observe.
+ * @param callback - Function to invoke when values change.
+ * @param requireValues - If `true` will throw if accessing a value which is `undefined`.
+ */
+declare function createEffect<T extends Model>(target: T, callback: Effect<Required<T>>, requireValues: true): () => void;
+declare function createEffect<T extends Model>(target: T, callback: Effect<T>, requireValues?: boolean): () => void;
+
 declare namespace Model {
     /** Any type of Model, using own class constructor as its identifier. */
     type Type<T extends Model = Model> = (abstract new (...args: any[]) => T) & typeof Model;
@@ -27,7 +54,7 @@ declare namespace Model {
     /** Value for a property managed by a model. */
     type Value<T extends Model, K extends Event<T>> = K extends keyof T ? Export<T[K]> : unknown;
     type OnEvent<T extends Model> = (this: T, key: unknown, source: T) => (() => void) | void | null;
-    type OnUpdate<T extends Model, K extends Event<T>> = (this: T, value: Value<T, K>, key: K, thisArg: K) => void;
+    type OnUpdate<T extends Model, K extends Event<T>> = (this: T, key: K, thisArg: K) => void;
     /**
      * Values from current state of given model.
      * Differs from `Values` as values here will drill
@@ -133,29 +160,18 @@ declare abstract class Model {
     /**
      * Get update in progress.
      *
-     * @returns Promise which resolves object with updated values. Is `undefined` if there is no update.
+     * @returns Promise which resolves object with updated values, `undefined` if there no update is pending.
      **/
     set(): PromiseLike<Model.Event<this>[]> | undefined;
     /**
-     * Call a function when update occurs.
-     *
-     * Given function is called for every assignment (which changes value) or explicit `set`.
-     *
-     * To run logic on final value only, callback may return a function. Using the same
-     * function for one or more events will ensure it is called only when events are settled.
-     *
-     * @param callback - Function to call when update occurs.
-     * @returns Function to remove listener. Will return `true` if removed, `false` if inactive already.
-     *
-    */
-    set(callback: Model.OnEvent<this>): () => boolean;
-    /**
-     * Declare an end to updates. This event is final and will freeze state.
-     * This event can be watched for as well, to run cleanup logic and internally will remove all listeners.
+     * Update mulitple properties at once. Merges argument with current state.
+     * Properties which are not managed by this model will be ignored.
      *
-     * @param status - `null` to end updates.
+     * @param assign - Object with properties to update.
+     * @param silent - If an update does occur, listeners will not be refreshed automatically.
+     * @returns Promise resolving an array of keys updated, `undefined` (immediately) if a noop.
      */
-    set(status: null): void;
+    set(assign: Model.Assign<this>, silent?: boolean): PromiseLike<Model.Event<this>[]> | undefined;
     /**
      * Push an update. This will not change the value of associated property.
      *
@@ -172,25 +188,28 @@ declare abstract class Model {
      */
     set(key: Model.Event<this>): PromiseLike<Model.Event<this>[]>;
     /**
-     * Update mulitple properties at once. Merges argument with current state.
-     * Properties which are not managed by this model will be ignored.
+     * Call a function when update occurs.
      *
-     * @param assign - Object with properties to update.
-     * @returns Promise resolving an array of keys updated, `undefined` (immediately) if a noop.
-     */
-    set(assign: Model.Assign<this>): PromiseLike<Model.Event<this>[]> | undefined;
+     * Given function is called for every assignment (which changes value) or explicit `set`.
+     *
+     * To run logic on final value only, callback may return a function. Using the same
+     * function for one or more events will ensure it is called only when events are settled.
+     *
+     * @param callback - Function to call when update occurs.
+     * @returns Function to remove listener. Will return `true` if removed, `false` if inactive already.
+     *
+    */
+    set(callback: Model.OnEvent<this>): () => boolean;
     /**
-     * Update a property with value.
+     * Declare an end to updates. This event is final and will freeze state.
+     * This event can be watched for as well, to run cleanup logic and internally will remove all listeners.
      *
-     * @param key - property to update
-     * @param value - value to update property with (if the same as current, no update will occur)
-     * @param silent - if true, will not notify listeners of an update
-     * @returns Promise resolving an array of keys updated, `undefined` (immediately) if a noop.
+     * @param status - `null` to end updates.
      */
-    set<K extends string>(key: K, value: Model.Value<this, K>, silent?: boolean): PromiseLike<Model.Event<this>[]> | undefined;
+    set(status: null): void;
     /**
      * Iterate over managed properties in this instance of Model.
-     * Yeilds the key and underlying value for each property.
+     * Yeilds the key and current value for each property.
      */
     [Symbol.iterator](): Iterator<[string, unknown]>;
     /**
@@ -215,9 +234,10 @@ declare abstract class Model {
 }
 
 declare namespace get {
-    type Function<T, S = any> = (on: S, key: string) => T;
+    type Compute<T, S = any> = (on: S, key: string) => T;
     type Factory<T, S = any> = (this: S, key: string, thisArg: S) => T;
     type Source<T extends Model = Model> = (resolve: (x: T) => void) => void;
+    type Effect<T> = (model: T, key: string) => (() => void) | void;
 }
 /**
  * Fetches and assigns the controller which spawned this host.
@@ -244,14 +264,14 @@ declare function get<T extends Model>(Type: Model.Type<T>, required?: false): T
  * @param source - Type of Model to fetch for computation.
  * @param compute - Compute function. Will update automatically as input values change.
  */
-declare function get<R, T extends Model>(Type: Model.Type<T>, compute: get.Function<R, T>): R;
+declare function get<R, T extends Model>(Type: Model.Type<T>, effect: get.Effect<T>): R;
 /**
  * Implement a computed value; output will be generated by provided function.
  *
  * @param source - Source model from which computed value will be a subscriber.
  * @param compute - Compute function. Bound to a subscriber-proxy of source, returns output value. Will update automatically as input values change.
  */
-declare function get<R, T extends Model>(source: T, compute: get.Function<R, T>): R;
+declare function get<R, T extends Model>(source: T, compute: get.Compute<R, T>): R;
 /**
  * Implement a computed value; output is returned by function from provided factory.
  *
@@ -326,10 +346,10 @@ declare namespace set {
     type Factory<T, S = any> = (this: S, key: string) => Promise<T> | T;
 }
 /**
- * Set property with a placeholder.
+ * Set property as `undefined` but required.
  *
  * Property cannot be accessed until it is defined. If accessed while undefined, a hybrid
- * `Promise`/`Error` (ala: [Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)) will be thrown.
+ * `Promise`/`Error` (aka: [Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)) will be thrown.
  */
 declare function set<T = any>(): T;
 /**
@@ -367,20 +387,12 @@ declare namespace has {
 declare function has<T extends Model>(type: Model.Type<T>, callback?: has.Callback<T>): readonly T[];
 declare function has(callback?: has.Callback): readonly Model[];
 
-type Effect<T extends {}> = (this: T, argument: T) => ((update: boolean | null) => void) | Promise<void> | null | void;
-/**
- * Create a side-effect which will update whenever values accessed change.
- * Callback is called immediately and if ever values are stale.
- *
- * @param target - Instance of Model to observe.
- * @param callback - Function to invoke when values change.
- * @param requireValues - If `true` will throw if accessing a value which is `undefined`.
- */
-declare function effect<T extends {}>(target: T, callback: Effect<Required<T>>, requireValues: true): () => void;
-declare function effect<T extends {}>(target: T, callback: Effect<T>, requireValues?: boolean): () => void;
-
 declare namespace Context {
-    type Input = Record<string | number, Model | Model.Init>;
+    type Multiple<T extends Model> = {
+        [key: string | number]: Model.Init<T> | T;
+    };
+    type Accept<T extends Model = Model> = T | Model.Init<T> | Multiple<T>;
+    type ForEach = (added: Model, explicit: boolean) => void;
     type Expect = (model: Model) => (() => void) | void;
 }
 interface Context {
@@ -392,13 +404,15 @@ declare class Context {
     id: string;
     protected layer: Map<string | number, Model | Model.Type<Model>>;
     protected cleanup: Set<() => void>;
-    constructor(inputs?: Context.Input);
+    constructor(inputs?: Context.Accept);
+    /** Run callback when a specified type is registered to a **child** context. */
+    has<T extends Model>(Type: Model.Type<T>, callback: (model: T) => void): void;
+    /** Find specified type registered to a parent context. Returns undefined if none are found. */
     get<T extends Model>(Type: Model.Type<T>): T | undefined;
-    get<T extends Model>(Type: Model.Type<T>, callback: (model: T) => void): void;
-    push(inputs?: Context.Input): this;
+    push(inputs?: Context.Accept): this;
     pop(): void;
-    include(inputs: Context.Input, forEach?: (added: Model, explicit: boolean) => void): void;
+    include<T extends Model>(inputs: Context.Accept<T>, forEach?: Context.ForEach | Model.Assign<T>): void;
     protected add<T extends Model>(input: T | Model.Init<T>, implicit?: boolean): T;
 }
 
-export { Context, Model, Model as default, effect, get, has, ref, set, use };
+export { Context, Model, addListener, createEffect, createProxy, Model as default, get, has, ref, set, use };