atomirx 0.0.1

package/src/core/hook.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect } from "vitest";
+import { hook } from "./hook";
+
+describe("hook", () => {
+  describe("createHook", () => {
+    it("should create a hook with initial value", () => {
+      const myHook = hook(42);
+      expect(myHook.current).toBe(42);
+    });
+
+    it("should create a hook with undefined when no initial value", () => {
+      const myHook = hook<string>();
+      expect(myHook.current).toBeUndefined();
+    });
+
+    it("should create a hook with object value", () => {
+      const obj = { name: "test" };
+      const myHook = hook(obj);
+      expect(myHook.current).toBe(obj);
+    });
+
+    it("should create a hook with function value", () => {
+      const fn = () => 42;
+      const myHook = hook(fn);
+      expect(myHook.current).toBe(fn);
+    });
+  });
+
+  describe("hook.override", () => {
+    it("should override the current value using reducer", () => {
+      const myHook = hook(0);
+      expect(myHook.current).toBe(0);
+
+      myHook.override(() => 100);
+      expect(myHook.current).toBe(100);
+    });
+
+    it("should allow multiple overrides", () => {
+      const myHook = hook("initial");
+      myHook.override(() => "first");
+      expect(myHook.current).toBe("first");
+
+      myHook.override(() => "second");
+      expect(myHook.current).toBe("second");
+    });
+
+    it("should receive previous value in reducer", () => {
+      const myHook = hook(10);
+      myHook.override((prev) => prev + 5);
+      expect(myHook.current).toBe(15);
+
+      myHook.override((prev) => prev * 2);
+      expect(myHook.current).toBe(30);
+    });
+
+    it("should support composing handlers (middleware pattern)", () => {
+      const calls: string[] = [];
+      const myHook = hook<((msg: string) => void) | undefined>(undefined);
+
+      // First handler
+      myHook.override(() => (msg) => calls.push(`first: ${msg}`));
+
+      // Compose with second handler
+      myHook.override((prev) => (msg) => {
+        prev?.(msg);
+        calls.push(`second: ${msg}`);
+      });
+
+      myHook.current?.("hello");
+      expect(calls).toEqual(["first: hello", "second: hello"]);
+    });
+  });
+
+  describe("hook setup/release pattern", () => {
+    it("should create a setup function that returns a release function", () => {
+      const myHook = hook(0);
+      const setup = myHook(() => 10);
+
+      expect(typeof setup).toBe("function");
+
+      const release = setup();
+      expect(typeof release).toBe("function");
+      expect(myHook.current).toBe(10);
+
+      release();
+      expect(myHook.current).toBe(0);
+    });
+
+    it("should support nested setup/release", () => {
+      const myHook = hook(0);
+
+      const setup1 = myHook(() => 1);
+      const release1 = setup1();
+      expect(myHook.current).toBe(1);
+
+      const setup2 = myHook(() => 2);
+      const release2 = setup2();
+      expect(myHook.current).toBe(2);
+
+      release2();
+      expect(myHook.current).toBe(1);
+
+      release1();
+      expect(myHook.current).toBe(0);
+    });
+
+    it("should receive previous value in setup reducer", () => {
+      const myHook = hook(10);
+
+      const setup = myHook((prev) => prev + 5);
+      const release = setup();
+      expect(myHook.current).toBe(15);
+
+      release();
+      expect(myHook.current).toBe(10);
+    });
+  });
+
+  describe("hook.use", () => {
+    it("should temporarily set hook value during function execution", () => {
+      const myHook = hook(0);
+
+      const result = hook.use([myHook(() => 42)], () => {
+        expect(myHook.current).toBe(42);
+        return "done";
+      });
+
+      expect(result).toBe("done");
+      expect(myHook.current).toBe(0);
+    });
+
+    it("should support multiple hooks", () => {
+      const hookA = hook("a");
+      const hookB = hook("b");
+
+      hook.use([hookA(() => "A"), hookB(() => "B")], () => {
+        expect(hookA.current).toBe("A");
+        expect(hookB.current).toBe("B");
+      });
+
+      expect(hookA.current).toBe("a");
+      expect(hookB.current).toBe("b");
+    });
+
+    it("should restore values even if function throws", () => {
+      const myHook = hook(0);
+
+      expect(() => {
+        hook.use([myHook(() => 42)], () => {
+          expect(myHook.current).toBe(42);
+          throw new Error("test error");
+        });
+      }).toThrow("test error");
+
+      expect(myHook.current).toBe(0);
+    });
+
+    it("should support nested hook.use calls", () => {
+      const myHook = hook(0);
+
+      hook.use([myHook(() => 1)], () => {
+        expect(myHook.current).toBe(1);
+
+        hook.use([myHook(() => 2)], () => {
+          expect(myHook.current).toBe(2);
+        });
+
+        expect(myHook.current).toBe(1);
+      });
+
+      expect(myHook.current).toBe(0);
+    });
+
+    it("should release hooks in reverse order", () => {
+      const order: string[] = [];
+      const hookA = hook<string | undefined>();
+      const hookB = hook<string | undefined>();
+
+      // Create custom setups that track release order
+      const setupA = () => {
+        hookA.current = "A";
+        return () => {
+          order.push("release A");
+          hookA.current = undefined;
+        };
+      };
+
+      const setupB = () => {
+        hookB.current = "B";
+        return () => {
+          order.push("release B");
+          hookB.current = undefined;
+        };
+      };
+
+      hook.use([setupA, setupB], () => {
+        expect(hookA.current).toBe("A");
+        expect(hookB.current).toBe("B");
+      });
+
+      expect(order).toEqual(["release B", "release A"]);
+    });
+
+    it("should work with empty setups array", () => {
+      const result = hook.use([], () => "result");
+      expect(result).toBe("result");
+    });
+
+    it("should return the function result", () => {
+      const myHook = hook(0);
+      const result = hook.use([myHook(() => 1)], () => {
+        return { value: myHook.current };
+      });
+      expect(result).toEqual({ value: 1 });
+    });
+
+    it("should support reducer composition in hook.use", () => {
+      const myHook = hook(10);
+
+      hook.use([myHook((prev) => prev + 5)], () => {
+        expect(myHook.current).toBe(15);
+      });
+
+      expect(myHook.current).toBe(10);
+    });
+  });
+});

