@ersbeth/picoflow 0.0.1

package/biome.json

@@ -0,0 +1,34 @@
+{
+    "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+    "files": {
+        "ignore": [
+            "dist",
+            "node_modules",
+            "doc/.vitepress/dist",
+            "doc/.vitepress/cache"
+        ]
+    },
+    "organizeImports": {
+        "enabled": true
+    },
+    "formatter": {
+        "enabled": true,
+        "indentStyle": "space",
+        "indentWidth": 4,
+        "lineEnding": "lf"
+    },
+    "linter": {
+        "rules": {
+            "suspicious": {
+                "noExplicitAny": "off",
+                "useIsArray": "off"
+            },
+            "complexity": {
+                "noForEach": "off"
+            },
+            "style": {
+                "noNonNullAssertion": "off"
+            }
+        }
+    }
+}

package/dist/picoflow.js

@@ -0,0 +1,572 @@
+class FlowSignal {
+  /* API ---------------------------------------------------------------------- */
+  /**
+   * Triggers the signal.
+   * @remarks
+   * This method notifies all registered listeners and causes associated effects to execute.
+   * @throws Error if the signal is disposed.
+   * @public
+   */
+  trigger() {
+    if (this._disposed) throw new Error("Signal is disposed");
+    this._notify();
+  }
+  /**
+   * Disposes the signal.
+   * @remarks
+   * Disposing a signal will dispose all registered effects and listeners,
+   * and unregister all dependencies. Once disposed, any further calls to the signal
+   * will throw an error.
+   * @throws Error if the signal is already disposed.
+   * @public
+   */
+  dispose() {
+    if (this._disposed) throw new Error("Signal is disposed");
+    Array.from(this._effects).forEach((effect) => effect.dispose());
+    Array.from(this._listeners).forEach((listener) => listener.dispose());
+    Array.from(this._dependencies).forEach((dependency) => {
+      this._unregisterDependency(dependency);
+    });
+    this._disposed = true;
+  }
+  /**
+   * Indicates whether the signal has been disposed.
+   * @remarks
+   * Once disposed, the signal should not be used.
+   * @public
+   */
+  get disposed() {
+    return this._disposed;
+  }
+  /* INTERNAL ------------------------------------------------------------- */
+  /**
+   * @internal
+   */
+  _disposed = false;
+  /**
+   * @internal
+   */
+  _dependencies = /* @__PURE__ */ new Set();
+  /**
+   * @internal
+   */
+  _listeners = /* @__PURE__ */ new Set();
+  /**
+   * @internal
+   */
+  _effects = /* @__PURE__ */ new Set();
+  /**
+   * @internal
+   * Internal method to watch the signal.
+   * @throws Error if the signal is disposed.
+   */
+  _watch() {
+    if (this._disposed) throw new Error("Signal is disposed");
+  }
+  /**
+   * @internal
+   * Notifies all listeners and executes all registered effects.
+   */
+  _notify() {
+    this._listeners.forEach((listener) => listener._notify());
+    this._effects.forEach((effect) => effect._exec());
+  }
+  /**
+   * @internal
+   * Registers a dependency from the given listener and watches the signal.
+   * @param listener - A FlowSignal or FlowEffect that will depend on this signal.
+   */
+  _watchFrom(listener) {
+    listener._registerDependency(this);
+    this._watch();
+  }
+  /**
+   * @internal
+   * Registers a dependency with the given FlowSignal.
+   * @param dependency - The FlowSignal to register as a dependency.
+   */
+  _registerDependency(dependency) {
+    this._dependencies.add(dependency);
+    dependency._registerListener(this);
+  }
+  /**
+   * @internal
+   * Unregisters the given dependency.
+   * @param dependency - The FlowSignal to unregister.
+   */
+  _unregisterDependency(dependency) {
+    this._dependencies.delete(dependency);
+    dependency._unregisterListener(this);
+  }
+  /**
+   * @internal
+   * Registers a listener (another FlowSignal) to this signal.
+   * @param signal - The FlowSignal to register as a listener.
+   */
+  _registerListener(signal) {
+    this._listeners.add(signal);
+  }
+  /**
+   * @internal
+   * Unregisters the given listener.
+   * @param signal - The FlowSignal to unregister.
+   */
+  _unregisterListener(signal) {
+    this._listeners.delete(signal);
+  }
+  /**
+   * @internal
+   * Registers a FlowEffect to this signal.
+   * @param effect - The FlowEffect to register.
+   */
+  _registerEffect(effect) {
+    this._effects.add(effect);
+  }
+  /**
+   * @internal
+   * Unregisters the given FlowEffect.
+   * @param effect - The FlowEffect to unregister.
+   */
+  _unregisterEffect(effect) {
+    this._effects.delete(effect);
+  }
+}
+
+class FlowObservable extends FlowSignal {
+  /* INTERNAL -------------------------------------------*/
+  /**
+   * @internal
+   * Internal storage for the observable's value.
+   */
+  _value;
+  /**
+   * @internal
+   * Retrieves the current value from the observable and registers a dependency
+   * from the provided listener.
+   * @param listener - The FlowObservable or FlowEffect that is accessing this observable.
+   * @returns The current value, as returned by {@link FlowObservable.get}.
+   */
+  _getFrom(listener) {
+    listener._registerDependency(this);
+    return this.get();
+  }
+}
+
+class FlowDerivation extends FlowObservable {
+  /**
+   * Creates a new FlowDerivation.
+   * @param compute - A function that computes the derived value. It is provided with a getter
+   * and a watcher function to access observables and signals dependencies.
+   * @public
+   */
+  constructor(compute) {
+    super();
+    this._trackedExec = () => compute(this._trackedGet, this._trackedWatch);
+    this._untrackedExec = () => compute(this._untrackedGet, this._untrackedWatch);
+  }
+  /**
+   * Gets the current derived value.
+   * @returns The current computed value.
+   * @remarks
+   * This method ensures that the derivation is up-to-date before returning the value.
+   * @public
+   */
+  get() {
+    this._exec();
+    return this._value;
+  }
+  /* INTERNAL MEMBERS AND METHODS */
+  /** @internal */
+  _initialized = false;
+  /** @internal */
+  _dirty = true;
+  /** @internal */
+  _trackedGet = (observable) => observable._getFrom(this);
+  /** @internal */
+  _trackedWatch = (signal) => signal._watchFrom(this);
+  /** @internal */
+  _untrackedGet = (observable) => observable.get();
+  /** @internal */
+  _untrackedWatch = (signal) => signal._watch();
+  /** @internal */
+  _trackedExec;
+  /** @internal */
+  _untrackedExec;
+  /**
+   * @internal
+   * Executes the compute function if necessary to update the derived value.
+   */
+  _exec() {
+    if (this._disposed) throw new Error("Effect is disposed");
+    if (this._dirty) {
+      if (this._initialized) this._value = this._untrackedExec();
+      else {
+        this._value = this._trackedExec();
+        this._initialized = true;
+      }
+      this._dirty = false;
+    }
+  }
+  /**
+   * @internal
+   * Marks the derivation as dirty and notifies downstream dependencies.
+   */
+  _notify() {
+    this._dirty = true;
+    super._notify();
+  }
+  /**
+   * @internal
+   * Ensures that the derivation is up-to-date when it is watched.
+   */
+  _watch() {
+    this._exec();
+  }
+}
+
+class FlowEffect {
+  /* API --------------------------------------------------- */
+  /**
+   * Creates a new FlowEffect.
+   *
+   * @param apply - 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.
+   *
+   * @public
+   */
+  constructor(apply) {
+    this._trackedExec = () => apply(this._trackedGet, this._trackedWatch);
+    this._untrackedExec = () => apply(this._untrackedGet, this._untrackedWatch);
+    this._exec();
+  }
+  /**
+   * Disposes the effect, unregistering all its dependencies.
+   *
+   * @remarks
+   * After disposal, the effect should no longer be used. Calling this method on an already
+   * disposed effect will throw an error.
+   *
+   * @public
+   */
+  dispose() {
+    if (this._disposed) throw new Error("Effect is disposed");
+    Array.from(this._dependencies).forEach((dependency) => {
+      this._unregisterDependency(dependency);
+    });
+    this._disposed = true;
+  }
+  /**
+   * Indicates whether this effect has been disposed.
+   *
+   * @returns A boolean value indicating if the effect is disposed.
+   *
+   * @public
+   */
+  get disposed() {
+    return this._disposed;
+  }
+  /* INTERNAL ------------------------------------------------------------ */
+  /**
+   * @internal
+   */
+  _disposed = false;
+  /**
+   * @internal
+   */
+  _initialized = false;
+  /**
+   * @internal
+   */
+  _dependencies = /* @__PURE__ */ new Set();
+  /**
+   * @internal
+   * A tracked getter that registers a dependency when accessing an observable.
+   */
+  _trackedGet = (observable) => observable._getFrom(this);
+  /**
+   * @internal
+   * A tracked watcher that registers a dependency when watching a signal.
+   */
+  _trackedWatch = (signal) => signal._watchFrom(this);
+  /**
+   * @internal
+   * An untracked getter that simply retrieves the current value from an observable.
+   */
+  _untrackedGet = (observable) => observable.get();
+  /**
+   * @internal
+   * An untracked watcher that calls the default watch on a signal.
+   */
+  _untrackedWatch = (signal) => signal._watch();
+  /**
+   * @internal
+   * Execution function used during initialization (tracked mode).
+   */
+  _trackedExec;
+  /**
+   * @internal
+   * Execution function used after initialization (untracked mode).
+   */
+  _untrackedExec;
+  /**
+   * @internal
+   * Executes the effect. If the effect has not been initialized, it runs in tracked mode;
+   * otherwise, it runs in untracked mode.
+   *
+   * @throws Error if the effect has been disposed.
+   */
+  _exec() {
+    if (this._disposed) throw new Error("Effect is disposed");
+    if (this._initialized) this._untrackedExec();
+    else {
+      this._trackedExec();
+      this._initialized = true;
+    }
+  }
+  /**
+   * @internal
+   * Registers a dependency on the given signal.
+   *
+   * @param dependency - The FlowSignal to register as a dependency.
+   */
+  _registerDependency(dependency) {
+    this._dependencies.add(dependency);
+    dependency._registerEffect(this);
+  }
+  /**
+   * @internal
+   * Unregisters the given dependency.
+   *
+   * @param dependency - The FlowSignal to unregister.
+   */
+  _unregisterDependency(dependency) {
+    this._dependencies.delete(dependency);
+    dependency._unregisterEffect(this);
+  }
+}
+
+class FlowResource extends FlowObservable {
+  /**
+   * Creates a new FlowResource.
+   * @param fetch - An asynchronous function that retrieves the resource's value.
+   * @param initial - The initial value of the resource.
+   * @public
+   */
+  constructor(fetch, initial) {
+    super();
+    this._value = initial;
+    this._fetch = fetch;
+  }
+  /**
+   * Retrieves the current resource value.
+   * @returns The current value.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("Resource is disposed");
+    return this._value;
+  }
+  /**
+   * Asynchronously fetches a new value for the resource.
+   * @remarks
+   * Executes the internal fetch function. If the fetched value differs from the current one,
+   * updates the resource's value and notifies subscribers.
+   * @returns A Promise that resolves when the fetch operation is complete.
+   * @throws Error if the resource is disposed.
+   * @public
+   */
+  async fetch() {
+    if (this._disposed) throw new Error("Resource is disposed");
+    const value = await this._fetch();
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
+  /* INTERNAL ------------------------------------------------ */
+  /**
+   * @internal
+   * The asynchronous function used to fetch the resource value.
+   */
+  _fetch;
+}
+
+class FlowState extends FlowObservable {
+  /**
+   * Creates a new FlowState with the given initial value.
+   * @param value - The initial value for the state.
+   * @public
+   */
+  constructor(value) {
+    super();
+    this._value = value;
+  }
+  /**
+   * Retrieves the current state value.
+   * @returns The current value of the state.
+   * @throws Error if the state has been disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("State is disposed");
+    return this._value;
+  }
+  /**
+   * Updates the state with a new value.
+   * @param value - The new value to set.
+   * @remarks
+   * If the new value is identical to the current value, no update or notification occurs.
+   * Otherwise, the state is updated and all subscribers are notified.
+   * @throws Error if the state has been disposed.
+   * @public
+   */
+  set(value) {
+    if (this._disposed) throw new Error("State is disposed");
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
+}
+
+class FlowMap extends FlowState {
+  /**
+   * A reactive state that holds the most recent key and value that were set.
+   *
+   * @remarks
+   * When a key is set via {@link FlowMap.setAt}, this state is updated with
+   * the corresponding key and value.
+   *
+   * @public
+   */
+  $lastSet = new FlowState({});
+  /**
+   * A reactive state that holds the most recent key and value that were deleted.
+   *
+   * @remarks
+   * When a key is deleted via {@link FlowMap.delete}, this state is updated with
+   * the corresponding key and its last known value.
+   *
+   * @public
+   */
+  $lastDeleted = new FlowState({});
+  /**
+   * Sets a value at the specified key in the underlying map.
+   *
+   * @param key - The key at which to set the value.
+   * @param value - The value to set.
+   *
+   * @remarks
+   * This method updates the internal map with the given key and value, emits the new
+   * key-value pair via {@link FlowMap.$lastSet}, and notifies subscribers of the change.
+   *
+   * @public
+   */
+  setAt(key, value) {
+    if (this._disposed) throw new Error("StateMap is disposed");
+    this._value.set(key, value);
+    this.$lastSet.set({ key, value });
+    this._notify();
+  }
+  /**
+   * Deletes the value at the specified key from the underlying map.
+   *
+   * @param key - The key to delete.
+   *
+   * @remarks
+   * This method removes the key from the internal map, emits the deleted key and its
+   * corresponding value via {@link FlowMap.$lastDeleted}, and notifies subscribers
+   * of the change.
+   *
+   * @public
+   */
+  delete(key) {
+    if (this._disposed) throw new Error("StateMap is disposed");
+    const value = this._value.get(key);
+    this._value.delete(key);
+    this.$lastDeleted.set({ key, value });
+    this._notify();
+  }
+}
+
+class FlowStream extends FlowObservable {
+  /* API -------------------------------------------------------- */
+  /**
+   * Creates a new FlowStream.
+   * @param updater - A function that receives a setter to update the stream's value.
+   * It should return a disposer function that will be called upon disposal.
+   * @param initial - The initial value of the stream.
+   * @public
+   */
+  constructor(updater, initial) {
+    super();
+    this._value = initial;
+    this._disposer = updater((value) => {
+      this._set(value);
+    });
+  }
+  /**
+   * Retrieves the current value of the stream.
+   * @returns The current value.
+   * @throws Error if the stream is disposed.
+   * @public
+   */
+  get() {
+    if (this._disposed) throw new Error("Stream is disposed");
+    return this._value;
+  }
+  /**
+   * Disposes the stream, releasing all resources.
+   * @remarks
+   * In addition to disposing the underlying observable, this method calls the disposer
+   * returned by the updater.
+   * @public
+   */
+  dispose() {
+    super.dispose();
+    this._disposer();
+  }
+  /* INTERNAL ------------------------------------------------------ */
+  /**
+   * @internal
+   * The disposer function returned by the updater.
+   */
+  _disposer;
+  /**
+   * @internal
+   * Updates the stream's value and notifies subscribers if the value changes.
+   * @param value - The new value to set.
+   * @internal
+   */
+  _set(value) {
+    if (this._disposed) throw new Error("Stream is disposed");
+    if (value === this._value) return;
+    this._value = value;
+    this._notify();
+  }
+}
+
+function signal() {
+  return new FlowSignal();
+}
+function state(value) {
+  return new FlowState(value);
+}
+function resource(fn, initial) {
+  return new FlowResource(fn, initial);
+}
+function stream(updater, initial) {
+  return new FlowStream(updater, initial);
+}
+function derivation(fn) {
+  return new FlowDerivation(fn);
+}
+function effect(fn) {
+  return new FlowEffect(fn);
+}
+function map(initial) {
+  return new FlowMap(
+    new Map(initial ? Object.entries(initial) : [])
+  );
+}
+
+export { derivation, effect, map, resource, signal, state, stream };

package/dist/types/creators.d.ts

@@ -0,0 +1,70 @@
+import { FlowDerivation } from './derivation';
+import { FlowEffect } from './effect';
+import { FlowGetter } from './observable';
+import { FlowResource } from './resource';
+import { FlowSignal, FlowWatcher } from './signal';
+import { FlowState } from './state';
+import { FlowMap } from './map';
+import { FlowStream } from './stream';
+/**
+ * Creates a new reactive signal.
+ * @returns A new instance of {@link FlowSignal}.
+ * @public
+ */
+export declare function signal(): FlowSignal;
+/**
+ * Creates a new reactive state holding a value.
+ * @typeparam T - The type of the state value.
+ * @param value - The initial value for the state.
+ * @returns A new instance of {@link FlowState}.
+ * @public
+ */
+export declare function state<T>(value: T): FlowState<T>;
+/**
+ * Creates a new reactive resource that asynchronously fetches its value.
+ * @typeparam T - The type of the resource value.
+ * @param fn - An asynchronous function that fetches the resource value.
+ * @param initial - The initial value of the resource.
+ * @returns A new instance of {@link FlowResource}.
+ * @public
+ */
+export declare function resource<T>(fn: () => Promise<T>, initial: T): FlowResource<T>;
+/**
+ * Creates a new reactive stream.
+ * @typeparam T - The type of the stream value.
+ * @param updater - A function that receives a setter to update the stream's value.
+ * It should return a disposer function to clean up resources.
+ * @param initial - The initial value of the stream.
+ * @returns A new instance of {@link FlowStream}.
+ * @public
+ */
+export declare function stream<T>(updater: (set: (value: T) => void) => () => void, initial: T): FlowStream<T>;
+/**
+ * Creates a new reactive derivation whose value is computed based on other reactive signals.
+ * @typeparam T - The type of the derived value.
+ * @param fn - A function that computes the derived value. It receives a getter and a watcher
+ * function to access and register dependencies.
+ * @returns A new instance of {@link FlowDerivation}.
+ * @public
+ */
+export declare function derivation<T>(fn: (get: FlowGetter, watch: FlowWatcher) => T): FlowDerivation<T>;
+/**
+ * Creates a new reactive effect that executes a side-effect function based on its dependencies.
+ * @param fn - A function that performs side effects. It receives a getter and a watcher
+ * function for tracking reactive dependencies.
+ * @returns A new instance of {@link FlowEffect}.
+ * @public
+ */
+export declare function effect(fn: (get: FlowGetter, watch: FlowWatcher) => void): FlowEffect;
+/**
+ * Creates a new reactive map state.
+ * @typeparam K - The type of the keys.
+ * @typeparam V - The type of the values.
+ * @param initial - An optional record of key-value pairs to initialize the map.
+ * @returns A new instance of {@link FlowMap}.
+ * @remarks
+ * The initial record is converted to a native Map before being used.
+ * @public
+ */
+export declare function map<K extends string | number | symbol, V>(initial?: Record<K, V>): FlowMap<K, V>;
+//# sourceMappingURL=creators.d.ts.map

package/dist/types/creators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creators.d.ts","sourceRoot":"","sources":["../../src/creators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,UAAU,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACpB,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,EAChD,OAAO,EAAE,CAAC,GACX,UAAU,CAAC,CAAC,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAE/F;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,UAAU,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,EACrD,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAIf"}