atomirx 0.0.8 → 0.1.1

package/src/core/withReady.ts

@@ -1,191 +0,0 @@
-import { isPromiseLike } from "./isPromiseLike";
-import { trackPromise } from "./promiseCache";
-import { SelectContext } from "./select";
-import { AnyFunc, 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>;
-}
-
-/**
- * Internal helper that suspends computation if value is null/undefined.
- */
-function waitForValue<T>(value: T): any {
-  if (value === undefined || value === null) {
-    throw new Promise(() => {});
-  }
-
-  // Handle async selectors: when the selector returns a Promise,
-  // we track its state and handle suspension/resolution accordingly
-  if (isPromiseLike(value)) {
-    const p = trackPromise(value);
-
-    // Promise is still pending - suspend computation by throwing
-    // the tracked promise. This enables React Suspense integration.
-    if (p.status === "pending") {
-      throw p.promise;
-    }
-
-    // Promise resolved successfully - return the resolved value.
-    // Note: This bypasses null/undefined checking for async results,
-    // allowing async selectors to return any value including null.
-    if (p.status === "fulfilled") {
-      return p.value;
-    }
-
-    // Promise rejected - propagate the error
-    throw p.error;
-  }
-
-  // For sync values (no selector, or selector returned sync value),
-  // check for null/undefined and suspend if not ready
-
-  return value as Exclude<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 function withReady() {
-  return <TContext extends SelectContext>(
-    context: TContext
-  ): TContext & WithReadySelectContext => {
-    return {
-      ...context,
-      ready: (
-        atomOrFn: Atom<any> | AnyFunc,
-        selector?: (current: any) => any
-      ): any => {
-        if (typeof atomOrFn === "function") {
-          const value = atomOrFn();
-          if (isPromiseLike(value)) {
-            throw new Error(
-              "ready(callback) overload does not support async callbacks. Use ready(atom, selector?) instead."
-            );
-          }
-          return waitForValue(value);
-        }
-        const value = context.read(atomOrFn);
-        // we allow selector to return a promise, and wait for that promise if it is not resolved yet
-        const selected = selector ? selector(value) : value;
-
-        return waitForValue(selected);
-      },
-    };
-  };
-}

package/src/core/withUse.test.ts

@@ -1,249 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { withUse } from "./withUse";
-
-describe("withUse", () => {
-  describe("basic functionality", () => {
-    it("should add use method to object", () => {
-      const obj = { value: 1 };
-      const result = withUse(obj);
-
-      expect(result.value).toBe(1);
-      expect(typeof result.use).toBe("function");
-    });
-
-    it("should preserve original object properties", () => {
-      const obj = { a: 1, b: "hello", c: true };
-      const result = withUse(obj);
-
-      expect(result.a).toBe(1);
-      expect(result.b).toBe("hello");
-      expect(result.c).toBe(true);
-    });
-
-    it("should work with arrays", () => {
-      const arr = [1, 2, 3];
-      const result = withUse(arr);
-
-      expect(result[0]).toBe(1);
-      expect(result.length).toBe(3);
-      expect(typeof result.use).toBe("function");
-    });
-  });
-
-  describe("use() transformations", () => {
-    it("should transform object with plugin", () => {
-      const obj = withUse({ value: 10 });
-
-      const transformed = obj.use((source) => ({
-        ...source,
-        doubled: source.value * 2,
-      }));
-
-      expect(transformed.value).toBe(10);
-      expect(transformed.doubled).toBe(20);
-    });
-
-    it("should return source when plugin returns void", () => {
-      const obj = withUse({ value: 1 });
-      const sideEffect = vi.fn();
-
-      const result = obj.use((source) => {
-        sideEffect(source.value);
-      });
-
-      expect(sideEffect).toHaveBeenCalledWith(1);
-      expect(result).toBe(obj);
-    });
-
-    it("should return source when plugin returns undefined", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => undefined);
-
-      expect(result).toBe(obj);
-    });
-
-    it("should return source when plugin returns null", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => null as any);
-
-      expect(result).toBe(obj);
-    });
-
-    it("should return source when plugin returns false", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => false as any);
-
-      expect(result).toBe(obj);
-    });
-
-    it("should return source when plugin returns empty string", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => "" as any);
-
-      expect(result).toBe(obj);
-    });
-
-    it("should return source when plugin returns 0", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => 0 as any);
-
-      expect(result).toBe(obj);
-    });
-  });
-
-  describe("chaining", () => {
-    it("should allow chaining by wrapping result with use method", () => {
-      const obj = withUse({ value: 1 });
-
-      // First transformation - result gets wrapped with use()
-      const withA = obj.use((source) => ({ ...source, a: "first" }));
-      expect(withA.value).toBe(1);
-      expect(withA.a).toBe("first");
-      expect(typeof withA.use).toBe("function");
-    });
-
-    it("should pass the transformed object to the next use() in chain", () => {
-      const obj = withUse({ value: 1 });
-
-      // When chaining, each use() receives the result of the previous transformation
-      const result = obj
-        .use((source) => ({ original: source.value, a: "first" }))
-        .use((source) => ({ ...source, b: "second" }));
-
-      expect(result.original).toBe(1);
-      expect(result.a).toBe("first");
-      expect(result.b).toBe("second");
-    });
-
-    it("should wrap result with withUse if it does not have use method", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => ({ newProp: "test" }));
-
-      expect(result.newProp).toBe("test");
-      expect(typeof result.use).toBe("function");
-    });
-
-    it("should return as-is if result already has use method", () => {
-      const obj = withUse({ value: 1 });
-      const existingWithUse = withUse({ other: 2 });
-
-      const result = obj.use(() => existingWithUse);
-
-      expect(result).toBe(existingWithUse);
-    });
-
-    it("should allow fluent chaining with independent transformations", () => {
-      const obj = withUse({ value: 1 });
-
-      // Each use() receives the result of the previous use()
-      const result = obj
-        .use((source) => ({ value: source.value, doubled: source.value * 2 }))
-        .use((source) => ({ ...source, tripled: source.value * 3 }));
-
-      expect(result.value).toBe(1);
-      expect(result.doubled).toBe(2);
-      expect(result.tripled).toBe(3);
-    });
-  });
-
-  describe("primitive return values", () => {
-    it("should return primitive number directly", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => 42);
-
-      expect(result).toBe(42);
-    });
-
-    it("should return primitive string directly", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => "hello");
-
-      expect(result).toBe("hello");
-    });
-
-    it("should return primitive boolean directly", () => {
-      const obj = withUse({ value: 1 });
-
-      const result = obj.use(() => true);
-
-      expect(result).toBe(true);
-    });
-  });
-
-  describe("function return values", () => {
-    it("should wrap function result with withUse if no use method", () => {
-      const obj = withUse({ value: 1 });
-      const fn = () => 42;
-
-      const result = obj.use(() => fn);
-
-      expect(result()).toBe(42);
-      expect(typeof result.use).toBe("function");
-    });
-
-    it("should return function as-is if it has use method", () => {
-      const obj = withUse({ value: 1 });
-      const fnWithUse = Object.assign(() => 42, { use: () => {} });
-
-      const result = obj.use(() => fnWithUse);
-
-      expect(result).toBe(fnWithUse);
-    });
-  });
-
-  describe("real-world patterns", () => {
-    it("should support adding methods to an object", () => {
-      const counter = withUse({ count: 0 });
-
-      const enhanced = counter.use((source) => ({
-        ...source,
-        increment: () => {
-          source.count++;
-        },
-        decrement: () => {
-          source.count--;
-        },
-      }));
-
-      enhanced.increment();
-      expect(counter.count).toBe(1);
-
-      enhanced.decrement();
-      expect(counter.count).toBe(0);
-    });
-
-    it("should support middleware-like pattern", () => {
-      const logger: string[] = [];
-
-      const api = withUse({
-        fetch: (url: string) => `data from ${url}`,
-      });
-
-      const withLogging = api.use((source) => ({
-        ...source,
-        fetch: (url: string) => {
-          logger.push(`fetching: ${url}`);
-          const result = source.fetch(url);
-          logger.push(`fetched: ${result}`);
-          return result;
-        },
-      }));
-
-      const result = withLogging.fetch("/api/users");
-
-      expect(result).toBe("data from /api/users");
-      expect(logger).toEqual([
-        "fetching: /api/users",
-        "fetched: data from /api/users",
-      ]);
-    });
-  });
-});

