atomirx 0.0.1

package/dist/core/batch.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Batches multiple state updates into a single reactive update cycle.
+ *
+ * Without batching, each `atom.set()` call triggers immediate notifications to all
+ * subscribers. With `batch()`, all updates are collected and subscribers are notified
+ * once at the end with the final values.
+ *
+ * ## Key Behavior
+ *
+ * 1. **Multiple updates to same atom**: Only 1 notification with final value
+ * 2. **Listener deduplication**: Same listener subscribed to multiple atoms = 1 call
+ * 3. **Nested batches**: Inner batches are merged into outer batch
+ * 4. **Cascading updates**: Updates triggered by listeners are also batched
+ *
+ * ## When to Use
+ *
+ * - Updating multiple related atoms together
+ * - Preventing intermediate render states
+ * - Performance optimization for bulk updates
+ * - Ensuring consistent state during complex operations
+ *
+ * ## How It Works
+ *
+ * ```
+ * batch(() => {
+ *   a.set(1);  // Queued, no notification yet
+ *   b.set(2);  // Queued, no notification yet
+ *   c.set(3);  // Queued, no notification yet
+ * });
+ * // All listeners notified once here (deduped)
+ * ```
+ *
+ * @template T - Return type of the batched function
+ * @param fn - Function containing multiple state updates
+ * @returns The return value of fn
+ *
+ * @example Basic batching - prevent intermediate states
+ * ```ts
+ * const firstName = atom("John");
+ * const lastName = atom("Doe");
+ *
+ * // Without batch: component renders twice (once per set)
+ * firstName.set("Jane");
+ * lastName.set("Smith");
+ *
+ * // With batch: component renders once with final state
+ * batch(() => {
+ *   firstName.set("Jane");
+ *   lastName.set("Smith");
+ * });
+ * ```
+ *
+ * @example Multiple updates to same atom
+ * ```ts
+ * const counter = atom(0);
+ *
+ * counter.on(() => console.log("Counter:", counter.value));
+ *
+ * batch(() => {
+ *   counter.set(1);
+ *   counter.set(2);
+ *   counter.set(3);
+ * });
+ * // Logs once: "Counter: 3"
+ * ```
+ *
+ * @example Listener deduplication
+ * ```ts
+ * const a = atom(0);
+ * const b = atom(0);
+ *
+ * // Same listener subscribed to both atoms
+ * const listener = () => console.log("Changed!", a.value, b.value);
+ * a.on(listener);
+ * b.on(listener);
+ *
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * // Logs once: "Changed! 1 2" (not twice)
+ * ```
+ *
+ * @example Nested batches
+ * ```ts
+ * batch(() => {
+ *   a.set(1);
+ *   batch(() => {
+ *     b.set(2);
+ *     c.set(3);
+ *   });
+ *   d.set(4);
+ * });
+ * // All updates batched together, listeners notified once at outer batch end
+ * ```
+ *
+ * @example Return value
+ * ```ts
+ * const result = batch(() => {
+ *   counter.set(10);
+ *   return counter.value * 2;
+ * });
+ * console.log(result); // 20
+ * ```
+ *
+ * @example With async operations (be careful!)
+ * ```ts
+ * // ❌ Wrong: async operations escape the batch
+ * batch(async () => {
+ *   a.set(1);
+ *   await delay(100);
+ *   b.set(2); // This is OUTSIDE the batch!
+ * });
+ *
+ * // ✅ Correct: batch sync operations only
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * await delay(100);
+ * batch(() => {
+ *   c.set(3);
+ * });
+ * ```
+ */
+export declare function batch<T>(fn: () => T): T;

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

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

package/dist/core/define.d.ts

