@expressive/mvc 1.0.0-beta.19 → 1.0.0-beta.22

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@expressive/mvc",
-  "version": "1.0.0-beta.19",
   "description": "Use classes to define state in React!",
+  "version": "1.0.0-beta.22",
   "author": {
     "name": "Gabe Klein",
     "email": "gabe@termtm.com",
@@ -14,7 +14,7 @@
   },
   "keywords": [
     "react",
-    "hooks"
+    "mvc"
   ],
   "main": "lib/index.js",
   "types": "types/index.d.ts",
@@ -24,10 +24,9 @@
   ],
   "scripts": {
     "build": "rollup --config",
-    "watch": "rollup --config --sourcemap --watch",
-    "prebuild": "rm -rf lib/",
-    "test": "jest --watchAll",
-    "coverage": "jest --collectCoverage"
+    "watch": "jest --watchAll",
+    "test": "jest --collectCoverage",
+    "prebuild": "rm -rf lib/"
   },
   "peerDependencies": {
     "react": ">=17.0.2"
@@ -44,8 +43,14 @@
     "react-test-renderer": "^17.0.2",
     "rollup": "^2.52.2",
     "rollup-plugin-typescript2": "^0.30.0",
+    "semantic-release": "^18.0.1",
     "ts-jest": "^27.0.3",
     "tslib": "^2.3.0",
     "typescript": "typescript@>=3.8 <5.0"
+  },
+  "release": {
+    "branches": [
+      { "name": "beta", "prerelease": true }
+    ]
   }
 }

package/types/index.d.ts

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

package/types/instructions.d.ts

@@ -1,11 +1,11 @@
-import Model, { Selector } from '.';
+import Model from '.';
 import { Async, Class, InstanceOf, InterceptCallback } from './types';
 
 /**
  * Run instruction as controller sets itself up.
  * This will specialize the behavior of a given property.
  **/
-export function set <T = any> (instruction: Model.Instruction<T>, name?: string): T;
+export function apply <T = any> (instruction: Model.Instruction<T>, name?: string): T;
 
 /**
  * Creates a new child-instance of specified controller.
@@ -116,15 +116,28 @@ export function tap <T extends Class> (Type: T, required?: boolean): InstanceOf<
 export function on <T = any> (initialValue: undefined, onUpdate: InterceptCallback<T>): T | undefined;
 export function on <T = any> (initialValue: T, onUpdate: InterceptCallback<T>): T;
 
+/** Object with references to all managed values of `T`. */
+export type Refs <T extends Model> = { [P in Model.Fields<T>]: Model.Ref<T[P]> };
+
 /**
- * Creates a ref-compatible property for use with components.
+ * Creates an object with references to all managed values.
+ * Each property will set value in state when invoked.
+ *
+ * *Properties are simultaneously a ref-function and ref-object, use as needed.*
+ *
+ * @param target - Source model from which to reference values.
+ */
+export function ref <T extends Model> (target: T): Refs<T>;
+
+/**
+ * Creates a ref-compatible property.
  * Will persist value, and updates to this are made part of controller event-stream.
  *
  * *Output is simultaneously a ref-function and ref-object, use as needed.*
  *
  * @param callback - Optional callback to synchronously fire when reference is first set or does update.
  */
-export function ref <T = HTMLElement> (this: any, callback?: InterceptCallback<T>): Model.Ref<T>;
+export function ref <T = HTMLElement> (callback?: InterceptCallback<T>): Model.Ref<T>;
 
 /**
  * Sets an exotic method with managed ready-state. Property accepts an async function.
@@ -141,29 +154,29 @@ export function act <T extends Async> (action: T): T & { active: boolean };
 /**
  * Implement a computed value; output is returned by function from provided factory.
  *
- * @param fn - Factory function to generate a getter to subscribe dependancies.
+ * @param compute - Factory function to generate a getter to subscribe dependancies.
  */
