@pulse-js/core 0.1.5 → 0.1.6

package/README.md

@@ -6,7 +6,17 @@
 
 > A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.
 
-Pulse differs from traditional signals or state managers by treating `Conditions` as first-class citizens. Instead of embedding complex boolean logic inside components or selectors, you define semantic **Guards** that can be observed, composed, and debugged independently.
+Pulse differs from traditional signals or state managers by treating `Conditions` as first-class citizens. Instead of embedding complex boolean logic inside components or selectors, you define **Semantic Guards** that can be observed, composed, and debugged independently.
+
+### Mental Model
+
+Compare Pulse primitives at a glance:
+
+| Concept     | Can be async | Has state | Observable | Purpose                              |
+| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
+| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
+| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
+| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
 
 </div>
 
@@ -53,7 +63,7 @@ rawCount.update((n) => n + 1);
 
 ### Guards (Semantic Logic)
 
-Guards represent business rules or derivations. They are not just boolean flags; they track their own state including `status` (ok, fail, pending) and `reason` (why it failed).
+Guards represent business rules or derivations. A Guard is not just a boolean: it is a **Semantic Guard**—an observable rule with context. They track their own state including `status` (ok, fail, pending) and `reason` (why it failed).
 
 ```typescript
 import { guard } from "@pulse-js/core";
@@ -73,56 +83,40 @@ if (isAdmin.ok()) {
 }
 ```
 
-### Async Guards
+### Computed Values
 
-Pulse handles asynchronous logic natively. Guards can return Promises, and their status will automatically transition from `pending` to `ok` or `fail`.
+You can derive new data from sources or other guards using `compute`. It works like a memoized transformation that automatically re-evaluates when dependencies change.
 
 ```typescript
-const isServerOnline = guard("check-server", async () => {
-  const response = await fetch("/health");
-  if (!response.ok) throw new Error("Server unreachable");
-  return true;
-});
+import { compute } from "@pulse-js/core";
 
-// Check status synchronously non-blocking
-if (isServerOnline.pending()) {
-  showSpinner();
-}
+const fullName = compute("full-name", [firstName, lastName], (first, last) => {
+  return `${first} ${last}`;
+});
 ```
 
-### Composition
-
-Guards can be composed using logical operators. This creates a semantic tree of conditions that is easy to debug.
+### Async Guards & Race Control
 
-```typescript
-import { guard } from "@pulse-js/core";
-
-// .all() - Success only if ALL pass. Fails with the reason of the first failure.
-const canCheckout = guard.all("can-checkout", [
-  isAuthenticated,
-  hasItemsInCart,
-  isServerOnline,
-]);
+Pulse handles asynchronous logic natively. Guards can return Promises, and their status will automatically transition from `pending` to `ok` or `fail`.
 
-// .any() - Success if AT LEAST ONE passes.
-const hasAccess = guard.any("has-access", [isAdmin, isEditor]);
+Pulse implements internal **runId versioning** to automatically cancel stale async evaluations if the underlying sources change multiple times before a promise resolves, preventing race conditions.
 
-// .not() - Inverts the logical result.
-const isGuest = guard.not("is-guest", isAuthenticated);
+```typescript
+const isServerOnline = guard("check-server", async () => {
+  const response = await fetch("/health");
+  if (!response.ok) throw new Error("Server unreachable");
+  return true;
+});
 ```
 
-### Computed Values
+### Explanable Guards
 
-You can derive new data from sources or other guards using `guard.compute`.
+For complex conditions, you can call `.explain()` to get a structured tree of the current status, failure reason, and the status of all direct dependencies.
 
-```typescript
-const fullName = guard.compute(
-  "full-name",
-  [firstName, lastName],
-  (first, last) => {
-    return `${first} ${last}`;
-  }
-);
+```ts
+const explanation = canCheckout.explain();
+console.log(explanation);
+// { status: 'fail', reason: 'auth failed', dependencies: [...] }
 ```
 
 ## Server-Side Rendering (SSR)

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   PulseRegistry: () => PulseRegistry,
+  compute: () => compute,
   evaluate: () => evaluate,
   getCurrentGuard: () => getCurrentGuard,
   guard: () => extendedGuard,
