@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.
Files changed (183) hide show
  1. package/.cursor/plans/unifier-flowresource-avec-flowderivation-c9506e24.plan.md +372 -0
  2. package/README.md +17 -1
  3. package/biome.json +4 -1
  4. package/dist/picoflow.js +1155 -582
  5. package/dist/types/flow/base/flowDisposable.d.ts +67 -0
  6. package/dist/types/flow/base/flowDisposable.d.ts.map +1 -0
  7. package/dist/types/flow/base/flowEffect.d.ts +127 -0
  8. package/dist/types/flow/base/flowEffect.d.ts.map +1 -0
  9. package/dist/types/flow/base/flowGraph.d.ts +97 -0
  10. package/dist/types/flow/base/flowGraph.d.ts.map +1 -0
  11. package/dist/types/flow/base/flowSignal.d.ts +134 -0
  12. package/dist/types/flow/base/flowSignal.d.ts.map +1 -0
  13. package/dist/types/flow/base/flowTracker.d.ts +15 -0
  14. package/dist/types/flow/base/flowTracker.d.ts.map +1 -0
  15. package/dist/types/flow/base/index.d.ts +7 -0
  16. package/dist/types/flow/base/index.d.ts.map +1 -0
  17. package/dist/types/flow/base/utils.d.ts +20 -0
  18. package/dist/types/flow/base/utils.d.ts.map +1 -0
  19. package/dist/types/{advanced/array.d.ts → flow/collections/flowArray.d.ts} +50 -12
  20. package/dist/types/flow/collections/flowArray.d.ts.map +1 -0
  21. package/dist/types/flow/collections/flowMap.d.ts +224 -0
  22. package/dist/types/flow/collections/flowMap.d.ts.map +1 -0
  23. package/dist/types/flow/collections/index.d.ts +3 -0
  24. package/dist/types/flow/collections/index.d.ts.map +1 -0
  25. package/dist/types/flow/index.d.ts +4 -0
  26. package/dist/types/flow/index.d.ts.map +1 -0
  27. package/dist/types/flow/nodes/async/flowConstantAsync.d.ts +137 -0
  28. package/dist/types/flow/nodes/async/flowConstantAsync.d.ts.map +1 -0
  29. package/dist/types/flow/nodes/async/flowDerivationAsync.d.ts +137 -0
  30. package/dist/types/flow/nodes/async/flowDerivationAsync.d.ts.map +1 -0
  31. package/dist/types/flow/nodes/async/flowNodeAsync.d.ts +343 -0
  32. package/dist/types/flow/nodes/async/flowNodeAsync.d.ts.map +1 -0
  33. package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts +81 -0
  34. package/dist/types/flow/nodes/async/flowReadonlyAsync.d.ts.map +1 -0
  35. package/dist/types/flow/nodes/async/flowStateAsync.d.ts +111 -0
  36. package/dist/types/flow/nodes/async/flowStateAsync.d.ts.map +1 -0
  37. package/dist/types/flow/nodes/async/index.d.ts +6 -0
  38. package/dist/types/flow/nodes/async/index.d.ts.map +1 -0
  39. package/dist/types/flow/nodes/index.d.ts +3 -0
  40. package/dist/types/flow/nodes/index.d.ts.map +1 -0
  41. package/dist/types/flow/nodes/sync/flowConstant.d.ts +108 -0
  42. package/dist/types/flow/nodes/sync/flowConstant.d.ts.map +1 -0
  43. package/dist/types/flow/nodes/sync/flowDerivation.d.ts +100 -0
  44. package/dist/types/flow/nodes/sync/flowDerivation.d.ts.map +1 -0
  45. package/dist/types/flow/nodes/sync/flowNode.d.ts +314 -0
  46. package/dist/types/flow/nodes/sync/flowNode.d.ts.map +1 -0
  47. package/dist/types/flow/nodes/sync/flowReadonly.d.ts +57 -0
  48. package/dist/types/flow/nodes/sync/flowReadonly.d.ts.map +1 -0
  49. package/dist/types/flow/nodes/sync/flowState.d.ts +96 -0
  50. package/dist/types/flow/nodes/sync/flowState.d.ts.map +1 -0
  51. package/dist/types/flow/nodes/sync/index.d.ts +6 -0
  52. package/dist/types/flow/nodes/sync/index.d.ts.map +1 -0
  53. package/dist/types/index.d.ts +2 -4
  54. package/dist/types/index.d.ts.map +1 -1
  55. package/dist/types/solid/converters.d.ts +34 -45
  56. package/dist/types/solid/converters.d.ts.map +1 -1
  57. package/dist/types/solid/index.d.ts +2 -2
  58. package/dist/types/solid/index.d.ts.map +1 -1
  59. package/dist/types/solid/primitives.d.ts +1 -0
  60. package/dist/types/solid/primitives.d.ts.map +1 -1
  61. package/docs/.vitepress/config.mts +1 -1
  62. package/docs/api/typedoc-sidebar.json +81 -1
  63. package/package.json +60 -58
  64. package/src/flow/base/flowDisposable.ts +71 -0
  65. package/src/flow/base/flowEffect.ts +171 -0
  66. package/src/flow/base/flowGraph.ts +288 -0
  67. package/src/flow/base/flowSignal.ts +207 -0
  68. package/src/flow/base/flowTracker.ts +17 -0
  69. package/src/flow/base/index.ts +6 -0
  70. package/src/flow/base/utils.ts +19 -0
  71. package/src/flow/collections/flowArray.ts +409 -0
  72. package/src/flow/collections/flowMap.ts +398 -0
  73. package/src/flow/collections/index.ts +2 -0
  74. package/src/flow/index.ts +3 -0
  75. package/src/flow/nodes/async/flowConstantAsync.ts +142 -0
  76. package/src/flow/nodes/async/flowDerivationAsync.ts +143 -0
  77. package/src/flow/nodes/async/flowNodeAsync.ts +474 -0
  78. package/src/flow/nodes/async/flowReadonlyAsync.ts +81 -0
  79. package/src/flow/nodes/async/flowStateAsync.ts +116 -0
  80. package/src/flow/nodes/async/index.ts +5 -0
  81. package/src/flow/nodes/await/advanced/index.ts +5 -0
  82. package/src/{advanced → flow/nodes/await/advanced}/resource.ts +37 -3
  83. package/src/{advanced → flow/nodes/await/advanced}/resourceAsync.ts +35 -3
  84. package/src/{advanced → flow/nodes/await/advanced}/stream.ts +40 -2
  85. package/src/{advanced → flow/nodes/await/advanced}/streamAsync.ts +38 -3
  86. package/src/flow/nodes/await/flowConstantAwait.ts +154 -0
  87. package/src/flow/nodes/await/flowDerivationAwait.ts +154 -0
  88. package/src/flow/nodes/await/flowNodeAwait.ts +508 -0
  89. package/src/flow/nodes/await/flowReadonlyAwait.ts +89 -0
  90. package/src/flow/nodes/await/flowStateAwait.ts +130 -0
  91. package/src/flow/nodes/await/index.ts +5 -0
  92. package/src/flow/nodes/index.ts +3 -0
  93. package/src/flow/nodes/sync/flowConstant.ts +111 -0
  94. package/src/flow/nodes/sync/flowDerivation.ts +105 -0
  95. package/src/flow/nodes/sync/flowNode.ts +439 -0
  96. package/src/flow/nodes/sync/flowReadonly.ts +57 -0
  97. package/src/flow/nodes/sync/flowState.ts +101 -0
  98. package/src/flow/nodes/sync/index.ts +5 -0
  99. package/src/index.ts +2 -47
  100. package/src/solid/converters.ts +60 -199
  101. package/src/solid/index.ts +2 -8
  102. package/src/solid/primitives.ts +4 -0
  103. package/test/base/flowEffect.test.ts +108 -0
  104. package/test/base/flowGraph.test.ts +485 -0
  105. package/test/base/flowSignal.test.ts +372 -0
  106. package/test/collections/flowArray.asyncStates.test.ts +1553 -0
  107. package/test/collections/flowArray.scalars.test.ts +1129 -0
  108. package/test/collections/flowArray.states.test.ts +1365 -0
  109. package/test/collections/flowMap.asyncStates.test.ts +1105 -0
  110. package/test/collections/flowMap.scalars.test.ts +877 -0
  111. package/test/collections/flowMap.states.test.ts +1097 -0
  112. package/test/nodes/async/flowConstantAsync.test.ts +860 -0
  113. package/test/nodes/async/flowDerivationAsync.test.ts +1517 -0
  114. package/test/nodes/async/flowStateAsync.test.ts +1387 -0
  115. package/test/{resource.test.ts → nodes/await/advanced/resource.test.ts} +21 -19
  116. package/test/{resourceAsync.test.ts → nodes/await/advanced/resourceAsync.test.ts} +3 -1
  117. package/test/{stream.test.ts → nodes/await/advanced/stream.test.ts} +30 -28
  118. package/test/{streamAsync.test.ts → nodes/await/advanced/streamAsync.test.ts} +16 -14
  119. package/test/nodes/await/flowConstantAwait.test.ts +643 -0
  120. package/test/nodes/await/flowDerivationAwait.test.ts +1583 -0
  121. package/test/nodes/await/flowStateAwait.test.ts +999 -0
  122. package/test/nodes/mixed/derivation.test.ts +1527 -0
  123. package/test/nodes/sync/flowConstant.test.ts +620 -0
  124. package/test/nodes/sync/flowDerivation.test.ts +1373 -0
  125. package/test/nodes/sync/flowState.test.ts +945 -0
  126. package/test/solid/converters.test.ts +721 -0
  127. package/test/solid/primitives.test.ts +1031 -0
  128. package/tsconfig.json +2 -1
  129. package/vitest.config.ts +7 -1
  130. package/IMPLEMENTATION_GUIDE.md +0 -1578
  131. package/dist/types/advanced/array.d.ts.map +0 -1
  132. package/dist/types/advanced/index.d.ts +0 -9
  133. package/dist/types/advanced/index.d.ts.map +0 -1
  134. package/dist/types/advanced/map.d.ts +0 -166
  135. package/dist/types/advanced/map.d.ts.map +0 -1
  136. package/dist/types/advanced/resource.d.ts +0 -78
  137. package/dist/types/advanced/resource.d.ts.map +0 -1
  138. package/dist/types/advanced/resourceAsync.d.ts +0 -56
  139. package/dist/types/advanced/resourceAsync.d.ts.map +0 -1
  140. package/dist/types/advanced/stream.d.ts +0 -117
  141. package/dist/types/advanced/stream.d.ts.map +0 -1
  142. package/dist/types/advanced/streamAsync.d.ts +0 -97
  143. package/dist/types/advanced/streamAsync.d.ts.map +0 -1
  144. package/dist/types/basic/constant.d.ts +0 -60
  145. package/dist/types/basic/constant.d.ts.map +0 -1
  146. package/dist/types/basic/derivation.d.ts +0 -89
  147. package/dist/types/basic/derivation.d.ts.map +0 -1
  148. package/dist/types/basic/disposable.d.ts +0 -82
  149. package/dist/types/basic/disposable.d.ts.map +0 -1
  150. package/dist/types/basic/effect.d.ts +0 -67
  151. package/dist/types/basic/effect.d.ts.map +0 -1
  152. package/dist/types/basic/index.d.ts +0 -10
  153. package/dist/types/basic/index.d.ts.map +0 -1
  154. package/dist/types/basic/observable.d.ts +0 -83
  155. package/dist/types/basic/observable.d.ts.map +0 -1
  156. package/dist/types/basic/signal.d.ts +0 -69
  157. package/dist/types/basic/signal.d.ts.map +0 -1
  158. package/dist/types/basic/state.d.ts +0 -47
  159. package/dist/types/basic/state.d.ts.map +0 -1
  160. package/dist/types/basic/trackingContext.d.ts +0 -33
  161. package/dist/types/basic/trackingContext.d.ts.map +0 -1
  162. package/dist/types/creators.d.ts +0 -340
  163. package/dist/types/creators.d.ts.map +0 -1
  164. package/src/advanced/array.ts +0 -222
  165. package/src/advanced/index.ts +0 -12
  166. package/src/advanced/map.ts +0 -193
  167. package/src/basic/constant.ts +0 -97
  168. package/src/basic/derivation.ts +0 -147
  169. package/src/basic/disposable.ts +0 -86
  170. package/src/basic/effect.ts +0 -104
  171. package/src/basic/index.ts +0 -9
  172. package/src/basic/observable.ts +0 -109
  173. package/src/basic/signal.ts +0 -145
  174. package/src/basic/state.ts +0 -60
  175. package/src/basic/trackingContext.ts +0 -45
  176. package/src/creators.ts +0 -395
  177. package/test/array.test.ts +0 -600
  178. package/test/constant.test.ts +0 -44
  179. package/test/derivation.test.ts +0 -539
  180. package/test/effect.test.ts +0 -29
  181. package/test/map.test.ts +0 -240
  182. package/test/signal.test.ts +0 -72
  183. 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"}