atomirx 0.1.0 → 0.1.2

package/dist/core/abortable.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Options for configuring an abortable promise.
+ */
+export interface AbortableOptions {
+    /**
+     * External signal(s) to link. The abortable promise will abort when any
+     * of these signals abort. Useful for hierarchical cancellation.
+     *
+     * @example Single signal
+     * ```ts
+     * const controller = new AbortController();
+     * const req = abortable((signal) => fetch('/api', { signal }), {
+     *   signal: controller.signal
+     * });
+     * controller.abort(); // Aborts the request
+     * ```
+     *
+     * @example Multiple signals (e.g., timeout + user cancel)
+     * ```ts
+     * const req = abortable((signal) => fetch('/api', { signal }), {
+     *   signal: [AbortSignal.timeout(5000), userCancelSignal]
+     * });
+     * ```
+     */
+    signal?: AbortSignal | AbortSignal[];
+    /**
+     * Callback invoked when the operation is aborted. Called once, regardless
+     * of abort source (manual abort, linked signal, or inner AbortError).
+     *
+     * @param reason - The abort reason (string, Error, or any value)
+     *
+     * @example
+     * ```ts
+     * const req = abortable((signal) => fetch('/api', { signal }), {
+     *   onAbort: (reason) => console.log('Aborted:', reason)
+     * });
+     * ```
+     */
+    onAbort?: (reason: unknown) => void;
+}
+/**
+ * Promise with abort control capabilities.
+ *
+ * Extends the standard Promise interface with:
+ * - `abort(reason?)` - Cancel the operation
+ * - `aborted()` - Check if operation was aborted
+ */
+export interface AbortablePromise<T> extends Promise<T> {
+    /**
+     * Abort the operation with an optional reason.
+     *
+     * - Immediately rejects the promise with an AbortError
+     * - Calls the `onAbort` callback if provided
+     * - Signals abort to the inner function via its AbortSignal
+     * - Safe to call multiple times (subsequent calls are no-ops)
+     *
+     * @param reason - Optional abort reason (passed to onAbort and error message)
+     *
+     * @example
+     * ```ts
+     * const req = abortable((signal) => fetch('/api', { signal }));
+     * req.abort('User cancelled');
+     * ```
+     */
+    abort(reason?: unknown): void;
+    /**
+     * Returns true if the operation was aborted.
+     *
+     * Aborted state is set when:
+     * - `abort()` is called explicitly
+     * - A linked signal aborts
+     * - The inner function throws an AbortError
+     *
+     * @returns boolean indicating abort state
+     *
+     * @example
+     * ```ts
+     * const req = abortable((signal) => fetch('/api', { signal }));
+     * req.abort();
+     * console.log(req.aborted()); // true
+     * ```
+     */
+    aborted(): boolean;
+}
+/**
+ * Creates an AbortError (DOMException with name 'AbortError').
+ *
+ * @param reason - Optional reason for the abort (string, Error, or any value)
+ * @returns DOMException with name 'AbortError'
+ *
+ * @example
+ * ```ts
+ * throw createAbortError('User cancelled');
+ * throw createAbortError({ message: 'Timeout exceeded' });
+ * ```
+ */
+export declare function createAbortError(reason?: unknown): DOMException;
+/**
+ * Checks if an error is an AbortError.
+ *
+ * Returns true for:
+ * - DOMException with name 'AbortError'
+ * - Error with name 'AbortError'
+ *
+ * @param error - The error to check
+ * @returns true if the error is an AbortError
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await abortableRequest;
+ * } catch (e) {
+ *   if (isAbortError(e)) {
+ *     console.log('Request was cancelled');
+ *   } else {
+ *     throw e;
+ *   }
+ * }
+ * ```
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Wraps an async function with abort control.
+ *
+ * Returns a Promise that can be aborted, with automatic cleanup and
+ * hierarchical cancellation support.
+ *
+ * ## Features
+ *
+ * - **Guaranteed rejection on abort**: Immediate rejection when abort is called
+ * - **Hierarchical cancellation**: Link to parent signals for nested abort
+ * - **Bidirectional abort detection**: Detects abort from both external and internal sources
+ * - **Safe abort**: Multiple abort() calls are no-ops
+ *
+ * ## Behavior Table
+ *
+ * | Trigger                    | Promise         | aborted() | onAbort |
+ * |----------------------------|-----------------|-----------|---------|
+ * | `abort()` called           | Rejects         | `true`    | ✓       |
+ * | Linked signal aborts       | Rejects         | `true`    | ✓       |
+ * | Inner fn throws AbortError | Rejects         | `true`    | ✓       |
+ * | Inner fn throws other      | Rejects         | `false`   | ✗       |
+ * | Inner fn resolves          | Resolves        | `false`   | ✗       |
+ *
+ * @param fn - Function that receives an AbortSignal. Can return sync value or Promise.
+ * @param options - Optional configuration (linked signals, onAbort callback)
+ * @returns AbortablePromise with abort() and aborted() methods
+ *
+ * @example Basic usage with async function
+ * ```ts
+ * const req = abortable((signal) => fetch('/api', { signal }));
+ * req.abort('User cancelled');
+ * console.log(req.aborted()); // true
+ * ```
+ *
+ * @example Sync function (always returns a Promise)
+ * ```ts
+ * const result = await abortable(() => computeExpensiveValue());
+ * ```
+ *
+ * @example With timeout and cleanup
+ * ```ts
+ * const req = abortable(
+ *   (signal) => fetch('/api/slow', { signal }),
+ *   {
+ *     signal: AbortSignal.timeout(5000),
+ *     onAbort: () => console.log('Request timed out or cancelled')
+ *   }
+ * );
+ * ```
+ *
+ * @example Composing nested abortable operations
+ * ```ts
+ * const parent = abortable(async (signal) => {
+ *   const a = await abortable((s) => fetchA(s), { signal });
+ *   const b = await abortable((s) => fetchB(s), { signal });
+ *   return { a, b };
+ * });
+ * parent.abort(); // Cancels entire chain
+ * ```
+ *
+ * @example Component unmount pattern
+ * ```ts
+ * const unmountController = new AbortController();
+ *
+ * // In component effect
+ * const req = abortable(
+ *   (signal) => fetchUserData(signal),
+ *   { signal: unmountController.signal }
+ * );
+ *
+ * // On unmount
+ * unmountController.abort();
+ * ```
+ */
+export declare function abortable<T>(fn: (signal: AbortSignal) => T | Promise<T>, options?: AbortableOptions): AbortablePromise<T>;

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

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

