@expressive/mvc 0.34.0 → 0.35.0-alpha.0

package/{lib → dist}/index.d.ts

@@ -14,44 +14,29 @@ type Async<T = any, Y extends any[] = any> = {
  */
 declare function run<T, Y extends any[]>(action: (...args: Y) => T | Promise<T>): Async<T, Y>;
 
-type Callback = () => void;
-
-declare global {
-  namespace jest {
-    interface Matchers<R> {
-      /** Assert model does have one or more updates pending. */
-      toUpdate(): Promise<R>;
-
-      /** Assert model did update with keys specified. */
-      toHaveUpdated<R>(...keys: string[]): Promise<R>; 
-    }
-  }
-}
-
-type InstanceOf<T> = T extends {
-    prototype: infer U;
-} ? U : never;
-type Class = new (...args: any[]) => any;
 type Predicate = (key: string) => boolean | void;
 declare namespace Model {
-    /** Any typeof Model, using class constructor as the reference. */
+    /** Any type of Model, using own class constructor as its identifier. */
     type Type<T extends Model = Model> = abstract new (...args: any[]) => T;
-    /** A typeof Model, specifically one which can be created without any arguments. */
+    /** A type of Model which may be created without constructor arguments. */
     type New<T extends Model = Model> = (new () => T) & typeof Model;
     /** Subset of `keyof T` which are not methods or defined by base Model U. **/
     type Key<T> = Exclude<keyof T, keyof Model> & string;
+    type Any<T> = Exclude<keyof T, keyof Model> | (string & {});
     /** Actual value stored in state. */
     type Value<R> = R extends Ref<infer T> ? T : R extends Model ? Export<R> : R;
-    /** Object comperable to data found in T. */
-    type Values<T> = {
-        [P in Key<T>]?: Value<T[P]>;
-    };
+    type ValueOf<T extends Model, K extends Any<T>> = K extends keyof T ? T[K] extends Ref<infer V> ? V : T[K] : unknown;
     /**
      * Values from current state of given controller.
-     * Differs from `Values` as values here will drill into "real" values held by exotics like ref.
+     * Differs from `Values` as values here will drill
+     * into "real" values held by exotics like ref.
      */
     type Export<T> = {
-        [P in keyof T]: Value<T[P]>;
+        [P in Key<T>]: Value<T[P]>;
+    };
+    /** Object comperable to data found in T. */
+    type Values<T> = {
+        [P in Key<T>]?: Value<T[P]>;
     };
     /** Exotic value, where actual value is contained within. */
     type Ref<T = any> = {
@@ -59,29 +44,55 @@ declare namespace Model {
         current: T | null;
     };
     /** A callback function which is subscribed to parent and updates when values change. */
-    type Effect<T> = (this: T, argument: T) => Callback | Promise<void> | void;
+    type Effect<T> = (this: T, argument: T) => Callback | Promise<void> | null | void;
     type Event = (key: string) => Callback | void;
+    namespace Instruction {
+        type Getter<T> = (source: Model) => T;
+        type Setter<T> = (value: T, previous: T) => boolean | void | (() => T);
+        type Descriptor<T = any> = {
+            get?: Getter<T> | boolean;
+            set?: Setter<T> | false;
+            enumerable?: boolean;
+            value?: T;
+        };
+    }
+    /**
+     * Property initializer, will run upon instance creation.
+     * Optional returned callback will run when once upon first access.
+     */
+    type Instruction<T = any, M extends Model = any> = (this: M, key: Model.Key<M>, thisArg: M, state: Model.Export<M>) => Instruction.Descriptor<T> | Instruction.Getter<T> | void;
 }
-declare class Model {
+interface Model {
+    /**
+     * Loopback to instance of this model. This is useful when in a subscribed context,
+     * to keep write access to `this` after a destructure. You can use it to read variables silently as well.
+     **/
     is: this;
+}
+declare class Model {
     constructor(id?: string | number);
     /** Pull current values from state. Flattens all models and exotic values amongst properties. */
     get(): Model.Export<this>;
-    /** Run a function which will automatically run again when accessed properties change. */
+    /** Run a function which will run automatically when accessed values change. */
     get(effect: Model.Effect<this>): Callback;
-    /** Assert update is in progress. Returns a promise which resolves updated keys. */
+    get<T extends string>(key: T, required: true): Exclude<Model.ValueOf<this, T>, undefined>;
+    get<T extends string>(key: T, required?: boolean): Model.ValueOf<this, T>;
+    /**
+     * Check if update is in progress.
+     * Returns a promise which resolves updated keys. If no update, will resolve `false`.
+     **/
     set(): Promise<Model.Values<this> | false>;
     /**
-     * Expect an update to state within timeout.
+     * Expect an update to state within a set timeout.
      *
      * @param timeout - milliseconds to wait for update
-     * @param predicate - optional function to filter updates. If returns true, update is accepted.
+     * @param predicate - optional function to filter for specific updates. If returns true, update is accepted.
      *
-     * @returns a promise which resolves full update.
+     * @returns a promise to resolve when next accepted update has occured.
      */
     set(timeout: number, predicate?: Predicate): Promise<Model.Values<this>>;
     /**
-     * Call a function when an update to state has occured.
+     * Call a function whenever an update to state has occured.
      *
      * @param callback - Function to call when any update occurs.
      *   Note: This will be called for every assignment which changes the value.
@@ -89,11 +100,26 @@ declare class Model {
      *   Returning the same function for the same (or multiple for that matter)
      *   will ensure it is only called once.
      *
-     * @returns a function to remove listener
+     * @returns a function to remove listener. Will return true if listener did exist.
     */
-    set(callback: Model.Event): Callback;
-    /** Mark this instance for garbage collection. */
-    null(): void;
+    set(callback: Model.Event): () => boolean;
+    /**
+     * Push an update without changing the value of associated property.
+     *
+     * This is useful where a property value internally has changed, but the object remains the same.
+     * For example: an array which has pushed a new value, or change to nested properties.
+     */
+    set(key: string | null): void;
+    /**
+     * Update a property programatically within state.
+     *
+     * @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
+     */
+    set<K extends string>(key: K, value?: Model.ValueOf<this, K>, silent?: boolean): void;
+    /** Iterate over managed properties in this instance of Model. */
+    [Symbol.iterator](): Iterator<[string, unknown]>;
     /**
      * Creates a new instance of this controller.
      *
@@ -101,7 +127,7 @@ declare class Model {
      *
      * @param args - arguments sent to constructor
      */
-    static new<T extends Class>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
+    static new<T extends typeof Model>(this: T, ...args: ConstructorParameters<T>): InstanceType<T>;
     /**
      * Static equivalent of `x instanceof this`.
      * Determines if provided class is a subtype of this one.
@@ -110,29 +136,12 @@ declare class Model {
      */
     static is<T extends Model.Type>(this: T, maybe: any): maybe is T;
 }
-
-declare namespace Context {
-    type Inputs = {
-        [key: string | number]: Model | Model.New;
-    };
-}
-declare class Context {
-    key: string;
-    private table;
-    private layer;
-    private has;
-    get<T extends Model>(Type: Model.Type<T>): T | undefined;
-    include(inputs: Context.Inputs): Map<Model, boolean>;
-    add<T extends Model>(input: T | Model.New<T>, implicit?: boolean): T;
-    push(): this;
-    pop(): void;
-}
+declare function add<T = any, M extends Model = any>(instruction: Model.Instruction): T;
 
 declare namespace get {
     type Function<T, S = any> = (this: S, on: S) => T;
     type Factory<R, T> = (this: T, property: string, on: T) => Function<R, T>;
     type Source<T extends Model = Model> = (resolve: (x: T) => void) => void;
-    function from(target: Model): (resolve: (got: Context) => void) => void;
 }
 /**
  * Fetches and assigns the controller which spawned this host.
@@ -281,93 +290,23 @@ declare function use<T extends Model>(model: T, ready?: (i: T) => void): T;
 /** Create a managed object with observable entries. */
 declare function use<T extends {}, O = use.Object<T>>(data: T, ready?: (object: O) => void): O;
 
-declare namespace Control {
-    /**
-     * Property initializer, will run upon instance creation.
-     * Optional returned callback will run when once upon first access.
-     */
-    type Instruction<T> = (this: Control, key: string, thisArg: Control) => PropertyDescriptor<T> | Getter<T> | void;
-    type Getter<T> = (source: Model) => T;
-    type Setter<T> = (value: T, previous: T) => boolean | void;
-    type PropertyDescriptor<T = any> = {
-        get?: Getter<T>;
-        set?: Setter<T> | false;
-        enumerable?: boolean;
-        value?: T;
+declare namespace Context {
+    type Inputs = {
+        [key: string | number]: Model | Model.New;
     };
-    type Callback = (control: Control) => void;
-    /**
-     * Callback for Controller.for() static method.
-     * Returned callback is forwarded.
-     */
-    type OnReady<T extends {}> = (control: Control<T>) => (() => void) | void;
-    type OnUpdate<T extends {} = any> = (key: Model.Key<T> | null | undefined, source: T) => (() => void) | null | void;
-    type OnChange = (this: {}, next: unknown, previous: unknown) => boolean | void;
 }
-declare class Control<T extends {} = any> {
-    static watch: typeof watch;
-    static for: typeof control;
-    static add: typeof add;
-    static on(event: "ready", callback: Control.Callback): Callback;
-    static on(event: "update" | "didUpdate", callback: Callback): Callback;
-    id: string;
-    subject: T;
-    state: {
-        [property: string]: unknown;
-    };
-    frame: {
-        [property: string]: unknown;
-    };
-    listeners: Map<Control.OnUpdate, Set<string> | undefined>;
-    constructor(subject: T, id?: string | number | false);
-    watch(key: string, output: Control.PropertyDescriptor<any>): void;
-    update(key: string, value?: unknown): void;
-    fetch(key: string, required?: boolean): () => unknown;
-    addListener<T extends Model>(fn: Control.OnUpdate<T>): () => boolean;
-    clear(): void;
+declare class Context {
+    static resolve(from: Model, callback: (context: Context) => void): void;
+    constructor(inputs?: Context.Inputs);
+    key: string;
+    private table;
+    private layer;
+    private has;
+    get<T extends Model>(Type: Model.Type<T>): T | undefined;
+    include(inputs: Context.Inputs): Map<Model, boolean>;
+    protected add<T extends Model>(input: T | Model.New<T>, implicit?: boolean): T;
+    push(): this;
+    pop(): void;
 }
-declare function control<T extends Model>(subject: T, ready: Control.OnReady<T>): Callback;
-declare function control<T extends Model>(subject: T, ready?: boolean): Control<T>;
-declare function watch<T extends {}>(value: T, argument: Control.OnUpdate): T;
-declare function add<T = any>(instruction: Control.Instruction<T>): T;
-
-declare const STATE = "__state";
-declare const UPDATE = "__update";
-declare const CONTROL = "__control";
-declare const PARENT = "__parent";
-declare const Debug: {
-    /** Use to access snapshot of Model's current state. */
-    STATE: "__state";
-    /**
-     * Use to access snapshot of Model's latest update.
-     */
-    UPDATE: "__update";
-    /** Use to access a Model's controller. */
-    CONTROL: "__control";
-    /** Use to access a Model's parent, if exists. */
-    PARENT: "__parent";
-};
-/**
- * Generic will declare debug properties on a given Model.
- *
- * These properties always exist at runtime, however are hidden unless you cast your Model as `Debug<T>`.
- */
-type Debug<T extends Model = Model> = T & {
-    /** Controller for this instance. */
-    [CONTROL]?: Control<T>;
-    /** Current state of this instance. */
-    [STATE]?: Model.Export<T>;
-    /**
-     * Last update causing a refresh to subscribers.
-     *
-     * If accessed directly, will contain all keys from last push.
-     * If within a subscribed function, will contain only keys which explicitly caused a refresh.
-     */
-    [UPDATE]?: Model.Values<T>;
-    /**
-     * Parent currently assigned to parent. Usually the model which this one is a property of.
-     */
-    [PARENT]?: Model;
-};
 
-export { Context, Control, Debug, Model, Model as default, get, ref, run, set, use };
+export { Context, Model, add, Model as default, get, ref, run, set, use };