atomirx 0.0.2 → 0.0.5

package/dist/core/types.d.ts

@@ -25,8 +25,8 @@ export declare const SYMBOL_DERIVED: unique symbol;
  * @example
  * ```ts
  * const enhanced = atom(0)
- *   .use(source => ({ ...source, double: () => source.value * 2 }))
- *   .use(source => ({ ...source, triple: () => source.value * 3 }));
+ *   .use(source => ({ ...source, double: () => source.get() * 2 }))
+ *   .use(source => ({ ...source, triple: () => source.get() * 3 }));
  * ```
  */
 export interface Pipeable {
@@ -37,9 +37,8 @@ export interface Pipeable {
 /**
  * Optional metadata for atoms.
  */
-export interface AtomMeta {
+export interface AtomMeta extends AtomirxMeta {
     key?: string;
-    [key: string]: unknown;
 }
 /**
  * Base interface for all atoms.
@@ -50,10 +49,10 @@ export interface AtomMeta {
 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;
+    /** Get the current value */
+    get(): T;
     /**
      * Subscribe to value changes.
      * @param listener - Callback invoked when value changes
@@ -79,7 +78,7 @@ export interface Atom<T> {
  *
  * // Async value (stores Promise as-is)
  * const posts = atom(fetchPosts());
- * posts.value; // Promise<Post[]>
+ * posts.get(); // Promise<Post[]>
  * posts.set(fetchPosts()); // Store new Promise
  * ```
  */
@@ -119,7 +118,7 @@ export interface MutableAtom<T> extends Atom<T>, Pipeable {
  * 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,
+ * re-run whenever dependencies change. The `.get()` always returns a Promise,
  * even for synchronous computations.
  *
  * @template T - The resolved type of the computed value
@@ -128,13 +127,13 @@ export interface MutableAtom<T> extends Atom<T>, Pipeable {
  * @example
  * ```ts
  * // Without fallback
- * const double$ = derived(({ get }) => get(count$) * 2);
- * await double$.value; // number
+ * const double$ = derived(({ read }) => read(count$) * 2);
+ * await double$.get(); // number
  * double$.staleValue;  // number | undefined
  * double$.state();     // { status: "ready", value: 10 }
  *
  * // With fallback - during loading
- * const double$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+ * const double$ = derived(({ read }) => read(count$) * 2, { fallback: 0 });
  * double$.staleValue;  // number (guaranteed)
  * double$.state();     // { status: "loading", promise } during loading
  * ```
@@ -178,13 +177,59 @@ export type AtomValue<A> = A extends DerivedAtom<infer V, boolean> ? V : A exten
 export type AtomState<T> = {
     status: "ready";
     value: T;
+    error?: undefined;
+    promise?: undefined;
 } | {
     status: "error";
     error: unknown;
+    value?: undefined;
+    promise?: undefined;
 } | {
     status: "loading";
     promise: Promise<T>;
+    value?: undefined;
+    error?: undefined;
 };
+/**
+ * Result type for SelectContext.state() - simplified AtomState without promise.
+ *
+ * All properties (`status`, `value`, `error`) are always present:
+ * - `value` is `T` when ready, `undefined` otherwise
+ * - `error` is the error when errored, `undefined` otherwise
+ *
+ * This enables easy destructuring without type narrowing:
+ * ```ts
+ * const { status, value, error } = state(atom$);
+ * ```
+ *
+ * Equality comparisons work correctly (no promise reference issues).
+ */
+export type SelectStateResult<T> = {
+    status: "ready";
+    value: T;
+    error: undefined;
+} | {
+    status: "error";
+    value: undefined;
+    error: unknown;
+} | {
+    status: "loading";
+    value: undefined;
+    error: undefined;
+};
+/**
+ * Result type for race() and any() - includes winning key.
+ *
+ * @template K - The key type (string literal union)
+ * @template V - The value type
+ */
+export type KeyedResult<K extends string, V> = {
+    /** The key that won the race/any */
+    key: K;
+    /** The resolved value */
+    value: V;
+};
+export type AtomPlugin = <T extends Atom<any>>(atom: T) => T | void;
 /**
  * Result type for settled operations.
  */
@@ -220,15 +265,63 @@ export interface DerivedOptions<T> {
     meta?: DerivedAtomMeta;
     /** Equality strategy for change detection (default: "strict") */
     equals?: Equality<T>;
+    /**
+     * Callback invoked when the derived computation throws an error.
+     * This is called for actual errors, NOT for Promise throws (Suspense).
+     *
+     * @param error - The error thrown during computation
+     *
+     * @example
+     * ```ts
+     * const data$ = derived(
+     *   ({ read }) => {
+     *     const raw = read(source$);
+     *     return JSON.parse(raw); // May throw SyntaxError
+     *   },
+     *   {
+     *     onError: (error) => {
+     *       console.error('Derived computation failed:', error);
+     *       reportToSentry(error);
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    onError?: (error: unknown) => void;
 }
 /**
  * Configuration options for effects.
  */
 export interface EffectOptions {
-    /** Optional key for debugging */
+    meta?: EffectMeta;
+    /**
+     * Callback invoked when the effect computation throws an error.
+     * This is called for actual errors, NOT for Promise throws (Suspense).
+     *
+     * @param error - The error thrown during effect execution
+     *
+     * @example
+     * ```ts
+     * effect(
+     *   ({ read }) => {
+     *     const data = read(source$);
+     *     riskyOperation(data); // May throw
+     *   },
+     *   {
+     *     onError: (error) => {
+     *       console.error('Effect failed:', error);
+     *       showErrorNotification(error);
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    onError?: (error: unknown) => void;
+}
+export interface AtomirxMeta {
+}
+export interface EffectMeta extends AtomirxMeta {
     key?: string;
-    /** Error handler for uncaught errors in the effect */
-    onError?: (error: Error) => void;
 }
 /**
  * A function that returns a value when called.
@@ -269,11 +362,3 @@ 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/withReady.d.ts

@@ -0,0 +1,115 @@
+import { SelectContext } from './select';
+import { Atom } from './types';
+/**
+ * Extension interface that adds `ready()` method to SelectContext.
+ * Used in derived atoms and effects to wait for non-null values.
+ */
+export interface WithReadySelectContext {
+    /**
+     * Wait for an atom to have a non-null/non-undefined value.
+     *
+     * If the value is null/undefined, the computation suspends until the atom
+     * changes to a non-null value, then automatically resumes.
+     *
+     * **IMPORTANT: Only use in `derived()` or `effect()` context**
+     *
+     * @param atom - The atom to read and wait for
+     * @returns The non-null value (type excludes null | undefined)
+     *
+     * @example
+     * ```ts
+     * // Wait for currentArticleId to be set before computing
+     * const currentArticle$ = derived(({ ready, read }) => {
+     *   const id = ready(currentArticleId$); // Suspends if null
+     *   const cache = read(articleCache$);
+     *   return cache[id];
+     * });
+     * ```
+     */
+    ready<T>(atom: Atom<T>): T extends PromiseLike<any> ? never : Exclude<T, null | undefined>;
+    /**
+     * Wait for a selected value from an atom to be non-null/non-undefined.
+     *
+     * If the selected value is null/undefined, the computation suspends until the
+     * selected value changes to a non-null value, then automatically resumes.
+     *
+     * **IMPORTANT: Only use in `derived()` or `effect()` context**
+     *
+     * @param atom - The atom to read
+     * @param selector - Function to extract/transform the value
+     * @returns The non-null selected value
+     *
+     * @example
+     * ```ts
+     * // Wait for user's email to be set
+     * const emailDerived$ = derived(({ ready }) => {
+     *   const email = ready(user$, u => u.email); // Suspends if email is null
+     *   return `Contact: ${email}`;
+     * });
+     * ```
+     */
+    ready<T, R>(atom: Atom<T>, selector: (current: Awaited<T>) => R): R extends PromiseLike<any> ? never : Exclude<R, null | undefined>;
+    /**
+     * Execute a function and wait for its result to be non-null/non-undefined.
+     *
+     * If the function returns null/undefined, the computation suspends until
+     * re-executed with a non-null result.
+     *
+     * **IMPORTANT: Only use in `derived()` or `effect()` context**
+     *
+     * **NOTE:** This overload is designed for use with async combinators like
+     * `all()`, `race()`, `any()`, `settled()` where promises come from stable
+     * atom sources. It does NOT support dynamic promise creation (returning a
+     * new Promise from the callback). For async selectors that return promises,
+     * use `ready(atom$, selector?)` instead.
+     *
+     * @param fn - Synchronous function to execute and wait for
+     * @returns The non-null result (excludes null | undefined)
+     * @throws {Error} If the callback returns a Promise
+     *
+     * @example
+     * ```ts
+     * // Wait for a computed value to be ready
+     * const result$ = derived(({ ready, read }) => {
+     *   const value = ready(() => computeExpensiveValue(read(input$)));
+     *   return `Result: ${value}`;
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Use with async combinators (all, race, any, settled)
+     * const combined$ = derived(({ ready, all }) => {
+     *   const [user, posts] = ready(() => all(user$, posts$));
+     *   return { user, posts };
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // For async selectors, use ready(atom$, selector?) instead:
+     * const data$ = derived(({ ready }) => {
+     *   const data = ready(source$, (val) => fetchData(val.id));
+     *   return data;
+     * });
+     * ```
+     */
+    ready<T>(fn: () => T): T extends PromiseLike<any> ? never : Exclude<Awaited<T>, null | undefined>;
+}
+/**
+ * Plugin that adds `ready()` method to a SelectContext.
+ *
+ * `ready()` enables a "reactive suspension" pattern where derived atoms
+ * wait for required values before computing. This is useful for:
+ *
+ * - Route-based entity loading (`/article/:id` - wait for ID to be set)
+ * - Authentication-gated content (wait for user to be logged in)
+ * - Conditional data dependencies (wait for prerequisite data)
+ *
+ * @example
+ * ```ts
+ * // Used internally by derived() - you don't need to call this directly
+ * const result = select((context) => fn(context.use(withReady())));
+ * ```
+ */
+export declare function withReady(): <TContext extends SelectContext>(context: TContext) => TContext & WithReadySelectContext;

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

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