atomirx 0.0.1

package/dist/core/emitter.d.ts

@@ -0,0 +1,237 @@
+import { Listener, SingleOrMultipleListeners } from './types';
+/**
+ * Event emitter interface for pub/sub pattern.
+ *
+ * @template T - The type of payload emitted to listeners (defaults to void)
+ */
+export interface Emitter<T = void> {
+    /**
+     * Subscribe to events with one or more listeners.
+     *
+     * @param listeners - Single listener or array of listeners
+     * @returns Unsubscribe function (idempotent - safe to call multiple times)
+     */
+    on(listeners: SingleOrMultipleListeners<T>): VoidFunction;
+    /**
+     * Subscribe with a mapping function that filters and transforms events.
+     *
+     * The map function receives the emitted value and returns either:
+     * - `{ value: TValue }` - Listener is called with the transformed value
+     * - `undefined` - Listener is NOT called (event filtered out)
+     *
+     * @template TValue - The transformed value type passed to listeners
+     * @param map - Transform function that can filter (return undefined) or map values
+     * @param listeners - Single listener or array of listeners for transformed values
+     * @returns Unsubscribe function
+     *
+     * @example Filter and transform
+     * ```ts
+     * const emitter = emitter<{ type: string; data: number }>();
+     *
+     * // Only listen to 'success' events, extract just the data
+     * emitter.on(
+     *   (event) => event.type === 'success' ? { value: event.data } : undefined,
+     *   (data) => console.log('Success data:', data)
+     * );
+     * ```
+     */
+    on<TValue>(map: (value: T) => {
+        value: TValue;
+    } | undefined, listeners: SingleOrMultipleListeners<TValue>): VoidFunction;
+    /**
+     * Emit an event to all registered listeners.
+     *
+     * @param payload - The value to pass to all listeners
+     */
+    emit(payload: T): void;
+    /**
+     * Emit an event to all registered listeners in LIFO (reverse) order.
+     * Useful for cleanup scenarios where resources should be released
+     * in reverse order of acquisition.
+     *
+     * @param payload - The value to pass to all listeners
+     */
+    emitLifo(payload: T): void;
+    /**
+     * Remove all registered listeners.
+     */
+    clear(): void;
+    /**
+     * Emit an event to all listeners, then clear all listeners.
+     * Useful for one-time events like disposal.
+     *
+     * @param payload - The value to pass to all listeners
+     */
+    emitAndClear(payload: T): void;
+    /**
+     * Emit an event to all listeners in LIFO (reverse) order, then clear.
+     * Useful for cleanup scenarios where resources should be released
+     * in reverse order of acquisition.
+     *
+     * @param payload - The value to pass to all listeners
+     */
+    emitAndClearLifo(payload: T): void;
+    /**
+     * Emit to all listeners, clear, and "settle" the emitter.
+     *
+     * After settling:
+     * - Any new `on()` call immediately invokes the listener with the settled payload
+     * - Returns a no-op unsubscribe function
+     * - `emit()` and `emitAndClear()` become no-ops
+     *
+     * Useful for one-time events where late subscribers should still receive the value
+     * (similar to Promise behavior).
+     *
+     * @param payload - The final value to pass to all listeners
+     */
+    settle(payload: T): void;
+    /** Number of registered listeners */
+    size(): number;
+    /** Whether the emitter has been settled */
+    settled(): boolean;
+    /**
+     * Iterate over all registered listeners.
+     * Used for batching to dedupe listeners across multiple atoms.
+     */
+    forEach(callback: (listener: Listener<T>) => void): void;
+}
+/**
+ * Creates an event emitter for managing and notifying listeners.
+ *
+ * An emitter provides a simple pub/sub pattern for managing event listeners.
+ * It's used internally by atoms and effects to manage subscriptions and notifications.
+ *
+ * ## Key Features
+ *
+ * 1. **Subscribe/Unsubscribe**: Add listeners that will be notified when events are emitted
+ * 2. **Emit events**: Notify all registered listeners with a payload
+ * 3. **Mapped subscriptions**: Filter and transform events before they reach listeners
+ * 4. **LIFO emission**: Emit in reverse order for cleanup scenarios
+ * 5. **Settle pattern**: One-time events where late subscribers still receive the value
+ * 6. **Idempotent unsubscribe**: Safe to call unsubscribe multiple times
+ *
+ * ## Emission Methods
+ *
+ * | Method | Order | Clears | Settles | Use Case |
+ * |--------|-------|--------|---------|----------|
+ * | `emit()` | FIFO | No | No | Normal notifications |
+ * | `emitLifo()` | LIFO | No | No | Cleanup in reverse order |
+ * | `emitAndClear()` | FIFO | Yes | No | One-time broadcast |
+ * | `emitAndClearLifo()` | LIFO | Yes | No | One-time cleanup |
+ * | `settle()` | FIFO | Yes | Yes | Promise-like one-time events |
+ *
+ * ## Settle Behavior
+ *
+ * After `settle()` is called:
+ * - New `on()` calls immediately invoke the listener with the settled payload
+ * - Returns a no-op unsubscribe function
+ * - `emit()` and other methods become no-ops
+ *
+ * This is similar to how Promises work - late `.then()` calls still receive the value.
+ *
+ * @template T - The type of payload emitted to listeners (defaults to void)
+ * @param initialListeners - Optional array of listeners to start with
+ * @returns An Emitter instance
+ *
+ * @example Basic usage
+ * ```ts
+ * const events = emitter<string>();
+ *
+ * // Subscribe
+ * const unsubscribe = events.on((message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * // Emit
+ * events.emit('Hello'); // Logs: "Received: Hello"
+ *
+ * // Unsubscribe
+ * unsubscribe();
+ *
+ * events.emit('World'); // Nothing logged
+ * ```
+ *
+ * @example Multiple listeners
+ * ```ts
+ * const events = emitter<number>();
+ *
+ * events.on((n) => console.log('A:', n));
+ * events.on((n) => console.log('B:', n));
+ *
+ * events.emit(42);
+ * // Logs: "A: 42"
+ * // Logs: "B: 42"
+ * ```
+ *
+ * @example Mapped subscriptions (filter and transform)
+ * ```ts
+ * const events = emitter<{ type: string; data: number }>();
+ *
+ * // Only listen to 'success' events, extract just the data
+ * events.on(
+ *   (event) => event.type === 'success' ? { value: event.data } : undefined,
+ *   (data) => console.log('Success data:', data)
+ * );
+ *
+ * events.emit({ type: 'error', data: 0 });   // Nothing logged (filtered)
+ * events.emit({ type: 'success', data: 42 }); // Logs: "Success data: 42"
+ * ```
+ *
+ * @example LIFO emission for cleanup
+ * ```ts
+ * const cleanup = emitter();
+ *
+ * cleanup.on(() => console.log('First registered, last to clean'));
+ * cleanup.on(() => console.log('Second registered, second to clean'));
+ * cleanup.on(() => console.log('Last registered, first to clean'));
+ *
+ * cleanup.emitLifo();
+ * // Logs in reverse order:
+ * // "Last registered, first to clean"
+ * // "Second registered, second to clean"
+ * // "First registered, last to clean"
+ * ```
+ *
+ * @example Settle pattern (Promise-like)
+ * ```ts
+ * const ready = emitter<{ config: Config }>();
+ *
+ * // Early subscriber
+ * ready.on((payload) => console.log('Early:', payload.config));
+ *
+ * // Settle the emitter
+ * ready.settle({ config: loadedConfig });
+ * // Logs: "Early: ..."
+ *
+ * // Late subscriber - still receives the value immediately
+ * ready.on((payload) => console.log('Late:', payload.config));
+ * // Logs: "Late: ..." (immediately)
+ * ```
+ *
+ * @example Void emitter (no payload)
+ * ```ts
+ * const tick = emitter(); // emitter<void>
+ *
+ * tick.on(() => console.log('Tick!'));
+ *
+ * tick.emit(); // Logs: "Tick!"
+ * ```
+ *
+ * @example Array of listeners
+ * ```ts
+ * const events = emitter<string>();
+ *
+ * // Subscribe multiple listeners at once
+ * const unsubscribe = events.on([
+ *   (msg) => console.log('Logger 1:', msg),
+ *   (msg) => console.log('Logger 2:', msg),
+ * ]);
+ *
+ * events.emit('Hello');
+ * // Logs: "Logger 1: Hello"
+ * // Logs: "Logger 2: Hello"
+ *
+ * unsubscribe(); // Removes both listeners
+ * ```
+ */
+export declare function emitter<T = void>(initialListeners?: Listener<T>[]): Emitter<T>;

