atomirx 0.0.1

package/src/core/types.ts

@@ -0,0 +1,311 @@
+/**
+ * Generic function type that accepts any arguments and returns any value.
+ * Used internally for type-safe function handling.
+ */
+export type AnyFunc = (...args: any[]) => any;
+
+/**
+ * Unique symbol used to identify atom instances.
+ * Uses Symbol.for() to ensure the same symbol across different module instances.
+ */
+export const SYMBOL_ATOM = Symbol.for("atomirx.atom");
+
+/**
+ * Symbol to identify derived atoms.
+ */
+export const SYMBOL_DERIVED = Symbol.for("atomirx.derived");
+
+/**
+ * Interface for objects that support the `.use()` plugin pattern.
+ *
+ * The `.use()` method enables chainable transformations via plugins.
+ * Return type behavior:
+ * - `void` → returns original source (side-effect only)
+ * - Object with `.use` → returns as-is (already pipeable)
+ * - Object without `.use` → wraps with Pipeable
+ * - Primitive → returns directly (not chainable)
+ *
+ * @example
+ * ```ts
+ * const enhanced = atom(0)
+ *   .use(source => ({ ...source, double: () => source.value * 2 }))
+ *   .use(source => ({ ...source, triple: () => source.value * 3 }));
+ * ```
+ */
+export interface Pipeable {
+  use<TNew = void>(
+    plugin: (source: this) => TNew
+  ): void extends TNew
+    ? this
+    : TNew extends object
+      ? TNew extends { use: any }
+        ? TNew
+        : Pipeable & TNew
+      : TNew;
+}
+
+/**
+ * Optional metadata for atoms.
+ */
+export interface AtomMeta {
+  key?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Base interface for all atoms.
+ * Represents a reactive value container with subscription capability.
+ *
+ * @template T - The type of value stored in the atom
+ */
+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;
+  /**
+   * Subscribe to value changes.
+   * @param listener - Callback invoked when value changes
+   * @returns Unsubscribe function
+   */
+  on(listener: VoidFunction): VoidFunction;
+}
+
+/**
+ * A mutable atom that can be updated via `set()` and reset to initial state.
+ *
+ * MutableAtom is a raw storage container. It stores values as-is, including Promises.
+ * Unlike DerivedAtom, it does not automatically unwrap or track Promise states.
+ *
+ * @template T - The type of value stored in the atom
+ *
+ * @example
+ * ```ts
+ * // Sync value
+ * const count = atom(0);
+ * count.set(5);           // Direct value
+ * count.set(n => n + 1);  // Reducer function
+ * count.reset();          // Back to 0
+ *
+ * // Async value (stores Promise as-is)
+ * const posts = atom(fetchPosts());
+ * posts.value; // Promise<Post[]>
+ * posts.set(fetchPosts()); // Store new Promise
+ * ```
+ */
+export interface MutableAtom<T> extends Atom<T>, Pipeable {
+  /** Reset atom to its initial state (also clears dirty flag) */
+  reset(): void;
+  /**
+   * Update the atom's value.
+   *
+   * @param value - New value or reducer function (prev) => newValue
+   */
+  set(value: T | ((prev: T) => T)): void;
+  /**
+   * Returns `true` if the value has changed since initialization or last `reset()`.
+   *
+   * Useful for:
+   * - Tracking unsaved changes
+   * - Enabling/disabling save buttons
+   * - Detecting form modifications
+   *
+   * @example
+   * ```ts
+   * const form$ = atom({ name: "", email: "" });
+   *
+   * form$.dirty(); // false - just initialized
+   *
+   * form$.set({ name: "John", email: "" });
+   * form$.dirty(); // true - value changed
+   *
+   * form$.reset();
+   * form$.dirty(); // false - reset clears dirty flag
+   * ```
+   */
+  dirty(): boolean;
+}
+
+/**
+ * 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,
+ * even for synchronous computations.
+ *
+ * @template T - The resolved type of the computed value
+ * @template F - Whether fallback is provided (affects staleValue type)
+ *
+ * @example
+ * ```ts
+ * // Without fallback
+ * const double$ = derived(({ get }) => get(count$) * 2);
+ * await double$.value; // number
+ * double$.staleValue;  // number | undefined
+ * double$.state();     // { status: "ready", value: 10 }
+ *
+ * // With fallback - during loading
+ * const double$ = derived(({ get }) => get(count$) * 2, { fallback: 0 });
+ * double$.staleValue;  // number (guaranteed)
+ * double$.state();     // { status: "loading", promise } during loading
+ * ```
+ */
+export interface DerivedAtom<T, F extends boolean = false> extends Atom<
+  Promise<T>
+> {
+  /** Symbol marker to identify derived atom instances */
+  readonly [SYMBOL_DERIVED]: true;
+  /** Re-run the computation */
+  refresh(): void;
+  /**
+   * Get the current state of the derived atom.
+   * Returns a discriminated union with status, value/error, and stale flag.
+   */
+  state(): AtomState<T>;
+  /**
+   * The stale value - fallback or last resolved value.
+   * - Without fallback: T | undefined
+   * - With fallback: T (guaranteed)
+   */
+  readonly staleValue: F extends true ? T : T | undefined;
+}
+
+/**
+ * Union type for any atom (mutable or derived).
+ */
+export type AnyAtom<T> = MutableAtom<T> | DerivedAtom<T, boolean>;
+
+/**
+ * Extract the value type from an atom.
+ * For DerivedAtom, returns the awaited type.
+ */
+export type AtomValue<A> =
+  A extends DerivedAtom<infer V, boolean>
+    ? V
+    : A extends Atom<infer V>
+      ? Awaited<V>
+      : never;
+
+/**
+ * Represents the state of an atom as a discriminated union.
+ *
+ * Uses intuitive state terms:
+ * - `ready` - Value is available
+ * - `error` - Computation failed
+ * - `loading` - Waiting for async value
+ *
+ * @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> };
+
+/**
+ * Result type for settled operations.
+ */
+export type SettledResult<T> =
+  | { status: "ready"; value: T }
+  | { status: "error"; error: unknown };
+
+/**
+ * Configuration options for creating a mutable atom.
+ *
+ * @template T - The type of value stored in the atom
+ */
+export interface AtomOptions<T> {
+  /** Optional metadata for the atom */
+  meta?: MutableAtomMeta;
+  /** Equality strategy for change detection (default: "strict") */
+  equals?: Equality<T>;
+}
+
+export interface MutableAtomMeta extends AtomMeta {}
+
+export interface DerivedAtomMeta extends AtomMeta {}
+
+/**
+ * Configuration options for creating a derived atom.
+ *
+ * @template T - The type of the derived value
+ */
+export interface DerivedOptions<T> {
+  /** Optional metadata for the atom */
+  meta?: DerivedAtomMeta;
+  /** Equality strategy for change detection (default: "strict") */
+  equals?: Equality<T>;
+}
+
+/**
+ * Configuration options for effects.
+ */
+export interface EffectOptions {
+  /** Optional key for debugging */
+  key?: string;
+  /** Error handler for uncaught errors in the effect */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * A function that returns a value when called.
+ * Used for lazy evaluation in derived atoms.
+ *
+ * @template T - The type of value returned
+ */
+export type Getter<T> = () => T;
+
+/**
+ * Built-in equality strategy names.
+ *
+ * Used with atoms to control when subscribers are notified:
+ * - `"strict"` - Object.is (default, fastest)
+ * - `"shallow"` - Compare object keys/array items with Object.is
+ * - `"shallow2"` - 2 levels deep
+ * - `"shallow3"` - 3 levels deep
+ * - `"deep"` - Full recursive comparison (slowest)
+ */
+export type EqualityShorthand =
+  | "strict"
+  | "shallow"
+  | "shallow2"
+  | "shallow3"
+  | "deep";
+
+/**
+ * Equality strategy for change detection.
+ *
+ * Can be a shorthand string or custom comparison function.
+ * Used by atoms to determine if value has "changed" -
+ * if equal, subscribers won't be notified.
+ *
+ * @template T - Type of values being compared
+ */
+export type Equality<T = unknown> =
+  | EqualityShorthand
+  | ((a: T, b: T) => boolean);
+
+/**
+ * Prettify a type by adding all properties to the type.
+ * @template T - The type to prettify
+ */
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+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/src/core/withUse.test.ts

@@ -0,0 +1,249 @@
+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

@@ -0,0 +1,56 @@
+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: 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

@@ -0,0 +1,80 @@
+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.value).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(({ get }) => get(count) * 2);
+    expect(await doubled.value).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(({ get }) => get(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);
+  });
+});