@pulse-js/core 0.1.8 → 0.1.9

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

@@ -95,7 +95,7 @@ function guardFail(reason) {
 function guardOk(value) {
   return value;
 }
-function guard(nameOrFn, fn) {
+function guard(nameOrFn, fn, _internalOffset = 3) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -293,13 +293,84 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
+  autoNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Generates a stable auto-name based on source code location.
+   * Uses file path and line number to ensure the same location always gets the same name.
+   * Cached to avoid repeated stack trace parsing.
+   */
+  generateAutoName(type, offset = 3) {
+    const err = new Error();
+    const stack = err.stack?.split("\n") || [];
+    let callSite = stack[offset]?.trim() || "";
+    const cacheKey = `${type}:${callSite}`;
+    if (this.autoNameCache.has(cacheKey)) {
+      return this.autoNameCache.get(cacheKey);
+    }
+    const match = callSite.match(/([^/\\]+)\.(?:ts|tsx|js|jsx):(\d+):\d+/);
+    let name;
+    if (match) {
+      const filename = match[1];
+      const line = match[2];
+      if (filename && line) {
+        name = `${type}@${filename}:${line}`;
+      } else {
+        name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+      }
+    } else {
+      name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+    }
+    this.autoNameCache.set(cacheKey, name);
+    return name;
+  }
+  /**
+   * Increments generation and schedules cleanup of old units.
+   * Called automatically when HMR is detected.
+   */
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    this.currentGeneration++;
+    setTimeout(() => {
+      this.cleanupOldGenerations();
+      this.cleanupScheduled = false;
+    }, 100);
+  }
+  /**
+   * Removes units from old generations (likely orphaned by HMR).
+   */
+  cleanupOldGenerations() {
+    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} stale units after HMR`);
+    }
+  }
   /**
    * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Auto-assigns stable names to unnamed units for HMR stability.
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
+  register(unit, offset = 3) {
+    const unitWithMetadata = unit;
+    let name = unitWithMetadata._name;
+    if (!name) {
+      const isGuard2 = "state" in unit;
+      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
+      unitWithMetadata._name = name;
+    }
+    unitWithMetadata._generation = this.currentGeneration;
+    if (this.units.has(name)) {
+      this.scheduleCleanup();
+    }
+    this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
   /**
@@ -320,11 +391,24 @@ var Registry = class {
       this.listeners.delete(listener);
     };
   }
+  /**
+   * Clears all registered units.
+   */
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+    this.autoNameCache.clear();
+  }
 };
-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 = {}) {
+function source(initialValue, options = {}, _internalOffset = 3) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
@@ -363,7 +447,7 @@ function compute(name, dependencies, processor) {
   return guard(name, () => {
     const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
     return processor(...values);
-  });
+  }, 4);
 }
 
 // src/composition.ts
@@ -386,7 +470,7 @@ function guardAll(nameOrGuards, maybeGuards) {
       throw new Error(message);
     }
     return true;
-  });
+  }, 4);
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -400,7 +484,7 @@ function guardAny(nameOrGuards, maybeGuards) {
       allFails.push(message);
     }
     throw new Error(allFails.length > 0 ? allFails.join(" and ") : "no conditions met");
-  });
+  }, 4);
 }
 function guardNot(nameOrTarget, maybeTarget) {
   const name = typeof nameOrTarget === "string" ? nameOrTarget : void 0;
@@ -410,7 +494,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  });
+  }, 4);
 }
 var guardExtensions = {
   all: guardAll,

package/dist/index.d.cts

@@ -186,7 +186,7 @@ declare function guardFail(reason: string | GuardReason): never;
  * Returns the value passed to it.
  */
 declare function guardOk<T>(value: T): T;
-declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>, _internalOffset?: number): Guard<T>;
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -361,7 +361,7 @@ interface Source<T> {
  * user.set({ name: 'Bob' });
  * ```
  */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
 
 /**
  * Serialized state of guards for transfer from server to client.
@@ -422,11 +422,29 @@ type PulseUnit = Source<any> | Guard<any>;
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
+    private autoNameCache;
+    /**
+     * Generates a stable auto-name based on source code location.
+     * Uses file path and line number to ensure the same location always gets the same name.
+     * Cached to avoid repeated stack trace parsing.
+     */
+    generateAutoName(type: 'source' | 'guard', offset?: number): string;
+    /**
+     * Increments generation and schedules cleanup of old units.
+     * Called automatically when HMR is detected.
+     */
+    private scheduleCleanup;
+    /**
+     * Removes units from old generations (likely orphaned by HMR).
+     */
+    private cleanupOldGenerations;
     /**
      * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Auto-assigns stable names to unnamed units for HMR stability.
      */
-    register(unit: PulseUnit): void;
+    register(unit: PulseUnit, offset?: number): void;
     /**
      * Retrieves all registered units.
      */
@@ -438,6 +456,10 @@ declare class Registry {
      * @returns Unsubscribe function.
      */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    /**
+     * Clears all registered units.
+     */
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 

package/dist/index.d.ts

@@ -186,7 +186,7 @@ declare function guardFail(reason: string | GuardReason): never;
  * Returns the value passed to it.
  */
 declare function guardOk<T>(value: T): T;
-declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>, _internalOffset?: number): Guard<T>;
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -361,7 +361,7 @@ interface Source<T> {
  * user.set({ name: 'Bob' });
  * ```
  */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+declare function source<T>(initialValue: T, options?: SourceOptions<T>, _internalOffset?: number): Source<T>;
 
 /**
  * Serialized state of guards for transfer from server to client.
@@ -422,11 +422,29 @@ type PulseUnit = Source<any> | Guard<any>;
 declare class Registry {
     private units;
     private listeners;
+    private currentGeneration;
+    private cleanupScheduled;
+    private autoNameCache;
+    /**
+     * Generates a stable auto-name based on source code location.
+     * Uses file path and line number to ensure the same location always gets the same name.
+     * Cached to avoid repeated stack trace parsing.
+     */
+    generateAutoName(type: 'source' | 'guard', offset?: number): string;
+    /**
+     * Increments generation and schedules cleanup of old units.
+     * Called automatically when HMR is detected.
+     */
+    private scheduleCleanup;
+    /**
+     * Removes units from old generations (likely orphaned by HMR).
+     */
+    private cleanupOldGenerations;
     /**
      * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
+     * Auto-assigns stable names to unnamed units for HMR stability.
      */
-    register(unit: PulseUnit): void;
+    register(unit: PulseUnit, offset?: number): void;
     /**
      * Retrieves all registered units.
      */
@@ -438,6 +456,10 @@ declare class Registry {
      * @returns Unsubscribe function.
      */
     onRegister(listener: (unit: PulseUnit) => void): () => void;
+    /**
+     * Clears all registered units.
+     */
+    reset(): void;
 }
 declare const PulseRegistry: Registry;
 

package/dist/index.js

@@ -59,7 +59,7 @@ function guardFail(reason) {
 function guardOk(value) {
   return value;
 }
-function guard(nameOrFn, fn) {
+function guard(nameOrFn, fn, _internalOffset = 3) {
   const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
   const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
   if (!evaluator) {
@@ -257,13 +257,84 @@ function guard(nameOrFn, fn) {
 var Registry = class {
   units = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
+  currentGeneration = 0;
+  cleanupScheduled = false;
+  autoNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Generates a stable auto-name based on source code location.
+   * Uses file path and line number to ensure the same location always gets the same name.
+   * Cached to avoid repeated stack trace parsing.
+   */
+  generateAutoName(type, offset = 3) {
+    const err = new Error();
+    const stack = err.stack?.split("\n") || [];
+    let callSite = stack[offset]?.trim() || "";
+    const cacheKey = `${type}:${callSite}`;
+    if (this.autoNameCache.has(cacheKey)) {
+      return this.autoNameCache.get(cacheKey);
+    }
+    const match = callSite.match(/([^/\\]+)\.(?:ts|tsx|js|jsx):(\d+):\d+/);
+    let name;
+    if (match) {
+      const filename = match[1];
+      const line = match[2];
+      if (filename && line) {
+        name = `${type}@${filename}:${line}`;
+      } else {
+        name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+      }
+    } else {
+      name = `${type}#${Math.random().toString(36).substring(2, 7)}`;
+    }
+    this.autoNameCache.set(cacheKey, name);
+    return name;
+  }
+  /**
+   * Increments generation and schedules cleanup of old units.
+   * Called automatically when HMR is detected.
+   */
+  scheduleCleanup() {
+    if (this.cleanupScheduled) return;
+    this.cleanupScheduled = true;
+    this.currentGeneration++;
+    setTimeout(() => {
+      this.cleanupOldGenerations();
+      this.cleanupScheduled = false;
+    }, 100);
+  }
+  /**
+   * Removes units from old generations (likely orphaned by HMR).
+   */
+  cleanupOldGenerations() {
+    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} stale units after HMR`);
+    }
+  }
   /**
    * Registers a new unit (Source or Guard).
-   * Uses the unit's name as a key to prevent duplicates during HMR.
+   * Auto-assigns stable names to unnamed units for HMR stability.
    */
-  register(unit) {
-    const key = unit._name || unit;
-    this.units.set(key, unit);
+  register(unit, offset = 3) {
+    const unitWithMetadata = unit;
+    let name = unitWithMetadata._name;
+    if (!name) {
+      const isGuard2 = "state" in unit;
+      name = this.generateAutoName(isGuard2 ? "guard" : "source", offset);
+      unitWithMetadata._name = name;
+    }
+    unitWithMetadata._generation = this.currentGeneration;
+    if (this.units.has(name)) {
+      this.scheduleCleanup();
+    }
+    this.units.set(name, unit);
     this.listeners.forEach((l) => l(unit));
   }
   /**
@@ -284,11 +355,24 @@ var Registry = class {
       this.listeners.delete(listener);
     };
   }
+  /**
+   * Clears all registered units.
+   */
+  reset() {
+    this.units.clear();
+    this.currentGeneration = 0;
+    this.autoNameCache.clear();
+  }
 };
-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 = {}) {
+function source(initialValue, options = {}, _internalOffset = 3) {
   let value = initialValue;
   const subscribers = /* @__PURE__ */ new Set();
   const dependents = /* @__PURE__ */ new Set();
@@ -327,7 +411,7 @@ function compute(name, dependencies, processor) {
   return guard(name, () => {
     const values = dependencies.map((dep) => typeof dep === "function" ? dep() : dep);
     return processor(...values);
-  });
+  }, 4);
 }
 
 // src/composition.ts
@@ -350,7 +434,7 @@ function guardAll(nameOrGuards, maybeGuards) {
       throw new Error(message);
     }
     return true;
-  });
+  }, 4);
 }
 function guardAny(nameOrGuards, maybeGuards) {
   const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
@@ -364,7 +448,7 @@ function guardAny(nameOrGuards, maybeGuards) {
       allFails.push(message);
     }
     throw new Error(allFails.length > 0 ? allFails.join(" and ") : "no conditions met");
-  });
+  }, 4);
 }
 function guardNot(nameOrTarget, maybeTarget) {
   const name = typeof nameOrTarget === "string" ? nameOrTarget : void 0;
@@ -374,7 +458,7 @@ function guardNot(nameOrTarget, maybeTarget) {
       return !target.ok();
     }
     return !target();
-  });
+  }, 4);
 }
 var guardExtensions = {
   all: guardAll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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": {