atomirx 0.0.1

package/dist/react/useStable.d.ts

@@ -0,0 +1,183 @@
+import { StableFn } from '../core/equality';
+import { AnyFunc, Equality } from '../core/types';
+/**
+ * Extracts non-function keys from an object type.
+ */
+type NonFunctionKeys<T> = {
+    [K in keyof T]: T[K] extends AnyFunc ? never : K;
+}[keyof T];
+/**
+ * Equals options for useStable - only non-function properties can have custom equality.
+ */
+export type UseStableEquals<T> = {
+    [K in NonFunctionKeys<T>]?: Equality<T[K]>;
+};
+/**
+ * Result type for useStable - functions are wrapped in StableFn.
+ */
+export type UseStableResult<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? StableFn<A, R> : T[K];
+};
+/**
+ * React hook that provides stable references for objects, arrays, and callbacks.
+ *
+ * `useStable` solves the common React problem of unstable references causing
+ * unnecessary re-renders, useEffect re-runs, and useCallback/useMemo invalidations.
+ *
+ * ## Why Use `useStable`?
+ *
+ * In React, inline objects, arrays, and callbacks create new references on every render:
+ *
+ * ```tsx
+ * // ❌ Problem: new reference every render
+ * function Parent() {
+ *   const config = { theme: 'dark' };  // New object every render!
+ *   const onClick = () => doSomething(); // New function every render!
+ *   return <Child config={config} onClick={onClick} />;
+ * }
+ *
+ * // ✅ Solution: stable references
+ * function Parent() {
+ *   const stable = useStable({
+ *     config: { theme: 'dark' },
+ *     onClick: () => doSomething(),
+ *   });
+ *   return <Child config={stable.config} onClick={stable.onClick} />;
+ * }
+ * ```
+ *
+ * ## How It Works
+ *
+ * Each property is independently stabilized based on its type:
+ *
+ * | Type | Default Equality | Behavior |
+ * |------|------------------|----------|
+ * | **Functions** | N/A (always wrapped) | Reference never changes, calls latest implementation |
+ * | **Arrays** | shallow | Stable if items are reference-equal |
+ * | **Dates** | timestamp | Stable if same time value |
+ * | **Objects** | shallow | Stable if keys have reference-equal values |
+ * | **Primitives** | strict | Stable if same value |
+ *
+ * ## Key Benefits
+ *
+ * 1. **Stable callbacks**: Functions maintain reference identity while always calling latest implementation
+ * 2. **Stable objects/arrays**: Prevent unnecessary child re-renders
+ * 3. **Safe for deps arrays**: Use in useEffect, useMemo, useCallback deps
+ * 4. **Per-property equality**: Customize comparison strategy for each property
+ * 5. **No wrapper overhead**: Returns the same result object reference
+ *
+ * @template T - The type of the input object
+ * @param input - Object with properties to stabilize
+ * @param equals - Optional custom equality strategies per property (except functions)
+ * @returns Stable object with same properties (functions wrapped in StableFn)
+ *
+ * @example Basic usage - stable callbacks and objects
+ * ```tsx
+ * function MyComponent({ userId }) {
+ *   const stable = useStable({
+ *     // Object - stable if shallow equal
+ *     config: { theme: 'dark', userId },
+ *     // Array - stable if items are reference-equal
+ *     items: [1, 2, 3],
+ *     // Function - reference never changes
+ *     onClick: () => console.log('clicked', userId),
+ *   });
+ *
+ *   // Safe to use in deps - won't cause infinite loops
+ *   useEffect(() => {
+ *     console.log(stable.config);
+ *   }, [stable.config]);
+ *
+ *   // stable.onClick is always the same reference
+ *   return <button onClick={stable.onClick}>Click</button>;
+ * }
+ * ```
+ *
+ * @example Preventing child re-renders
+ * ```tsx
+ * function Parent() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   const stable = useStable({
+ *     // These won't cause Child to re-render when count changes
+ *     user: { id: 1, name: 'John' },
+ *     onSave: () => saveUser(),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ *       <MemoizedChild user={stable.user} onSave={stable.onSave} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Custom equality per property
+ * ```tsx
+ * const stable = useStable(
+ *   {
+ *     user: { id: 1, profile: { name: "John", avatar: "..." } },
+ *     tags: ["react", "typescript"],
+ *     settings: { theme: "dark" },
+ *   },
+ *   {
+ *     user: "deep",              // Deep compare nested objects
+ *     tags: "strict",            // Override default shallow for arrays
+ *     settings: "shallow",       // Explicit shallow (same as default)
+ *   }
+ * );
+ * ```
+ *
+ * @example Custom equality function
+ * ```tsx
+ * const stable = useStable(
+ *   { user: { id: 1, name: "John", updatedAt: new Date() } },
+ *   {
+ *     // Only compare by id - ignore name and updatedAt changes
+ *     user: (a, b) => a?.id === b?.id
+ *   }
+ * );
+ * // stable.user reference only changes when id changes
+ * ```
+ *
+ * @example With useEffect deps
+ * ```tsx
+ * function DataFetcher({ filters }) {
+ *   const stable = useStable({
+ *     filters: { ...filters, timestamp: Date.now() },
+ *     onSuccess: (data) => processData(data),
+ *   });
+ *
+ *   useEffect(() => {
+ *     // Only re-runs when filters actually change (shallow comparison)
+ *     fetchData(stable.filters).then(stable.onSuccess);
+ *   }, [stable.filters, stable.onSuccess]);
+ * }
+ * ```
+ *
+ * @example Stable event handlers for lists
+ * ```tsx
+ * function TodoList({ todos }) {
+ *   const stable = useStable({
+ *     onDelete: (id) => deleteTodo(id),
+ *     onToggle: (id) => toggleTodo(id),
+ *   });
+ *
+ *   return (
+ *     <ul>
+ *       {todos.map(todo => (
+ *         <TodoItem
+ *           key={todo.id}
+ *           todo={todo}
+ *           onDelete={stable.onDelete}  // Same reference for all items
+ *           onToggle={stable.onToggle}  // Prevents unnecessary re-renders
+ *         />
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStable<T extends Record<string, unknown>>(input: T, equals?: UseStableEquals<T>): UseStableResult<T>;
+export {};

package/dist/react/useStable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/react/useValue.d.ts

@@ -0,0 +1,134 @@
+import { ContextSelectorFn } from '../core/select';
+import { Atom, Equality } from '../core/types';
+/**
+ * React hook that selects/derives a value from atom(s) with automatic subscriptions.
+ *
+ * Uses `useSyncExternalStore` for proper React 18+ concurrent mode support.
+ * Only subscribes to atoms that are actually accessed during selection.
+ *
+ * ## IMPORTANT: Selector Must Return Synchronous Value
+ *
+ * **The selector function MUST NOT be async or return a Promise.**
+ *
+ * ```tsx
+ * // ❌ WRONG - Don't use async function
+ * useValue(async ({ get }) => {
+ *   const data = await fetch('/api');
+ *   return data;
+ * });
+ *
+ * // ❌ WRONG - Don't return a Promise
+ * useValue(({ get }) => fetch('/api').then(r => r.json()));
+ *
+ * // ✅ CORRECT - Create async atom and read with get()
+ * const data$ = atom(fetch('/api').then(r => r.json()));
+ * useValue(({ get }) => get(data$)); // Suspends until resolved
+ * ```
+ *
+ * ## IMPORTANT: Suspense-Style API
+ *
+ * This hook uses a **Suspense-style API** for async atoms:
+ * - When an atom is **loading**, the getter throws a Promise (suspends)
+ * - When an atom has an **error**, the getter throws the error
+ * - When an atom is **resolved**, the getter returns the value
+ *
+ * This means:
+ * - **You MUST wrap components with `<Suspense>`** to handle loading states
+ * - **You MUST wrap components with `<ErrorBoundary>`** to handle errors
+ *
+ * ## Alternative: Using staleValue for Non-Suspense
+ *
+ * If you want to show loading states without Suspense:
+ *
+ * ```tsx
+ * function MyComponent() {
+ *   // Access staleValue directly - always has a value (with fallback)
+ *   const count = myDerivedAtom$.staleValue;
+ *   const isLoading = isPending(myDerivedAtom$.value);
+ *
+ *   return (
+ *     <div>
+ *       {isLoading && <Spinner />}
+ *       Count: {count}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @template T - The type of the selected value
+ * @param selectorOrAtom - Atom or context-based selector function (must return sync value)
+ * @param equals - Equality function or shorthand. Defaults to "shallow"
+ * @returns The selected value (Awaited<T>)
+ * @throws Error if selector returns a Promise or PromiseLike
+ *
+ * @example Single atom (shorthand)
+ * ```tsx
+ * const count = atom(5);
+ *
+ * function Counter() {
+ *   const value = useValue(count);
+ *   return <div>{value}</div>;
+ * }
+ * ```
+ *
+ * @example With selector
+ * ```tsx
+ * const count = atom(5);
+ *
+ * function Counter() {
+ *   const doubled = useValue(({ get }) => get(count) * 2);
+ *   return <div>{doubled}</div>;
+ * }
+ * ```
+ *
+ * @example Multiple atoms
+ * ```tsx
+ * const firstName = atom("John");
+ * const lastName = atom("Doe");
+ *
+ * function FullName() {
+ *   const fullName = useValue(({ get }) =>
+ *     `${get(firstName)} ${get(lastName)}`
+ *   );
+ *   return <div>{fullName}</div>;
+ * }
+ * ```
+ *
+ * @example Async atom with Suspense
+ * ```tsx
+ * const userAtom = atom(fetchUser());
+ *
+ * function UserProfile() {
+ *   const user = useValue(({ get }) => get(userAtom));
+ *   return <div>{user.name}</div>;
+ * }
+ *
+ * // MUST wrap with Suspense and ErrorBoundary
+ * function App() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Error!</div>}>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         <UserProfile />
+ *       </Suspense>
+ *     </ErrorBoundary>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using all() for multiple async atoms
+ * ```tsx
+ * const userAtom = atom(fetchUser());
+ * const postsAtom = atom(fetchPosts());
+ *
+ * function Dashboard() {
+ *   const data = useValue(({ all }) => {
+ *     const [user, posts] = all(userAtom, postsAtom);
+ *     return { user, posts };
+ *   });
+ *
+ *   return <DashboardContent user={data.user} posts={data.posts} />;
+ * }
+ * ```
+ */
+export declare function useValue<T>(atom: Atom<T>, equals?: Equality<Awaited<T>>): Awaited<T>;
+export declare function useValue<T>(selector: ContextSelectorFn<T>, equals?: Equality<T>): T;

