@pulse-js/core 0.1.0 → 0.1.1

package/dist/index.d.cts

@@ -1,414 +0,0 @@
-/**
- * Represents an object that can be notified of changes.
- * Primarily implemented by Guards to trigger re-evaluation.
- */
-interface Trackable {
-    /** Triggered when a dependency (Source or another Guard) changes. */
-    notify(): void;
-}
-/**
- * Subscriber callback for manual source subscriptions.
- */
-type Subscriber<T> = (value: T) => void;
-/**
- * Internal interface for Guard nodes within the dependency graph.
- */
-interface GuardNode extends Trackable {
-    /**
-     * Registers a dependency for this guard.
-     * Internal use only.
-     */
-    addDependency(trackable: Trackable): void;
-}
-/**
- * Executes a function within the context of a specific Guard.
- * Any Pulse primitives read during this execution will register the guard as a dependent.
- *
- * @internal
- * @param guard The guard node to set as active.
- * @param fn The function to execute.
- * @returns The result of the function.
- */
-declare function runInContext<T>(guard: GuardNode, fn: () => T): T;
-/**
- * Retrieves the guard currently being evaluated, if any.
- * Used by Sources and Guards to perform automatic dependency registration.
- *
- * @internal
- */
-declare function getCurrentGuard(): GuardNode | null;
-
-/**
- * Status of a Pulse Guard evaluation.
- * - 'pending': Async evaluation is in progress.
- * - 'ok': Evaluation completed successfully (return value was not `false`).
- * - 'fail': Evaluation encountered an error or return value was `false`.
- */
-type GuardStatus = 'ok' | 'fail' | 'pending';
-/**
- * The internal state of a Pulse Guard.
- */
-interface GuardState<T> {
-    /** Current status of the guard. */
-    status: GuardStatus;
-    /** The value returned by the evaluator (only if status is 'ok'). */
-    value?: T;
-    /** The message explaining why the guard failed (only if status is 'fail'). */
-    reason?: string;
-}
-/**
- * A Pulse Guard is a reactive semantic condition.
- * It encapsulates a condition (sync or async) and manages its lifecycle,
- * dependencies, and error states.
- *
- * @template T The type of the value returned by the evaluator.
- */
-interface Guard<T = boolean> {
-    /**
-     * Returns the current value of the guard if its status is 'ok'.
-     * If status is 'fail' or 'pending', returns `undefined`.
-     *
-     * When called within another Guard's evaluator, it establishes a reactive dependency.
-     *
-     * @returns The successful value or undefined.
-     */
-    (): T | undefined;
-    /**
-     * Returns `true` if the guard successfully evaluated and is ready for use.
-     * Establishes a reactive dependency.
-     */
-    ok(): boolean;
-    /**
-     * Returns `true` if the guard failed its condition or encountered an error.
-     * Establishes a reactive dependency.
-     */
-    fail(): boolean;
-    /**
-     * Returns `true` if the guard is currently performing an asynchronous evaluation.
-     * Establishes a reactive dependency.
-     */
-    pending(): 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.
-     */
-    reason(): string | undefined;
-    /**
-     * Returns a snapshot of the full internal state of the guard.
-     * Useful for adapters (like React) to synchronize with the guard.
-     *
-     * @returns {GuardState<T>}
-     */
-    state(): GuardState<T>;
-    /**
-     * Manually subscribes to changes in the guard's state.
-     *
-     * @param listener - A callback that receives the new GuardState.
-     * @returns An unsubscription function.
-     */
-    subscribe(listener: Subscriber<GuardState<T>>): () => void;
-    /**
-     * Manually forces a re-evaluation of the guard.
-     * Typically used internally by Pulse or for debugging.
-     * @internal
-     */
-    _evaluate(): void;
-}
-/**
- * Creates a new Pulse Guard.
- *
- * Guards represent semantic conditions or asynchronous data dependencies.
- * They automatically track any Sources or other Guards used during their evaluation.
- *
- * @template T - The type of value returned by the evaluator (defaults to boolean).
- * @param nameOrFn - Either a unique string name (required for SSR) or the evaluator function.
- * @param fn - The evaluator function if a name was provided as the first argument.
- * @returns A reactive Pulse Guard.
- *
- * @example
- * ```ts
- * // 1. Synchronous boolean guard
- * const canEnter = guard(() => age() >= 18);
- *
- * // 2. Asynchronous data guard with a name
- * const profile = guard('user-profile', async () => {
- *   const data = await fetchUser(userId());
- *   return data.json();
- * });
- * ```
- */
-declare function guard<T = boolean>(nameOrFn?: string | (() => T | Promise<T>), fn?: () => T | Promise<T>): Guard<T>;
-
-/**
- * Creates a composite guard that is 'ok' only if ALL provided guards are 'ok'.
- * If any guard fails, this guard also fails and adopts the reason of the FIRST failing guard.
- *
- * @param nameOrGuards Optional name for the guard or the array of guards.
- * @param maybeGuards The array of guards (if name was provided).
- *
- * @example
- * ```ts
- * const canPost = guard.all('can-post', [isLoggedIn, hasPostPermission, emailVerified]);
- *
- * // If isLoggedIn fails with reason "Unauthorized",
- * // canPost.reason() will also be "Unauthorized".
- * ```
- */
-declare function guardAll(nameOrGuards: string | Guard<any>[], maybeGuards?: Guard<any>[]): Guard<boolean>;
-/**
- * Creates a composite guard that is 'ok' if AT LEAST ONE provided guard is 'ok'.
- * If all guards fail, this guard fails and concatenates their reasons.
- *
- * @param nameOrGuards Optional name for the guard or the array of guards.
- * @param maybeGuards The array of guards (if name was provided).
- *
- * @example
- * ```ts
- * const isStaff = guard.any('is-staff', [isAdmin, isEditor, isModerator]);
- * ```
- */
-declare function guardAny(nameOrGuards: string | Guard<any>[], maybeGuards?: Guard<any>[]): Guard<boolean>;
-/**
- * Negates a Pulse Guard, Source, or boolean-returning function.
- *
- * @param nameOrTarget Optional name or the target to negate.
- * @param maybeTarget The target to negate (if name was provided).
- *
- * @example
- * ```ts
- * const isGuest = guard.not('is-guest', isLoggedIn);
- * ```
- */
-declare function guardNot(nameOrTarget: string | Guard<any> | (() => any), maybeTarget?: Guard<any> | (() => any)): Guard<boolean>;
-/**
- * Utility to transform reactive dependencies into a new derived value.
- *
- * Works like a memoized computation that automatically re-evaluates when
- * any of its dependencies change.
- *
- * @template T - The type of input values.
- * @template R - The type of the computed result.
- * @param name - A unique name for the computation (required for SSR).
- * @param dependencies - An array of sources or guards to observe.
- * @param processor - A function that derives the new value.
- * @returns A Pulse Guard holding the computed result.
- *
- * @example
- * ```ts
- * const fullName = guard.compute('full-name', [firstName, lastName], (f, l) => `${f} ${l}`);
- * ```
- */
-declare function guardCompute<T, R>(name: string, dependencies: any[], processor: (...args: any[]) => R): Guard<R>;
-
-/**
- * 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.
- */
-interface HydrationState {
-    /** Map of guard names to their semantic states. */
-    [key: string]: GuardState<any>;
-}
-/**
- * Registers a guard to be automatically hydrated when the client starts.
- * Guards with a 'name' are automatically registered upon creation.
- *
- * @internal
- */
-declare function registerGuardForHydration(name: string, guard: Guard<any>): void;
-/**
- * Evaluates a list of Pulse Guards and returns a serializable snapshot of their states.
- * This is meant to be used on the server (SSR).
- * It waits for any 'pending' guards to resolve before taking the snapshot.
- *
- * @param guards Array of guards to evaluate.
- * @returns A promise resolving to the hydration state.
- *
- * @example
- * ```ts
- * // Server side
- * const state = await evaluate([isLoggedIn, userData]);
- * const html = renderToString(<App />);
- * res.send(`
- *   <script>window.__PULSE_STATE__ = ${JSON.stringify(state)}</script>
- *   <div id="root">${html}</div>
- * `);
- * ```
- */
-declare function evaluate(guards: Guard<any>[]): Promise<HydrationState>;
-/**
- * Hydrates client-side guards with the state captured on the server.
- * This should be called early in the client lifecycle, before rendering.
- *
- * @param state The hydration state received from the server.
- *
- * @example
- * ```ts
- * // Client side
- * import { hydrate } from '@pulse/core';
- * hydrate(window.__PULSE_STATE__);
- * ```
- */
-declare function hydrate(state: HydrationState): void;
-
-type PulseUnit = Source<any> | Guard<any>;
-/**
- * Root Registry for Pulse.
- *
- * It tracks all registered Units (Sources and Guards) globally, providing
- * the data source for DevTools and HMR stability.
- */
-declare class Registry {
-    private units;
-    private listeners;
-    /**
-     * Registers a new unit (Source or Guard).
-     * Uses the unit's name as a key to prevent duplicates during HMR.
-     */
-    register(unit: PulseUnit): void;
-    /**
-     * Retrieves all registered units.
-     */
-    getAll(): PulseUnit[];
-    /**
-     * Subscribes to new unit registrations.
-     *
-     * @param listener - Callback receiving the newly registered unit.
-     * @returns Unsubscribe function.
-     */
-    onRegister(listener: (unit: PulseUnit) => void): () => void;
-}
-declare const PulseRegistry: Registry;
-
-/**
- * Pulse Guard with integrated Composition Helpers.
- *
- * This is the primary entry point for creating reactive conditions.
- * It includes static methods like `.all()`, `.any()`, and `.not()`.
- *
- * @example
- * ```ts
- * const isReady = guard(() => true);
- * const allReady = guard.all([isReady, isLoaded]);
- * ```
- */
-declare const extendedGuard: typeof guard & {
-    all: typeof guardAll;
-    any: typeof guardAny;
-    not: typeof guardNot;
-    compute: typeof guardCompute;
-};
-
-export { type Guard, type GuardNode, type GuardState, type GuardStatus, type HydrationState, PulseRegistry, type PulseUnit, type Source, type SourceOptions, type Subscriber, type Trackable, evaluate, getCurrentGuard, extendedGuard as guard, hydrate, registerGuardForHydration, runInContext, source };