@expressive/mvc 0.9.6 → 0.10.1

package/lib/index.d.ts

@@ -4,6 +4,9 @@ type Callback = () => void;
 type Class = new (...args: any[]) => any;
 type InstanceOf<T> = T extends { prototype: infer U } ? U : never;
 
+/** Type may not be undefined - instead will be null.  */
+type NoVoid<T> = T extends undefined ? null : T;
+
 declare type Listener = {
     commit(): void;
     release(): void;
@@ -22,7 +25,7 @@ declare class Subscriber<T extends {} = any> {
     dependant: Set<Listener>;
     watch: Map<any, boolean | (() => true | void)>;
     constructor(parent: Control<T>, onUpdate: Subscriber.OnEvent);
-    get using(): Model.Field<T>[];
+    get using(): Model.Key<T>[];
     assign(apply: Model.Compat<T>, keys?: any): void;
     add(key: any, value?: boolean | Callback): void;
     commit: () => () => void;
@@ -71,6 +74,7 @@ declare namespace Model {
     export type Methods<T> = {
         [K in keyof T]: T[K] extends Ref ? never : T[K] extends Function ? K : never;
     }[keyof T];
+    type BuiltIn = keyof Model | keyof Debug<{}>;
     /**
      * Subset of `keyof T` which are not methods or defined by base Model U.
      *
@@ -78,18 +82,18 @@ declare namespace Model {
      *
      * TODO: Should exclude methods
      **/
-    export type Field<T, E extends Model = Model> = Exclude<keyof T, keyof E | keyof Debug<{}>> & string;
+    export type Key<T> = Exclude<keyof T, BuiltIn> & string;
     /**
      * Including but not limited to `keyof T` which are not methods or defined by base Model.
      **/
-    export type Event<T, E extends Model = Model> = Extends<Field<T, E>>;
+    export type Event<T> = Extends<Key<T>>;
     /** Object containing managed entries found in T. */
-    export type Entries<T, E extends Model = Model> = {
-        [K in Field<T, E>]: T[K];
+    export type Entries<T> = {
+        [K in Key<T>]: T[K];
     };
     /** Object comperable to data found in T. */
-    export type Compat<T, E extends Model = Model> = {
-        [K in Field<T, E>]?: T[K];
+    export type Compat<T> = {
+        [K in Key<T>]?: T[K];
     };
     /** Actual value stored in state. */
     export type Value<R> = R extends Ref<infer T> ? T : R;
@@ -100,11 +104,11 @@ declare namespace Model {
      *
      * Differs from `Entries` as values here will drill into "real" values held by exotics like ref.
      */
-    export type Values<T, K extends Field<T> = Field<T>> = {
+    export type Get<T, K extends Key<T> = Key<T>> = {
         [P in K]: Value<T[P]>;
     };
     export type Export<T, E extends Model = Model> = {
-        [P in Field<T, E>]: Value<T[P]>;
+        [P in Key<T>]: Value<T[P]>;
     };
 }
 declare class Model {
@@ -115,11 +119,8 @@ declare class Model {
      */
     is: this;
     constructor();
-    on<P extends Model.Event<this>>(key: P, timeout?: number): Promise<Model.ValueOf<this, P>>;
-    on<P extends Model.Field<this>>(key: P, listener: (this: this, value: this[P], key: P) => void, once?: boolean): Callback;
-    on<P extends Model.Event<this>>(key: P, listener: (this: this, value: undefined, key: P) => void, once?: boolean): Callback;
-    on<P extends Model.Event<this>>(keys: P[], timeout?: number): Promise<P[]>;
-    on<P extends Model.Event<this>>(keys: P[], listener: (keys: P[]) => void, once?: boolean): Callback;
+    on<P extends Model.Event<this>>(keys?: P | Iterable<P>, timeout?: number): Promise<P[]>;
+    on<P extends Model.Event<this>>(keys: P | Iterable<P>, listener: (this: this, keys: Model.Event<this>[]) => void, once?: boolean): Callback;
     on(effect: Model.Effect<this>): Callback;
     on(effect: Model.Effect<this>, watch?: []): Callback;
     on(effect: Model.Effect<this>, watch?: Model.Event<this>[]): Callback;
@@ -127,17 +128,25 @@ declare class Model {
     on(current?: boolean): Promise<Model.Event<this>[] | null>;
     on(current: true): Promise<Model.Event<this>[]>;
     on(current: null): Promise<null>;
-    export(): Model.Export<this>;
-    export<P extends Model.Field<this>>(select: Iterable<P>): Model.Values<this, P>;
-    update(key: Model.Event<this>): PromiseLike<readonly Model.Event<this>[]>;
-    update(key: Model.Event<this>, callMethod: boolean): PromiseLike<readonly Model.Event<this>[]>;
-    update<T>(key: Model.Event<this>, argument: T): PromiseLike<readonly Model.Event<this>[]>;
-    update<T extends Model.Compat<this>>(source: T, select: (keyof T)[]): PromiseLike<(keyof T)[]>;
-    update<T extends Model.Compat<this>>(source: T, force?: boolean): PromiseLike<(keyof T)[]>;
+    get(): Model.Export<this>;
+    get<P extends Model.Key<this>>(property: P): this[P];
+    get<P extends Model.Key<this>>(property: P, timeout: number): Promise<this[P]>;
+    get<P extends Model.Key<this>>(property: P, onChange: true): Promise<this[P]>;
+    get<P extends Model.Key<this>>(property: P, onChange: boolean): this[P] | Promise<this[P]>;
+    get<P extends Model.Key<this>>(property: P, listener: (this: this, value: this[P], key: P[]) => void): Callback;
+    get<P extends Model.Key<this>>(select: Iterable<P>): Model.Get<this, P>;
+    get<P extends Model.Key<this>>(select: Iterable<P>, timeout: number): Promise<Model.Get<this, P>>;
+    get<P extends Model.Key<this>>(select: Iterable<P>, onChange: true): Promise<Model.Get<this, P>>;
+    get<P extends Model.Key<this>>(select: Iterable<P>, onChange: boolean): Model.Get<this, P> | Promise<Model.Get<this, P>>;
+    get<P extends Model.Key<this>>(select: Iterable<P>, listener: (this: this, value: Model.Get<this, P>, key: P[]) => void): Callback;
+    set(key: Model.Event<this>): PromiseLike<readonly Model.Event<this>[]>;
+    set<K extends Model.Event<this>>(key: Model.Event<this>, value: Model.ValueOf<this, K>): PromiseLike<readonly Model.Event<this>[]>;
+    set<T extends Model.Compat<this>>(source: T, select: (keyof T)[]): PromiseLike<(keyof T)[]>;
+    set<T extends Model.Compat<this>>(source: T, force?: boolean): PromiseLike<(keyof T)[]>;
     /**
      * Clean up side effects and mark this instance for garbage-collection.
      */
-    destroy(): void;
+    end(): void;
     /**
      * Creates a new instance of this controller.
      *
@@ -180,8 +189,8 @@ declare class Control<T extends {} = any> {
     subscribe(callback: Subscriber.OnEvent<T>): Model.Subscriber<T>;
     watch(key: keyof T & string): void;
     addListener(listener: Control.OnSync<T>): () => void;
-    ref<K extends Model.Field<T>>(key: K, handler?: (this: T, value: T[K]) => boolean | void): (value: any) => void;
-    update(key: Model.Field<T>): void;
+    ref<K extends Model.Key<T>>(key: K, handler?: (this: T, value: T[K]) => boolean | void): (value: any) => void;
+    update(key: Model.Key<T>): void;
     clear(): void;
     static get<T extends {}>(from: T): Control<T> | undefined;
     static for<T extends {}>(subject: T): Control<T>;
@@ -312,10 +321,10 @@ declare namespace ref {
     }
     /** Object with references to all managed values of `T`. */
     type Proxy<T extends Model> = {
-        [P in Model.Field<T>]-?: Model.Ref<T[P]>;
+        [P in Model.Key<T>]-?: Model.Ref<T[P]>;
     };
     type CustomProxy<T extends Model, R> = {
-        [P in Model.Field<T>]-?: R;
+        [P in Model.Key<T>]-?: R;
     };
 }
 /**
@@ -335,7 +344,7 @@ declare function ref<T extends Model>(target: T): ref.Proxy<T>;
  * @param target - Source model from which to reference values.
  * @param mapper - Function producing the placeholder value for any given property.
  */
-declare function ref<O extends Model, R>(target: O, mapper: (key: Model.Field<O>) => R): ref.CustomProxy<O, R>;
+declare function ref<O extends Model, R>(target: O, mapper: (key: Model.Key<O>) => R): ref.CustomProxy<O, R>;
 /**
  * Creates a ref-compatible property.
  * Will persist value, and updates to this are made part of controller event-stream.
@@ -416,42 +425,54 @@ declare function use<T extends {}>(peer: T, callback?: (i: T) => void): T;
 declare function has<T extends Model>(Type: Model.Type<T>, required: false): T | undefined;
 declare function has<T extends Model>(Type: Model.Type<T>, required?: true): T;
 
+declare namespace MVC {
+    type EffectCallback<T = MVC> = (found: T) => Callback | void;
+}
 declare class MVC extends Model {
+    end(force?: boolean): boolean | void;
+    static global?: boolean;
+    static keepAlive?: boolean;
+    /**
+     * Create a new instance of this model and activate its managed state.
+     *
+     * @param args - arguments sent to constructor
+     */
+    static new<T extends Class>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
     /**
      * **React Hook** - Fetch most instance of this controller from context, if it exists.
      *
      * @param required - Unless false, will throw where instance cannot be found.
      */
-    static get<T extends MVC>(this: Model.Type<T>, required?: boolean): T;
+    static get<T extends MVC>(this: Model.Type<T>, required?: boolean, effectCallback?: MVC.EffectCallback<T>): T;
     /**
      * **React Hook** - Fetch most instance of this controller from context.
      *
      * @param required - If false, may return undefined.
      */
-    static get<T extends MVC>(this: Model.Type<T>, required: false): T | undefined;
-    /**
-     * **React Hook** - Fetch specific value from instance of this controller in context.
-     */
-    static get<I extends MVC, K extends Model.Field<I>>(this: Model.Type<I>, key: K): I[K];
+    static get<T extends MVC>(this: Model.Type<T>, required: false, effectCallback?: MVC.EffectCallback<T | undefined>): T | undefined;
     /**
      * **React Hook** - Fetch instance.
      *
      * Effect callback will run once if found, throw if not found.
      * Returned function is called on unmount.
      */
-    static get<I extends MVC>(this: Model.Type<I>, effect: (found: I) => Callback | void): I;
+    static get<I extends MVC>(this: Model.Type<I>, effectCallback: MVC.EffectCallback<I>): I | undefined;
+    /**
+     * **React Hook** - Fetch specific value from instance of this controller in context.
+     */
+    static get<I extends MVC, K extends Model.Key<I>>(this: Model.Type<I>, key: K): I[K];
     /**
      * **React Hook** - Fetch and subscribe to instance of this controller within ambient component.
      */
     static tap<T extends MVC>(this: Model.Type<T>): T;
-    static tap<T extends MVC, K extends Model.Field<T>>(this: Model.Type<T>, key: K, expect: true): Exclude<T[K], undefined>;
-    static tap<T extends MVC, K extends Model.Field<T>>(this: Model.Type<T>, key: K, expect?: boolean): T[K];
-    static tap<T extends MVC, R>(this: Model.Type<T>, connect: (this: T, model: T) => () => R): R;
-    static tap<T extends MVC, R>(this: Model.Type<T>, connect: (this: T, model: T) => (() => R) | null): R | null;
+    static tap<T extends MVC, K extends Model.Key<T>>(this: Model.Type<T>, key: K, expect: true): Exclude<T[K], undefined>;
+    static tap<T extends MVC, K extends Model.Key<T>>(this: Model.Type<T>, key: K, expect?: boolean): NoVoid<T[K]>;
+    static tap<T extends MVC, R>(this: Model.Type<T>, connect: (this: T, model: T) => () => R): NoVoid<R>;
+    static tap<T extends MVC, R>(this: Model.Type<T>, connect: (this: T, model: T) => (() => R) | null): NoVoid<R> | null;
     static tap<T extends MVC, R>(this: Model.Type<T>, compute: (this: T, model: T) => Promise<R> | R, expect: true): Exclude<R, undefined>;
-    static tap<T extends MVC, R>(this: Model.Type<T>, compute: (this: T, model: T) => Promise<R>, expect?: boolean): R | undefined;
-    static tap<T extends MVC, R>(this: Model.Type<T>, compute: (this: T, model: T) => R, expect?: boolean): R;
-    static use<I extends MVC>(this: Model.Type<I>, watch: Model.Field<I>[], callback?: (instance: I) => void): I;
+    static tap<T extends MVC, R>(this: Model.Type<T>, compute: (this: T, model: T) => Promise<R>, expect?: boolean): NoVoid<R> | null;
+    static tap<T extends MVC, R>(this: Model.Type<T>, compute: (this: T, model: T) => R, expect?: boolean): NoVoid<R>;
+    static use<I extends MVC>(this: Model.Type<I>, watch: Model.Key<I>[], callback?: (instance: I) => void): I;
     static use<I extends MVC>(this: Model.Type<I>, callback?: (instance: I) => void): I;
     static use<I extends MVC>(this: Model.Type<I>, apply: Model.Compat<I>, keys?: Model.Event<I>[]): I;
     static meta<T extends Class>(this: T): T;
@@ -463,38 +484,33 @@ declare class MVC extends Model {
     static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect?: boolean): T;
 }
 
-declare function useValue<T extends {}, R>(source: (() => T) | T, compute: (this: T, from: T) => R, expect: true): Exclude<R, undefined>;
-declare function useValue<T extends {}, R>(source: (() => T) | T, compute: (this: T, from: T) => R, expect?: boolean): R;
-
 declare class Lookup {
     private table;
     get local(): Model[];
     private key;
     get(T: Model.Type): any;
+    add(T: Model.Type, I: Model, writable?: boolean): void;
     push(): this;
-    inject(T: Model.Type, I: Model, writable?: boolean): void;
     pop(): void;
 }
 declare function useContext<T extends Model>(Type: Model.Type<T>, required: false): T | undefined;
-declare function useContext<T extends Model>(Type: Model.Type<T>, arg?: boolean): T;
-declare function useContext<T extends Model>(Type: Model.Type<T>, effect: (found: T) => Callback | void): T;
-declare function useContext<T extends Model, K extends Model.Field<T>>(Type: Model.Type<T>, key: K): T[K];
+declare function useContext<T extends Model>(Type: Model.Type<T>, required?: boolean): T;
 
-declare function useModel<T extends Model>(source: Model.Type<T> | (() => T), callback?: (instance: T) => void): T;
-declare function useModel<T extends Model>(source: Model.Type<T> | (() => T), watch: Model.Field<T>[], callback?: (instance: T) => void): T;
-declare function useModel<T extends Model>(source: Model.Type<T> | (() => T), apply: Model.Compat<T>, keys?: Model.Event<T>[]): T;
+declare function useNew<T extends Model>(source: Model.Type<T> | (() => T), callback?: (instance: T) => void): T;
+declare function useNew<T extends Model>(source: Model.Type<T> | (() => T), watch: Model.Key<T>[], callback?: (instance: T) => void): T;
+declare function useNew<T extends Model>(source: Model.Type<T> | (() => T), apply: Model.Compat<T>, keys?: Model.Event<T>[]): T;
 
 declare namespace useTap {
     type Source<T extends Model> = T | Model.Type<T> | (() => T | Model.Type<T>);
 }
 declare function useTap<T extends Model>(source: useTap.Source<T>): T;
-declare function useTap<T extends Model, K extends Model.Field<T>>(source: useTap.Source<T>, path: K, expect: true): Exclude<T[K], undefined>;
-declare function useTap<T extends Model, K extends Model.Field<T>>(source: useTap.Source<T>, path: K, expect?: boolean): T[K];
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, connect: (this: T, model: T) => () => R): R;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, connect: (this: T, model: T) => (() => R) | null): R | null;
+declare function useTap<T extends Model, K extends Model.Key<T>>(source: useTap.Source<T>, path: K, expect: true): Exclude<T[K], undefined>;
+declare function useTap<T extends Model, K extends Model.Key<T>>(source: useTap.Source<T>, path: K, expect?: boolean): NoVoid<T[K]>;
+declare function useTap<T extends Model, R>(source: useTap.Source<T>, connect: (this: T, model: T) => () => R): NoVoid<R>;
+declare function useTap<T extends Model, R>(source: useTap.Source<T>, connect: (this: T, model: T) => (() => R) | null): NoVoid<R> | null;
 declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: (this: T, model: T) => Promise<R> | R, expect: true): Exclude<R, undefined>;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: (this: T, model: T) => Promise<R>, expect?: boolean): R | undefined;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: (this: T, model: T) => R, expect?: boolean): R;
+declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: (this: T, model: T) => Promise<R>, expect?: boolean): NoVoid<R> | null;
+declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: (this: T, model: T) => R, expect?: boolean): NoVoid<R>;
 
 declare namespace Consumer {
     type HasProps<E extends Class> = {
@@ -538,48 +554,24 @@ declare namespace Provider {
     type Multiple<T extends Item = Item> = T[] | {
         [key: string]: T;
     };
-    type Existent<E> = E extends Class ? InstanceType<E> : E extends Model ? E : never;
-    type NormalProps<E, I = Existent<E>> = {
+    type Instance<E> = E extends Class ? InstanceType<E> : E extends Model ? E : never;
+    type NormalProps<E, I = Instance<E>> = {
         for: E;
         children?: React.ReactNode | ((instance: I) => React.ReactNode);
-    } & Model.Compat<I>;
+        and?: Model.Compat<I>;
+    };
     type MultipleProps<T extends Item> = {
         for: Multiple<T>;
         children?: React.ReactNode | (() => React.ReactNode);
-    } & Model.Compat<Existent<T>>;
+        and?: Model.Compat<Instance<T>>;
+    };
     type Props<T extends Item> = MultipleProps<T> | NormalProps<T>;
 }
 declare function Provider<T extends Provider.Item>(props: Provider.Props<T>): React.FunctionComponentElement<React.ProviderProps<Lookup>>;
 
 declare class Global extends MVC {
-    constructor();
-    destroy(force?: boolean): boolean;
+    static global: boolean;
     static keepAlive: boolean;
-    static new<T extends Class>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
-    /**
-     * Update the active instance of this class.
-     * Returns a thenable; resolves after successful update.
-     * If instance does not already exist, one will be created.
-     */
-    static set<T extends typeof Global>(this: T, values: Model.Compat<InstanceOf<T>, Global>): PromiseLike<Model.Field<InstanceOf<T>, Global>[]>;
-    /**
-     * **React Hook** - Fetch most instance of this controller from context, if it exists.
-     *
-     * @param required - If false, may return undefined.
-     */
-    static get<T extends Global>(this: Model.Type<T>, required: false): T | undefined;
-    /**
-     * **React Hook** - Fetch most instance of this controller from context.
-     *
-     * @param required - Unless false, will throw where instance cannot be found.
-     */
-    static get<T extends Global>(this: Model.Type<T>, required?: boolean): T;
-    /**
-     * **React Hook** - Fetch specific value from instance of this controller in context.
-     */
-    static get<T extends Global, K extends Model.Field<T, Global>>(this: Model.Type<T>, key: K): T[K];
-    /** Destroy current instance of Global, if it exists. */
-    static reset(): void;
 }
 
 /**
@@ -607,4 +599,4 @@ declare function tap<T extends Model>(Type: Model.Type<T>, callback?: (instance?
 declare function tap<T extends Model>(Type: Model.Type<T>, required: true): T;
 declare function tap<T extends Model>(Type: Model.Type<T>, required?: boolean): T | undefined;
 
-export { Consumer, Debug, Global, MVC, MVC as Model, Provider, add, MVC as default, get, has, ref, run, set, tap, use, useContext, useModel, useTap, useValue };
+export { Consumer, Debug, Global, MVC, MVC as Model, Provider, add, MVC as default, get, has, ref, run, set, tap, use, useContext, useNew, useTap };