package/dist/core/derived.d.ts

@@ -16,10 +16,13 @@ export interface DerivedInternalOptions {
 }
 /**
  * Context object passed to derived atom selector functions.
- * Provides utilities for reading atoms: `{ read, all, any, race, settled }`.
+ * Provides utilities for reading atoms.
  *
- * Currently identical to `SelectContext`, but defined separately to allow
- * future derived-specific extensions without breaking changes.
+ * Extends SelectContext with:
+ * - `ready()` - Wait for non-null values (from WithReadyContext)
+ *
+ * Note: Events now implement Atom<Promise<T>> and work directly with
+ * `read()`, `race()`, `all()` - no special `wait()` method needed.
  */
 export interface DerivedContext extends SelectContext, WithReadyContext {
 }

package/dist/core/effect.d.ts

@@ -5,6 +5,9 @@ import { WithReadyContext } from './withReady';
 /**
  * Context object passed to effect functions.
  * Extends `SelectContext` with cleanup utilities.
+ *
+ * Note: Events now implement Atom<Promise<T>> and work directly with
+ * `read()`, `race()`, `all()` - no special `wait()` method needed.
  */
 export interface EffectContext extends SelectContext, WithReadyContext, WithAbortContext {
     /**

package/dist/core/event.d.ts

@@ -0,0 +1,152 @@
+import { Equality, Event, EventMeta } from './types';
+/**
+ * Options for creating an event.
+ *
+ * @template T - The type of payload
+ */
+export interface EventOptions<T = void> {
+    /** Optional metadata for debugging/devtools */
+    meta?: EventMeta;
+    /**
+     * Equality function to compare payloads.
+     *
+     * When `fire(payload)` is called after the first fire:
+     * - If `equals(lastPayload, payload)` returns true → no-op (no new promise)
+     * - If `equals(lastPayload, payload)` returns false → create new resolved promise
+     *
+     * **Default: `() => false`** - every fire creates a new promise.
+     * This is important for void events where `fire()` is called multiple times.
+     *
+     * @example Dedupe identical payloads
+     * ```ts
+     * const searchEvent = event<string>({ equals: "shallow" });
+     * searchEvent.fire("hello");  // Promise1 resolves
+     * searchEvent.fire("hello");  // No-op (same value)
+     * searchEvent.fire("world");  // Promise2 created
+     * ```
+     */
+    equals?: Equality<T>;
+    /**
+     * If true, the event can only fire once.
+     * After first fire, subsequent `fire()` calls are no-op.
+     * `next()` returns the same resolved promise forever.
+     *
+     * Useful for one-time events like initialization, login, or data load.
+     *
+     * @example
+     * ```ts
+     * const initEvent = event<Config>({ once: true });
+     * initEvent.fire(config);   // Promise resolved
+     * initEvent.fire(config2);  // No-op (already fired)
+     * initEvent.get();          // Same resolved promise
+     * initEvent.next();         // Same resolved promise
+     * ```
+     */
+    once?: boolean;
+}
+/**
+ * Creates an event - a reactive signal that can be fired with a payload.
+ *
+ * Events implement `Atom<Promise<T>>`, so they work directly with
+ * `read()`, `race()`, `all()` in derived/effect - no wrapper needed.
+ *
+ * ## Behavior
+ *
+ * ```
+ * event<T>() created
+ *        │
+ *        ▼
+ *    atom.value = Promise1 (pending)
+ *        │
+ * fire(A) ────────────────────────────────┐
+ *        │                                │
+ *    First fire?                          │
+ *        │Yes                             │
+ *        ▼                                │
+ *    Promise1.resolve(A)                  │
+ *    last = { data: A }                   │
+ *        │                                │
+ * fire(B) ────────────────────────────────┤
+ *        │                                │
+ *    !equals(A, B)?                       │
+ *        │Yes                             │
+ *        ▼                                │
+ *    atom.value = Promise2 (resolved B)   │
+ *    → subscribers notified               │
+ *    last = { data: B }                   │
+ * ```
+ *
+ * ## Key Features
+ *
+ * 1. **Atom-compatible**: Works with `read()`, `race()`, `all()` directly
+ * 2. **Suspend until fire**: `read(event)` suspends if promise is pending
+ * 3. **Reactive**: `fire()` triggers derived recomputation via subscription
+ * 4. **Deduplication**: Use `equals` option to skip identical payloads
+ *
+ * @template T - The type of payload (void for no payload)
+ * @param options - Optional configuration (meta, equals)
+ * @returns An Event instance that implements Atom<Promise<T>>
+ *
+ * @example Basic usage
+ * ```ts
+ * const clickEvent = event<{ x: number; y: number }>();
+ *
+ * // Fire the event
+ * clickEvent.fire({ x: 100, y: 200 });
+ *
+ * // Get last fired payload
+ * clickEvent.last(); // { x: 100, y: 200 }
+ *
+ * // Get current promise
+ * const promise = clickEvent.get();
+ * ```
+ *
+ * @example Void event (no payload)
+ * ```ts
+ * const cancelEvent = event();
+ * cancelEvent.fire(); // No payload needed
+ * cancelEvent.fire(); // Each fire creates new promise (default equals)
+ * ```
+ *
+ * @example In derived - works directly with read()
+ * ```ts
+ * const result$ = derived(({ read }) => {
+ *   const data = read(submitEvent); // suspends until fire
+ *   return processSubmit(data);
+ * });
+ * ```
+ *
+ * @example Race multiple events
+ * ```ts
+ * const result$ = derived(({ race }) => {
+ *   const { key, value } = race({
+ *     submit: submitEvent,
+ *     cancel: cancelEvent,
+ *   });
+ *   return key === 'cancel' ? null : processSubmit(value);
+ * });
+ * ```
+ *
+ * @example With equals (dedupe identical payloads)
+ * ```ts
+ * const searchEvent = event<string>({ equals: "shallow" });
+ * searchEvent.fire("hello");  // Promise1 resolves
+ * searchEvent.fire("hello");  // No-op (same value)
+ * searchEvent.fire("world");  // Promise2 created, subscribers notified
+ * ```
+ */
+export declare function event<T = void>(options?: EventOptions<T>): Event<T>;
+/**
+ * Type guard to check if a value is an Event.
+ *
+ * @param value - The value to check
+ * @returns true if the value is an Event
+ *
+ * @example
+ * ```ts
+ * if (isEvent(value)) {
+ *   value.fire(payload);
+ * }
+ * ```
+ */
+export declare function isEvent<T = unknown>(value: unknown): value is Event<T>;

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

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

package/dist/core/onCreateHook.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from './effect';
-import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta, EffectMeta, PoolMeta, Pool } from './types';
+import { MutableAtomMeta, DerivedAtomMeta, MutableAtom, DerivedAtom, ModuleMeta, EffectMeta, PoolMeta, Pool, EventMeta, Event } from './types';
 /**
  * Information provided when a mutable atom is created.
  */
