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

package/types/instructions.d.ts

@@ -1,5 +1,5 @@
 import Model from '.';
-import { Async, Class, InstanceOf, InterceptCallback } from './types';
+import { Async, Class, InstanceOf } from './types';
 
 /**
  * Run instruction as controller sets itself up.
@@ -15,57 +15,22 @@ export function use <T extends Model> (): T | undefined;
 /**
  * Create a new child instance of model.
  */
-export function use <T extends Class> (Type: T): InstanceOf<T>;
-
-/**
- * Create a new child-instance of specified controller, in readonly mode.
- * Will prevent assignment of new value.
- * 
- * **Note:** This is only enforced at runtime. Use
- * [`readonly`](https://www.typescriptlang.org/docs/handbook/2/classes.html#readonly), if writing in typescript.
- */
-export function use <T extends Class> (Type: T, readonly: true): InstanceOf<T>;
-export function use <T extends Model> (from: () => T, readonly: true): T;
-
-/**
- * Create a new child-instance of specified controller, in optional mode.
- * Will allow assignment of undefined, and likewise should be checked before usage.
- */
-export function use <T extends Class> (Type: T, required: false): InstanceOf<T> | undefined;
-export function use <T extends Model> (from: () => T | undefined, required: false): T | undefined;
-
-/**
- * Create a new child-instance of specified controller.
- * 
- * By default, property is non-nullable. If callback returns `true` the first time, will be in readonly mode.
- * If callback returns false, property may also be set to undefined, as needed.
- */
-export function use <T extends Class> (Type: T, callback: (i: InstanceOf<T>) => true): InstanceOf<T>;
-export function use <T extends Class> (Type: T, callback: (i: InstanceOf<T>) => false): InstanceOf<T> | undefined;
-export function use <T extends Class> (Type: T, callback: (i: InstanceOf<T>) => void): InstanceOf<T>;
+export function use <T extends Class> (Type: T, callback?: (i: InstanceOf<T>) => void): InstanceOf<T>;
 
 /**
  * Create a new child-instance from factory function.
  */
-export function use <T extends Model> (from: () => T): T;
-export function use <T extends Model> (from: () => T, callback: (i: T) => true): T;
-export function use <T extends Model> (from: () => T | undefined, callback: (i: T) => false): T | undefined;
-export function use <T extends Model> (from: () => T, callback: (i: T) => void): T;
+export function use <T extends Model> (from: () => T, callback?: (i: T) => void): T;
 
 /**
- * Createa child-instance relationship with provided model.
+ * Create 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, if
  * already active.
  */
-export function use <T extends Model> (peer: T): T;
-export function use <T extends Model> (peer: T, readonly: true): T;
-export function use <T extends Model> (peer: T, required: false): T | undefined;
-export function use <T extends Model> (peer: T, callback: (i: T) => true): T;
-export function use <T extends Model> (peer: T, callback: (i: T) => false): T | undefined;
-export function use <T extends Model> (peer: T, callback: (i: T) => void): T;
+export function use <T extends Model> (peer: T, callback?: (i: T) => void): T;
 
 /**
  * Generate a child controller from specified object. Object's values are be trackable, as would be for a full-model.
@@ -74,12 +39,19 @@ export function use <T extends Model> (peer: T, callback: (i: T) => void): T;
  */
 export function use <T extends {}> (object: T): T;
 
+export namespace child {
+  type Instruction<T> = (this: Model.Controller, key: string) => {
+    get: () => T | undefined,
+    set?: (value: T | undefined) => void
+  }
+}
+
 /**
  * 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;
+export function child <T extends Model> (from: child.Instruction<T>): T;
  
 /**
  * Fetches and assigns the controller which spawned this host.
@@ -117,6 +89,11 @@ export function tap <T extends typeof Model> (Type: T, callback?: (instance?: In
  */
 export function tap <T extends Class> (Type: T, required?: boolean): InstanceOf<T>;
 
+export namespace on {
+  type Callback<T, S = any> = (this: S, argument: T) =>
+    ((next: T) => void) | Promise<any> | void | boolean;
+}
+
 /**
  * Cause property to synchronously run effect upon update.
  * 
@@ -129,15 +106,22 @@ export function tap <T extends Class> (Type: T, required?: boolean): InstanceOf<
  *
  * @param initialValue - Beginning value of host property.
  * @param onUpdate - Effect-callback fired upon set of host property.
+ * 
+ * @deprecated will be removed in favor of `set`
  */
