@expressive/mvc 0.73.0 → 0.78.0

package/dist/state.d.ts

@@ -0,0 +1,311 @@
+import { Context } from "./context.js";
+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>>;
+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)[];
+  /**
+   * State 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. A bare `Init`
+   * function passed to `on` is sugar for `{ before }`.
+   */
+  interface On<T extends State = State> {
+    /**
+     * 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;
+    /**
+     * Per-instance setup, run in the `prepare` phase before `observe` and the
+     * `new()` hook. Equivalent to passing a bare function to `on`. May return a
+     * cleanup, constructor args, or an assign overlay.
+     */
+    before?(this: T, thisArg: T): void | (() => void) | Promise<void> | Args<T> | Assign<T>;
+    /**
+     * Per-instance setup, run at the `new()` slot - after own values are
+     * observed and constructor args applied. May return a cleanup function.
+     */
+    after?(this: T, self: T): void | (() => void);
+  }
+  /** Object overlay to override values and methods on a state. */
+  type Assign<T> = Record<string, unknown> & { [K in Field<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 Field<T> = Exclude<keyof T, keyof State>;
+  /** Any valid key for state, including but not limited to Field<T>. */
+  type Event<T = State> = 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 {
+    get(): infer T;
+  } ? T : R;
+  /**
+   * Values from current state of given state.
+   * Differs from `Values` as values here will drill
+   * into "real" values held by exotics like ref.Object.
+   */
+  type Values<T> = { [P in Field<T>]: Export<T[P]> };
+  /** 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 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;
+    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;
+  /** Exotic value, where actual value is contained within. */
+  type Ref<T = any> = {
+    (next: T): void;
+    current: T | null;
+  };
+  /**
+   * A callback function which is subscribed to parent and updates when accessed properties change.
+   *
+   * @param current - Current state of this state. This is a proxy which detects properties which
+   * where accessed, and thus depended upon to stay current.
+   *
+   * @param update - Set of properties which have changed, and events fired, since last update.
+   *
+   * @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;
+  /**
+   * A callback function returned by effect. Will be called when effect is stale.
+   *
+   * @param update - `true` if update is pending, `false` effect has been cancelled, `null` if state is destroyed.
+   */
+  type EffectCallback = (update: boolean | null) => void;
+  /**
+   * 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>[]>;
+}
+declare abstract class State {
+  /**
+   * 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);
+  /**
+   * Optional lifecycle hook called during State initialization.
+   * Can return a cleanup function to run when state is destroyed.
+   *
+   * It is recommended you protect this method.
+   */
+  protected new?(): void | (() => void);
+  /**
+   * Pull current values from state. Flattens all states and exotic values recursively.
+   *
+   * @returns Object with all values from this state.
+   **/
+  get(): State.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.
+   */
+  get(effect: State.Effect<this>): () => void;
+  /**
+   * Get value of a property. Will fetch underlying value from exotic values like ref.Object.
+   *
+   * Any value which implements `get()` (with no arguments) will be treated as such.
+   *
+   * @param key - Property to get value of.
+   * @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>;
+  /**
+   * Check if state is destroyed.
+   *
+   * @param status - `null` to check if state is destroyed.
+   * @returns `true` if state is destroyed, `false` otherwise.
+   */
+  get(status: null): boolean;
+  /**
+   * Callback when state is to be destroyed.
+   *
+   * @param callback - Function to call when state is destroyed.
+   * @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;
+  /**
+   * Subscribe to State becoming available in context.
+   *
+   * Will search both up and downstream by default.
+   * Normally you can ignore this because State 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.
+   *
+   * @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.
+   * @returns Function to cancel listener.
+   */
+  get<T extends State>(type: State.Type<T>, callback: Context.Expect<T>, downstream?: boolean): () => void;
+  /**
+   * Get update in progress.
+   *
+   * @returns Promise which resolves object with updated values, `undefined` if there no update is pending.
+   **/
+  set(): State.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.
+   *
+   * @param assign - Object with properties to update.
+   * @param silent - If true, listeners will not be notified. If state is destroyed, will squash update without throwing.
+   * @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>;
+  /**
+   * Call a function when update occurs.
+   *
+   * Given function is called for every assignment (which changes value) or explicit `set`.
+   *
+   * To run logic on final value only, callback may return a function. The same
+   * function for one or more events will be called only once when update is settled.
+   *
+   * Return `null` from callback to stop listening.
+   *
+   * @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;
+  /**
+   * Push an update. This will not change the value of associated property.
+   *
+   * Useful where a property value internally has changed, but the object is the same.
+   * For example: An array has pushed a new value, or a nested property is updated.
+   *
+   * You can also use this to dispatch arbitrary events.
+   * Symbols are recommended as non-property events, however you can use any string.
+   * If doing so, be sure to avoid collisions using property names. An easy way to do this is
+   * to prefix an event with "!" and/or use dash-case. e.g. `set("!event")` or `set("my-event")`.
+   *
+   * @param key - Property or event to dispatch.
+   * @returns Promise resolves an array of keys updated.
+   */
+  set(key: State.Event<this>): State.Updated<this>;
+  /**
+   * Declare an end to updates. This event is final and will freeze state.
+   * This event can be watched for as well, to run cleanup logic and internally will remove all listeners.
+   *
+   * @param status - `null` to end updates.
+   */
+  set(status: null): void;
+  /**
+   * Register a callback for a specific property or event.
+   *
+   * Callback receives the key, current value, and source instance.
+   *
+   * @param event - Property or event to watch. If `null`, will callback on destroy.
+   * @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;
+  /**
+   * 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 key - Property to define or update.
+   * @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>;
+  /**
+   * Iterate over managed properties in this instance of State.
+   * Yeilds the key and current value for each property.
+   */
+  [Symbol.iterator](): Iterator<[string, unknown]>;
+  /**
+   * Create and activate a new instance of this state.
+   *
+   * **Important** - Unlike `new this(...)` - this method also activates state.
+   *
+   * @param args - arguments sent to constructor
+   */
+  static new<T extends State>(this: State.Type<T>, ...args: State.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;
+  /**
+   * Register a lifecycle handler for this State and its subclasses.
+   *
+   * A bare function is per-instance setup run in the `prepare` phase (sugar for
+   * `{ before }`); if it returns a function, that runs when the instance is
+   * destroyed. Pass a {@link State.On} object to hook by cadence - `type`
+   * (per-class, at bootstrap), `before` (per-instance, before `new()`), and
+   * `after` (per-instance, at the `new()` slot).
+   *
+   * @returns Function to remove the handler.
+   */
+  static on<T extends State>(this: State.Extends<T>, handler: State.Init<T> | State.On<T>): () => boolean;
+}
+/**
+ * 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 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 access(state: State, property: string, required?: boolean): any;
+/**
+ * Update a property on a state instance and notify listeners.
+ *
+ * This is used internally to update properties, but can also be used to update properties which are not managed by state, or to update values without triggering setters.
+ *
+ * If `silent` is true, the update will not dispatch events and will return `false` instead of throwing if state is destroyed.
+ */
+declare function update<T>(state: State, key: State.Event<T>, value: T, silent?: boolean): boolean;
+/** Random alphanumberic of length 6; always starts with a letter. */
+declare function uid(): string;
+declare function unbind<T extends Function>(fn: T): T;
+declare function unbind<T extends Function>(fn?: T): T | undefined;
+/**
+ * Get or set a parent on given state. May only be assigned once; ignores new value.
+ * Returns parent of child, or `undefined` if not assigned yet.
+ */
+declare function parent(child: State, value?: State | null): State | null | undefined;
+//#endregion
+export { STORE, State, access, apply, event, parent, uid, unbind, update };
+//# sourceMappingURL=state.d.ts.map