@ersbeth/picoflow 1.0.1 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursor/plans/unifier-flowresource-avec-flowderivation-c9506e24.plan.md +372 -0
- package/README.md +17 -1
- package/biome.json +4 -1
- package/dist/picoflow.js +1155 -582
- package/dist/types/flow/base/flowDisposable.d.ts +67 -0
- package/dist/types/flow/base/flowDisposable.d.ts.map +1 -0
- package/dist/types/flow/base/flowEffect.d.ts +127 -0
- package/dist/types/flow/base/flowEffect.d.ts.map +1 -0
- package/dist/types/flow/base/flowGraph.d.ts +97 -0
- package/dist/types/flow/base/flowGraph.d.ts.map +1 -0
- package/dist/types/flow/base/flowSignal.d.ts +134 -0
- package/dist/types/flow/base/flowSignal.d.ts.map +1 -0
- package/dist/types/flow/base/flowTracker.d.ts +15 -0
- package/dist/types/flow/base/flowTracker.d.ts.map +1 -0
- package/dist/types/flow/base/index.d.ts +7 -0
- package/dist/types/flow/base/index.d.ts.map +1 -0
- package/dist/types/flow/base/utils.d.ts +20 -0
- package/dist/types/flow/base/utils.d.ts.map +1 -0
- package/dist/types/{advanced/array.d.ts → flow/collections/flowArray.d.ts} +50 -12
- package/dist/types/flow/collections/flowArray.d.ts.map +1 -0
- package/dist/types/flow/collections/flowMap.d.ts +224 -0
- package/dist/types/flow/collections/flowMap.d.ts.map +1 -0
- package/dist/types/flow/collections/index.d.ts +3 -0
- package/dist/types/flow/collections/index.d.ts.map +1 -0
- package/dist/types/flow/index.d.ts +4 -0
- package/dist/types/flow/index.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/flowConstantAsync.d.ts +137 -0
- package/dist/types/flow/nodes/async/flowConstantAsync.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/flowDerivationAsync.d.ts +137 -0
- package/dist/types/flow/nodes/async/flowDerivationAsync.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/flowNodeAsync.d.ts +343 -0
- package/dist/types/flow/nodes/async/flowNodeAsync.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts +81 -0
- package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/flowStateAsync.d.ts +111 -0
- package/dist/types/flow/nodes/async/flowStateAsync.d.ts.map +1 -0
- package/dist/types/flow/nodes/async/index.d.ts +6 -0
- package/dist/types/flow/nodes/async/index.d.ts.map +1 -0
- package/dist/types/flow/nodes/index.d.ts +3 -0
- package/dist/types/flow/nodes/index.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/flowConstant.d.ts +108 -0
- package/dist/types/flow/nodes/sync/flowConstant.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/flowDerivation.d.ts +100 -0
- package/dist/types/flow/nodes/sync/flowDerivation.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/flowNode.d.ts +314 -0
- package/dist/types/flow/nodes/sync/flowNode.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/flowReadonly.d.ts +57 -0
- package/dist/types/flow/nodes/sync/flowReadonly.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/flowState.d.ts +96 -0
- package/dist/types/flow/nodes/sync/flowState.d.ts.map +1 -0
- package/dist/types/flow/nodes/sync/index.d.ts +6 -0
- package/dist/types/flow/nodes/sync/index.d.ts.map +1 -0
- package/dist/types/index.d.ts +2 -4
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/solid/converters.d.ts +34 -45
- package/dist/types/solid/converters.d.ts.map +1 -1
- package/dist/types/solid/index.d.ts +2 -2
- package/dist/types/solid/index.d.ts.map +1 -1
- package/dist/types/solid/primitives.d.ts +1 -0
- package/dist/types/solid/primitives.d.ts.map +1 -1
- package/docs/.vitepress/config.mts +1 -1
- package/docs/api/typedoc-sidebar.json +81 -1
- package/package.json +60 -58
- package/src/flow/base/flowDisposable.ts +71 -0
- package/src/flow/base/flowEffect.ts +171 -0
- package/src/flow/base/flowGraph.ts +288 -0
- package/src/flow/base/flowSignal.ts +207 -0
- package/src/flow/base/flowTracker.ts +17 -0
- package/src/flow/base/index.ts +6 -0
- package/src/flow/base/utils.ts +19 -0
- package/src/flow/collections/flowArray.ts +409 -0
- package/src/flow/collections/flowMap.ts +398 -0
- package/src/flow/collections/index.ts +2 -0
- package/src/flow/index.ts +3 -0
- package/src/flow/nodes/async/flowConstantAsync.ts +142 -0
- package/src/flow/nodes/async/flowDerivationAsync.ts +143 -0
- package/src/flow/nodes/async/flowNodeAsync.ts +474 -0
- package/src/flow/nodes/async/flowReadonlyAsync.ts +81 -0
- package/src/flow/nodes/async/flowStateAsync.ts +116 -0
- package/src/flow/nodes/async/index.ts +5 -0
- package/src/flow/nodes/await/advanced/index.ts +5 -0
- package/src/{advanced → flow/nodes/await/advanced}/resource.ts +37 -3
- package/src/{advanced → flow/nodes/await/advanced}/resourceAsync.ts +35 -3
- package/src/{advanced → flow/nodes/await/advanced}/stream.ts +40 -2
- package/src/{advanced → flow/nodes/await/advanced}/streamAsync.ts +38 -3
- package/src/flow/nodes/await/flowConstantAwait.ts +154 -0
- package/src/flow/nodes/await/flowDerivationAwait.ts +154 -0
- package/src/flow/nodes/await/flowNodeAwait.ts +508 -0
- package/src/flow/nodes/await/flowReadonlyAwait.ts +89 -0
- package/src/flow/nodes/await/flowStateAwait.ts +130 -0
- package/src/flow/nodes/await/index.ts +5 -0
- package/src/flow/nodes/index.ts +3 -0
- package/src/flow/nodes/sync/flowConstant.ts +111 -0
- package/src/flow/nodes/sync/flowDerivation.ts +105 -0
- package/src/flow/nodes/sync/flowNode.ts +439 -0
- package/src/flow/nodes/sync/flowReadonly.ts +57 -0
- package/src/flow/nodes/sync/flowState.ts +101 -0
- package/src/flow/nodes/sync/index.ts +5 -0
- package/src/index.ts +2 -47
- package/src/solid/converters.ts +60 -199
- package/src/solid/index.ts +2 -8
- package/src/solid/primitives.ts +4 -0
- package/test/base/flowEffect.test.ts +108 -0
- package/test/base/flowGraph.test.ts +485 -0
- package/test/base/flowSignal.test.ts +372 -0
- package/test/collections/flowArray.asyncStates.test.ts +1553 -0
- package/test/collections/flowArray.scalars.test.ts +1129 -0
- package/test/collections/flowArray.states.test.ts +1365 -0
- package/test/collections/flowMap.asyncStates.test.ts +1105 -0
- package/test/collections/flowMap.scalars.test.ts +877 -0
- package/test/collections/flowMap.states.test.ts +1097 -0
- package/test/nodes/async/flowConstantAsync.test.ts +860 -0
- package/test/nodes/async/flowDerivationAsync.test.ts +1517 -0
- package/test/nodes/async/flowStateAsync.test.ts +1387 -0
- package/test/{resource.test.ts → nodes/await/advanced/resource.test.ts} +21 -19
- package/test/{resourceAsync.test.ts → nodes/await/advanced/resourceAsync.test.ts} +3 -1
- package/test/{stream.test.ts → nodes/await/advanced/stream.test.ts} +30 -28
- package/test/{streamAsync.test.ts → nodes/await/advanced/streamAsync.test.ts} +16 -14
- package/test/nodes/await/flowConstantAwait.test.ts +643 -0
- package/test/nodes/await/flowDerivationAwait.test.ts +1583 -0
- package/test/nodes/await/flowStateAwait.test.ts +999 -0
- package/test/nodes/mixed/derivation.test.ts +1527 -0
- package/test/nodes/sync/flowConstant.test.ts +620 -0
- package/test/nodes/sync/flowDerivation.test.ts +1373 -0
- package/test/nodes/sync/flowState.test.ts +945 -0
- package/test/solid/converters.test.ts +721 -0
- package/test/solid/primitives.test.ts +1031 -0
- package/tsconfig.json +2 -1
- package/vitest.config.ts +7 -1
- package/IMPLEMENTATION_GUIDE.md +0 -1578
- package/dist/types/advanced/array.d.ts.map +0 -1
- package/dist/types/advanced/index.d.ts +0 -9
- package/dist/types/advanced/index.d.ts.map +0 -1
- package/dist/types/advanced/map.d.ts +0 -166
- package/dist/types/advanced/map.d.ts.map +0 -1
- package/dist/types/advanced/resource.d.ts +0 -78
- package/dist/types/advanced/resource.d.ts.map +0 -1
- package/dist/types/advanced/resourceAsync.d.ts +0 -56
- package/dist/types/advanced/resourceAsync.d.ts.map +0 -1
- package/dist/types/advanced/stream.d.ts +0 -117
- package/dist/types/advanced/stream.d.ts.map +0 -1
- package/dist/types/advanced/streamAsync.d.ts +0 -97
- package/dist/types/advanced/streamAsync.d.ts.map +0 -1
- package/dist/types/basic/constant.d.ts +0 -60
- package/dist/types/basic/constant.d.ts.map +0 -1
- package/dist/types/basic/derivation.d.ts +0 -89
- package/dist/types/basic/derivation.d.ts.map +0 -1
- package/dist/types/basic/disposable.d.ts +0 -82
- package/dist/types/basic/disposable.d.ts.map +0 -1
- package/dist/types/basic/effect.d.ts +0 -67
- package/dist/types/basic/effect.d.ts.map +0 -1
- package/dist/types/basic/index.d.ts +0 -10
- package/dist/types/basic/index.d.ts.map +0 -1
- package/dist/types/basic/observable.d.ts +0 -83
- package/dist/types/basic/observable.d.ts.map +0 -1
- package/dist/types/basic/signal.d.ts +0 -69
- package/dist/types/basic/signal.d.ts.map +0 -1
- package/dist/types/basic/state.d.ts +0 -47
- package/dist/types/basic/state.d.ts.map +0 -1
- package/dist/types/basic/trackingContext.d.ts +0 -33
- package/dist/types/basic/trackingContext.d.ts.map +0 -1
- package/dist/types/creators.d.ts +0 -340
- package/dist/types/creators.d.ts.map +0 -1
- package/src/advanced/array.ts +0 -222
- package/src/advanced/index.ts +0 -12
- package/src/advanced/map.ts +0 -193
- package/src/basic/constant.ts +0 -97
- package/src/basic/derivation.ts +0 -147
- package/src/basic/disposable.ts +0 -86
- package/src/basic/effect.ts +0 -104
- package/src/basic/index.ts +0 -9
- package/src/basic/observable.ts +0 -109
- package/src/basic/signal.ts +0 -145
- package/src/basic/state.ts +0 -60
- package/src/basic/trackingContext.ts +0 -45
- package/src/creators.ts +0 -395
- package/test/array.test.ts +0 -600
- package/test/constant.test.ts +0 -44
- package/test/derivation.test.ts +0 -539
- package/test/effect.test.ts +0 -29
- package/test/map.test.ts +0 -240
- package/test/signal.test.ts +0 -72
- package/test/state.test.ts +0 -212
|
@@ -1,89 +0,0 @@
|
|
|
1
|
-
import { FlowObservable } from './observable';
|
|
2
|
-
import { TrackingContext } from './trackingContext';
|
|
3
|
-
/**
|
|
4
|
-
* Represents a reactive derivation whose value is computed based on other reactive signals.
|
|
5
|
-
*
|
|
6
|
-
* @remarks
|
|
7
|
-
* FlowDerivation creates a computed value that automatically tracks its dependencies and
|
|
8
|
-
* recomputes when any dependency changes. The computation is lazy: it doesn't execute until
|
|
9
|
-
* the value is first accessed (via `get()` or `pick()`), and subsequent accesses return the
|
|
10
|
-
* cached value until a dependency changes.
|
|
11
|
-
*
|
|
12
|
-
* **Lazy Initialization:**
|
|
13
|
-
* The compute function doesn't run immediately upon creation. It runs only when:
|
|
14
|
-
* - The value is first read via `get()` or `pick()`
|
|
15
|
-
* - The derivation is watched via `watch()`
|
|
16
|
-
*
|
|
17
|
-
* **Dirty Checking and Recomputation:**
|
|
18
|
-
* When a tracked dependency changes, the derivation is marked as "dirty" but doesn't recompute
|
|
19
|
-
* immediately. Recomputation happens lazily on the next value access. This prevents unnecessary
|
|
20
|
-
* computations when multiple dependencies change in quick succession.
|
|
21
|
-
*
|
|
22
|
-
* **Dynamic Dependencies:**
|
|
23
|
-
* Dependencies are tracked dynamically during each computation. If the compute function
|
|
24
|
-
* conditionally tracks different observables, the dependency graph updates automatically.
|
|
25
|
-
*
|
|
26
|
-
* @example
|
|
27
|
-
* ```typescript
|
|
28
|
-
* const $firstName = state('John');
|
|
29
|
-
* const $lastName = state('Doe');
|
|
30
|
-
*
|
|
31
|
-
* const $fullName = derivation((t) => {
|
|
32
|
-
* return `${$firstName.get(t)} ${$lastName.get(t)}`;
|
|
33
|
-
* });
|
|
34
|
-
*
|
|
35
|
-
* // Compute function hasn't run yet (lazy)
|
|
36
|
-
* const name = $fullName.pick(); // Now it computes
|
|
37
|
-
* ```
|
|
38
|
-
*
|
|
39
|
-
* @typeParam T - The type of the computed value.
|
|
40
|
-
* @public
|
|
41
|
-
*/
|
|
42
|
-
export declare class FlowDerivation<T> extends FlowObservable<T> {
|
|
43
|
-
/**
|
|
44
|
-
* Creates a new FlowDerivation.
|
|
45
|
-
*
|
|
46
|
-
* @param compute - A function that computes the derived value using a tracking context.
|
|
47
|
-
* The function receives a TrackingContext and should use it to access dependencies via
|
|
48
|
-
* `.get(t)`. The function is not executed immediately; it runs lazily on first access.
|
|
49
|
-
*
|
|
50
|
-
* @public
|
|
51
|
-
*/
|
|
52
|
-
constructor(compute: (t: TrackingContext) => T);
|
|
53
|
-
private _initialized;
|
|
54
|
-
private _dirty;
|
|
55
|
-
private _compute;
|
|
56
|
-
private _trackedContext;
|
|
57
|
-
private _initLazy;
|
|
58
|
-
/**
|
|
59
|
-
* Watches the derivation, registering it as a dependency in the given context.
|
|
60
|
-
*
|
|
61
|
-
* @param context - The tracking context in which to register this derivation.
|
|
62
|
-
*
|
|
63
|
-
* @remarks
|
|
64
|
-
* This method overrides the base `watch()` to handle a special case: when a derivation
|
|
65
|
-
* is watched without having its value read (e.g., `$derivation.watch(t)` instead of
|
|
66
|
-
* `$derivation.get(t)`), the derivation still needs to compute its value to establish
|
|
67
|
-
* its own dependencies. Otherwise, the derivation would be tracked but wouldn't track
|
|
68
|
-
* its own dependencies, breaking the reactive chain.
|
|
69
|
-
*
|
|
70
|
-
* This override ensures that:
|
|
71
|
-
* 1. The derivation is registered as a dependency in the provided context
|
|
72
|
-
* 2. The derivation computes its value (if not already computed)
|
|
73
|
-
* 3. The derivation tracks its own dependencies during computation
|
|
74
|
-
*
|
|
75
|
-
* @example
|
|
76
|
-
* ```typescript
|
|
77
|
-
* const $derived = derivation((t) => $state.get(t) * 2);
|
|
78
|
-
*
|
|
79
|
-
* effect((t) => {
|
|
80
|
-
* $derived.watch(t); // Derivation computes even without reading value
|
|
81
|
-
* doSomething(); // Effect re-runs when $derived's dependencies change
|
|
82
|
-
* });
|
|
83
|
-
* ```
|
|
84
|
-
*
|
|
85
|
-
* @public
|
|
86
|
-
*/
|
|
87
|
-
watch(context: TrackingContext): void;
|
|
88
|
-
}
|
|
89
|
-
//# sourceMappingURL=derivation.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../../../src/basic/derivation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACvD;;;;;;;;OAQG;gBACS,OAAO,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,CAAC;IAmB9C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,eAAe,CAAkB;IAEzC,OAAO,CAAC,SAAS;IAiCjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACa,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;CAQrD"}
|
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Represents an object with a disposable lifecycle that manages resources requiring cleanup.
|
|
3
|
-
*
|
|
4
|
-
* @remarks
|
|
5
|
-
* FlowDisposable is the interface for PicoFlow primitives that hold resources needing
|
|
6
|
-
* explicit cleanup. Implementing this interface ensures that objects can properly release
|
|
7
|
-
* resources such as subscriptions, event listeners, and dependent effects.
|
|
8
|
-
*
|
|
9
|
-
* **Disposal Behavior:**
|
|
10
|
-
* All PicoFlow reactive primitives (signals, states, effects, derivations, etc.) implement
|
|
11
|
-
* this interface. When disposed:
|
|
12
|
-
* - The primitive becomes unusable and throws errors on further access
|
|
13
|
-
* - All subscriptions and dependencies are cleaned up
|
|
14
|
-
* - Memory is freed for garbage collection
|
|
15
|
-
*
|
|
16
|
-
* **Options:**
|
|
17
|
-
* The optional `options` parameter controls disposal behavior:
|
|
18
|
-
* - `{ self: true }`: Dispose only this object, leaving dependent effects/listeners active
|
|
19
|
-
* - `{ self: false }` or omitted: Dispose this object AND all dependent effects/listeners (cascade)
|
|
20
|
-
*
|
|
21
|
-
* @example
|
|
22
|
-
* ```typescript
|
|
23
|
-
* const $state = state(0);
|
|
24
|
-
* const fx = effect((t) => console.log($state.get(t)));
|
|
25
|
-
*
|
|
26
|
-
* // Cascade disposal - disposes $state and all its effects
|
|
27
|
-
* $state.dispose();
|
|
28
|
-
*
|
|
29
|
-
* // Self-only disposal - disposes $state but leaves effects intact
|
|
30
|
-
* $state.dispose({ self: true });
|
|
31
|
-
* ```
|
|
32
|
-
*
|
|
33
|
-
* @public
|
|
34
|
-
*/
|
|
35
|
-
export interface FlowDisposable {
|
|
36
|
-
/**
|
|
37
|
-
* Disposes resources held by this object.
|
|
38
|
-
*
|
|
39
|
-
* @param options - Optional configuration for disposal behavior.
|
|
40
|
-
* @param options.self - When true, disposes only this object without cascading to dependents.
|
|
41
|
-
* When false or omitted, disposes this object and all its dependent effects and listeners.
|
|
42
|
-
*
|
|
43
|
-
* @throws Error if the object has already been disposed (behavior may vary by implementation).
|
|
44
|
-
*/
|
|
45
|
-
dispose(options?: {
|
|
46
|
-
self: boolean;
|
|
47
|
-
}): void;
|
|
48
|
-
}
|
|
49
|
-
/**
|
|
50
|
-
* Type guard that checks whether an object implements the FlowDisposable interface.
|
|
51
|
-
*
|
|
52
|
-
* @param obj - The object to test for disposability.
|
|
53
|
-
* @returns True if the object has a `dispose` method and is therefore disposable, false otherwise.
|
|
54
|
-
*
|
|
55
|
-
* @remarks
|
|
56
|
-
* This utility function is useful for safely checking if an object needs disposal before
|
|
57
|
-
* attempting cleanup operations. It performs a runtime check for the presence of a `dispose`
|
|
58
|
-
* method, making it safe to use with unknown types.
|
|
59
|
-
*
|
|
60
|
-
* **Common Use Cases:**
|
|
61
|
-
* - Conditionally disposing items in collections (arrays, maps)
|
|
62
|
-
* - Generic cleanup functions that handle both disposable and non-disposable objects
|
|
63
|
-
* - Defensive programming when working with mixed types
|
|
64
|
-
*
|
|
65
|
-
* @example
|
|
66
|
-
* ```typescript
|
|
67
|
-
* function cleanupArray<T>(items: T[]) {
|
|
68
|
-
* items.forEach(item => {
|
|
69
|
-
* if (isDisposable(item)) {
|
|
70
|
-
* item.dispose();
|
|
71
|
-
* }
|
|
72
|
-
* });
|
|
73
|
-
* }
|
|
74
|
-
*
|
|
75
|
-
* const mixed = [state(1), "string", signal(), 42];
|
|
76
|
-
* cleanupArray(mixed); // Only disposes the state and signal
|
|
77
|
-
* ```
|
|
78
|
-
*
|
|
79
|
-
* @public
|
|
80
|
-
*/
|
|
81
|
-
export declare function isDisposable(obj: unknown): obj is FlowDisposable;
|
|
82
|
-
//# sourceMappingURL=disposable.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../../src/basic/disposable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAMhE"}
|
|
@@ -1,67 +0,0 @@
|
|
|
1
|
-
import { TrackingContext } from './trackingContext';
|
|
2
|
-
/**
|
|
3
|
-
* Represents a reactive effect that executes side-effect functions based
|
|
4
|
-
* on its tracked dependencies.
|
|
5
|
-
*
|
|
6
|
-
* @remarks
|
|
7
|
-
* FlowEffect executes an apply function that performs side effects. The effect always runs
|
|
8
|
-
* with a tracking context, allowing you to explicitly control which observables and signals
|
|
9
|
-
* become dependencies using `.get(t)` for tracked reads or `.pick()` for untracked reads.
|
|
10
|
-
*
|
|
11
|
-
* When any tracked dependency changes, the effect automatically re-executes. The effect
|
|
12
|
-
* runs immediately upon creation and whenever its dependencies trigger updates.
|
|
13
|
-
*
|
|
14
|
-
* Unlike the old API, effects in the new TrackingContext-based system always execute with
|
|
15
|
-
* a tracking context available. You control reactivity by choosing which observables to track
|
|
16
|
-
* within the effect body.
|
|
17
|
-
*
|
|
18
|
-
* @example
|
|
19
|
-
* ```typescript
|
|
20
|
-
* const fx = effect((t) => {
|
|
21
|
-
* const reactive = $stateA.get(t); // Tracked - effect re-runs when $stateA changes
|
|
22
|
-
* const snapshot = $stateB.pick(); // Not tracked - changes don't trigger re-runs
|
|
23
|
-
* console.log(reactive, snapshot);
|
|
24
|
-
* });
|
|
25
|
-
* ```
|
|
26
|
-
*
|
|
27
|
-
* @public
|
|
28
|
-
*/
|
|
29
|
-
export declare class FlowEffect {
|
|
30
|
-
/**
|
|
31
|
-
* Creates a new FlowEffect.
|
|
32
|
-
*
|
|
33
|
-
* @param apply - A side-effect function that receives a tracking context to
|
|
34
|
-
* access and register dependencies on reactive observables and signals.
|
|
35
|
-
*
|
|
36
|
-
* @remarks
|
|
37
|
-
* The provided function is executed immediately upon construction with a tracking context.
|
|
38
|
-
* Use the context parameter to call `.get(t)` on observables you want to track, or `.pick()`
|
|
39
|
-
* on observables you want to read without creating dependencies.
|
|
40
|
-
*
|
|
41
|
-
* @public
|
|
42
|
-
*/
|
|
43
|
-
constructor(apply: (t: TrackingContext) => void);
|
|
44
|
-
/**
|
|
45
|
-
* Disposes the effect, unregistering all its tracked dependencies.
|
|
46
|
-
*
|
|
47
|
-
* @remarks
|
|
48
|
-
* Once disposed, the effect must no longer be used. Trying to dispose an effect
|
|
49
|
-
* that is already disposed will throw an error.
|
|
50
|
-
*
|
|
51
|
-
* @public
|
|
52
|
-
*/
|
|
53
|
-
dispose(): void;
|
|
54
|
-
/**
|
|
55
|
-
* Indicates whether this effect has been disposed.
|
|
56
|
-
*
|
|
57
|
-
* @returns A boolean value that is true if the effect is disposed, false otherwise.
|
|
58
|
-
*
|
|
59
|
-
* @public
|
|
60
|
-
*/
|
|
61
|
-
get disposed(): boolean;
|
|
62
|
-
private _disposed;
|
|
63
|
-
private _dependencies;
|
|
64
|
-
private _trackedContext;
|
|
65
|
-
private _apply;
|
|
66
|
-
}
|
|
67
|
-
//# sourceMappingURL=effect.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../../src/basic/effect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,UAAU;IACtB;;;;;;;;;;;;OAYG;gBACS,KAAK,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI;IAM/C;;;;;;;;OAQG;IACI,OAAO,IAAI,IAAI;IAQtB;;;;;;OAMG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAID,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAA+B;CAoB7C"}
|
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
export { FlowConstant } from './constant';
|
|
2
|
-
export { FlowDerivation } from './derivation';
|
|
3
|
-
export type { FlowDisposable } from './disposable';
|
|
4
|
-
export { isDisposable } from './disposable';
|
|
5
|
-
export { FlowEffect } from './effect';
|
|
6
|
-
export { FlowObservable } from './observable';
|
|
7
|
-
export { FlowSignal } from './signal';
|
|
8
|
-
export { FlowState } from './state';
|
|
9
|
-
export { TrackingContext } from './trackingContext';
|
|
10
|
-
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/basic/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
|
|
@@ -1,83 +0,0 @@
|
|
|
1
|
-
import { FlowSignal } from './signal';
|
|
2
|
-
import { TrackingContext } from './trackingContext';
|
|
3
|
-
/**
|
|
4
|
-
* Represents a reactive observable that holds and tracks a value.
|
|
5
|
-
*
|
|
6
|
-
* @remarks
|
|
7
|
-
* FlowObservable is the base class for all reactive values in PicoFlow. It provides two ways
|
|
8
|
-
* to access the current value:
|
|
9
|
-
*
|
|
10
|
-
* 1. **Tracked access** via `get(context)`: Registers the observable as a dependency in the
|
|
11
|
-
* tracking context, so changes trigger re-execution of the effect or derivation.
|
|
12
|
-
*
|
|
13
|
-
* 2. **Untracked access** via `pick()` or `get(null)`: Reads the current value without registering
|
|
14
|
-
* a dependency, useful for reading values within effects that shouldn't trigger re-runs.
|
|
15
|
-
*
|
|
16
|
-
* Subclasses must implement the {@link FlowObservable._getRaw} method to provide the actual value.
|
|
17
|
-
*
|
|
18
|
-
* @typeParam T - The type of the value held by the observable.
|
|
19
|
-
* @public
|
|
20
|
-
*/
|
|
21
|
-
export declare abstract class FlowObservable<T> extends FlowSignal {
|
|
22
|
-
/**
|
|
23
|
-
* Gets the current value with optional dependency tracking.
|
|
24
|
-
*
|
|
25
|
-
* @param context - The tracking context for reactive tracking, or null for untracked access.
|
|
26
|
-
* When a context is provided, this observable is registered as a dependency. When null,
|
|
27
|
-
* the value is read without any tracking.
|
|
28
|
-
*
|
|
29
|
-
* @returns The current value of type T.
|
|
30
|
-
*
|
|
31
|
-
* @remarks
|
|
32
|
-
* Use `get(t)` within effects and derivations to create reactive dependencies.
|
|
33
|
-
* Use `get(null)` when you need to read a value without tracking (though `pick()` is more idiomatic).
|
|
34
|
-
*
|
|
35
|
-
* @example
|
|
36
|
-
* ```typescript
|
|
37
|
-
* effect((t) => {
|
|
38
|
-
* const tracked = $state.get(t); // Dependency registered
|
|
39
|
-
* const untracked = $other.get(null); // No dependency
|
|
40
|
-
* });
|
|
41
|
-
* ```
|
|
42
|
-
*
|
|
43
|
-
* @public
|
|
44
|
-
*/
|
|
45
|
-
get(context: TrackingContext | null): T;
|
|
46
|
-
/**
|
|
47
|
-
* Gets the current value without any dependency tracking.
|
|
48
|
-
*
|
|
49
|
-
* @returns The current value of type T.
|
|
50
|
-
*
|
|
51
|
-
* @remarks
|
|
52
|
-
* This method is equivalent to calling `get(null)` but provides a more semantic and readable API.
|
|
53
|
-
* Use `pick()` when you want to read a snapshot of the current value without creating a reactive
|
|
54
|
-
* dependency. This is useful for:
|
|
55
|
-
* - Reading initial values
|
|
56
|
-
* - Accessing configuration that shouldn't trigger updates
|
|
57
|
-
* - Mixing tracked and untracked reads in the same effect
|
|
58
|
-
*
|
|
59
|
-
* @example
|
|
60
|
-
* ```typescript
|
|
61
|
-
* // Read a snapshot outside reactive context
|
|
62
|
-
* const currentValue = $state.pick();
|
|
63
|
-
*
|
|
64
|
-
* // Mix tracked and untracked reads
|
|
65
|
-
* effect((t) => {
|
|
66
|
-
* const tracked = $reactive.get(t); // Triggers re-runs
|
|
67
|
-
* const snapshot = $config.pick(); // Doesn't trigger re-runs
|
|
68
|
-
* processData(tracked, snapshot);
|
|
69
|
-
* });
|
|
70
|
-
* ```
|
|
71
|
-
*
|
|
72
|
-
* @public
|
|
73
|
-
*/
|
|
74
|
-
pick(): T;
|
|
75
|
-
/**
|
|
76
|
-
* Subscribes a listener function to changes of the observable.
|
|
77
|
-
* The listener is executed immediately with the current value and on subsequent updates.
|
|
78
|
-
* @param listener - A callback function that receives the new value.
|
|
79
|
-
* @returns A disposer function to cancel the subscription.
|
|
80
|
-
*/
|
|
81
|
-
subscribe(listener: (value: T) => void): () => void;
|
|
82
|
-
}
|
|
83
|
-
//# sourceMappingURL=observable.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"observable.d.ts","sourceRoot":"","sources":["../../../src/basic/observable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,CAAC;IAOvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,IAAI,IAAI,CAAC;IAeT;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;CAMnD"}
|
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
import { FlowDisposable } from './disposable';
|
|
2
|
-
import { TrackingContext } from './trackingContext';
|
|
3
|
-
/**
|
|
4
|
-
* Represents a reactive signal.
|
|
5
|
-
*
|
|
6
|
-
* @remarks Use FlowSignal to create reactive streams that notify listeners and execute associated effects.
|
|
7
|
-
* Signals can be triggered and disposed. Once disposed, interactions with the signal will throw errors.
|
|
8
|
-
* @public
|
|
9
|
-
*/
|
|
10
|
-
export declare class FlowSignal implements FlowDisposable {
|
|
11
|
-
/**
|
|
12
|
-
* Triggers the FlowSignal.
|
|
13
|
-
* Notifies all registered listeners and schedules execution of associated effects.
|
|
14
|
-
* @throws If the FlowSignal has already been disposed.
|
|
15
|
-
* @public
|
|
16
|
-
*/
|
|
17
|
-
trigger(): void;
|
|
18
|
-
/**
|
|
19
|
-
* Watches the signal, registering it as a dependency in the tracking context.
|
|
20
|
-
*
|
|
21
|
-
* @param context - The tracking context in which to register this signal as a dependency.
|
|
22
|
-
*
|
|
23
|
-
* @remarks
|
|
24
|
-
* Use `watch()` when you want to track a signal without reading its value (signals don't
|
|
25
|
-
* have values to read). This is useful for triggering effects based on signal events
|
|
26
|
-
* without needing associated data.
|
|
27
|
-
*
|
|
28
|
-
* When the signal is triggered via `trigger()`, any effects or derivations that have
|
|
29
|
-
* watched this signal will automatically re-execute.
|
|
30
|
-
*
|
|
31
|
-
* This method must be called within an effect or derivation context where a TrackingContext
|
|
32
|
-
* is available. For observables (which hold values), use `.get(t)` instead, which both
|
|
33
|
-
* reads the value and watches for changes.
|
|
34
|
-
*
|
|
35
|
-
* @throws Error if the signal has been disposed.
|
|
36
|
-
*
|
|
37
|
-
* @example
|
|
38
|
-
* ```typescript
|
|
39
|
-
* const $signal = signal();
|
|
40
|
-
*
|
|
41
|
-
* effect((t) => {
|
|
42
|
-
* $signal.watch(t); // Track the signal
|
|
43
|
-
* console.log('Signal triggered!');
|
|
44
|
-
* });
|
|
45
|
-
*
|
|
46
|
-
* $signal.trigger(); // Logs: "Signal triggered!"
|
|
47
|
-
* ```
|
|
48
|
-
*
|
|
49
|
-
* @public
|
|
50
|
-
*/
|
|
51
|
-
watch(context: TrackingContext): void;
|
|
52
|
-
/**
|
|
53
|
-
* Disposes the FlowSignal.
|
|
54
|
-
* Cleans up all registered effects, listeners, and dependencies.
|
|
55
|
-
* Once disposed, further usage of the signal will throw an error.
|
|
56
|
-
* @throws If the FlowSignal is already disposed.
|
|
57
|
-
* @public
|
|
58
|
-
*/
|
|
59
|
-
dispose(options?: {
|
|
60
|
-
self: boolean;
|
|
61
|
-
}): void;
|
|
62
|
-
/**
|
|
63
|
-
* Indicates whether the FlowSignal has been disposed.
|
|
64
|
-
* @remarks Once disposed, the signal should not be used.
|
|
65
|
-
* @public
|
|
66
|
-
*/
|
|
67
|
-
get disposed(): boolean;
|
|
68
|
-
}
|
|
69
|
-
//# sourceMappingURL=signal.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../src/basic/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;GAMG;AACH,qBAAa,UAAW,YAAW,cAAc;IAChD;;;;;OAKG;IACI,OAAO,IAAI,IAAI;IAKtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK5C;;;;;;OAMG;IACI,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAuBjD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;CA8CD"}
|
|
@@ -1,47 +0,0 @@
|
|
|
1
|
-
import { FlowConstant } from './constant';
|
|
2
|
-
/**
|
|
3
|
-
* Represents a reactive state that holds a mutable value.
|
|
4
|
-
*
|
|
5
|
-
* @typeParam T - The type of the state value.
|
|
6
|
-
*
|
|
7
|
-
* @remarks
|
|
8
|
-
* FlowState extends FlowConstant and inherits reactive value access methods from FlowObservable.
|
|
9
|
-
* You can read the state value using `get(context)` for tracked access or `pick()` for untracked access.
|
|
10
|
-
* Use the {@link FlowState.set} method to update the state value.
|
|
11
|
-
*
|
|
12
|
-
* When the state is updated with a new value that differs from the current value, all dependent
|
|
13
|
-
* effects and derivations are automatically notified and re-executed. If the new value is strictly
|
|
14
|
-
* equal to the current value, no notification occurs.
|
|
15
|
-
*
|
|
16
|
-
* @example
|
|
17
|
-
* ```typescript
|
|
18
|
-
* const $count = state(0);
|
|
19
|
-
*
|
|
20
|
-
* // Read with tracking
|
|
21
|
-
* effect((t) => {
|
|
22
|
-
* console.log($count.get(t)); // Effect re-runs when $count changes
|
|
23
|
-
* });
|
|
24
|
-
*
|
|
25
|
-
* // Read without tracking
|
|
26
|
-
* const snapshot = $count.pick();
|
|
27
|
-
*
|
|
28
|
-
* // Update the value
|
|
29
|
-
* $count.set(1);
|
|
30
|
-
* $count.set(current => current + 1);
|
|
31
|
-
* ```
|
|
32
|
-
*
|
|
33
|
-
* @public
|
|
34
|
-
*/
|
|
35
|
-
export declare class FlowState<T> extends FlowConstant<T> {
|
|
36
|
-
/**
|
|
37
|
-
* Updates the state with a new value.
|
|
38
|
-
* @param value - A new value or a callback function that computes a new value based on the current state.
|
|
39
|
-
* @remarks
|
|
40
|
-
* If the computed new value is strictly equal to the current state value, no change is made and subscribers
|
|
41
|
-
* will not be notified. Otherwise, the state is updated and all subscribers are informed of the change.
|
|
42
|
-
* @throws Error if the state has been disposed.
|
|
43
|
-
* @public
|
|
44
|
-
*/
|
|
45
|
-
set(value: T | ((current: T) => T)): void;
|
|
46
|
-
}
|
|
47
|
-
//# sourceMappingURL=state.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/basic/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChD;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;CAczC"}
|
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Represents a tracking context used to register dependencies during reactive computations.
|
|
3
|
-
*
|
|
4
|
-
* @remarks
|
|
5
|
-
* TrackingContext is the core mechanism that enables automatic dependency tracking in PicoFlow's
|
|
6
|
-
* reactive system. When you create an effect or derivation, PicoFlow automatically creates and
|
|
7
|
-
* manages a TrackingContext instance for you. This context is passed as a parameter (typically
|
|
8
|
-
* named `t`) to your computation functions.
|
|
9
|
-
*
|
|
10
|
-
* You use the tracking context to explicitly mark which observables should be tracked as dependencies:
|
|
11
|
-
* - Call `observable.get(t)` to read a value AND register it as a dependency
|
|
12
|
-
* - Call `observable.pick()` to read a value WITHOUT registering it as a dependency
|
|
13
|
-
* - Call `signal.watch(t)` to register a signal as a dependency without reading a value
|
|
14
|
-
*
|
|
15
|
-
* End-users typically don't instantiate TrackingContext directly; instead, they receive it as
|
|
16
|
-
* a parameter in effect and derivation callbacks.
|
|
17
|
-
*
|
|
18
|
-
* @example
|
|
19
|
-
* ```typescript
|
|
20
|
-
* // TrackingContext passed as parameter 't'
|
|
21
|
-
* effect((t) => {
|
|
22
|
-
* const value = $state.get(t); // Tracked dependency
|
|
23
|
-
* const snapshot = $other.pick(); // Not tracked
|
|
24
|
-
* console.log(value, snapshot);
|
|
25
|
-
* });
|
|
26
|
-
* ```
|
|
27
|
-
*
|
|
28
|
-
* @public
|
|
29
|
-
*/
|
|
30
|
-
export declare class TrackingContext {
|
|
31
|
-
private _owner;
|
|
32
|
-
}
|
|
33
|
-
//# sourceMappingURL=trackingContext.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"trackingContext.d.ts","sourceRoot":"","sources":["../../../src/basic/trackingContext.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAe;IAEf,OAAO,CAAC,MAAM;CAS1B"}
|