@pulse-js/core 0.2.0 → 0.2.1

package/dist/index.cjs

@@ -259,11 +259,20 @@ function guard(nameOrFn, fn) {
     lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
-      deps.push({
-        name: depName,
-        type: isG ? "guard" : "source",
-        status: isG ? dep.state().status : void 0
-      });
+      if (isG) {
+        const depState = dep.state();
+        deps.push({
+          name: depName,
+          type: "guard",
+          status: depState.status,
+          reason: depState.status === "fail" ? depState.reason : void 0
+        });
+      } else {
+        deps.push({
+          name: depName,
+          type: "source"
+        });
+      }
     });
     return {
       name: name || "guard",
@@ -288,6 +297,13 @@ function guard(nameOrFn, fn) {
   evaluate2();
   return g;
 }
+guard.map = function(source2, mapper, name) {
+  const guardName = name || `map-${source2._name || "source"}`;
+  return guard(guardName, () => {
+    const value = source2();
+    return mapper(value);
+  });
+};
 
 // src/registry.ts
 var Registry = class {

package/dist/index.d.cts

@@ -41,6 +41,118 @@ declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
  */
 declare function getCurrentGuard(): GuardNode | null;
 
+/**
+ * Options for configuring a Pulse Source.
+ *
+ * @template T - The type of value stored in the source.
+ */
+interface SourceOptions<T> {
+    /**
+     * A descriptive name for the source.
+     * Required for SSR hydration and highly recommended for debugging in DevTools.
+     */
+    name?: string;
+    /**
+     * Custom equality function to determine if a value has changed.
+     * By default, Pulse uses strict equality (`===`).
+     *
+     * @param a - The current value.
+     * @param b - The new value.
+     * @returns `true` if the values are considered equal, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const list = source([1], {
+     *   equals: (a, b) => a.length === b.length
+     * });
+     * ```
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * A Pulse Source is a reactive container for a value.
+ * It tracks which Guards read its value and notifies them when it changes.
+ *
+ * @template T The type of the value held by the source.
+ */
+interface Source<T> {
+    /**
+     * Returns the current value of the source.
+     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * console.log(count()); // 0
+     * ```
+     */
+    (): T;
+    /**
+     * Updates the source with a new value.
+     * If the value is different (based on strict equality or `options.equals`),
+     * all dependent Guards and subscribers will be notified.
+     *
+     * @param value The new value to set.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.set(1); // Triggers re-evaluation of dependents
+     * ```
+     *
+     * @error
+     * Common error: Mutating an object property without setting a new object reference.
+     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
+     * Solution: Always provide a new object or implement a custom `equals`.
+     */
+    set(value: T): void;
+    /**
+     * Updates the source value using a transformer function based on the current value.
+     * Useful for increments or toggles.
+     *
+     * @param updater A function that receives the current value and returns the new value.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.update(n => n + 1);
+     * ```
+     */
+    update(updater: (current: T) => T): void;
+    /**
+     * Manually subscribes to changes in the source value.
+     *
+     * @param listener A callback that receives the new value.
+     * @returns An unsubscription function.
+     *
+     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
+     */
+    subscribe(listener: Subscriber<T>): () => void;
+}
+/**
+ * Creates a new Pulse Source.
+ *
+ * Sources are the fundamental building blocks of state in Pulse. They hold a value
+ * and track which Guards depend on them.
+ *
+ * @template T - The type of value to store.
+ * @param initialValue - The initial state.
+ * @param options - Configuration options (name, equality).
+ * @returns A reactive Pulse Source.
+ *
+ * @example
+ * ```ts
+ * const user = source({ name: 'Alice' }, { name: 'user_state' });
+ *
+ * // Read value (auto-tracks if inside a guard)
+ * console.log(user());
+ *
+ * // Update value
+ * user.set({ name: 'Bob' });
+ * ```
+ */
+declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
@@ -86,6 +198,7 @@ interface GuardExplanation {
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
+        reason?: string | GuardReason;
     }>;
 }
 /**
@@ -187,6 +300,9 @@ declare function guardFail(reason: string | GuardReason): never;
  */
 declare function guardOk<T>(value: T): T;
 declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare namespace guard {
+    var map: <T, U>(source: Source<T>, mapper: (value: T) => U | Promise<U>, name?: string) => Guard<U>;
+}
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -251,118 +367,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
-/**
- * Options for configuring a Pulse Source.
- *
- * @template T - The type of value stored in the source.
- */
-interface SourceOptions<T> {
-    /**
-     * A descriptive name for the source.
-     * Required for SSR hydration and highly recommended for debugging in DevTools.
-     */
-    name?: string;
-    /**
-     * Custom equality function to determine if a value has changed.
-     * By default, Pulse uses strict equality (`===`).
-     *
-     * @param a - The current value.
-     * @param b - The new value.
-     * @returns `true` if the values are considered equal, `false` otherwise.
-     *
-     * @example
-     * ```ts
-     * const list = source([1], {
-     *   equals: (a, b) => a.length === b.length
-     * });
-     * ```
-     */
-    equals?: (a: T, b: T) => boolean;
-}
-/**
- * A Pulse Source is a reactive container for a value.
- * It tracks which Guards read its value and notifies them when it changes.
- *
- * @template T The type of the value held by the source.
- */
-interface Source<T> {
-    /**
-     * Returns the current value of the source.
-     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * console.log(count()); // 0
-     * ```
-     */
-    (): T;
-    /**
-     * Updates the source with a new value.
-     * If the value is different (based on strict equality or `options.equals`),
-     * all dependent Guards and subscribers will be notified.
-     *
-     * @param value The new value to set.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.set(1); // Triggers re-evaluation of dependents
-     * ```
-     *
-     * @error
-     * Common error: Mutating an object property without setting a new object reference.
-     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
-     * Solution: Always provide a new object or implement a custom `equals`.
-     */
-    set(value: T): void;
-    /**
-     * Updates the source value using a transformer function based on the current value.
-     * Useful for increments or toggles.
-     *
-     * @param updater A function that receives the current value and returns the new value.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.update(n => n + 1);
-     * ```
-     */
-    update(updater: (current: T) => T): void;
-    /**
-     * Manually subscribes to changes in the source value.
-     *
-     * @param listener A callback that receives the new value.
-     * @returns An unsubscription function.
-     *
-     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
-     */
-    subscribe(listener: Subscriber<T>): () => void;
-}
-/**
- * Creates a new Pulse Source.
- *
- * Sources are the fundamental building blocks of state in Pulse. They hold a value
- * and track which Guards depend on them.
- *
- * @template T - The type of value to store.
- * @param initialValue - The initial state.
- * @param options - Configuration options (name, equality).
- * @returns A reactive Pulse Source.
- *
- * @example
- * ```ts
- * const user = source({ name: 'Alice' }, { name: 'user_state' });
- *
- * // Read value (auto-tracks if inside a guard)
- * console.log(user());
- *
- * // Update value
- * user.set({ name: 'Bob' });
- * ```
- */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
-
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -455,6 +459,17 @@ declare class Registry {
 }
 declare const PulseRegistry: Registry;
 
+/**
+ * Extracts the result type T from a Guard<T>.
+ *
+ * @example
+ * ```ts
+ * const authGuard = guard('auth', async () => fetchUser());
+ * type AuthUser = InferGuardType<typeof authGuard>; // User
+ * ```
+ */
+type InferGuardType<T> = T extends Guard<infer U> ? U : never;
+
 /**
  * Pulse Guard with integrated Composition Helpers.
  *
@@ -474,4 +489,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.d.ts

@@ -41,6 +41,118 @@ declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
  */
 declare function getCurrentGuard(): GuardNode | null;
 
+/**
+ * Options for configuring a Pulse Source.
+ *
+ * @template T - The type of value stored in the source.
+ */
+interface SourceOptions<T> {
+    /**
+     * A descriptive name for the source.
+     * Required for SSR hydration and highly recommended for debugging in DevTools.
+     */
+    name?: string;
+    /**
+     * Custom equality function to determine if a value has changed.
+     * By default, Pulse uses strict equality (`===`).
+     *
+     * @param a - The current value.
+     * @param b - The new value.
+     * @returns `true` if the values are considered equal, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * const list = source([1], {
+     *   equals: (a, b) => a.length === b.length
+     * });
+     * ```
+     */
+    equals?: (a: T, b: T) => boolean;
+}
+/**
+ * A Pulse Source is a reactive container for a value.
+ * It tracks which Guards read its value and notifies them when it changes.
+ *
+ * @template T The type of the value held by the source.
+ */
+interface Source<T> {
+    /**
+     * Returns the current value of the source.
+     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * console.log(count()); // 0
+     * ```
+     */
+    (): T;
+    /**
+     * Updates the source with a new value.
+     * If the value is different (based on strict equality or `options.equals`),
+     * all dependent Guards and subscribers will be notified.
+     *
+     * @param value The new value to set.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.set(1); // Triggers re-evaluation of dependents
+     * ```
+     *
+     * @error
+     * Common error: Mutating an object property without setting a new object reference.
+     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
+     * Solution: Always provide a new object or implement a custom `equals`.
+     */
+    set(value: T): void;
+    /**
+     * Updates the source value using a transformer function based on the current value.
+     * Useful for increments or toggles.
+     *
+     * @param updater A function that receives the current value and returns the new value.
+     *
+     * @example
+     * ```ts
+     * const count = source(0);
+     * count.update(n => n + 1);
+     * ```
+     */
+    update(updater: (current: T) => T): void;
+    /**
+     * Manually subscribes to changes in the source value.
+     *
+     * @param listener A callback that receives the new value.
+     * @returns An unsubscription function.
+     *
+     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
+     */
+    subscribe(listener: Subscriber<T>): () => void;
+}
+/**
+ * Creates a new Pulse Source.
+ *
+ * Sources are the fundamental building blocks of state in Pulse. They hold a value
+ * and track which Guards depend on them.
+ *
+ * @template T - The type of value to store.
+ * @param initialValue - The initial state.
+ * @param options - Configuration options (name, equality).
+ * @returns A reactive Pulse Source.
+ *
+ * @example
+ * ```ts
+ * const user = source({ name: 'Alice' }, { name: 'user_state' });
+ *
+ * // Read value (auto-tracks if inside a guard)
+ * console.log(user());
+ *
+ * // Update value
+ * user.set({ name: 'Bob' });
+ * ```
+ */
+declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
+
 /**
  * Status of a Pulse Guard evaluation.
  * - 'pending': Async evaluation is in progress.
@@ -86,6 +198,7 @@ interface GuardExplanation {
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
+        reason?: string | GuardReason;
     }>;
 }
 /**
@@ -187,6 +300,9 @@ declare function guardFail(reason: string | GuardReason): never;
  */
 declare function guardOk<T>(value: T): T;
 declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
+declare namespace guard {
+    var map: <T, U>(source: Source<T>, mapper: (value: T) => U | Promise<U>, name?: string) => Guard<U>;
+}
 
 /**
  * Utility to transform reactive dependencies into a new derived value.
@@ -251,118 +367,6 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
-/**
- * Options for configuring a Pulse Source.
- *
- * @template T - The type of value stored in the source.
- */
-interface SourceOptions<T> {
-    /**
-     * A descriptive name for the source.
-     * Required for SSR hydration and highly recommended for debugging in DevTools.
-     */
-    name?: string;
-    /**
-     * Custom equality function to determine if a value has changed.
-     * By default, Pulse uses strict equality (`===`).
-     *
-     * @param a - The current value.
-     * @param b - The new value.
-     * @returns `true` if the values are considered equal, `false` otherwise.
-     *
-     * @example
-     * ```ts
-     * const list = source([1], {
-     *   equals: (a, b) => a.length === b.length
-     * });
-     * ```
-     */
-    equals?: (a: T, b: T) => boolean;
-}
-/**
- * A Pulse Source is a reactive container for a value.
- * It tracks which Guards read its value and notifies them when it changes.
- *
- * @template T The type of the value held by the source.
- */
-interface Source<T> {
-    /**
-     * Returns the current value of the source.
-     * If called within a Guard evaluation, it automatically registers that Guard as a dependent.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * console.log(count()); // 0
-     * ```
-     */
-    (): T;
-    /**
-     * Updates the source with a new value.
-     * If the value is different (based on strict equality or `options.equals`),
-     * all dependent Guards and subscribers will be notified.
-     *
-     * @param value The new value to set.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.set(1); // Triggers re-evaluation of dependents
-     * ```
-     *
-     * @error
-     * Common error: Mutating an object property without setting a new object reference.
-     * Pulse uses reference equality by default. If you mutate a property, Pulse won't know it changed.
-     * Solution: Always provide a new object or implement a custom `equals`.
-     */
-    set(value: T): void;
-    /**
-     * Updates the source value using a transformer function based on the current value.
-     * Useful for increments or toggles.
-     *
-     * @param updater A function that receives the current value and returns the new value.
-     *
-     * @example
-     * ```ts
-     * const count = source(0);
-     * count.update(n => n + 1);
-     * ```
-     */
-    update(updater: (current: T) => T): void;
-    /**
-     * Manually subscribes to changes in the source value.
-     *
-     * @param listener A callback that receives the new value.
-     * @returns An unsubscription function.
-     *
-     * @note Most users should use `guard()` or `usePulse()` instead of manual subscriptions.
-     */
-    subscribe(listener: Subscriber<T>): () => void;
-}
-/**
- * Creates a new Pulse Source.
- *
- * Sources are the fundamental building blocks of state in Pulse. They hold a value
- * and track which Guards depend on them.
- *
- * @template T - The type of value to store.
- * @param initialValue - The initial state.
- * @param options - Configuration options (name, equality).
- * @returns A reactive Pulse Source.
- *
- * @example
- * ```ts
- * const user = source({ name: 'Alice' }, { name: 'user_state' });
- *
- * // Read value (auto-tracks if inside a guard)
- * console.log(user());
- *
- * // Update value
- * user.set({ name: 'Bob' });
- * ```
- */
-declare function source<T>(initialValue: T, options?: SourceOptions<T>): Source<T>;
-
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -455,6 +459,17 @@ declare class Registry {
 }
 declare const PulseRegistry: Registry;
 
+/**
+ * Extracts the result type T from a Guard<T>.
+ *
+ * @example
+ * ```ts
+ * const authGuard = guard('auth', async () => fetchUser());
+ * type AuthUser = InferGuardType<typeof authGuard>; // User
+ * ```
+ */
+type InferGuardType<T> = T extends Guard<infer U> ? U : never;
+
 /**
  * Pulse Guard with integrated Composition Helpers.
  *
@@ -474,4 +489,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, compute, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, registerGuardForHydration, runInContext, source };

package/dist/index.js

@@ -223,11 +223,20 @@ function guard(nameOrFn, fn) {
     lastDeps.forEach((dep) => {
       const depName = dep._name || "unnamed";
       const isG = "state" in dep;
-      deps.push({
-        name: depName,
-        type: isG ? "guard" : "source",
-        status: isG ? dep.state().status : void 0
-      });
+      if (isG) {
+        const depState = dep.state();
+        deps.push({
+          name: depName,
+          type: "guard",
+          status: depState.status,
+          reason: depState.status === "fail" ? depState.reason : void 0
+        });
+      } else {
+        deps.push({
+          name: depName,
+          type: "source"
+        });
+      }
     });
     return {
       name: name || "guard",
@@ -252,6 +261,13 @@ function guard(nameOrFn, fn) {
   evaluate2();
   return g;
 }
+guard.map = function(source2, mapper, name) {
+  const guardName = name || `map-${source2._name || "source"}`;
+  return guard(guardName, () => {
+    const value = source2();
+    return mapper(value);
+  });
+};
 
 // src/registry.ts
 var Registry = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-js/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "module": "dist/index.js",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",