@expressive/mvc 0.88.0 → 0.89.0

package/dist/state.d.ts

@@ -3,13 +3,13 @@ import { event } from "./observable.js";
 
 //#region src/state.d.ts
 /** Internal state assigned to states. */
-declare const STORE: WeakMap<State, Record<string | number | symbol, unknown>>;
-/** States under construction - added on `new`, removed when activated or released.
+declare const STORE: WeakMap<Model, Record<string | number | symbol, unknown>>;
+/** Models under construction - added on `new`, removed when activated or released.
  *  Also carries work to run at the deadline, which `def` uses to bound its registry. */
-declare const PENDING: Set<State | (() => void)>;
-/** External lifecycle listeners for any given State class. */
-type Handler = State.On<any>;
-declare const SETUP: WeakMap<State.Extends<State>, Set<Handler>>;
+declare const PENDING: Set<Model | (() => void)>;
+/** External lifecycle listeners for any given Model class. */
+type Handler = Model.On<any>;
+declare const SETUP: WeakMap<Model.Extends<Model>, Set<Handler>>;
 /** Reference bound instance methods, or their getter, to real one. */
 declare const UNBIND: WeakMap<any, any>;
 /** List of methods defined by a given type. */
@@ -18,43 +18,44 @@ declare const METHODS: WeakMap<Function, Map<string, (value: any) => void>>;
 declare const GETTERS: WeakMap<Function, Map<string, () => unknown>>;
 /** Replacement for a getter captured by live computed properties, for hot patching. */
 declare const LATEST: WeakMap<Function, Function>;