package/dist/core/emitter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/equality.d.ts

@@ -0,0 +1,62 @@
+import { Equality, EqualityShorthand } from './types';
+/**
+ * Strict equality (Object.is).
+ */
+export declare function strictEqual<T>(a: T, b: T): boolean;
+/**
+ * Shallow equality for objects/arrays.
+ * Compares by reference for each top-level key/index.
+ *
+ * @param itemEqual - Optional comparator for each item/value (defaults to Object.is)
+ */
+export declare function shallowEqual<T>(a: T, b: T, itemEqual?: (a: unknown, b: unknown) => boolean): boolean;
+/**
+ * 2-level shallow equality.
+ * Compares keys/length, then shallow compares each item/value.
+ *
+ * @example
+ * [{ id: 1, data: obj }] vs [{ id: 1, data: obj }] // true (same obj ref)
+ */
+export declare function shallow2Equal<T>(a: T, b: T): boolean;
+/**
+ * 3-level shallow equality.
+ * Compares keys/length, then shallow2 compares each item/value.
+ *
+ * @example
+ * [{ id: 1, nested: { data: obj } }] vs [{ id: 1, nested: { data: obj } }] // true
+ */
+export declare function shallow3Equal<T>(a: T, b: T): boolean;
+/**
+ * Deep equality.
+ */
+export declare const deepEqual: (value: any, other: any) => boolean;
+/**
+ * Resolve equality strategy to a function.
+ */
+export declare function resolveEquality<T>(e: Equality<T> | undefined): (a: T, b: T) => boolean;
+export declare function equality(shorthand: EqualityShorthand): (a: unknown, b: unknown) => boolean;
+export type StableFn<TArgs extends any[], TResult> = ((...args: TArgs) => TResult) & {
+    getOriginal: () => (...args: TArgs) => TResult;
+    getCurrent: () => (...args: TArgs) => TResult;
+    setCurrent: (newFn: (...args: TArgs) => TResult) => void;
+};
+export declare function createStableFn<TArgs extends any[], TResult>(fn: (...args: TArgs) => TResult): StableFn<TArgs, TResult>;
+/**
+ * Check if a value is a stable function wrapper.
+ */
+export declare function isStableFn<TArgs extends any[], TResult>(value: unknown): value is StableFn<TArgs, TResult>;
+/**
+ * Stabilize a value with automatic function wrapper support.
+ *
+ * - Functions: Creates/updates stable wrapper (reference never changes)
+ * - Date objects: Compared by timestamp (uses deepEqual)
+ * - Other values: Returns previous if equal per equalityFn
+ *
+ * @param prev - Previous value container (or undefined for first call)
+ * @param next - New value
+ * @param equalityFn - Equality function for non-function/non-date values
+ * @returns Tuple of [stabilized value, wasStable]
+ */
+export declare function tryStabilize<T>(prev: {
+    value: T;
+} | undefined, next: T, equalityFn: (a: T, b: T) => boolean): [T, boolean];

