atomirx 0.0.2 → 0.0.5

package/src/core/types.ts

@@ -28,8 +28,8 @@ export const SYMBOL_DERIVED = Symbol.for("atomirx.derived");
  * @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 {
@@ -47,9 +47,8 @@ export interface Pipeable {
 /**
  * Optional metadata for atoms.
  */
-export interface AtomMeta {
+export interface AtomMeta extends AtomirxMeta {
   key?: string;
-  [key: string]: unknown;
 }
 
 /**
@@ -61,10 +60,13 @@ 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
@@ -91,7 +93,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
  * ```
  */
@@ -132,7 +134,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
@@ -141,13 +143,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
  * ```
@@ -199,9 +201,48 @@ export type AtomValue<A> =
  * @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> };
+  | { 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.
@@ -236,16 +277,65 @@ 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;
 }
 
 /**
@@ -297,15 +387,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>;