@expressive/mvc 0.17.1 → 0.18.1

package/lib/index.d.ts

@@ -1,46 +1,3 @@
-import React from 'react';
-
-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;
-
-type OptionalValues<T extends {}> = {
-  [P in Model.Key<T>]: T[P] | undefined;
-}
-
-type NonOptionalValues<T extends {}> = {
-  [P in Model.Key<T>]: Exclude<T[P], undefined>;
-};
-
-type Listener = {
-    commit(): void;
-    release(): void;
-};
-declare namespace Subscriber {
-    type OnEvent<T = any> = (key: Model.Event<T> | null, source: Control) => Callback | void;
-}
-declare class Subscriber<T extends {} = any> {
-    parent: Control<T>;
-    onUpdate: Subscriber.OnEvent;
-    strict?: boolean | undefined;
-    proxy: T;
-    clear: () => void;
-    latest?: Model.Event<T>[];
-    active: boolean;
-    dependant: Set<Listener>;
-    watch: Map<any, boolean | (() => boolean | void)>;
-    constructor(parent: Control<T>, onUpdate: Subscriber.OnEvent, strict?: boolean | undefined);
-    get using(): Model.Key<T>[];
-    apply(values: Model.Compat<T>, keys?: Model.Key<T>[]): void;
-    follow(key: any, value?: boolean | (() => boolean | void)): void;
-    commit(): void;
-    release(): void;
-    private notify;
-}
-
 declare const LOCAL = "$debug local";
 declare const STATE = "$debug state";
 declare const UPDATE = "$debug update";
@@ -51,7 +8,7 @@ declare const Debug: {
     readonly STATE: "$debug state";
     readonly UPDATE: "$debug update";
 };
