@pulse-js/core 0.2.1 → 0.3.0

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);
 
@@ -138,7 +145,12 @@ function guard(nameOrFn, fn) {
             if (currentId === evaluationId) {
               persistDependencies();
               if (resolved === false) {
-                const reason = name ? `${name} failed` : "condition failed";
+                const message = name ? `${name} failed` : "condition failed";
+                const reason = {
+                  code: "GUARD_FAIL",
+                  message,
+                  toString: () => message
+                };
                 state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
               } else if (resolved === void 0) {
                 state = { ...state, status: "pending", updatedAt: Date.now() };
@@ -150,13 +162,22 @@ function guard(nameOrFn, fn) {
           }).catch((err) => {
             if (currentId === evaluationId) {
               persistDependencies();
-              const message = err instanceof Error ? err.message : String(err);
-              const reason = err.meta ? {
-                code: err.code || "ERROR",
-                message,
-                meta: err.meta,
-                toString: () => message
-              } : message;
+              let reason;
+              if (err && err._pulseFail) {
+                reason = err._reason;
+              } else {
+                const message = err instanceof Error ? err.message : String(err);
+                reason = err && err.meta ? {
+                  code: err.code || "ERROR",
+                  message,
+                  meta: err.meta,
+                  toString: () => message
+                } : {
+                  code: "ERROR",
+                  message,
+                  toString: () => message
+                };
+              }
               state = {
                 status: "fail",
                 reason,
@@ -169,7 +190,12 @@ function guard(nameOrFn, fn) {
         } else {
           persistDependencies();
           if (result === false) {
-            const reason = name ? `${name} failed` : "condition failed";
+            const message = name ? `${name} failed` : "condition failed";
+            const reason = {
+              code: "GUARD_FAIL",
+              message,
+              toString: () => message
+            };
             state = { status: "fail", reason, lastReason: reason, updatedAt: Date.now() };
           } else if (result === void 0) {
             state = { ...state, status: "pending", updatedAt: Date.now() };
@@ -198,7 +224,11 @@ function guard(nameOrFn, fn) {
           message,
           meta: err.meta,
           toString: () => message
-        } : message;
+        } : {
+          code: "ERROR",
+          message,
+          toString: () => message
+        };
         state = {
           status: "fail",
           reason,
@@ -293,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"}`;
@@ -304,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;
   /**
-   * Schedules cleanup of units that weren't re-registered (deleted from code).
+   * 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.
    */
   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);
@@ -375,7 +467,8 @@ var Registry = class {
     };
   }
   reset() {
-    this.units.clear();
+    this.targets.clear();
+    this.proxies.clear();
     this.currentGeneration = 0;
   }
 };
@@ -417,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
@@ -487,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
 });