atomirx 0.0.2 → 0.0.5

package/src/core/atom.ts

@@ -2,16 +2,42 @@ import { onCreateHook } from "./onCreateHook";
 import { emitter } from "./emitter";
 import { resolveEquality } from "./equality";
 import { scheduleNotifyHook } from "./scheduleNotifyHook";
-import { AtomOptions, MutableAtom, SYMBOL_ATOM, Equality } from "./types";
+import {
+  AtomOptions,
+  MutableAtom,
+  SYMBOL_ATOM,
+  Equality,
+  Pipeable,
+  Atom,
+} from "./types";
 import { withUse } from "./withUse";
 import { isPromiseLike } from "./isPromiseLike";
 import { trackPromise } from "./promiseCache";
 
+/**
+ * Context object passed to atom initializer functions.
+ * Provides utilities for cleanup and cancellation.
+ */
+export interface AtomContext extends Pipeable {
+  /**
+   * AbortSignal that is aborted when the atom value changes (via set or reset).
+   * Use this to cancel pending async operations.
+   */
+  signal: AbortSignal;
+  /**
+   * Register a cleanup function that runs when the atom value changes or resets.
+   * Multiple cleanup functions can be registered; they run in FIFO order.
+   *
+   * @param cleanup - Function to run during cleanup
+   */
+  onCleanup(cleanup: VoidFunction): void;
+}
+
 /**
  * Creates a mutable atom - a reactive state container that holds a single value.
  *
  * MutableAtom is a raw storage container. It stores values as-is, including Promises.
- * If you store a Promise, `.value` returns the Promise object itself.
+ * If you store a Promise, `.get()` returns the Promise object itself.
  *
  * Features:
  * - Raw storage: stores any value including Promises
@@ -25,14 +51,14 @@ import { trackPromise } from "./promiseCache";
  * @param options - Configuration options
  * @param options.meta - Optional metadata for debugging/devtools
  * @param options.equals - Equality strategy for change detection (default: strict)
- * @returns A mutable atom with value, set/reset methods
+ * @returns A mutable atom with get, set/reset methods
  *
  * @example Synchronous value
  * ```ts
  * const count = atom(0);
  * count.set(1);
  * count.set(prev => prev + 1);
- * console.log(count.value); // 2
+ * console.log(count.get()); // 2
  * ```
  *
  * @example Lazy initialization
@@ -51,7 +77,7 @@ import { trackPromise } from "./promiseCache";
  * @example Async value (stores Promise as-is)
  * ```ts
  * const posts = atom(fetchPosts());
- * posts.value; // Promise<Post[]>
+ * posts.get(); // Promise<Post[]>
  *
  * // Refetch - set a new Promise
  * posts.set(fetchPosts());
@@ -69,17 +95,45 @@ import { trackPromise } from "./promiseCache";
  * ```
  */
 export function atom<T>(
-  valueOrInit: T | (() => T),
+  valueOrInit: T | ((context: AtomContext) => T),
   options: AtomOptions<T> = {}
 ): MutableAtom<T> {
   const changeEmitter = emitter();
   const eq = resolveEquality(options.equals as Equality<unknown>);
 
-  // Resolve initial value (supports lazy initialization)
-  const initialValue: T =
-    typeof valueOrInit === "function"
-      ? (valueOrInit as () => T)()
-      : valueOrInit;
+  // Track current AbortController and cleanup emitter for init context
+  let abortController: AbortController | null = null;
+  const cleanupEmitter = emitter();
+
+  /**
+   * Aborts the current signal and calls all registered cleanup functions.
+   */
+  const abortAndCleanup = (reason: string) => {
+    // Abort the signal first
+    if (abortController) {
+      abortController.abort(reason);
+      abortController = null;
+    }
+    // Then call all registered cleanups
+    cleanupEmitter.emitAndClear();
+  };
+
+  /**
+   * Creates a fresh AtomContext for initializer functions.
+   */
+  const createContext = (): AtomContext => {
+    abortController = new AbortController();
+    return withUse({
+      signal: abortController.signal,
+      onCleanup: cleanupEmitter.on,
+    });
+  };
+
+  // Resolve initial value (supports lazy initialization with context)
+  const isInitFunction = typeof valueOrInit === "function";
+  const initialValue: T = isInitFunction
+    ? (valueOrInit as (context: AtomContext) => T)(createContext())
+    : valueOrInit;
 
   // Current value
   let value: T = initialValue;
@@ -118,6 +172,9 @@ export function atom<T>(
       return;
     }
 
+    // Abort previous signal and run cleanups before changing value
+    abortAndCleanup("value changed");
+
     value = nextValue;
     isDirty = true;
     isPromiseLike(value) && trackPromise(value);
@@ -128,11 +185,13 @@ export function atom<T>(
    * Resets the atom to its initial value and clears dirty flag.
    */
   const reset = () => {
-    // Re-run initializer if function, otherwise use initial value
-    const nextValue: T =
-      typeof valueOrInit === "function"
-        ? (valueOrInit as () => T)()
-        : valueOrInit;
+    // Abort previous signal and run cleanups before resetting
+    abortAndCleanup("reset");
+
+    // Re-run initializer if function (with fresh context), otherwise use initial value
+    const nextValue: T = isInitFunction
+      ? (valueOrInit as (context: AtomContext) => T)(createContext())
+      : valueOrInit;
 
     // Track promise if needed
     isPromiseLike(nextValue) && trackPromise(nextValue);
@@ -161,29 +220,92 @@ export function atom<T>(
     meta: options.meta,
 
     /**
-     * Current value (raw, including Promises).
+     * Get the current value (raw, including Promises).
      */
-    get value(): T {
+    get(): any {
       return value;
     },
-
+    use: undefined as any,
     set,
     reset,
     dirty,
-
     /**
      * Subscribe to value changes.
      */
     on: changeEmitter.on,
-  }) as MutableAtom<T>;
+  }) as Pipeable & MutableAtom<T>;
 
   // Notify devtools/plugins of atom creation
   onCreateHook.current?.({
     type: "mutable",
     key: options.meta?.key,
     meta: options.meta,
-    atom: a as MutableAtom<unknown>,
+    instance: a as MutableAtom<unknown>,
   });
 
   return a;
 }
