@expressive/mvc 1.0.0-beta.12 → 1.0.0-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressive/mvc",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.17",
   "description": "Use classes to define state in React!",
   "author": {
     "name": "Gabe Klein",
@@ -27,7 +27,7 @@
     "watch": "rollup --config --sourcemap --watch",
     "prebuild": "rm -rf lib/",
     "publish:pre": "npm version prerelease --preid=beta",
-    "preversion": "jest",
+    "preversion": "jest --coverage",
     "postversion": "npm run build; npm publish",
     "postpublish": "git push; git push --tags; rm -rf lib",
     "coverage": "jest --collectCoverage",

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export {
+    State,
     Model,
     Model as default,
     Singleton

package/types/instructions.d.ts

@@ -1,5 +1,5 @@
-import Model from '.';
-import { Async, Class, EffectCallback, InstanceOf } from './types';
+import Model, { Selector } from '.';
+import { Async, Class, InstanceOf, InterceptCallback } from './types';
 
 /**
  * Run instruction as controller sets itself up.
@@ -55,7 +55,7 @@ export function use <T extends Model> (): T | undefined;
  *
  * Note: Child will *not* be same object as one provided.
  */
-export function use <T extends BunchOf<any>> (object: T): T;
+export function use <T extends {}> (object: T): T;
 
 /**
  * Generic instruction used by `use()` and `tap()` for recursive subscription.
@@ -99,15 +99,22 @@ export function tap <T extends typeof Model> (Type: T, callback?: (instance?: In
  * @param required - Throw if instance of Type cannot be found.
  */
 export function tap <T extends Class> (Type: T, required?: boolean): InstanceOf<T>;
- 
+
 /**
- * Sets property to synchronously call effect upon update.
+ * Cause property to synchronously run effect upon update.
+ * 
+ * Callback may return an effect callback, Promise (ignored), or a boolean.
+ * 
+ * If a boolean is returned explicitly, new value will be dropped. Useful to override.
+ * 
+ * - `false` will prevent update.
+ * - `true` will emit update (unchanged).
  *
- * @param starting - Beginning value of host property.
- * @param callback - Effect-callback fired upon set of host property.
+ * @param initialValue - Beginning value of host property.
+ * @param onUpdate - Effect-callback fired upon set of host property.
  */
-export function on <T = any> (initial: undefined, callback: EffectCallback<T>): T | undefined;
-export function on <T = any> (initial: T, callback: EffectCallback<T>): T;
+export function on <T = any> (initialValue: undefined, onUpdate: InterceptCallback<T>): T | undefined;
+export function on <T = any> (initialValue: T, onUpdate: InterceptCallback<T>): T;
 
 /**
  * Creates a ref-compatible property for use with components.
@@ -117,7 +124,7 @@ export function on <T = any> (initial: T, callback: EffectCallback<T>): T;
  *
  * @param callback - Optional callback to synchronously fire when reference is first set or does update.
  */
-export function ref <T = HTMLElement> (callback?: EffectCallback<T>): Model.Ref<T>;
+export function ref <T = HTMLElement> (this: any, callback?: InterceptCallback<T>): Model.Ref<T>;
 
 /**
  * Sets an exotic method with managed ready-state. Property accepts an async function.
@@ -130,15 +137,24 @@ export function ref <T = HTMLElement> (callback?: EffectCallback<T>): Model.Ref<
  * @param action - Action to fire when resulting property is invoked.
  */
 export function act <T extends Async> (action: T): T & { active: boolean };
- 
+
 /**
- * Implement a computed value; output will be generated by provided function.
+ * Implement a computed value; output is returned by function from provided factory.
  *
- * *Alternative to using native getters; works exactly the same!*
+ * @param fn - Factory function to generate a getter to subscribe dependancies.
+ */
+export function from <R> (fn: (property: string) => (this: any, on: any) => R): R;
+
+/**
+ * Implement a computed value; output will be generated by provided function.
  *
- * @param fn - Factory function to generate value and subscribe dependancies.
+ * @param source - Source model from which computed value will be subscribed.
+ * **Note:** Currently will only support `this`.
+ * 
+ * @param fn - Compute function. Bound to a subscriber-proxy of source, returns output value.
+ * Will update automatically as accessed values change.
  */
-export function from <T, R> (fn: (this: T, on: T) => R): R;
+export function from <T, R> (source: T, fn: (this: T, on: T) => R): R;
 
 /**
  * Memoized value. Computes and stores a value returned by provided factory. 

package/types/model.d.ts

@@ -1,6 +1,5 @@
-import Dispatch from './dispatch';
 import Lifecycle from './lifecycle';
-import { Selector } from './selector';
+import { Select, Selector } from './selector';
 import { Class, InstanceOf, Key } from './types';
 
 interface PropertyDescriptor<T> {
@@ -12,6 +11,12 @@ interface PropertyDescriptor<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> {
@@ -25,7 +30,7 @@ export namespace Model {
      * Property initializer, will run upon instance creation.
      * Optional returned callback will run when once upon first access.
     */
-    type Instruction<T> = (this: Controller, key: string) =>
+    type Instruction<T> = (this: Controller, key: string, thisArg: Controller) =>
         void | GetFunction<T> | PropertyDescriptor<T>;
 
     /** Shallow replacement given all entries of Model */
@@ -96,6 +101,14 @@ export namespace 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 class Controller {
@@ -107,9 +120,7 @@ export namespace Model {
 
         select(using?: Query): string[];
 
-        sets(key: string, effect?: HandleValue): (value: any) => boolean | void;
-
-        watch(target: string | Iterable<string> | Query, handler: Function, squash?: boolean, once?: boolean): Callback;
+        setter(key: string, effect?: HandleValue): (value: any) => boolean | void;
 
         addListener(batch: BunchOf<RequestCallback>): Callback;
 
@@ -118,18 +129,16 @@ export namespace Model {
         include(cb: RequestCallback): void;
     }
 
-    type Listener = {
-        commit(): void;
-        release(): void;
-    }
-      
     export class Subscriber {
         proxy: any;
         source: any;
+        parent: Controller;
         active: boolean;
         follows: BunchOf<Callback>;
-        dependant: Set<Listener>;
-        parent: Controller;
+        dependant: Set<{
+            commit(): void;
+            release(): void;
+        }>;
 
         follow(key: string, cb?: Callback | undefined): void;
         commit(): Callback;
@@ -142,9 +151,16 @@ declare const CONTROL: unique symbol;
 declare const LOCAL: unique symbol;
 declare const STATE: unique symbol;
 
-export interface Model extends Dispatch, Lifecycle {}
+export abstract class State {
+    /** 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;
 
-export abstract class Model {
     /**
      * Circular reference to `this` controller.
      * 
@@ -204,6 +220,36 @@ export abstract class Model {
      */
     set: this;
 
+    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<string[] | false>;
+    update(strict: true): Promise<string[]>;
+    update(strict: false): Promise<false>;
+    update(strict: boolean): Promise<string[] | false>;
+
+    update(keys: Model.Fields<this>): Thenable<string[]>;
+    update(keys: Model.SelectFieldKey<this>): Thenable<string[]>;
+
+    update(keys: Model.Fields<this>, callMethod: boolean): PromiseLike<string[]>;
+    update(keys: Model.SelectFields<this>, callMethod: boolean): PromiseLike<string[]>;
+
+    update<T>(keys: Model.Fields<this>, argument: T): PromiseLike<string[]>;
+    update<T>(keys: Model.SelectFields<this>, argument: T): PromiseLike<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.
      * 
@@ -233,33 +279,6 @@ 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>;
 
-    /**
-     * **React Hook** - Attach to instance of this controller within ambient 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;
-
-     /**
-      * **React Hook** - Attach to instance of this controller within ambient component.
-      * 
-      * This method will fire lifecycle events on given controller.
-      * 
-      * @param idFactory - Will be invoked with fetched instance. Use this to register a tag as-needed.
-      */
-    tag(idFactory: (idFactory: this) => Key | void): this;
-
-    /** 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;
-
     /** Use symbol to access controller of a model. */
     static CONTROL: typeof CONTROL;
 
@@ -283,8 +302,11 @@ 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 args - Arguments passed to constructor of `this`
+     * @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, args?: ConstructorParameters<T>, callback?: (instance: InstanceOf<T>) => void): InstanceOf<T>;
 
     /**
      * **React Hook** - Create and attach an instance of this controller a react component.
@@ -292,8 +314,9 @@ export abstract class Model {
      * 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, args?: ConstructorParameters<T>, callback?: (instance: InstanceOf<T>) => void): InstanceOf<T>;
 
     /**
      * **React Hook** - Similar to `use`, will instanciate a controller bound to ambient component.
@@ -301,7 +324,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.
@@ -310,7 +333,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.
@@ -356,6 +385,61 @@ export abstract class Model {
     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.SelectField<I>> (this: T, key: K, expect: true): Exclude<ReturnType<K>, undefined>;
 
+    /**
+     * 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;
+}
+
+export interface Model extends Lifecycle {}
+export abstract class Model extends State {
+    // Keyed
+    on <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<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;
+    // 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;
+    // Unknown
+    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;
+
+    // Keyed
+    once <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<S, this>, squash?: false): 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 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 extends Model.EventsCompat<this>> (key: P | P[]): Promise<P[]>;
+    // Unknown
+    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: (this: this, state: this) => void, select?: Model.SelectFields<this>): Callback;
+    effect(callback: (this: this, state: this) => void, select?: (keyof this)[]): Callback;
+
+    /**
+     * **React Hook** - Attach to instance of this controller within ambient 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;
+
+     /**
+      * **React Hook** - Attach to instance of this controller within ambient component.
+      * 
+      * This method will fire lifecycle events on given controller.
+      * 
+      * @param idFactory - Will be invoked with fetched instance. Use this to register a tag as-needed.
+      */
+    tag(idFactory: (idFactory: this) => Key | void): this;
+
+
     /**
      * **React Hook** - Attach to instance of this controller within ambient component.
      * 
@@ -389,28 +473,20 @@ export abstract class Model {
      * Documentation TBD.
      */
     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.
@@ -29,4 +33,15 @@ export namespace Selector {
 
   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

@@ -10,5 +10,6 @@ export type Callback = () => void;
 export type RequestCallback = (keys?: 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> = (argument: T) => ((next: T) => void) | Promise<any> | void | boolean;
 
 export type RefFunction = (e: HTMLElement | null) => void;

package/types/dispatch.d.ts

@@ -1,52 +0,0 @@
-import { Model } from './model';
-import { Selector } from './selector';
-import { Callback, EffectCallback, UpdateCallback } from './types';
-
-/**
- * Observable Instance
- * 
- * Implements internal value tracking. 
- * Able to be subscribed to, per-value to know when updated.
- */
-interface Dispatch {
-  // Keyed
-  on <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<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;
-  // 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;
-  // Unknown
-  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;
-
-  // Keyed
-  once <S extends Model.SelectEvents<this>> (via: S, cb: Selector.Callback<S, this>, squash?: false): 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 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 extends Model.EventsCompat<this>> (key: P | P[]): Promise<P[]>;
-  // Unknown
-  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.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(strict: true): Promise<string[]>;
-  update(strict: false): Promise<false>;
-  update(strict?: boolean): Promise<string[] | false>;
-  update(keys: Model.Fields<this>[]): Promise<string[]>;
-  update(keys: Model.Fields<this>): Promise<string[]>;
-  update(keys: Model.SelectFields<this>): Promise<string[]>;
-}
-
-export = Dispatch;