@expressive/mvc 1.0.0-beta.2 → 1.0.0-beta.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressive/mvc",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.23",
   "description": "Use classes to define state in React!",
   "author": {
     "name": "Gabe Klein",
@@ -14,7 +14,7 @@
   },
   "keywords": [
     "react",
-    "hooks"
+    "mvc"
   ],
   "main": "lib/index.js",
   "types": "types/index.d.ts",
@@ -24,13 +24,9 @@
   ],
   "scripts": {
     "build": "rollup --config",
-    "watch": "rollup --config --sourcemap --watch",
-    "prebuild": "rm -rf lib/",
-    "publish:pre": "npm version prerelease --preid=beta",
-    "preversion": "jest",
-    "postversion": "npm run build; npm publish",
-    "postpublish": "git push; git push --tags; rm -rf lib",
-    "test": "jest --watchAll"
+    "watch": "jest --watchAll",
+    "test": "jest --collectCoverage",
+    "prebuild": "rm -rf lib/"
   },
   "peerDependencies": {
     "react": ">=17.0.2"
@@ -47,8 +43,17 @@
     "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/context.d.ts

@@ -0,0 +1,57 @@
+import { Consumer, ReactElement, ReactNode } from "react";
+import { Model } from "./model"
+import { Class } from "./types";
+
+export namespace Provider {
+    type Item = Model | typeof Model;
+    type Collection<T extends Item> = T[] | { [key: string]: T };
+    type Existent<E> = E extends Class ? InstanceType<E> : E extends Model ? E : never;
+    
+    type NormalProps<E, I = Existent<E>> =
+        & { of: E, children: ReactNode | ((instance: I) => ReactNode) }
+        & Model.Data<I>;
+
+    // FIX: This fails to exclude properties with same key but different type.
+    type MultipleProps<T extends Item> =
+        & { of: Collection<T>, children?: ReactNode | (() => ReactNode) }
+        & Model.Data<Existent<T>>;
+
+    type Props<T extends Item> = MultipleProps<T> | NormalProps<T>;
+}
+
+export function Provider<T extends Provider.Item>(props: Provider.Props<T>): ReactElement<typeof props>;
+
+export namespace Consumer {
+    type HasProps<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 GetProps<E extends Class> = {
+        /** 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 RenderProps<E extends Class> = {
+        /** 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>) => ReactElement<any, any> | null;
+    }
+
+    type Props<T extends Class> = HasProps<T> | GetProps<T> | RenderProps<T>
+}
+
+export function Consumer<T extends Class>(props: Consumer.Props<T>): null;

package/types/index.d.ts

@@ -4,23 +4,6 @@ export {
     Singleton
 } from './model';
 
-export {
-    Consumer,
-    Provider
-} from './react';
-
-export {
-    setChild as use,
-    setParent as parent,
-    setPeer as tap,
-    setEffect as on,
-    setReference as ref,
-    setAction as act,
-    setComputed as from,
-    setMemo as memo,
-    setIgnored as lazy
-} from "./instructions";
-
-export {
-    Selector
-} from './selector'
+export * from './context';
+export * from './instructions';
+export * from './selector';

package/types/instructions.d.ts

@@ -1,101 +1,228 @@
 import Model from '.';
-import { Async, Class, EffectCallback, InstanceOf } from './types';
-
-declare namespace Directives {
-  /**
-   * Creates a new child-instance of specified controller.
-   * 
-   * @param Peer - Type of Model to create and apply to host property.
-   * @param callback - Fired after controller is created and ready for use.
-   */
-  export function setChild <T extends typeof Model> (Peer: T, callback?: (i: InstanceOf<T>) => void): InstanceOf<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 Expects - Type of controller compatible with this class. 
-   * @param required - Throw if controller is created independantly.
-   */
-  export function setParent <T extends typeof Model> (Expects: T, required: true): InstanceOf<T>;
-  export function setParent <T extends typeof Model> (Expects: T, required?: false): InstanceOf<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.
-   */
-  export function setPeer <T extends Class> (Type: T, required?: boolean): InstanceOf<T>;
-  
-  /**
-   * Sets property to synchronously call an effect upon update (much like a setter).
-   * 
-   * **Note:** Use generic-type to specifiy property signature. 
-   * Value will always start off as undefined. 
-   * 
-   * @param callback - Effect-callback fired upon update of host property.
-   */
-  export function setEffect <T = any> (callback: EffectCallback<T>): T | undefined;
-
-  /**
-   * Sets property to synchronously call effect upon update.
-   * 
-   * @param starting - Beginning value of host property.
-   * @param callback - Effect-callback fired upon set of host property.
-   */
-  export function setEffect <T = any> (starting: T, callback: EffectCallback<T>): T;
-  
-  /**
-   * Creates a ref-compatible property for use with components.
-   * 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 setReference <T = HTMLElement> (callback?: EffectCallback<T>): ((next: T) => void) & { current: T | null };
-  
-  /**
-   * Sets an exotic method with managed ready-state. Property accepts an async function.
-   * 
-   * When an act-method is invoked, its `active` property to true for duration of call.
-   * This is emitted as an update to property, both when called and after returns (or throws).
-   * 
-   * **Note:** Subsequent calls will immediately throw if one is still pending.
-   * 
-   * @param action - Action to fire when resulting property is invoked.
-   */
-  export function setAction <T extends Async>(action: T): T & { active: boolean };
-  
-  /**
-   * Implement a computed value; output will be generated by provided function.
-   * 
-   * *Alternative to using native getters; works exactly the same!*
-   * 
-   * @param fn - Factory function to generate value and subscribe dependancies.
-   */
-  export function setComputed <T, R>(fn: (this: T, on: T) => R): R;
-
-  /**
-   * Memoized value. Computes and stores a value returned by provided factory. 
-   * Equivalent to a getter, sans the automatic updates.
-   * 
-   * @param compute - Factory for memoized value.
-   * @param lazy - Wait until accessed to introduce value.
-   */
-  export function setMemo <T> (compute: () => T, lazy?: boolean): T;
-  
-  /**
-   * Flag property as not to be tracked. Useful if changes often with no real-time impact.
-   * 
-   * @param value - starting value of property.
-   */
-  export function setIgnored <T> (value?: T): T;
-}
-
-export = Directives;
+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 apply <T = any> (instruction: Model.Instruction<T>, name?: string): T;
+
+/**
+ * Creates a new child-instance of specified controller.
+ *
+ * @param Peer - Type of Model to create and apply to host property.
+ * @param callback - Fired after controller is created and ready for use.
+ */
+export function use <T extends Class> (Peer: T, callback: (i?: InstanceOf<T>) => void): InstanceOf<T> | undefined;
+
+/**
+ * Creates a new child-instance of specified controller.
+ *
+ * @param Peer - Type of Model to create and apply to host property.
+ * @param required - Property should be non-nullable, will throw if value is set to undefined.
+ */
+export function use <T extends Class> (Peer: T, required: false): InstanceOf<T> | undefined;
+export function use <T extends Class> (Peer: T, required?: true): InstanceOf<T>;
+
+/**
+ * Creates a new child-instance of specified controller.
+ *
+ * @param factory - Generate model for use.
+ * @param callback - Fired after controller is created and ready for use.
+ */
+export function use <T extends Model | undefined> (factory: () => T, callback?: (i: T) => void): T;
+
+/**
+ * Create a child-instance relationship with provided model.
+ *
+ * Note: If `peer` is not already initialized before parent is
+ * (created with `new` as opposed to create method), that model will
+ * attach this via `parent()` instruction. It will not howerver, if
+ * already active.
+ *
+ * @param factory - Instance of model to attach.
+ * @param callback - Fired after controller is attached.
+ */
+export function use <T extends Model> (peer: T, callback?: (i: T) => void): T;
+
+/**
+ * Create a placeholder for specified Model type.
+ */
+export function use <T extends Model> (): T | undefined;
+
+/**
+ * Generate a child controller from specified object. Object's values are be trackable, as would be for a full-model.
+ *
+ * Note: Child will *not* be same object as one provided.
+ */
+export function use <T extends {}> (object: T): T;
+
+/**
+ * Generic instruction used by `use()` and `tap()` for recursive subscription.
+ *
+ * @param from - Instruction body is run upon parent create. Return function to fetch current value of field.
+ */
+export function child <T extends Model> (from: (this: Model.Controller, key: string) => () => T | undefined): 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 Expects - Type of controller compatible with this class. 
+ * @param required - Throw if controller is created independantly.
+ */
+export function parent <T extends typeof Model> (Expects: T, required: true): InstanceOf<T>;
+export function parent <T extends typeof Model> (Expects: T, required?: false): InstanceOf<T> | undefined;
+
+/**
+ * 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.
+ */
+export function tap <T extends typeof Model> (Type: T, callback?: (instance?: InstanceOf<T>) => void | true): InstanceOf<T>;
+export function tap <T extends typeof Model> (Type: T, callback?: (instance?: InstanceOf<T>) => void | false): InstanceOf<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.
+ */
+export function tap <T extends Class> (Type: T, required?: boolean): InstanceOf<T>;
+
+/**
+ * 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 initialValue - Beginning value of host property.
+ * @param onUpdate - Effect-callback fired upon set of host property.
+ */
+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 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> (callback?: InterceptCallback<T>): Model.Ref<T>;
+
+/**
+ * Sets an exotic method with managed ready-state. Property accepts an async function.
+ *
+ * When an act-method is invoked, its `active` property to true for duration of call.
+ * This is emitted as an update to property, both when called and after returns (or throws).
+ *
+ * **Note:** Subsequent calls will immediately throw if one is still pending.
+ *
+ * @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 is returned by function from provided factory.
+ *
+ * @param compute - Factory function to generate a getter to subscribe dependancies.
+ */
+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 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, 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 a subscriber.
+ * 
+ * @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, compute: (this: T, on: T) => R): R;
+
+/**
+ * Memoized value. Computes and stores a value returned by provided factory. 
+ * Equivalent to a getter, sans the automatic updates.
+ *
+ * @param compute - Factory for memoized value.
+ * @param lazy - Wait until accessed to introduce value.
+ */
+export function memo <T> (compute: () => T, lazy?: boolean): T;
+ 
+/**
+ * Flag property as not to be tracked. Useful if changes often with no real-time impact.
+ *
+ * @param value - starting value of property.
+ */
+export function lazy <T> (value?: T): T;
+
+/**
+ * Pending value. Will suspend unless value is defined,
+ * suspense resolves when a value is aquired. 
+ */
+export function pending <T = boolean> (): Exclude<T, undefined>;
+
+/**
+ * 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>;