@expressive/mvc 0.15.2 → 0.17.0

package/lib/index.d.ts

@@ -7,7 +7,15 @@ 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 = {
+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;
 };
@@ -17,17 +25,20 @@ declare namespace Subscriber {
 declare class Subscriber<T extends {} = any> {
     parent: Control<T>;
     onUpdate: Subscriber.OnEvent;
+    strict?: boolean | undefined;
     proxy: T;
-    release: Callback;
+    clear: () => void;
     latest?: Model.Event<T>[];
     active: boolean;
     dependant: Set<Listener>;
-    watch: Map<any, boolean | (() => true | void)>;
-    constructor(parent: Control<T>, onUpdate: Subscriber.OnEvent);
+    watch: Map<any, boolean | (() => boolean | void)>;
+    constructor(parent: Control<T>, onUpdate: Subscriber.OnEvent, strict?: boolean | undefined);
     get using(): Model.Key<T>[];
-    add(key: any, value?: boolean | Callback): void;
-    commit(): () => void;
-    private onEvent;
+    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";
@@ -40,7 +51,7 @@ declare const Debug: {
     readonly STATE: "$debug state";
     readonly UPDATE: "$debug update";
 };
-declare type Debug<T extends {}> = T & {
+type Debug<T extends {}> = T & {
     /** Controller for this instance. */
     [CONTROL]?: Control<T>;
     /** Current subscriber (if present) while used in a live context (e.g. hook or effect). */
@@ -62,7 +73,7 @@ declare namespace Model {
     /** Including but not limited to T. */
     type Extends<T> = T | (string & Record<never, never>);
     /** Any typeof Model, using class constructor as the reference. */
-    export type Type<T extends Model = Model> = abstract new (...args: any[]) => T;
+    export type Type<T extends Model = Model> = (abstract new (...args: any[]) => T) & typeof Model;
     /** A typeof Model, specifically one which may be created without arguments. */
     export type New<T extends Model = Model> = (new () => T) & typeof Model;
     export type Effect<T> = (this: T, argument: T) => Callback | Promise<any> | void;
@@ -111,6 +122,7 @@ declare namespace Model {
     export type Export<T> = {
         [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;
 }
 declare class Model {
     /**
@@ -182,42 +194,39 @@ declare class Control<T extends {} = any> {
     followers: Set<Model.Control.OnSync<any>>;
     latest?: Model.Event<T>[];
     constructor(subject: T);
-    subscribe(callback: Subscriber.OnEvent<T>): Model.Subscriber<T>;
     watch(key: keyof T & string): void;
     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;
     clear(): void;
+    static get: typeof controller;
+    static for: typeof control;
+}
+declare function controller<T extends Model>(from: T): Control<T> | undefined;
+declare namespace control {
+    /**
+     * Callback for Controller.for() static method.
+     * Returned callback is forwarded.
+     */
+    type OnReady<T extends Model> = (control: Control<T>) => Callback | void;
 }
+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.
  */
-declare type Instruction<T> = (this: Control, key: string, thisArg: Control) => Instruction.Getter<T> | Instruction.ExplicitDescriptor | Instruction.Descriptor<T> | Instruction.RecursiveDescriptor<T> | boolean | void;
+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<T> = (this: Control, key: string, on: Control) => Instruction.Descriptor<T> | boolean | undefined;
+    type Runner = (on: Control, key: string) => Instruction.Descriptor<any> | undefined;
     interface Descriptor<T> {
-        configurable?: boolean;
         enumerable?: boolean;
         value?: T;
-        writable?: boolean;
         get?: Getter<T>;
         set?: Setter<T> | false;
-        suspend?: boolean;
-        destroy?: () => void;
-    }
-    interface ExplicitDescriptor extends PropertyDescriptor {
-        explicit: true;
-    }
-    interface RecursiveDescriptor<T> {
-        recursive: true;
-        enumerable?: boolean;
-        value?: T;
-        set?: Setter<T> | false;
-        suspend?: boolean;
     }
 }
 /**
@@ -226,7 +235,7 @@ declare namespace Instruction {
  */
 declare function add<T = any>(instruction: Instruction<any>, label?: string): T;
 
-declare type Async<T = any> = (...args: any[]) => Promise<T>;
+type Async<T = any> = (...args: any[]) => Promise<T>;
 /**
  * Sets an exotic method with managed ready-state. Property accepts an async function.
  *
@@ -246,65 +255,35 @@ declare function run<S>(action: Async<S>): typeof action & {
 
 declare namespace get {
     type Function<T, S = any> = (this: S, on: S) => T;
-    type Factory<T, S = unknown> = (this: S, key: string, thisArg: S) => T;
+    type Factory<R, T> = (this: T, property: string, on: T) => Function<R, 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 - Throw if controller is created independantly.
+ */
+declare function get<T extends Model>(Type: Model.Type<T>, required?: true): T;
+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>;
+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.
  *
  * @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.
- * @param suspend - Value will throw suspense when evaulating to undefined.
  */
-declare function get<R, T>(source: T, compute: (this: T, on: T) => R, suspend: true): Exclude<R, undefined>;
-declare function get<R, T>(source: T, compute: (this: T, on: T) => R, suspend?: boolean): R;
+declare function get<R, T>(source: T, compute: (this: T, on: T) => R): Exclude<R, undefined>;
+declare function get<R, T>(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.
- * @param suspend - Value will throw suspense when evaulating to undefined.
  */
-declare function get<R, T>(compute: (property: string, on: T) => (this: T, state: T) => R, suspend: true): Exclude<R, undefined>;
-declare function get<R, T>(compute: (property: string, on: T) => (this: T, state: T) => R, suspend?: boolean): R;
-/**
- * Set property with an async function.
- *
- * Property cannot be accessed until factory resolves, yeilding a result.
- * If accessed while processing, React Suspense will be thrown.
- *
- * - `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.
- *
- * @param factory - Callback run to derrive property value.
- * @param required - (default: true) Run factory immediately on creation, otherwise on access.
- */
-declare function get<T>(factory: get.Factory<Promise<T>>, required: false): T | undefined;
-declare function get<T, S>(factory: get.Factory<Promise<T>, S>, required: false): T | undefined;
-declare function get<T>(factory: get.Factory<Promise<T>>, required?: boolean): T;
-declare function get<T, S>(factory: get.Factory<Promise<T>, S>, required?: boolean): T;
-/**
- * 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.
- *
- * @param factory - Callback run to derrive property value.
- * @param required - (default: true) Run factory immediately on creation, otherwise on access.
- */
-declare function get<T>(factory: get.Factory<T>, required: false): T | undefined;
-declare function get<T, S>(factory: get.Factory<T, S>, required: false): T | undefined;
-declare function get<T>(factory: get.Factory<T>, required?: boolean): T;
-declare function get<T, S>(factory: get.Factory<T, S>, required?: boolean): T;
-/**
- * Assign a property with result of a promise.
- */
-declare function get<T>(factory: Promise<T>, required: false): T | undefined;
-declare function get<T>(factory: Promise<T>, required?: boolean): T;
+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 {
     type Callback<T, S = any> = (this: S, argument: T) => ((next: T) => void) | Promise<void> | void | boolean;
@@ -351,6 +330,7 @@ declare function ref<T, S>(callback?: ref.Callback<T, S>): ref.Object<T>;
 
 declare namespace set {
     type Callback<T, S = any> = (this: S, argument: T) => ((next: T) => void) | Promise<any> | void | boolean;
+    type Factory<T, S = unknown> = (this: S, key: string, thisArg: S) => T;
 }
 /**
  * Set property with a placeholder.
@@ -359,15 +339,50 @@ declare namespace set {
  * `Promise`/`Error` (ala: [Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)) will be thrown.
  */
 declare function set<T = any>(): T;
-declare function set<T>(onUpdate: set.Callback<T>): T;
-declare function set<T, S>(onUpdate: set.Callback<T, S>): T;
+/**
+ * Set property with an async function.
+ *
+ * Property cannot be accessed until factory resolves, yeilding a result.
+ * If accessed while processing, React Suspense will be thrown.
+ *
+ * - `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.
+ *
+ * @param factory - Callback run to derrive property value.
+ * @param required - (default: true) Run factory immediately on creation, otherwise on access.
+ */
+declare function set<T>(factory: set.Factory<Promise<T>>, required: false): T | undefined;
+declare function set<T, S>(factory: set.Factory<Promise<T>, S>, required: false): T | undefined;
+declare function set<T>(factory: set.Factory<Promise<T>>, required?: boolean): T;
+declare function set<T, S>(factory: set.Factory<Promise<T>, S>, required?: boolean): T;
+/**
+ * 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.
+ *
+ * @param factory - Callback run to derrive property value.
+ * @param required - (default: true) Run factory immediately on creation, otherwise on access.
+ */
+declare function set<T>(factory: set.Factory<T>, required: false): T | undefined;
+declare function set<T, S>(factory: set.Factory<T, S>, required: false): T | undefined;
+declare function set<T>(factory: set.Factory<T>, required?: boolean): T;
+declare function set<T, S>(factory: set.Factory<T, S>, required?: boolean): T;
+declare function set<T>(factory: Promise<T>, required: false): T | undefined;
+declare function set<T>(factory: Promise<T>, required?: boolean): T;
 declare function set<T>(value: undefined, onUpdate: set.Callback<T>): T;
 declare function set<T, S>(value: undefined, onUpdate: set.Callback<T, S>): T;
 declare function set<T>(value: T, onUpdate: set.Callback<T>): T;
 declare function set<T, S>(value: T, onUpdate: set.Callback<T, S>): T;
 
-declare type MapFunction<T, R> = T extends Map<infer K, infer V> ? (value: V, key: K, map: T) => R | void : T extends Set<infer K> ? (value: K, key: K, set: T) => R | void : never;
-declare type Managed<T> = Exclude<T, "forEach"> & {
+type MapFunction<T, R> = T extends Map<infer K, infer V> ? (value: V, key: K, map: T) => R | void : T extends Set<infer K> ? (value: K, key: K, set: T) => R | void : never;
+type Managed<T> = Exclude<T, "forEach"> & {
     from?: T;
     forEach<R>(mapFunction: MapFunction<T, R>, thisArg?: any): Exclude<R, undefined>[] | void;
 };
@@ -407,17 +422,6 @@ declare function use<T extends {}>(from: () => T, callback?: (i: T) => void): T;
  */
 declare function use<T extends {}>(peer: T, callback?: (i: T) => void): 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 - Throw if controller is created independantly.
- */
-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;
     type ForceUpdate = {
@@ -466,52 +470,31 @@ declare class MVC extends Model {
      * Returned function is called on unmount.
      */
     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.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: MVC.TapCallback<T, () => R>): NoVoid<R>;
-    static tap<T extends MVC, R>(this: Model.Type<T>, connect: MVC.TapCallback<T, (() => R) | null>): NoVoid<R> | null;
+    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;
-    static meta<T extends Class>(this: T): T;
-    static meta<T extends Class, K extends keyof T>(this: T, key: K, expect: true): Exclude<T[K], undefined>;
-    static meta<T extends Class, K extends keyof T>(this: T, key: K, expect?: boolean): T[K];
-    static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect: true): Exclude<T, undefined>;
-    static meta<T, M extends Class>(this: M, from: (this: M, state: M) => Promise<T>, expect?: boolean): T;
-    static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect: true): Exclude<T, undefined>;
-    static meta<T, M extends Class>(this: M, from: (this: M, state: M) => T, expect?: boolean): T;
-}
-
-declare function useContext<T extends Model>(Type: Model.Type<T>, required: false): T | undefined;
-declare function useContext<T extends Model>(Type: Model.Type<T>, required?: boolean): T;
-
-declare function useNew<T extends Model>(source: Model.New<T> | (() => T), callback?: (instance: T) => void): T;
-declare function useNew<T extends Model>(source: Model.New<T> | (() => T), watch: Model.Key<T>[], callback?: (instance: T) => void): T;
-declare function useNew<T extends Model>(source: Model.New<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>);
-    type Callback<T extends Model, R> = (this: T, model: T, update: MVC.ForceUpdate) => R;
+    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 function useTap<T extends Model>(source: useTap.Source<T>): T;
-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: useTap.Callback<T, () => R>): NoVoid<R>;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, connect: useTap.Callback<T, (() => R) | null>): NoVoid<R> | null;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: useTap.Callback<T, Promise<R> | R>, expect: true): Exclude<R, undefined>;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: useTap.Callback<T, Promise<R>>, expect?: boolean): NoVoid<R> | null;
-declare function useTap<T extends Model, R>(source: useTap.Source<T>, compute: useTap.Callback<T, R>, expect?: boolean): NoVoid<R>;
 
 declare namespace Consumer {
     type HasProps<E extends Class> = {
@@ -577,32 +560,4 @@ declare class Global extends MVC {
     static keepAlive: boolean;
 }
 
-declare namespace tap {
-    type Callback<T extends Model> = (instance: T | undefined) => void | boolean;
-}
-/**
- * Find and attach most applicable instance of Model via context.
- *
- * Host controller will search element-hierarchy relative to where it spawned.
- *
- * @param Type - Type of model to find from context
- * @param callback -
- *  - Invoked after context is scanned, is passed result - either found or undefined.
- *  - If argument is inadequate, but required, your implemention should simply throw.
- *  - If inadequate and not required, conditionally return false.
- */
-declare function tap<T extends Model>(Type: Model.Type<T>, callback?: (instance?: T) => void | true): T;
-declare function tap<T extends Model>(Type: Model.Type<T>, callback?: (instance?: T) => void | boolean): T | undefined;
-/**
- * Find and attach most applicable instance of Model via context.
- *
- * Expects a `<Provider>` of target controller to exist.
- * Host controller will search element-hierarchy relative to where it spawned.
- *
- * @param Type - Type of controller to attach to property.
- * @param required - Throw if instance of Type cannot be found.
- */
-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, useNew, useTap };
+export { Consumer, Debug, Global, MVC, MVC as Model, Provider, add, MVC as default, get, ref, run, set, use };