atomirx 0.0.1

package/v2.md

@@ -0,0 +1,725 @@
+# atomirx v2 - Design Specification
+
+## Philosophy
+
+```
+Atom        = Base interface (value + subscribe)
+MutableAtom = Atom + set/reset (raw storage)
+DerivedAtom = Atom<Promise<T>> + refresh + state() (computed, always async)
+            = DerivedAtom<T, false> without fallback (staleValue: T | undefined)
+            = DerivedAtom<T, true>  with fallback    (staleValue: T, guaranteed)
+```
+
+---
+
+## Type Hierarchy
+
+```
+Atom<T>
+  │
+  ├─► MutableAtom<T> = Atom<T> & { set(), reset() }
+  │     Created by: atom(value)
+  │
+  └─► DerivedAtom<T, F> = Atom<Promise<T>> & { refresh(), state(), staleValue }
+        │
+        ├─► DerivedAtom<T, false>  (staleValue: T | undefined)
+        │     Created by: derived(compute)
+        │
+        └─► DerivedAtom<T, true>   (staleValue: T, guaranteed)
+              Created by: derived(compute, { fallback })
+```
+
+---
+
+## Base Interface
+
+```typescript
+interface AtomMeta {
+  key: string | undefined;
+}
+
+interface Atom<T> {
+  readonly value: T;
+  readonly meta?: AtomMeta;
+  on(listener: () => void): () => void;
+}
+```
+
+---
+
+## MutableAtom
+
+Simple, raw value container. Can store anything including Promises.
+
+### API
+
+```typescript
+function atom<T>(initialValue: T, options?: AtomOptions): MutableAtom<T>;
+
+interface AtomOptions<T> {
+  meta?: AtomMeta;
+  equals?: EqualsFn<T>;
+}
+
+interface MutableAtom<T> extends Atom<T> {
+  set(value: T | ((prev: T) => T)): void; // throws sync errors
+  reset(): void; // restore initial value
+}
+```
+
+### Behavior
+
+| Operation       | Behavior                                  |
+| --------------- | ----------------------------------------- |
+| `.value`        | Returns raw value (T, including Promise)  |
+| `.set(value)`   | Stores value, notifies                    |
+| `.set(reducer)` | Applies reducer, throws if reducer throws |
+| `.reset()`      | Restores initial value                    |
+
+### Examples
+
+```typescript
+// Sync
+const count$ = atom(0);
+count$.value; // 0
+count$.set(1); // stores 1
+count$.set((n) => n + 1); // stores 2
+
+// Async (stores raw Promise)
+const posts$ = atom(fetchPosts());
+posts$.value; // Promise<Post[]>
+
+// Refetch - must call set() with new Promise
+posts$.set(fetchPosts()); // stores new Promise
+
+// Reset - restores initial Promise (does NOT refetch)
+posts$.reset(); // restores original Promise object
+```
+
+---
+
+## DerivedAtom
+
+Computed value. Always returns `Promise<T>` for `.value`.
+
+### API
+
+```typescript
+// Without fallback - staleValue is T | undefined
+function derived<T>(
+  compute: (ctx: SelectContext) => T,
+  options?: DerivedOptions,
+): DerivedAtom<T, false>;
+
+// With fallback - staleValue is guaranteed T
+function derived<T>(
+  compute: (ctx: SelectContext) => T,
+  options: DerivedOptions & { fallback: T },
+): DerivedAtom<T, true>;
+
+interface DerivedOptions<T> {
+  meta?: AtomMeta;
+  equals?: EqualsFn<T>;
+  fallback?: T; // When provided, staleValue is guaranteed T
+}
+
+interface DerivedAtom<T, F extends boolean = false> extends Atom<Promise<T>> {
+  refresh(): void; // re-run computation
+  state(): AtomState<T>; // get current state (ready/error/loading)
+  readonly staleValue: F extends true ? T : T | undefined; // fallback or last resolved value
+}
+```
+
+### SelectContext
+
+```typescript
+type AnyAtom<T> = MutableAtom<T> | DerivedAtom<T>;
+type AtomValue<A> = A extends AnyAtom<infer V> ? Awaited<V> : never;
+
+type SettledResult<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown };
+
+interface SelectContext {
+  // Single atom
+  get<V>(atom: AnyAtom<V>): Awaited<V>;
+
+  // Multiple atoms - parallel
+  all<A extends AnyAtom<unknown>[]>(
+    ...atoms: A
+  ): { [K in keyof A]: AtomValue<A[K]> };
+  race<A extends AnyAtom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+  any<A extends AnyAtom<unknown>[]>(...atoms: A): AtomValue<A[number]>;
+  settled<A extends AnyAtom<unknown>[]>(
+    ...atoms: A
+  ): { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
+}
+```
+
+### getAtomState()
+
+Returns the current state of an atom as a discriminated union.
+
+```ts
+type AtomState<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown }
+  | { status: "loading"; promise: Promise<T> };
+
+function getAtomState<T>(atom: Atom<T>): AtomState<T> {
+  // For derived atoms, use their own state method
+  if (isDerived(atom)) {
+    return atom.state();
+  }
+
+  const value = atom.value;
+
+  // 1. Sync value - ready
+  if (!isPromiseLike(value)) {
+    return {
+      status: "ready",
+      value: value,
+    };
+  }
+
+  // 2. Promise value - check state via promiseCache
+  const state = trackPromise(value);
+
+  switch (state.status) {
+    case "fulfilled":
+      return {
+        status: "ready",
+        value: state.value,
+      };
+
+    case "rejected":
+      return {
+        status: "error",
+        error: state.error,
+      };
+
+    case "pending":
+      return {
+        status: "loading",
+        promise: state.promise,
+      };
+  }
+}
+```
+
+**Usage:**
+
+```ts
+const state = getAtomState(myAtom$);
+
+switch (state.status) {
+  case "ready":
+    console.log(state.value); // T
+    break;
+  case "error":
+    console.log(state.error); // unknown
+    break;
+  case "loading":
+    console.log(state.promise); // Promise<T>
+    break;
+}
+
+// For derived atoms with fallback, use staleValue during loading:
+if (state.status === "loading") {
+  console.log("Using stale/fallback:", derived$.staleValue);
+}
+```
+
+### get() Behavior
+
+The `get()` function resolves atom values using `getAtomState()`:
+
+```typescript
+function get<T>(atom: AnyAtom<T>): Awaited<T> {
+  const state = getAtomState(atom);
+
+  switch (state.status) {
+    case "ready":
+      return state.value;
+    case "error":
+      throw state.error;
+    case "loading":
+      throw state.promise; // Suspense pattern
+  }
+}
+```
+
+**Summary:**
+
+| State   | Result                   |
+| ------- | ------------------------ |
+| ready   | return value             |
+| error   | throw error              |
+| loading | throw Promise (Suspense) |
+
+> **Note:** For derived atoms with fallback, use `staleValue` directly to access
+> the fallback/cached value during loading without triggering Suspense.
+
+### all() Behavior
+
+Like `Promise.all` - waits for all atoms, returns array of values.
+
+```typescript
+function all<A extends AnyAtom<unknown>[]>(...atoms: A): AwaitedAll<A> {
+  const results: unknown[] = [];
+  let loadingPromise: Promise<unknown> | null = null;
+
+  for (const atom of atoms) {
+    const state = getAtomState(atom);
+
+    switch (state.status) {
+      case "ready":
+        results.push(state.value);
+        break;
+
+      case "error":
+        // Any error → throw immediately
+        throw state.error;
+
+      case "loading":
+        // First loading → will throw
+        if (!loadingPromise) {
+          loadingPromise = state.promise;
+        }
+        break;
+    }
+  }
+
+  // If any loading → throw Promise
+  if (loadingPromise) {
+    throw loadingPromise;
+  }
+
+  return results as AwaitedAll<A>;
+}
+```
+
+| Scenario    | Result                         |
+| ----------- | ------------------------------ |
+| All ready   | return `[value1, value2, ...]` |
+| Any error   | throw first error              |
+| Any loading | throw Promise                  |
+
+### race() Behavior
+
+Like `Promise.race` - returns first settled value (ready or error).
+
+```typescript
+function race<A extends AnyAtom<unknown>[]>(...atoms: A): AtomValue<A[number]> {
+  let firstLoadingPromise: Promise<unknown> | null = null;
+
+  for (const atom of atoms) {
+    const state = getAtomState(atom);
+
+    switch (state.status) {
+      case "ready":
+        return state.value as AtomValue<A[number]>;
+
+      case "error":
+        throw state.error;
+
+      case "loading":
+        if (!firstLoadingPromise) {
+          firstLoadingPromise = state.promise;
+        }
+        break;
+    }
+  }
+
+  // All loading → throw first Promise
+  if (firstLoadingPromise) {
+    throw firstLoadingPromise;
+  }
+
+  throw new Error("race() called with no atoms");
+}
+```
+
+| Scenario       | Result                  |
+| -------------- | ----------------------- |
+| Any sync value | return first sync value |
+| Any ready      | return first value      |
+| Any error      | throw first error       |
+| All loading    | throw first Promise     |
+
+> **Note:** `race()` does NOT use fallback - it's meant to return the first "real" settled value.
+
+### any() Behavior
+
+Like `Promise.any` - returns first ready, ignores errors unless all error.
+
+```typescript
+function any<A extends AnyAtom<unknown>[]>(...atoms: A): AtomValue<A[number]> {
+  const errors: unknown[] = [];
+  let firstLoadingPromise: Promise<unknown> | null = null;
+
+  for (const atom of atoms) {
+    const state = getAtomState(atom);
+
+    switch (state.status) {
+      case "ready":
+        return state.value as AtomValue<A[number]>;
+
+      case "error":
+        errors.push(state.error);
+        break;
+
+      case "loading":
+        if (!firstLoadingPromise) {
+          firstLoadingPromise = state.promise;
+        }
+        break;
+    }
+  }
+
+  // If any loading → throw Promise (might still succeed)
+  if (firstLoadingPromise) {
+    throw firstLoadingPromise;
+  }
+
+  // All errored → throw AggregateError
+  throw new AggregateError(errors, "All atoms rejected");
+}
+```
+
+| Scenario       | Result                              |
+| -------------- | ----------------------------------- |
+| Any sync value | return first sync value             |
+| Any ready      | return first value                  |
+| Any loading    | throw Promise (wait for potential)  |
+| All errored    | throw `AggregateError`              |
+
+> **Note:** `any()` does NOT use fallback - it waits for a real ready value.
+
+### settled() Behavior
+
+Like `Promise.allSettled` - returns status of all atoms.
+
+```typescript
+function settled<A extends AnyAtom<unknown>[]>(
+  ...atoms: A
+): { [K in keyof A]: SettledResult<AtomValue<A[K]>> } {
+  const results: SettledResult<unknown>[] = [];
+  let loadingPromise: Promise<unknown> | null = null;
+
+  for (const atom of atoms) {
+    const state = getAtomState(atom);
+
+    switch (state.status) {
+      case "ready":
+        results.push({ status: "ready", value: state.value });
+        break;
+
+      case "error":
+        results.push({ status: "error", error: state.error });
+        break;
+
+      case "loading":
+        // Loading → will throw
+        if (!loadingPromise) {
+          loadingPromise = state.promise;
+        }
+        break;
+    }
+  }
+
+  // If any loading → throw Promise
+  if (loadingPromise) {
+    throw loadingPromise;
+  }
+
+  return results as { [K in keyof A]: SettledResult<AtomValue<A[K]>> };
+}
+```
+
+| Scenario    | Result                                   |
+| ----------- | ---------------------------------------- |
+| All settled | return `[{ status, value/error }, ...]`  |
+| Any loading | throw Promise                            |
+
+### SelectContext Summary
+
+All methods use `getAtomState()` internally.
+
+| Method              | Returns         | Throws on Error?   |
+| ------------------- | --------------- | ------------------ |
+| `get(atom)`         | Single value    | Yes                |
+| `all(...atoms)`     | Array of values | Yes (first error)  |
+| `race(...atoms)`    | First settled   | Yes (if first)     |
+| `any(...atoms)`     | First ready     | Only if all error  |
+| `settled(...atoms)` | Array of status | No                 |
+
+> **Note:** `race()` and `any()` are typically used with `MutableAtom<Promise<T>>` for racing data sources.
+
+### Behavior
+
+**Without fallback (`DerivedAtom<T, false>`):**
+
+| State    | `.value`             | `.staleValue`            | `.state().status` |
+| -------- | -------------------- | ------------------------ | ----------------- |
+| Loading  | `Promise` (pending)  | `undefined`              | `"loading"`       |
+| Resolved | `Promise` (resolved) | resolved value           | `"ready"`         |
+| Error    | `Promise` (rejected) | last value / `undefined` | `"error"`         |
+
+**With fallback (`DerivedAtom<T, true>`):**
+
+| State    | `.value`             | `.staleValue`       | `.state().status` |
+| -------- | -------------------- | ------------------- | ----------------- |
+| Loading  | `Promise` (pending)  | fallback            | `"loading"`       |
+| Resolved | `Promise` (resolved) | resolved value      | `"ready"`         |
+| Error    | `Promise` (rejected) | last value/fallback | `"error"`         |
+
+> **Note:** Use `state().status === "loading"` or `isPending(derived$.value)` to check loading state.
+
+### Examples
+
+```typescript
+// Basic derived (no fallback) - DerivedAtom<number, false>
+const count$ = atom(0);
+const double$ = derived(({ get }) => get(count$) * 2);
+await double$.value; // 0
+double$.staleValue; // undefined (during loading) → 0 (after)
+double$.state(); // { status: "ready", value: 0 }
+
+// Async derived (no fallback) - DerivedAtom<number, false>
+const posts$ = atom(fetchPosts());
+const postCount$ = derived(({ get }) => get(posts$).length);
+await postCount$.value; // 42 (after loading)
+postCount$.staleValue; // undefined (during loading) → 42 (after)
+postCount$.state(); // { status: "loading", promise } → { status: "ready", value: 42 }
+
+// With fallback - DerivedAtom<number, true>
+const postCountWithFallback$ = derived(({ get }) => get(posts$).length, {
+  fallback: 0,
+});
+await postCountWithFallback$.value; // 42
+postCountWithFallback$.staleValue; // 0 (during loading, guaranteed) → 42 (after)
+postCountWithFallback$.state(); // { status: "loading", promise } → { status: "ready", value: 42 }
+
+// Check loading state
+postCount$.state().status === "loading"; // true while loading
+isPending(postCount$.value); // alternative: true while loading
+
+// Multiple deps
+const combined$ = derived(({ get, all }) => {
+  const [posts, user] = all(posts$, user$);
+  return posts.filter((p) => p.authorId === user.id);
+});
+
+// Refresh - re-run computation
+postCount$.refresh();
+
+// Error handling
+try {
+  const count = await postCount$.value;
+} catch (e) {
+  console.error("Failed:", e);
+}
+// Or check state
+const state = postCount$.state();
+if (state.status === "error") {
+  console.error("Failed:", state.error);
+}
+```
+
+---
+
+## Effect
+
+Side effect runner with same get() semantics.
+
+### API
+
+```typescript
+interface EffectContext extends SelectContext {
+  onCleanup: (cleanup: VoidFunction) => void;
+  onError: (handler: (error: unknown) => void) => void;
+}
+
+function effect(
+  fn: (ctx: EffectContext) => void,
+  options?: EffectOptions,
+): () => void;
+
+interface EffectOptions {
+  key?: string;
+  onError?: (error: Error) => void; // For unhandled errors
+}
+```
+
+### Behavior
+
+- Runs when dependencies change
+- `get()` works same as in derived (throws Promise/Error)
+- If throws Promise → re-runs when Promise resolves
+- If throws Error → calls registered `onError` handlers, or `options.onError` if none registered
+- Use `onCleanup()` to register cleanup functions
+
+### Example
+
+```typescript
+// With cleanup
+const dispose = effect(({ get, onCleanup }) => {
+  const interval = get(intervalAtom);
+  const id = setInterval(() => console.log("tick"), interval);
+  onCleanup(() => clearInterval(id));
+});
+
+// With error handling (callback-based)
+const dispose = effect(({ get, onError }) => {
+  onError((e) => console.error("Effect failed:", e));
+  const posts = get(posts$);
+  console.log("Posts loaded:", posts.length);
+});
+
+// With error handling (option-based for unhandled errors)
+const dispose = effect(
+  ({ get }) => {
+    const posts = get(posts$);
+    riskyOperation(posts);
+  },
+  {
+    onError: (e) => console.error("Unhandled error:", e),
+  },
+);
+```
+
+---
+
+## React Hooks
+
+### useValue
+
+```typescript
+function useValue<T>(atom: Atom<T>): Awaited<T>;
+function useValue<T>(
+  selector: (ctx: SelectContext) => T,
+  equals?: Equality<Awaited<T>>,
+): Awaited<T>;
+```
+
+### Example
+
+```typescript
+// With DerivedAtom (Suspense handles loading)
+function PostCount() {
+  const count = useValue(postCount$); // number (awaited)
+  return <div>Count: {count}</div>;
+}
+
+// Usage with Suspense + ErrorBoundary
+<ErrorBoundary fallback={<Error />}>
+  <Suspense fallback={<Loading />}>
+    <PostCount />
+  </Suspense>
+</ErrorBoundary>
+
+// With fallback - staleValue is guaranteed T
+function PostCountWithFallback() {
+  const count = postCountWithFallback$.staleValue; // always number
+  const isLoading = isPending(postCountWithFallback$.value);
+
+  return (
+    <div>
+      {isLoading && <Spinner />}
+      Count: {count}
+    </div>
+  );
+}
+
+// Without fallback - staleValue is T | undefined
+function PostCountNoFallback() {
+  const count = postCount$.staleValue; // number | undefined
+  const isLoading = isPending(postCount$.value);
+
+  return (
+    <div>
+      {isLoading && <Spinner />}
+      Count: {count ?? "Loading..."}
+    </div>
+  );
+}
+```
+
+---
+
+## Promise State Cache
+
+Internal mechanism for tracking Promise states.
+
+```typescript
+// Internal - not exposed
+type PromiseState<T> =
+  | { status: "pending"; promise: Promise<T> }
+  | { status: "fulfilled"; value: T }
+  | { status: "rejected"; error: unknown };
+
+const promiseCache = new WeakMap<Promise<any>, PromiseState<any>>();
+```
+
+---
+
+## Type Utilities
+
+```typescript
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+
+type AwaitedAll<T extends unknown[]> = {
+  [K in keyof T]: Awaited<T[K]>;
+};
+
+type EqualsFn<T> = (a: T, b: T) => boolean;
+```
+
+---
+
+## Complete API Surface
+
+```typescript
+// Core
+atom<T>(initial, options?): MutableAtom<T>
+derived<T>(compute, options?): DerivedAtom<T, false>
+derived<T>(compute, { fallback }): DerivedAtom<T, true>
+effect(fn, options?): () => void
+
+// React
+useValue(source): T | Awaited<T>
+
+// Types
+Atom<T>
+MutableAtom<T>
+DerivedAtom<T, F>  // F = false (no fallback) | true (with fallback)
+SelectContext
+```
+
+---
+
+## Summary Table
+
+|                  | MutableAtom | DerivedAtom         | DerivedAtom with fallback |
+| ---------------- | ----------- | ------------------- | ------------------------- |
+| Purpose          | Raw storage | Computed (async)    | Computed + sync access    |
+| `.value`         | `T` (raw)   | `Promise<T>`        | `Promise<T>`              |
+| `.staleValue`    | ❌          | ✅ `T \| undefined` | ✅ `T`                    |
+| `.state()`       | ❌          | ✅ `AtomState<T>`   | ✅ `AtomState<T>`         |
+| `.set()`         | ✅          | ❌                  | ❌                        |
+| `.reset()`       | ✅          | ❌                  | ❌                        |
+| `.refresh()`     | ❌          | ✅                  | ✅                        |
+| `.on()`          | ✅          | ✅                  | ✅                        |
+
+---
+
+## Migration from v1
+
+| v1                             | v2                                            |
+| ------------------------------ | --------------------------------------------- |
+| `atom(promise, { fallback })`  | `atom(promise)` (no fallback on atom)         |
+| `atom.loading`                 | `isPending(derived$.value)` from promiseCache |
+| `atom.error`                   | `await derived.value` throws                  |
+| `atom.stale()`                 | `isPending(derived$.value)` from promiseCache |
+| `useValue(atom)` with Suspense | `useValue(derived)` with Suspense             |