import { DepItem } from './_computed_queue'; import { IDisposableOwnerT } from './dispose'; import { BaseObservable as Obs, Observable } from './observable'; import { ISubscribable, UseCBOwner as UseCB } from './subscribe'; /** @internal */ type Owner = IDisposableOwnerT> | null; /** * `Computed` implements a computed observable, whose value depends on other observables and gets * recalculated automatically when they change. * * E.g. if we have some existing observables (which may themselves be instances of `Computed`), * we can create a computed that subscribes to them explicitly: * ```ts * const obs1 = Observable.create(null, 5), obs2 = Observable.create(null, 12); * const computed1 = Computed.create(null, obs1, obs2, (use, v1, v2) => v1 + v2); * ``` * * or implicitly by using `use(obs)` function: * ```ts * const computed2 = Computed.create(null, use => use(obs1) + use(obs2)); * ``` * * In either case, `computed1.get()` and `computed2.get()` will have the value 17. If `obs1` or * `obs2` is changed, `computed1` and `computed2` will get recomputed automatically. * * Creating a computed allows any number of dependencies to be specified explicitly, and their * values will be passed to the `read()` callback. These may be combined with automatic dependencies * detected using `use()`. Note that constructor dependencies have less overhead. * ```ts * const val = Computed.create(null, ...deps, ((use, ...depValues) => READ_CALLBACK)); * ``` * * You may specify a `write` callback by calling `onWrite(WRITE_CALLBACK)`, which will be called * whenever `set()` is called on the computed by its user. If a `write` bacllback is not specified, * calling `set` on a computed observable will throw an exception. * * Note that `PureComputed` offers a variation of `Computed` with the same interface, but which * stays unsubscribed from dependencies while it itself has no subscribers. * * A computed may be used with a disposable value using `use.owner` as the value's owner. E.g. * ```ts * const val = Computed.create(null, ((use) => Foo.create(use.owner, use(a), use(b))); * ``` * * When the `Computed` is re-evaluated, and when it itself is disposed, it disposes the previously * owned value. Note that only the pattern above works, i.e. `use.owner` may only be used to take * ownership of the same disposable that the callback returns. */ export declare class Computed extends Observable { /** * Creates a new Computed, owned by the given owner. * @param owner - Object to own this Computed, or null to handle disposal manually. * @param observables - Zero or more observables on which this computes depends. The callback * will get called when any of these changes. * @param callback - Read callback that will be called with `(use, ...values)`, * i.e. the `use` function and values for all of the `...observables`. The callback is called * immediately and whenever any dependency changes. * @returns The newly created `Computed` observable. */ static create(owner: Owner, cb: (use: UseCB) => T): Computed; static create(owner: Owner, a: Obs, cb: (use: UseCB, a: A) => T): Computed; static create(owner: Owner, a: Obs, b: Obs, cb: (use: UseCB, a: A, b: B) => T): Computed; static create(owner: Owner, a: Obs, b: Obs, c: Obs, cb: (use: UseCB, a: A, b: B, c: C) => T): Computed; static create(owner: Owner, a: Obs, b: Obs, c: Obs, d: Obs, cb: (use: UseCB, a: A, b: B, c: C, d: D) => T): Computed; static create(owner: Owner, a: Obs, b: Obs, c: Obs, d: Obs, e: Obs, cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): Computed; private _callback; private _write; private _sub; constructor(callback: (use: UseCB, ...args: any[]) => T, dependencies: ISubscribable[]); /** * Used by subscriptions to keep track of dependencies. * @internal */ _getDepItem(): DepItem; /** * "Sets" the value of the computed by calling the write() callback if one was provided in the * constructor. Throws an error if there was no such callback (not a "writable" computed). * @param value - The value to pass to the write() callback. */ set(value: T): void; /** * Set callback to call when this.set(value) is called, to make it a writable computed. If not * set, attempting to write to this computed will throw an exception. */ onWrite(writeFunc: (value: T) => void): Computed; /** * Disposes the computed, unsubscribing it from all observables it depends on. */ dispose(): void; private _read; } /** * Creates a new Computed. * @param observables - The initial params, of which there may be zero or more, are * observables on which this computed depends. When any of them change, the `read()` callback * will be called with the values of these observables as arguments. * @param readCallback - Read callback that will be called with `(use, ...values)`, * i.e. the `use` function and values for all of the `...observables`. The callback is called * immediately and whenever any dependency changes. * @returns The newly created `Computed` observable. */ export declare function computed(cb: (use: UseCB) => T): Computed; export declare function computed(a: Obs, cb: (use: UseCB, a: A) => T): Computed; export declare function computed(a: Obs, b: Obs, cb: (use: UseCB, a: A, b: B) => T): Computed; export declare function computed(a: Obs, b: Obs, c: Obs, cb: (use: UseCB, a: A, b: B, c: C) => T): Computed; export declare function computed(a: Obs, b: Obs, c: Obs, d: Obs, cb: (use: UseCB, a: A, b: B, c: C, d: D) => T): Computed; export declare function computed(a: Obs, b: Obs, c: Obs, d: Obs, e: Obs, cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): Computed; export {};