@pulse-js/core 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -179,9 +179,9 @@ interface GuardState<T> {
     /** The value returned by the evaluator (only if status is 'ok'). */
     value?: T;
     /** The reason why the guard failed. */
-    reason?: string | GuardReason;
+    reason?: GuardReason;
     /** The last known failure reason, persisted even during 'pending'. */
-    lastReason?: string | GuardReason;
+    lastReason?: GuardReason;
     /** The timestamp when the status last changed. */
     updatedAt?: number;
 }
@@ -191,14 +191,14 @@ interface GuardState<T> {
 interface GuardExplanation {
     name: string;
     status: GuardStatus;
-    reason?: string | GuardReason;
-    lastReason?: string | GuardReason;
+    reason?: GuardReason;
+    lastReason?: GuardReason;
     value?: any;
     dependencies: Array<{
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
-        reason?: string | GuardReason;
+        reason?: GuardReason;
     }>;
 }
 /**
@@ -237,9 +237,9 @@ interface Guard<T = boolean> {
      * Returns the failure reason message if the guard is in the 'fail' state.
      * Useful for displaying semantic error messages in the UI.
      *
-     * @returns The error message or undefined.
+     * @returns The error message object or undefined.
      */
-    reason(): string | GuardReason | undefined;
+    reason(): GuardReason | undefined;
     /**
      * Returns a snapshot of the full internal state of the guard.
      * Useful for adapters (like React) to synchronize with the guard.
@@ -302,6 +302,14 @@ 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>;
+    var select: <T extends object, U>(pulseObj: T, selector: (obj: T) => U | Promise<U>, name?: string) => Guard<U>;
+    var from: <T>(getValue: () => {
+        value?: T;
+        isLoading?: boolean;
+        error?: any;
+    } | T, options?: {
+        name?: string;
+    }) => Guard<T | undefined>;
 }
 
 /**
@@ -367,6 +375,139 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
+/**
+ * Pulse Signal - Low-level reactive primitive
+ *
+ * Internal building block for fine-grained reactivity.
+ * Signals are the foundation for both `source()` and `pulse()` APIs.
+ *
+ * @internal
+ */
+
+/**
+ * A reactive signal holding a value.
+ * @template T The type of value held by the signal.
+ */
+interface Signal<T> {
+    /** Get the current value, auto-tracking if inside a Guard. */
+    get(): T;
+    /** Set a new value, notifying all dependents. */
+    set(value: T): void;
+    /** Update value using a transformer function. */
+    update(fn: (current: T) => T): void;
+    /** Subscribe to value changes. */
+    subscribe(listener: Subscriber<T>): () => void;
+    /** Get value without tracking (break dependency). */
+    peek(): T;
+}
+/**
+ * Batch multiple reactive updates into a single notification cycle.
+ * Reduces unnecessary re-evaluations when updating multiple signals.
+ *
+ * @param fn Function containing multiple signal updates.
+ *
+ * @example
+ * ```ts
+ * batch(() => {
+ *   count.set(1);
+ *   name.set('Alice');
+ *   // Dependents notified only once after both updates
+ * });
+ * ```
+ */
+declare function batch(fn: () => void): void;
+/**
+ * Creates a low-level reactive signal.
+ *
+ * Signals automatically track dependencies when read inside a Guard context.
+ * When the signal value changes, all dependent Guards are re-evaluated.
+ *
+ * @template T The type of value to store.
+ * @param initialValue The initial value.
+ * @param equals Optional equality function (defaults to ===).
+ * @returns A reactive Signal.
+ *
+ * @example
+ * ```ts
+ * const count = createSignal(0);
+ * count.get(); // 0
+ * count.set(5);
+ * count.get(); // 5
+ * ```
+ */
+declare function createSignal<T>(initialValue: T, equals?: (a: T, b: T) => boolean): Signal<T>;
+/**
+ * Effect tracking - run a function when its dependencies change.
+ * Similar to Solid's createEffect or Vue's watchEffect.
+ *
+ * @param fn The effect function to run.
+ * @returns Cleanup function to stop the effect.
+ *
+ * @example
+ * ```ts
+ * const count = createSignal(0);
+ * const cleanup = effect(() => {
+ *   console.log('Count changed:', count.get());
+ * });
+ * // Later: cleanup() to stop
+ * ```
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+
+/**
+ * Metadata attached to pulse objects for internal tracking.
+ */
+interface PulseMeta<T> {
+    signals: Map<string | symbol, Signal<any>>;
+    subscribers: Set<Subscriber<T>>;
+    dependents: Set<Trackable>;
+    name?: string;
+    target: T;
+}
+declare const PULSE_META: unique symbol;
+/**
+ * Represents a reactive Pulse Object.
+ */
+type PulseObject<T extends object> = T & {
+    /** @internal */
+    [PULSE_META]: PulseMeta<T>;
+    /** Subscribe to any property change on this object. */
+    $subscribe(listener: Subscriber<T>): () => void;
+    /** Take a non-reactive snapshot of the current state. */
+    $snapshot(): T;
+    /** Access the raw target object. */
+    $raw: T;
+};
+/**
+ * Configuration options for pulse objects.
+ */
+interface PulseOptions {
+    /** Optional name for registry and debugging. */
+    name?: string;
+    /** Whether to recursively wrap nested objects (default: true). */
+    deep?: boolean;
+}
+/**
+ * Creates a reactive Pulse Object from a plain JavaScript object.
+ *
+ * Pulse Objects use Proxies to automatically track property access and mutations.
+ * They are ideal for managing complex state structures without manual source calls.
+ */
+declare function pulse<T extends object>(target: T, options?: PulseOptions): PulseObject<T>;
+/**
+ * Check if a value is a Pulse Object.
+ */
+declare function isPulseObject(value: any): value is PulseObject<any>;
+/**
+ * Get the raw (non-reactive) object from a Pulse Object.
+ */
+declare function toRaw<T extends object>(pulseObj: PulseObject<T>): T;
+/**
+ * Create a readonly view of a Pulse Object.
+ * Attempts to write will throw in development.
+ */
+declare function readonly<T extends object>(pulseObj: PulseObject<T>): Readonly<T>;
+
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -421,40 +562,35 @@ type PulseUnit = Source<any> | Guard<any>;
  * Root Registry for Pulse.
  *
  * Tracks all registered Units (Sources and Guards) globally for DevTools.
- *
- * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
- * Unnamed units work perfectly but are not tracked to avoid HMR instability.
- *
- * @example
- * ```ts
- * // ✅ Visible in DevTools
- * const count = source(0, { name: 'count' });
- *
- * // ❌ Not visible in DevTools (but works fine)
- * const temp = source(0);
- * ```
+ * Uses the Proxy of Identity pattern to maintain stable references during HMR.
  */
 declare class Registry {
-    private units;
+    private targets;
+    private proxies;
     private listeners;
     private currentGeneration;
     private cleanupScheduled;
+    private hmrDebounce;
     /**
-     * Schedules cleanup of units that weren't re-registered (deleted from code).
+     * Registers a unit and returns a stable Identity Proxy.
+     *
+     * If a unit with the same UID already exists, it updates the internal
+     * target of the existing proxy and returns that same proxy.
      */
-    private scheduleCleanup;
+    register<T extends PulseUnit>(unit: T): T;
     /**
-     * Removes units that weren't re-registered in the current generation.
-     * Uses mark-and-sweep: units that were re-registered have current generation,
-     * units that weren't are from old generation and should be removed.
+     * Schedules cleanup of units that weren't re-registered.
      */
+    private scheduleCleanup;
     private cleanupDeadUnits;
-    /**
-     * Registers a unit (only if it has an explicit name).
-     */
-    register(unit: PulseUnit): void;
+    private notifyListeners;
+    get(nameOrUid: string): PulseUnit | undefined;
     getAll(): PulseUnit[];
-    onRegister(listener: (unit: PulseUnit) => void): () => void;
+    getAllWithMeta(): Array<{
+        unit: PulseUnit;
+        uid: string;
+    }>;
+    onRegister(listener: (unit: PulseUnit, event?: 'add' | 'update' | 'remove') => void): () => void;
     reset(): void;
 }
 declare const PulseRegistry: Registry;
@@ -489,4 +625,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-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 };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, type PulseObject, type PulseOptions, PulseRegistry, type PulseUnit, type Signal, type Source, type SourceOptions, type Subscriber, type Trackable, batch, compute, createSignal, effect, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, isPulseObject, pulse, readonly, registerGuardForHydration, runInContext, source, toRaw };

