@pulse-js/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZtaMDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# Pulse
+
+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.
+
+## Installation
+
+```bash
+npm install @pulse-js/core @pulse-js/react @pulse-js/devtools
+# or
+bun add @pulse-js/core @pulse-js/react @pulse-js/devtools
+```
+
+## Core Concepts
+
+### Sources (Refined Data)
+
+Sources are the primitive containers for your application state. They hold values and notify dependents when those values change.
+
+```typescript
+import { source } from "@pulse-js/core";
+
+// Create a source
+const user = source({ name: "Alice", id: 1 });
+const rawCount = source(0);
+
+// Read the value (dependencies are tracked automatically if called inside a Guard)
+console.log(user());
+
+// Update the value
+user.set({ name: "Bob", id: 1 });
+
+// Update using a callback
+rawCount.update((n) => n + 1);
+```
+
+### Guards (Semantic Logic)
+
+Guards represent business rules or derivations. They are not just boolean flags; they track their own state including `status` (ok, fail, pending) and `reason` (why it failed).
+
+```typescript
+import { guard } from "@pulse-js/core";
+
+// Synchronous Guard
+const isAdmin = guard("is-admin", () => {
+  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"
+}
+```
+
+### Async Guards
+
+Pulse handles asynchronous logic natively. Guards can return Promises, and their status will automatically transition from `pending` to `ok` or `fail`.
+
+```typescript
+const isServerOnline = guard("check-server", async () => {
+  const response = await fetch("/health");
+  if (!response.ok) throw new Error("Server unreachable");
+  return true;
+});
+
+// Check status synchronously non-blocking
+if (isServerOnline.pending()) {
+  showSpinner();
+}
+```
+
+### Composition
+
+Guards can be composed using logical operators. This creates a semantic tree of conditions that is easy to debug.
+
+```typescript
+import { guard } from "@pulse-js/core";
+
+// .all() - Success only if ALL pass. Fails with the reason of the first failure.
+const canCheckout = guard.all("can-checkout", [
+  isAuthenticated,
+  hasItemsInCart,
+  isServerOnline,
+]);
+
+// .any() - Success if AT LEAST ONE passes.
+const hasAccess = guard.any("has-access", [isAdmin, isEditor]);
+
+// .not() - Inverts the logical result.
+const isGuest = guard.not("is-guest", isAuthenticated);
+```
+
+### Computed Values
+
+You can derive new data from sources or other guards using `guard.compute`.
+
+```typescript
+const fullName = guard.compute(
+  "full-name",
+  [firstName, lastName],
+  (first, last) => {
+    return `${first} ${last}`;
+  }
+);
+```
+
+## 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__);
+```
+
+## 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>)`
+
+Creates a semantic guard.
+
+Methods:
+
+- `.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.
+
+---
+
+## Ecosystem
+
+- **@pulse-js/react**: React bindings and hooks.
+- **@pulse-js/devtools**: Visual debugging tools.

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
+});