@expressive/mvc 1.0.0-beta.32 → 1.0.0-beta.35

package/types/model.d.ts

@@ -1,19 +1,12 @@
 import { Key } from 'react';
 
 import Lifecycle from './lifecycle';
-import { Select, Selector } from './selector';
-import { BunchOf, Callback, Class, InstanceOf, Query, RequestCallback, UpdateCallback } from './types';
-
-interface PropertyDescriptor<T> {
-    configurable?: boolean;
-    enumerable?: boolean;
-    value?: T;
-    writable?: boolean;
-    get?(): T;
-    set?(v: T): void;
-}
+import { BunchOf, Class, InstanceOf } from './types';
 
+type Callback = () => void;
 type Argument<T> = T extends (arg: infer U) => any ? U : never;
+type IfApplicable<T extends {}, K> = K extends keyof T ? T[K] : undefined;
+type Including<T> = T | (string & Record<never, never>);
 
 type Thenable<T> = {
     then(onFulfilled: (arg: T) => void): void;
@@ -26,17 +19,29 @@ export namespace Model {
         current: T | null;
     }
 
-    type GetFunction<T> = (within?: Subscriber) => T;
+    type UpdateCallback<T, P> = (this: T, value: IfApplicable<T, P>, changed: P) => void;
+
+    type EffectCallback<T> = (this: T, argument: T) => Callback | Promise<any> | void;
 
     /**
      * Property initializer, will run upon instance creation.
      * Optional returned callback will run when once upon first access.
     */
     type Instruction<T> = (this: Controller, key: string, thisArg: Controller) =>
-        void | GetFunction<T> | PropertyDescriptor<T>;
-
-    /** Shallow replacement given all entries of Model */
-    type Overlay<T, R> = { [K in keyof Entries<T>]: R };
+        void | Instruction.Getter<T> | Instruction.Descriptor<T>;
+
+    namespace Instruction {
+        interface Descriptor<T> {
+            configurable?: boolean;
+            enumerable?: boolean;
+            value?: T;
+            writable?: boolean;
+            get?(current: T | undefined, within?: Subscriber): T;
+            set?(value: T, state: any): boolean | void;
+        }
+    
+        type Getter<T> = (state: T | undefined, within?: Subscriber) => T;
+    }
 
     /** Subset of `keyof T` excluding keys defined by base Model */
     type Fields<T, E = Model> = Exclude<keyof T, keyof E>;
@@ -52,87 +57,48 @@ export namespace Model {
         [P in K]: Value<T[P]>;
     }
 
-    /** Object comperable to data which may be found in T. */
-    type Data<T, E = Model> = Partial<Entries<T, E>>;
+    /** Object comperable to data found in T. */
+    type Compat<T, Exclude = Model> = Partial<Entries<T, Exclude>>;
 
     /** Subset of `keyof T` excluding keys defined by base Model, except lifecycle. */
     type Events<T> = Omit<T, Exclude<keyof Model, keyof Lifecycle>>;
 
-    type EventsCompat<T> = keyof T | keyof Lifecycle;
-
-    /**
-     * Field selector which includes Model-Lifecycle events.
-     * Can select for any tracked-property on a specified controller.
-     * 
-     * Function `SelectEvent<T>` is a preferred alterative to string `keyof T`.
-     * 
-     * ---
-     * 
-     * ```js
-     * Model.on(x => x.foo.bar.didMountComponent, cb)
-     * ```
-     * is equivalent to, while also more robust than:
-     * ```js
-     * Model.on(["foo", "bar", "didMountComponent"], cb)
-     * ```
-     */
-    type SelectEvents<T> = Selector.Function<Events<T>>;
-
-    /**
-     * Field selector function you provide. Argument is a representation of controller specified.
-     * *When used as an argument*, return a chain of properties desired for a given operation.
-     * 
-     * Allows for refactor safe selection of properties belonging to a controller. 
-     * Using selectors is generally recommended to prevent unexpected behavior to be caused by bundling of your code.
-     * 
-     * ---
-     * 
-     * **Selector used to update specific properties:**
-     * 
-     * ```js
-     * Model.update(x => x.foo.bar.baz)
-     * ```
-     * 
-     * is equivalent to, while more robust than:
-     * 
-     * ```js
-     * Model.update(["foo", "bar", "baz"])
-     * ```
-     */
-    type SelectFields<T> = Selector.Function<Omit<T, keyof Model>>;
-
-    type SelectField<T> = (arg: Omit<T, keyof Model>) => any;
-
-    type SelectFieldKey<T> = Select.Key<Fields<T>>;
+    type EventsCompat<T> = Including<keyof T | keyof Lifecycle>;
 
     type Typeof<T, ST, X extends keyof T = Exclude<keyof T, keyof Model>> = {
         [Key in X]: T[Key] extends ST ? Key : never;
     }[X];
 
-    type SelectTypeof<T, ST> = Select.Key<Typeof<T, ST>>;
-
-    type HandleValue = (value: any) => boolean | void;
-
     export namespace Controller {
-        export type Listen = (key: string, source: Controller) =>
+        type RequestCallback = (keys: readonly string[]) => void;
+
+        type OnEvent = (key: string, source: Controller) =>
             RequestCallback | undefined;
+
+        type OnValue = <T>(this: T, value: any, state: T) => boolean | void;
     }
 
     export class Controller {
         state: BunchOf<any>;
         subject: {};
-        waiting: Set<RequestCallback>;
+        waiting: Set<Controller.RequestCallback>;
+        frame: Set<string>;
 
-        /** Add property to managed state. */
-        manage(key: string, initial: any, effect?: HandleValue): void;
+        start(): this;
 
-        select(using?: Query): string[];
+        manage(key: string, effect?: Controller.OnValue): void;
 
-        setter(key: string, effect?: HandleValue): (value: any) => boolean | void;
+        setter(key: string, effect?: Controller.OnValue): (value: any) => boolean | void;
 
-        addListener(listener: Controller.Listen): Callback;
+        addListener(listener: Controller.OnEvent): Callback;
 
         update(key: string, value?: any): void;
+
+        requestUpdate(): PromiseLike<readonly string[] | false>;
+        requestUpdate(strict: true): Promise<readonly string[]>;
+        requestUpdate(strict: false): Promise<false>;
+        requestUpdate(strict: boolean): Promise<readonly string[] | false>;
+        requestUpdate(callback: Controller.RequestCallback): void;
     }
 
     export class Subscriber {
@@ -140,13 +106,13 @@ export namespace Model {
         source: any;
         parent: Controller;
         active: boolean;
-        listen: Controller.Listen;
+        listen: Controller.OnEvent;
         dependant: Set<{
             commit(): void;
             release(): void;
         }>;
 
-        follow(key: string, cb?: RequestCallback | undefined): void;
+        follow(key: string, cb?: Controller.RequestCallback | undefined): void;
         commit(): Callback;
         release(): Callback;
         onUpdate(): void;
@@ -154,7 +120,7 @@ export namespace Model {
 }
 
 declare const CONTROL: unique symbol;
-declare const UPDATE: unique symbol;
+declare const WHY: unique symbol;
 declare const LOCAL: unique symbol;
 declare const STATE: unique symbol;
 
@@ -175,7 +141,7 @@ export abstract class Model {
      * 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 string[];
+    [WHY]?: readonly string[];
 
     /**
      * Circular reference to `this` controller.
@@ -236,25 +202,19 @@ export abstract class Model {
      */
     set: this;
 
-    import <O extends Model.Data<this>> (via: O, select?: string[] | Model.SelectFields<this>): void;
+    import <O extends Model.Compat<this>> (via: O, select?: string[]): void;
 
     export(): Model.State<this>;
     export <P extends Model.Fields<this>> (select: P[]): Model.State<this, P>;
-    export <S extends Model.SelectFields<this>> (select: S): Model.State<this, Selector.From<S>>;
 
     update(): PromiseLike<readonly string[] | false>;
     update(strict: true): Promise<readonly string[]>;
     update(strict: false): Promise<false>;
     update(strict: boolean): Promise<readonly string[] | false>;
 
-    update(keys: Model.Fields<this>): Thenable<readonly string[]>;
-    update(keys: Model.SelectFieldKey<this>): Thenable<readonly string[]>;
-
-    update(keys: Model.Fields<this>, callMethod: boolean): PromiseLike<readonly string[]>;
-    update(keys: Model.SelectFields<this>, callMethod: boolean): PromiseLike<readonly string[]>;
-
-    update<T>(keys: Model.Fields<this>, argument: T): PromiseLike<readonly string[]>;
-    update<T>(keys: Model.SelectFields<this>, argument: T): PromiseLike<readonly string[]>;
+    update(keys: Including<Model.Fields<this>>): Thenable<readonly string[]>;
+    update(keys: Including<Model.Fields<this>>, callMethod: boolean): PromiseLike<readonly string[]>;
+    update<T>(keys: Including<Model.Fields<this>>, argument: T): PromiseLike<readonly string[]>;
 
     /*
     Issue with self-reference, using fallback.
@@ -289,45 +249,41 @@ export abstract class Model {
     tap(): this;
 
     /** Tracks specific key of this controller within a component. */
-    tap <K extends Model.Fields<this>> (key: K, expect?: boolean): this[K];
     tap <K extends Model.Fields<this>> (key: K, expect: true): Exclude<this[K], undefined>;
+    tap <K extends Model.Fields<this>> (key: K, expect?: boolean): this[K];
+
+    tap <T> (from: (this: this, state: this) => Promise<T>, expect: true): Exclude<T, undefined>;
+    tap <T> (from: (this: this, state: this) => Promise<T>, expect?: boolean): T | undefined;
 
-    tap <T> (from: (this: this, state: this) => T, expect?: boolean): T;
     tap <T> (from: (this: this, state: this) => T, expect: true): Exclude<T, undefined>;
+    tap <T> (from: (this: this, state: this) => T, expect?: boolean): T;
     
     // Keyed
-    on <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<S, this>, squash?: false, once?: boolean): Callback;
-    on <P = Model.EventsCompat<this>> (keys: [], listener: UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
-    on <P extends Model.EventsCompat<this>> (key: P | P[], listener: UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
+    on <P = Model.EventsCompat<this>> (keys: [], listener: Model.UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
+    on <P extends Model.EventsCompat<this>> (key: P | P[], listener: Model.UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
     // Squash
-    on <S extends Model.SelectEvents<this>> (via: S, cb: (keys: Selector.From<S>[]) => void, squash: true, once?: boolean): Callback;
     on <P = Model.EventsCompat<this>> (keys: [], listener: (keys: P[]) => void, squash: true, once?: boolean): Callback;
     on <P extends Model.EventsCompat<this>> (key: P | P[], listener: (keys: P[]) => void, squash: true, once?: boolean): Callback;
     // Unknown
-    on <S extends Model.SelectEvents<this>> (via: S, cb: unknown, squash: boolean, once?: boolean): Callback;
     on (keys: [], listener: unknown, squash: boolean, once?: boolean): Callback;
     on <P extends Model.EventsCompat<this>> (key: P | P[], listener: unknown, squash: boolean, once?: boolean): Callback;
 
     // Keyed
-    once <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<S, this>, squash?: false): Callback;
-    once <P = Model.EventsCompat<this>> (keys: [], listener: UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
-    once <P extends Model.EventsCompat<this>> (key: P | P[], listener: UpdateCallback<this, P>, squash?: false): Callback;
+    once <P = Model.EventsCompat<this>> (keys: [], listener: Model.UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
+    once <P extends Model.EventsCompat<this>> (key: P | P[], listener: Model.UpdateCallback<this, P>, squash?: false): Callback;
     // Squash
-    once <S extends Model.SelectEvents<this>> (via: S, cb: (keys: Selector.From<S>[]) => void, squash: true): Callback;
     once <P = Model.EventsCompat<this>> (keys: [], listener: (keys: P[]) => void, squash: true, once?: boolean): Callback;
     once <P extends Model.EventsCompat<this>> (key: P | P[], listener: (keys: P[]) => void, squash: true): Callback;
     // Promise
-    once <S extends Model.SelectEvents<this>> (via: S): Promise<Selector.From<S>[]>;
     once <P = Model.EventsCompat<this>> (keys: [], listener: (keys: P[]) => void, squash: true, once?: boolean): Callback;
     once <P extends Model.EventsCompat<this>> (key: P | P[]): Promise<P[]>;
     // Unknown
-    once <S extends Model.SelectEvents<this>> (via: S, cb: unknown, squash: boolean): Callback;
     once (keys: [], listener: unknown, squash: boolean, once?: boolean): Callback;
     once <P extends Model.EventsCompat<this>> (key: P | P[], listener: unknown, squash: boolean): Callback;
 
-    effect(callback: (this: this, state: this) => void, select?: Model.SelectFields<this>): Callback;
-    effect(callback: (this: this, state: this) => void, select?: []): Callback;
-    effect(callback: (this: this, state: this) => void, select?: (keyof this)[]): Callback;
+    effect(callback: Model.EffectCallback<this>): Callback;
+    effect(callback: Model.EffectCallback<this>, select: []): Callback;
+    effect(callback: Model.EffectCallback<this>, select: (keyof this)[]): Callback;
 
     /**
      * **React Hook** - Attach to instance of this controller within a component.
@@ -366,7 +322,7 @@ export abstract class Model {
     static LOCAL: typeof LOCAL;
 
     /** Use symbol to access keys affected by last update. */
-    static WHY: typeof UPDATE;
+    static WHY: typeof WHY;
 
     /**
      * Creates a new instance of this controller.
@@ -413,36 +369,25 @@ export abstract class Model {
      */
     static using <T extends Class, I extends InstanceOf<T>, D extends Partial<I>> (this: T, data: D, only?: (keyof D)[]): I;
 
-    /**
-     * **React Hook** - Locate most relevant instance of this type in context.
-     */
-    static find <T extends Class>(this: T, strict: true): InstanceOf<T>;
-    static find <T extends Class>(this: T, strict?: boolean): InstanceOf<T> | undefined;
-
     /**
      * **React Hook** - Fetch most instance of this controller from context, if it exists.
      * 
-     * @param expect - If true, will throw where controller cannot be found. Otherwise, may return undefined.
+     * @param required - If false, may return undefined.
      */
-    static get <T extends Class> (this: T, expect?: boolean): InstanceOf<T> | undefined;
+    static get <T extends Class> (this: T, required?: true): InstanceOf<T>;
 
     /**
      * **React Hook** - Fetch most instance of this controller from context.
      * 
-     * @param expect - Will throw if controller cannot be found.
+     * @param required - Unless false, will throw where instance cannot be found.
      */
-    static get <T extends Class> (this: T, expect: true): InstanceOf<T>;
+    static get <T extends Class> (this: T, required: boolean): InstanceOf<T> | undefined;
 
     /**
      * **React Hook** - Fetch specific value from instance of this controller in context.
      */
     static get <T extends Class, I extends InstanceOf<T>, K extends Model.Fields<I>> (this: T, key: K): I[K];
 
-    /**
-     * **React Hook** - Fetch specific value from instance of this controller in context.
-     */
-    static get <T extends Class, I extends InstanceOf<T>, K extends Model.SelectField<I>> (this: T, key?: K): ReturnType<K>;
-    
     /** 
      * **React Hook** - Fetch and subscribe to instance of this controller within ambient component.
      */
@@ -451,17 +396,14 @@ export abstract class Model {
     /** 
      * **React Hook** - Fetch and subscribe to a value on applicable instance within ambient component.
      */
+    static tap <T extends Class, I extends InstanceOf<T>, K extends Model.Fields<I>> (this: T, key: K, expect: true): Exclude<I[K], undefined>;
     static tap <T extends Class, I extends InstanceOf<T>, K extends Model.Fields<I>> (this: T, key: K, expect?: boolean): I[K];
-    static tap <T, M extends Class, I extends InstanceOf<M>> (this: M, from: (this: I, state: I) => T, expect?: boolean): T;
 
-    /** 
-     * **React Hook** - Fetch and subscribe to a value on applicable instance within ambient component.
-     * 
-     * **(In Expect Mode)** - Will throw of value is undefined.
-     * This makes return type non-nullable and convenient to use without optional chaining.
-     */
-    static tap <T extends Class, I extends InstanceOf<T>, K extends Model.Fields<I>> (this: T, key: K, expect: true): Exclude<I[K], undefined>;
+    static tap <T, M extends Class, I extends InstanceOf<M>> (this: M, from: (this: I, state: I) => Promise<T>, expect: true): Exclude<T, undefined>;
+    static tap <T, M extends Class, I extends InstanceOf<M>> (this: M, from: (this: I, state: I) => Promise<T>, expect?: boolean): T | undefined;
+
     static tap <T, M extends Class, I extends InstanceOf<M>> (this: M, from: (this: I, state: I) => T, expect: true): Exclude<T, undefined>;
+    static tap <T, M extends Class, I extends InstanceOf<M>> (this: M, from: (this: I, state: I) => T, expect?: boolean): T;
 
     /**
      * **React Hook** - Attach to instance of this controller within ambient component.
@@ -481,21 +423,16 @@ export abstract class Model {
      */
     static tag <T extends Class, I extends InstanceOf<T>> (this: T, idFactory: (on: I) => Key | void): I;
 
-    /** 
-     * **React Hook** - Fetch and subscribe to *class itself* within a component.
-     * 
-     * This allows you to do pretty meta stuff.
-     * 
-     * Documentation TBD.
-     */
     static meta <T extends Class>(this: T): T;
 
-    /** 
-     * **React Hook** - Fetch and subscribe to value defined on class itself using selectors.
-     * 
-     * Documentation TBD.
-     */
-    static meta <T extends Class, K extends Model.SelectField<T>> (this: T, key?: K): ReturnType<K>;
+    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 | undefined;
+
+    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;
 
     /**
      * Static equivalent of `x instanceof this`.
@@ -506,16 +443,13 @@ export abstract class Model {
 }
 
 export class Singleton extends Model {
-    /** Get current instance of this singleton. Will throw if one does not exist. */
-    static is<T extends Class>(this: 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 update<T extends Class>(
-        this: T, updates: Model.Data<InstanceOf<T>>
+    static set<T extends Class>(
+        this: T, updates: Model.Compat<InstanceOf<T>>
     ): PromiseLike<string[] | false>;
 
     /** Destroy current instance of Singleton, if it exists. */

package/types/types.d.ts

@@ -1,18 +1,4 @@
-export type Key = string | symbol | number;
 export type Async<T = any> = (this: T, ...args: any[]) => Promise<any>;
 export type BunchOf<T> = { [key: string]: T };
-
-export type Class = new (...args: any[]) => any;
 export type InstanceOf<T> = T extends { prototype: infer U } ? U : never;
-export type IfApplicable<T extends {}, K> = K extends keyof T ? T[K] : undefined;
-
-export type Callback = () => void;
-export type RequestCallback = (keys: readonly string[]) => void;
-export type EffectCallback<T, A = T> = (this: T, argument: A) => Callback | Promise<any> | void;
-export type UpdateCallback<T, P> = (this: T, value: IfApplicable<T, P>, changed: P) => void;
-export type InterceptCallback<T, S = any> = (this: S, argument: T) => ((next: T) => void) | Promise<any> | void | boolean;
-
-export type RefFunction = (e: HTMLElement | null) => void;
-
-export type Recursive<T> = { [K in keyof T]: Recursive<Omit<T, K>> };
-export type Query = (select: Recursive<{}>) => void;
+export type Class = new (...args: any[]) => any;

package/types/selector.ts

@@ -1,47 +0,0 @@
-export type KeysOfType<T, ST> = {
-    [Key in keyof T]: T[Key] extends ST ? Key : never
-}[keyof T];
-
-export namespace Selector {
-  /**
-   * Shallow-recursive clone of source object.
-   * Accumulates keys by property access.
-   * 
-   * For every key:
-   * - add key to register
-   * - delete key from object
-   * - return object
-   */
-  type Object<T extends {} = {}, KS extends keyof T = never> = {
-      [K in Exclude<keyof T, KS>]: Object<T, KS | K>
-  };
-
-  type Keys<S extends Object> =
-      S extends Object<any, infer I> ? I : never;
-
-  type Values<S extends Object> =
-      S extends Object<infer T, infer I> ? T[I] : never;
-
-  export type Function<T> =
-      (selector: Object<T>) => Object<T, keyof T>;
-
-  export type From<F extends Function<any>> =
-      F extends (spy: any) => infer R ? Keys<R> : never;
-
-  export type Gets<F extends Function<any>> =
-      F extends (spy: any) => infer R ? Values<R> : never;
-
-  export type Callback<S extends Function<any>, T> =
-      (this: T, value: Gets<S>, key: From<S>) => void;
-}
-
-export namespace Select {
-    export type One<T> =
-        (arg: { [K in keyof T]: K }) => string & keyof T;
-
-    export type Key<T extends string | number | symbol> =
-        (arg: { [K in T]: K }) => string & T;
-
-    export type From<T extends One<any>> =
-        T extends (from: any) => infer R ? R : never;
-}