@pulse-js/core 0.1.1 → 0.1.2

package/README.md

@@ -1,15 +1,31 @@
+<div align="center">
+
+<img width="200" height="200" alt="logo" src="./pulse.svg" />
+
 # Pulse
 
-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 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.
+</div>
 
 ## Installation
 
 ```bash
-npm install @pulse-js/core @pulse-js/react @pulse-js/tools
-# or
-bun add @pulse-js/core @pulse-js/react @pulse-js/tools
+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

package/dist/index.cjs

@@ -0,0 +1,324 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PulseRegistry: () => PulseRegistry,
+  evaluate: () => evaluate,
+  getCurrentGuard: () => getCurrentGuard,
+  guard: () => extendedGuard,
+  hydrate: () => hydrate,
+  registerGuardForHydration: () => registerGuardForHydration,
+  runInContext: () => runInContext,
+  source: () => source
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tracking.ts
+var activeGuard = null;
+function runInContext(guard2, fn) {
+  const prev = activeGuard;
+  activeGuard = guard2;
+  try {
+    return fn();
+  } finally {
+    activeGuard = prev;
+  }
+}
+function getCurrentGuard() {
+  return activeGuard;
+}
+
+// src/ssr.ts
+var guardRegistry = /* @__PURE__ */ new Map();
+function registerGuardForHydration(name, guard2) {
+  guardRegistry.set(name, guard2);
+}
+async function evaluate(guards) {
+  const state = {};
+  await Promise.all(guards.map(async (g) => {
+    while (g.pending()) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }));
+  guards.forEach((g) => {
+    const name = g._name;
+    if (name) {
+      state[name] = g.state();
+    }
+  });
+  return state;
+}
+function hydrate(state) {
+  Object.entries(state).forEach(([name, guardState]) => {
+    const g = guardRegistry.get(name);
+    if (g && g._hydrate) {
+      g._hydrate(guardState);
+    }
+  });
+}
+
+// src/guard.ts
+function guard(nameOrFn, fn) {
+  const name = typeof nameOrFn === "string" ? nameOrFn : void 0;
+  const evaluator = typeof nameOrFn === "function" ? nameOrFn : fn;
+  if (!evaluator) {
+    throw new Error("Guard requires an evaluator function");
+  }
+  let state = { status: "pending" };
+  const dependents = /* @__PURE__ */ new Set();
+  const subscribers = /* @__PURE__ */ new Set();
+  let evaluationId = 0;
+  const node = {
+    addDependency(trackable) {
+    },
+    notify() {
+      evaluate2();
+    }
+  };
+  const evaluate2 = () => {
+    const currentId = ++evaluationId;
+    const oldStatus = state.status;
+    const oldValue = state.value;
+    try {
+      const result = runInContext(node, () => evaluator());
+      if (result instanceof Promise) {
+        state = { status: "pending" };
+        result.then((resolved) => {
+          if (currentId === evaluationId) {
+            if (resolved === false) {
+              state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+            } else {
+              state = { status: "ok", value: resolved };
+            }
+            notifyDependents();
+          }
+        }).catch((err) => {
+          if (currentId === evaluationId) {
+            state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+            notifyDependents();
+          }
+        });
+      } else {
+        if (result === false) {
+          state = { status: "fail", reason: name ? `${name} failed` : "condition failed" };
+        } else {
+          state = { status: "ok", value: result };
+        }
+        if (oldStatus !== state.status || oldValue !== state.value) {
+          notifyDependents();
+        }
+      }
+    } catch (err) {
+      state = { status: "fail", reason: err instanceof Error ? err.message : String(err) };
+      notifyDependents();
+    }
+  };
+  const notifyDependents = () => {
+    const deps = Array.from(dependents);
+    dependents.clear();
+    deps.forEach((dep) => dep.notify());
+    subscribers.forEach((sub) => sub({ ...state }));
+  };
+  evaluate2();
+  const handleRead = () => {
+    const activeGuard2 = getCurrentGuard();
+    if (activeGuard2 && activeGuard2 !== node) {
+      dependents.add(activeGuard2);
+    }
+  };
+  const g = (() => {
+    handleRead();
+    return state.status === "ok" ? state.value : void 0;
+  });
+  g.ok = () => {
+    handleRead();
+    return state.status === "ok";
+  };
+  g.fail = () => {
+    handleRead();
+    return state.status === "fail";
+  };
+  g.pending = () => {
+    handleRead();
+    return state.status === "pending";
+  };
+  g.reason = () => {
+    handleRead();
+    return state.reason;
+  };
+  g.state = () => {
+    handleRead();
+    return state;
+  };
+  g.subscribe = (listener) => {
+    subscribers.add(listener);
+    return () => subscribers.delete(listener);
+  };
+  g._evaluate = () => evaluate2();
+  g._name = name;
+  g._hydrate = (newState) => {
+    state = newState;
+    evaluationId++;
+    notifyDependents();
+  };
+  if (name) {
+    registerGuardForHydration(name, g);
+  }
+  PulseRegistry.register(g);
+  return g;
+}
+
+// src/registry.ts
+var Registry = class {
+  units = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  /**
+   * Registers a new unit (Source or Guard).
+   * Uses the unit's name as a key to prevent duplicates during HMR.
+   */
+  register(unit) {
+    const key = unit._name || unit;
+    this.units.set(key, unit);
+    this.listeners.forEach((l) => l(unit));
+  }
+  /**
+   * Retrieves all registered units.
+   */
+  getAll() {
+    return Array.from(this.units.values());
+  }
+  /**
+   * Subscribes to new unit registrations.
+   * 
+   * @param listener - Callback receiving the newly registered unit.
+   * @returns Unsubscribe function.
+   */
+  onRegister(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+};
+var PulseRegistry = new Registry();
+
+// src/source.ts
+function source(initialValue, options = {}) {
+  let value = initialValue;
+  const subscribers = /* @__PURE__ */ new Set();
+  const dependents = /* @__PURE__ */ new Set();
+  const s = (() => {
+    const activeGuard2 = getCurrentGuard();
+    if (activeGuard2) {
+      dependents.add(activeGuard2);
+    }
+    return value;
+  });
+  s.set = (newValue) => {
+    const equals = options.equals || ((a, b) => a === b);
+    if (!equals(value, newValue)) {
+      value = newValue;
+      subscribers.forEach((sub) => sub(value));
+      const deps = Array.from(dependents);
+      dependents.clear();
+      deps.forEach((dep) => dep.notify());
+    }
+  };
+  s.update = (updater) => {
+    s.set(updater(value));
+  };
+  s.subscribe = (listener) => {
+    subscribers.add(listener);
+    return () => subscribers.delete(listener);
+  };
+  s._name = options.name;
+  PulseRegistry.register(s);
+  return s;
+}
+
+// src/composition.ts
+function isGuard(target) {
+  return typeof target === "function" && "ok" in target;
+}
+function guardAll(nameOrGuards, maybeGuards) {
+  const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
+  const guards = Array.isArray(nameOrGuards) ? nameOrGuards : maybeGuards;
+  return guard(name, () => {
+    let firstFail = null;
+    for (const g of guards) {
+      if (!g.ok()) {
+        if (!firstFail) firstFail = g;
+      }
+    }
+    if (firstFail) {
+      throw new Error(firstFail.reason() || "condition failed");
+    }
+    return true;
+  });
+}
+function guardAny(nameOrGuards, maybeGuards) {
+  const name = typeof nameOrGuards === "string" ? nameOrGuards : void 0;
+  const guards = Array.isArray(nameOrGuards) ? nameOrGuards : maybeGuards;
+  return guard(name, () => {
+    let allFails = [];
+    for (const g of guards) {
+      if (g.ok()) return true;
+      allFails.push(g.reason() || "failed");
+    }
+    throw new Error(allFails.length > 0 ? allFails.join(" and ") : "no conditions met");
+  });
+}
+function guardNot(nameOrTarget, maybeTarget) {
+  const name = typeof nameOrTarget === "string" ? nameOrTarget : void 0;
+  const target = typeof nameOrTarget === "string" ? maybeTarget : nameOrTarget;
+  return guard(name, () => {
+    if (isGuard(target)) {
+      return !target.ok();
+    }
+    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
+};
+
+// src/index.ts
+var extendedGuard = Object.assign(guard, guardExtensions);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PulseRegistry,
+  evaluate,
+  getCurrentGuard,
+  guard,
+  hydrate,
+  registerGuardForHydration,
+  runInContext,
+  source
+});