@@ -86,8 +87,10 @@ function guard(nameOrFn, fn) {
   const dependents = /* @__PURE__ */ new Set();
   const subscribers = /* @__PURE__ */ new Set();
   let evaluationId = 0;
+  const dependencies = /* @__PURE__ */ new Set();
   const node = {
     addDependency(trackable) {
+      dependencies.add(trackable);
     },
     notify() {
       evaluate2();
@@ -97,37 +100,41 @@ function guard(nameOrFn, fn) {
     const currentId = ++evaluationId;
     const oldStatus = state.status;
     const oldValue = state.value;
+    dependencies.clear();
     try {
       const result = runInContext(node, () => evaluator());
       if (result instanceof Promise) {
-        state = { status: "pending" };
+        if (state.status !== "pending") {
+          state = { ...state, status: "pending", updatedAt: Date.now() };
+          notifyDependents();
+        }
         result.then((resolved) => {
           if (currentId === evaluationId) {
             if (resolved === false) {
-              state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+              state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
             } else {
-              state = { status: "ok", value: resolved };
+              state = { status: "ok", value: resolved, updatedAt: Date.now() };
             }
             notifyDependents();
           }
         }).catch((err) => {
           if (currentId === evaluationId) {
-            state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+            state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
             notifyDependents();
           }
         });
       } else {
         if (result === false) {
-          state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+          state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
         } else {
-          state = { status: "ok", value: result };
+          state = { status: "ok", value: result, updatedAt: Date.now() };
         }
         if (oldStatus !== state.status || oldValue !== state.value) {
           notifyDependents();
         }
       }
     } catch (err) {
-      state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+      state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
       notifyDependents();
     }
   };
@@ -138,40 +145,60 @@ function guard(nameOrFn, fn) {
     subscribers.forEach((sub) => sub({ ...state }));
   };
   evaluate2();
-  const handleRead = () => {
+  const track = () => {
     const activeGuard2 = getCurrentGuard();
     if (activeGuard2 && activeGuard2 !== node) {
       dependents.add(activeGuard2);
+      activeGuard2.addDependency(g);
     }
   };
   const g = (() => {
-    handleRead();
+    track();
     return state.status === "ok" ? state.value : void 0;
   });
   g.ok = () => {
-    handleRead();
+    track();
     return state.status === "ok";
   };
   g.fail = () => {
-    handleRead();
+    track();
     return state.status === "fail";
   };
   g.pending = () => {
-    handleRead();
+    track();
     return state.status === "pending";
   };
   g.reason = () => {
-    handleRead();
+    track();
     return state.reason;
   };
   g.state = () => {
-    handleRead();
+    track();
     return state;
   };
   g.subscribe = (listener) => {
     subscribers.add(listener);
     return () => subscribers.delete(listener);
   };
+  g.explain = () => {
+    const deps = [];
+    dependencies.forEach((dep) => {
+      const depName = dep._name || "unnamed";
+      const isG = "state" in dep;
+      deps.push({
+        name: depName,
+        type: isG ? "guard" : "source",
+        status: isG ? dep.state().status : void 0
+      });
+    });
+    return {
+      name: name || "guard",
+      status: state.status,
+      reason: state.reason,
+      value: state.value,
+      dependencies: deps
+    };
+  };
   g._evaluate = () => evaluate2();
   g._name = name;
   g._hydrate = (newState) => {
@@ -229,6 +256,7 @@ function source(initialValue, options = {}) {
     const activeGuard2 = getCurrentGuard();
     if (activeGuard2) {
       dependents.add(activeGuard2);
+      activeGuard2.addDependency(s);
     }
     return value;
   });
@@ -254,6 +282,14 @@ function source(initialValue, options = {}) {
   return s;
 }
 
+// src/compute.ts
+function compute(name, dependencies, processor) {
+  return guard(name, () => {
+    const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
+    return processor(...values);
+  });
+}
+
 // src/composition.ts
 function isGuard(target) {
   return typeof target === "function" && "ok" in target;
@@ -296,17 +332,11 @@ function guardNot(nameOrTarget, maybeTarget) {
     return !target();
   });
 }
-function guardCompute(name, dependencies, processor) {
-  return guard(name, () => {
-    const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
-    return processor(...values);
-  });
-}
 var guardExtensions = {
   all: guardAll,
   any: guardAny,
   not: guardNot,
-  compute: guardCompute
+  compute
 };
 
 // src/index.ts
@@ -314,6 +344,7 @@ var extendedGuard = Object.assign(guard, guardExtensions);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PulseRegistry,
+  compute,
   evaluate,
   getCurrentGuard,
   guard,

package/dist/index.d.cts

@@ -18,7 +18,7 @@ interface GuardNode extends Trackable {
      * Registers a dependency for this guard.
      * Internal use only.
      */
-    addDependency(trackable: Trackable): void;
+    addDependency(trackable: any): void;
 }
 /**
  * Executes a function within the context of a specific Guard.
@@ -55,6 +55,22 @@ interface GuardState<T> {
     value?: T;
     /** The message explaining why the guard failed (only if status is 'fail'). */
     reason?: string;
+    /** The timestamp when the status last changed. */
+    updatedAt?: number;
+}
+/**
+ * Detailed explanation of the Guard's current state and its dependencies.
+ */
+interface GuardExplanation {
+    name: string;
+    status: GuardStatus;
+    reason?: string;
+    value?: any;
+    dependencies: Array<{
+        name: string;
+        type: 'source' | 'guard';
+        status?: GuardStatus;
+    }>;
 }
 /**
  * A Pulse Guard is a reactive semantic condition.
@@ -109,6 +125,11 @@ interface Guard<T = boolean> {
      * @returns An unsubscription function.
      */
     subscribe(listener: Subscriber<GuardState<T>>): () => void;
+    /**
+     * Returns a structured explanation of the guard's state and its direct dependencies.
+     * Useful for DevTools and sophisticated error reporting.
+     */
+    explain(): GuardExplanation;
     /**
      * Manually forces a re-evaluation of the guard.
      * Typically used internally by Pulse or for debugging.
@@ -141,6 +162,27 @@ interface Guard<T = boolean> {
  */
 declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
 
+/**
+ * Utility to transform reactive dependencies into a new derived value.
+ *
+ * Works like a memoized computation that automatically re-evaluates when
+ * any of its dependencies change. Unlike a Guard, compute is intended for
+ * pure transformations and does not have a failure reason by default.
+ *
+ * @template T - The type of input values.
+ * @template R - The type of the computed result.
+ * @param name - A unique name for the computation (required for SSR).
+ * @param dependencies - An array of sources or guards to observe.
+ * @param processor - A function that derives the new value.
+ * @returns A Pulse Guard holding the computed result.
+ *
+ * @example
+ * ```ts
+ * const fullName = compute('full-name', [firstName, lastName], (f, l) => `${f} ${l}`);
+ * ```
+ */
+declare function compute<R>(name: string, dependencies: any[], processor: (...args: any[]) => R): Guard<R>;
+
 /**
  * Creates a composite guard that is 'ok' only if ALL provided guards are 'ok'.
  * If any guard fails, this guard also fails and adopts the reason of the FIRST failing guard.
@@ -182,25 +224,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  * ```
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
-/**
- * Utility to transform reactive dependencies into a new derived value.
- *
- * Works like a memoized computation that automatically re-evaluates when
- * any of its dependencies change.
- *
- * @template T - The type of input values.
- * @template R - The type of the computed result.
- * @param name - A unique name for the computation (required for SSR).
- * @param dependencies - An array of sources or guards to observe.
- * @param processor - A function that derives the new value.
- * @returns A Pulse Guard holding the computed result.
- *
- * @example
- * ```ts
- * const fullName = guard.compute('full-name', [firstName, lastName], (f, l) => `${f} ${l}`);
- * ```
- */
-declare function guardCompute<T, R>(name: string, dependencies: any[], processor: (...args: any[]) => R): Guard<R>;
 
 /**
  * Options for configuring a Pulse Source.
@@ -408,7 +431,7 @@ declare const extendedGuard: typeof guard & {
     all: typeof guardAll;
     any: typeof guardAny;
     not: typeof guardNot;
-    compute: typeof guardCompute;
+    compute: typeof compute;
 };
 
-export { type Guard, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.d.ts

@@ -18,7 +18,7 @@ interface GuardNode extends Trackable {
      * Registers a dependency for this guard.
      * Internal use only.
      */
-    addDependency(trackable: Trackable): void;
+    addDependency(trackable: any): void;
 }
 /**
  * Executes a function within the context of a specific Guard.
@@ -55,6 +55,22 @@ interface GuardState<T> {
     value?: T;
     /** The message explaining why the guard failed (only if status is 'fail'). */
     reason?: string;
+    /** The timestamp when the status last changed. */
+    updatedAt?: number;
+}
+/**
+ * Detailed explanation of the Guard's current state and its dependencies.
+ */
+interface GuardExplanation {
+    name: string;
+    status: GuardStatus;
+    reason?: string;
+    value?: any;
+    dependencies: Array<{
+        name: string;
+        type: 'source' | 'guard';
+        status?: GuardStatus;
+    }>;
 }
 /**
  * A Pulse Guard is a reactive semantic condition.
@@ -109,6 +125,11 @@ interface Guard<T = boolean> {
      * @returns An unsubscription function.
      */
     subscribe(listener: Subscriber<GuardState<T>>): () => void;
