@ersbeth/picoflow 0.0.1

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "files.associations": {
+        "*.json": "jsonc"
+    }
+}

package/README.md

@@ -0,0 +1,151 @@
+# Picoflow
+
+**Picoflow** is a lightweight reactive dataflow library that provides fine-grained reactive primitives. It gives you an intuitive API for signals, state, asynchronous resources, streams, derivations, effects, and reactive maps. Instead of using traditional subscriptions, Picoflow uses effects to automatically track reactive dependencies.
+
+## Features
+
+- **Reactive Signals:** Manually trigger updates using `$signal.trigger()`.
+- **Reactive State:** Manage state with observables that expose getter/setter APIs.
+- **Asynchronous Resources:** Fetch and update asynchronous data reactively.
+- **Reactive Streams:** Create streams that update over time using an updater function.
+- **Derivations:** Compute derived values from other reactive primitives.
+  - **Automatic Caching:** Derived values are cached and are re-evaluated only when one or more of their dependencies change.
+  - **Lazy Evaluation:** Derivations are evaluated lazily—that is, the computation only runs if and when an effect actually uses the derived value.
+- **Reactive Maps:** Manage collections reactively with granular update notifications.
+- **Effects:** Automatically run side-effect functions when dependencies change.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install @ersbeth/picoflow
+```
+
+## Usage
+
+In Picoflow, we advise to prefix all reactive primitives and effects with `$` for improved readability. Rather than using a subscribe method, you always create an effect that "watches" a primitive. Below are some examples:
+
+### Creating a Signal
+
+```ts
+import { signal, effect } from 'picoflow';
+
+const $signal = signal();
+
+const $effect = effect((get, watch) => {
+  // Automatically tracks $signal
+  watch($signal);
+  console.log('$signal has been triggered');
+});
+
+// Trigger the signal
+$signal.trigger();
+
+// LOG -> $signal has been triggered
+```
+
+### Creating Reactive State
+
+```ts
+import { state, effect } from 'picoflow';
+
+const $count = state(0);
+
+const $effect = effect((get, watch) => {
+  // Automatically tracks $count
+  console.log('Count changed:', get($count));
+});
+
+// Update the state
+$count.set(42);
+
+// LOG -> $Count changed: 42
+```
+
+### Creating an Asynchronous Resource
+
+```ts
+import { resource, effect } from 'picoflow';
+
+async function fetchData() {
+  const response = await fetch('https://api.example.com/data');
+  return response.json();
+}
+
+const $data = resource(fetchData, {});
+
+// Create an effect to watch for updates
+const $effect = effect((get, watch) => {
+  console.log('Resource updated:', get($data));
+});
+
+// Later, you can trigger a new fetch
+$data.fetch();
+```
+
+### Creating a Reactive Stream
+
+```ts
+import { stream, effect } from 'picoflow';
+
+const $ticker = stream(
+  (set) => {
+    const interval = setInterval(() => set(Date.now()), 1000);
+    // Return a disposer to clear the interval when the stream is disposed.
+    return () => clearInterval(interval);
+  },
+  Date.now()
+);
+
+const $effect = effect((get, watch) => {
+  console.log('Current time:', get($ticker));
+});
+```
+
+### Creating a Derived Value
+
+```ts
+import { state, derivation, effect } from 'picoflow';
+
+const $a = state(10);
+const $b = state(20);
+
+// Create a derived value that sums $a and $b.
+const $sum = derivation((get, watch) => {
+  return get($a) + get($b);
+});
+
+const $effect = effect((get, watch) => {
+  console.log('Sum:', get($sum));
+});
+
+// Update a dependency to see the derivation update.
+$a.set(15);
+```
+
+### Creating a Reactive Map
+
+Reactive maps allow fine-grained tracking of collection updates.
+
+```ts
+import { map, effect } from 'picoflow';
+
+const $map = map({ foo: 'bar' });
+
+const $effect = effect((get, watch) => {
+  console.log('Map updated:', get($map));
+});
+
+// Update the map to trigger updates
+$map.setAt('baz', 'qux');
+$map.delete('foo');
+```
+
+## API Documentation
+
+For detailed API documentation, please refer to the [API Reference](./api/doc/index.md).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/api/doc/index.md

@@ -0,0 +1,31 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[picoflow](./picoflow.md)
+
+
+</td><td>
+
+PicoFlow is a lightweight reactive dataflow library that provides a set of reactive primitives such as signals, state, resources, streams, derivations, effects, and reactive maps.
+
+
+</td></tr>
+</tbody></table>

package/api/doc/picoflow.derivation.md

@@ -0,0 +1,55 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [derivation](./picoflow.derivation.md)
+
+## derivation() function
+
+Creates a new reactive derivation whose value is computed based on other reactive signals.
+
+**Signature:**
+
+```typescript
+export declare function derivation<T>(fn: (get: FlowGetter, watch: FlowWatcher) => T): FlowDerivation<T>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+fn
+
+
+</td><td>
+
+(get: [FlowGetter](./picoflow.flowgetter.md)<!-- -->, watch: [FlowWatcher](./picoflow.flowwatcher.md)<!-- -->) =&gt; T
+
+
+</td><td>
+
+A function that computes the derived value. It receives a getter and a watcher function to access and register dependencies.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[FlowDerivation](./picoflow.flowderivation.md)<!-- -->&lt;T&gt;
+
+A new instance of [FlowDerivation](./picoflow.flowderivation.md)<!-- -->.
+

