@expressive/mvc 0.32.0 → 0.34.0

package/lib/index.d.ts

@@ -1,4 +1,7 @@
-type Async<T = any> = (...args: any[]) => Promise<T>;
+type Async<T = any, Y extends any[] = any> = {
+    (...args: Y): Promise<T>;
+    active: boolean;
+};
 /**
  * Sets an exotic method with managed ready-state. Property accepts an async function.
  *
@@ -9,40 +12,7 @@ type Async<T = any> = (...args: any[]) => Promise<T>;
  *
  * @param action - Action to fire when resulting property is invoked.
  */
-declare function run(action: Async): typeof action & {
-    active: boolean;
-};
-declare function run<S>(action: Async<S>): typeof action & {
-    active: boolean;
-};
-
-/** Type may not be undefined - instead will be null.  */
-type NoVoid<T> = T extends undefined | void ? null : T;
-type ForceUpdate = {
-    /** Force an update in current component. */
-    (): void;
-    /**
-     * Force an update and again after promise either resolves or rejects.
-     * Will return a duplicate of given Promise, which resolves after refresh.
-     */
-    <T = void>(passthru: Promise<T>): Promise<T>;
-    /**
-     * Force a update while calling async function.
-     * A refresh will occur both before and after given function.
-     * Any actions performed before first `await` will occur before refresh!
-     */
-    <T = void>(invoke: () => Promise<T>): Promise<T>;
-};
-type Factory<T extends Model, R> = (this: T, current: T, update: ForceUpdate) => R;
-/** Fetch instance of this class from context. */
-declare function get$1<T extends Model>(this: Model.Type<T>, ignoreUpdates?: true): Model.Focus<T>;
-/** Fetch instance of this class optionally. May be undefined, but will never subscribe. */
-declare function get$1<T extends Model>(this: Model.Type<T>, required: boolean): Model.Focus<T> | undefined;
-declare function get$1<T extends Model, R>(this: Model.Type<T>, factory: Factory<T, (() => R) | R | Promise<R>>): NoVoid<R>;
-declare function get$1<T extends Model, R>(this: Model.Type<T>, factory: Factory<T, (() => R) | null>): NoVoid<R> | null;
-
-declare function use$1<T extends Model>(this: Model.New<T>, callback?: (instance: T) => void, repeat?: boolean): Model.Focus<T>;
-declare function use$1<T extends Model>(this: Model.New<T>, apply?: Model.Values<T>, repeat?: boolean): Model.Focus<T>;
+declare function run<T, Y extends any[]>(action: (...args: Y) => T | Promise<T>): Async<T, Y>;
 
 type Callback = () => void;
 
@@ -53,43 +23,25 @@ declare global {
       toUpdate(): Promise<R>;
 
       /** Assert model did update with keys specified. */
-      toHaveUpdated<R>(keys: string[]): Promise<R>; 
+      toHaveUpdated<R>(...keys: string[]): Promise<R>; 
     }
   }
 }
 
-type SelectOne<T, K extends Model.Key<T>> = K;
-type SelectFew<T, K extends Model.Key<T>> = K[];
-type Select<T, K extends Model.Key<T> = Model.Key<T>> = K | K[];
-type Export<T, S> = S extends SelectOne<T, infer P> ? T[P] : S extends SelectFew<T, infer P> ? Model.Export<T, P> : never;
-type OnUpdate<T, S> = (this: T, value: Export<T, S>, updated: Model.Event<T>[]) => void;
-interface Observable {
-    get(): Model.Export<this>;
-    get<P extends Select<this>>(select: P): Export<this, P>;
-    get<P extends Select<this>>(select: P, onUpdate: OnUpdate<this, P>, once?: true): Callback;
-    get<P extends Select<this>>(select: P, onUpdate: OnUpdate<this, P>, initial?: false): Callback;
-    get(effect: Model.Effect<this>): Callback;
-    set(): Promise<Model.Event<this>[]>;
-    set(timeout: number): Promise<Model.Event<this>[] | false>;
-    set<T extends Model.Values<this>>(from: T, only?: (keyof T)[]): Promise<Model.Event<T>[] | false>;
-    set<K extends Model.Key<this>>(key: K, value: Model.Value<this[K]>): Promise<Model.Event<this>[] | false>;
-    set<K extends Model.Event<this>>(key: K): Promise<Model.Event<this>[] | false>;
-}
-
 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. */
     type Type<T extends Model = Model> = abstract new (...args: any[]) => T;
     /** A typeof Model, specifically one which can be created without any arguments. */
     type New<T extends Model = Model> = (new () => T) & typeof Model;