package/dist/index.d.ts

@@ -179,9 +179,9 @@ interface GuardState<T> {
     /** The value returned by the evaluator (only if status is 'ok'). */
     value?: T;
     /** The reason why the guard failed. */
-    reason?: string | GuardReason;
+    reason?: GuardReason;
     /** The last known failure reason, persisted even during 'pending'. */
-    lastReason?: string | GuardReason;
+    lastReason?: GuardReason;
     /** The timestamp when the status last changed. */
     updatedAt?: number;
 }
@@ -191,14 +191,14 @@ interface GuardState<T> {
 interface GuardExplanation {
     name: string;
     status: GuardStatus;
-    reason?: string | GuardReason;
-    lastReason?: string | GuardReason;
+    reason?: GuardReason;
+    lastReason?: GuardReason;
     value?: any;
     dependencies: Array<{
         name: string;
         type: 'source' | 'guard';
         status?: GuardStatus;
-        reason?: string | GuardReason;
+        reason?: GuardReason;
     }>;
 }
 /**
@@ -237,9 +237,9 @@ interface Guard<T = boolean> {
      * Returns the failure reason message if the guard is in the 'fail' state.
      * Useful for displaying semantic error messages in the UI.
      *
-     * @returns The error message or undefined.
+     * @returns The error message object or undefined.
      */
-    reason(): string | GuardReason | undefined;
+    reason(): GuardReason | undefined;
     /**
      * Returns a snapshot of the full internal state of the guard.
      * Useful for adapters (like React) to synchronize with the guard.
@@ -302,6 +302,14 @@ 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>;
+    var select: <T extends object, U>(pulseObj: T, selector: (obj: T) => U | Promise<U>, name?: string) => Guard<U>;
+    var from: <T>(getValue: () => {
+        value?: T;
+        isLoading?: boolean;
+        error?: any;
+    } | T, options?: {
+        name?: string;
+    }) => Guard<T | undefined>;
 }
 
 /**
@@ -367,6 +375,139 @@ declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Gua
  */
 declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
 
+/**
+ * Pulse Signal - Low-level reactive primitive
+ *
+ * Internal building block for fine-grained reactivity.
+ * Signals are the foundation for both `source()` and `pulse()` APIs.
+ *
+ * @internal
+ */
+
+/**
+ * A reactive signal holding a value.
+ * @template T The type of value held by the signal.
+ */
+interface Signal<T> {
+    /** Get the current value, auto-tracking if inside a Guard. */
+    get(): T;
+    /** Set a new value, notifying all dependents. */
+    set(value: T): void;
+    /** Update value using a transformer function. */
+    update(fn: (current: T) => T): void;
+    /** Subscribe to value changes. */
+    subscribe(listener: Subscriber<T>): () => void;
+    /** Get value without tracking (break dependency). */
+    peek(): T;
+}
+/**
+ * Batch multiple reactive updates into a single notification cycle.
+ * Reduces unnecessary re-evaluations when updating multiple signals.
+ *
+ * @param fn Function containing multiple signal updates.
+ *
+ * @example
+ * ```ts
+ * batch(() => {
+ *   count.set(1);
+ *   name.set('Alice');
+ *   // Dependents notified only once after both updates
+ * });
+ * ```
+ */
+declare function batch(fn: () => void): void;
+/**
+ * Creates a low-level reactive signal.
+ *
+ * Signals automatically track dependencies when read inside a Guard context.
+ * When the signal value changes, all dependent Guards are re-evaluated.
+ *
+ * @template T The type of value to store.
+ * @param initialValue The initial value.
+ * @param equals Optional equality function (defaults to ===).
+ * @returns A reactive Signal.
+ *
+ * @example
+ * ```ts
+ * const count = createSignal(0);
+ * count.get(); // 0
+ * count.set(5);
+ * count.get(); // 5
+ * ```
+ */
+declare function createSignal<T>(initialValue: T, equals?: (a: T, b: T) => boolean): Signal<T>;
+/**
+ * Effect tracking - run a function when its dependencies change.
+ * Similar to Solid's createEffect or Vue's watchEffect.
+ *
+ * @param fn The effect function to run.
+ * @returns Cleanup function to stop the effect.
+ *
+ * @example
+ * ```ts
+ * const count = createSignal(0);
+ * const cleanup = effect(() => {
+ *   console.log('Count changed:', count.get());
+ * });
+ * // Later: cleanup() to stop
+ * ```
+ */
+declare function effect(fn: () => void | (() => void)): () => void;
+
+/**
+ * Metadata attached to pulse objects for internal tracking.
+ */
+interface PulseMeta<T> {
+    signals: Map<string | symbol, Signal<any>>;
+    subscribers: Set<Subscriber<T>>;
+    dependents: Set<Trackable>;
+    name?: string;
+    target: T;
+}
+declare const PULSE_META: unique symbol;
+/**
+ * Represents a reactive Pulse Object.
+ */
+type PulseObject<T extends object> = T & {
+    /** @internal */
+    [PULSE_META]: PulseMeta<T>;
+    /** Subscribe to any property change on this object. */
+    $subscribe(listener: Subscriber<T>): () => void;
+    /** Take a non-reactive snapshot of the current state. */
+    $snapshot(): T;
+    /** Access the raw target object. */
+    $raw: T;
+};
+/**
+ * Configuration options for pulse objects.
+ */
+interface PulseOptions {
+    /** Optional name for registry and debugging. */
+    name?: string;
+    /** Whether to recursively wrap nested objects (default: true). */
+    deep?: boolean;
+}
+/**
+ * Creates a reactive Pulse Object from a plain JavaScript object.
+ *
+ * Pulse Objects use Proxies to automatically track property access and mutations.
+ * They are ideal for managing complex state structures without manual source calls.
+ */
+declare function pulse<T extends object>(target: T, options?: PulseOptions): PulseObject<T>;
+/**
+ * Check if a value is a Pulse Object.
+ */
+declare function isPulseObject(value: any): value is PulseObject<any>;
+/**
+ * Get the raw (non-reactive) object from a Pulse Object.
+ */
+declare function toRaw<T extends object>(pulseObj: PulseObject<T>): T;
+/**
+ * Create a readonly view of a Pulse Object.
+ * Attempts to write will throw in development.
+ */
+declare function readonly<T extends object>(pulseObj: PulseObject<T>): Readonly<T>;
+
 /**
  * Serialized state of guards for transfer from server to client.
  */
@@ -421,40 +562,35 @@ type PulseUnit = Source<any> | Guard<any>;
  * Root Registry for Pulse.
  *
  * Tracks all registered Units (Sources and Guards) globally for DevTools.
- *
- * **IMPORTANT**: Only units with explicit names are registered and visible in DevTools.
- * Unnamed units work perfectly but are not tracked to avoid HMR instability.
- *
- * @example
- * ```ts
- * // ✅ Visible in DevTools
- * const count = source(0, { name: 'count' });
- *
- * // ❌ Not visible in DevTools (but works fine)
- * const temp = source(0);
- * ```
+ * Uses the Proxy of Identity pattern to maintain stable references during HMR.
  */
 declare class Registry {
-    private units;
+    private targets;
+    private proxies;
     private listeners;
     private currentGeneration;
     private cleanupScheduled;
+    private hmrDebounce;
     /**
-     * Schedules cleanup of units that weren't re-registered (deleted from code).
+     * Registers a unit and returns a stable Identity Proxy.
+     *
+     * If a unit with the same UID already exists, it updates the internal
+     * target of the existing proxy and returns that same proxy.
      */
-    private scheduleCleanup;
+    register<T extends PulseUnit>(unit: T): T;
     /**
-     * Removes units that weren't re-registered in the current generation.
-     * Uses mark-and-sweep: units that were re-registered have current generation,
-     * units that weren't are from old generation and should be removed.
+     * Schedules cleanup of units that weren't re-registered.
      */
+    private scheduleCleanup;
     private cleanupDeadUnits;
-    /**
-     * Registers a unit (only if it has an explicit name).
-     */
-    register(unit: PulseUnit): void;
+    private notifyListeners;
+    get(nameOrUid: string): PulseUnit | undefined;
     getAll(): PulseUnit[];
-    onRegister(listener: (unit: PulseUnit) => void): () => void;
+    getAllWithMeta(): Array<{
+        unit: PulseUnit;
+        uid: string;
+    }>;
+    onRegister(listener: (unit: PulseUnit, event?: 'add' | 'update' | 'remove') => void): () => void;
     reset(): void;
 }
 declare const PulseRegistry: Registry;
@@ -489,4 +625,4 @@ declare const extendedGuard: typeof guard & {
     compute: typeof compute;
 };
 
-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 };
+export { type Guard, type GuardExplanation, type GuardNode, type GuardReason, type GuardState, type GuardStatus, type HydrationState, type InferGuardType, type PulseObject, type PulseOptions, PulseRegistry, type PulseUnit, type Signal, type Source, type SourceOptions, type Subscriber, type Trackable, batch, compute, createSignal, effect, evaluate, getCurrentGuard, extendedGuard as guard, guardFail, guardOk, hydrate, isPulseObject, pulse, readonly, registerGuardForHydration, runInContext, source, toRaw };