+
+/**
+ * Type utility to expose an atom as read-only when exporting from a module.
+ *
+ * This function returns the same atom instance but with a narrowed type (`Atom<T>`)
+ * that hides mutable methods like `set()` and `reset()`. Use this to encapsulate
+ * state mutations within a module while allowing external consumers to only read
+ * and subscribe to changes.
+ *
+ * **Note:** This is a compile-time restriction only. At runtime, the atom is unchanged.
+ * Consumers with access to the original reference can still mutate it.
+ *
+ * @param atom - The atom (or record of atoms) to expose as read-only
+ * @returns The same atom(s) with a read-only type signature
+ *
+ * @example Single atom
+ * ```ts
+ * const myModule = define(() => {
+ *   const count$ = atom(0); // Internal mutable atom
+ *
+ *   return {
+ *     // Expose as read-only - consumers can't call set() or reset()
+ *     count$: readonly(count$),
+ *     // Mutations only possible through explicit actions
+ *     increment: () => count$.set(prev => prev + 1),
+ *     decrement: () => count$.set(prev => prev - 1),
+ *   };
+ * });
+ *
+ * // Usage:
+ * const { count$, increment } = myModule();
+ * count$.get();        // ✅ OK - reading is allowed
+ * count$.on(console.log); // ✅ OK - subscribing is allowed
+ * count$.set(5);       // ❌ TypeScript error - set() not available on Atom<T>
+ * increment();         // ✅ OK - use exposed action instead
+ * ```
+ *
+ * @example Record of atoms
+ * ```ts
+ * const myModule = define(() => {
+ *   const count$ = atom(0);
+ *   const name$ = atom('');
+ *
+ *   return {
+ *     // Expose multiple atoms as read-only at once
+ *     ...readonly({ count$, name$ }),
+ *     setName: (name: string) => name$.set(name),
+ *   };
+ * });
+ *
+ * // Usage:
+ * const { count$, name$, setName } = myModule();
+ * count$.get();  // ✅ Atom<number>
+ * name$.get();   // ✅ Atom<string>
+ * name$.set(''); // ❌ TypeScript error
+ * ```
+ */
+export function readonly<T extends Atom<any> | Record<string, Atom<any>>>(
+  atom: T
+): T extends Atom<infer V>
+  ? Atom<V>
+  : { [K in keyof T]: T[K] extends Atom<infer V> ? Atom<V> : never } {
+  return atom as any;
+}

package/src/core/batch.test.ts

@@ -16,7 +16,7 @@ describe("batch", () => {
       });
 
       // All updates batched - listener called once at the end
-      expect(count.value).toBe(3);
+      expect(count.get()).toBe(3);
       expect(listener).toHaveBeenCalledTimes(1);
     });
 
@@ -54,7 +54,7 @@ describe("batch", () => {
         count.set(4);
       });
 
-      expect(count.value).toBe(4);
+      expect(count.get()).toBe(4);
       // All updates batched together
       expect(listener).toHaveBeenCalledTimes(1);
     });
@@ -87,8 +87,8 @@ describe("batch", () => {
         b.set(2);
       });
 
-      expect(a.value).toBe(2);
-      expect(b.value).toBe(2);
+      expect(a.get()).toBe(2);
+      expect(b.get()).toBe(2);
       expect(listenerA).toHaveBeenCalledTimes(1);
       expect(listenerB).toHaveBeenCalledTimes(1);
     });
