atomirx 0.0.7 → 0.1.0

package/v2.md

@@ -1,725 +0,0 @@
-# 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
-
-### useSelector
-
-```typescript
-function useSelector<T>(atom: Atom<T>): Awaited<T>;
-function useSelector<T>(
-  selector: (ctx: SelectContext) => T,
-  equals?: Equality<Awaited<T>>
-): Awaited<T>;
-```
-
-### Example
-
-```typescript
-// With DerivedAtom (Suspense handles loading)
-function PostCount() {
-  const count = useSelector(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
-useSelector(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 |
-| `useSelector(atom)` with Suspense | `useSelector(derived)` with Suspense          |