-export function from <R> (fn: (property: string) => (this: any, state: any) => R): R;
+export function from <R> (compute: (property: string) => (this: any, state: any) => R): R;
 
 /**
  * Implement a computed value; output will be generated by provided function.
  *
  * @param source - Source Model to find and subscribe to, for input.
  * 
- * @param fn - Compute function. Bound to a subscriber-proxy of source, returns output value.
- * Will update automatically as accessed values change.
+ * @param compute - Compute function. Bound to a subscriber-proxy of source, returns output value.
+ * Will update automatically as input values change.
  */
-export function from <T extends Class, R> (source: T, fn: (this: InstanceOf<T>, on: InstanceOf<T>) => R): R;
+export function from <T extends Class, R> (source: T, compute: (this: InstanceOf<T>, on: InstanceOf<T>) => R): R;
 
 /**
  * Implement a computed value; output will be generated by provided function.
  *
- * @param source - Source model from which computed value will be subscribed.
+ * @param source - Source model from which computed value will be a subscriber.
  * 
- * @param fn - Compute function. Bound to a subscriber-proxy of source, returns output value.
- * Will update automatically as accessed values change.
+ * @param compute - Compute function. Bound to a subscriber-proxy of source, returns output value.
+ * Will update automatically as input values change.
  */
-export function from <T, R> (source: T, fn: (this: T, on: T) => R): R;
+export function from <T, R> (source: T, compute: (this: T, on: T) => R): R;
 
 /**
  * Memoized value. Computes and stores a value returned by provided factory. 
@@ -179,4 +192,31 @@ export function memo <T> (compute: () => T, lazy?: boolean): T;
  *
  * @param value - starting value of property.
  */
-export function lazy <T> (value?: T): T;
+export function lazy <T> (value?: T): T;
+
+/**
+ * Suspend during the execution of given function to obtain value.
+ * 
+ * @param waitFor - Async function to suspend for.
+ */
+export function pending (waitFor: () => Promise<void>): undefined;
+export function pending <T> (waitFor: () => Promise<T>): T;
+
+/**
+ * Suspend for a computed value, returned by syncronous function.
+ *
+ * If accessed while computing to undefined, will throw a promise. Function is subscribed
+ * and will re-evaluate anytime used properties change. Once function returns any value,
+ * outstanding promises resolve and are not thrown on subsequent access of this property.
+ * 
+ * Similar to `from`, compute function will only run when inputs change and not upon access.
+ *
+ * This behavior is recursive. If return value _becomes_ undefined, property
+ * access will throw Promises again, awaiting its next value.
+ *
+ * @param source - Source object, from which computed value will be a subscriber.
+ *
+ * @param compute - Compute function returns output value. Bound to a subscriber of source.
+ * Will re-run automatically as input values change.
+ */
+ export function pending <T, R> (source: T, compute: (this: T, on: T) => R): Exclude<R, undefined>;

package/types/model.d.ts

@@ -1,6 +1,8 @@
+import { Key } from 'react';
+
 import Lifecycle from './lifecycle';
 import { Select, Selector } from './selector';
-import { Class, InstanceOf, Key } from './types';
+import { BunchOf, Callback, Class, InstanceOf, Query, RequestCallback, UpdateCallback } from './types';
 
 interface PropertyDescriptor<T> {
     configurable?: boolean;
@@ -151,7 +153,8 @@ declare const CONTROL: unique symbol;
 declare const LOCAL: unique symbol;
 declare const STATE: unique symbol;
 
-export abstract class State {
+export interface Model extends Lifecycle {}
+export abstract class Model {
     /** Controller for this instance. */
     [CONTROL]: Model.Controller;
 
@@ -278,6 +281,50 @@ export abstract class State {
 
     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 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?: any): 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) => any): this;
 
     /** Use symbol to access controller of a model. */
     static CONTROL: typeof CONTROL;
@@ -385,61 +432,6 @@ export abstract class State {
     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.
      * 
@@ -473,6 +465,13 @@ export abstract class Model extends State {
      * Documentation TBD.
      */
     static meta <T extends Class, K extends Model.SelectField<T>> (this: T, key?: K): ReturnType<K>;
+
+    /**
+     * 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 class Singleton extends Model {

package/types/types.d.ts

@@ -12,4 +12,7 @@ export type EffectCallback<T, A = T> = (this: T, argument: A) => Callback | Prom
 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;
+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;