@expressive/mvc 1.0.0-beta.3 → 1.0.0-beta.30

package/types/model.d.ts

@@ -1,11 +1,40 @@
-import React from 'react';
+import { Key } from 'react';
 
-import Controller from './controller';
 import Lifecycle from './lifecycle';
-import { Selector } from './selector';
-import { Class, InstanceOf, Key, RefFunction } from './types';
+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;
+}
+
+type Argument<T> = T extends (arg: infer U) => any ? U : never;
+
+type Thenable<T> = {
+    then(onFulfilled: (arg: T) => void): void;
+}
 
 export namespace Model {
+    /** Exotic value, actual value is contained. */
+    interface Ref<T = any> {
+        (next: T): void;
+        current: T | null;
+    }
+
+    type GetFunction<T> = (within?: Subscriber) => T;
+
+    /**
+     * 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 };
 
@@ -15,6 +44,14 @@ export namespace Model {
     /** Object containing data found in T. */
     type Entries<T, E = Model> = Pick<T, Fields<T, E>>;
 
+    /** Actual value stored in state. */
+    type Value<R> = R extends Ref<infer T> ? T : R;
+
+    /** Values from current state of given controller. */
+    type State<T, K extends keyof T = Fields<T, 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>>;
 
@@ -65,11 +102,81 @@ export namespace Model {
     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 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) =>
+            RequestCallback | undefined;
+    }
+
+    export class Controller {
+        state: BunchOf<any>;
+        subject: {};
+        waiting: Set<RequestCallback>;
+
+        /** Add property to managed state. */
+        manage(key: string, initial: any, effect?: HandleValue): void;
+
+        select(using?: Query): string[];
+
+        setter(key: string, effect?: HandleValue): (value: any) => boolean | void;
+
+        addListener(listener: Controller.Listen): Callback;
+
+        update(key: string, value?: any): void;
+    }
+
+    export class Subscriber {
+        proxy: any;
+        source: any;
+        parent: Controller;
+        active: boolean;
+        listen: Controller.Listen;
+        dependant: Set<{
+            commit(): void;
+            release(): void;
+        }>;
+
+        follow(key: string, cb?: RequestCallback | undefined): void;
+        commit(): Callback;
+        release(): Callback;
+        onUpdate(): void;
+    }
 }
 
-export interface Model extends Controller, Lifecycle {}
+declare const CONTROL: unique symbol;
+declare const UPDATE: unique symbol;
+declare const LOCAL: unique symbol;
+declare const STATE: unique symbol;
 