@@ -0,0 +1,173 @@
+import { ModuleMeta } from './types';
+/**
+ * A factory function that creates a swappable lazy singleton store.
+ *
+ * @template TModule The type of the store instance
+ */
+export interface Define<TModule> {
+    readonly key: string | undefined;
+    /** Get the current service instance (creates lazily on first call) */
+    (): TModule;
+    /**
+     * Override the service implementation with a lazy factory.
+     * Useful for testing, platform-specific implementations, or feature flags.
+     * The factory is called lazily on first access after override.
+     *
+     * **IMPORTANT**: Must be called **before** the service is initialized.
+     * Throws an error if called after the service has been accessed.
+     *
+     * @param factory - Factory function that creates the replacement implementation.
+     *                  Receives the original factory as argument for extending.
+     *
+     * @throws {Error} If called after the service has been initialized
+     *
+     * @example Full replacement
+     * ```ts
+     * myService.override(() => ({ value: 'mock' }));
+     * ```
+     *
+     * @example Extend original
+     * ```ts
+     * myService.override((original) => ({
+     *   ...original(),
+     *   extraMethod() { ... }
+     * }));
+     * ```
+     */
+    override(factory: (original: () => TModule) => TModule): void;
+    /**
+     * Reset to the original implementation.
+     * Clears any override set via `.override()` and disposes the current instance.
+     * Next access will create a fresh original instance.
+     */
+    reset(): void;
+    /**
+     * Invalidate the cached instance. Next call will create a fresh instance.
+     * If the current instance has a `dispose()` method, it will be called before clearing.
+     *
+     * Unlike `reset()` which only clears overrides, `invalidate()` clears everything
+     * so the next access creates a completely fresh instance from the factory.
+     */
+    invalidate(): void;
+    /** Returns true if currently using an overridden implementation via `.override()` */
+    isOverridden(): boolean;
+    /** Returns true if the lazy instance has been created */
+    isInitialized(): boolean;
+}
+export interface DefineOptions {
+    key?: string;
+    meta?: ModuleMeta;
+}
+/**
+ * Creates a swappable lazy singleton store.
+ *
+ * Unlike `once()` from lodash, `define()` allows you to:
+ * - Override the implementation at runtime with `.override()`
+ * - Reset to the original with `.reset()`
+ * - Invalidate and recreate fresh with `.invalidate()`
+ *
+ * This is useful for:
+ * - **Testing** - inject mocks without module mocking
+ * - **Platform-specific** - mobile vs web implementations
+ * - **Feature flags** - swap implementations at runtime
+ *
+ * @param creator - Factory function that creates the store instance
+ * @returns A callable store with `.override()`, `.reset()`, and `.invalidate()` methods
+ *
+ * @example Basic usage
+ * ```ts
+ * const counterStore = define(() => {
+ *   const [count, setCount] = atom(0);
+ *   return {
+ *     count,
+ *     increment: () => setCount((c) => c + 1),
+ *   };
+ * });
+ *
+ * // Normal usage - lazy singleton
+ * const store = counterStore();
+ * store.increment();
+ * ```
+ *
+ * @example Platform-specific implementation
+ * ```ts
+ * const storageStore = define(() => ({
+ *   get: (key) => localStorage.getItem(key),
+ *   set: (key, value) => localStorage.setItem(key, value),
+ * }));
+ *
+ * // On mobile, swap to secure storage BEFORE first access
+ * if (isMobile()) {
+ *   storageStore.override(() => ({
+ *     get: (key) => SecureStore.getItem(key),
+ *     set: (key, value) => SecureStore.setItem(key, value),
+ *   }));
+ * }
+ * ```
+ *
+ * @example Extending original with extra methods
+ * ```ts
+ * apiStore.override((original) => ({
+ *   ...original(),
+ *   mockFetch: vi.fn(),
+ * }));
+ * ```
+ *
+ * @example Wrapping original behavior
+ * ```ts
+ * loggerStore.override((original) => {
+ *   const base = original();
+ *   return {
+ *     ...base,
+ *     log: (msg) => {
+ *       console.log('[DEBUG]', msg);
+ *       base.log(msg);
+ *     },
+ *   };
+ * });
+ * ```
+ *
+ * @example Testing with reset (creates fresh instances)
+ * ```ts
+ * beforeEach(() => {
+ *   counterStore.override(() => ({
+ *     count: () => 999,
+ *     increment: vi.fn(),
+ *   }));
+ * });
+ *
+ * afterEach(() => {
+ *   counterStore.reset(); // Clears override, next call creates fresh original
+ * });
+ * ```
+ *
+ * @example Testing with invalidate (fresh instance each test)
+ * ```ts
+ * afterEach(() => {
+ *   counterStore.invalidate(); // Next call creates fresh instance
+ * });
+ *
+ * it('test 1', () => {
+ *   counterStore().increment(); // count = 1
+ * });
+ *
+ * it('test 2', () => {
+ *   // Fresh instance, count starts at 0 again
+ *   expect(counterStore().count()).toBe(0);
+ * });
+ * ```
+ *
+ * @example Store with dispose cleanup
+ * ```ts
+ * const connectionStore = define(() => {
+ *   const connection = createConnection();
+ *   return {
+ *     query: (sql) => connection.query(sql),
+ *     dispose: () => connection.close(), // Called on invalidate()
+ *   };
+ * });
+ *
+ * connectionStore.invalidate(); // Closes connection, next call creates new
+ * ```
+ */
+export declare function define<T>(creator: () => T, options?: DefineOptions): Define<T>;

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

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

