@pulse-js/core 0.1.8 → 0.2.0

package/README.md

@@ -2,10 +2,14 @@
 
 <img width="200" height="200" alt="logo" src="https://raw.githubusercontent.com/ZtaMDev/Pulse/refs/heads/main/pulse.svg" />
 
-# Pulse
+# Pulse-JS
+
+[![npm version](https://img.shields.io/npm/v/@pulse-js/core.svg)](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.
 
+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.
 
 </div>
@@ -146,37 +150,23 @@ Compare Pulse primitives:
 | **Guard**   |      ✅      |    ✅     |     ✅     | Business rules (conditioned truths). |
 | **Compute** |      ❌      |    ❌     |     ✅     | Pure transformations (derivations).  |
 
-## API Reference
-
-### `source<T>(initialValue: T, options?: SourceOptions)`
-
-Creates a reactive source.
-
-- `options.name`: Unique string name (highly recommended for debugging).
-- `options.equals`: Custom equality function `(prev, next) => boolean`.
-
-Methods:
-
-- `.set(value: T)`: Updates the value.
-- `.update(fn: (current: T) => T)`: Updates value using a transform.
-- `.subscribe(fn: (value: T) => void)`: Manual subscription.
-
-### `guard<T>(name: string, evaluator: () => T | Promise<T>)`
+## Framework Integrations
 
-Creates a semantic guard.
+Pulse provides official adapters for major frameworks to ensure seamless integration.
 
-Methods:
+| 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) |
 
-- `.ok()`: Returns true if status is 'ok'.
-- `.fail()`: Returns true if status is 'fail'.
-- `.pending()`: Returns true if evaluating async.
-- `.reason()`: Returns the failure message.
-- `.state()`: Returns full `{ status, value, reason }` object.
-- `.subscribe(fn: (state: GuardState) => void)`: Manual subscription.
+## Developer Tools
 
----
+Debug your reactive graph with **[Pulse Tools](https://pulse-js.vercel.app/guides/devtools/)**, a powerful framework-agnostic inspector.
 
-## Ecosystem
+### Features
 
-- **@pulse-js/react**: React bindings and hooks.
-- **@pulse-js/tools**: Visual debugging tools.
+- **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.
+- **Zero Config**: Works out of the box with `@pulse-js/tools`.

package/dist/index.cjs

@@ -293,35 +293,82 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
   /**
-   * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Schedules cleanup of units that weren't re-registered (deleted from code).
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
-    this.listeners.forEach((l) => l(unit));
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    setTimeout(() => {
+      this.cleanupDeadUnits();
+      this.cleanupScheduled = false;
+    }, 100);
   }
   /**
-   * Retrieves all registered units.
+   * 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.
    */
-  getAll() {
-    return Array.from(this.units.values());
+  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`);
+    }
   }
   /**
-   * Subscribes to new unit registrations.
-   * 
-   * @param listener - Callback receiving the newly registered unit.
-   * @returns Unsubscribe function.
+   * 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));
+  }
+  getAll() {
+    return Array.from(this.units.values());
+  }
   onRegister(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+  }
 };
-var PulseRegistry = new Registry();
+var GLOBAL_KEY = "__PULSE_REGISTRY__";
+var globalSymbols = globalThis;
+if (!globalSymbols[GLOBAL_KEY]) {
+  globalSymbols[GLOBAL_KEY] = new Registry();
+}
+var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
 function source(initialValue, options = {}) {

package/dist/index.d.cts

@@ -416,28 +416,42 @@ type PulseUnit = Source<any> | Guard<any>;
 /**
  * Root Registry for Pulse.
  *
- * It tracks all registered Units (Sources and Guards) globally, providing
- * the data source for DevTools and HMR stability.
+ * Tracks all registered Units (Sources and Guards) globally for DevTools.
+ *
+ * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
+ * Unnamed units work perfectly but are not tracked to avoid HMR instability.
+ *
+ * @example
+ * ```ts
+ * // ✅ Visible in DevTools
+ * const count = source(0, { name: 'count' });
+ *
+ * // ❌ Not visible in DevTools (but works fine)
+ * const temp = source(0);
+ * ```
  */
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
     /**
-     * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Schedules cleanup of units that weren't re-registered (deleted from code).
      */
-    register(unit: PulseUnit): void;
+    private scheduleCleanup;
     /**
-     * Retrieves all registered units.
+     * 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.
      */
-    getAll(): PulseUnit[];
+    private cleanupDeadUnits;
     /**
-     * Subscribes to new unit registrations.
-     *
-     * @param listener - Callback receiving the newly registered unit.
-     * @returns Unsubscribe function.
+     * Registers a unit (only if it has an explicit name).
      */
+    register(unit: PulseUnit): void;
+    getAll(): PulseUnit[];
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 

package/dist/index.d.ts

@@ -416,28 +416,42 @@ type PulseUnit = Source<any> | Guard<any>;
 /**
  * Root Registry for Pulse.
  *
- * It tracks all registered Units (Sources and Guards) globally, providing
- * the data source for DevTools and HMR stability.
+ * Tracks all registered Units (Sources and Guards) globally for DevTools.
+ *
+ * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
+ * Unnamed units work perfectly but are not tracked to avoid HMR instability.
+ *
+ * @example
+ * ```ts
+ * // ✅ Visible in DevTools
+ * const count = source(0, { name: 'count' });
+ *
+ * // ❌ Not visible in DevTools (but works fine)
+ * const temp = source(0);
+ * ```
  */
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
     /**
-     * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Schedules cleanup of units that weren't re-registered (deleted from code).
      */
-    register(unit: PulseUnit): void;
+    private scheduleCleanup;
     /**
-     * Retrieves all registered units.
+     * 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.
      */
-    getAll(): PulseUnit[];
+    private cleanupDeadUnits;
     /**
-     * Subscribes to new unit registrations.
-     *
-     * @param listener - Callback receiving the newly registered unit.
-     * @returns Unsubscribe function.
+     * Registers a unit (only if it has an explicit name).
      */
+    register(unit: PulseUnit): void;
+    getAll(): PulseUnit[];
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 

package/dist/index.js

@@ -257,35 +257,82 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
   /**
-   * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Schedules cleanup of units that weren't re-registered (deleted from code).
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
-    this.listeners.forEach((l) => l(unit));
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    setTimeout(() => {
+      this.cleanupDeadUnits();
+      this.cleanupScheduled = false;
+    }, 100);
   }
   /**
-   * Retrieves all registered units.
+   * 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.
    */
-  getAll() {
-    return Array.from(this.units.values());
+  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`);
+    }
   }
   /**
-   * Subscribes to new unit registrations.
-   * 
-   * @param listener - Callback receiving the newly registered unit.
-   * @returns Unsubscribe function.
+   * 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));
+  }
+  getAll() {
+    return Array.from(this.units.values());
+  }
   onRegister(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+  }
 };
-var PulseRegistry = new Registry();
+var GLOBAL_KEY = "__PULSE_REGISTRY__";
+var globalSymbols = globalThis;
+if (!globalSymbols[GLOBAL_KEY]) {
+  globalSymbols[GLOBAL_KEY] = new Registry();
+}
+var PulseRegistry = globalSymbols[GLOBAL_KEY];
 
 // src/source.ts
 function source(initialValue, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -18,7 +18,8 @@
   "description": "A semantic reactivity system for modern applications. Separate reactive data (sources) from business conditions (guards) with a declarative, composable, and observable approach.",
   "workspaces": [
     "packages/*",
-    "tests"
+    "tests",
+    "tests/*"
   ],
   "keywords": [
     "reactivity",
@@ -37,7 +38,7 @@
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/ZtaMDev/pulse/issues"
+    "url": "https://github.com/ZtaMDev/pulse-js/issues"
   },
   "license": "MIT",
   "scripts": {