+    /**
+     * Returns a structured explanation of the guard's state and its direct dependencies.
+     * Useful for DevTools and sophisticated error reporting.
+     */
+    explain(): GuardExplanation;
     /**
      * Manually forces a re-evaluation of the guard.
      * Typically used internally by Pulse or for debugging.
@@ -141,6 +162,27 @@ interface Guard<T = boolean> {
  */
 declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
 
+/**
+ * Utility to transform reactive dependencies into a new derived value.
+ *
+ * Works like a memoized computation that automatically re-evaluates when
+ * any of its dependencies change. Unlike a Guard, compute is intended for
+ * pure transformations and does not have a failure reason by default.
+ *
+ * @template T - The type of input values.
+ * @template R - The type of the computed result.
+ * @param name - A unique name for the computation (required for SSR).
+ * @param dependencies - An array of sources or guards to observe.
+ * @param processor - A function that derives the new value.
+ * @returns A Pulse Guard holding the computed result.
+ *
+ * @example
+ * ```ts
+ * const fullName = compute('full-name', [firstName, lastName], (f, l) => `${f} ${l}`);
+ * ```
+ */
+declare function compute<R>(name: string, dependencies: any[], processor: (...args: any[]) => R): Guard<R>;
+
 /**
  * Creates a composite guard that is 'ok' only if ALL provided guards are 'ok'.
  * If any guard fails, this guard also fails and adopts the reason of the FIRST failing guard.
@@ -182,25 +224,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  * ```
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
-/**
- * Utility to transform reactive dependencies into a new derived value.
- *
- * Works like a memoized computation that automatically re-evaluates when
- * any of its dependencies change.
- *
- * @template T - The type of input values.
- * @template R - The type of the computed result.
- * @param name - A unique name for the computation (required for SSR).
- * @param dependencies - An array of sources or guards to observe.
- * @param processor - A function that derives the new value.
- * @returns A Pulse Guard holding the computed result.
- *
- * @example
- * ```ts
- * const fullName = guard.compute('full-name', [firstName, lastName], (f, l) => `${f} ${l}`);
- * ```
- */
-declare function guardCompute<T, R>(name: string, dependencies: any[], processor: (...args: any[]) => R): Guard<R>;
 
 /**
  * Options for configuring a Pulse Source.
@@ -408,7 +431,7 @@ declare const extendedGuard: typeof guard & {
     all: typeof guardAll;
     any: typeof guardAny;
     not: typeof guardNot;
-    compute: typeof guardCompute;
+    compute: typeof compute;
 };
 
-export { type Guard, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.js

@@ -53,8 +53,10 @@ function guard(nameOrFn, fn) {
   const dependents = /* @__PURE__ */ new Set();
   const subscribers = /* @__PURE__ */ new Set();
   let evaluationId = 0;