@@ -125,7 +125,7 @@ describe("batch", () => {
         });
       }).not.toThrow();
 
-      expect(count.value).toBe(3);
+      expect(count.get()).toBe(3);
     });
   });
 
@@ -138,8 +138,8 @@ describe("batch", () => {
 
       // When a changes, update b
       a.on(() => {
-        if (a.value !== undefined && a.value > 0) {
-          b.set(a.value * 2);
+        if (a.get() !== undefined && a.get() > 0) {
+          b.set(a.get() * 2);
         }
       });
 
@@ -150,8 +150,8 @@ describe("batch", () => {
         a.set(5);
       });
 
-      expect(a.value).toBe(5);
-      expect(b.value).toBe(10);
+      expect(a.get()).toBe(5);
+      expect(b.get()).toBe(10);
     });
   });
 
@@ -226,7 +226,7 @@ describe("batch", () => {
 
       // Listener called once at the end with final value
       expect(listener).toHaveBeenCalledTimes(1);
-      expect(count.value).toBe(3);
+      expect(count.get()).toBe(3);
     });
 
     it("should handle mixed scenario with shared and unique listeners", () => {

package/src/core/batch.ts

@@ -59,7 +59,7 @@ let batchDepth = 0;
  * ```ts
  * const counter = atom(0);
  *
- * counter.on(() => console.log("Counter:", counter.value));
+ * counter.on(() => console.log("Counter:", counter.get()));
  *
  * batch(() => {
  *   counter.set(1);
@@ -75,7 +75,7 @@ let batchDepth = 0;
  * const b = atom(0);
  *
  * // Same listener subscribed to both atoms
- * const listener = () => console.log("Changed!", a.value, b.value);
+ * const listener = () => console.log("Changed!", a.get(), b.get());
  * a.on(listener);
  * b.on(listener);
  *
@@ -103,7 +103,7 @@ let batchDepth = 0;
  * ```ts
  * const result = batch(() => {
  *   counter.set(10);
- *   return counter.value * 2;
+ *   return counter.get() * 2;
  * });
  * console.log(result); // 20
  * ```

package/src/core/define.test.ts

@@ -3,14 +3,12 @@ import { define } from "./define";
 import { onCreateHook } from "./onCreateHook";
 
 describe("define", () => {
-  const originalOnCreateHook = onCreateHook.current;
-
   beforeEach(() => {
-    onCreateHook.current = undefined;
+    onCreateHook.reset();
   });
 
   afterEach(() => {
-    onCreateHook.current = originalOnCreateHook;
+    onCreateHook.reset();
   });
 
   describe("basic functionality", () => {
@@ -238,7 +236,7 @@ describe("define", () => {
   describe("onCreateHook", () => {
     it("should call onCreateHook when module is created", () => {
       const hookFn = vi.fn();
-      onCreateHook.current = hookFn;
+      onCreateHook.override(() => hookFn);
 
       const store = define(() => ({ value: 42 }), { key: "testModule" });
       const instance = store();
@@ -247,13 +245,14 @@ describe("define", () => {
       expect(hookFn).toHaveBeenCalledWith({
         type: "module",
         key: "testModule",
-        module: instance,
+        meta: undefined,
+        instance,
       });
     });
 
     it("should call onCreateHook with undefined key when not provided", () => {
       const hookFn = vi.fn();
-      onCreateHook.current = hookFn;
+      onCreateHook.override(() => hookFn);
 
       const store = define(() => ({ value: 42 }));
       store();
@@ -261,12 +260,13 @@ describe("define", () => {
       expect(hookFn).toHaveBeenCalledWith({
         type: "module",
         key: undefined,
-        module: expect.any(Object),
+        meta: undefined,
+        instance: expect.any(Object),
       });
     });
 
     it("should not throw when onCreateHook is undefined", () => {
-      onCreateHook.current = undefined;
+      onCreateHook.reset();
 
       const store = define(() => ({ value: 42 }));
       expect(() => store()).not.toThrow();
@@ -274,7 +274,7 @@ describe("define", () => {
 
     it("should call onCreateHook for overridden module", () => {
       const hookFn = vi.fn();
-      onCreateHook.current = hookFn;
+      onCreateHook.override(() => hookFn);
 
       const store = define(() => ({ value: "original" }));
       store.override(() => ({ value: "overridden" }));
@@ -283,7 +283,8 @@ describe("define", () => {
       expect(hookFn).toHaveBeenCalledWith({
         type: "module",
         key: undefined,
-        module: instance,
+        meta: undefined,
+        instance,
       });
     });
   });

package/src/core/define.ts

@@ -213,7 +213,7 @@ export function define<T>(
         type: "module",
         key: options?.key,
         meta: options?.meta,
-        module: instance,
+        instance,
       });
     }
     return instance;