package/api/doc/picoflow.effect.md

@@ -0,0 +1,55 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [effect](./picoflow.effect.md)
+
+## effect() function
+
+Creates a new reactive effect that executes a side-effect function based on its dependencies.
+
+**Signature:**
+
+```typescript
+export declare function effect(fn: (get: FlowGetter, watch: FlowWatcher) => void): FlowEffect;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+fn
+
+
+</td><td>
+
+(get: [FlowGetter](./picoflow.flowgetter.md)<!-- -->, watch: [FlowWatcher](./picoflow.flowwatcher.md)<!-- -->) =&gt; void
+
+
+</td><td>
+
+A function that performs side effects. It receives a getter and a watcher function for tracking reactive dependencies.
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[FlowEffect](./picoflow.floweffect.md)
+
+A new instance of [FlowEffect](./picoflow.floweffect.md)<!-- -->.
+

package/api/doc/picoflow.flowderivation._constructor_.md

@@ -0,0 +1,49 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowDerivation](./picoflow.flowderivation.md) &gt; [(constructor)](./picoflow.flowderivation._constructor_.md)
+
+## FlowDerivation.(constructor)
+
+Creates a new FlowDerivation.
+
+**Signature:**
+
+```typescript
+constructor(compute: (get: FlowGetter, watch: FlowWatcher) => T);
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+compute
+
+
+</td><td>
+
+(get: [FlowGetter](./picoflow.flowgetter.md)<!-- -->, watch: [FlowWatcher](./picoflow.flowwatcher.md)<!-- -->) =&gt; T
+
+
+</td><td>
+
+A function that computes the derived value. It is provided with a getter and a watcher function to access observables and signals dependencies.
+
+
+</td></tr>
+</tbody></table>

package/api/doc/picoflow.flowderivation.get.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowDerivation](./picoflow.flowderivation.md) &gt; [get](./picoflow.flowderivation.get.md)
+
+## FlowDerivation.get() method
+
+Gets the current derived value.
+
+**Signature:**
+
+```typescript
+get(): T;
+```
+**Returns:**
+
+T
+
+The current computed value.
+
+## Remarks
+
+This method ensures that the derivation is up-to-date before returning the value.
+

package/api/doc/picoflow.flowderivation.md

