@flowgram.ai/reactive 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import React from 'react';
+
+/**
+ * Fork from: https://github.com/meteor/meteor/blob/devel/packages/tracker/tracker.js
+ */
+type ICallback<ARG = void, RET = void> = (arg: ARG) => RET;
+/**
+ * Tracker 是一套 响应式依赖追踪 库，来源于 Meteor.Tracker
+ * https://docs.meteor.com/api/Tracker.html#tracker-autorun-and-async-callbacks
+ * https://github.com/meteor/meteor/blob/devel/packages/tracker/tracker.js
+ *
+ * 相关论文：https://dl.acm.org/doi/fullHtml/10.1145/3184558.3185978
+ */
+declare namespace Tracker {
+    interface FlushOptions {
+        finishSynchronously?: boolean;
+        throwFirstError?: boolean;
+    }
+    /******************************** Tracker Base API ******************************************/
+    /**
+     * 函数在响应式模块中执行
+     * @param computation
+     * @param f
+     */
+    function withComputation<T = any>(computation: Computation, f: ICallback<Computation, T>): T;
+    /**
+     * 函数在非响应式模块中执行
+     */
+    function withoutComputation<T = any>(f: ICallback<undefined, T>): T;
+    function isActive(): boolean;
+    function getCurrentComputation(): Computation | undefined;
+    /**
+     * Run a function now and rerun it later whenever its dependencies
+     * change. Returns a Computation object that can be used to stop or observe the
+     * rerunning.
+     */
+    function autorun<T = any>(f: IComputationCallback<T>, options?: {
+        onError: ICallback<Error>;
+    }): Computation<T>;
+    function onInvalidate(f: ICallback<Computation | undefined>): void;
+    /**
+     * True if we are computing a computation now, either first time or recompute.  This matches Tracker.active unless we are inside Tracker.nonreactive, which nullfies currentComputation even though an enclosing computation may still be running.
+     */
+    function inFlush(): boolean;
+    /**
+     * Process all reactive updates immediately and ensure that all invalidated computations are rerun.
+     */
+    function flush(options?: Omit<FlushOptions, 'finishSynchronously'>): void;
+    /**
+     * Schedules a function to be called during the next flush, or later in the current flush if one is in progress, after all invalidated computations have been rerun.  The function will be run once and not on subsequent flushes unless `afterFlush` is called again.
+     */
+    function afterFlush(f: ICallback): void;
+    /********************************************************************************************/
+    type IComputationCallback<V = any> = ICallback<Computation, V>;
+    /**
+     * A Computation object represents code that is repeatedly rerun
+     * in response to
+     * reactive data changes. Computations don't have return values; they just
+     * perform actions, such as rerendering a template on the screen. Computations
+     * are created using Tracker.autorun. Use stop to prevent further rerunning of a
+     * computation.
+     */
+    class Computation<V = any> {
+        private _fn;
+        readonly parent?: Computation<any> | undefined;
+        private readonly _onError?;
+        private _onInvalidateCallbacks;
+        private _onStopCallbacks;
+        private _recomputing;
+        private _result;
+        /**
+         * 是否停止
+         */
+        stopped: boolean;
+        /**
+         * 未开始执行则返回 false
+         */
+        invalidated: boolean;
+        /**
+         * 是否第一次执行
+         */
+        firstRun: boolean;
+        constructor(_fn: IComputationCallback<V>, parent?: Computation<any> | undefined, _onError?: ICallback<Error, void> | undefined);
+        onInvalidate(f: IComputationCallback): void;
+        /**
+         * @summary Invalidates this computation so that it will be rerun.
+         */
+        invalidate(): void;
+        /**
+         * @summary Prevents this computation from rerunning.
+         * @locus Client
+         */
+        stop(): void;
+        onStop(f: IComputationCallback): void;
+        private _compute;
+        _needsRecompute(): boolean;
+        _recompute(): void;
+        /**
+         * @summary Process the reactive updates for this computation immediately
+         * and ensure that the computation is rerun. The computation is rerun only
+         * if it is invalidated.
+         */
+        flush(): void;
+        /**
+         * @summary Causes the function inside this computation to run and
+         * synchronously process all reactive updtes.
+         * @locus Client
+         */
+        run(): void;
+        get result(): V;
+    }
+    /**
+     * A Dependency represents an atomic unit of reactive data that a
+     * computation might depend on. Reactive data sources such as Session or
+     * Minimongo internally create different Dependency objects for different
+     * pieces of data, each of which may be depended on by multiple computations.
+     * When the data changes, the computations are invalidated.
+     */
+    class Dependency {
+        private _dependents;
+        /**
+         * Declares that the current computation (or `fromComputation` if given) depends on `dependency`.  The computation will be invalidated the next time `dependency` changes.
+         * If there is no current computation and `depend()` is called with no arguments, it does nothing and returns false.
+         * Returns true if the computation is a new dependent of `dependency` rather than an existing one.
+         */
+        depend(computation?: Computation): boolean;
+        /**
+         * Invalidate all dependent computations immediately and remove them as dependents.
+         */
+        changed(): void;
+        /**
+         * True if this Dependency has one or more dependent Computations, which would be invalidated if this Dependency were to change.
+         */
+        hasDependents(): boolean;
+    }
+}
+
+type IStateEqual = (a: any, b: any) => boolean;
+declare class ReactiveBaseState<V> {
+    protected _dep: Tracker.Dependency;
+    protected _value: V;
+    protected _isEqual: IStateEqual;
+    protected _addDepend(dep: Tracker.Dependency): void;
+    constructor(initialValue: V, opts?: {
+        isEqual?: IStateEqual;
+    });
+    hasDependents(): boolean;
+    get value(): V;
+    set value(newValue: V);
+}
+
+declare class ReactiveState<V extends Record<string, any>> extends ReactiveBaseState<V> {
+    private _keyDeps;
+    set(key: keyof V & string, value: any): boolean;
+    get(key: keyof V & string): V[keyof V & string];
+    protected _ensureKey(key: keyof V & string): void;
+    hasDependents(): boolean;
+    keys(): string[];
+    set value(newValue: V);
+    private _proxyValue;
+    get value(): V;
+    private _proxyReadonlyValue;
+    get readonlyValue(): Readonly<V>;
+}
+
+declare function useReactiveState<T extends Record<string, any>>(v: ReactiveState<T> | T): T;
+
+declare function useReadonlyReactiveState<T extends Record<string, any>>(state: ReactiveState<T>): Readonly<T>;
+
+declare function useObserve<T extends Record<string, any>>(value: T | undefined): T;
+
+declare function observe<T = any>(fc: React.FC<T>): React.FC<T>;
+
+declare const Dependency: typeof Tracker.Dependency;
+declare const Computation: typeof Tracker.Computation;
+
+export { Computation, Dependency, ReactiveBaseState, ReactiveState, Tracker, observe, useObserve, useReactiveState, useReadonlyReactiveState };

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+import React from 'react';
+
+/**
+ * Fork from: https://github.com/meteor/meteor/blob/devel/packages/tracker/tracker.js
+ */
+type ICallback<ARG = void, RET = void> = (arg: ARG) => RET;
+/**
+ * Tracker 是一套 响应式依赖追踪 库，来源于 Meteor.Tracker
+ * https://docs.meteor.com/api/Tracker.html#tracker-autorun-and-async-callbacks
+ * https://github.com/meteor/meteor/blob/devel/packages/tracker/tracker.js
+ *
+ * 相关论文：https://dl.acm.org/doi/fullHtml/10.1145/3184558.3185978
+ */
+declare namespace Tracker {
+    interface FlushOptions {
+        finishSynchronously?: boolean;
+        throwFirstError?: boolean;
+    }
+    /******************************** Tracker Base API ******************************************/
+    /**
+     * 函数在响应式模块中执行
+     * @param computation
+     * @param f
+     */
+    function withComputation<T = any>(computation: Computation, f: ICallback<Computation, T>): T;
+    /**
+     * 函数在非响应式模块中执行
+     */
+    function withoutComputation<T = any>(f: ICallback<undefined, T>): T;
+    function isActive(): boolean;
+    function getCurrentComputation(): Computation | undefined;
+    /**
+     * Run a function now and rerun it later whenever its dependencies
+     * change. Returns a Computation object that can be used to stop or observe the
+     * rerunning.
+     */
+    function autorun<T = any>(f: IComputationCallback<T>, options?: {
+        onError: ICallback<Error>;
+    }): Computation<T>;
+    function onInvalidate(f: ICallback<Computation | undefined>): void;
+    /**
+     * True if we are computing a computation now, either first time or recompute.  This matches Tracker.active unless we are inside Tracker.nonreactive, which nullfies currentComputation even though an enclosing computation may still be running.
+     */
+    function inFlush(): boolean;
+    /**
+     * Process all reactive updates immediately and ensure that all invalidated computations are rerun.
+     */
+    function flush(options?: Omit<FlushOptions, 'finishSynchronously'>): void;
+    /**
+     * Schedules a function to be called during the next flush, or later in the current flush if one is in progress, after all invalidated computations have been rerun.  The function will be run once and not on subsequent flushes unless `afterFlush` is called again.
+     */
+    function afterFlush(f: ICallback): void;
+    /********************************************************************************************/
+    type IComputationCallback<V = any> = ICallback<Computation, V>;
+    /**
+     * A Computation object represents code that is repeatedly rerun
+     * in response to
+     * reactive data changes. Computations don't have return values; they just
+     * perform actions, such as rerendering a template on the screen. Computations
+     * are created using Tracker.autorun. Use stop to prevent further rerunning of a
+     * computation.
+     */
+    class Computation<V = any> {
+        private _fn;
+        readonly parent?: Computation<any> | undefined;
+        private readonly _onError?;
+        private _onInvalidateCallbacks;
+        private _onStopCallbacks;
+        private _recomputing;
+        private _result;
+        /**
+         * 是否停止
+         */
+        stopped: boolean;
+        /**
+         * 未开始执行则返回 false
+         */
+        invalidated: boolean;
+        /**
+         * 是否第一次执行
+         */
+        firstRun: boolean;
+        constructor(_fn: IComputationCallback<V>, parent?: Computation<any> | undefined, _onError?: ICallback<Error, void> | undefined);
+        onInvalidate(f: IComputationCallback): void;
+        /**
+         * @summary Invalidates this computation so that it will be rerun.
+         */
+        invalidate(): void;
+        /**
+         * @summary Prevents this computation from rerunning.
+         * @locus Client
+         */
+        stop(): void;
+        onStop(f: IComputationCallback): void;
+        private _compute;
+        _needsRecompute(): boolean;
+        _recompute(): void;
+        /**
+         * @summary Process the reactive updates for this computation immediately
+         * and ensure that the computation is rerun. The computation is rerun only
+         * if it is invalidated.
+         */
+        flush(): void;
+        /**
+         * @summary Causes the function inside this computation to run and
+         * synchronously process all reactive updtes.
+         * @locus Client
+         */
+        run(): void;
+        get result(): V;
+    }
+    /**
+     * A Dependency represents an atomic unit of reactive data that a
+     * computation might depend on. Reactive data sources such as Session or
+     * Minimongo internally create different Dependency objects for different
+     * pieces of data, each of which may be depended on by multiple computations.
+     * When the data changes, the computations are invalidated.
+     */
+    class Dependency {
+        private _dependents;
+        /**
+         * Declares that the current computation (or `fromComputation` if given) depends on `dependency`.  The computation will be invalidated the next time `dependency` changes.
+         * If there is no current computation and `depend()` is called with no arguments, it does nothing and returns false.
+         * Returns true if the computation is a new dependent of `dependency` rather than an existing one.
+         */
+        depend(computation?: Computation): boolean;
+        /**
+         * Invalidate all dependent computations immediately and remove them as dependents.
+         */
+        changed(): void;
+        /**
+         * True if this Dependency has one or more dependent Computations, which would be invalidated if this Dependency were to change.
+         */
+        hasDependents(): boolean;
+    }
+}
+
+type IStateEqual = (a: any, b: any) => boolean;
+declare class ReactiveBaseState<V> {
+    protected _dep: Tracker.Dependency;
+    protected _value: V;
+    protected _isEqual: IStateEqual;
+    protected _addDepend(dep: Tracker.Dependency): void;
+    constructor(initialValue: V, opts?: {
+        isEqual?: IStateEqual;
+    });
+    hasDependents(): boolean;
+    get value(): V;
+    set value(newValue: V);
+}
+
+declare class ReactiveState<V extends Record<string, any>> extends ReactiveBaseState<V> {
+    private _keyDeps;
+    set(key: keyof V & string, value: any): boolean;
+    get(key: keyof V & string): V[keyof V & string];
+    protected _ensureKey(key: keyof V & string): void;
+    hasDependents(): boolean;
+    keys(): string[];
+    set value(newValue: V);
+    private _proxyValue;
+    get value(): V;
+    private _proxyReadonlyValue;
+    get readonlyValue(): Readonly<V>;
+}
+
+declare function useReactiveState<T extends Record<string, any>>(v: ReactiveState<T> | T): T;
+
+declare function useReadonlyReactiveState<T extends Record<string, any>>(state: ReactiveState<T>): Readonly<T>;
+
+declare function useObserve<T extends Record<string, any>>(value: T | undefined): T;
+
+declare function observe<T = any>(fc: React.FC<T>): React.FC<T>;
+
+declare const Dependency: typeof Tracker.Dependency;
+declare const Computation: typeof Tracker.Computation;
+
+export { Computation, Dependency, ReactiveBaseState, ReactiveState, Tracker, observe, useObserve, useReactiveState, useReadonlyReactiveState };