+export interface Model extends Lifecycle {}
 export abstract class Model {
+    /** Controller for this instance. */
+    [CONTROL]: Model.Controller;
+
+    /** Current state of this instance. */
+    [STATE]?: Model.State<this>;
+
+    /** Current subscriber (if present) while used in a live context (e.g. hook or effect). */
+    [LOCAL]?: Model.Subscriber;
+
+    /**
+     * Last update causing a refresh to subscribers.
+     * 
+     * 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[];
+
     /**
      * Circular reference to `this` controller.
      * 
@@ -129,15 +236,35 @@ export abstract class Model {
      */
     set: this;
 
-    /**
-     * Plug-n-Play references for properties of this controller.
-     * 
-     * Matched ref-functions automatically bind between receiving element and live value of field.
-     * 
-     * For `<input type="text" />` this is a two-way binding.
-     * User input is captured and part of controller's state/event stream.
-     */
-    bind: Model.Overlay<this, RefFunction>;
+    import <O extends Model.Data<this>> (via: O, select?: string[] | Model.SelectFields<this>): 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[]>;
+
+    /*
+    Issue with self-reference, using fallback.
+    
+    update(keys: Model.Typeof<this, () => void>, callMethod: boolean): Thenable<string[]>;
+    update(keys: Model.SelectTypeof<this, () => void>, callMethod: boolean): Thenable<string[]>;
+
+    update<T>(keys: Model.Typeof<this, (arg: T) => void>, argument: T): Thenable<string[]>;
+    update<T>(keys: Model.SelectTypeof<this, (arg: T) => void>, argument: T): Thenable<string[]>;
+    */
 
     /** 
      * Mark this instance for garbage-collection and send `willDestroy` event to all listeners.
@@ -167,24 +294,79 @@ export abstract class Model {
 
     tap <K extends Model.SelectField<this>> (key: K, expect?: boolean): ReturnType<K>;
     tap <K extends Model.SelectField<this>> (key: K, expect: true): Exclude<ReturnType<K>, undefined>;
+    
+    // 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;
+    // 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;
+    // 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;
 
     /**
-     * **React Hook** - Attach to instance of this controller within ambient component.
+     * **React Hook** - Attach to instance of this controller within a component.
      * 
      * This method will fire lifecycle events on given controller.
      * 
      * @param id - Argument passed to controller-lifecycle methods. Use to identify the consumer.
      */
-     tag(id?: Key): this;
+    tag(id?: any): this;
 
      /**
-      * **React Hook** - Attach to instance of this controller within ambient component.
+      * **React Hook** - Subscribe to instance of controller within a component.
       * 
-      * This method will fire lifecycle events on given controller.
+      * This method will fire lifecycle events on given controller (as element)..
       * 
       * @param idFactory - Will be invoked with fetched instance. Use this to register a tag as-needed.
       */
-     tag(idFactory: (idFactory: this) => Key | void): this;
+    tag(idFactory: (idFactory: this) => any): this;
+
+    /**
+     * **React Hook** - Subscribe to instance of controller within a component.
+     * 
+     * This method will fire lifecycle events on given controller (as component).
+     * 
+     * @param callback - Run once before subscription begins.
+     */
+    use(callback?: (instance: this) => void): this;
+
+    /** Use symbol to access controller of a model. */
+    static CONTROL: typeof CONTROL;
+
+    /** Use symbol to access current state of a model. */
+    static STATE: typeof STATE;
+
+    /** Use symbol to access current subscriber of a model in a live context (e.g. hook or effect). */
+    static LOCAL: typeof LOCAL;
+
+    /** Use symbol to access keys affected by last update. */
+    static WHY: typeof UPDATE;
 
     /**
      * Creates a new instance of this controller.
@@ -200,17 +382,19 @@ export abstract class Model {
      * 
      * Differs from `use()` in lacking subscription and lifecycle events.
      * Much more efficient if you don't need hook-based features.
+     * 
+     * @param callback - Run after creation of instance.
      */
-    static new <T extends Class> (this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
+    static new <T extends Class> (this: T, callback?: (instance: InstanceOf<T>) => void): InstanceOf<T>;
 
     /**
      * **React Hook** - Create and attach an instance of this controller a react component.
      * 
      * Note: Model will be destroyed when ambient component unmounts!
      * 
-     * @param args - Arguments passed to constructor of `this`
+     * @param callback - Run after creation of instance.
      */
-    static use <T extends Class> (this: T, ...args: ConstructorParameters<T>): InstanceOf<T>;
+    static use <T extends Class> (this: T, callback?: (instance: InstanceOf<T>) => void): InstanceOf<T>;
 
     /**
      * **React Hook** - Similar to `use`, will instanciate a controller bound to ambient component.
@@ -218,7 +402,7 @@ export abstract class Model {
      * 
      * @param data - Data to be applied to controller upon creation.
      */
-    static uses <T extends Class, I extends InstanceOf<T>, D extends Partial<I>> (this: T, data: D): I;
+    static uses <T extends Class, I extends InstanceOf<T>, D extends Partial<I>> (this: T, data: D, only?: (keyof D)[]): I;
 
     /**
      * **React Hook** - Similar to `uses`, will instanciate a controller includive of given data.
@@ -227,7 +411,13 @@ export abstract class Model {
      * 
      * @param data - Data to be observed by controller.
      */
-    static using <T extends Class, I extends InstanceOf<T>, D extends Partial<I>> (this: T, data: D): I;
+    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.
@@ -298,7 +488,7 @@ export abstract class Model {
      * 
      * Documentation TBD.
      */
-    static meta <T extends Class>(this: T): T & Controller;
+    static meta <T extends Class>(this: T): T;
 
     /** 
      * **React Hook** - Fetch and subscribe to value defined on class itself using selectors.
@@ -307,25 +497,27 @@ export abstract class Model {
      */
     static meta <T extends Class, K extends Model.SelectField<T>> (this: T, key?: K): ReturnType<K>;
 
-    /**
-     * **React Hook** - Locate most relevant instance of this type in context.
-     */
-    static find <T extends Class>(this: T): InstanceOf<T>;
-
     /**
      * Static equivalent of `x instanceof this`.
      * 
      * Will determine if provided class is a subtype of this one. 
      */
     static isTypeof <T extends Class>(this: T, subject: any): subject is T;
-
-    /** 
-     * Retreives parent inherited by this class, unless it is base `Model`.
-     */
-    static inherits: typeof Model | undefined;
 }
 
 export class Singleton extends Model {
-    /** Current instance of this controller accessable anywhere. */
-    static current?: Singleton;
+    /** 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>>
+    ): PromiseLike<string[] | false>;
+
+    /** Destroy current instance of Singleton, if it exists. */
+    static reset(): void;
 }

package/types/selector.ts

@@ -1,3 +1,7 @@
+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.
@@ -26,4 +30,18 @@ export namespace Selector {
 
   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;
 }

package/types/types.d.ts

@@ -1,5 +1,5 @@
 export type Key = string | symbol | number;
-export type Async = (...args: any[]) => Promise<any>;
+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;
@@ -7,8 +7,12 @@ 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?: string[]) => 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 RefFunction = (e: HTMLElement | null) => void;
+
+export type Recursive<T> = { [K in keyof T]: Recursive<Omit<T, K>> };
+export type Query = (select: Recursive<{}>) => void;

package/types/controller.d.ts

@@ -1,56 +0,0 @@
-import { Model } from './model';
-import { Selector } from './selector';
-import { Callback, EffectCallback, UpdateCallback } from './types';
-
-type CallbackFor<S extends Selector.Function<any>, T> =
-  (this: T, value: Selector.Gets<S>, key: Selector.From<S>) => void;
-
-/**
- * Observable Instance
- * 
- * Implements internal value tracking. 
- * Able to be subscribed to, per-value to know when updated.
- */
-interface Dispatch {
-  // Explicit all
-  on <S extends Model.SelectEvents<this>> (via: S, cb: CallbackFor<S, this>, squash?: false, once?: boolean): Callback;
-  on <P extends Model.EventsCompat<this>> (key: P | P[], listener: UpdateCallback<this, P>, squash?: false, once?: boolean): Callback;
-
-  once <S extends Model.SelectEvents<this>> (via: S, cb: CallbackFor<S, this>, squash?: false): Callback;
-  once <P extends Model.EventsCompat<this>> (key: P | P[], listener: UpdateCallback<this, P>, squash?: false): Callback;
-
-  // Explicit squash
-  on <S extends Model.SelectEvents<this>> (via: S, cb: (keys: Selector.From<S>[]) => void, squash: true, once?: boolean): Callback;
-  on <P extends Model.EventsCompat<this>> (key: P | P[], listener: (keys: P[]) => void, squash: true, once?: boolean): Callback;
-
-  once <S extends Model.SelectEvents<this>> (via: S, cb: (keys: Selector.From<S>[]) => void, squash: true): Callback;
-  once <P extends Model.EventsCompat<this>> (key: P | P[], listener: (keys: P[]) => void, squash: true): Callback;
-
-  // Implicit squash
-  once <S extends Model.SelectEvents<this>> (via: S): Promise<Selector.From<S>[]>;
-  once <P extends Model.EventsCompat<this>> (key: P | P[]): Promise<P[]>;
-
-  // Unknown squash
-  on <S extends Model.SelectEvents<this>> (via: S, cb: unknown, squash: boolean, once?: boolean): Callback;
-  on <P extends Model.EventsCompat<this>> (key: P | P[], listener: unknown, squash: boolean, once?: boolean): Callback;
-
-  once <S extends Model.SelectEvents<this>> (via: S, cb: unknown, squash: boolean): Callback;
-  once <P extends Model.EventsCompat<this>> (key: P | P[], listener: unknown, squash: boolean): Callback;
-
-  effect(callback: EffectCallback<this>, select?: Model.SelectFields<this>): Callback;
-  effect(callback: EffectCallback<this>, select?: (keyof this)[]): Callback;
-
-  import <O extends Model.Data<this>> (via: O, select?: string[] | Model.SelectFields<this>): void;
-
-  export(): Model.Entries<this>;
-  export <P extends Model.Fields<this>> (select: P[]): Pick<this, P>;
-  export <S extends Model.SelectFields<this>> (select: S): Pick<this, Selector.From<S>>;
-
-  update(keys: Model.SelectFields<this>): void;
-  update(keys: Model.Fields<this>[]): void;
-
-  requestUpdate(strict?: boolean): Promise<string[] | false>;
-  requestUpdate(cb: (keys: string[]) => void): void;
-}
-
-export = Dispatch;

package/types/react.d.ts

@@ -1,46 +0,0 @@
-import { ReactElement } from "react";
-import { Model } from "./model"
-import { Class } from "./types";
-
-type ComponentOutput = ReactElement<any, any> | null;
-
-type ProviderForProps<E> = E extends Class
-    ? ({ of: E, children?: React.ReactNode } & Model.Data<InstanceType<E>>)
-    | ({ of: E, children?: (instance: InstanceType<E>) => React.ReactNode } & Model.Data<InstanceType<E>>)
-    : ({ of: E, children?: React.ReactNode } & Model.Data<E>);
-
-type ConsumerProps<E extends Class> = 
-    | {
-        /** Type of controller to fetch from context. */
-        of: 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 of controller to fetch from context. */
-        of: E;
-        /** Getter function. Is called on every natural render of this component. */
-        get: (value: InstanceType<E> | undefined) => void;
-    }
-    | {
-        /** Type of controller to fetch from context. */
-        of: 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>) => ComponentOutput;
-    }
-
-// type ProvideCollection = Array<Model | typeof Model> | BunchOf<Model | typeof Model>;
-// declare function Provider(props: ProviderOfProps): ComponentOutput;
-
-declare function Provider<T>(props: ProviderForProps<T>): ComponentOutput;
-declare function Consumer<T extends Class>(props: ConsumerProps<T>): ComponentOutput;
-
-export { Consumer, Provider };