@@ -0,0 +1,86 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowDerivation](./picoflow.flowderivation.md)
+
+## FlowDerivation class
+
+Represents a reactive derivation whose value is computed based on other reactive signals.
+
+**Signature:**
+
+```typescript
+export declare class FlowDerivation<T> extends FlowObservable<T> 
+```
+**Extends:** [FlowObservable](./picoflow.flowobservable.md)<!-- -->&lt;T&gt;
+
+## Remarks
+
+A FlowDerivation automatically tracks its dependencies and recomputes its value when needed.
+
+## Constructors
+
+<table><thead><tr><th>
+
+Constructor
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[(constructor)(compute)](./picoflow.flowderivation._constructor_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Creates a new FlowDerivation.
+
+
+</td></tr>
+</tbody></table>
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[get()](./picoflow.flowderivation.get.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Gets the current derived value.
+
+
+</td></tr>
+</tbody></table>

package/api/doc/picoflow.flowdisposer.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowDisposer](./picoflow.flowdisposer.md)
+
+## FlowDisposer type
+
+A function that disposes of a resource.
+
+**Signature:**
+
+```typescript
+export type FlowDisposer = () => void;
+```

package/api/doc/picoflow.floweffect._constructor_.md

@@ -0,0 +1,49 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowEffect](./picoflow.floweffect.md) &gt; [(constructor)](./picoflow.floweffect._constructor_.md)
+
+## FlowEffect.(constructor)
+
+Creates a new FlowEffect.
+
+**Signature:**
+
+```typescript
+constructor(apply: (get: FlowGetter, watch: FlowWatcher) => void);
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+apply
+
+
+</td><td>
+
+(get: [FlowGetter](./picoflow.flowgetter.md)<!-- -->, watch: [FlowWatcher](./picoflow.flowwatcher.md)<!-- -->) =&gt; void
+
+
+</td><td>
+
+A function that performs the side effect. It receives a getter and a watcher function to access and register dependencies on reactive observables and signals.
+
+
+</td></tr>
+</tbody></table>

package/api/doc/picoflow.floweffect.dispose.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowEffect](./picoflow.floweffect.md) &gt; [dispose](./picoflow.floweffect.dispose.md)
+
+## FlowEffect.dispose() method
+
+Disposes the effect, unregistering all its dependencies.
+
+**Signature:**
+
+```typescript
+dispose(): void;
+```
+**Returns:**
+
+void
+
+## Remarks
+
+After disposal, the effect should no longer be used. Calling this method on an already disposed effect will throw an error.
+

package/api/doc/picoflow.floweffect.disposed.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowEffect](./picoflow.floweffect.md) &gt; [disposed](./picoflow.floweffect.disposed.md)
+
+## FlowEffect.disposed property
+
+Indicates whether this effect has been disposed.
+
+**Signature:**
+
+```typescript
+get disposed(): boolean;
+```

package/api/doc/picoflow.floweffect.md

@@ -0,0 +1,131 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowEffect](./picoflow.floweffect.md)
+
+## FlowEffect class
+
+Represents a reactive effect that executes a side‐effect function based on its tracked dependencies.
+
+**Signature:**
+
+```typescript
+export declare class FlowEffect 
+```
+
+## Remarks
+
+A FlowEffect runs an apply function to perform side effects. The apply function is executed in two modes: Initially, in a tracked mode to register dependencies. Subsequently, in an untracked mode to only re-execute the effect .
+
+## Constructors
+
+<table><thead><tr><th>
+
+Constructor
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[(constructor)(apply)](./picoflow.floweffect._constructor_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Creates a new FlowEffect.
+
+
+</td></tr>
+</tbody></table>
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[disposed](./picoflow.floweffect.disposed.md)
+
+
+</td><td>
+
+`readonly`
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+Indicates whether this effect has been disposed.
+
+
+</td></tr>
+</tbody></table>
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[dispose()](./picoflow.floweffect.dispose.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Disposes the effect, unregistering all its dependencies.
+
+
+</td></tr>
+</tbody></table>

package/api/doc/picoflow.flowgetter.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [picoflow](./picoflow.md) &gt; [FlowGetter](./picoflow.flowgetter.md)
+
+## FlowGetter type
+
+A function for retrieving the current value from a FlowObservable.
+
+**Signature:**
+
+```typescript
+export type FlowGetter = <T>(observable: FlowObservable<T>) => T;
+```
+**References:** [FlowObservable](./picoflow.flowobservable.md)
+