@expressive/mvc 0.33.0 → 0.35.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+type Async<T = any, Y extends any[] = any> = {
+    (...args: Y): Promise<T>;
+    active: boolean;
+};
+/**
+ * Sets an exotic method with managed ready-state. Property accepts an async function.
+ *
+ * When a run-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.
+ */
+declare function run<T, Y extends any[]>(action: (...args: Y) => T | Promise<T>): Async<T, Y>;
+
+type Predicate = (key: string) => boolean | void;
+declare namespace Model {
+    /** Any type of Model, using own class constructor as its identifier. */
+    type Type<T extends Model = Model> = abstract new (...args: any[]) => T;
+    /** A type of Model which may be created without constructor arguments. */
+    type New<T extends Model = Model> = (new () => T) & typeof Model;
+    /** Subset of `keyof T` which are not methods or defined by base Model U. **/
+    type Key<T> = Exclude<keyof T, keyof Model> & string;
+    type Any<T> = Exclude<keyof T, keyof Model> | (string & {});
+    /** Actual value stored in state. */
+    type Value<R> = R extends Ref<infer T> ? T : R extends Model ? Export<R> : R;
+    type ValueOf<T extends Model, K extends Any<T>> = K extends keyof T ? T[K] extends Ref<infer V> ? V : T[K] : unknown;
+    /**
+     * Values from current state of given controller.
+     * Differs from `Values` as values here will drill
+     * into "real" values held by exotics like ref.
+     */
+    type Export<T> = {
+        [P in Key<T>]: Value<T[P]>;
+    };
+    /** Object comperable to data found in T. */
+    type Values<T> = {
+        [P in Key<T>]?: Value<T[P]>;
+    };
+    /** 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 values change. */
+    type Effect<T> = (this: T, argument: T) => Callback | Promise<void> | null | void;
+    type Event = (key: string) => Callback | void;
+    namespace Instruction {
+        type Getter<T> = (source: Model) => T;
+        type Setter<T> = (value: T, previous: T) => boolean | void | (() => T);
+        type Descriptor<T = any> = {
+            get?: Getter<T> | boolean;
+            set?: Setter<T> | false;
+            enumerable?: boolean;
+            value?: T;
+        };
+    }
+    /**
+     * Property initializer, will run upon instance creation.
+     * Optional returned callback will run when once upon first access.
+     */
+    type Instruction<T = any, M extends Model = any> = (this: M, key: Model.Key<M>, thisArg: M, state: Model.Export<M>) => Instruction.Descriptor<T> | Instruction.Getter<T> | void;
+}
+interface Model {
+    /**
+     * Loopback to instance of this model. 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;
+}
+declare class Model {
+    constructor(id?: string | number);
+    /** Pull current values from state. Flattens all models and exotic values amongst properties. */
+    get(): Model.Export<this>;
+    /** Run a function which will run automatically when accessed values change. */
+    get(effect: Model.Effect<this>): Callback;
+    get<T extends string>(key: T, required: true): Exclude<Model.ValueOf<this, T>, undefined>;
+    get<T extends string>(key: T, required?: boolean): Model.ValueOf<this, T>;
+    /**
+     * Check if update is in progress.
+     * Returns a promise which resolves updated keys. If no update, will resolve `false`.
+     **/
+    set(): Promise<Model.Values<this> | false>;
+    /**
+     * Expect an update to state within a set timeout.
+     *
+     * @param timeout - milliseconds to wait for update
+     * @param predicate - optional function to filter for specific updates. If returns true, update is accepted.
+     *
+     * @returns a promise to resolve when next accepted update has occured.
+     */
+    set(timeout: number, predicate?: Predicate): Promise<Model.Values<this>>;
+    /**
+     * Call a function whenever an update to state has occured.
+     *
+     * @param callback - Function to call when any update occurs.
+     *   Note: This will be called for every assignment which changes the value.
+     *   To run logic on final value only, this callback may return a function.
+     *   Returning the same function for the same (or multiple for that matter)
+     *   will ensure it is only called once.
+     *
+     * @returns a function to remove listener. Will return true if listener did exist.
+    */
+    set(callback: Model.Event): () => boolean;
+    /**
+     * Push an update without changing the value of associated property.
+     *
+     * This is useful where a property value internally has changed, but the object remains the same.
+     * For example: an array which has pushed a new value, or change to nested properties.
+     */
+    set(key: string | null): void;
+    /**
+     * Update a property programatically within state.
+     *
+     * @param key - property to update
+     * @param value - value to update property with (if the same as current, no update will occur)
+     * @param silent - if true, will not notify listeners of an update
+     */
+    set<K extends string>(key: K, value?: Model.ValueOf<this, K>, silent?: boolean): void;
+    /** Iterate over managed properties in this instance of Model. */
+    [Symbol.iterator](): Iterator<[string, unknown]>;
+    /**
+     * Creates a new instance of this controller.
+     *
+     * Beyond `new this(...)`, method will activate managed-state.
+     *
+     * @param args - arguments sent to constructor
+     */
+    static new<T extends typeof Model>(this: T, ...args: ConstructorParameters<T>): InstanceType<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 Model.Type>(this: T, maybe: any): maybe is T;
+}
+declare function add<T = any, M extends Model = any>(instruction: Model.Instruction): T;
+
+declare namespace get {
+    type Function<T, S = any> = (this: S, on: S) => T;
+    type Factory<R, T> = (this: T, property: string, on: T) => Function<R, T>;
+    type Source<T extends Model = Model> = (resolve: (x: T) => void) => void;
+}
+/**
+ * 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 Type - Type of controller compatible with this class.
+ * @param required - If true, will throw if Model is created without a parent.
+ */
+declare function get<T extends Model>(Type: Model.Type<T>, required?: true): 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 Type - Type of controller compatible with this class.
+ * @param required - If false, property may be undefined. Otherwise will throw suspense.
+ */
+declare function get<T extends Model>(Type: Model.Type<T>, required: boolean): T | undefined;
+/**
+ * Implement a computed value from a foreign model. Output will be generated by provided function,
+ * where the foreign model will be passed to that function.
+ *
+ * @param source - Type of Model to fetch for computation.
+ * @param compute - Compute function. Will update automatically as input values change.
+ */
+declare function get<R, T extends Model>(Type: Model.Type<T>, compute: (this: T, on: 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.
+ */
+declare function get<R, T extends Model>(source: T, compute: (this: T, on: T) => R): R;
+/**
+ * Implement a computed value; output is returned by function from provided factory.
+ *
+ * @param compute - Factory function to generate a getter to subscribe dependancies.
+ */
+declare function get<R, T>(compute: (property: string, on: T) => (this: T, state: T) => R): R;
+
+declare namespace ref {
+    type Callback<T> = (argument: T) => ((next: T | null) => void) | Promise<void> | void | boolean;
+    interface Object<T = any> {
+        (next: T | null): void;
+        current: T | null;
+    }
+    /** Object with references to all managed values of `T`. */
+    type Proxy<T extends Model> = {
+        [P in Model.Key<T>]-?: Model.Ref<T[P]>;
+    };
+    type CustomProxy<T extends Model, R> = {
+        [P in Model.Key<T>]-?: R;
+    };
+}
+/**
+ * Creates an object with references to all managed values.
+ * Each property is a function to 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.
+ */
+declare function ref<T extends Model>(target: T): ref.Proxy<T>;
+/**
+ * Creates an object with values based on managed values.
+ * Each property will invoke mapper function on first access supply
+ * the its return value going forward.
+ *
+ * @param target - Source model from which to reference values.
+ * @param mapper - Function producing the placeholder value for any given property.
+ */
+declare function ref<O extends Model, R>(target: O, mapper: (key: Model.Key<O>) => R): ref.CustomProxy<O, R>;
+/**
+ * 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.
+ */
+declare function ref<T = HTMLElement>(callback?: ref.Callback<T>): ref.Object<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.
+ * @param ignoreNull - Default `true`. If `false`, will still callback with `null`.
+ */
+declare function ref<T = HTMLElement>(callback: ref.Callback<T | null>, ignoreNull: boolean): ref.Object<T>;
+
+declare namespace set {
+    type Callback<T, S = any> = (this: S, next: T, previous: T) => ((next: T) => void) | Promise<any> | void | boolean;
+    type Factory<T, S = any> = (this: S, key: string, thisArg: S) => Promise<T> | T;
+}
+/**
+ * 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.
+ */
+declare function set<T = any>(): T;
+/**
+ * Set property with a factory function.
+ *
+ * Run factory only if/when accessed. Value will be undefined until
+ * factory resolves, which will also dispatch an update for the property.
+ */
+declare function set<T>(factory: set.Factory<T> | Promise<T>, required: false): T | undefined;
+/**
+ * Set property with a factory function.
+ *
+ * If async, property cannot be accessed until resolves, yeilding a result.
+ * If accessed while still processing, React Suspense will be thrown.
+ *
+ * @param factory - Callback run to derrive property value.
+ * @param required - If true run factory immediately on creation, otherwise on access.
+ */
+declare function set<T>(factory: set.Factory<T> | Promise<T>, required?: boolean): T;
+/**
+ * Set a property with empty placeholder and update callback.
+ *
+ * @param value - Starting value for property. If undefined, suspense will be thrown on access, until value is set and accepted by callback.
+ * @param onUpdate - Callback run when property is set. If returns false, update is not accepted and property will keep previous value.
+ */
+declare function set<T>(value: T | undefined, onUpdate: set.Callback<T>): T;
+
+declare namespace use {
+    type Object<T extends {}> = T;
+}
+/** Create a placeholder for specified Model type. */
+declare function use<T extends Model>(): T | undefined;
+/** Create a new child instance of model. */
+declare function use<T extends Model>(Type: Model.New<T>, ready?: (i: T) => void): T;
+/**
+ * Use existing model as a child of model assigned to.
+ *
+ * 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, however, if
+ * already active.
+ **/
+declare function use<T extends Model>(model: T, ready?: (i: T) => void): T;
+/** Create a managed object with observable entries. */
+declare function use<T extends {}, O = use.Object<T>>(data: T, ready?: (object: O) => void): O;
+
+declare namespace Context {
+    type Inputs = {
+        [key: string | number]: Model | Model.New;
+    };
+}
+declare class Context {
+    static resolve(from: Model, callback: (context: Context) => void): void;
+    constructor(inputs?: Context.Inputs);
+    key: string;
+    private table;
+    private layer;
+    private has;
+    get<T extends Model>(Type: Model.Type<T>): T | undefined;
+    include(inputs: Context.Inputs): Map<Model, boolean>;
+    protected add<T extends Model>(input: T | Model.New<T>, implicit?: boolean): T;
+    push(): this;
+    pop(): void;
+}
+
+export { Context, Model, add, Model as default, get, ref, run, set, use };