package/dist/core/derived.d.ts

@@ -0,0 +1,102 @@
+import { SelectContext } from './select';
+import { DerivedAtom, DerivedOptions } from './types';
+/**
+ * Context object passed to derived atom selector functions.
+ * Provides utilities for reading atoms: `{ get, all, any, race, settled }`.
+ *
+ * Currently identical to `SelectContext`, but defined separately to allow
+ * future derived-specific extensions without breaking changes.
+ */
+export interface DerivedContext extends SelectContext {
+}
+/**
+ * Creates a derived (computed) atom from source atom(s).
+ *
+ * Derived atoms are **read-only** and automatically recompute when their
+ * source atoms change. The `.value` property always returns a `Promise<T>`,
+ * even for synchronous computations.
+ *
+ * ## IMPORTANT: Selector Must Return Synchronous Value
+ *
+ * **The selector function MUST NOT be async or return a Promise.**
+ *
+ * ```ts
+ * // ❌ WRONG - Don't use async function
+ * derived(async ({ get }) => {
+ *   const data = await fetch('/api');
+ *   return data;
+ * });
+ *
+ * // ❌ WRONG - Don't return a Promise
+ * derived(({ get }) => fetch('/api').then(r => r.json()));
+ *
+ * // ✅ CORRECT - Create async atom and read with get()
+ * const data$ = atom(fetch('/api').then(r => r.json()));
+ * derived(({ get }) => get(data$)); // Suspends until resolved
+ * ```
+ *
+ * ## Key Features
+ *
+ * 1. **Always async**: `.value` returns `Promise<T>`
+ * 2. **Lazy computation**: Value is computed on first access
+ * 3. **Automatic updates**: Recomputes when any source atom changes
+ * 4. **Equality checking**: Only notifies if derived value changed
+ * 5. **Fallback support**: Optional fallback for loading/error states
+ * 6. **Suspense-like async**: `get()` throws promise if loading
+ * 7. **Conditional dependencies**: Only subscribes to atoms accessed
+ *
+ * ## Suspense-Style get()
+ *
+ * The `get()` function behaves like React Suspense:
+ * - If source atom is **loading**: `get()` throws the promise
+ * - If source atom has **error**: `get()` throws the error
+ * - If source atom has **value**: `get()` returns the value
+ *
+ * @template T - Derived value type
+ * @template F - Whether fallback is provided
+ * @param fn - Context-based derivation function (must return sync value, not Promise)
+ * @param options - Optional configuration (meta, equals, fallback)
+ * @returns A read-only derived atom
+ * @throws Error if selector returns a Promise or PromiseLike
+ *
+ * @example Basic derived (no fallback)
+ * ```ts
+ * const count$ = atom(5);
+ * const doubled$ = derived(({ get }) => get(count$) * 2);
+ *
+ * await doubled$.value; // 10
+ * doubled$.staleValue;  // undefined (until first resolve) -> 10
+ * doubled$.state();     // { status: "ready", value: 10 }
+ * ```
+ *
+ * @example With fallback
+ * ```ts
+ * const posts$ = atom(fetchPosts());
+ * const count$ = derived(({ get }) => get(posts$).length, { fallback: 0 });
+ *
+ * count$.staleValue; // 0 (during loading) -> 42 (after resolve)
+ * count$.state();    // { status: "loading", promise } during loading
+ *                    // { status: "ready", value: 42 } after resolve
+ * ```
+ *
+ * @example Async dependencies
+ * ```ts
+ * const user$ = atom(fetchUser());
+ * const posts$ = atom(fetchPosts());
+ *
+ * const dashboard$ = derived(({ all }) => {
+ *   const [user, posts] = all(user$, posts$);
+ *   return { user, posts };
+ * });
+ * ```
+ *
+ * @example Refresh
+ * ```ts
+ * const data$ = derived(({ get }) => get(source$));
+ * data$.refresh(); // Re-run computation
+ * ```
+ */
+export declare function derived<T>(fn: (ctx: DerivedContext) => T, options?: DerivedOptions<T>): DerivedAtom<T, false>;
+export declare function derived<T>(fn: (ctx: DerivedContext) => T, options: DerivedOptions<T> & {
+    fallback: T;
+}): DerivedAtom<T, true>;

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

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