@@ -40,9 +40,22 @@ export interface EffectInfo {
     instance: Effect;
 }
 /**
- * Union type for atom/derived/effect creation info.
+ * Information provided when an event is created.
  */
-export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo | PoolInfo;
+export interface EventInfo {
+    /** Discriminator for events */
+    type: "event";
+    /** Optional key from event options (for debugging/devtools) */
+    key: string | undefined;
+    /** Optional metadata from event options */
+    meta: EventMeta | undefined;
+    /** The created event instance */
+    instance: Event<unknown>;
+}
+/**
+ * Union type for atom/derived/effect/event creation info.
+ */
+export type CreateInfo = MutableInfo | DerivedInfo | EffectInfo | PoolInfo | EventInfo;
 /**
  * Information provided when a module (via define()) is created.
  */

package/dist/core/promiseCache.d.ts

@@ -109,6 +109,41 @@ export declare function isFulfilled<T>(value: T | PromiseLike<T>): boolean;
  * @returns true if value is a Promise in rejected state
  */
 export declare function isRejected<T>(value: T | PromiseLike<T>): boolean;
+/**
+ * Creates a Promise that is immediately resolved AND pre-cached as fulfilled.
+ * This avoids the loading→resolved flicker when trackPromise() is called.
+ *
+ * Use this instead of `Promise.resolve(value)` when you need the promise
+ * to be recognized as already-resolved by the promise tracking system.
+ *
+ * @param value - The resolved value
+ * @returns A resolved Promise with pre-populated cache state
+ *
+ * @example
+ * ```ts
+ * const promise = createResolvedPromise(42);
+ * const state = trackPromise(promise);
+ * // state.status === 'fulfilled' immediately (no loading flicker)
+ * ```
+ */
+export declare function createResolvedPromise<T>(value: T): Promise<T>;
+/**
+ * Creates a Promise that is immediately rejected AND pre-cached as rejected.
+ * This avoids the loading→rejected flicker when trackPromise() is called.
+ *
+ * Note: Attaches a no-op catch to prevent unhandled rejection warnings.
+ *
+ * @param error - The rejection error
+ * @returns A rejected Promise with pre-populated cache state
+ *
+ * @example
+ * ```ts
+ * const promise = createRejectedPromise(new Error('Failed'));
+ * const state = trackPromise(promise);
+ * // state.status === 'rejected' immediately (no loading flicker)
+ * ```
+ */
+export declare function createRejectedPromise<T = never>(error: unknown): Promise<T>;
 /**
  * Gets the resolved value of a Promise if fulfilled, otherwise undefined.
  *

package/dist/core/select.d.ts

@@ -103,7 +103,7 @@ export interface SelectContext extends Pipeable {
      * const [user, posts] = all([user$, posts$]);
      * ```
      */