package/src/core/withUse.ts

@@ -1,56 +0,0 @@
-import type { Pipeable } from "./types";
-
-/**
- * Adds a chainable `.use()` method to any object, enabling plugin-based transformations.
- *
- * The `.use()` method accepts a plugin function that receives the source object
- * and can return a transformed version. Supports several return patterns:
- *
- * - **Void/falsy**: Returns the original source unchanged (side-effect only plugins)
- * - **Object/function with `.use`**: Returns as-is (already chainable)
- * - **Object/function without `.use`**: Wraps with `withUse()` for continued chaining
- * - **Primitive**: Returns the value directly
- *
- * @template TSource - The type of the source object being enhanced
- * @param source - The object to add `.use()` method to
- * @returns The source object with `.use()` method attached
- *
- * @example
- * // Basic usage with atom tuple
- * const mappable = withUse([signal, setter]);
- * const transformed = mappable.use(([sig, set]) => ({
- *   sig,
- *   set: (v: string) => set(Number(v))
- * }));
- *
- * @example
- * // Chaining multiple transformations
- * atom(0)
- *   .use(([sig, set]) => [sig, (v: number) => set(v * 2)])
- *   .use(([sig, set]) => [sig, (v: number) => set(v + 1)]);
- *
- * @example
- * // Side-effect only plugin (returns void)
- * mappable.use((source) => {
- *   console.log('Source:', source);
- *   // returns undefined - original source is returned
- * });
- */
-export function withUse<TSource extends object>(source: TSource) {
-  return Object.assign(source, {
-    use<TNew = void>(plugin: (source: NoInfer<TSource>) => TNew): any {
-      const result = plugin(source);
-      // Void/falsy: return original source (side-effect only plugins)
-      if (!result) return source;
-      // Object or function: check if already has .use(), otherwise wrap
-      if (typeof result === "object" || typeof result === "function") {
-        if ("use" in result) {
-          return result;
-        }
-        return withUse(result);
-      }
-      // Primitive values: return directly (not chainable)
-      return result;
-    },
-  }) as TSource & Pipeable;
-}

