@expressive/mvc 0.1.1 → 0.2.2

package/lib/index.d.ts

@@ -112,8 +112,16 @@ interface Model extends Stateful {
      * Circular reference to `this` controller.
      *
      * Useful to obtain full reference where one has already destructured.
+     *
+     * @deprecated will be removed in favor of `is`
      */
     get: this;
+    /**
+     * Circular reference to `this` controller.
+     *
+     * Useful to obtain full reference where one has already destructured.
+     */
+    is: this;
     /**
     * Setter utility
     *
@@ -356,6 +364,18 @@ declare function set<T>(factory: set.Factory<T>, required?: boolean): T;
 declare function set<T, S>(factory: set.Factory<T, S>, required?: boolean): T;
 declare function set<T>(value: set.Factory<T>, onUpdate: set.Callback<T>): T;
 declare function set<T, S>(value: set.Factory<T, S>, onUpdate: set.Callback<T, S>): T;
+/**
+ * Assign a property with result of a promise.
+ */
+declare function set<T>(factory: Promise<T>, required: false): T | undefined;
+declare function set<T>(factory: Promise<T>, required?: boolean): T;
+declare function set<T>(value: Promise<T>, onUpdate: set.Callback<T>): T;
+/**
+ * Assign a property.
+ */
+declare function set<T>(factory: T, required: false): T | undefined;
+declare function set<T>(factory: T, required?: boolean): T;
+declare function set<T>(value: T, onUpdate: set.Callback<T>): T;
 
 /**
  * Create a placeholder for specified Model type.
@@ -410,19 +430,26 @@ declare class MVC extends Model {
     /**
      * **React Hook** - Fetch most instance of this controller from context, if it exists.
      *
-     * @param required - If false, may return undefined.
+     * @param required - Unless false, will throw where instance cannot be found.
      */
-    static get<T extends Class>(this: T, required?: true): InstanceOf<T>;
+    static get<T extends Class>(this: T, required?: boolean): InstanceOf<T>;
     /**
      * **React Hook** - Fetch most instance of this controller from context.
      *
-     * @param required - Unless false, will throw where instance cannot be found.
+     * @param required - If false, may return undefined.
      */
-    static get<T extends Class>(this: T, required: boolean): InstanceOf<T> | undefined;
+    static get<T extends Class>(this: T, required: false): InstanceOf<T> | undefined;
     /**
      * **React Hook** - Fetch specific value from instance of this controller in context.
      */
     static get<T extends Class, I extends InstanceOf<T>, K extends Model.Field<I>>(this: T, key: K): I[K];
+    /**
+     * **React Hook** - Fetch instance.
+     *
+     * Effect callback will run once if found, throw if not found.
+     * Returned function is called on unmount.
+     */
+    static get<T extends Class, I extends InstanceOf<T>>(Type: T, effect: (found: I) => Callback | void): I;
     /**
      * **React Hook** - Fetch and subscribe to instance of this controller within ambient component.
      */
@@ -464,8 +491,10 @@ declare class MVC extends Model {
 
 declare namespace Consumer {
     type HasProps<E extends Class> = {
+        /** @deprecated - use for instead */
+        of?: never;
         /** Type of controller to fetch from context. */
-        of: E;
+        for: E;
         /**
          * Getter function. Is called on every natural render of this component.
          * Will throw if usable instance cannot be found in context.
@@ -473,14 +502,18 @@ declare namespace Consumer {
         has: (value: InstanceType<E>) => void;
     };
     type GetProps<E extends Class> = {
+        /** @deprecated - use for instead */
+        of?: never;
         /** Type of controller to fetch from context. */
-        of: E;
+        for: E;
         /** Getter function. Is called on every natural render of this component. */
         get: (value: InstanceType<E> | undefined) => void;
     };
     type RenderProps<E extends Class> = {
+        /** @deprecated - use for instead */
+        of?: never;
         /** Type of controller to fetch from context. */
-        of: E;
+        for: E;
         /**
          * Render function, will receive instance of desired controller.
          *
@@ -513,11 +546,15 @@ declare namespace Provider {
     };
     type Existent<E> = E extends Class ? InstanceType<E> : E extends Model ? E : never;
     type NormalProps<E, I = Existent<E>> = {
-        of: E;
+        /** @deprecated use for instead. */
+        of?: never;
+        for: E;
         children: React.ReactNode | ((instance: I) => React.ReactNode);
     } & Model.Compat<I>;
     type MultipleProps<T extends Item> = {
-        of: Collection<T>;
+        /** @deprecated use for instead. */
+        of?: never;
+        for: Collection<T>;
         children?: React.ReactNode | (() => React.ReactNode);
     } & Model.Compat<Existent<T>>;
     type Props<T extends Item> = MultipleProps<T> | NormalProps<T>;
@@ -581,7 +618,10 @@ declare function tap<T extends Class>(Type: T, required?: boolean): InstanceOf<T
 declare function useFrom<T extends Stateful, R>(source: (() => T) | T, compute: (this: T, from: T) => R, expect: true): Exclude<R, undefined>;
 declare function useFrom<T extends Stateful, R>(source: (() => T) | T, compute: (this: T, from: T) => R, expect?: boolean): R;
 
-declare function useLocal<T extends typeof Model>(Type: T, arg?: boolean | string): any;
+declare function useLocal<T extends typeof Model>(Type: T, required: false): InstanceOf<T> | undefined;
+declare function useLocal<T extends typeof Model>(Type: T, arg?: boolean): InstanceOf<T>;
+declare function useLocal<T extends typeof Model, I extends InstanceOf<T>>(Type: T, effect: (found: I) => Callback | void): I;
+declare function useLocal<T extends typeof Model, I extends InstanceOf<T>, K extends Model.Field<I>>(Type: T, key: K): I[K];
 
 declare function useModel<T extends Class, I extends InstanceOf<T>>(source: T, watch: Model.Field<I>[], callback?: (instance: I) => void): I;
 declare function useModel<T extends Class, I extends InstanceOf<T>>(source: T, callback?: (instance: I) => void): I;

package/lib/index.esm.js

@@ -1,4 +1,4 @@
-import React, { useState, useMemo } from 'react';
+import React, { useLayoutEffect, useState, useMemo } from 'react';
 
 /*! *****************************************************************************
 Copyright (c) Microsoft Corporation.
@@ -43,10 +43,10 @@ function issues(register) {
 }
 
 const Oops$c = issues({
-    ValueNotReady: (model, key) => `Value ${model}.${key} value is not yet available.`,
+    NotReady: (model, key) => `Value ${model}.${key} value is not yet available.`,
 });
 function suspend(source, key) {
-    const error = Oops$c.ValueNotReady(source.subject, key);
+    const error = Oops$c.NotReady(source.subject, key);
     const promise = new Promise(resolve => {
         const release = source.addListener(forKey => {
             if (forKey == key)
@@ -87,7 +87,7 @@ function mayRetry(fn) {
 }
 
 const Oops$b = issues({
-    BadEffectCallback: () => `Callback for effect-callback may only return a function.`
+    BadCallback: () => `Callback for effect-callback may only return a function.`
 });
 const { assign, create, defineProperty, entries, getPrototypeOf, getOwnPropertyNames, getOwnPropertyDescriptor, getOwnPropertySymbols, values } = Object;
 function define(target, key, value) {
@@ -112,7 +112,7 @@ function createEffect(callback) {
         if (unSet instanceof Promise)
             unSet = undefined;
         if (unSet && typeof unSet !== "function")
-            throw Oops$b.BadEffectCallback();
+            throw Oops$b.BadCallback();
     };
 }
 function createValueEffect(callback) {
@@ -128,7 +128,7 @@ function createValueEffect(callback) {
         if (typeof out == "function")
             unSet = out;
         else
-            throw Oops$b.BadEffectCallback();
+            throw Oops$b.BadCallback();
     };
 }
 
@@ -148,16 +148,16 @@ const LOCAL = Symbol("LOCAL");
 const STATE = Symbol("STATE");
 class Model {
     constructor() {
-        const control = new Controller(this);
-        define(this, CONTROL, control);
+        define(this, CONTROL, new Controller(this));
         define(this, "get", this);
+        define(this, "is", this);
         defineLazy(this, "set", () => {
+            const controller = control(this);
             const assign = (key, value) => {
-                control.update(key, value);
+                controller.update(key, value);
             };
-            ready(control);
-            for (const key of getOwnPropertyNames(control.proxy))
-                define(assign, key, control.ref(key));
+            for (const key of getOwnPropertyNames(controller.proxy))
+                define(assign, key, controller.ref(key));
             return assign;
         });
     }
@@ -345,10 +345,10 @@ class Subscriber {
 }
 
 const Oops$a = issues({
-    BadComputedSource: (model, property, got) => `Bad from-instruction provided to ${model}.${property}. Expects an arrow-function or a Model as source. Got ${got}.`,
+    BadSource: (model, property, got) => `Bad from-instruction provided to ${model}.${property}. Expects an arrow-function or a Model as source. Got ${got}.`,
     PeerNotAllowed: (model, property) => `Attempted to use an instruction result (probably use or tap) as computed source for ${model}.${property}. This is not possible.`,
-    ComputeFailed: (parent, property, initial) => `An exception was thrown while ${initial ? "initializing" : "refreshing"} [${parent}.${property}].`,
-    ComputedEarly: (property) => `Note: Computed values don't run until accessed, except when subscribed to. '${property}' getter may have run earlier than intended.`
+    Failed: (parent, property, initial) => `An exception was thrown while ${initial ? "initializing" : "refreshing"} [${parent}.${property}].`,
+    Early: (property) => `Note: Computed values don't run until accessed, except when subscribed to. '${property}' getter may have run earlier than intended.`
 });
 const INIT = new WeakSet();
 const INFO = new WeakMap();
@@ -375,7 +375,7 @@ function from(source, arg1, arg2) {
         }
         // Regular function is too ambiguous so not allowed.
         else
-            throw Oops$a.BadComputedSource(subject, key, source);
+            throw Oops$a.BadSource(subject, key, source);
         let sub;
         const setter = arg1;
         const info = { key, parent, priority: 1 };
@@ -390,7 +390,7 @@ function from(source, arg1, arg2) {
                 return setter.call(sub.proxy, sub.proxy);
             }
             catch (err) {
-                Oops$a.ComputeFailed(subject, key, !!initial).warn();
+                Oops$a.Failed(subject, key, !!initial).warn();
                 throw err;
             }
         }
@@ -431,7 +431,7 @@ function from(source, arg1, arg2) {
             }
             catch (e) {
                 if (early)
-                    Oops$a.ComputedEarly(key).warn();
+                    Oops$a.Early(key).warn();
                 throw e;
             }
             finally {
@@ -615,9 +615,6 @@ function control(subject, cb) {
         control = new Controller(subject);
         define(subject, CONTROL, control);
     }
-    return ready(control, cb);
-}
-function ready(control, cb) {
     const ready = READY.has(control);
     if (!ready) {
         if (cb) {
@@ -715,14 +712,14 @@ function forSubscriber(fn) {
 }
 
 const Oops$8 = issues({
-    DuplicateAction: (key) => `Invoked action ${key} but one is already active.`
+    DuplicatePending: (key) => `Invoked action ${key} but one is already active.`
 });
 function act(task) {
     return apply(function act(key) {
         let pending = false;
         const invoke = (...args) => __awaiter(this, void 0, void 0, function* () {
             if (pending)
-                return Promise.reject(Oops$8.DuplicateAction(key));
+                return Promise.reject(Oops$8.DuplicatePending(key));
             pending = true;
             this.update(key);
             try {
@@ -827,28 +824,74 @@ function createRef(key, cb) {
 
 const Oops$7 = issues({
     NonOptional: (Parent, key) => `Property ${Parent}.${key} is marked as required.`,
-    BadFactory: () => `Set instruction can only accept a factory or undefined.`,
-    ValueNotReady: (model, key) => `Value ${model}.${key} value is not yet available.`,
-    FactoryFailed: (model, key) => `Generating initial value for ${model}.${key} failed.`
+    NotReady: (model, key) => `Value ${model}.${key} value is not yet available.`,
+    Failed: (model, key) => `Generating initial value for ${model}.${key} failed.`
 });
 function set(factory, argument) {
     return apply(function set(key) {
+        const { subject, state } = this;
+        const required = argument === true || argument === undefined;
         let set;
         let get;
         let suspense;
-        const required = argument === true || argument === undefined;
         if (factory === undefined)
             suspense = true;
-        else if (typeof factory === "function")
-            get = pendingFactory(this, key, factory, required);
-        else
-            throw Oops$7.BadFactory();
+        else {
+            let pending;
+            let error;
+            const init = () => {
+                const output = typeof factory == "function" ?
+                    mayRetry(() => factory.call(subject, key, subject)) :
+                    factory;
+                if (output instanceof Promise) {
+                    pending = output
+                        .catch(err => error = err)
+                        .then(val => state[key] = val)
+                        .finally(() => {
+                        pending = undefined;
+                        this.update(key);
+                    });
+                    return;
+                }
+                return state[key] = output;
+            };
+            const suspend = () => {
+                if (required === false)
+                    return undefined;
+                const issue = Oops$7.NotReady(subject, key);
+                Object.assign(pending, {
+                    message: issue.message,
+                    stack: issue.stack
+                });
+                throw pending;
+            };
+            if (required)
+                try {
+                    init();
+                }
+                catch (err) {
+                    Oops$7.Failed(subject, key).warn();
+                    throw err;
+                }
+            get = () => {
+                if (pending)
+                    return suspend();
+                if (error)
+                    throw error;
+                if (key in state)
+                    return state[key];
+                let output = init();
+                return pending
+                    ? suspend()
+                    : output;
+            };
+        }
         if (typeof argument == "function")
             set = createValueEffect(argument);
         else
             set = (value) => {
                 if (value === undefined && required)
-                    throw Oops$7.NonOptional(this.subject, key);
+                    throw Oops$7.NonOptional(subject, key);
             };
         return {
             set,
@@ -856,63 +899,12 @@ function set(factory, argument) {
             suspense
         };
     });
-}
-function pendingFactory(parent, key, fn, required) {
-    const { subject, state } = parent;
-    let pending;
-    let error;
-    const init = () => {
-        const output = mayRetry(() => {
-            return fn.call(subject, key, subject);
-        });
-        if (output instanceof Promise) {
-            pending = output
-                .catch(err => error = err)
-                .then(val => state[key] = val)
-                .finally(() => {
-                pending = undefined;
-                parent.update(key);
-            });
-            return;
-        }
-        return state[key] = output;
-    };
-    const suspend = () => {
-        if (required === false)
-            return undefined;
-        const issue = Oops$7.ValueNotReady(subject, key);
-        Object.assign(pending, {
-            message: issue.message,
-            stack: issue.stack
-        });
-        throw pending;
-    };
-    if (required)
-        try {
-            init();
-        }
-        catch (err) {
-            Oops$7.FactoryFailed(subject, key).warn();
-            throw err;
-        }
-    return () => {
-        if (pending)
-            return suspend();
-        if (error)
-            throw error;
-        if (key in state)
-            return state[key];
-        let output = init();
-        return pending
-            ? suspend()
-            : output;
-    };
 }
 
 const Parent = new WeakMap();
 const Oops$6 = issues({
-    ParentRequired: (expects, child) => `New ${child} created standalone but requires parent of type ${expects}. Did you remember to create via use(${child})?`,
-    UnexpectedParent: (expects, child, got) => `New ${child} created as child of ${got}, but must be instanceof ${expects}.`,
+    Required: (expects, child) => `New ${child} created standalone but requires parent of type ${expects}. Did you remember to create via use(${child})?`,
+    Unexpected: (expects, child, got) => `New ${child} created as child of ${got}, but must be instanceof ${expects}.`,
 });
 function parent(Expects, required) {
     return apply(function parent() {
@@ -921,10 +913,10 @@ function parent(Expects, required) {
         const expected = Expects.name;
         if (!value) {
             if (required !== false)
-                throw Oops$6.ParentRequired(expected, child);
+                throw Oops$6.Required(expected, child);
         }
         else if (!(value instanceof Expects))
-            throw Oops$6.UnexpectedParent(expected, child, value);
+            throw Oops$6.Unexpected(expected, child, value);
         return { value };
     });
 }
@@ -1029,19 +1021,24 @@ class Lookup {
 const LookupContext = React.createContext(new Lookup());
 const useLookup = () => React.useContext(LookupContext);
 const Oops$4 = issues({
-    NothingInContext: (name) => `Couldn't find ${name} in context; did you forget to use a Provider?`
+    NotFound: (name) => `Couldn't find ${name} in context; did you forget to use a Provider?`
 });
 function useLocal(Type, arg) {
     const instance = useLookup().get(Type);
     if (!instance && arg !== false)
-        throw Oops$4.NothingInContext(Type.name);
-    return typeof arg == "string" ?
-        instance[arg] :
-        instance;
+        throw Oops$4.NotFound(Type.name);
+    switch (typeof arg) {
+        case "string":
+            return instance[arg];
+        case "function":
+            useLayoutEffect(() => arg(instance), []);
+        default:
+            return instance;
+    }
 }
 
 const Oops$3 = issues({
-    CantAttachGlobal: (parent, child) => `Global '${parent}' attempted to attach '${child}' but it is not also a singleton.`,
+    NotAllowed: (parent, child) => `Global '${parent}' attempted to attach '${child}' but it is not also a singleton.`,
     AmbientRequired: (requested, requester, key) => `Attempted to find an instance of ${requested} in context. It is required for [${requester}.${key}], but one could not be found.`
 });
 const PendingContext = new WeakMap();
@@ -1055,7 +1052,7 @@ function tap(type, argument) {
             };
         const { subject } = this;
         if ("set" in subject.constructor)
-            throw Oops$3.CantAttachGlobal(subject, type.name);
+            throw Oops$3.NotAllowed(subject, type.name);
         getPending(subject).push(context => {
             let instance = context.get(type);
             if (typeof argument == "function") {
@@ -1233,8 +1230,8 @@ class MVC extends Model {
     use(arg, callback) {
         return useModel(this, arg, callback);
     }
-    static get(required) {
-        return useLocal(this, required);
+    static get(arg) {
+        return useLocal(this, arg);
     }
     static tap(key, expect) {
         return useTap(this, key, expect);
@@ -1280,25 +1277,28 @@ class MVC extends Model {
 }
 
 const Oops$2 = issues({
-    BadConsumerProps: () => `Provider expects either a render function, 'get' or 'has' props.`
+    BadProps: () => `Provider expects either a render function, 'get' or 'has' props.`
 });
 function Consumer(props) {
-    const { get, has, children, of: Control } = props;
+    const { get, has, children, for: type } = props;
     if (typeof children == "function")
-        return children(useTap(Control));
+        return children(useTap(type));
     const callback = has || get;
     if (typeof callback == "function")
-        callback(useLocal(Control, !!has));
+        callback(useLocal(type, !!has));
     else
-        throw Oops$2.BadConsumerProps();
+        throw Oops$2.BadProps();
     return null;
 }
 
 const Oops$1 = issues({
-    NoProviderType: () => `Provider 'of' prop must be Model, typeof Model or a collection of them.`
+    NoType: () => "Provider 'of' prop must be Model, typeof Model or a collection of them.",
+    PropDeprecated: () => "Provider `of` prop is deprecated, use `for` instead."
 });
 function Provider(props) {
-    const context = useNewContext(props.of);
+    if ("of" in props)
+        throw Oops$1.PropDeprecated();
+    const context = useNewContext(props.for);
     const render = props.children;
     useAppliedProps(context, props);
     React.useLayoutEffect(() => () => context.pop(), []);
@@ -1310,7 +1310,7 @@ function useNewContext(inject) {
     const from = useLookup();
     return React.useMemo(() => {
         if (!inject)
-            throw Oops$1.NoProviderType();
+            throw Oops$1.NoType();
         const context = from.push(inject);
         for (const instance of context.local)
             if (instance)
@@ -1324,7 +1324,7 @@ function useAppliedProps(within, props) {
         const targets = within.local;
         return function integrate(props) {
             for (const [key, value] of entries(props))
-                if (key != "of" && key != "children")
+                if (["of", "for", "children"].indexOf(key) < 0)
                     for (const into of targets)
                         if (into && key in into)
                             into[key] = value;
@@ -1345,15 +1345,15 @@ function RenderFunction(props) {
 }
 
 const Oops = issues({
-    GlobalDoesNotExist: (name) => `Tried to access singleton ${name}, but none exist! Did you forget to initialize?\nCall ${name}.create() before attempting to access, or consider using ${name}.use() instead.`,
-    GlobalExists: (name) => `Shared instance of ${name} already exists! Consider unmounting existing, or use ${name}.reset() to force-delete it.`
+    DoesNotExist: (name) => `Tried to access singleton ${name}, but none exist! Did you forget to initialize?\nCall ${name}.create() before attempting to access, or consider using ${name}.use() instead.`,
+    AlreadyExists: (name) => `Shared instance of ${name} already exists! Consider unmounting existing, or use ${name}.reset() to force-delete it.`
 });
 const Active = new WeakMap();
 class Global extends MVC {
     static create(...args) {
         const Type = this;
         if (Active.has(Type))
-            throw Oops.GlobalExists(this.name);
+            throw Oops.AlreadyExists(this.name);
         const instance = super.create(...args);
         Active.set(Type, instance);
         return instance;
@@ -1371,7 +1371,7 @@ class Global extends MVC {
     static get(arg) {
         const instance = Active.get(this);
         if (!instance && arg !== false)
-            throw Oops.GlobalDoesNotExist(this.name);
+            throw Oops.DoesNotExist(this.name);
         return (typeof arg == "string" ?
             instance[arg] :
             instance);