-declare namespace State {
-  /** Any type of State, using own class constructor as its identifier. */
-  type Extends<T extends State = State> = (abstract new (...args: any[]) => T) & typeof State;
-  /** A State constructor which may be instanciated. */
-  type Type<T extends State = State> = (new (...args: State.Args<T>) => T) & Omit<typeof State, never>;
-  /** State constructor arguments */
-  type Args<T extends State = any> = (Args<T> | Init<T> | Assign<T> | void)[];
+type Overlay<T> = Record<string, unknown> & { [K in Model.Property<T>]?: T[K] extends ((...args: infer A) => infer R) ? (this: T, ...args: A) => R : T[K] };
+declare namespace Model {
+  /** Any type of Model, using own class constructor as its identifier. */
+  type Extends<T extends Model = Model> = (abstract new (...args: any[]) => T) & typeof Model;
+  /** A Model constructor which may be instanciated. */
+  type Type<T extends Model = Model> = (new (...args: Model.Args<T>) => T) & Omit<typeof Model, never>;
+  /** Model constructor arguments */
+  type Args<T extends Model = any> = (Args<T> | Init<T> | Overlay<T> | void)[];
   /**
-   * Value of `static global`. A boolean opts a State in or out of the
+   * Value of `static global`. A boolean opts a Model in or out of the
    * process-global root; a resolver decides at activation, receiving the
    * instance and returning whether it registers - use it to make the choice
    * conditional (e.g. per environment). A bare literal (`= true` / `= false`)
    * seals the choice for subclasses; widen a subclass's `static global` type to
-   * `State.Global` to permit a resolver or a later override.
+   * `Model.Global` to permit a resolver or a later override.
    */
-  type Global<T extends State = any> = boolean | ((self: T) => boolean);
+  type Global<T extends Model = any> = boolean | ((self: T) => boolean);
   /**
-   * State constructor callback - runs during activation, in argument order,
+   * Model constructor callback - runs during activation, in argument order,
    * before the `new()` lifecycle hook (so it may configure state `new()`
    * will observe). Returned function will run when state is destroyed.
    */
-  type Init<T extends State = State> = (this: T, thisArg: T) => Promise<void> | (() => void) | Args<T> | Assign<T> | void;
-  /** Lifecycle handlers for `State.on`, keyed by when they run. */
-  interface On<T extends State = State> {
+  type Init<T extends Model = Model> = (this: T, thisArg: T) => Promise<void> | (() => void) | Args<T> | Overlay<T> | void;
+  /** Lifecycle handlers for `Model.on`, keyed by when they run. */
+  interface On<T extends Model = Model> {
     /**
      * Per-class setup, run once when the class is first bootstrapped - before
      * its members are classified and bound. Receives the class, so a handler
      * may inspect or reshape the prototype first. A handler registered on a
      * base class runs for each subclass too.
      */
-    type?(type: State.Extends<T>): void;
+    type?(type: Model.Extends<T>): void;
     /**
      * Per-instance, once constructed - before own values are observed and
      * before constructor args and `new()`. May return a cleanup, constructor
      * args, or an assign overlay.
      */
-    setup?(this: T, self: T): void | (() => void) | Promise<void> | Args<T> | Assign<T>;
+    setup?(this: T, self: T): void | (() => void) | Promise<void> | Args<T> | Overlay<T>;
     /**
      * Per-instance, once ready - after own values are observed, constructor
      * args applied and `new()` has run. May return a cleanup function.
@@ -67,7 +68,7 @@ declare namespace State {
      */
     method?(this: T, key: string, fn: Function, self: T): void;
     /**
-     * Receives what an effect, refreshing getter or async initializer of this State
+     * Receives what an effect, refreshing getter or async initializer of this Model
      * or a subclass threw, a destroyed write, or an instance never activated - with
      * its `kind` (`effect`, `getter`, `setup`, `dead`, `unused`) and `key` where
      * one applies. Most-derived class first, last registered first, each once. Return the error
@@ -78,17 +79,17 @@ declare namespace State {
     catch?(this: T, error: unknown, kind: 'effect' | 'getter' | 'setup' | 'dead' | 'unused', key?: string): unknown;
   }
   /** Object overlay to override values and methods on a state. */
-  type Assign<T> = Record<string, unknown> & { [K in Property<T>]?: T[K] extends ((...args: infer A) => infer R) ? (this: T, ...args: A) => R : T[K] };
-  /** Subset of `keyof T` not defined by base State. **/
-  type Property<T> = Exclude<keyof T, keyof State>;
+  type Assign<T> = Record<string, unknown> & { [K in Property<T>]?: T[K] } & ThisType<T>;
+  /** Subset of `keyof T` not defined by base Model. **/
+  type Property<T> = Exclude<keyof T, keyof Model>;
   /** Managed subset of Property<T> - excludes unmanaged `_` keys. **/
   type Field<T> = Exclude<Property<T>, `_${string}`>;
   /** Any valid key for state, including but not limited to Field<T>. */
-  type Event<T = State> = Field<T> | number | symbol | (string & {});
+  type Event<T = Model> = Field<T> | number | symbol | (string & {});
   /** Any event signal dispatched to listeners, including lifecycle meta events. */
-  type Signal<T = State> = Event<T> | true | false | null;
-  /** Export/Import compatible value for a given property in a State. */
-  type Export<R> = R extends State ? Values<R> : R extends {
+  type Signal<T = Model> = Event<T> | true | false | null;
+  /** Export/Import compatible value for a given property in a Model. */
+  type Export<R> = R extends Model ? Values<R> : R extends {
     get(): infer T;
   } ? T : R;
   /**
@@ -100,18 +101,18 @@ declare namespace State {
   /** Object comperable to data found in T. */
   type Partial<T> = { [P in Field<T>]?: Export<T[P]> };
   /** Value for a property applied by a state. */
-  type Value<T extends State, K extends State.Event<T>> = K extends keyof T ? Export<T[K]> : unknown;
+  type Value<T extends Model, K extends Model.Event<T>> = K extends keyof T ? Export<T[K]> : unknown;
   type Setter<T> = (value: T, previous: T) => T | void;
   /** Descriptor config for a managed property. */
   type Apply<T = any> = {
     value?: T;
-    get?: ((source: State) => T) | boolean;
+    get?: ((source: Model) => T) | boolean;
     set?: Setter<T> | boolean;
     enumerable?: boolean;
   };
   /** Descriptor config for set() overload - enforces type when key is a known field. */
   type Define<T, K> = K extends Field<T> ? Apply<T[K] | Export<T[K]>> : Apply;
-  type OnEvent<T extends State> = (this: T, key: Signal<T>, source: T) => void | (() => void) | null;
+  type OnEvent<T extends Model> = (this: T, key: Signal<T>, source: T) => void | (() => void) | null;
   /** Exotic value, where actual value is contained within. */
   type Ref<T = any> = {
     (next: T): void;
@@ -127,7 +128,13 @@ declare namespace State {
    *
    * @returns A callback function which will be called when this effect is stale.
    */
-  type Effect<T> = (this: T, current: T, update: readonly State.Event<T>[] | undefined) => EffectCallback | Promise<void> | null | void;
+  type Effect<T, R = EffectCallback | Promise<void> | null | void> = (this: T, current: T, update: readonly Model.Event<T>[] | undefined) => R;
+  /**
+   * Returned by `get(effect)`. Call to stop the effect. Await to stop it once it
+   * has run clean and receive that run's value - a sync run's output, or what its
+   * promise resolved to.
+   */
+  type Release<R = void> = (() => void) & PromiseLike<R>;
   /**
    * A callback function returned by effect. Will be called when effect is stale.
    *
@@ -138,29 +145,29 @@ declare namespace State {
    * A list of keys updated, or events fired, since last update.
    * This may be awaited to get full list (same array) when update is settled.
    */
-  type Updated<T extends State> = readonly Event<T>[] & PromiseLike<readonly Event<T>[]>;
+  type Updated<T extends Model> = readonly Event<T>[] & PromiseLike<readonly Event<T>[]>;
 }
-declare abstract class State {
+declare abstract class Model {
   /**
    * Whether an instance activated with no enclosing context registers itself
    * to the process-global root, where `get()` can resolve it from anywhere.
    * `false` (the default) keeps a context-less instance fully functional but
    * private - not injectable, though it can still read declared globals. Opt in
-   * with `static readonly global = true`; a resolver (see {@link State.Global})
+   * with `static readonly global = true`; a resolver (see {@link Model.Global})
    * makes the choice conditional. It must be declared per class - a subclass
    * that would inherit a global without its own declaration throws on
-   * activation, so an accidental global (a forgotten `Provider`, an extended
-   * global) cannot leak into the shared root.
+   * activation, so an accidental global (a forgotten `<Component for>`, an
+   * extended global) cannot leak into the shared root.
    */
-  static readonly global: State.Global;
+  static readonly global: Model.Global;
   /**
    * Loopback to instance of this state. This is useful when in a subscribed context,
    * to keep write access to `this` after a destructure. You can use it to read variables silently as well.
    **/
   is: this;
-  constructor(...args: State.Args);
+  constructor(...args: Model.Args);
   /**
-   * Optional lifecycle hook called during State initialization.
+   * Optional lifecycle hook called during Model initialization.
    * Can return a cleanup function to run when state is destroyed.
    *
    * It is recommended you protect this method.
@@ -171,16 +178,23 @@ declare abstract class State {
    *
    * @returns Object with all values from this state.
    **/
-  get(): State.Values<this>;
+  get(): Model.Values<this>;
   /**
    * Run a function to run automatically when accessed values change.
    *
    * @param effect Function to run, and whenever accessed values change.
    *               If effect returns a function, it will be called when a change occurs (syncronously),
-   *               effect is cancelled, or parent state is destroyed.
-   * @returns Function to cancel listener.
+   *               effect is cancelled, or parent state is destroyed. A returned promise
+   *               defers re-runs until it settles; its resolved value is treated the same way.
+   * @returns Function to cancel listener - awaited, cancels and yields the effect's value.
+   */
+  get(effect: Model.Effect<this>): Model.Release;
+  /**
+   * Run a function to run automatically when accessed values change, which
+   * produces a value - sync or async. Await the returned function to cancel the
+   * effect once a run completes and receive what it returned.
    */
-  get(effect: State.Effect<this>): () => void;
+  get<R>(effect: Model.Effect<this, Promise<R>>): Model.Release<R>;
   /**
    * Get value of a property. Will fetch underlying value from exotic values like ref.Object.
    *
@@ -190,7 +204,7 @@ declare abstract class State {
    * @param required - If true, will throw an error if property is not available.
    * @returns Value of property.
    */
-  get<T extends State.Event<this>>(key: T, required?: boolean): State.Value<this, T>;
+  get<T extends Model.Event<this>>(key: T, required?: boolean): Model.Value<this, T>;
   /**
    * Check if state is destroyed.
    *
@@ -205,42 +219,42 @@ declare abstract class State {
    * @returns Function to cancel listener.
    */
   get(status: null, callback: () => void): () => void;
-  /** Fetch State of type from context. Throws if not found. */
-  get<T extends State>(type: State.Type<T>, required?: true): T;
-  /** Fetch a State from context. Undefined if not found. */
-  get<T extends State>(type: State.Type<T>, required: boolean): T | undefined;
+  /** Fetch Model of type from context. Throws if not found. */
+  get<T extends Model>(type: Model.Type<T>, required?: true): T;
+  /** Fetch a Model from context. Undefined if not found. */
+  get<T extends Model>(type: Model.Type<T>, required: boolean): T | undefined;
   /**
-   * Subscribe to State becoming available in context.
+   * Subscribe to Model becoming available in context.
    *
    * Will search both up and downstream by default.
-   * Normally you can ignore this because State you expect is rarely both.
+   * Normally you can ignore this because Model you expect is rarely both.
    *
-   * Specify downstream if you only want to watch for State in children, which can be useful if you expect multiple of the same State in different branches of the tree.
+   * Specify downstream if you only want to watch for Model in children, which can be useful if you expect multiple of the same Model in different branches of the tree.
    *
-   * @param type - Type of State to watch for.
-   * @param callback - Function to call when State is found. Will be called immediately if State is already available.
-   * @param downstream - If true, will only watch for State in children, if false will only for parents.
+   * @param type - Type of Model to watch for.
+   * @param callback - Function to call when Model is found. Will be called immediately if Model is already available.
+   * @param downstream - If true, will only watch for Model in children, if false will only for parents.
    * @returns Function to cancel listener.
    */
-  get<T extends State>(type: State.Type<T>, callback: Context.Expect<T>, downstream?: boolean): () => void;
-  /** Owner of this State. Throws if it has none. */
-  get<T extends typeof State>(type: T & (typeof State extends T ? unknown : never), required?: true): State;
-  /** Owner of this State. Undefined if it has none. */
-  get<T extends typeof State>(type: T & (typeof State extends T ? unknown : never), required: boolean): State | undefined;
+  get<T extends Model>(type: Model.Type<T>, callback: Context.Expect<T>, downstream?: boolean): () => void;
+  /** Owner of this Model. Throws if it has none. */
+  get<T extends typeof Model>(type: T & (typeof Model extends T ? unknown : never), required?: true): Model;
+  /** Owner of this Model. Undefined if it has none. */
+  get<T extends typeof Model>(type: T & (typeof Model extends T ? unknown : never), required: boolean): Model | undefined;
   /**
-   * Run a callback for each State this one owns - those owned now, then each
-   * one as it activates. Callback may return a function, called when that State
+   * Run a callback for each Model this one owns - those owned now, then each
+   * one as it activates. Callback may return a function, called when that Model
    * is destroyed.
    *
    * @returns Function to stop watching.
    */
-  get<T extends typeof State>(type: T & (typeof State extends T ? unknown : never), callback: (child: State) => void | (() => void), downstream: true): () => void;
+  get<T extends typeof Model>(type: T & (typeof Model extends T ? unknown : never), callback: (child: Model) => void | (() => void), downstream: true): () => void;
   /**
    * Get update in progress.
    *
    * @returns Promise which resolves object with updated values, `undefined` if there no update is pending.
    **/
-  set(): State.Updated<this>;
+  set(): Model.Updated<this>;
   /**
    * Merge argument with current state, updating one or more properties at once.
    * Properties which are not managed by this state will be ignored.
@@ -249,7 +263,7 @@ declare abstract class State {
    * @param silent - If true, listeners will not be notified. If state is destroyed, stores the update without reporting it.
    * @returns Array of keys updated, syncronously contains keys updated immediately and may be resolved (to itself) when all updates are settled.
    */
-  set(assign?: State.Assign<this>, silent?: boolean): State.Updated<this>;
+  set(assign?: Model.Assign<this>, silent?: boolean): Model.Updated<this>;
   /**
    * Call a function when update occurs.
    *
@@ -263,7 +277,7 @@ declare abstract class State {
    * @param callback - Function to call when update occurs.
    * @returns Function to remove listener. Will return `true` if removed, `false` if inactive already.
    */
-  set(callback: State.OnEvent<this>): () => boolean;
+  set(callback: Model.OnEvent<this>): () => boolean;
   /**
    * Push an update. This will not change the value of associated property.
    *
@@ -278,7 +292,7 @@ declare abstract class State {
    * @param key - Property or event to dispatch.
    * @returns Promise resolves an array of keys updated.
    */
-  set(key: State.Event<this>): State.Updated<this>;
+  set(key: Model.Event<this>): Model.Updated<this>;
   /**
    * Declare an end to updates. This event is final - later writes are stored but never dispatched.
    * This event can be watched for as well, to run cleanup logic and internally will remove all listeners.
@@ -295,7 +309,7 @@ declare abstract class State {
    * @param callback - Function to call when event occurs.
    * @returns Function to remove listener.
    */
-  set<K extends State.Event<this>>(event: K | null, callback: State.OnEvent<this>): () => boolean;
+  set<K extends Model.Event<this>>(event: K | null, callback: Model.OnEvent<this>): () => boolean;
   /**
    * Define or update a managed property using a descriptor config.
    * If the property already is managed, config will only accept value.
@@ -305,9 +319,9 @@ declare abstract class State {
    * @param config - Descriptor config with value, get, set, enumerable, and/or destroy.
    * @returns Promise resolves an array of keys updated.
    */
-  set<K extends State.Event<this>>(key: K, config: State.Define<this, K>): State.Updated<this>;
+  set<K extends Model.Event<this>>(key: K, config: Model.Define<this, K>): Model.Updated<this>;
   /**
-   * Iterate over managed properties in this instance of State.
+   * Iterate over managed properties in this instance of Model.
    * Yeilds the key and current value for each property.
    */
   [Symbol.iterator](): Iterator<[string, unknown]>;
@@ -318,16 +332,16 @@ declare abstract class State {
    *
    * @param args - arguments sent to constructor
    */
-  static new<T extends State>(this: State.Type<T>, ...args: State.Args<T>): T;
+  static new<T extends Model>(this: Model.Type<T>, ...args: Model.Args<T>): T;
   /**
    * Static equivalent of `x instanceof this`.
    * Determines if provided class is a subtype of this one.
    * If so, language server will make available all static
    * methods and properties of this class.
    */
-  static is<T extends State.Extends>(this: T, maybe: unknown): maybe is T;
+  static is<T extends Model.Extends>(this: T, maybe: unknown): maybe is T;
   /**
-   * Register a lifecycle handler for this State and its subclasses.
+   * Register a lifecycle handler for this Model and its subclasses.
    *
    * Hooks by cadence - `type` (per-class, at bootstrap), `setup` (per-instance,
    * before values are observed), `ready` (per-instance, after `new()`), and
@@ -336,11 +350,11 @@ declare abstract class State {
    *
    * @returns Function to remove the handler.
    */
-  static on<T extends State>(this: State.Extends<T>, setup: NonNullable<State.On<T>['setup']>): () => boolean;
-  static on<T extends State>(this: State.Extends<T>, handler: State.On<T>): () => boolean;
+  static on<T extends Model>(this: Model.Extends<T>, setup: NonNullable<Model.On<T>['setup']>): () => boolean;
+  static on<T extends Model>(this: Model.Extends<T>, handler: Model.On<T>): () => boolean;
 }
 /** Bind own configurable methods of a type and collect its reactive getters. */
-declare function classify(type: State.Extends, keys: Map<string, (value: any) => void>, getters: Map<string, () => unknown>): void;
+declare function classify(type: Model.Extends, keys: Map<string, (value: any) => void>, getters: Map<string, () => unknown>): void;
 /**
  * Install a reactive computed property on a state instance, derived from a prototype
  * getter or an arity-bearing `set` factory.
@@ -349,34 +363,34 @@ declare function classify(type: State.Extends, keys: Map<string, (value: any) =>
  * reads of managed properties through it create subscriptions. Result is cached and
  * emits a keyed event when stale.
  */
-declare function compute(this: State, getter: (self: any) => unknown, key: string): void;
+declare function compute(this: Model, getter: (self: any) => unknown, key: string): void;
 /**
  * Define or update a managed property using a descriptor config.
  * If the property already is managed, config will only accept value.
  * If the property does not exist, it will be created and made reactive.
  *
- * @param state - State to apply property to.
+ * @param state - Model to apply property to.
  * @param key - Property to define or update.
  * @param config - Descriptor config with value, get, set, enumerable, and/or destroy.
  * @param silent - If an update does occur, listeners will not be refreshed automatically.
  */
-declare function apply(state: State, key: string, config: State.Apply, silent?: boolean): void;
+declare function apply(state: Model, key: string, config: Model.Apply, silent?: boolean): void;
 /**
- * Pending States constructed after this one - in a parent, the products of
+ * Pending Models constructed after this one - in a parent, the products of
  * its own initializers, until the last one it kept.
  */
-declare function trailing(state: State): State[];
+declare function trailing(state: Model): Model[];
 /**
- * Report States adopted by a parent - those already held, then each one
+ * Report Models adopted by a parent - those already held, then each one
  * claimed later. Returns a callback to stop watching.
  */
-declare function children(state: State, callback: (child: State) => void): () => boolean;
+declare function children(state: Model, callback: (child: Model) => void): () => boolean;
 /**
- * Report States owned by this one - those active now, then each one as it
- * activates. A function returned by `callback` runs when that State is destroyed.
+ * Report Models owned by this one - those active now, then each one as it
+ * activates. A function returned by `callback` runs when that Model is destroyed.
  */
-declare function owned(state: State, callback: (child: State) => void | (() => void)): () => undefined;
-declare function access(state: State, property: string, required?: boolean): any;
+declare function owned(state: Model, callback: (child: Model) => void | (() => void)): () => undefined;
+declare function access(state: Model, property: string, required?: boolean): any;
 /**
  * Update a property on a state instance and notify listeners.
  *
@@ -384,14 +398,14 @@ declare function access(state: State, property: string, required?: boolean): any
  *
  * A destroyed state stores the write without dispatch, reports it unless `silent`, and returns `false`.
  */
-declare function update<T>(state: State, key: State.Event<T>, value: T, silent?: boolean, own?: boolean): boolean;
+declare function update<T>(state: Model, key: Model.Event<T>, value: T, silent?: boolean, own?: boolean): boolean;
 /**
  * Hand a value stored by an owning writer to that property's adopter,
- * creating one the first time a State is stored there. A property which has
- * held a State keeps its adopter, so a later non-State value releases the
+ * creating one the first time a Model is stored there. A property which has
+ * held a Model keeps its adopter, so a later non-Model value releases the
  * previous child.
  */
-declare function adopt(state: State, key: unknown, value: unknown): void;
+declare function adopt(state: Model, key: unknown, value: unknown): void;
 /** Random alphanumberic of length 6; always starts with a letter. */
 declare function uid(): string;
 declare function unbind<T extends Function>(fn: T): T;
@@ -402,8 +416,8 @@ declare function unbind<T extends Function>(fn?: T): T | undefined;
  * only if unclaimed and returns whether the assignment applied - `true` means
  * this call freshly claimed it, `false` means it was already parented.
  */
-declare function parent(child: object): State | null | undefined;
-declare function parent(child: object, value: State | null): boolean;
+declare function parent(child: object): Model | null | undefined;
+declare function parent(child: object, value: Model | null): boolean;
 //#endregion
-export { GETTERS, type Handler, LATEST, METHODS, PENDING, SETUP, STORE, State, UNBIND, access, adopt, apply, children, classify, compute, event, owned, parent, trailing, uid, unbind, update };
+export { GETTERS, type Handler, LATEST, METHODS, Model, PENDING, SETUP, STORE, UNBIND, access, adopt, apply, children, classify, compute, event, owned, parent, trailing, uid, unbind, update };
 //# sourceMappingURL=state.d.ts.map