-    /** A callback function which is subscribed to parent and updates when values change. */
-    type Effect<T> = (this: T, argument: T) => Callback | Promise<void> | void;
     /** Subset of `keyof T` which are not methods or defined by base Model U. **/
-    type Key<T, U = Observable> = Extract<Exclude<keyof T, keyof U>, string>;
-    /** Including but not limited to `keyof T` which are not methods or defined by base Model. */
-    type Event<T> = Key<T> | (string & {});
+    type Key<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]>;
@@ -98,32 +50,50 @@ declare namespace Model {
      * Values from current state of given controller.
      * Differs from `Values` as values here will drill into "real" values held by exotics like ref.
      */
-    type Export<T, K extends Key<T> = Key<T>> = {
-        [P in K]: Value<T[P]>;
-    };
-    /**
-     * Reference to `this` without a subscription.
-     * Use to obtain full reference from a destructure.
-     */
-    type Focus<T> = T & {
-        is: T;
+    type Export<T> = {
+        [P in keyof T]: Value<T[P]>;
     };
-    /** Exotic value, actual value is contained. */
+    /** Exotic value, where actual value is contained within. */
     type Ref<T = any> = {
         (next: T): void;
         current: T | null;
     };
-    /** Actual value stored in state. */
-    type Value<R> = R extends Ref<infer T> ? T : R extends Observable ? Export<R> : R;
-}
-interface Model extends Observable {
+    /** 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 Event = (key: string) => Callback | void;
 }
 declare class Model {
+    is: this;
     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. */
+    get(effect: Model.Effect<this>): Callback;
+    /** Assert update is in progress. Returns a promise which resolves updated keys. */
+    set(): Promise<Model.Values<this> | false>;
+    /**
+     * Expect an update to state within timeout.
+     *
+     * @param timeout - milliseconds to wait for update
+     * @param predicate - optional function to filter updates. If returns true, update is accepted.
+     *
+     * @returns a promise which resolves full update.
+     */
+    set(timeout: number, predicate?: Predicate): Promise<Model.Values<this>>;
+    /**
+     * Call a function when 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.
+     *   To run logic on final value only, this callback may return a function.
+     *   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
+    */
+    set(callback: Model.Event): Callback;
     /** Mark this instance for garbage collection. */
     null(): void;
-    static get: typeof get$1;
-    static use: typeof use$1;
     /**
      * Creates a new instance of this controller.
      *
@@ -131,19 +101,38 @@ declare class Model {
      *
      * @param args - arguments sent to constructor
      */
-    static new<T extends new (...args: any[]) => any>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
+    static new<T extends Class>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
     /**
      * Static equivalent of `x instanceof this`.
-     *
-     * Will determine if provided class is a subtype of this one.
+     * Determines if provided class is a subtype of this one.
+     * If so, language server will make available all static
+     * methods and properties of this class.
      */
     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 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> = (callback: (x: T) => void) => void;
+    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.
@@ -151,11 +140,25 @@ declare namespace get {
  * will be made available to child upon this request.
  *
  * @param Type - Type of controller compatible with this class.
- * @param required - Throw if controller is created independantly.
+ * @param required - If true, will throw if Model is created without a parent.
  */
 declare function get<T extends Model>(Type: Model.Type<T>, required?: true): T;
+/**
+ * Fetches and assigns the controller which spawned this host.
+ * When parent assigns an instance via `use()` directive, it
+ * will be made available to child upon this request.
+ *
+ * @param Type - Type of controller compatible with this class.
+ * @param required - If false, property may be undefined. Otherwise will throw suspense.
+ */
 declare function get<T extends Model>(Type: Model.Type<T>, required: boolean): T | undefined;
-declare function get<R, T extends Model>(Type: Model.Type<T>, compute: (this: T, on: T) => R): Exclude<R, undefined>;
+/**
+ * Implement a computed value from a foreign model. Output will be generated by provided function,
+ * where the foreign model will be passed to that function.
+ *
+ * @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: (this: T, on: T) => R): R;
 /**
  * Implement a computed value; output will be generated by provided function.
@@ -163,14 +166,12 @@ declare function get<R, T extends Model>(Type: Model.Type<T>, compute: (this: T,
  * @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: (this: T, on: T) => R): Exclude<R, undefined>;
 declare function get<R, T extends Model>(source: T, compute: (this: T, on: T) => R): R;
 /**
  * Implement a computed value; output is returned by function from provided factory.
  *
  * @param compute - Factory function to generate a getter to subscribe dependancies.
  */
-declare function get<R, T>(compute: (property: string, on: T) => (this: T, state: T) => R): Exclude<R, undefined>;
 declare function get<R, T>(compute: (property: string, on: T) => (this: T, state: T) => R): R;
 
 declare namespace ref {
@@ -226,7 +227,7 @@ declare function ref<T = HTMLElement>(callback?: ref.Callback<T>): ref.Object<T>
 declare function ref<T = HTMLElement>(callback: ref.Callback<T | null>, ignoreNull: boolean): ref.Object<T>;
 
 declare namespace set {
-    type Callback<T, S = any> = (this: S, argument: T) => ((next: T) => void) | Promise<any> | void | boolean;
+    type Callback<T, S = any> = (this: S, next: T, previous: T) => ((next: T) => void) | Promise<any> | void | boolean;
     type Factory<T, S = any> = (this: S, key: string, thisArg: S) => Promise<T> | T;
 }
 /**
@@ -239,29 +240,30 @@ declare function set<T = any>(): T;
 /**
  * Set property with a factory function.
  *
- * If async, poperty cannot be accessed until resolves, yeilding a result.
- * If accessed while still processing, React Suspense will be thrown.
+ * Run factory only if/when accessed. Value will be undefined until
+ * factory resolves, which will also dispatch an update for the property.
+ */
+declare function set<T>(factory: set.Factory<T> | Promise<T>, required: false): T | undefined;
+/**
+ * Set property with a factory function.
  *
- * - `required: true` (default) -
- *      Run factory immediately upon creation of model instance.
- * - `required: false` -
- *      Run factory only if/when accessed.
- *      Value will always throw suspense at least once - use with caution.
+ * If async, property cannot be accessed until resolves, yeilding a result.
+ * If accessed while still processing, React Suspense will be thrown.
  *
  * @param factory - Callback run to derrive property value.
- * @param required - (default: true) Run factory immediately on creation, otherwise on access.
+ * @param required - If true run factory immediately on creation, otherwise on access.
  */
-declare function set<T>(factory: set.Factory<T> | Promise<T>, required: false): T | undefined;
 declare function set<T>(factory: set.Factory<T> | Promise<T>, required?: boolean): T;
-declare function set<T>(value: undefined, onUpdate: set.Callback<T>): T;
-declare function set<T>(value: T, onUpdate: set.Callback<T>): T;
+/**
+ * Set a property with empty placeholder and update callback.
+ *
+ * @param value - Starting value for property. If undefined, suspense will be thrown on access, until value is set and accepted by callback.
+ * @param onUpdate - Callback run when property is set. If returns false, update is not accepted and property will keep previous value.
+ */
+declare function set<T>(value: T | undefined, onUpdate: set.Callback<T>): T;
 
-type Empty = Record<string, never>;
 declare namespace use {
-    type Record<T> = {
-        [key: string | number]: T;
-    } & Observable;
-    type Object<T extends {}> = T & Observable;
+    type Object<T extends {}> = T;
 }
 /** Create a placeholder for specified Model type. */
 declare function use<T extends Model>(): T | undefined;
@@ -276,29 +278,9 @@ declare function use<T extends Model>(Type: Model.New<T>, ready?: (i: T) => void
  * already active.
  **/
 declare function use<T extends Model>(model: T, ready?: (i: T) => void): T;
-/** Create a managed record with observable entries. */
-declare function use<T = any, C = use.Record<T>>(record: Empty, ready?: (object: C) => void): C;
 /** 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 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;
-}
-
-type Observer<T extends Model = any> = (key: Model.Event<T> | null | undefined, source: Control) => Callback | null | void;
 declare namespace Control {
     /**
      * Property initializer, will run upon instance creation.
@@ -306,7 +288,7 @@ declare namespace Control {
      */
     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) => boolean | void;
+    type Setter<T> = (value: T, previous: T) => boolean | void;
     type PropertyDescriptor<T = any> = {
         get?: Getter<T>;
         set?: Setter<T> | false;
@@ -319,55 +301,35 @@ declare namespace Control {
      * Returned callback is forwarded.
      */
     type OnReady<T extends {}> = (control: Control<T>) => (() => void) | void;
-    type RequestRefresh = (update: (tick: number) => number) => void;
-    type GetContext = (target: Model) => (callback: (got: Context) => void) => void;
-    type GetAdapter<T> = (refresh: RequestRefresh, context: Context) => {
-        mount: () => (() => void) | void;
-        render: () => T;
-    } | void;
-    type GetHook = <T>(adapter: GetAdapter<T>) => T | null;
-    type UseAdapter<T extends Model, R> = (refresh: RequestRefresh) => {
-        instance: T;
-        mount: () => (() => void) | void;
-        render: R;
-    };
-    type UseHook = <T extends Model, R>(adapter: UseAdapter<T, R>) => R;
+    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 ready: Set<Control.Callback>;
-    static after: Set<Callback>;
-    static before: Set<Callback>;
-    static pending: Set<Callback>;
-    static get: Control.GetHook;
-    static use: Control.UseHook;
-    static has: Control.GetContext;
-    static for: typeof control;
-    static apply: typeof apply;
     static watch: typeof watch;
-    id: string | number | false;
+    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: {
-        [key: string]: any;
+        [property: string]: unknown;
+    };
+    frame: {
+        [property: string]: unknown;
     };
-    latest?: Model.Event<T>[];
-    frame: Set<string>;
-    followers: Set<Observer<any>>;
-    observers: Map<string, Set<Observer<any>>>;
-    constructor(subject: T, id: string | number | false);
-    add(key: string): void;
+    listeners: Map<Control.OnUpdate, Set<string> | undefined>;
+    constructor(subject: T, id?: string | number | false);
     watch(key: string, output: Control.PropertyDescriptor<any>): void;
-    ref<K extends Model.Key<T>>(key: K, callback?: (this: T, value: T[K]) => boolean | void): (value: any) => void;
-    update(key: string): void;
-    addListener(fn: Observer): () => boolean;
+    update(key: string, value?: unknown): void;
+    fetch(key: string, required?: boolean): () => unknown;
+    addListener<T extends Model>(fn: Control.OnUpdate<T>): () => boolean;
     clear(): 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>;
-type Focus<T extends {}> = T & {
-    is: T;
-};
-declare function watch<T extends {}>(value: T, cb: Observer): Focus<T>;
-declare function apply<T = any>(instruction: Control.Instruction<T>): 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";
@@ -401,7 +363,7 @@ type Debug<T extends Model = Model> = T & {
      * 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]?: readonly Model.Event<T>[];
+    [UPDATE]?: Model.Values<T>;
     /**
      * Parent currently assigned to parent. Usually the model which this one is a property of.
      */