-    all<A extends Atom<unknown>[]>(atoms: A): {
+    all<const A extends readonly Atom<unknown>[]>(atoms: A): {
         [K in keyof A]: AtomValue<A[K]>;
     };
     /**
@@ -115,20 +115,24 @@ export interface SelectContext extends Pipeable {
      * - If all atoms are loading → throws first Promise
      *
      * The `key` in the result identifies which atom won the race.
+     * Returns a discriminated union - checking `key` narrows `value` type.
      *
      * Note: race() does NOT use fallback - it's meant for first "real" settled value.
      *
      * @param atoms - Record of atoms to race
-     * @returns KeyedResult with winning key and value
+     * @returns KeyedResult discriminated union with winning key and value
      *
      * @example
      * ```ts
      * const result = race({ cache: cache$, api: api$ });
-     * console.log(result.key);   // "cache" or "api"
-     * console.log(result.value); // The winning value
+     * if (result.key === "cache") {
+     *   result.value; // narrowed to cache atom's type
+     * }
      * ```
      */
-    race<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
+    race<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<{
+        [K in keyof T & string]: AtomValue<T[K]>;
+    }>;
     /**
      * Return the first ready value (like Promise.any).
      * Object-based - pass atoms as a record with keys.
@@ -138,20 +142,24 @@ export interface SelectContext extends Pipeable {
      * - If any loading (not all errored) → throws Promise
      *
      * The `key` in the result identifies which atom resolved first.
+     * Returns a discriminated union - checking `key` narrows `value` type.
      *
      * Note: any() does NOT use fallback - it waits for a real ready value.
      *
      * @param atoms - Record of atoms to check
-     * @returns KeyedResult with winning key and value
+     * @returns KeyedResult discriminated union with winning key and value
      *
      * @example
      * ```ts
      * const result = any({ primary: primaryApi$, fallback: fallbackApi$ });
-     * console.log(result.key);   // "primary" or "fallback"
-     * console.log(result.value); // The winning value
+     * if (result.key === "primary") {
+     *   result.value; // narrowed to primary atom's type
+     * }
      * ```
      */
-    any<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<keyof T & string, AtomValue<T[keyof T]>>;
+    any<T extends Record<string, Atom<unknown>>>(atoms: T): KeyedResult<{
+        [K in keyof T & string]: AtomValue<T[K]>;
+    }>;
     /**
      * Get all atom statuses when all are settled (like Promise.allSettled).
      * Array-based - pass atoms as an array.
@@ -168,7 +176,7 @@ export interface SelectContext extends Pipeable {
      * const [userResult, postsResult] = settled([user$, posts$]);
      * ```
      */
-    settled<A extends Atom<unknown>[]>(atoms: A): {
+    settled<const A extends readonly Atom<unknown>[]>(atoms: A): {
         [K in keyof A]: SettledResult<AtomValue<A[K]>>;
     };
     /**