@pulse-js/react 0.1.3 → 0.1.5

package/README.md

@@ -57,13 +57,23 @@ function ProtectedRoute() {
   }
 
   if (status === "fail") {
-    return <AccessDenied message={reason} />;
+    return <AccessDenied message={formatReason(reason)} />;
   }
 
   return <AdminDashboard />;
 }
 ```
 
+### Rendering Failure Reasons
+
+The `reason` property in a `GuardState` can be a string or a `GuardReason` object. To render it safely in JSX, use the `formatReason` helper:
+
+```tsx
+import { formatReason } from "@pulse-js/react";
+
+<p className="error">{formatReason(reason)}</p>;
+```
+
 ## Developer Tools
 
 Pulse provides a dedicated inspector for debugging your reactive graph. In React applications, you can enable it with zero configuration.

package/dist/index.cjs

@@ -20,27 +20,66 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  formatReason: () => formatReason,
+  useGuard: () => useGuard,
   usePulse: () => usePulse
 });
 module.exports = __toCommonJS(index_exports);
 var import_react = require("react");
+var isServer = typeof window === "undefined";
+var promiseCache = /* @__PURE__ */ new WeakMap();
+function getGuardPromise(g) {
+  if (promiseCache.has(g)) return promiseCache.get(g);
+  const promise = new Promise((resolve) => {
+    const check = () => {
+      const state = g.state();
+      if (state.status !== "pending") {
+        unsub();
+        resolve(state);
+      }
+    };
+    const unsub = g.subscribe(check);
+    check();
+  });
+  promiseCache.set(g, promise);
+  return promise;
+}
 function usePulse(unit) {
-  const isGuard = "state" in unit;
+  const isGuard = unit !== null && typeof unit === "function" && "state" in unit;
+  if (isServer) {
+    return isGuard ? unit.state() : unit();
+  }
   if (isGuard) {
     const g = unit;
     return (0, import_react.useSyncExternalStore)(
       g.subscribe,
-      g.state
+      () => g.state(),
+      () => g.state()
     );
   } else {
     const s = unit;
     return (0, import_react.useSyncExternalStore)(
       s.subscribe,
-      s
+      () => s(),
+      () => s()
     );
   }
 }
+function useGuard(guard, options) {
+  const state = usePulse(guard);
+  if (options?.suspend && state.status === "pending") {
+    throw getGuardPromise(guard);
+  }
+  return state;
+}
+function formatReason(reason) {
+  if (!reason) return "";
+  if (typeof reason === "string") return reason;
+  return reason.toString();
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  formatReason,
+  useGuard,
   usePulse
 });

package/dist/index.d.cts

@@ -26,5 +26,39 @@ import { Source, Guard, GuardState } from '@pulse-js/core';
  */
 declare function usePulse<T>(unit: Source<T>): T;
 declare function usePulse<T>(unit: Guard<T>): GuardState<T>;
+/**
+ * Options for useGuard hook.
+ */
+interface UseGuardOptions {
+    /**
+     * If true, the hook will throw a promise when the guard is in 'pending' state,
+     * triggering the nearest React Suspense boundary.
+     */
+    suspend?: boolean;
+}
+/**
+ * Explicit hook for Pulse Guards.
+ * Returns the current GuardState and updates on changes.
+ *
+ * @example
+ * const { ok, value, reason } = useGuard(authGuard, { suspend: true });
+ */
+declare function useGuard<T>(guard: Guard<T>, options?: UseGuardOptions): GuardState<T>;
+/**
+ * Formats a guard reason for display in React components.
+ * Handles both string reasons and GuardReason objects.
+ *
+ * @param reason - The reason from a guard state
+ * @returns A string suitable for rendering in React
+ *
+ * @example
+ * ```tsx
+ * const { status, reason } = usePulse(myGuard);
+ * return <p>Error: {formatReason(reason)}</p>;
+ * ```
+ */
+declare function formatReason(reason: string | {
+    toString(): string;
+} | undefined): string;
 
-export { usePulse };
+export { type UseGuardOptions, formatReason, useGuard, usePulse };

package/dist/index.d.ts

@@ -26,5 +26,39 @@ import { Source, Guard, GuardState } from '@pulse-js/core';
  */
 declare function usePulse<T>(unit: Source<T>): T;
 declare function usePulse<T>(unit: Guard<T>): GuardState<T>;
+/**
+ * Options for useGuard hook.
+ */
+interface UseGuardOptions {
+    /**
+     * If true, the hook will throw a promise when the guard is in 'pending' state,
+     * triggering the nearest React Suspense boundary.
+     */
+    suspend?: boolean;
+}
+/**
+ * Explicit hook for Pulse Guards.
+ * Returns the current GuardState and updates on changes.
+ *
+ * @example
+ * const { ok, value, reason } = useGuard(authGuard, { suspend: true });
+ */
+declare function useGuard<T>(guard: Guard<T>, options?: UseGuardOptions): GuardState<T>;
+/**
+ * Formats a guard reason for display in React components.
+ * Handles both string reasons and GuardReason objects.
+ *
+ * @param reason - The reason from a guard state
+ * @returns A string suitable for rendering in React
+ *
+ * @example
+ * ```tsx
+ * const { status, reason } = usePulse(myGuard);
+ * return <p>Error: {formatReason(reason)}</p>;
+ * ```
+ */
+declare function formatReason(reason: string | {
+    toString(): string;
+} | undefined): string;
 
-export { usePulse };
+export { type UseGuardOptions, formatReason, useGuard, usePulse };

package/dist/index.js

@@ -1,21 +1,58 @@
 // src/index.ts
 import { useSyncExternalStore } from "react";
+var isServer = typeof window === "undefined";
+var promiseCache = /* @__PURE__ */ new WeakMap();
+function getGuardPromise(g) {
+  if (promiseCache.has(g)) return promiseCache.get(g);
+  const promise = new Promise((resolve) => {
+    const check = () => {
+      const state = g.state();
+      if (state.status !== "pending") {
+        unsub();
+        resolve(state);
+      }
+    };
+    const unsub = g.subscribe(check);
+    check();
+  });
+  promiseCache.set(g, promise);
+  return promise;
+}
 function usePulse(unit) {
-  const isGuard = "state" in unit;
+  const isGuard = unit !== null && typeof unit === "function" && "state" in unit;
+  if (isServer) {
+    return isGuard ? unit.state() : unit();
+  }
   if (isGuard) {
     const g = unit;
     return useSyncExternalStore(
       g.subscribe,
-      g.state
+      () => g.state(),
+      () => g.state()
     );
   } else {
     const s = unit;
     return useSyncExternalStore(
       s.subscribe,
-      s
+      () => s(),
+      () => s()
     );
   }
 }
+function useGuard(guard, options) {
+  const state = usePulse(guard);
+  if (options?.suspend && state.status === "pending") {
+    throw getGuardPromise(guard);
+  }
+  return state;
+}
+function formatReason(reason) {
+  if (!reason) return "";
+  if (typeof reason === "string") return reason;
+  return reason.toString();
+}
 export {
+  formatReason,
+  useGuard,
   usePulse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/react",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -28,8 +28,8 @@
     "react": "^19.2.3"
   },
   "dependencies": {
-    "@pulse-js/core": "^0.1.6",
-    "@pulse-js/tools": "^0.1.3"
+    "@pulse-js/core": "^0.1.8",
+    "@pulse-js/tools": "^0.1.5"
   },
   "devDependencies": {
     "@types/bun": "latest",