package/src/core/hook.ts

@@ -0,0 +1,177 @@
+/**
+ * A setup function that returns a release function.
+ * Called by hook.use() to activate a hook, release restores previous value.
+ */
+export type HookSetup = () => VoidFunction;
+
+/**
+ * A hook is a callable factory that creates setup functions,
+ * with direct access to current value via `.current`.
+ *
+ * @example
+ * ```ts
+ * const myHook = hook<string>("default");
+ *
+ * // Read current value (fast - direct property access)
+ * console.log(myHook.current); // "default"
+ *
+ * // Create a setup function (reducer receives previous value)
+ * const setup = myHook(() => "new value");
+ *
+ * // Use with hook.use()
+ * hook.use([myHook(() => "temp")], () => {
+ *   console.log(myHook.current); // "temp"
+ * });
+ * console.log(myHook.current); // "default" (restored)
+ *
+ * // Compose with previous value
+ * myHook.override(prev => {
+ *   console.log("Previous:", prev);
+ *   return "next";
+ * });
+ * ```
+ */
+export interface Hook<T> {
+  /**
+   * Creates a HookSetup that will set this hook using a reducer.
+   * The reducer receives the previous value and returns the next value.
+   *
+   * @param reducer - Function that receives previous value and returns next value
+   *
+   * @example Set new value (ignore previous)
+   * ```ts
+   * myHook(() => "new value")
+   * ```
+   *
+   * @example Compose with previous
+   * ```ts
+   * myHook(prev => {
+   *   prev?.(); // call previous handler
+   *   return newHandler;
+   * })
+   * ```
+   */
+  (reducer: (prev: T) => T): HookSetup;
+
+  /**
+   * Current value of the hook. Direct property access for fast reads.
+   */
+  current: T;
+
+  /**
+   * Override the current value using a reducer.
+   * The reducer receives the previous value and returns the next value.
+   * Unlike the setup/release pattern, this is an immediate mutation.
+   *
+   * @param reducer - Function that receives previous value and returns next value
+   *
+   * @example Set new value (ignore previous)
+   * ```ts
+   * myHook.override(() => "new value")
+   * ```
+   *
+   * @example Compose with previous (middleware pattern)
+   * ```ts
+   * onCreateHook.override(prev => (info) => {
+   *   prev?.(info);  // call existing handler
+   *   console.log("Created:", info.key);
+   * });
+   * ```
+   */
+  override(reducer: (prev: T) => T): void;
+
+  /**
+   * Reset the hook to its initial value.
+   */
+  reset(): void;
+}
+
+/**
+ * Creates a new hook with an initial value.
+ *
+ * Hooks use the setup/release pattern for performance:
+ * - Reads are direct property access (fastest)
+ * - Writes use setup/release for proper nesting
+ *
+ * @param initial - Initial value for the hook
+ * @returns A Hook instance
+ *
+ * @example
+ * ```ts
+ * // Create a hook
+ * const countHook = hook(0);
+ *
+ * // Read
+ * console.log(countHook.current); // 0
+ *
+ * // Use with hook.use() - reducer receives previous value
+ * hook.use([countHook(() => 5)], () => {
+ *   console.log(countHook.current); // 5
+ * });
+ *
+ * // Compose with previous (middleware pattern)
+ * myHook.override(prev => (info) => {
+ *   prev?.(info);  // call existing
+ *   newHandler(info);
+ * });
+ * ```
+ */
+function createHook<T>(initial: T): Hook<T>;
+function createHook<T>(): Hook<T | undefined>;
+function createHook<T>(initial?: T): Hook<T | undefined> {
+  // The hook function creates a setup that returns a release
+  const h = Object.assign(
+    (reducer: (prev: T | undefined) => T | undefined): HookSetup => {
+      return () => {
+        const prev = h.current;
+        h.current = reducer(prev);
+        return () => {
+          h.current = prev;
+        };
+      };
+    },
+    {
+      current: initial,
+      // Override method for direct mutation using reducer
+      override: (reducer: (prev: T | undefined) => T | undefined) => {
+        h.current = reducer(h.current);
+      },
+      reset: () => {
+        h.current = initial;
+      },
+    }
+  );
+
+  return h as Hook<T | undefined>;
+}
+
+/**
+ * Executes a function with multiple hooks temporarily set.
+ *
+ * @param setups - Array of HookSetup functions (from hook factories)
+ * @param fn - Function to execute with hooks active
+ * @returns The return value of fn
+ *
+ * @example
+ * ```ts
+ * hook.use([trackHook(myTracker), debugHook(true)], () => {
+ *   // hooks active here
+ * });
+ * ```
+ */
+function use<T>(setups: HookSetup[], fn: () => T): T {
+  const releases: VoidFunction[] = [];
+  for (const setup of setups) {
+    releases.push(setup());
+  }
+  try {
+    return fn();
+  } finally {
+    for (const release of releases.reverse()) {
+      release();
+    }
+  }
+}
+
+// Combine into namespace
+export const hook = Object.assign(createHook, { use });