-export function on <T> (initialValue: undefined, onUpdate: InterceptCallback<T>): T | undefined;
-export function on <T> (initialValue: T, onUpdate: InterceptCallback<T>): T;
-export function on <T, S> (initialValue: undefined, onUpdate: InterceptCallback<T, S>): T | undefined;
-export function on <T, S> (initialValue: T, onUpdate: InterceptCallback<T, S>): T;
+export function on <T> (initialValue: undefined, onUpdate: on.Callback<T>): T | undefined;
+export function on <T> (initialValue: T, onUpdate: on.Callback<T>): T;
+export function on <T, S> (initialValue: undefined, onUpdate: on.Callback<T, S>): T | undefined;
+export function on <T, S> (initialValue: T, onUpdate: on.Callback<T, S>): 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]> };
 
+export namespace ref {
+  type Callback<T, S = any> = (this: S, argument: T) =>
+    ((next: T) => void) | Promise<any> | void | boolean;
+}
+
 /**
  * Creates an object with references to all managed values.
  * Each property will set value in state when invoked.
@@ -156,8 +140,8 @@ export function ref <T extends Model> (target: T): Refs<T>;
  *
  * @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>;
-export function ref <T, S> (callback?: InterceptCallback<T, S>): Model.Ref<T>;
+export function ref <T = HTMLElement> (callback?: ref.Callback<T>): Model.Ref<T>;
+export function ref <T, S> (callback?: ref.Callback<T, S>): Model.Ref<T>;
 
 /**
  * Sets an exotic method with managed ready-state. Property accepts an async function.
@@ -177,8 +161,10 @@ export function act <S> (action: Async<S>): typeof action & { active: boolean };
  *
  * @param compute - Factory function to generate a getter to subscribe dependancies.
  */
-export function from <R> (compute: (property: string) => <T>(this: T, state: T) => R): R;
-export function from <R, T> (compute: (property: string) => (this: T, state: T) => R): R;
+export function from <R> (compute: (property: string) => <T>(this: T, state: T) => R | void, suspense: true): R;
+export function from <R, T> (compute: (property: string) => (this: T, state: T) => R | void, suspense: true): R;
+export function from <R> (compute: (property: string) => <T>(this: T, state: T) => R, suspense?: boolean): R;
+export function from <R, T> (compute: (property: string) => (this: T, state: T) => R, suspense?: boolean): R;
 
 /**
  * Implement a computed value; output will be generated by provided function.
@@ -187,8 +173,11 @@ export function from <R, T> (compute: (property: string) => (this: T, state: T)
  * 
  * @param compute - Compute function. Bound to a subscriber-proxy of source, returns output value.
  * Will update automatically as input values change.
+ *
+ * @param suspense - Compute function will suspend 
  */