package/dist/core/equality.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/hook.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A setup function that returns a release function.
+ * Called by hook.use() to activate a hook, release restores previous value.
+ */
+export type HookSetup = () => VoidFunction;
+/**
+ * A hook is a callable factory that creates setup functions,
+ * with direct access to current value via `.current`.
+ *
+ * @example
+ * ```ts
+ * const myHook = hook<string>("default");
+ *
+ * // Read current value (fast - direct property access)
+ * console.log(myHook.current); // "default"
+ *
+ * // Create a setup function (reducer receives previous value)
+ * const setup = myHook(() => "new value");
+ *
+ * // Use with hook.use()
+ * hook.use([myHook(() => "temp")], () => {
+ *   console.log(myHook.current); // "temp"
+ * });
+ * console.log(myHook.current); // "default" (restored)
+ *
+ * // Compose with previous value
+ * myHook.override(prev => {
+ *   console.log("Previous:", prev);
+ *   return "next";
+ * });
+ * ```
+ */
+export interface Hook<T> {
+    /**
+     * Creates a HookSetup that will set this hook using a reducer.
+     * The reducer receives the previous value and returns the next value.
+     *
+     * @param reducer - Function that receives previous value and returns next value
+     *
+     * @example Set new value (ignore previous)
+     * ```ts
+     * myHook(() => "new value")
+     * ```
+     *
+     * @example Compose with previous
+     * ```ts
+     * myHook(prev => {
+     *   prev?.(); // call previous handler
+     *   return newHandler;
+     * })
+     * ```
+     */
+    (reducer: (prev: T) => T): HookSetup;
+    /**
+     * Current value of the hook. Direct property access for fast reads.
+     */
+    current: T;
+    /**
+     * Override the current value using a reducer.
+     * The reducer receives the previous value and returns the next value.
+     * Unlike the setup/release pattern, this is an immediate mutation.
+     *
+     * @param reducer - Function that receives previous value and returns next value
+     *
+     * @example Set new value (ignore previous)
+     * ```ts
+     * myHook.override(() => "new value")
+     * ```
+     *
+     * @example Compose with previous (middleware pattern)
+     * ```ts
+     * onCreateHook.override(prev => (info) => {
+     *   prev?.(info);  // call existing handler
+     *   console.log("Created:", info.key);
+     * });
+     * ```
+     */
+    override(reducer: (prev: T) => T): void;
+    /**
+     * Reset the hook to its initial value.
+     */
+    reset(): void;
+}
+/**
+ * Creates a new hook with an initial value.
+ *
+ * Hooks use the setup/release pattern for performance:
+ * - Reads are direct property access (fastest)
+ * - Writes use setup/release for proper nesting
+ *
+ * @param initial - Initial value for the hook
+ * @returns A Hook instance
+ *
+ * @example
+ * ```ts
+ * // Create a hook
+ * const countHook = hook(0);
+ *
+ * // Read
+ * console.log(countHook.current); // 0
+ *
+ * // Use with hook.use() - reducer receives previous value
+ * hook.use([countHook(() => 5)], () => {
+ *   console.log(countHook.current); // 5
+ * });
+ *
+ * // Compose with previous (middleware pattern)
+ * myHook.override(prev => (info) => {
+ *   prev?.(info);  // call existing
+ *   newHandler(info);
+ * });
+ * ```
+ */
+declare function createHook<T>(initial: T): Hook<T>;
+declare function createHook<T>(): Hook<T | undefined>;
+/**
+ * Executes a function with multiple hooks temporarily set.
+ *
+ * @param setups - Array of HookSetup functions (from hook factories)
+ * @param fn - Function to execute with hooks active
+ * @returns The return value of fn
+ *
+ * @example
+ * ```ts
+ * hook.use([trackHook(myTracker), debugHook(true)], () => {
+ *   // hooks active here
+ * });
+ * ```
+ */
+declare function use<T>(setups: HookSetup[], fn: () => T): T;
+export declare const hook: typeof createHook & {
+    use: typeof use;
+};
+export {};

