atomirx 0.0.1

package/dist/core/scheduleNotifyHook.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Hook that controls how atom change notifications are scheduled.
+ *
+ * ## Default Behavior
+ *
+ * By default, notifications are **synchronous** - listeners are called immediately
+ * when an atom's value changes:
+ *
+ * ```ts
+ * // Default: (fn) => fn() - immediate execution
+ * atom.set(newValue);  // Listeners called immediately here
+ * ```
+ *
+ * ## Used by `batch()`
+ *
+ * The `batch()` function temporarily overrides this hook to defer notifications
+ * until all updates complete:
+ *
+ * ```ts
+ * batch(() => {
+ *   a.set(1);  // Notification deferred
+ *   b.set(2);  // Notification deferred
+ * });
+ * // All listeners called here (deduped)
+ * ```
+ *
+ * ## Custom Scheduling
+ *
+ * Can be overridden for custom scheduling strategies (e.g., microtask, RAF):
+ *
+ * ```ts
+ * // Schedule notifications as microtasks
+ * scheduleNotifyHook.override(() => (fn) => queueMicrotask(fn));
+ *
+ * // Schedule notifications on next animation frame
+ * scheduleNotifyHook.override(() => (fn) => requestAnimationFrame(fn));
+ *
+ * // Reset to default synchronous behavior
+ * scheduleNotifyHook.reset();
+ * ```
+ *
+ * ## API
+ *
+ * - `scheduleNotifyHook.current` - Get/set the current scheduler function
+ * - `scheduleNotifyHook.override(reducer)` - Override with custom scheduler (reducer receives previous)
+ * - `scheduleNotifyHook.reset()` - Reset to default synchronous behavior
+ * - `scheduleNotifyHook(reducer)` - Create a HookSetup for use with `hook.use()`
+ *
+ * @internal Used internally by atomState and batch. Not typically needed by users.
+ */
+export declare const scheduleNotifyHook: import('./hook').Hook<(fn: VoidFunction) => void>;

package/dist/core/select.d.ts

