@pulse-js/react 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @pulse-js/react
+
+React integration for the Pulse reactivity ecosystem. Provides hooks and utilities to consume Pulse Sources and Guards within React components efficiently.
+
+## Features
+
+- **Concurrent Mode Compatible**: Built with `useSyncExternalStore` for compatibility with React 18+ concurrent features.
+- **Zero Polling**: Logic driven by direct subscriptions to the Pulse core, ensuring updates happen exactly when state changes.
+- **Type Safety**: Full TypeScript support for inferred types from Sources and Guards.
+
+## Installation
+
+```bash
+npm install @pulse-js/react @pulse-js/core
+```
+
+## Usage
+
+The primary API is the `usePulse` hook. It adapts automatically depending on whether you pass it a Source or a Guard.
+
+### Using Sources
+
+When used with a **Source**, `usePulse` returns the current value and triggers a re-render whenever that value updates.
+
+```jsx
+import { source } from "@pulse-js/core";
+import { usePulse } from "@pulse-js/react";
+
+const counter = source(0);
+
+function Counter() {
+  const value = usePulse(counter);
+
+  return (
+    <button onClick={() => counter.update((n) => n + 1)}>Count: {value}</button>
+  );
+}
+```
+
+### Using Guards
+
+When used with a **Guard**, `usePulse` returns the complete `GuardState` object, which includes `status`, `value`, and `reason`. This allows you to handle loading and error states declaratively.
+
+```tsx
+import { guard } from "@pulse-js/core";
+import { usePulse } from "@pulse-js/react";
+
+const isAuthorized = guard("auth-check", async () => {
+  // ... async logic
+});
+
+function ProtectedRoute() {
+  const { status, reason } = usePulse(isAuthorized);
+
+  if (status === "pending") {
+    return <LoadingSpinner />;
+  }
+
+  if (status === "fail") {
+    return <AccessDenied message={reason} />;
+  }
+
+  return <AdminDashboard />;
+}
+```
+
+## API
+
+### `usePulse<T>(unit: PulseUnit<T>): T | GuardState<T>`
+
+- **Arguments**:
+  - `unit`: A Pulse Source or Guard.
+- **Returns**:
+  - For Sources: The inner value `T`.
+  - For Guards: An object `{ status: 'ok' | 'fail' | 'pending', value?: T, reason?: string }`.
+
+## Performance
+
+`@pulse-js/react` leverages modern React 18 patterns to ensure optimal performance. It avoids unnecessary re-renders by strictly tracking object references and using the `useSyncExternalStore` API to integrate with React's scheduling system.

package/dist/index.cjs

@@ -0,0 +1,46 @@
+"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, {
+  usePulse: () => usePulse
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+function usePulse(unit) {
+  const isGuard = "state" in unit;
+  if (isGuard) {
+    const g = unit;
+    return (0, import_react.useSyncExternalStore)(
+      g.subscribe,
+      g.state
+    );
+  } else {
+    const s = unit;
+    return (0, import_react.useSyncExternalStore)(
+      s.subscribe,
+      s
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  usePulse
+});

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import { Source, Guard, GuardState } from '@pulse-js/core';
+
+/**
+ * Hook to consume a Pulse Unit (Source or Guard) in a React component.
+ *
+ * - If passed a **Source**, it returns the current value and triggers a re-render when the value changes.
+ * - If passed a **Guard**, it returns the current `GuardState` (ok, fail, pending, reason, value)
+ *   and triggers a re-render when the status or value changes.
+ *
+ * @template T The underlying type of the reactive unit.
+ * @param unit The Pulse Source or Guard to observe.
+ * @returns The current value or guard state.
+ *
+ * @example
+ * ```tsx
+ * // Using a Source
+ * const count = usePulse(countSource);
+ *
+ * // Using a Guard
+ * const { status, reason, value } = usePulse(authGuard);
+ *
+ * if (status === 'pending') return <Loading />;
+ * if (status === 'fail') return <ErrorMessage message={reason} />;
+ * return <Dashboard user={value} />;
+ * ```
+ */
+declare function usePulse<T>(unit: Source<T>): T;
+declare function usePulse<T>(unit: Guard<T>): GuardState<T>;
+
+export { usePulse };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { Source, Guard, GuardState } from '@pulse-js/core';
+
+/**
+ * Hook to consume a Pulse Unit (Source or Guard) in a React component.
+ *
+ * - If passed a **Source**, it returns the current value and triggers a re-render when the value changes.
+ * - If passed a **Guard**, it returns the current `GuardState` (ok, fail, pending, reason, value)
+ *   and triggers a re-render when the status or value changes.
+ *
+ * @template T The underlying type of the reactive unit.
+ * @param unit The Pulse Source or Guard to observe.
+ * @returns The current value or guard state.
+ *
+ * @example
+ * ```tsx
+ * // Using a Source
+ * const count = usePulse(countSource);
+ *
+ * // Using a Guard
+ * const { status, reason, value } = usePulse(authGuard);
+ *
+ * if (status === 'pending') return <Loading />;
+ * if (status === 'fail') return <ErrorMessage message={reason} />;
+ * return <Dashboard user={value} />;
+ * ```
+ */
+declare function usePulse<T>(unit: Source<T>): T;
+declare function usePulse<T>(unit: Guard<T>): GuardState<T>;
+
+export { usePulse };

package/dist/index.js

@@ -0,0 +1,21 @@
+// src/index.ts
+import { useSyncExternalStore } from "react";
+function usePulse(unit) {
+  const isGuard = "state" in unit;
+  if (isGuard) {
+    const g = unit;
+    return useSyncExternalStore(
+      g.subscribe,
+      g.state
+    );
+  } else {
+    const s = unit;
+    return useSyncExternalStore(
+      s.subscribe,
+      s
+    );
+  }
+}
+export {
+  usePulse
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pulse-js/react",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun x tsup src/index.ts --format esm,cjs --dts --clean --external react",
+    "lint": "bun x tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3"
+  },
+  "dependencies": {
+    "@pulse-js/core": "^0.1.0"
+  }
+}