package/dist/core/hook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/isAtom.d.ts

@@ -0,0 +1,9 @@
+import { Atom, DerivedAtom } from './types';
+/**
+ * Type guard to check if a value is an Atom.
+ */
+export declare function isAtom<T>(value: unknown): value is Atom<T>;
+/**
+ * Type guard to check if a value is a DerivedAtom.
+ */
+export declare function isDerived<T>(value: unknown): value is DerivedAtom<T, boolean>;

package/dist/core/isPromiseLike.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Check if a value is a PromiseLike (has a .then method).
+ *
+ * @example
+ * isPromiseLike(Promise.resolve(1)) // true
+ * isPromiseLike({ then: () => {} }) // true
+ * isPromiseLike(42) // false
+ */
+export declare function isPromiseLike<T>(value: unknown): value is PromiseLike<T>;

package/dist/core/isPromiseLike.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/onCreateHook.d.ts

@@ -0,0 +1,79 @@
+import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta } from './types';
+/**
+ * Information provided when a mutable atom is created.
+ */
+export interface MutableAtomCreateInfo {
+    /** Discriminator for mutable atoms */
+    type: "mutable";
+    /** Optional key from atom options (for debugging/devtools) */
+    key: string | undefined;
+    /** Optional metadata from atom options */
+    meta: MutableAtomMeta | undefined;
+    /** The created mutable atom instance */
+    atom: MutableAtom<unknown>;
+}
+/**
+ * Information provided when a derived atom is created.
+ */
+export interface DerivedAtomCreateInfo {
+    /** Discriminator for derived atoms */
+    type: "derived";
+    /** Optional key from derived options (for debugging/devtools) */
+    key: string | undefined;
+    /** Optional metadata from derived options */
+    meta: DerivedAtomMeta | undefined;
+    /** The created derived atom instance */
+    atom: DerivedAtom<unknown, boolean>;
+}
+/**
+ * Union type for atom creation info (mutable or derived).
+ */
+export type AtomCreateInfo = MutableAtomCreateInfo | DerivedAtomCreateInfo;
+/**
+ * Information provided when a module (via define()) is created.
+ */
+export interface ModuleCreateInfo {
+    /** Discriminator for modules */
+    type: "module";
+    /** Optional key from define options (for debugging/devtools) */
+    key: string | undefined;
+    /** Optional metadata from define options */
+    meta: ModuleMeta | undefined;
+    /** The created module instance */
+    module: unknown;
+}
+/**
+ * Global hook that fires whenever an atom or module is created.
+ *
+ * This is useful for:
+ * - **DevTools integration** - track all atoms/modules in the app
+ * - **Debugging** - log atom creation for troubleshooting
+ * - **Testing** - verify expected atoms are created
+ *
+ * @example Basic logging
+ * ```ts
+ * onCreateHook.current = (info) => {
+ *   console.log(`Created ${info.type}: ${info.key ?? "anonymous"}`);
+ * };
+ * ```
+ *
+ * @example DevTools integration
+ * ```ts
+ * const atoms = new Map();
+ * const modules = new Map();
+ *
+ * onCreateHook.current = (info) => {
+ *   if (info.type === "module") {
+ *     modules.set(info.key, info.module);
+ *   } else {
+ *     atoms.set(info.key, info.atom);
+ *   }
+ * };
+ * ```
+ *
+ * @example Cleanup (disable hook)
+ * ```ts
+ * onCreateHook.current = undefined;
+ * ```
+ */
+export declare const onCreateHook: import('./hook').Hook<((info: AtomCreateInfo | ModuleCreateInfo) => void) | undefined>;