-export function from <T extends Class, R> (source: T, compute: (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 | void, suspense: true): R;
+export function from <T extends Class, R> (source: T, compute: (this: InstanceOf<T>, on: InstanceOf<T>) => R, suspense?: boolean): R;
 
 /**
  * Implement a computed value; output will be generated by provided function.
@@ -206,6 +195,8 @@ export function from <R, T> (source: T, compute: (this: T, on: T) => R): R;
  *
  * @param compute - Factory for memoized value.
  * @param lazy - Wait until accessed to introduce value.
+ * 
+ * @deprecated will be removed in favor of `set`
  */
 export function memo <R> (compute: () => R, lazy?: boolean): R;
 export function memo <R, T> (compute: (this: T) => R, lazy?: boolean): R;
@@ -214,12 +205,16 @@ export function memo <R, T> (compute: (this: T) => R, lazy?: boolean): R;
  * Flag property as not to be tracked. Useful if changes often with no real-time impact.
  *
  * @param value - starting value of property.
+ * 
+ * @deprecated will be removed in major version 1.0
  */
 export function lazy <T> (value?: T): T;
 
 /**
- * Pending value. Will suspend unless value is defined,
- * suspense resolves when a value is aquired. 
+ * Pending value. Will suspend unless value is already defined,
+ * suspense resolves when a value is then aquired.
+ * 
+ * @deprecated will be removed in favor of `set`
  */
 export function pending <T = boolean> (): T;
 
@@ -227,6 +222,8 @@ export function pending <T = boolean> (): T;
  * Suspend during the execution of given function to obtain value.
  * 
  * @param waitFor - Async function to suspend for.
+ * 
+ * @deprecated will be removed in favor of `set`
  */
 export function pending (waitFor: () => Promise<void>): undefined;
 export function pending <T> (waitFor: (this: T) => Promise<void>): undefined;
@@ -250,4 +247,80 @@ export function pending <R, T> (waitFor: (this: T) => Promise<R>): R;
  * @param compute - Compute function returns output value. Bound to a subscriber of source.
  * Will re-run automatically as input values change.
  */
- export function pending <R, T> (source: T, compute: (this: T, on: T) => R): R;
+export function pending <R, T> (source: T, compute: (this: T, on: T) => R): R; // ✅
+
+export namespace set {
+  type Factory<T, S = unknown> = (this: S, key: string, subject: S) => T;
+
+  type Callback<T, S = any> = (this: S, argument: T) =>
+    ((next: T) => void) | Promise<any> | void | boolean;
+}
+
+/**
+ * Set property with a placeholder.
+ * 
+ * Property cannot be accessed until it is defined. If accessed while undefined, a hybrid
+ * `Promise`/`Error` (ala: [Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)) will be thrown.
+ */
+ export function set <T = any>(): T;
+
+ /**
+  * Set property with starting value `undefined`.
+  * 
+  * If required and accessed while still empty, React Suspense will be thrown.
+  * Property will reject any assignment of undefined.
+  * 
+  * @param value - Starting value of host property (undefined).
+  * @param required - Property will suspend callee if undefined at time of access.
+  */
+ export function set <T> (value: undefined, required: false): T | undefined;
+ export function set <T> (value: undefined, required?: boolean): T;
+ 
+ export function set <T> (value: undefined, onUpdate: set.Callback<T>): T | undefined;
+ export function set <T, S> (value: undefined, onUpdate: set.Callback<T, S>): T | undefined;
+ 
+ /**
+  * Set property with an async function.
+  * 
+  * Property cannot be accessed until factory resolves, yeilding a result.
+  * If accessed while processing, React Suspense will be thrown.
+  * 
+  * - `required: true` (default) -
+  *      Run factory immediately upon creation of model instance.
+  * - `required: false` -
+  *      Run factory only if/when accessed.
+  *      Value will always throw suspense at least once - use with caution.
+  * 
+  * @param factory - Callback run to derrive property value.
+  * @param required - (default: true) Run factory immediately on creation, otherwise on access.
+  */
+ export function set <T>(factory: set.Factory<Promise<T>>, required: false): T | undefined;
+ export function set <T, S>(factory: set.Factory<Promise<T>, S>, required: false): T | undefined;
+ 
+ export function set <T>(factory: set.Factory<Promise<T>>, required?: boolean): T;
+ export function set <T, S>(factory: set.Factory<Promise<T>, S>, required?: boolean): T;
+ 
+ export function set <T> (value: set.Factory<Promise<T>>, onUpdate: set.Callback<T>): T;
+ export function set <T, S> (value: set.Factory<Promise<T>, S>, onUpdate: set.Callback<T, S>): T;
+ 
+ /**
+  * Set property with a factory function.
+  * 
+  * - `required: true` (default) -
+  *      Run factory immediately upon creation of model instance.
+  * - `required: false` -
+  *      Run factory only if/when accessed.
+  *      Value will always throw suspense at least once - use with caution.
+  * 
+  * @param factory - Callback run to derrive property value.
+  * @param required - (default: true) Run factory immediately on creation, otherwise on access.
+  */
+ export function set <T>(factory: set.Factory<T>, required: false): T | undefined;
+ export function set <T, S>(factory: set.Factory<T, S>, required: false): T | undefined;
+ 
+ export function set <T>(factory: set.Factory<T>, required?: boolean): T;
+ export function set <T, S>(factory: set.Factory<T, S>, required?: boolean): T;
+ 
+ export function set <T> (value: set.Factory<T>, onUpdate: set.Callback<T>): T;
+ export function set <T, S> (value: set.Factory<T, S>, onUpdate: set.Callback<T, S>): T;
+ 

package/types/lifecycle.d.ts

@@ -1,4 +1,6 @@
-import { Key } from "./types";
+declare namespace Lifecycle {
+  type Key = string | symbol | number;
+}
 
 /**
  * Model-Component Lifecycle
@@ -8,17 +10,17 @@ import { Key } from "./types";
  * call these respectively to that component's lifecycle.
  */
 interface Lifecycle {
-  didMount?(tag?: Key): void;
-  willRender?(tag?: Key): void;
-  willUpdate?(tag?: Key): void;
-  willMount?(tag?: Key): void;
-  willUnmount?(tag?: Key): void;
+  didMount?(tag?: Lifecycle.Key): void;
+  willRender?(tag?: Lifecycle.Key): void;
+  willUpdate?(tag?: Lifecycle.Key): void;
+  willMount?(tag?: Lifecycle.Key): void;
+  willUnmount?(tag?: Lifecycle.Key): void;
 
-  elementDidMount?(tag: Key): void;
-  elementWillRender?(tag: Key): void;
-  elementWillUpdate?(tag: Key): void;
-  elementWillMount?(tag: Key): void;
-  elementWillUnmount?(tag: Key): void;
+  elementDidMount?(tag: Lifecycle.Key): void;
+  elementWillRender?(tag: Lifecycle.Key): void;
+  elementWillUpdate?(tag: Lifecycle.Key): void;
+  elementWillMount?(tag: Lifecycle.Key): void;
+  elementWillUnmount?(tag: Lifecycle.Key): void;
 
   componentDidMount?(): void;
   componentWillRender?(): void;