package/src/core/isAtom.ts

@@ -0,0 +1,27 @@
+import { Atom, DerivedAtom, SYMBOL_ATOM, SYMBOL_DERIVED } from "./types";
+
+/**
+ * Type guard to check if a value is an Atom.
+ */
+export function isAtom<T>(value: unknown): value is Atom<T> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    SYMBOL_ATOM in value &&
+    (value as Atom<T>)[SYMBOL_ATOM] === true
+  );
+}
+
+/**
+ * Type guard to check if a value is a DerivedAtom.
+ */
+export function isDerived<T>(
+  value: unknown
+): value is DerivedAtom<T, boolean> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    SYMBOL_DERIVED in value &&
+    (value as DerivedAtom<T, boolean>)[SYMBOL_DERIVED] === true
+  );
+}

package/src/core/isPromiseLike.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { isPromiseLike } from "./isPromiseLike";
+
+describe("isPromiseLike", () => {
+  describe("returns true for PromiseLike values", () => {
+    it("should return true for native Promise", () => {
+      expect(isPromiseLike(Promise.resolve(1))).toBe(true);
+    });
+
+    it("should return true for rejected Promise", () => {
+      const rejected = Promise.reject(new Error("test"));
+      rejected.catch(() => {}); // Prevent unhandled rejection
+      expect(isPromiseLike(rejected)).toBe(true);
+    });
+
+    it("should return true for object with then method", () => {
+      const thenable = { then: () => {} };
+      expect(isPromiseLike(thenable)).toBe(true);
+    });
+
+    it("should return true for object with then method that takes callbacks", () => {
+      const thenable = {
+        then: (resolve: (v: number) => void, _reject: (e: Error) => void) => {
+          resolve(42);
+        },
+      };
+      expect(isPromiseLike(thenable)).toBe(true);
+    });
+  });
+
+  describe("returns false for non-PromiseLike values", () => {
+    it("should return false for null", () => {
+      expect(isPromiseLike(null)).toBe(false);
+    });
+
+    it("should return false for undefined", () => {
+      expect(isPromiseLike(undefined)).toBe(false);
+    });
+
+    it("should return false for number", () => {
+      expect(isPromiseLike(42)).toBe(false);
+    });
+
+    it("should return false for string", () => {
+      expect(isPromiseLike("hello")).toBe(false);
+    });
+
+    it("should return false for boolean", () => {
+      expect(isPromiseLike(true)).toBe(false);
+    });
+
+    it("should return false for plain object without then", () => {
+      expect(isPromiseLike({ value: 1 })).toBe(false);
+    });
+
+    it("should return false for array", () => {
+      expect(isPromiseLike([1, 2, 3])).toBe(false);
+    });
+
+    it("should return false for function", () => {
+      expect(isPromiseLike(() => {})).toBe(false);
+    });
+
+    it("should return false for object with non-function then property", () => {
+      expect(isPromiseLike({ then: "not a function" })).toBe(false);
+    });
+
+    it("should return false for object with then as number", () => {
+      expect(isPromiseLike({ then: 123 })).toBe(false);
+    });
+  });
+});