package/dist/core/effect.d.ts

@@ -0,0 +1,120 @@
+import { SelectContext } from './select';
+import { EffectOptions } from './types';
+/**
+ * Context object passed to effect functions.
+ * Extends `SelectContext` with cleanup and error handling utilities.
+ */
+export interface EffectContext extends SelectContext {
+    /**
+     * Register a cleanup function that runs before the next execution or on dispose.
+     * Multiple cleanup functions can be registered; they run in FIFO order.
+     *
+     * @param cleanup - Function to run during cleanup
+     *
+     * @example
+     * ```ts
+     * effect(({ get, onCleanup }) => {
+     *   const id = setInterval(() => console.log('tick'), 1000);
+     *   onCleanup(() => clearInterval(id));
+     * });
+     * ```
+     */
+    onCleanup: (cleanup: VoidFunction) => void;
+    /**
+     * Register an error handler for synchronous errors thrown in the effect.
+     * If registered, prevents errors from propagating to `options.onError`.
+     *
+     * @param handler - Function to handle errors
+     *
+     * @example
+     * ```ts
+     * effect(({ get, onError }) => {
+     *   onError((e) => console.error('Effect failed:', e));
+     *   riskyOperation();
+     * });
+     * ```
+     */
+    onError: (handler: (error: unknown) => void) => void;
+}
+/**
+ * Callback function for effects.
+ * Receives the effect context with `{ get, all, any, race, settled, onCleanup, onError }` utilities.
+ */
+export type EffectFn = (context: EffectContext) => void;
+/**
+ * Creates a side-effect that runs when accessed atom(s) change.
+ *
+ * Effects are similar to derived atoms but for side-effects rather than computed values.
+ * They inherit derived's behavior:
+ * - **Suspense-like async**: Waits for async atoms to resolve before running
+ * - **Conditional dependencies**: Only tracks atoms actually accessed via `get()`
+ * - **Automatic cleanup**: Previous cleanup runs before next execution
+ * - **Batched updates**: Atom updates within the effect are batched
+ *
+ * ## IMPORTANT: Effect Function Must Be Synchronous
+ *
+ * **The effect function MUST NOT be async or return a Promise.**
+ *
+ * ```ts
+ * // ❌ WRONG - Don't use async function
+ * effect(async ({ get }) => {
+ *   const data = await fetch('/api');
+ *   console.log(data);
+ * });
+ *
+ * // ✅ CORRECT - Create async atom and read with get()
+ * const data$ = atom(fetch('/api').then(r => r.json()));
+ * effect(({ get }) => {
+ *   console.log(get(data$)); // Suspends until resolved
+ * });
+ * ```
+ *
+ * ## Basic Usage
+ *
+ * ```ts
+ * const dispose = effect(({ get }) => {
+ *   localStorage.setItem('count', String(get(countAtom)));
+ * });
+ * ```
+ *
+ * ## With Cleanup
+ *
+ * Use `onCleanup` to register cleanup functions that run before the next execution or on dispose:
+ *
+ * ```ts
+ * const dispose = effect(({ get, onCleanup }) => {
+ *   const interval = get(intervalAtom);
+ *   const id = setInterval(() => console.log('tick'), interval);
+ *   onCleanup(() => clearInterval(id));
+ * });
+ * ```
+ *
+ * ## Error Handling
+ *
+ * Use `onError` callback to handle errors within the effect, or `options.onError` for unhandled errors:
+ *
+ * ```ts
+ * // Callback-based error handling
+ * const dispose = effect(({ get, onError }) => {
+ *   onError((e) => console.error('Effect failed:', e));
+ *   const data = get(dataAtom);
+ *   riskyOperation(data);
+ * });
+ *
+ * // Option-based error handling (for unhandled errors)
+ * const dispose = effect(
+ *   ({ get }) => {
+ *     const data = get(dataAtom);
+ *     riskyOperation(data);
+ *   },
+ *   { onError: (e) => console.error('Effect failed:', e) }
+ * );
+ * ```
+ *
+ * @param fn - Effect callback receiving context with `{ get, all, any, race, settled, onCleanup, onError }`.
+ *             Must be synchronous (not async).
+ * @param options - Optional configuration (key, onError for unhandled errors)
+ * @returns Dispose function to stop the effect and run final cleanup
+ * @throws Error if effect function returns a Promise
+ */
+export declare function effect(fn: EffectFn, options?: EffectOptions): VoidFunction;

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

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