atomirx 0.0.1

package/src/core/define.test.ts

@@ -0,0 +1,342 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { define } from "./define";
+import { onCreateHook } from "./onCreateHook";
+
+describe("define", () => {
+  const originalOnCreateHook = onCreateHook.current;
+
+  beforeEach(() => {
+    onCreateHook.current = undefined;
+  });
+
+  afterEach(() => {
+    onCreateHook.current = originalOnCreateHook;
+  });
+
+  describe("basic functionality", () => {
+    it("should create a lazy singleton", () => {
+      const creator = vi.fn(() => ({ value: 42 }));
+      const store = define(creator);
+
+      // Creator not called yet
+      expect(creator).not.toHaveBeenCalled();
+
+      // First access creates instance
+      const instance1 = store();
+      expect(creator).toHaveBeenCalledTimes(1);
+      expect(instance1.value).toBe(42);
+
+      // Second access returns same instance
+      const instance2 = store();
+      expect(creator).toHaveBeenCalledTimes(1);
+      expect(instance2).toBe(instance1);
+    });
+
+    it("should store key from options", () => {
+      const store = define(() => ({}), { key: "myStore" });
+      expect(store.key).toBe("myStore");
+    });
+
+    it("should have undefined key when not provided", () => {
+      const store = define(() => ({}));
+      expect(store.key).toBeUndefined();
+    });
+  });
+
+  describe("isInitialized", () => {
+    it("should return false before first access", () => {
+      const store = define(() => ({ value: 1 }));
+      expect(store.isInitialized()).toBe(false);
+    });
+
+    it("should return true after first access", () => {
+      const store = define(() => ({ value: 1 }));
+      store();
+      expect(store.isInitialized()).toBe(true);
+    });
+  });
+
+  describe("override", () => {
+    it("should allow overriding before initialization", () => {
+      const store = define(() => ({ value: "original" }));
+
+      store.override(() => ({ value: "overridden" }));
+
+      expect(store().value).toBe("overridden");
+    });
+
+    it("should throw if override called after initialization", () => {
+      const store = define(() => ({ value: "original" }));
+
+      // Initialize
+      store();
+
+      expect(() => {
+        store.override(() => ({ value: "overridden" }));
+      }).toThrow(
+        "Cannot override after initialization. Call override() before accessing the service."
+      );
+    });
+
+    it("should provide original factory to override function", () => {
+      const store = define(() => ({ value: 1, extra: false }));
+
+      store.override((original) => ({
+        ...original(),
+        extra: true,
+      }));
+
+      const instance = store();
+      expect(instance.value).toBe(1);
+      expect(instance.extra).toBe(true);
+    });
+
+    it("should allow wrapping original behavior", () => {
+      const store = define(() => ({
+        getValue: () => 10 as number,
+      }));
+
+      store.override((original) => {
+        const base = original();
+        return {
+          getValue: () => base.getValue() * 2,
+        };
+      });
+
+      expect(store().getValue()).toBe(20);
+    });
+  });
+
+  describe("isOverridden", () => {
+    it("should return false when not overridden", () => {
+      const store = define(() => ({}));
+      expect(store.isOverridden()).toBe(false);
+    });
+
+    it("should return true when overridden", () => {
+      const store = define(() => ({}));
+      store.override(() => ({}));
+      expect(store.isOverridden()).toBe(true);
+    });
+
+    it("should return false after reset", () => {
+      const store = define(() => ({}));
+      store.override(() => ({}));
+      store.reset();
+      expect(store.isOverridden()).toBe(false);
+    });
+  });
+
+  describe("reset", () => {
+    it("should clear override and instance", () => {
+      const creator = vi.fn(() => ({ value: "original" }));
+      const store = define(creator);
+
+      store.override(() => ({ value: "overridden" }));
+      expect(store().value).toBe("overridden");
+
+      store.reset();
+
+      // Override cleared, original creator used
+      expect(store().value).toBe("original");
+      expect(store.isOverridden()).toBe(false);
+    });
+
+    it("should call dispose if present", () => {
+      const dispose = vi.fn();
+      const store = define(() => ({
+        value: 1,
+        dispose,
+      }));
+
+      store(); // Initialize
+      store.reset();
+
+      expect(dispose).toHaveBeenCalledTimes(1);
+    });
+
+    it("should allow re-initialization after reset", () => {
+      const creator = vi.fn(() => ({ value: Math.random() }));
+      const store = define(creator);
+
+      const first = store();
+      store.reset();
+      const second = store();
+
+      expect(first).not.toBe(second);
+      expect(creator).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("invalidate", () => {
+    it("should clear instance and allow re-creation", () => {
+      let counter = 0;
+      const store = define(() => ({ id: ++counter }));
+
+      expect(store().id).toBe(1);
+      expect(store().id).toBe(1); // Same instance
+
+      store.invalidate();
+
+      expect(store().id).toBe(2); // New instance
+    });
+
+    it("should call dispose if present", () => {
+      const dispose = vi.fn();
+      const store = define(() => ({
+        value: 1,
+        dispose,
+      }));
+
+      store(); // Initialize
+      store.invalidate();
+
+      expect(dispose).toHaveBeenCalledTimes(1);
+    });
+
+    it("should also clear override", () => {
+      const store = define(() => ({ value: "original" }));
+
+      store.override(() => ({ value: "overridden" }));
+      expect(store().value).toBe("overridden");
+
+      store.invalidate();
+
+      expect(store.isOverridden()).toBe(false);
+      expect(store().value).toBe("original");
+    });
+  });
+
+  describe("dispose handling", () => {
+    it("should not throw if dispose is not a function", () => {
+      const store = define(() => ({
+        value: 1,
+        dispose: "not a function",
+      }));
+
+      store();
+
+      expect(() => store.reset()).not.toThrow();
+    });
+
+    it("should not throw if instance has no dispose", () => {
+      const store = define(() => ({ value: 1 }));
+
+      store();
+
+      expect(() => store.reset()).not.toThrow();
+    });
+
+    it("should handle null instance gracefully", () => {
+      const store = define(() => ({ value: 1 }));
+
+      // Reset without initialization
+      expect(() => store.reset()).not.toThrow();
+    });
+  });
+
+  describe("onCreateHook", () => {
+    it("should call onCreateHook when module is created", () => {
+      const hookFn = vi.fn();
+      onCreateHook.current = hookFn;
+
+      const store = define(() => ({ value: 42 }), { key: "testModule" });
+      const instance = store();
+
+      expect(hookFn).toHaveBeenCalledTimes(1);
+      expect(hookFn).toHaveBeenCalledWith({
+        type: "module",
+        key: "testModule",
+        module: instance,
+      });
+    });
+
+    it("should call onCreateHook with undefined key when not provided", () => {
+      const hookFn = vi.fn();
+      onCreateHook.current = hookFn;
+
+      const store = define(() => ({ value: 42 }));
+      store();
+
+      expect(hookFn).toHaveBeenCalledWith({
+        type: "module",
+        key: undefined,
+        module: expect.any(Object),
+      });
+    });
+
+    it("should not throw when onCreateHook is undefined", () => {
+      onCreateHook.current = undefined;
+
+      const store = define(() => ({ value: 42 }));
+      expect(() => store()).not.toThrow();
+    });
+
+    it("should call onCreateHook for overridden module", () => {
+      const hookFn = vi.fn();
+      onCreateHook.current = hookFn;
+
+      const store = define(() => ({ value: "original" }));
+      store.override(() => ({ value: "overridden" }));
+      const instance = store();
+
+      expect(hookFn).toHaveBeenCalledWith({
+        type: "module",
+        key: undefined,
+        module: instance,
+      });
+    });
+  });
+
+  describe("real-world patterns", () => {
+    it("should work as a service container", () => {
+      const apiService = define(() => ({
+        baseUrl: "https://api.example.com",
+        fetch: (endpoint: string) => `${endpoint}`,
+      }));
+
+      const userService = define(() => ({
+        api: apiService(),
+        getUser: (id: number) => `user-${id}`,
+      }));
+
+      expect(userService().api.baseUrl).toBe("https://api.example.com");
+      expect(userService().getUser(1)).toBe("user-1");
+    });
+
+    it("should support testing with mocks", () => {
+      const apiService = define(() => ({
+        fetch: (url: string) => `real-${url}`,
+      }));
+
+      // In test setup
+      apiService.override(() => ({
+        fetch: vi.fn((url: string) => `mock-${url}`),
+      }));
+
+      expect(apiService().fetch("/users")).toBe("mock-/users");
+
+      // Cleanup
+      apiService.reset();
+      expect(apiService().fetch("/users")).toBe("real-/users");
+    });
+
+    it("should support platform-specific implementations", () => {
+      const storageService = define(() => ({
+        get: (key: string) => `localStorage-${key}`,
+        set: (_key: string, _value: string) => {},
+      }));
+
+      // Simulate mobile platform override
+      const isMobile = true;
+      if (isMobile) {
+        storageService.override(() => ({
+          get: (key: string) => `secureStorage-${key}`,
+          set: (_key: string, _value: string) => {},
+        }));
+      }
+
+      expect(storageService().get("token")).toBe("secureStorage-token");
+    });
+  });
+});

package/src/core/define.ts

@@ -0,0 +1,243 @@
+import { onCreateHook } from "./onCreateHook";
+import { ModuleMeta } from "./types";
+
+/**
+ * A factory function that creates a swappable lazy singleton store.
+ *
+ * @template TModule The type of the store instance
+ */
+export interface Define<TModule> {
+  readonly key: string | undefined;
+  /** Get the current service instance (creates lazily on first call) */
+  (): TModule;
+
+  /**
+   * Override the service implementation with a lazy factory.
+   * Useful for testing, platform-specific implementations, or feature flags.
+   * The factory is called lazily on first access after override.
+   *
+   * **IMPORTANT**: Must be called **before** the service is initialized.
+   * Throws an error if called after the service has been accessed.
+   *
+   * @param factory - Factory function that creates the replacement implementation.
+   *                  Receives the original factory as argument for extending.
+   *
+   * @throws {Error} If called after the service has been initialized
+   *
+   * @example Full replacement
+   * ```ts
+   * myService.override(() => ({ value: 'mock' }));
+   * ```
+   *
+   * @example Extend original
+   * ```ts
+   * myService.override((original) => ({
+   *   ...original(),
+   *   extraMethod() { ... }
+   * }));
+   * ```
+   */
+  override(factory: (original: () => TModule) => TModule): void;
+
+  /**
+   * Reset to the original implementation.
+   * Clears any override set via `.override()` and disposes the current instance.
+   * Next access will create a fresh original instance.
+   */
+  reset(): void;
+
+  /**
+   * Invalidate the cached instance. Next call will create a fresh instance.
+   * If the current instance has a `dispose()` method, it will be called before clearing.
+   *
+   * Unlike `reset()` which only clears overrides, `invalidate()` clears everything
+   * so the next access creates a completely fresh instance from the factory.
+   */
+  invalidate(): void;
+
+  /** Returns true if currently using an overridden implementation via `.override()` */
+  isOverridden(): boolean;
+
+  /** Returns true if the lazy instance has been created */
+  isInitialized(): boolean;
+}
+
+export interface DefineOptions {
+  key?: string;
+  meta?: ModuleMeta;
+}
+
+/**
+ * Creates a swappable lazy singleton store.
+ *
+ * Unlike `once()` from lodash, `define()` allows you to:
+ * - Override the implementation at runtime with `.override()`
+ * - Reset to the original with `.reset()`
+ * - Invalidate and recreate fresh with `.invalidate()`
+ *
+ * This is useful for:
+ * - **Testing** - inject mocks without module mocking
+ * - **Platform-specific** - mobile vs web implementations
+ * - **Feature flags** - swap implementations at runtime
+ *
+ * @param creator - Factory function that creates the store instance
+ * @returns A callable store with `.override()`, `.reset()`, and `.invalidate()` methods
+ *
+ * @example Basic usage
+ * ```ts
+ * const counterStore = define(() => {
+ *   const [count, setCount] = atom(0);
+ *   return {
+ *     count,
+ *     increment: () => setCount((c) => c + 1),
+ *   };
+ * });
+ *
+ * // Normal usage - lazy singleton
+ * const store = counterStore();
+ * store.increment();
+ * ```
+ *
+ * @example Platform-specific implementation
+ * ```ts
+ * const storageStore = define(() => ({
+ *   get: (key) => localStorage.getItem(key),
+ *   set: (key, value) => localStorage.setItem(key, value),
+ * }));
+ *
+ * // On mobile, swap to secure storage BEFORE first access
+ * if (isMobile()) {
+ *   storageStore.override(() => ({
+ *     get: (key) => SecureStore.getItem(key),
+ *     set: (key, value) => SecureStore.setItem(key, value),
+ *   }));
+ * }
+ * ```
+ *
+ * @example Extending original with extra methods
+ * ```ts
+ * apiStore.override((original) => ({
+ *   ...original(),
+ *   mockFetch: vi.fn(),
+ * }));
+ * ```
+ *
+ * @example Wrapping original behavior
+ * ```ts
+ * loggerStore.override((original) => {
+ *   const base = original();
+ *   return {
+ *     ...base,
+ *     log: (msg) => {
+ *       console.log('[DEBUG]', msg);
+ *       base.log(msg);
+ *     },
+ *   };
+ * });
+ * ```
+ *
+ * @example Testing with reset (creates fresh instances)
+ * ```ts
+ * beforeEach(() => {
+ *   counterStore.override(() => ({
+ *     count: () => 999,
+ *     increment: vi.fn(),
+ *   }));
+ * });
+ *
+ * afterEach(() => {
+ *   counterStore.reset(); // Clears override, next call creates fresh original
+ * });
+ * ```
+ *
+ * @example Testing with invalidate (fresh instance each test)
+ * ```ts
+ * afterEach(() => {
+ *   counterStore.invalidate(); // Next call creates fresh instance
+ * });
+ *
+ * it('test 1', () => {
+ *   counterStore().increment(); // count = 1
+ * });
+ *
+ * it('test 2', () => {
+ *   // Fresh instance, count starts at 0 again
+ *   expect(counterStore().count()).toBe(0);
+ * });
+ * ```
+ *
+ * @example Store with dispose cleanup
+ * ```ts
+ * const connectionStore = define(() => {
+ *   const connection = createConnection();
+ *   return {
+ *     query: (sql) => connection.query(sql),
+ *     dispose: () => connection.close(), // Called on invalidate()
+ *   };
+ * });
+ *
+ * connectionStore.invalidate(); // Closes connection, next call creates new
+ * ```
+ */
+export function define<T>(
+  creator: () => T,
+  options?: DefineOptions
+): Define<T> {
+  let instance: T | undefined;
+  let overrideFactory: ((original: () => T) => T) | undefined;
+
+  const tryDispose = (target: T | undefined) => {
+    if (
+      target &&
+      typeof target === "object" &&
+      "dispose" in target &&
+      typeof target.dispose === "function"
+    ) {
+      target.dispose();
+    }
+  };
+
+  const clearInstance = () => {
+    tryDispose(instance);
+    instance = undefined;
+  };
+
+  const get = (): T => {
+    if (!instance) {
+      if (overrideFactory) {
+        instance = overrideFactory!(creator);
+      } else {
+        instance = creator();
+      }
+      onCreateHook.current?.({
+        type: "module",
+        key: options?.key,
+        meta: options?.meta,
+        module: instance,
+      });
+    }
+    return instance;
+  };
+
+  return Object.assign(get, {
+    key: options?.key,
+    override: (factory: (original: () => T) => T) => {
+      if (instance !== undefined) {
+        throw new Error(
+          "Cannot override after initialization. Call override() before accessing the service."
+        );
+      }
+      overrideFactory = factory;
+    },
+    reset: () => {
+      overrideFactory = undefined;
+      clearInstance();
+    },
+    invalidate: () => {
+      overrideFactory = undefined;
+      clearInstance();
+    },
+    isOverridden: () => overrideFactory !== undefined,
+    isInitialized: () => instance !== undefined,
+  });
+}