package/src/index.test.ts

@@ -1,80 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  atom,
-  batch,
-  define,
-  derived,
-  effect,
-  emitter,
-  isAtom,
-  isDerived,
-  select,
-  getAtomState,
-  isPending,
-} from "./index";
-
-describe("atomirx exports", () => {
-  it("should export atom", () => {
-    expect(typeof atom).toBe("function");
-    const count = atom(0);
-    expect(count.get()).toBe(0);
-  });
-
-  it("should export batch", () => {
-    expect(typeof batch).toBe("function");
-  });
-
-  it("should export define", () => {
-    expect(typeof define).toBe("function");
-  });
-
-  it("should export derived", async () => {
-    expect(typeof derived).toBe("function");
-    const count = atom(5);
-    const doubled = derived(({ read }) => read(count) * 2);
-    expect(await doubled.get()).toBe(10);
-  });
-
-  it("should export effect", () => {
-    expect(typeof effect).toBe("function");
-  });
-
-  it("should export emitter", () => {
-    expect(typeof emitter).toBe("function");
-  });
-
-  it("should export isAtom", () => {
-    expect(typeof isAtom).toBe("function");
-    const count = atom(0);
-    expect(isAtom(count)).toBe(true);
-    expect(isAtom({})).toBe(false);
-  });
-
-  it("should export isDerived", () => {
-    expect(typeof isDerived).toBe("function");
-    const count = atom(0);
-    const doubled = derived(({ read }) => read(count) * 2);
-    expect(isDerived(count)).toBe(false);
-    expect(isDerived(doubled)).toBe(true);
-  });
-
-  it("should export select", () => {
-    expect(typeof select).toBe("function");
-  });
-
-  it("should export getAtomState", () => {
-    expect(typeof getAtomState).toBe("function");
-    const count = atom(42);
-    const state = getAtomState(count);
-    expect(state.status).toBe("ready");
-    if (state.status === "ready") {
-      expect(state.value).toBe(42);
-    }
-  });
-
-  it("should export isPending", () => {
-    expect(typeof isPending).toBe("function");
-    expect(isPending(42)).toBe(false);
-    expect(isPending(new Promise(() => {}))).toBe(true);
-  });
-});

package/src/index.ts

@@ -1,65 +0,0 @@
-// Core
-export { atom, readonly } from "./core/atom";
-export { batch } from "./core/batch";
-export { define } from "./core/define";
-export { derived, type DerivedContext } from "./core/derived";
-export { effect, type EffectContext } from "./core/effect";
-export { emitter } from "./core/emitter";
-export { isAtom, isDerived } from "./core/isAtom";
-export { select, AllAtomsRejectedError } from "./core/select";
-
-// Promise utilities
-export { getAtomState } from "./core/getAtomState";
-export {
-  isPending,
-  isFulfilled,
-  isRejected,
-  trackPromise,
-  unwrap,
-} from "./core/promiseCache";
-
-// Types
-export type {
-  Atom,
-  AtomMeta,
-  AtomOptions,
-  AtomState,
-  AtomValue,
-  AnyAtom,
-  DerivedAtom,
-  DerivedAtomMeta,
-  DerivedOptions,
-  EffectOptions,
-  Equality,
-  EqualityShorthand,
-  Getter,
-  KeyedResult,
-  MutableAtom,
-  MutableAtomMeta,
-  Pipeable,
-  SelectStateResult,
-  SettledResult,
-} from "./core/types";
-
-export { onCreateHook } from "./core/onCreateHook";
-export type {
-  CreateInfo,
-  MutableInfo,
-  DerivedInfo,
-  EffectInfo,
-  ModuleInfo,
-} from "./core/onCreateHook";
-
-export { onErrorHook } from "./core/onErrorHook";
-export type { ErrorInfo } from "./core/onErrorHook";
-
-export type {
-  SelectContext,
-  SelectResult,
-  ReactiveSelector as ContextSelectorFn,
-  SafeResult,
-} from "./core/select";
-
-export type { PromiseState, CombinedPromiseMeta } from "./core/promiseCache";
-
-export { promisesEqual } from "./core/promiseCache";

package/src/react/index.ts

@@ -1,21 +0,0 @@
-export { useSelector } from "./useSelector";
-export { useStable } from "./useStable";
-export type { UseStableResult } from "./useStable";
-export { useAction } from "./useAction";
-export { rx } from "./rx";
-export type { RxOptions } from "./rx";
-
-export type {
-  ActionState,
-  ActionIdleState,
-  ActionLoadingState,
-  ActionSuccessState,
-  ActionErrorState,
-  ActionStateWithoutIdle,
-  AbortablePromise,
-  UseActionOptions,
-  ActionContext,
-  ActionApi,
-  Action,
-} from "./useAction";
-export * from "../index";