+  const dependencies = /* @__PURE__ */ new Set();
   const node = {
     addDependency(trackable) {
+      dependencies.add(trackable);
     },
     notify() {
       evaluate2();
@@ -64,37 +66,41 @@ function guard(nameOrFn, fn) {
     const currentId = ++evaluationId;
     const oldStatus = state.status;
     const oldValue = state.value;
+    dependencies.clear();
     try {
       const result = runInContext(node, () => evaluator());
       if (result instanceof Promise) {
-        state = { status: "pending" };
+        if (state.status !== "pending") {
+          state = { ...state, status: "pending", updatedAt: Date.now() };
+          notifyDependents();
+        }
         result.then((resolved) => {
           if (currentId === evaluationId) {
             if (resolved === false) {
-              state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+              state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
             } else {
-              state = { status: "ok", value: resolved };
+              state = { status: "ok", value: resolved, updatedAt: Date.now() };
             }
             notifyDependents();
           }
         }).catch((err) => {
           if (currentId === evaluationId) {
-            state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+            state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
             notifyDependents();
           }
         });
       } else {
         if (result === false) {
-          state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+          state = { status: "fail", reason: name ? `${name} failed` : "condition failed", updatedAt: Date.now() };
         } else {
-          state = { status: "ok", value: result };
+          state = { status: "ok", value: result, updatedAt: Date.now() };
         }
         if (oldStatus !== state.status || oldValue !== state.value) {
           notifyDependents();
         }
       }
     } catch (err) {
-      state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+      state = { status: "fail", reason: err instanceof Error ? err.message : String(err), updatedAt: Date.now() };
       notifyDependents();
     }
   };
@@ -105,40 +111,60 @@ function guard(nameOrFn, fn) {
     subscribers.forEach((sub) => sub({ ...state }));
   };
   evaluate2();
-  const handleRead = () => {
+  const track = () => {
     const activeGuard2 = getCurrentGuard();
     if (activeGuard2 && activeGuard2 !== node) {
       dependents.add(activeGuard2);
+      activeGuard2.addDependency(g);
     }
   };
   const g = (() => {
-    handleRead();
+    track();
     return state.status === "ok" ? state.value : void 0;
   });
   g.ok = () => {
-    handleRead();
+    track();
     return state.status === "ok";
   };
   g.fail = () => {
-    handleRead();
+    track();
     return state.status === "fail";
   };
   g.pending = () => {
-    handleRead();
+    track();
     return state.status === "pending";
   };
   g.reason = () => {
-    handleRead();
+    track();
     return state.reason;
   };
   g.state = () => {
-    handleRead();
+    track();
     return state;
   };
   g.subscribe = (listener) => {
     subscribers.add(listener);
     return () => subscribers.delete(listener);
   };
+  g.explain = () => {
+    const deps = [];
+    dependencies.forEach((dep) => {
+      const depName = dep._name || "unnamed";
+      const isG = "state" in dep;
+      deps.push({
+        name: depName,
+        type: isG ? "guard" : "source",
+        status: isG ? dep.state().status : void 0
+      });
+    });
+    return {
+      name: name || "guard",
+      status: state.status,
+      reason: state.reason,
+      value: state.value,
+      dependencies: deps
+    };
+  };
   g._evaluate = () => evaluate2();
   g._name = name;
   g._hydrate = (newState) => {
@@ -196,6 +222,7 @@ function source(initialValue, options = {}) {
     const activeGuard2 = getCurrentGuard();
     if (activeGuard2) {
       dependents.add(activeGuard2);
+      activeGuard2.addDependency(s);
     }
     return value;
   });
@@ -221,6 +248,14 @@ function source(initialValue, options = {}) {
   return s;
 }
 
+// src/compute.ts
+function compute(name, dependencies, processor) {
+  return guard(name, () => {
+    const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
+    return processor(...values);
+  });
+}
+
 // src/composition.ts
 function isGuard(target) {
   return typeof target === "function" && "ok" in target;
@@ -263,23 +298,18 @@ function guardNot(nameOrTarget, maybeTarget) {
     return !target();
   });
 }
-function guardCompute(name, dependencies, processor) {
-  return guard(name, () => {
-    const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
-    return processor(...values);
-  });
-}
 var guardExtensions = {
   all: guardAll,
   any: guardAny,
   not: guardNot,
-  compute: guardCompute
+  compute
 };
 
 // src/index.ts
 var extendedGuard = Object.assign(guard, guardExtensions);
 export {
   PulseRegistry,
+  compute,
   evaluate,
   getCurrentGuard,
   extendedGuard as guard,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",