package/dist/react/useValue.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "atomirx",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/atomirx.umd.cjs",
+  "module": "./dist/atomirx.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/atomirx.js",
+      "require": "./dist/atomirx.umd.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs",
+      "types": "./dist/react/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc && vite build",
+    "test": "vitest --no-watch",
+    "typecheck": "tsc --noEmit",
+    "prepublish:patch": "node scripts/publish.js pre patch",
+    "prepublish:minor": "node scripts/publish.js pre minor",
+    "prepublish:major": "node scripts/publish.js pre major",
+    "postpublish": "node scripts/publish.js post",
+    "release:patch": "node scripts/publish.js full patch",
+    "release:minor": "node scripts/publish.js full minor",
+    "release:major": "node scripts/publish.js full major"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@types/lodash": "^4.17.14",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "jsdom": "^24.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/scripts/publish.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * Publish helper scripts for manual npm publish with OTP.
+ *
+ * Workflow:
+ *   1. pnpm prepublish:patch   (test -> build -> bump)
+ *   2. npm publish             (manual, enter OTP via browser)
+ *   3. pnpm postpublish        (git commit -> tag -> push)
+ *
+ * Or all at once (if you have automation token):
+ *   pnpm publish:patch
+ */
+
+import { execSync } from "child_process";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJsonPath = join(__dirname, "..", "package.json");
+
+function exec(command, options = {}) {
+  console.log(`\n> ${command}`);
+  try {
+    execSync(command, { stdio: "inherit", ...options });
+    return true;
+  } catch (error) {
+    if (options.allowFail) {
+      console.warn(`   (skipped - already done or nothing to do)`);
+      return false;
+    }
+    console.error(`\n❌ Failed: ${command}`);
+    process.exit(1);
+  }
+}
+
+function hasGitRemote() {
+  try {
+    const result = execSync("git remote", { encoding: "utf-8" });
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  return pkg.version;
+}
+
+function bumpVersion(type) {
+  const validTypes = ["patch", "minor", "major"];
+  if (!validTypes.includes(type)) {
+    console.error(
+      `❌ Invalid version type: ${type}. Must be one of: ${validTypes.join(
+        ", "
+      )}`
+    );
+    process.exit(1);
+  }
+
+  console.log(`\n📦 Bumping ${type} version...`);
+  exec(`npm version ${type} --no-git-tag-version`);
+  return getVersion();
+}
+
+/**
+ * Pre-publish: test -> build -> bump version
+ */
+function prepublish(versionType) {
+  console.log("🚀 Pre-publish: preparing for release...\n");
+
+  // Step 1: Test
+  console.log("1️⃣  Running tests...");
+  exec("npm test");
+
+  // Step 2: Build
+  console.log("\n2️⃣  Building...");
+  exec("npm run build");
+
+  // Step 3: Bump version
+  const newVersion = bumpVersion(versionType);
+  console.log(`\n✅ Version bumped to ${newVersion}`);
+
+  console.log("\n" + "=".repeat(50));
+  console.log(`📦 Ready to publish v${newVersion}`);
+  console.log("=".repeat(50));
+  console.log("\nNow run:");
+  console.log("  npm publish");
+  console.log("\nThen after successful publish, run:");
+  console.log("  pnpm postpublish\n");
+}
+
+/**
+ * Post-publish: git commit -> tag -> push
+ */
+function postpublish() {
+  const version = getVersion();
+
+  console.log("🚀 Post-publish: committing and pushing...\n");
+
+  // Git commit and tag
+  console.log("1️⃣  Creating git commit and tag...");
+  exec("git add package.json");
+  exec(`git commit -m "chore: release v${version}"`, { allowFail: true });
+  exec(`git tag v${version}`, { allowFail: true });
+
+  // Push to git (skip if no remote)
+  if (hasGitRemote()) {
+    console.log("\n2️⃣  Pushing to git...");
+    exec("git push");
+    exec("git push --tags");
+  } else {
+    console.log("\n⚠️  No git remote configured. Skipping push.");
+    console.log("   To push later, run:");
+    console.log("     git remote add origin <url>");
+    console.log("     git push -u origin main --tags");
+  }
+
+  console.log(`\n✅ Successfully released fluxdom@${version}!\n`);
+}
+
+/**
+ * Full publish (for automation tokens)
+ */
+function fullPublish(versionType) {
+  console.log("🚀 Full publish workflow...\n");
+
+  // Pre-publish steps
+  console.log("1️⃣  Running tests...");
+  exec("npm test");
+
+  console.log("\n2️⃣  Building...");
+  exec("npm run build");
+
+  const newVersion = bumpVersion(versionType);
+  console.log(`✅ Version bumped to ${newVersion}`);
+
+  // Publish
+  console.log("\n3️⃣  Publishing to npm...");
+  exec("npm publish");
+
+  // Post-publish steps
+  console.log("\n4️⃣  Creating git commit and tag...");
+  exec("git add package.json");
+  exec(`git commit -m "chore: release v${newVersion}"`);
+  exec(`git tag v${newVersion}`);
+
+  // Push to git (skip if no remote)
+  if (hasGitRemote()) {
+    console.log("\n5️⃣  Pushing to git...");
+    exec("git push");
+    exec("git push --tags");
+  } else {
+    console.log("\n⚠️  No git remote configured. Skipping push.");
+  }
+
+  console.log(`\n✅ Successfully published fluxdom@${newVersion}!\n`);
+}
+
+// Main
+const command = process.argv[2];
+const versionType = process.argv[3];
+
+switch (command) {
+  case "pre":
+    if (!versionType) {
+      console.error(
+        "❌ Usage: node scripts/publish.js pre <patch|minor|major>"
+      );
+      process.exit(1);
+    }
+    prepublish(versionType);
+    break;
+
+  case "post":
+    postpublish();
+    break;
+
+  case "full":
+    if (!versionType) {
+      console.error(
+        "❌ Usage: node scripts/publish.js full <patch|minor|major>"
+      );
+      process.exit(1);
+    }
+    fullPublish(versionType);
+    break;
+
+  default:
+    console.error("❌ Usage:");
+    console.error("  node scripts/publish.js pre <patch|minor|major>");
+    console.error("  node scripts/publish.js post");
+    console.error("  node scripts/publish.js full <patch|minor|major>");
+    process.exit(1);
+}