@@ -0,0 +1,151 @@
+import { Atom, AtomValue, SettledResult } from './types';
+/**
+ * Result of a select computation.
+ *
+ * @template T - The type of the computed value
+ */
+export interface SelectResult<T> {
+    /** The computed value (undefined if error or loading) */
+    value: T | undefined;
+    /** Error thrown during computation (undefined if success or loading) */
+    error: unknown;
+    /** Promise thrown during computation - indicates loading state */
+    promise: PromiseLike<unknown> | undefined;
+    /** Set of atoms that were accessed during computation */
+    dependencies: Set<Atom<unknown>>;
+}
+/**
+ * Context object passed to selector functions.
+ * Provides utilities for reading atoms and handling async operations.
+ */
+export interface SelectContext {
+    /**
+     * Read the current value of an atom.
+     * Tracks the atom as a dependency.
+     *
+     * Suspense-like behavior using getAtomState():
+     * - If ready: returns value
+     * - If error: throws error
+     * - If loading: throws Promise (Suspense)
+     *
+     * @param atom - The atom to read
+     * @returns The atom's current value (Awaited<T>)
+     */
+    get<T>(atom: Atom<T>): Awaited<T>;
+    /**
+     * Wait for all atoms to resolve (like Promise.all).
+     * Variadic form - pass atoms as arguments.
+     *
+     * - If all atoms are ready → returns array of values
+     * - If any atom has error → throws that error
+     * - If any atom is loading (no fallback) → throws Promise
+     * - If loading with fallback → uses staleValue
+     *
+     * @param atoms - Atoms to wait for (variadic)
+     * @returns Array of resolved values (same order as input)
+     *
+     * @example
+     * ```ts
+     * const [user, posts] = all(user$, posts$);
+     * ```
+     */
+    all<A extends Atom<unknown>[]>(...atoms: A): {
+        [K in keyof A]: AtomValue<A[K]>;
+    };
+    /**
+     * Return the first settled value (like Promise.race).
+     * Variadic form - pass atoms as arguments.
+     *
+     * - If any atom is ready → returns first ready value
+     * - If any atom has error → throws first error
+     * - If all atoms are loading → throws first Promise
+     *
+     * Note: race() does NOT use fallback - it's meant for first "real" settled value.
+     *
+     * @param atoms - Atoms to race (variadic)
+     * @returns First settled value
+     */
+    race<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+    /**
+     * Return the first ready value (like Promise.any).
+     * Variadic form - pass atoms as arguments.
+     *
+     * - If any atom is ready → returns first ready value
+     * - If all atoms have errors → throws AggregateError
+     * - If any loading (not all errored) → throws Promise
+     *
+     * Note: any() does NOT use fallback - it waits for a real ready value.
+     *
+     * @param atoms - Atoms to check (variadic)
+     * @returns First ready value
+     */
+    any<A extends Atom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+    /**
+     * Get all atom statuses when all are settled (like Promise.allSettled).
+     * Variadic form - pass atoms as arguments.
+     *
+     * - If all atoms are settled → returns array of statuses
+     * - If any atom is loading (no fallback) → throws Promise
+     * - If loading with fallback → { status: "ready", value: staleValue }
+     *
+     * @param atoms - Atoms to check (variadic)
+     * @returns Array of settled results
+     */
+    settled<A extends Atom<unknown>[]>(...atoms: A): {
+        [K in keyof A]: SettledResult<AtomValue<A[K]>>;
+    };
+}
+/**
+ * Selector function type for context-based API.
+ */
+export type ContextSelectorFn<T> = (context: SelectContext) => T;
+/**
+ * Custom error for when all atoms in `any()` are rejected.
+ */
+export declare class AllAtomsRejectedError extends Error {
+    readonly errors: unknown[];
+    constructor(errors: unknown[], message?: string);
+}
+/**
+ * Selects/computes a value from atom(s) with dependency tracking.
+ *
+ * This is the core computation logic used by `derived()`. It:
+ * 1. Creates a context with `get`, `all`, `any`, `race`, `settled` utilities
+ * 2. Tracks which atoms are accessed during computation
+ * 3. Returns a result with value/error/promise and dependencies
+ *
+ * All context methods use `getAtomState()` internally.
+ *
+ * ## IMPORTANT: Selector Must Return Synchronous Value
+ *
+ * **The selector function MUST NOT return a Promise or PromiseLike value.**
+ *
+ * If your selector returns a Promise, it will throw an error. This is because:
+ * - `select()` is designed for synchronous derivation from atoms
+ * - Async atoms should be created using `atom(Promise)` directly
+ * - Use `get()` to read async atoms - it handles Suspense-style loading
+ *
+ * ```ts
+ * // ❌ WRONG - Don't return a Promise from selector
+ * select(({ get }) => fetch('/api/data'));
+ *
+ * // ✅ CORRECT - Create async atom and read with get()
+ * const data$ = atom(fetch('/api/data').then(r => r.json()));
+ * select(({ get }) => get(data$)); // Suspends until resolved
+ * ```
+ *
+ * @template T - The type of the computed value
+ * @param fn - Context-based selector function (must return sync value)
+ * @returns SelectResult with value, error, promise, and dependencies
+ * @throws Error if selector returns a Promise or PromiseLike
+ *
+ * @example
+ * ```ts
+ * select(({ get, all }) => {
+ *   const user = get(user$);
+ *   const [posts, comments] = all(posts$, comments$);
+ *   return { user, posts, comments };
+ * });
+ * ```
+ */
+export declare function select<T>(fn: ContextSelectorFn<T>): SelectResult<T>;

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

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

