@pulse-js/core 0.2.2 → 0.3.0

package/README.md

@@ -1,172 +1,97 @@
 <div align="center">
-
 <img width="200" height="200" alt="logo" src="https://raw.githubusercontent.com/ZtaMDev/Pulse/refs/heads/main/pulse.svg" />
 
-# Pulse-JS
+# Pulse-JS v2.0
 
 [![npm version](https://img.shields.io/npm/v/@pulse-js/core.svg?color=blue)](https://www.npmjs.com/package/@pulse-js/core)
 
-> A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.
+> A semantic reactivity system for modern applications. Separate reactive state (pulse) from business conditions (guards) with a declarative, composable, and proxied approach.
 
 Official [Documentation](https://pulse-js.vercel.app)
 
-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, you define **Semantic Guards** that are observed, composed, and debugged independently.
 
 </div>
 
 ## Installation
 
-```bash
-npm install @pulse-js/core @pulse-js/tools
-```
-
-### or
-
 ```bash
 bun add @pulse-js/core @pulse-js/tools
 ```
 
-Pulse works with React via adapters like `@pulse-js/react`.
-
-```bash
-bun add @pulse-js/react
-```
-
 ## Core Concepts
 
-### Sources (Refined Data)
+### Pulse Objects (Universal Reactivity)
 
-Sources are the primitive containers for your application state. They hold values and notify dependents when those values change.
+`pulse()` creates a deep reactive Proxy. Use it for complex objects and arrays. Track property access automatically and mutate state directly.
 
 ```typescript
-import { source } from "@pulse-js/core";
+import { pulse } from "@pulse-js/core";
+
+const user = pulse({
+  name: "Alice",
+  role: "admin",
+  increment() {
+    this.stats.clicks++;
+  },
+  stats: { clicks: 0 },
+});
 
-// Create a source
-const user = source({ name: "Alice", id: 1 });
-const rawCount = source(0);
+// Mutate directly - it's reactive!
+user.name = "Bob";
+user.increment();
+```
 
-// Read the value (dependencies are tracked automatically if called inside a Guard)
-console.log(user());
+### Sources (Primitive Records)
 
-// Update the value
-user.set({ name: "Bob", id: 1 });
+Sources are primitive containers for your application state. They hold values and notify dependents when those values change.
 
-// Update using a callback
-rawCount.update((n) => n + 1);
+```typescript
+import { source } from "@pulse-js/core";
+const count = source(0);
+count.set(5);
 ```
 
 ### Guards (Semantic Logic)
 
-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).
+Guards represent business rules or derivations. They act as high-performance **Selectors** with built-in dependency tracking and rich failure context.
 
 ```typescript
 import { guard } from "@pulse-js/core";
 
-// Synchronous Guard
-const isAdmin = guard("is-admin", () => {
+const isAuthorized = guard("auth-check", async () => {
   const u = user();
-  if (u.role !== "admin") return false; // Implicitly sets status to 'fail'
-  return true;
-});
-
-// Guards can be checked explicitly
-if (isAdmin.ok()) {
-  // Grant access
-} else {
-  console.log(isAdmin.reason()); // e.g. "is-admin failed"
-}
-```
-
-### Computed Values
-
-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
-import { compute } from "@pulse-js/core";
-
-const fullName = compute("full-name", [firstName, lastName], (first, last) => {
-  return `${first} ${last}`;
-});
-```
-
-### Async Guards & Race Control
-
-Pulse handles asynchronous logic natively. Guards can return Promises, and their status will automatically transition from `pending` to `ok` or `fail`.
-
-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.
-
-```typescript
-const isServerOnline = guard("check-server", async () => {
-  const response = await fetch("/health");
-  if (!response.ok) throw new Error("Server unreachable");
+  if (!u) return false;
   return true;
 });
 ```
 
 ### Explanable Guards
 
-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.
+Get a structured tree of the current status, failure reasons, and the status of all direct dependencies.
 
 ```ts
 const explanation = canCheckout.explain();
-console.log(explanation);
-// { status: 'fail', reason: 'auth failed', dependencies: [...] }
+// { status: 'fail', reason: { code: 'AUTH', message: '...' }, dependencies: [...] }
 ```
 
-## Server-Side Rendering (SSR)
-
-Pulse is designed with SSR in mind. It supports isomorphic rendering where async guards can be evaluated on the server, their state serialized, and then hydrated on the client.
-
-### Server Side
-
-```typescript
-import { evaluate } from "@pulse-js/core";
-
-// 1. Evaluate critical guards on the server
-const hydrationState = await evaluate([isUserAuthenticated, appSettings]);
-
-// 2. Serialize this state into your HTML
-const html = `
-  <script>window.__PULSE_STATE__ = ${JSON.stringify(hydrationState)}</script>
-`;
-```
-
-### Client Side (Hydration)
-
-```typescript
-import { hydrate } from "@pulse-js/core";
-
-// 1. Hydrate before rendering
-hydrate(window.__PULSE_STATE__);
-```
-
-### Mental Model
-
-Compare Pulse primitives:
-
-| Concept     | Can be async | Has state | Observable | Purpose                              |
-| :---------- | :----------: | :-------: | :--------: | :----------------------------------- |
-| **Source**  |      ❌      |    ❌     |     ✅     | Reactive data (facts).               |
-| **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
-| **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
-
 ## Framework Integrations
 
-Pulse provides official adapters for major frameworks to ensure seamless integration.
+Pulse provides official adapters for all major frameworks.
 
-| Framework  | Package            | Documentation                                                |
-| :--------- | :----------------- | :----------------------------------------------------------- |
-| **React**  | `@pulse-js/react`  | [Read Docs](https://pulse-js.vercel.app/integrations/react)  |
-| **Vue**    | `@pulse-js/vue`    | [Read Docs](https://pulse-js.vercel.app/integrations/vue)    |
-| **Svelte** | `@pulse-js/svelte` | [Read Docs](https://pulse-js.vercel.app/integrations/svelte) |
+| Framework    | Package              | Status |
+| :----------- | :------------------- | :----- |
+| **Astro**    | `@pulse-js/astro`    | NEW    |
+| **React**    | `@pulse-js/react`    | Stable |
+| **Vue**      | `@pulse-js/vue`      | Stable |
+| **Svelte**   | `@pulse-js/svelte`   | Stable |
+| **TanStack** | `@pulse-js/tanstack` | NEW    |
 
 ## Developer Tools
 
-Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a powerful framework-agnostic inspector.
-
-### Features
+Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a decoupled Agent-Client inspector.
 
-- **Component Tree**: Visualize your entire guard dependency graph.
-- **Editable Logic**: Update source values directly from the UI to test logic branches.
-- **Time Travel**: (Coming Soon) Replay state changes.
+- **Agent-Client Architecture**: Isolated UI that doesn't restart your app.
+- **Dependency Graph**: Visualize how your guards are connected.
+- **Glassmorphism UI**: A premium, draggable development experience.
 - **Zero Config**: Works out of the box with `@pulse-js/tools`.

package/dist/index.cjs

@@ -21,16 +21,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   PulseRegistry: () => PulseRegistry,
+  batch: () => batch,
   compute: () => compute,
+  createSignal: () => createSignal,
+  effect: () => effect,
   evaluate: () => evaluate,
   getCurrentGuard: () => getCurrentGuard,
   guard: () => extendedGuard,
   guardFail: () => guardFail,
   guardOk: () => guardOk,
   hydrate: () => hydrate,
+  isPulseObject: () => isPulseObject,
+  pulse: () => pulse,
+  readonly: () => readonly,
   registerGuardForHydration: () => registerGuardForHydration,
   runInContext: () => runInContext,
-  source: () => source
+  source: () => source,
+  toRaw: () => toRaw
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -316,9 +323,8 @@ function guard(nameOrFn, fn) {
   if (name) {
     registerGuardForHydration(name, g);
   }
-  PulseRegistry.register(g);
   evaluate2();
-  return g;
+  return PulseRegistry.register(g);
 }
 guard.map = function(source2, mapper, name) {
   const guardName = name || `map-${source2._name || "source"}`;
@@ -327,69 +333,132 @@ guard.map = function(source2, mapper, name) {
     return mapper(value);
   });
 };
+guard.select = function(pulseObj, selector, name) {
+  const guardName = name || `select-${pulseObj._name || "pulse"}`;
+  return guard(guardName, () => {
+    return selector(pulseObj);
+  });
+};
+guard.from = function(getValue, options) {
+  const name = options?.name || "from-external";
+  return guard(name, () => {
+    const result = getValue();
+    if (result && typeof result === "object" && ("value" in result || "isLoading" in result || "error" in result)) {
+      const wrapped = result;
+      if (wrapped.isLoading) {
+        return void 0;
+      }
+      if (wrapped.error) {
+        guardFail(wrapped.error?.message || "External error");
+      }
+      return wrapped.value;
+    }
+    return result;
+  });
+};
 
 // src/registry.ts
+function generateUID(name, sourceInfo) {
+  if (sourceInfo?.file && sourceInfo?.line) {
+    return `${sourceInfo.file}:${sourceInfo.line}:${name}`;
+  }
+  return `pulse:${name}`;
+}
 var Registry = class {
-  units = /* @__PURE__ */ new Map();
+  targets = /* @__PURE__ */ new Map();
+  proxies = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
   currentGeneration = 0;
   cleanupScheduled = false;
+  hmrDebounce = null;
+  /**
+   * Registers a unit and returns a stable Identity Proxy.
+   * 
+   * If a unit with the same UID already exists, it updates the internal
+   * target of the existing proxy and returns that same proxy.
+   */
+  register(unit) {
+    const meta = unit;
+    const name = meta._name;
+    if (!name) return unit;
+    const uid = generateUID(name, meta._sourceInfo);
+    meta._uid = uid;
+    const existingTarget = this.targets.get(uid);
+    const existingProxy = this.proxies.get(uid);
+    if (existingProxy) {
+      if (this.targets.get(uid) !== unit) {
+        if (this.currentGeneration === unit._generation) {
+        }
+        this.targets.set(uid, unit);
+        this.notifyListeners(unit, "update");
+      }
+      return existingProxy;
+    }
+    this.targets.set(uid, unit);
+    const self = this;
+    const proxy = new Proxy((() => {
+    }), {
+      get(_, prop) {
+        const target = self.targets.get(uid);
+        if (!target) return void 0;
+        const value = target[prop];
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+      apply(_, thisArg, args) {
+        const target = self.targets.get(uid);
+        if (typeof target !== "function") return void 0;
+        return Reflect.apply(target, thisArg, args);
+      },
+      // Ensure type checking and other proxy traps work
+      getPrototypeOf(_) {
+        return Object.getPrototypeOf(self.targets.get(uid) || {});
+      },
+      has(_, prop) {
+        return Reflect.has(self.targets.get(uid) || {}, prop);
+      },
+      ownKeys(_) {
+        return Reflect.ownKeys(self.targets.get(uid) || {});
+      },
+      getOwnPropertyDescriptor(_, prop) {
+        return Reflect.getOwnPropertyDescriptor(self.targets.get(uid) || {}, prop);
+      }
+    });
+    this.proxies.set(uid, proxy);
+    this.notifyListeners(unit, "add");
+    return proxy;
+  }
   /**
-   * Schedules cleanup of units that weren't re-registered (deleted from code).
+   * Schedules cleanup of units that weren't re-registered.
    */
   scheduleCleanup() {
     if (this.cleanupScheduled) return;
     this.cleanupScheduled = true;
-    setTimeout(() => {
+    if (this.hmrDebounce) clearTimeout(this.hmrDebounce);
+    this.hmrDebounce = setTimeout(() => {
       this.cleanupDeadUnits();
       this.cleanupScheduled = false;
-    }, 100);
+      this.hmrDebounce = null;
+    }, 150);
   }
-  /**
-   * Removes units that weren't re-registered in the current generation.
-   * Uses mark-and-sweep: units that were re-registered have current generation,
-   * units that weren't are from old generation and should be removed.
-   */
   cleanupDeadUnits() {
-    const toDelete = [];
-    this.units.forEach((unit, key) => {
-      const gen = unit._generation;
-      if (gen !== void 0 && gen < this.currentGeneration) {
-        toDelete.push(key);
-      }
-    });
-    toDelete.forEach((key) => this.units.delete(key));
-    if (toDelete.length > 0) {
-      console.log(`[Pulse] Cleaned up ${toDelete.length} deleted units after HMR`);
-    }
   }
-  /**
-   * Registers a unit (only if it has an explicit name).
-   */
-  register(unit) {
-    const unitWithMetadata = unit;
-    const name = unitWithMetadata._name;
-    if (!name) {
-      return;
-    }
-    const existingUnit = this.units.get(name);
-    if (existingUnit) {
-      const existingGen = existingUnit?._generation;
-      if (existingGen === this.currentGeneration) {
-        unitWithMetadata._generation = this.currentGeneration;
-        this.units.set(name, unit);
-        this.listeners.forEach((l) => l(unit));
-        return;
-      }
-      this.currentGeneration++;
-      this.scheduleCleanup();
-    }
-    unitWithMetadata._generation = this.currentGeneration;
-    this.units.set(name, unit);
-    this.listeners.forEach((l) => l(unit));
+  notifyListeners(unit, event) {
+    this.listeners.forEach((l) => l(unit, event));
+  }
+  get(nameOrUid) {
+    const proxy = this.proxies.get(nameOrUid);
+    if (proxy) return proxy;
+    const uid = generateUID(nameOrUid);
+    return this.proxies.get(uid);
   }
   getAll() {
-    return Array.from(this.units.values());
+    return Array.from(this.proxies.values());
+  }
+  getAllWithMeta() {
+    return Array.from(this.proxies.entries()).map(([uid, unit]) => ({
+      unit,
+      uid
+    }));
   }
   onRegister(listener) {
     this.listeners.add(listener);
@@ -398,7 +467,8 @@ var Registry = class {
     };
   }
   reset() {
-    this.units.clear();
+    this.targets.clear();
+    this.proxies.clear();
     this.currentGeneration = 0;
   }
 };
@@ -440,8 +510,192 @@ function source(initialValue, options = {}) {
     return () => subscribers.delete(listener);
   };
   s._name = options.name;
-  PulseRegistry.register(s);
-  return s;
+  return PulseRegistry.register(s);
+}
+
+// src/signal.ts
+var batchQueue = null;
+var batchDepth = 0;
+function batch(fn) {
+  batchDepth++;
+  if (!batchQueue) {
+    batchQueue = /* @__PURE__ */ new Set();
+  }
+  try {
+    fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0 && batchQueue) {
+      const queue = batchQueue;
+      batchQueue = null;
+      queue.forEach((notify) => notify());
+    }
+  }
+}
+function scheduleNotification(notify) {
+  if (batchQueue) {
+    batchQueue.add(notify);
+  } else {
+    notify();
+  }
+}
+function createSignal(initialValue, equals = (a, b) => a === b) {
+  let value = initialValue;
+  const subscribers = /* @__PURE__ */ new Set();
+  const dependents = /* @__PURE__ */ new Set();
+  const notify = () => {
+    subscribers.forEach((sub) => sub(value));
+    const deps = Array.from(dependents);
+    dependents.clear();
+    deps.forEach((dep) => dep.notify());
+  };
+  const signal = {
+    get() {
+      const activeGuard = getCurrentGuard();
+      if (activeGuard) {
+        dependents.add(activeGuard);
+        activeGuard.addDependency(signal);
+      }
+      return value;
+    },
+    peek() {
+      return value;
+    },
+    set(newValue) {
+      if (!equals(value, newValue)) {
+        value = newValue;
+        scheduleNotification(notify);
+      }
+    },
+    update(fn) {
+      signal.set(fn(value));
+    },
+    subscribe(listener) {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    }
+  };
+  return signal;
+}
+function effect(fn) {
+  let cleanup;
+  let disposed = false;
+  const run = () => {
+    if (disposed) return;
+    if (cleanup) cleanup();
+    cleanup = fn();
+  };
+  run();
+  return () => {
+    disposed = true;
+    if (cleanup) cleanup();
+  };
+}
+
+// src/pulse.ts
+var PULSE_META = /* @__PURE__ */ Symbol("PULSE_META");
+function pulse(target, options = {}) {
+  const { name, deep = true } = options;
+  const signals = /* @__PURE__ */ new Map();
+  const subscribers = /* @__PURE__ */ new Set();
+  const dependents = /* @__PURE__ */ new Set();
+  const nestedCache = /* @__PURE__ */ new Map();
+  const meta = {
+    signals,
+    subscribers,
+    dependents,
+    name,
+    target
+  };
+  function getSignal(key) {
+    if (!signals.has(key)) {
+      const initialValue = target[key];
+      signals.set(key, createSignal(initialValue));
+    }
+    return signals.get(key);
+  }
+  function notify() {
+    subscribers.forEach((sub) => sub(proxy));
+    const deps = Array.from(dependents);
+    dependents.clear();
+    deps.forEach((dep) => dep.notify());
+  }
+  function trackAccess() {
+    const activeGuard = getCurrentGuard();
+    if (activeGuard) {
+      dependents.add(activeGuard);
+      activeGuard.addDependency(proxy);
+    }
+  }
+  const proxy = new Proxy(target, {
+    get(obj, prop) {
+      if (prop === PULSE_META) return meta;
+      if (prop === "$raw") return target;
+      if (prop === "$subscribe") {
+        return (listener) => {
+          subscribers.add(listener);
+          return () => subscribers.delete(listener);
+        };
+      }
+      if (prop === "$snapshot") {
+        return () => ({ ...target });
+      }
+      const value = obj[prop];
+      if (typeof value === "function") {
+        return value.bind(proxy);
+      }
+      trackAccess();
+      const signal = getSignal(prop);
+      const currentValue = signal.get();
+      if (deep && currentValue !== null && typeof currentValue === "object" && !isPulseObject(currentValue)) {
+        if (!nestedCache.has(prop)) {
+          nestedCache.set(prop, pulse(currentValue, { deep, name: name ? `${name}.${String(prop)}` : void 0 }));
+        }
+        return nestedCache.get(prop);
+      }
+      return currentValue;
+    },
+    set(obj, prop, value) {
+      const oldValue = obj[prop];
+      if (oldValue === value) return true;
+      obj[prop] = value;
+      getSignal(prop).set(value);
+      notify();
+      return true;
+    },
+    has(obj, prop) {
+      if (prop === PULSE_META) return true;
+      trackAccess();
+      return Reflect.has(obj, prop);
+    },
+    ownKeys(obj) {
+      trackAccess();
+      return Reflect.ownKeys(obj);
+    }
+  });
+  return PulseRegistry.register(proxy);
+}
+function isPulseObject(value) {
+  return value !== null && typeof value === "object" && PULSE_META in value;
+}
+function toRaw(pulseObj) {
+  return pulseObj.$raw;
+}
+function readonly(pulseObj) {
+  return new Proxy(pulseObj, {
+    set() {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        console.warn("[Pulse] Attempted to mutate a readonly pulse object");
+      }
+      return false;
+    },
+    deleteProperty() {
+      if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+        console.warn("[Pulse] Attempted to delete from a readonly pulse object");
+      }
+      return false;
+    }
+  });
 }
 
 // src/compute.ts
@@ -510,14 +764,21 @@ var extendedGuard = Object.assign(guard, guardExtensions);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PulseRegistry,
+  batch,
   compute,
+  createSignal,
+  effect,
   evaluate,
   getCurrentGuard,
   guard,
   guardFail,
   guardOk,
   hydrate,
+  isPulseObject,
+  pulse,
+  readonly,
   registerGuardForHydration,
   runInContext,
-  source
+  source,
+  toRaw
 });