package/src/core/isPromiseLike.ts

@@ -0,0 +1,16 @@
+/**
+ * Check if a value is a PromiseLike (has a .then method).
+ *
+ * @example
+ * isPromiseLike(Promise.resolve(1)) // true
+ * isPromiseLike({ then: () => {} }) // true
+ * isPromiseLike(42) // false
+ */
+export function isPromiseLike<T>(value: unknown): value is PromiseLike<T> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    "then" in value &&
+    typeof (value as any).then === "function"
+  );
+}

package/src/core/onCreateHook.ts

@@ -0,0 +1,92 @@
+import { hook } from "./hook";
+import {
+  MutableAtomMeta,
+  DerivedAtomMeta,
+  MutableAtom,
+  DerivedAtom,
+  ModuleMeta,
+} from "./types";
+
+/**
+ * Information provided when a mutable atom is created.
+ */
+export interface MutableAtomCreateInfo {
+  /** Discriminator for mutable atoms */
+  type: "mutable";
+  /** Optional key from atom options (for debugging/devtools) */
+  key: string | undefined;
+  /** Optional metadata from atom options */
+  meta: MutableAtomMeta | undefined;
+  /** The created mutable atom instance */
+  atom: MutableAtom<unknown>;
+}
+
+/**
+ * Information provided when a derived atom is created.
+ */
+export interface DerivedAtomCreateInfo {
+  /** Discriminator for derived atoms */
+  type: "derived";
+  /** Optional key from derived options (for debugging/devtools) */
+  key: string | undefined;
+  /** Optional metadata from derived options */
+  meta: DerivedAtomMeta | undefined;
+  /** The created derived atom instance */
+  atom: DerivedAtom<unknown, boolean>;
+}
+
+/**
+ * Union type for atom creation info (mutable or derived).
+ */
+export type AtomCreateInfo = MutableAtomCreateInfo | DerivedAtomCreateInfo;
+
+/**
+ * Information provided when a module (via define()) is created.
+ */
+export interface ModuleCreateInfo {
+  /** Discriminator for modules */
+  type: "module";
+  /** Optional key from define options (for debugging/devtools) */
+  key: string | undefined;
+  /** Optional metadata from define options */
+  meta: ModuleMeta | undefined;
+  /** The created module instance */
+  module: unknown;
+}
+
+/**
+ * Global hook that fires whenever an atom or module is created.
+ *
+ * This is useful for:
+ * - **DevTools integration** - track all atoms/modules in the app
+ * - **Debugging** - log atom creation for troubleshooting
+ * - **Testing** - verify expected atoms are created
+ *
+ * @example Basic logging
+ * ```ts
+ * onCreateHook.current = (info) => {
+ *   console.log(`Created ${info.type}: ${info.key ?? "anonymous"}`);
+ * };
+ * ```
+ *
+ * @example DevTools integration
+ * ```ts
+ * const atoms = new Map();
+ * const modules = new Map();
+ *
+ * onCreateHook.current = (info) => {
+ *   if (info.type === "module") {
+ *     modules.set(info.key, info.module);
+ *   } else {
+ *     atoms.set(info.key, info.atom);
+ *   }
+ * };
+ * ```
+ *
+ * @example Cleanup (disable hook)
+ * ```ts
+ * onCreateHook.current = undefined;
+ * ```
+ */
+export const onCreateHook =
+  hook<(info: AtomCreateInfo | ModuleCreateInfo) => void>();