package/dist/core/types.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Generic function type that accepts any arguments and returns any value.
+ * Used internally for type-safe function handling.
+ */
+export type AnyFunc = (...args: any[]) => any;
+/**
+ * Unique symbol used to identify atom instances.
+ * Uses Symbol.for() to ensure the same symbol across different module instances.
+ */
+export declare const SYMBOL_ATOM: unique symbol;
+/**
+ * Symbol to identify derived atoms.
+ */
+export declare const SYMBOL_DERIVED: unique symbol;
+/**
+ * Interface for objects that support the `.use()` plugin pattern.
+ *
+ * The `.use()` method enables chainable transformations via plugins.
+ * Return type behavior:
+ * - `void` → returns original source (side-effect only)
+ * - Object with `.use` → returns as-is (already pipeable)
+ * - Object without `.use` → wraps with Pipeable
+ * - Primitive → returns directly (not chainable)
+ *
+ * @example
+ * ```ts
+ * const enhanced = atom(0)
+ *   .use(source => ({ ...source, double: () => source.value * 2 }))
+ *   .use(source => ({ ...source, triple: () => source.value * 3 }));
+ * ```
+ */
+export interface Pipeable {
+    use<TNew = void>(plugin: (source: this) => TNew): void extends TNew ? this : TNew extends object ? TNew extends {
+        use: any;
+    } ? TNew : Pipeable & TNew : TNew;
+}
+/**
+ * Optional metadata for atoms.
+ */
+export interface AtomMeta {
+    key?: string;
+    [key: string]: unknown;
+}
+/**
+ * Base interface for all atoms.
+ * Represents a reactive value container with subscription capability.
+ *
+ * @template T - The type of value stored in the atom
+ */
+export interface Atom<T> {
+    /** Symbol marker to identify atom instances */
+    readonly [SYMBOL_ATOM]: true;
+    /** The current value */
+    readonly value: T;
+    /** Optional metadata for the atom */
+    readonly meta?: AtomMeta;
+    /**
+     * Subscribe to value changes.
+     * @param listener - Callback invoked when value changes
+     * @returns Unsubscribe function
+     */
+    on(listener: VoidFunction): VoidFunction;
+}
+/**
+ * A mutable atom that can be updated via `set()` and reset to initial state.
+ *
+ * MutableAtom is a raw storage container. It stores values as-is, including Promises.
+ * Unlike DerivedAtom, it does not automatically unwrap or track Promise states.
+ *
+ * @template T - The type of value stored in the atom
+ *
+ * @example
+ * ```ts
+ * // Sync value
+ * const count = atom(0);
+ * count.set(5);           // Direct value
+ * count.set(n => n + 1);  // Reducer function
+ * count.reset();          // Back to 0
+ *
+ * // Async value (stores Promise as-is)
+ * const posts = atom(fetchPosts());
+ * posts.value; // Promise<Post[]>
+ * posts.set(fetchPosts()); // Store new Promise
+ * ```
+ */
+export interface MutableAtom<T> extends Atom<T>, Pipeable {
+    /** Reset atom to its initial state (also clears dirty flag) */
+    reset(): void;
+    /**
+     * Update the atom's value.
+     *
+     * @param value - New value or reducer function (prev) => newValue
+     */
+    set(value: T | ((prev: T) => T)): void;
+    /**
+     * Returns `true` if the value has changed since initialization or last `reset()`.
+     *
+     * Useful for:
+     * - Tracking unsaved changes
+     * - Enabling/disabling save buttons
+     * - Detecting form modifications
+     *
+     * @example
+     * ```ts
+     * const form$ = atom({ name: "", email: "" });
+     *
+     * form$.dirty(); // false - just initialized
+     *
+     * form$.set({ name: "John", email: "" });
+     * form$.dirty(); // true - value changed
+     *
+     * form$.reset();
+     * form$.dirty(); // false - reset clears dirty flag
+     * ```
+     */
+    dirty(): boolean;
+}
+/**
+ * A derived (computed) atom that always returns Promise<T> for its value.
+ *
+ * DerivedAtom computes its value from other atoms. The computation is
+ * re-run whenever dependencies change. The `.value` always returns a Promise,
+ * even for synchronous computations.
+ *
+ * @template T - The resolved type of the computed value
+ * @template F - Whether fallback is provided (affects staleValue type)
+ *
+ * @example
+ * ```ts
+ * // Without fallback
+ * const double$ = derived(({ get }) => get(count$) * 2);
+ * await double$.value; // number
+ * double$.staleValue;  // number | undefined
+ * double$.state();     // { status: "ready", value: 10 }
+ *
+ * // With fallback - during loading
+ * const double$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+ * double$.staleValue;  // number (guaranteed)
+ * double$.state();     // { status: "loading", promise } during loading
+ * ```
+ */
+export interface DerivedAtom<T, F extends boolean = false> extends Atom<Promise<T>> {
+    /** Symbol marker to identify derived atom instances */
+    readonly [SYMBOL_DERIVED]: true;
+    /** Re-run the computation */
+    refresh(): void;
+    /**
+     * Get the current state of the derived atom.
+     * Returns a discriminated union with status, value/error, and stale flag.
+     */
+    state(): AtomState<T>;
+    /**
+     * The stale value - fallback or last resolved value.
+     * - Without fallback: T | undefined
+     * - With fallback: T (guaranteed)
+     */
+    readonly staleValue: F extends true ? T : T | undefined;
+}
+/**
+ * Union type for any atom (mutable or derived).
+ */
+export type AnyAtom<T> = MutableAtom<T> | DerivedAtom<T, boolean>;
+/**
+ * Extract the value type from an atom.
+ * For DerivedAtom, returns the awaited type.
+ */
+export type AtomValue<A> = A extends DerivedAtom<infer V, boolean> ? V : A extends Atom<infer V> ? Awaited<V> : never;
+/**
+ * Represents the state of an atom as a discriminated union.
+ *
+ * Uses intuitive state terms:
+ * - `ready` - Value is available
+ * - `error` - Computation failed
+ * - `loading` - Waiting for async value
+ *
+ * @template T - The type of the atom's value
+ */
+export type AtomState<T> = {
+    status: "ready";
+    value: T;
+} | {
+    status: "error";
+    error: unknown;
+} | {
+    status: "loading";
+    promise: Promise<T>;
+};
+/**
+ * Result type for settled operations.
+ */
+export type SettledResult<T> = {
+    status: "ready";
+    value: T;
+} | {
+    status: "error";
+    error: unknown;
+};
+/**
+ * Configuration options for creating a mutable atom.
+ *
+ * @template T - The type of value stored in the atom
+ */
+export interface AtomOptions<T> {
+    /** Optional metadata for the atom */
+    meta?: MutableAtomMeta;
+    /** Equality strategy for change detection (default: "strict") */
+    equals?: Equality<T>;
+}
+export interface MutableAtomMeta extends AtomMeta {
+}
+export interface DerivedAtomMeta extends AtomMeta {
+}
+/**
+ * Configuration options for creating a derived atom.
+ *
+ * @template T - The type of the derived value
+ */
+export interface DerivedOptions<T> {
+    /** Optional metadata for the atom */
+    meta?: DerivedAtomMeta;
+    /** Equality strategy for change detection (default: "strict") */
+    equals?: Equality<T>;
+}
+/**
+ * Configuration options for effects.
+ */
+export interface EffectOptions {
+    /** Optional key for debugging */
+    key?: string;
+    /** Error handler for uncaught errors in the effect */
+    onError?: (error: Error) => void;
+}
+/**
+ * A function that returns a value when called.
+ * Used for lazy evaluation in derived atoms.
+ *
+ * @template T - The type of value returned
+ */
+export type Getter<T> = () => T;
+/**
+ * Built-in equality strategy names.
+ *
+ * Used with atoms to control when subscribers are notified:
+ * - `"strict"` - Object.is (default, fastest)
+ * - `"shallow"` - Compare object keys/array items with Object.is
+ * - `"shallow2"` - 2 levels deep
+ * - `"shallow3"` - 3 levels deep
+ * - `"deep"` - Full recursive comparison (slowest)
+ */
+export type EqualityShorthand = "strict" | "shallow" | "shallow2" | "shallow3" | "deep";
+/**
+ * Equality strategy for change detection.
+ *
+ * Can be a shorthand string or custom comparison function.
+ * Used by atoms to determine if value has "changed" -
+ * if equal, subscribers won't be notified.
+ *
+ * @template T - Type of values being compared
+ */
+export type Equality<T = unknown> = EqualityShorthand | ((a: T, b: T) => boolean);
+/**
+ * Prettify a type by adding all properties to the type.
+ * @template T - The type to prettify
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export interface ModuleMeta {
+}
+export type Listener<T> = (value: T) => void;
+export type SingleOrMultipleListeners<T> = Listener<T> | Listener<T>[];
+/**
+ * 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/withUse.d.ts

@@ -0,0 +1,38 @@
+import { Pipeable } from './types';
+/**
+ * Adds a chainable `.use()` method to any object, enabling plugin-based transformations.
+ *
+ * The `.use()` method accepts a plugin function that receives the source object
+ * and can return a transformed version. Supports several return patterns:
+ *
+ * - **Void/falsy**: Returns the original source unchanged (side-effect only plugins)
+ * - **Object/function with `.use`**: Returns as-is (already chainable)
+ * - **Object/function without `.use`**: Wraps with `withUse()` for continued chaining
+ * - **Primitive**: Returns the value directly
+ *
+ * @template TSource - The type of the source object being enhanced
+ * @param source - The object to add `.use()` method to
+ * @returns The source object with `.use()` method attached
+ *
+ * @example
+ * // Basic usage with atom tuple
+ * const mappable = withUse([signal, setter]);
+ * const transformed = mappable.use(([sig, set]) => ({
+ *   sig,
+ *   set: (v: string) => set(Number(v))
+ * }));
+ *
+ * @example
+ * // Chaining multiple transformations
+ * atom(0)
+ *   .use(([sig, set]) => [sig, (v: number) => set(v * 2)])
+ *   .use(([sig, set]) => [sig, (v: number) => set(v + 1)]);
+ *
+ * @example
+ * // Side-effect only plugin (returns void)
+ * mappable.use((source) => {
+ *   console.log('Source:', source);
+ *   // returns undefined - original source is returned
+ * });
+ */
+export declare function withUse<TSource extends object>(source: TSource): TSource & Pipeable;

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

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