/** base type definitions <br>
 * @module
*/
/** type definition for a value equality check function. */
export type EqualityFn<T> = (prev_value: T | undefined, new_value: T) => boolean;
/** type definition for an equality check specification. <br>
 * when `undefined`, javascript's regular `===` equality will be used. <br>
 * when `false`, equality will always be evaluated to false, meaning that setting any value will always fire a signal, even if it's equal.
*/
export type EqualityCheck<T> = undefined | false | EqualityFn<T>;
/** the {@link Signal.id | `id`} of a signal is simply a number. */
export type ID = number;
/** another way of saying the dependency (or source) signal id. */
export type FROM_ID = ID;
/** another way of saying the observer (or destination) signal id. */
export type TO_ID = ID;
/** the {@link Signal.rid | runtime id (`rid`)} of a signal becomes zero after its first run (because it has captured all of its dependencies). */
export type UNTRACKED_ID = 0;
/** the hash value generated by the dfs-signal-dag-traversal hash function. */
export type HASHED_IDS = number;
/** type definition for an incremental updater function. */
export type Updater<T> = (prev_value?: T) => T;
/** type definition for a signal accessor (value getter) function. */
export type Accessor<T> = ((observer_id?: TO_ID | UNTRACKED_ID) => T);
/** type definition for a signal value setter function. */
export type Setter<T> = ((new_value: T | Updater<T>) => boolean);
/** type definition for an async signal value setter function. <br>
 * TODO: should an `AsyncSetter<T>` return a `Promise<T>` ? or should it return a `Promise<boolean>`, which should tell whether or not the value has changed (i.e. `!signal.equal(old_value, new_value)`)
*/
export type AsyncSetter<T> = (new_value: (T | Promise<T | Updater<T>>) | Updater<T | Promise<T | Updater<T>>>, rejectable?: boolean) => Promise<T>;
/** type definition for when a signal's _update_ function `run` is called by the signal update propagator `propagateSignalUpdate` inside of {@link context!Context}. <br>
 * the return value should indicate whether this signal has:
 * - updated ({@link SignalUpdateStatus.UPDATED} === 1), and therefore propagate to its observers to also run
 * - unchanged ({@link SignalUpdateStatus.UNCHANGED} === 0), and therefore not propagate to its observers
 * - aborted ({@link SignalUpdateStatus.ABORTED} === -1), and therefore force each of its observers to also become non propagating and inherit the {@link SignalUpdateStatus.ABORTED} status
*/
export type Runner = () => SignalUpdateStatus;
/** the abstraction that defines what a signal is. */
export interface Signal<T> {
    /** id of this signal in the {@link context!Context} in which it exists. */
    id: number;
    /** runtime-id of this signal. <br>
     * it equals to the {@link id} on the first, so that the dependencies of this signal can be notified of being observed.
     * but once all dependencies have been notified after the first run, this runtime-id should become `0` ({@link UNTRACKED_ID}),
     * so that the dependiencies do not have to re-register this signal as an observer.
    */
    rid: ID | UNTRACKED_ID;
    /** give a name to this signal for debugging purposes */
    name?: string;
    /** get the value of this signal, and handle any observing signal's id ({@link observer_id}). <br>
     * typically, when `observer_id` is non-zero, this signal should handle it by registering it as an
     * observer through the use of the context's {@link context!Context.addEdge} method.
     *
     * @example
     * ```ts
     * const MySignalClass_Factory = (ctx: Context) => {
     * 	const addEdge = ctx.addEdge
     * 	return class MySignal<T> implements Signal<T> {
     * 		declare value: T
     * 		// ...
     * 		get(observer_id?: TO_ID | UNTRACKED_ID): T {
     * 			// register this.id to observer (if non-zero) in the dependency graph as a directed edge
     * 			if (observer_id) { addEdge(this.id, observer_id) }
     * 			return this.value
     * 		}
     * 		// ...
     * 	}
     * }
     * ```
    */
    get(observer_id?: TO_ID | UNTRACKED_ID): T;
    /** set the value of this signal. <br>
     * the meaning of setting a signal's value greatly varies from signal to signal, which is why it is so abstracted. <br>
     * however, the returning value must always be a `boolean` describing whether or not this signal's value has changed compared to its previous value. <br>
     * what makes use of the returned value again greatly varies from signal to signal.
     * but it is typically used by the {@link run} method to decide whether or not this signal should propagate. <br>
     * another purpose of the set method is typically to _initiate_ the ignition of an update cycle in a context, bu using {@link context!Context.runId}.
     * this is how {@link signal!StateSignal}s and {@link signal!EffectSignal}s begin an update cycle when their values have changed from the prior value.
     *
     * @example
     * ```ts
     * const MySignalClass_Factory = (ctx: Context) => {
     * 	const runId = ctx.runId
     * 	return class MySignal<T> implements Signal<T> {
     * 		declare value: T
     * 		// ...
     * 		set(new_value: T): boolean {
     * 			const value_has_changed = new_value !== this.value
     * 			if (value_has_changed) {
     * 				runId(this.id)
     * 				return true
     * 			}
     * 			return false
     * 		}
     * 		// ...
     * 	}
     * }
     * ```
    */
    set?(...args: any[]): boolean;
    /** specify actions that need to be taken __before__ an update cycle has even begun propagating. <br>
     * TODO: CURRENTLY NOT IMPLEMENTED.
     * ISSUE: what should the order in which prepruns run be? we do know the FULL set of signal ids that will be visited.
     *   but we do not know the subset of ids that WILL BE affected and ran, not until run time of the signal propagation.
     *   should ids that _might_ be affected also have their preruns ran? and in what order? because we cannot know the order until propagation runtime.
    */
    prerun?(): void;
    /** run the actions taken by a signal when it is informed that its dependency signals have been modified/changed. <br>
     * the return value should be of the numertic enum kind {@link SignalUpdateStatus}, which specifies that this signal has been either been:
     * - ` 1`: updated, and therefore this signal's observers should be notified (i.e. _ran_ via their `run` method)
     * - ` 0`: unchanged, and therefore this signal's observers should be notified if this is their only active dependency
     * - `-1`: aborted, and therefore this signal's observer should also abort their `run` method's execution if they were queued
     *
     * this method may also accept an optional `forced` parameter, which tells the signal that it is
     * being _forced_ to run, even though none of its dependency signals have been executed or changed.
     * this information is useful when coding for signals that _can_ be fired independently, such as {@link signal!StateSignal} or {@link signal!EffectSignal}.
     *
     * @param forced was this signal _forced_ to run independently?
     * @returns the update status of this signal, specifying whether or not it has changed, or if it has been aborted
    */
    run(forced?: boolean): SignalUpdateStatus;
    /** specify actions that need to be taken __after__ an update cycle has fully propagated till the end. <br>
     * the order in which `postrun`s will be executed will be in the reverse order in which they were first encountered (i.e: last in, last out).
     * meaning that if all three signals `A`, `B`, and `C`, had `postrun` methods on them, and the order of execution was:
     * `A -> B -> C`, then all `postrun`s will run in the order: `[C.postrun, B.postrun, A.postrun]` (similar to a stack popping).
    */
    postrun?(): void;
    /** a utility method defined in {@link signal!SimpleSignal}, which allows one to bind a certain method (by name) to _this_ instance of a signal,
     * and therefore make that method freeable/seperable from _this_ signal. <br>
     * this method is used by all signal classes's static {@link SignalClass.create} method, which is supposed to construct a signal in
     * a fashion similar to SolidJS, and return an array containing important control functions of the created signal.
     * most, if not all, of these control function are generally plain old signal methods that have been bounded to the created signal instance.
    */
    bindMethod<M extends keyof this>(method_name: M): this[M];
}
/** the abstraction that defines the static methods which must exist in a signal generating class */
export interface SignalClass {
    new (...args: any[]): Signal<any>;
    create(...args: any[]): [id: ID, ...any[]];
}
/** the numbers used for relaying the status of a signal after it has been _ran_ via its {@link Signal.run | `run method`}. <br>
 * these numbers convey the following instructions to the context's topological update cycle {@link context!Context.propagateSignalUpdate}:
 * - ` 1`: this signal's value has been updated, and therefore its observers should be updated too.
 * - ` 0`: this signal's value has not changed, and therefore its observers should be _not_ be updated.
 *   do note that an observer signal will still run if some _other_ of its dependency signal did update this cycle (i.e. had a status value of `1`)
 * - `-1`: this signal has been aborted, and therefore its observers must abort execution as well.
 *   the observers will abort _even_ if they had a dependency that _did_ update (had a status value of `1`)
 *
 * to sum up, given a signal `D`, with dependencies: `A`, `B`, and `C` (all of which are mutually independent of each other).
 * then the status of `D` will be as follows in the order of highest conditional priority to lowest:
 * | status of D           |          status of D as enum          |                                   condition                                   |
 * |-----------------------|:-------------------------------------:|:-----------------------------------------------------------------------------:|
 * | `status(D) = -1`      | `ABORTED`                             | `∃X ∈ [A, B, C] such that status(X) === -1` |
 * | `status(D) = D.run()` | `CHANGED` or `UNCHANGED` or `ABORTED` | `∃X ∈ [A, B, C] such that status(X) ===  1` |
 * | `status(D) = 0`       | `UNCHANGED`                           | `∀X ∈ [A, B, C], status(X) === 0`           |
*/
export declare const enum SignalUpdateStatus {
    ABORTED = -1,
    UNCHANGED = 0,
    UPDATED = 1
}