-type Debug<T extends {}> = T & {
+type Debug<T extends Model> = T & {
     /** Controller for this instance. */
     [CONTROL]?: Control<T>;
     /** Current subscriber (if present) while used in a live context (e.g. hook or effect). */
@@ -67,6 +24,21 @@ type Debug<T extends {}> = T & {
     [UPDATE]?: readonly Model.Event<T>[];
 };
 
+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;
+
+type OptionalValues<T extends {}> = {
+  [P in Model.Key<T>]: T[P] | undefined;
+}
+
+type NonOptionalValues<T extends {}> = {
+  [P in Model.Key<T>]: Exclude<T[P], undefined>;
+};
+
 declare namespace Model {
     export { Control };
     export { Subscriber };
@@ -86,7 +58,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<{}>;
+    type BuiltIn = keyof Model | keyof Debug<Model>;
     /**
      * Subset of `keyof T` which are not methods or defined by base Model U.
      *
@@ -123,12 +95,28 @@ declare namespace Model {
         [P in Key<T>]: Value<T[P]>;
     };
     export type FindFunction = <T extends Model>(type: Model.Type<T>, relativeTo: Model, required: boolean) => (_refresh: (x: T) => void) => T | undefined;
+    export type TapCallback<T extends Model, R> = (this: T, model: T, update: ForceUpdate) => R;
+    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>;
+    };
+    export type Suspense = Promise<void> & Error;
 }
 declare class Model {
     /**
-     * Circular reference to `this` controller.
-     *
-     * Useful to obtain full reference where one has already destructured.
+     * Reference to `this` without a subscription.
+     * Use to obtain full reference from a destructure.
      */
     is: this;
     constructor();
@@ -156,10 +144,8 @@ declare class Model {
     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.
-     */
-    end(): void;
+    /** Mark this instance for garbage collection. */
+    gc(): void;
     /**
      * Creates a new instance of this controller.
      *
@@ -168,6 +154,29 @@ declare class Model {
      * @param args - arguments sent to constructor
      */
     static new<T extends Class>(this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
+    static use<I extends Model>(this: Model.Type<I>, watch: Model.Key<I>[], callback?: (instance: I) => void): I;
+    static use<I extends Model>(this: Model.Type<I>, callback?: (instance: I) => void): I;
+    static use<I extends Model>(this: Model.Type<I>, apply: Model.Compat<I>, keys?: Model.Event<I>[]): I;
+    static get<T extends Model>(this: Model.Type<T>, required?: boolean): T;
+    static get<T extends Model>(this: Model.Type<T>, required: false): T | undefined;
+    static tap<T extends Model>(this: Model.Type<T>): T;
+    static tap<T extends Model, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: Model.TapCallback<T, R | (() => R)>, expect?: boolean): R;
+    static tap<T extends Model, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: Model.TapCallback<T, Promise<R> | (() => R) | null>, expect?: boolean): R | null;
+    static tap<T extends Model, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: Model.TapCallback<T, Promise<R> | R>, expect: true): Exclude<R, undefined>;
+    static tap<T extends Model, R>(this: Model.Type<T>, init: Model.TapCallback<T, () => R>): NoVoid<R>;
+    static tap<T extends Model, R>(this: Model.Type<T>, init: Model.TapCallback<T, (() => R) | null>): NoVoid<R> | null;
+    static tap<T extends Model, R>(this: Model.Type<T>, compute: Model.TapCallback<T, Promise<R> | R>, expect: true): Exclude<R, undefined>;
+    static tap<T extends Model, R>(this: Model.Type<T>, compute: Model.TapCallback<T, Promise<R>>, expect?: boolean): NoVoid<R> | null;
+    static tap<T extends Model, R>(this: Model.Type<T>, compute: Model.TapCallback<T, R>, expect?: boolean): NoVoid<R>;
+    static tap<T extends Model>(this: Model.Type<T>, expect: true): NonOptionalValues<T>;
+    static tap<T extends Model>(this: Model.Type<T>, expect?: boolean): OptionalValues<T>;
+    protected static meta<T extends Class>(this: T): T;
+    protected static meta<T extends Class>(this: T, expect: true): NonOptionalValues<T>;
+    protected static meta<T extends Class>(this: T, expect?: boolean): OptionalValues<T>;
+    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect: true): Exclude<T, undefined>;
+    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect?: boolean): T;
+    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect: true): Exclude<T, undefined>;
+    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect?: boolean): T;
     /**
      * Static equivalent of `x instanceof this`.
      *
@@ -176,6 +185,54 @@ declare class Model {
     static isTypeof<T extends Model.Type>(this: T, maybe: any): maybe is T;
 }
 
+type Listener = {
+    commit(): void;
+    release(): void;
+};
+declare namespace Subscriber {
+    type OnEvent<T = any> = (key: Model.Event<T> | null, source: Control) => Callback | void;
+    type Getter<T extends Model> = (within?: Subscriber<T> | undefined) => any;
+}
+declare class Subscriber<T extends Model = any> {
+    onUpdate: Subscriber.OnEvent;
+    proxy: T;
+    clear: () => void;
+    latest?: Model.Event<T>[];
+    active: boolean;
+    dependant: Set<Listener>;
+    watch: Map<any, boolean | (() => boolean | void)>;
+    parent: Control<T>;
+    constructor(parent: Control<T> | T, onUpdate: Subscriber.OnEvent);
+    get using(): Model.Key<T>[];
+    get(key: string, using?: Subscriber.Getter<T>): any;
+    follow(key: any, value?: boolean | (() => boolean | void)): void;
+    commit(): void;
+    release(): void;
+    private notify;
+}
+
+/**
+ * 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) => Instruction.Getter<T> | Instruction.Descriptor<T> | void;
+declare namespace Instruction {
+    type Getter<T> = (within?: Subscriber) => T;
+    type Setter<T> = (value: T) => boolean | void;
+    type Runner = (on: Control, key: string) => Instruction.Descriptor<any> | undefined;
+    interface Descriptor<T> {
+        enumerable?: boolean;
+        value?: T;
+        get?: Getter<T>;
+        set?: Setter<T> | false;
+    }
+}
+/**
+ * Run instruction as controller sets itself up.
+ * This will specialize the behavior of a given property.
+ */
+declare function add<T = any>(instruction: Instruction<any>, label?: string): T;
+
 declare namespace Control {
     /**
      * Called immediately when any key is changed or emitted.
@@ -195,6 +252,8 @@ declare class Control<T extends {} = any> {
     latest?: Model.Event<T>[];
     constructor(subject: T);
     watch(key: keyof T & string): void;
+    /** Throw suspense which resolves when key is set. */
+    waitFor(key: string): never;
     addListener(listener: Control.OnSync<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;
@@ -213,27 +272,7 @@ declare namespace control {
 declare function control<T extends Model>(subject: T): Control<T>;
 declare function control<T extends Model>(subject: T, cb: control.OnReady<T>): Callback;
 
-/**
- * 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) => Instruction.Getter<T> | Instruction.Descriptor<T> | void;
-declare namespace Instruction {
-    type Getter<T> = (within?: Subscriber) => T;
-    type Setter<T> = (value: T) => boolean | void;
-    type Runner = (on: Control, key: string) => Instruction.Descriptor<any> | undefined;
-    interface Descriptor<T> {
-        enumerable?: boolean;
-        value?: T;
-        get?: Getter<T>;
-        set?: Setter<T> | false;
-    }
-}
-/**
- * Run instruction as controller sets itself up.
- * This will specialize the behavior of a given property.
- */
-declare function add<T = any>(instruction: Instruction<any>, label?: string): T;
+declare function getParent<T extends Model>(from: Model, type?: Model.Type<T>): T;
 
 type Async<T = any> = (...args: any[]) => Promise<T>;
 /**
@@ -256,6 +295,10 @@ declare function run<S>(action: Async<S>): typeof action & {
 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 FindFunction<T extends Model = Model> = (type: typeof Model, relativeTo: Model, required: boolean) => Source<T>;
+    type Source<T extends Model = Model> = (callback: (x: T) => void) => void;
+    /** Assign fetch algorithm for get instruction. */
+    let using: (fn: FindFunction) => typeof get;
 }
 /**
  * Fetches and assigns the controller which spawned this host.
@@ -422,142 +465,18 @@ declare function use<T extends {}>(from: () => T, callback?: (i: T) => void): T;
  */
 declare function use<T extends {}>(peer: T, callback?: (i: T) => void): T;
 
-declare namespace MVC {
-    type EffectCallback<T = MVC> = (found: T) => Callback | void;
-    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 TapCallback<T extends Model, R> = (this: T, model: T, update: MVC.ForceUpdate) => R;
+declare class Register {
+    private table;
+    register: Map<string | number, Model | Model.Type>;
+    private has;
+    get<T extends Model>(Type: Model.Type<T>): T | undefined;
+    add(input: Model.New | Model, key?: number | string): Model;
+    push(): this;
+    pop(): 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, 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, 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>, effectCallback: MVC.EffectCallback<I>): I | undefined;
-    /**
-     * **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, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: MVC.TapCallback<T, R | (() => R)>, expect?: boolean): R;
-    static tap<T extends MVC, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: MVC.TapCallback<T, Promise<R> | (() => R) | null>, expect?: boolean): R | null;
-    static tap<T extends MVC, R extends readonly unknown[] | []>(this: Model.Type<T>, compute: MVC.TapCallback<T, Promise<R> | R>, expect: true): Exclude<R, undefined>;
-    static tap<T extends MVC, R>(this: Model.Type<T>, init: MVC.TapCallback<T, () => R>): NoVoid<R>;
-    static tap<T extends MVC, R>(this: Model.Type<T>, init: MVC.TapCallback<T, (() => R) | null>): NoVoid<R> | null;
-    static tap<T extends MVC, R>(this: Model.Type<T>, compute: MVC.TapCallback<T, Promise<R> | R>, expect: true): Exclude<R, undefined>;
-    static tap<T extends MVC, R>(this: Model.Type<T>, compute: MVC.TapCallback<T, Promise<R>>, expect?: boolean): NoVoid<R> | null;
-    static tap<T extends MVC, R>(this: Model.Type<T>, compute: MVC.TapCallback<T, R>, expect?: boolean): NoVoid<R>;
-    static tap<T extends MVC>(this: Model.Type<T>, expect: true): NonOptionalValues<T>;
-    static tap<T extends MVC>(this: Model.Type<T>, expect?: boolean): OptionalValues<T>;
-    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;
-    protected static meta<T extends Class>(this: T): T;
-    protected static meta<T extends Class>(this: T, expect: true): NonOptionalValues<T>;
-    protected static meta<T extends Class>(this: T, expect?: boolean): OptionalValues<T>;
-    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect: true): Exclude<T, undefined>;
-    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect?: boolean): T;
-    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect: true): Exclude<T, undefined>;
-    protected static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect?: boolean): T;
-}
-
-declare namespace Consumer {
-    type HasProps<E extends Class> = {
-        /** @deprecated - use for instead */
-        of?: never;
-        /** Type of controller to fetch from context. */
-        for: E;
-        /**
-         * Getter function. Is called on every natural render of this component.
-         * Will throw if usable instance cannot be found in context.
-         */
-        has: (value: InstanceType<E>) => void;
-    };
-    type GetProps<E extends Class> = {
-        /** @deprecated - use for instead */
-        of?: never;
-        /** Type of controller to fetch from context. */
-        for: E;
-        /** Getter function. Is called on every natural render of this component. */
-        get: (value: InstanceType<E> | undefined) => void;
-    };
-    type RenderProps<E extends Class> = {
-        /** @deprecated - use for instead */
-        of?: never;
-        /** Type of controller to fetch from context. */
-        for: E;
-        /**
-         * Render function, will receive instance of desired controller.
-         *
-         * Similar to `tap()`, updates to properties accessed in
-         * this function will cause a refresh when they change.
-         */
-        children: (value: InstanceType<E>) => React.ReactElement<any, any> | null;
-    };
-    type Props<T extends Class> = HasProps<T> | GetProps<T> | RenderProps<T>;
-}
-declare function Consumer<T extends Class>(props: Consumer.Props<T>): any;
-
-declare namespace Provider {
-    type Item = Model | Model.New;
-    type Multiple<T extends Item = Item> = T[] | {
-        [key: string]: T;
-    };
-    type Instance<E> = E extends Class ? InstanceType<E> : E extends Model ? E : never;
-    type NormalProps<E, I = Instance<E>> = {
-        for: E;
-        fallback?: React.ReactNode;
-        children?: React.ReactNode | ((instance: I) => React.ReactNode);
-        use?: Model.Compat<I>;
-    };
-    type MultipleProps<T extends Item> = {
-        for: Multiple<T>;
-        fallback?: React.ReactNode;
-        children?: React.ReactNode;
-        use?: Model.Compat<Instance<T>>;
-    };
-    type Props<T extends Item> = MultipleProps<T> | NormalProps<T>;
-}
-declare function Provider<T extends Provider.Item>(props: Provider.Props<T>): JSX.Element;
 
-declare class Global extends MVC {
-    static global: boolean;
-    static keepAlive: boolean;
-}
+declare const Internal: {
+    getParent: typeof getParent;
+};
 
-export { Consumer, Debug, Global, MVC, MVC as Model, Provider, add, MVC as default, get, ref, run, set, use };
+export { Control, Debug, Internal, Model, Register, Subscriber, add, Model as default, get, ref, run, set, use };