package/dist/core/promiseCache.d.ts

@@ -0,0 +1,134 @@
+import { Atom, AtomState, DerivedAtom } from './types';
+/**
+ * Represents the state of a tracked Promise.
+ */
+export type PromiseState<T> = {
+    status: "pending";
+    promise: PromiseLike<T>;
+} | {
+    status: "fulfilled";
+    value: T;
+} | {
+    status: "rejected";
+    error: unknown;
+};
+/**
+ * Tracks a Promise and caches its state.
+ * If the Promise is already tracked, returns the existing state.
+ * Otherwise, starts tracking and returns the initial pending state.
+ *
+ * @param promise - The Promise to track
+ * @returns The current state of the Promise
+ *
+ * @example
+ * ```ts
+ * const promise = fetchData();
+ * const state = trackPromise(promise);
+ * // state.status === 'pending'
+ *
+ * await promise;
+ * const state2 = trackPromise(promise);
+ * // state2.status === 'fulfilled'
+ * ```
+ */
+export declare function trackPromise<T>(promise: PromiseLike<T>): PromiseState<T>;
+/**
+ * Gets the current state of a Promise without tracking it.
+ * Returns undefined if the Promise is not being tracked.
+ *
+ * @param promise - The Promise to check
+ * @returns The current state or undefined if not tracked
+ */
+export declare function getPromiseState<T>(promise: PromiseLike<T>): PromiseState<T> | undefined;
+/**
+ * Checks if a Promise is being tracked.
+ *
+ * @param promise - The Promise to check
+ * @returns true if the Promise is tracked
+ */
+export declare function isTracked(promise: PromiseLike<unknown>): boolean;
+/**
+ * Type guard to check if a value is a DerivedAtom.
+ */
+export declare function isDerived<T>(value: unknown): value is DerivedAtom<T, boolean>;
+/**
+ * Returns the current state of an atom as a discriminated union.
+ *
+ * For DerivedAtom:
+ * - Returns atom.state() directly (derived atoms track their own state)
+ *
+ * For MutableAtom:
+ * - If value is not a Promise: returns ready state
+ * - If value is a Promise: tracks and returns its state (ready/error/loading)
+ *
+ * @param atom - The atom to get state from
+ * @returns AtomState discriminated union (ready | error | loading)
+ *
+ * @example
+ * ```ts
+ * const state = getAtomState(myAtom$);
+ *
+ * switch (state.status) {
+ *   case "ready":
+ *     console.log(state.value); // T
+ *     break;
+ *   case "error":
+ *     console.log(state.error);
+ *     break;
+ *   case "loading":
+ *     console.log(state.promise);
+ *     break;
+ * }
+ * ```
+ */
+export declare function getAtomState<T>(atom: Atom<T>): AtomState<Awaited<T>>;
+/**
+ * Unwraps a value that may be a Promise.
+ * - If not a Promise, returns the value directly.
+ * - If a resolved Promise, returns the resolved value.
+ * - If a loading Promise, throws the Promise (for Suspense).
+ * - If a rejected Promise, throws the error.
+ *
+ * This follows the React Suspense pattern where throwing a Promise
+ * signals that the component should suspend until the Promise resolves.
+ *
+ * @param value - The value to unwrap (may be a Promise)
+ * @returns The unwrapped value
+ * @throws Promise if loading, Error if rejected
+ */
+export declare function unwrap<T>(value: T | PromiseLike<T>): T;
+/**
+ * Checks if a value is a pending Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in pending state
+ */
+export declare function isPending<T>(value: T | PromiseLike<T>): boolean;
+/**
+ * Checks if a value is a fulfilled Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in fulfilled state
+ */
+export declare function isFulfilled<T>(value: T | PromiseLike<T>): boolean;
+/**
+ * Checks if a value is a rejected Promise.
+ *
+ * @param value - The value to check
+ * @returns true if value is a Promise in rejected state
+ */
+export declare function isRejected<T>(value: T | PromiseLike<T>): boolean;
+/**
+ * Gets the resolved value of a Promise if fulfilled, otherwise undefined.
+ *
+ * @param value - The value to check
+ * @returns The resolved value or undefined
+ */
+export declare function getResolvedValue<T>(value: T | PromiseLike<T>): T | undefined;
+/**
+ * Gets the error of a Promise if rejected, otherwise undefined.
+ *
+ * @param value - The value to check
+ * @returns The error or undefined
+ */
+export declare function getRejectedError<T>(value: T | PromiseLike<T>): unknown | undefined;

package/dist/core/promiseCache.test.d.ts

@@ -0,0 +1 @@
+export {};