@usefy/use-init 0.0.24

package/README.md

@@ -0,0 +1,610 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/geon0529/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-init</h1>
+
+<p align="center">
+  <strong>A powerful React hook for one-time initialization with async support, retry, timeout, and conditional execution</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-init">
+    <img src="https://img.shields.io/npm/v/@usefy/use-init.svg?style=flat-square&color=007acc" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@usefy/use-init">
+    <img src="https://img.shields.io/npm/dm/@usefy/use-init.svg?style=flat-square&color=007acc" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@usefy/use-init">
+    <img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-init?style=flat-square&color=007acc" alt="bundle size" />
+  </a>
+  <a href="https://github.com/geon0529/usefy/blob/master/LICENSE">
+    <img src="https://img.shields.io/npm/l/@usefy/use-init.svg?style=flat-square&color=007acc" alt="license" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://geon0529.github.io/usefy/?path=/docs/hooks-useinit--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`@usefy/use-init` is a React hook for executing initialization logic exactly once when a component mounts. It supports synchronous and asynchronous callbacks, automatic retry on failure, timeout handling, conditional execution, and cleanup functions. Perfect for initializing services, loading configuration, setting up subscriptions, and any one-time setup tasks.
+
+**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
+
+### Why use-init?
+
+- **Zero Dependencies** — Pure React implementation with no external dependencies
+- **TypeScript First** — Full type safety with exported interfaces
+- **One-Time Execution** — Guarantees initialization runs only once per mount
+- **Async Support** — Handles both synchronous and asynchronous initialization callbacks
+- **Cleanup Functions** — Optional cleanup function support for resource management
+- **Retry Logic** — Automatic retry with configurable attempts and delays
+- **Timeout Handling** — Built-in timeout support with custom error handling
+- **Conditional Execution** — Run initialization only when conditions are met
+- **State Tracking** — Track initialization status, loading state, and errors
+- **Manual Reinitialize** — Trigger re-initialization programmatically
+- **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks
+- **Well Tested** — Comprehensive test coverage with Vitest
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-init
+
+# yarn
+yarn add @usefy/use-init
+
+# pnpm
+pnpm add @usefy/use-init
+```
+
+### Peer Dependencies
+
+This package requires React 18 or 19:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function MyComponent() {
+  const { isInitialized, isInitializing, error } = useInit(async () => {
+    await loadConfiguration();
+    console.log("Component initialized!");
+  });
+
+  if (isInitializing) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!isInitialized) return null;
+
+  return <div>Ready!</div>;
+}
+```
+
+---
+
+## API Reference
+
+### `useInit(callback, options?)`
+
+A hook that executes initialization logic exactly once when the component mounts (or when conditions are met).
+
+#### Parameters
+
+| Parameter  | Type             | Default | Description                              |
+| ---------- | ---------------- | ------- | ---------------------------------------- |
+| `callback` | `InitCallback`   | —       | The initialization function to run       |
+| `options`  | `UseInitOptions` | `{}`    | Configuration options for initialization |
+
+#### Callback Type
+
+The callback can be:
+
+- **Synchronous**: `() => void`
+- **Asynchronous**: `() => Promise<void>`
+- **With cleanup**: `() => void | CleanupFn` or `() => Promise<void | CleanupFn>`
+
+Where `CleanupFn` is `() => void` - a function that will be called when the component unmounts or before re-initialization.
+
+#### Options
+
+| Option       | Type      | Default | Description                                         |
+| ------------ | --------- | ------- | --------------------------------------------------- |
+| `when`       | `boolean` | `true`  | Only run initialization when this condition is true |
+| `retry`      | `number`  | `0`     | Number of retry attempts on failure                 |
+| `retryDelay` | `number`  | `1000`  | Delay between retry attempts in milliseconds        |
+| `timeout`    | `number`  | —       | Timeout for initialization in milliseconds          |
+
+#### Returns `UseInitResult`
+
+| Property         | Type            | Description                                                    |
+| ---------------- | --------------- | -------------------------------------------------------------- |
+| `isInitialized`  | `boolean`       | Whether initialization has completed successfully              |
+| `isInitializing` | `boolean`       | Whether initialization is currently in progress                |
+| `error`          | `Error \| null` | Error that occurred during initialization, if any              |
+| `reinitialize`   | `() => void`    | Manually trigger re-initialization (respects `when` condition) |
+
+---
+
+## Examples
+
+### Basic Synchronous Initialization
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function BasicComponent() {
+  useInit(() => {
+    console.log("Component initialized!");
+    initializeAnalytics();
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+### Async Initialization with Status Tracking
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function DataLoader() {
+  const [data, setData] = useState(null);
+  const { isInitialized, isInitializing, error } = useInit(async () => {
+    const response = await fetch("/api/data");
+    const result = await response.json();
+    setData(result);
+  });
+
+  if (isInitializing) return <div>Loading data...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!isInitialized) return null;
+
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+### With Cleanup Function
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function SubscriptionComponent() {
+  useInit(() => {
+    const subscription = eventBus.subscribe("event", handleEvent);
+
+    // Return cleanup function
+    return () => {
+      subscription.unsubscribe();
+    };
+  });
+
+  return <div>Subscribed to events</div>;
+}
+```
+
+### Conditional Initialization
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function ConditionalComponent({ isEnabled }: { isEnabled: boolean }) {
+  const { isInitialized } = useInit(
+    () => {
+      initializeFeature();
+    },
+    { when: isEnabled }
+  );
+
+  if (!isEnabled) return <div>Feature disabled</div>;
+  if (!isInitialized) return <div>Initializing...</div>;
+
+  return <div>Feature ready!</div>;
+}
+```
+
+### With Retry Logic
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function ResilientComponent() {
+  const { isInitialized, error, reinitialize } = useInit(
+    async () => {
+      await connectToServer();
+    },
+    {
+      retry: 3,
+      retryDelay: 1000, // Wait 1 second between retries
+    }
+  );
+
+  if (error) {
+    return (
+      <div>
+        <p>Failed to connect: {error.message}</p>
+        <button onClick={reinitialize}>Retry</button>
+      </div>
+    );
+  }
+
+  if (!isInitialized) return <div>Connecting...</div>;
+
+  return <div>Connected!</div>;
+}
+```
+
+### With Timeout
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function TimeoutComponent() {
+  const { isInitialized, error } = useInit(
+    async () => {
+      await slowOperation();
+    },
+    {
+      timeout: 5000, // Fail after 5 seconds
+    }
+  );
+
+  if (error) {
+    return <div>Timeout: {error.message}</div>;
+  }
+
+  if (!isInitialized) return <div>Processing...</div>;
+
+  return <div>Completed!</div>;
+}
+```
+
+### Combined Options: Retry + Timeout + Conditional
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function AdvancedComponent({ shouldInit }: { shouldInit: boolean }) {
+  const { isInitialized, isInitializing, error, reinitialize } = useInit(
+    async () => {
+      await initializeService();
+    },
+    {
+      when: shouldInit,
+      retry: 2,
+      retryDelay: 2000,
+      timeout: 10000,
+    }
+  );
+
+  if (!shouldInit) return <div>Waiting for condition...</div>;
+  if (isInitializing) return <div>Initializing (attempt in progress)...</div>;
+  if (error) {
+    return (
+      <div>
+        <p>Error: {error.message}</p>
+        <button onClick={reinitialize}>Try Again</button>
+      </div>
+    );
+  }
+  if (!isInitialized) return <div>Not initialized</div>;
+
+  return <div>Service initialized successfully!</div>;
+}
+```
+
+### Manual Re-initialization
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function RefreshableComponent() {
+  const [refreshKey, setRefreshKey] = useState(0);
+  const { isInitialized, reinitialize } = useInit(async () => {
+    await loadData();
+  });
+
+  const handleRefresh = () => {
+    setRefreshKey((k) => k + 1);
+    reinitialize();
+  };
+
+  return (
+    <div>
+      <button onClick={handleRefresh}>Refresh Data</button>
+      {isInitialized && <div>Data loaded (key: {refreshKey})</div>}
+    </div>
+  );
+}
+```
+
+### Async Cleanup Function
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function AsyncCleanupComponent() {
+  useInit(async () => {
+    const connection = await establishConnection();
+
+    // Return async cleanup function
+    return async () => {
+      await connection.close();
+      console.log("Connection closed");
+    };
+  });
+
+  return <div>Connected</div>;
+}
+```
+
+### Initializing Multiple Services
+
+```tsx
+import { useInit } from "@usefy/use-init";
+
+function MultiServiceComponent() {
+  const analytics = useInit(() => {
+    initializeAnalytics();
+    return () => analyticsService.shutdown();
+  });
+
+  const logging = useInit(async () => {
+    await initializeLogging();
+    return () => loggingService.disconnect();
+  });
+
+  const config = useInit(async () => {
+    const config = await loadConfig();
+    return config;
+  });
+
+  const allReady =
+    analytics.isInitialized && logging.isInitialized && config.isInitialized;
+
+  if (!allReady) return <div>Initializing services...</div>;
+
+  return <div>All services ready!</div>;
+}
+```
+
+---
+
+## TypeScript
+
+This hook is written in TypeScript with full type safety.
+
+```tsx
+import {
+  useInit,
+  type UseInitOptions,
+  type UseInitResult,
+} from "@usefy/use-init";
+
+// Basic usage with type inference
+const { isInitialized } = useInit(() => {
+  console.log("Init");
+});
+
+// With options
+const options: UseInitOptions = {
+  when: true,
+  retry: 3,
+  retryDelay: 1000,
+  timeout: 5000,
+};
+
+const result: UseInitResult = useInit(async () => {
+  await initialize();
+}, options);
+
+// Cleanup function types
+useInit(() => {
+  const resource = createResource();
+  return () => {
+    // TypeScript knows this is a cleanup function
+    resource.cleanup();
+  };
+});
+```
+
+---
+
+## Behavior Details
+
+### One-Time Execution
+
+The hook guarantees that initialization runs only once per component mount. Even if the `callback` reference changes, initialization will not run again unless:
+
+- The component unmounts and remounts
+- `reinitialize()` is called manually
+- The `when` condition changes from `false` to `true` (after initial mount)
+
+### Conditional Execution (`when`)
+
+When `when` is `false`:
+
+- Initialization does not run
+- If `when` changes from `false` to `true`, initialization will run
+- If initialization was already successful, it will not run again even if `when` becomes `true` again
+
+### Retry Logic
+
+When `retry` is set to `n`, the hook will attempt initialization up to `n + 1` times (initial attempt + `n` retries). Between attempts, it waits for `retryDelay` milliseconds.
+
+### Timeout
+
+When `timeout` is set:
+
+- For async callbacks, a race condition is created between the callback and timeout
+- If timeout expires first, an `InitTimeoutError` is thrown
+- For sync callbacks, timeout is cleared immediately after execution
+
+### Cleanup Functions
+
+If the callback returns a cleanup function:
+
+- It is called when the component unmounts
+- It is called before re-initialization (when `reinitialize()` is called)
+- It can be synchronous or asynchronous
+- Only one cleanup function is stored at a time
+
+### Error Handling
+
+- Errors during initialization are caught and stored in the `error` property
+- If retry is enabled, errors trigger retry attempts
+- After all retries fail, the final error is stored
+- Errors do not prevent component rendering
+
+---
+
+## Testing
+
+This package maintains comprehensive test coverage to ensure reliability and stability.
+
+### Test Coverage
+
+📊 <a href="https://geon0529.github.io/usefy/coverage/use-init/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages)
+
+### Test Categories
+
+<details>
+<summary><strong>Basic Initialization Tests</strong></summary>
+
+- Run callback once on mount
+- Not run callback again on re-render
+- Support synchronous callbacks
+- Support asynchronous callbacks
+- Track initialization state correctly
+
+</details>
+
+<details>
+<summary><strong>Cleanup Function Tests</strong></summary>
+
+- Call cleanup function on unmount
+- Call cleanup function before re-initialization
+- Support synchronous cleanup functions
+- Support asynchronous cleanup functions
+- Handle cleanup function errors gracefully
+- Not call cleanup if callback doesn't return one
+
+</details>
+
+<details>
+<summary><strong>Conditional Execution Tests</strong></summary>
+
+- Not run when `when` is false
+- Run when `when` changes from false to true
+- Not run again if already initialized
+- Respect `when` condition in `reinitialize()`
+
+</details>
+
+<details>
+<summary><strong>Retry Logic Tests</strong></summary>
+
+- Retry on failure with correct number of attempts
+- Wait correct delay between retries
+- Stop retrying after successful attempt
+- Store final error after all retries fail
+- Not retry if component unmounts during retry
+
+</details>
+
+<details>
+<summary><strong>Timeout Tests</strong></summary>
+
+- Timeout async callbacks that exceed timeout
+- Not timeout sync callbacks
+- Clear timeout after successful execution
+- Throw InitTimeoutError on timeout
+- Handle timeout with retry logic
+
+</details>
+
+<details>
+<summary><strong>Manual Re-initialization Tests</strong></summary>
+
+- Reinitialize when `reinitialize()` is called
+- Respect `when` condition in `reinitialize()`
+- Clean up previous initialization before re-running
+- Update state correctly after re-initialization
+
+</details>
+
+<details>
+<summary><strong>State Management Tests</strong></summary>
+
+- Track `isInitializing` state correctly
+- Track `isInitialized` state correctly
+- Track `error` state correctly
+- Update state only when component is mounted
+- Handle rapid state changes correctly
+
+</details>
+
+<details>
+<summary><strong>Edge Cases Tests</strong></summary>
+
+- Handle component unmount during initialization
+- Handle component unmount during retry
+- Prevent concurrent initializations
+- Handle callback reference changes
+- Handle undefined/null errors gracefully
+
+</details>
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage report
+pnpm test --coverage
+```
+
+---
+
+## License
+
+MIT © [mirunamu](https://github.com/geon0529)
+
+This package is part of the [usefy](https://github.com/geon0529/usefy) monorepo.
+
+---
+
+<p align="center">
+  <sub>Built with care by the usefy team</sub>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,100 @@
+/**
+ * Options for useInit hook
+ */
+interface UseInitOptions {
+    /**
+     * Only run initialization when this condition is true
+     * @default true
+     */
+    when?: boolean;
+    /**
+     * Number of retry attempts on failure
+     * @default 0
+     */
+    retry?: number;
+    /**
+     * Delay between retry attempts in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Timeout for initialization in milliseconds
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+}
+/**
+ * Result object returned by useInit hook
+ */
+interface UseInitResult {
+    /**
+     * Whether initialization has completed successfully
+     */
+    isInitialized: boolean;
+    /**
+     * Whether initialization is currently in progress
+     */
+    isInitializing: boolean;
+    /**
+     * Error that occurred during initialization, if any
+     */
+    error: Error | null;
+    /**
+     * Manually trigger re-initialization (respects `when` condition)
+     */
+    reinitialize: () => void;
+}
+/**
+ * Type for cleanup function returned by init callback
+ */
+type CleanupFn = () => void;
+/**
+ * Type for init callback function
+ */
+type InitCallback = () => void | CleanupFn | Promise<void | CleanupFn>;
+/**
+ * A React hook for one-time initialization with async support, retry, timeout, and conditional execution.
+ *
+ * @param callback - The initialization function to run. Can be sync or async.
+ *                   Can optionally return a cleanup function.
+ * @param options - Configuration options for initialization
+ * @returns Object containing initialization state and control functions
+ *
+ * @example
+ * // Basic synchronous initialization
+ * useInit(() => {
+ *   console.log('Component initialized');
+ * });
+ *
+ * @example
+ * // With cleanup function
+ * useInit(() => {
+ *   const subscription = eventBus.subscribe();
+ *   return () => subscription.unsubscribe();
+ * });
+ *
+ * @example
+ * // Async initialization with status tracking
+ * const { isInitialized, isInitializing, error } = useInit(async () => {
+ *   await loadConfiguration();
+ * });
+ *
+ * @example
+ * // Conditional initialization
+ * useInit(() => {
+ *   initializeAnalytics();
+ * }, { when: isProduction });
+ *
+ * @example
+ * // With retry and timeout
+ * const { error, reinitialize } = useInit(async () => {
+ *   await connectToServer();
+ * }, {
+ *   retry: 3,
+ *   retryDelay: 1000,
+ *   timeout: 5000
+ * });
+ */
+declare function useInit(callback: InitCallback, options?: UseInitOptions): UseInitResult;
+
+export { type UseInitOptions, type UseInitResult, useInit };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Options for useInit hook
+ */
+interface UseInitOptions {
+    /**
+     * Only run initialization when this condition is true
+     * @default true
+     */
+    when?: boolean;
+    /**
+     * Number of retry attempts on failure
+     * @default 0
+     */
+    retry?: number;
+    /**
+     * Delay between retry attempts in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Timeout for initialization in milliseconds
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+}
+/**
+ * Result object returned by useInit hook
+ */
+interface UseInitResult {
+    /**
+     * Whether initialization has completed successfully
+     */
+    isInitialized: boolean;
+    /**
+     * Whether initialization is currently in progress
+     */
+    isInitializing: boolean;
+    /**
+     * Error that occurred during initialization, if any
+     */
+    error: Error | null;
+    /**
+     * Manually trigger re-initialization (respects `when` condition)
+     */
+    reinitialize: () => void;
+}
+/**
+ * Type for cleanup function returned by init callback
+ */
+type CleanupFn = () => void;
+/**
+ * Type for init callback function
+ */
+type InitCallback = () => void | CleanupFn | Promise<void | CleanupFn>;
+/**
+ * A React hook for one-time initialization with async support, retry, timeout, and conditional execution.
+ *
+ * @param callback - The initialization function to run. Can be sync or async.
+ *                   Can optionally return a cleanup function.
+ * @param options - Configuration options for initialization
+ * @returns Object containing initialization state and control functions
+ *
+ * @example
+ * // Basic synchronous initialization
+ * useInit(() => {
+ *   console.log('Component initialized');
+ * });
+ *
+ * @example
+ * // With cleanup function
+ * useInit(() => {
+ *   const subscription = eventBus.subscribe();
+ *   return () => subscription.unsubscribe();
+ * });
+ *
+ * @example
+ * // Async initialization with status tracking
+ * const { isInitialized, isInitializing, error } = useInit(async () => {
+ *   await loadConfiguration();
+ * });
+ *
+ * @example
+ * // Conditional initialization
+ * useInit(() => {
+ *   initializeAnalytics();
+ * }, { when: isProduction });
+ *
+ * @example
+ * // With retry and timeout
+ * const { error, reinitialize } = useInit(async () => {
+ *   await connectToServer();
+ * }, {
+ *   retry: 3,
+ *   retryDelay: 1000,
+ *   timeout: 5000
+ * });
+ */
+declare function useInit(callback: InitCallback, options?: UseInitOptions): UseInitResult;
+
+export { type UseInitOptions, type UseInitResult, useInit };

package/dist/index.js

@@ -0,0 +1,166 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useInit: () => useInit
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useInit.ts
+var import_react = require("react");
+var InitTimeoutError = class extends Error {
+  constructor(timeout) {
+    super(`Initialization timed out after ${timeout}ms`);
+    this.name = "InitTimeoutError";
+  }
+};
+function useInit(callback, options = {}) {
+  const { when = true, retry = 0, retryDelay = 1e3, timeout } = options;
+  const [state, setState] = (0, import_react.useState)({
+    isInitialized: false,
+    isInitializing: false,
+    error: null
+  });
+  const callbackRef = (0, import_react.useRef)(callback);
+  const cleanupRef = (0, import_react.useRef)(null);
+  const hasInitializedRef = (0, import_react.useRef)(false);
+  const mountedRef = (0, import_react.useRef)(true);
+  const initializingRef = (0, import_react.useRef)(false);
+  callbackRef.current = callback;
+  const runInit = (0, import_react.useCallback)(async () => {
+    if (initializingRef.current) {
+      return;
+    }
+    initializingRef.current = true;
+    if (cleanupRef.current) {
+      cleanupRef.current();
+      cleanupRef.current = null;
+    }
+    setState({
+      isInitialized: false,
+      isInitializing: true,
+      error: null
+    });
+    let lastError = null;
+    const maxAttempts = retry + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (!mountedRef.current) {
+        initializingRef.current = false;
+        return;
+      }
+      try {
+        let result;
+        if (timeout !== void 0) {
+          let timeoutId;
+          const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+              reject(new InitTimeoutError(timeout));
+            }, timeout);
+          });
+          const callbackResult = callbackRef.current();
+          if (callbackResult instanceof Promise) {
+            try {
+              result = await Promise.race([callbackResult, timeoutPromise]);
+            } finally {
+              if (timeoutId !== void 0) {
+                clearTimeout(timeoutId);
+              }
+            }
+          } else {
+            if (timeoutId !== void 0) {
+              clearTimeout(timeoutId);
+            }
+            result = callbackResult;
+          }
+        } else {
+          const callbackResult = callbackRef.current();
+          if (callbackResult instanceof Promise) {
+            result = await callbackResult;
+          } else {
+            result = callbackResult;
+          }
+        }
+        if (typeof result === "function") {
+          cleanupRef.current = result;
+        }
+        if (mountedRef.current) {
+          hasInitializedRef.current = true;
+          setState({
+            isInitialized: true,
+            isInitializing: false,
+            error: null
+          });
+        }
+        initializingRef.current = false;
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxAttempts - 1 && mountedRef.current) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+      }
+    }
+    if (mountedRef.current) {
+      setState({
+        isInitialized: false,
+        isInitializing: false,
+        error: lastError
+      });
+    }
+    initializingRef.current = false;
+  }, [retry, retryDelay, timeout]);
+  const reinitialize = (0, import_react.useCallback)(() => {
+    if (!when) {
+      return;
+    }
+    runInit();
+  }, [when, runInit]);
+  const prevWhenRef = (0, import_react.useRef)(when);
+  const hasRunOnceRef = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    mountedRef.current = true;
+    const whenJustBecameTrue = !prevWhenRef.current && when;
+    const shouldInit = when && !hasInitializedRef.current && (!hasRunOnceRef.current || whenJustBecameTrue);
+    prevWhenRef.current = when;
+    if (shouldInit) {
+      hasRunOnceRef.current = true;
+      runInit();
+    }
+    return () => {
+      mountedRef.current = false;
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+      }
+    };
+  }, [when, runInit]);
+  return {
+    isInitialized: state.isInitialized,
+    isInitializing: state.isInitializing,
+    error: state.error,
+    reinitialize
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useInit
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useInit.ts"],"sourcesContent":["export { useInit, type UseInitOptions, type UseInitResult } from \"./useInit\";\n","import { useState, useEffect, useRef, useCallback } from \"react\";\n\n/**\n * Options for useInit hook\n */\nexport interface UseInitOptions {\n  /**\n   * Only run initialization when this condition is true\n   * @default true\n   */\n  when?: boolean;\n  /**\n   * Number of retry attempts on failure\n   * @default 0\n   */\n  retry?: number;\n  /**\n   * Delay between retry attempts in milliseconds\n   * @default 1000\n   */\n  retryDelay?: number;\n  /**\n   * Timeout for initialization in milliseconds\n   * @default undefined (no timeout)\n   */\n  timeout?: number;\n}\n\n/**\n * Result object returned by useInit hook\n */\nexport interface UseInitResult {\n  /**\n   * Whether initialization has completed successfully\n   */\n  isInitialized: boolean;\n  /**\n   * Whether initialization is currently in progress\n   */\n  isInitializing: boolean;\n  /**\n   * Error that occurred during initialization, if any\n   */\n  error: Error | null;\n  /**\n   * Manually trigger re-initialization (respects `when` condition)\n   */\n  reinitialize: () => void;\n}\n\n/**\n * Type for cleanup function returned by init callback\n */\ntype CleanupFn = () => void;\n\n/**\n * Type for init callback function\n */\ntype InitCallback = () => void | CleanupFn | Promise<void | CleanupFn>;\n\n/**\n * Custom error for timeout\n */\nclass InitTimeoutError extends Error {\n  constructor(timeout: number) {\n    super(`Initialization timed out after ${timeout}ms`);\n    this.name = \"InitTimeoutError\";\n  }\n}\n\n/**\n * A React hook for one-time initialization with async support, retry, timeout, and conditional execution.\n *\n * @param callback - The initialization function to run. Can be sync or async.\n *                   Can optionally return a cleanup function.\n * @param options - Configuration options for initialization\n * @returns Object containing initialization state and control functions\n *\n * @example\n * // Basic synchronous initialization\n * useInit(() => {\n *   console.log('Component initialized');\n * });\n *\n * @example\n * // With cleanup function\n * useInit(() => {\n *   const subscription = eventBus.subscribe();\n *   return () => subscription.unsubscribe();\n * });\n *\n * @example\n * // Async initialization with status tracking\n * const { isInitialized, isInitializing, error } = useInit(async () => {\n *   await loadConfiguration();\n * });\n *\n * @example\n * // Conditional initialization\n * useInit(() => {\n *   initializeAnalytics();\n * }, { when: isProduction });\n *\n * @example\n * // With retry and timeout\n * const { error, reinitialize } = useInit(async () => {\n *   await connectToServer();\n * }, {\n *   retry: 3,\n *   retryDelay: 1000,\n *   timeout: 5000\n * });\n */\nexport function useInit(\n  callback: InitCallback,\n  options: UseInitOptions = {}\n): UseInitResult {\n  const { when = true, retry = 0, retryDelay = 1000, timeout } = options;\n\n  const [state, setState] = useState<{\n    isInitialized: boolean;\n    isInitializing: boolean;\n    error: Error | null;\n  }>({\n    isInitialized: false,\n    isInitializing: false,\n    error: null,\n  });\n\n  const callbackRef = useRef<InitCallback>(callback);\n  const cleanupRef = useRef<CleanupFn | null>(null);\n  const hasInitializedRef = useRef(false);\n  const mountedRef = useRef(true);\n  const initializingRef = useRef(false);\n\n  // Always update callback ref to latest version\n  callbackRef.current = callback;\n\n  const runInit = useCallback(async () => {\n    // Prevent concurrent initializations\n    if (initializingRef.current) {\n      return;\n    }\n\n    initializingRef.current = true;\n\n    // Clean up previous initialization if any\n    if (cleanupRef.current) {\n      cleanupRef.current();\n      cleanupRef.current = null;\n    }\n\n    setState({\n      isInitialized: false,\n      isInitializing: true,\n      error: null,\n    });\n\n    let lastError: Error | null = null;\n    const maxAttempts = retry + 1;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      if (!mountedRef.current) {\n        initializingRef.current = false;\n        return;\n      }\n\n      try {\n        let result: void | CleanupFn;\n\n        if (timeout !== undefined) {\n          // Race between callback and timeout\n          let timeoutId: ReturnType<typeof setTimeout> | undefined;\n          const timeoutPromise = new Promise<never>((_, reject) => {\n            timeoutId = setTimeout(() => {\n              reject(new InitTimeoutError(timeout));\n            }, timeout);\n          });\n\n          const callbackResult = callbackRef.current();\n\n          if (callbackResult instanceof Promise) {\n            try {\n              result = await Promise.race([callbackResult, timeoutPromise]);\n            } finally {\n              if (timeoutId !== undefined) {\n                clearTimeout(timeoutId);\n              }\n            }\n          } else {\n            if (timeoutId !== undefined) {\n              clearTimeout(timeoutId);\n            }\n            result = callbackResult;\n          }\n        } else {\n          const callbackResult = callbackRef.current();\n          if (callbackResult instanceof Promise) {\n            result = await callbackResult;\n          } else {\n            result = callbackResult;\n          }\n        }\n\n        // Store cleanup function if returned\n        if (typeof result === \"function\") {\n          cleanupRef.current = result;\n        }\n\n        if (mountedRef.current) {\n          hasInitializedRef.current = true;\n          setState({\n            isInitialized: true,\n            isInitializing: false,\n            error: null,\n          });\n        }\n\n        initializingRef.current = false;\n        return;\n      } catch (err) {\n        lastError = err instanceof Error ? err : new Error(String(err));\n\n        // If not the last attempt and still mounted, wait before retrying\n        if (attempt < maxAttempts - 1 && mountedRef.current) {\n          await new Promise((resolve) => setTimeout(resolve, retryDelay));\n        }\n      }\n    }\n\n    // All attempts failed\n    if (mountedRef.current) {\n      setState({\n        isInitialized: false,\n        isInitializing: false,\n        error: lastError,\n      });\n    }\n\n    initializingRef.current = false;\n  }, [retry, retryDelay, timeout]);\n\n  const reinitialize = useCallback(() => {\n    if (!when) {\n      return;\n    }\n    runInit();\n  }, [when, runInit]);\n\n  // Track when condition changes from false to true\n  const prevWhenRef = useRef(when);\n  const hasRunOnceRef = useRef(false);\n\n  useEffect(() => {\n    mountedRef.current = true;\n\n    // Run initialization if:\n    // 1. `when` is true AND\n    // 2. Never successfully initialized AND\n    // 3. Either first run OR `when` just changed from false to true\n    const whenJustBecameTrue = !prevWhenRef.current && when;\n    const shouldInit =\n      when &&\n      !hasInitializedRef.current &&\n      (!hasRunOnceRef.current || whenJustBecameTrue);\n\n    prevWhenRef.current = when;\n\n    if (shouldInit) {\n      hasRunOnceRef.current = true;\n      runInit();\n    }\n\n    return () => {\n      mountedRef.current = false;\n      if (cleanupRef.current) {\n        cleanupRef.current();\n        cleanupRef.current = null;\n      }\n    };\n  }, [when, runInit]);\n\n  return {\n    isInitialized: state.isInitialized,\n    isInitializing: state.isInitializing,\n    error: state.error,\n    reinitialize,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,139 @@
+// src/useInit.ts
+import { useState, useEffect, useRef, useCallback } from "react";
+var InitTimeoutError = class extends Error {
+  constructor(timeout) {
+    super(`Initialization timed out after ${timeout}ms`);
+    this.name = "InitTimeoutError";
+  }
+};
+function useInit(callback, options = {}) {
+  const { when = true, retry = 0, retryDelay = 1e3, timeout } = options;
+  const [state, setState] = useState({
+    isInitialized: false,
+    isInitializing: false,
+    error: null
+  });
+  const callbackRef = useRef(callback);
+  const cleanupRef = useRef(null);
+  const hasInitializedRef = useRef(false);
+  const mountedRef = useRef(true);
+  const initializingRef = useRef(false);
+  callbackRef.current = callback;
+  const runInit = useCallback(async () => {
+    if (initializingRef.current) {
+      return;
+    }
+    initializingRef.current = true;
+    if (cleanupRef.current) {
+      cleanupRef.current();
+      cleanupRef.current = null;
+    }
+    setState({
+      isInitialized: false,
+      isInitializing: true,
+      error: null
+    });
+    let lastError = null;
+    const maxAttempts = retry + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (!mountedRef.current) {
+        initializingRef.current = false;
+        return;
+      }
+      try {
+        let result;
+        if (timeout !== void 0) {
+          let timeoutId;
+          const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => {
+              reject(new InitTimeoutError(timeout));
+            }, timeout);
+          });
+          const callbackResult = callbackRef.current();
+          if (callbackResult instanceof Promise) {
+            try {
+              result = await Promise.race([callbackResult, timeoutPromise]);
+            } finally {
+              if (timeoutId !== void 0) {
+                clearTimeout(timeoutId);
+              }
+            }
+          } else {
+            if (timeoutId !== void 0) {
+              clearTimeout(timeoutId);
+            }
+            result = callbackResult;
+          }
+        } else {
+          const callbackResult = callbackRef.current();
+          if (callbackResult instanceof Promise) {
+            result = await callbackResult;
+          } else {
+            result = callbackResult;
+          }
+        }
+        if (typeof result === "function") {
+          cleanupRef.current = result;
+        }
+        if (mountedRef.current) {
+          hasInitializedRef.current = true;
+          setState({
+            isInitialized: true,
+            isInitializing: false,
+            error: null
+          });
+        }
+        initializingRef.current = false;
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < maxAttempts - 1 && mountedRef.current) {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+      }
+    }
+    if (mountedRef.current) {
+      setState({
+        isInitialized: false,
+        isInitializing: false,
+        error: lastError
+      });
+    }
+    initializingRef.current = false;
+  }, [retry, retryDelay, timeout]);
+  const reinitialize = useCallback(() => {
+    if (!when) {
+      return;
+    }
+    runInit();
+  }, [when, runInit]);
+  const prevWhenRef = useRef(when);
+  const hasRunOnceRef = useRef(false);
+  useEffect(() => {
+    mountedRef.current = true;
+    const whenJustBecameTrue = !prevWhenRef.current && when;
+    const shouldInit = when && !hasInitializedRef.current && (!hasRunOnceRef.current || whenJustBecameTrue);
+    prevWhenRef.current = when;
+    if (shouldInit) {
+      hasRunOnceRef.current = true;
+      runInit();
+    }
+    return () => {
+      mountedRef.current = false;
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+      }
+    };
+  }, [when, runInit]);
+  return {
+    isInitialized: state.isInitialized,
+    isInitializing: state.isInitializing,
+    error: state.error,
+    reinitialize
+  };
+}
+export {
+  useInit
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useInit.ts"],"sourcesContent":["import { useState, useEffect, useRef, useCallback } from \"react\";\n\n/**\n * Options for useInit hook\n */\nexport interface UseInitOptions {\n  /**\n   * Only run initialization when this condition is true\n   * @default true\n   */\n  when?: boolean;\n  /**\n   * Number of retry attempts on failure\n   * @default 0\n   */\n  retry?: number;\n  /**\n   * Delay between retry attempts in milliseconds\n   * @default 1000\n   */\n  retryDelay?: number;\n  /**\n   * Timeout for initialization in milliseconds\n   * @default undefined (no timeout)\n   */\n  timeout?: number;\n}\n\n/**\n * Result object returned by useInit hook\n */\nexport interface UseInitResult {\n  /**\n   * Whether initialization has completed successfully\n   */\n  isInitialized: boolean;\n  /**\n   * Whether initialization is currently in progress\n   */\n  isInitializing: boolean;\n  /**\n   * Error that occurred during initialization, if any\n   */\n  error: Error | null;\n  /**\n   * Manually trigger re-initialization (respects `when` condition)\n   */\n  reinitialize: () => void;\n}\n\n/**\n * Type for cleanup function returned by init callback\n */\ntype CleanupFn = () => void;\n\n/**\n * Type for init callback function\n */\ntype InitCallback = () => void | CleanupFn | Promise<void | CleanupFn>;\n\n/**\n * Custom error for timeout\n */\nclass InitTimeoutError extends Error {\n  constructor(timeout: number) {\n    super(`Initialization timed out after ${timeout}ms`);\n    this.name = \"InitTimeoutError\";\n  }\n}\n\n/**\n * A React hook for one-time initialization with async support, retry, timeout, and conditional execution.\n *\n * @param callback - The initialization function to run. Can be sync or async.\n *                   Can optionally return a cleanup function.\n * @param options - Configuration options for initialization\n * @returns Object containing initialization state and control functions\n *\n * @example\n * // Basic synchronous initialization\n * useInit(() => {\n *   console.log('Component initialized');\n * });\n *\n * @example\n * // With cleanup function\n * useInit(() => {\n *   const subscription = eventBus.subscribe();\n *   return () => subscription.unsubscribe();\n * });\n *\n * @example\n * // Async initialization with status tracking\n * const { isInitialized, isInitializing, error } = useInit(async () => {\n *   await loadConfiguration();\n * });\n *\n * @example\n * // Conditional initialization\n * useInit(() => {\n *   initializeAnalytics();\n * }, { when: isProduction });\n *\n * @example\n * // With retry and timeout\n * const { error, reinitialize } = useInit(async () => {\n *   await connectToServer();\n * }, {\n *   retry: 3,\n *   retryDelay: 1000,\n *   timeout: 5000\n * });\n */\nexport function useInit(\n  callback: InitCallback,\n  options: UseInitOptions = {}\n): UseInitResult {\n  const { when = true, retry = 0, retryDelay = 1000, timeout } = options;\n\n  const [state, setState] = useState<{\n    isInitialized: boolean;\n    isInitializing: boolean;\n    error: Error | null;\n  }>({\n    isInitialized: false,\n    isInitializing: false,\n    error: null,\n  });\n\n  const callbackRef = useRef<InitCallback>(callback);\n  const cleanupRef = useRef<CleanupFn | null>(null);\n  const hasInitializedRef = useRef(false);\n  const mountedRef = useRef(true);\n  const initializingRef = useRef(false);\n\n  // Always update callback ref to latest version\n  callbackRef.current = callback;\n\n  const runInit = useCallback(async () => {\n    // Prevent concurrent initializations\n    if (initializingRef.current) {\n      return;\n    }\n\n    initializingRef.current = true;\n\n    // Clean up previous initialization if any\n    if (cleanupRef.current) {\n      cleanupRef.current();\n      cleanupRef.current = null;\n    }\n\n    setState({\n      isInitialized: false,\n      isInitializing: true,\n      error: null,\n    });\n\n    let lastError: Error | null = null;\n    const maxAttempts = retry + 1;\n\n    for (let attempt = 0; attempt < maxAttempts; attempt++) {\n      if (!mountedRef.current) {\n        initializingRef.current = false;\n        return;\n      }\n\n      try {\n        let result: void | CleanupFn;\n\n        if (timeout !== undefined) {\n          // Race between callback and timeout\n          let timeoutId: ReturnType<typeof setTimeout> | undefined;\n          const timeoutPromise = new Promise<never>((_, reject) => {\n            timeoutId = setTimeout(() => {\n              reject(new InitTimeoutError(timeout));\n            }, timeout);\n          });\n\n          const callbackResult = callbackRef.current();\n\n          if (callbackResult instanceof Promise) {\n            try {\n              result = await Promise.race([callbackResult, timeoutPromise]);\n            } finally {\n              if (timeoutId !== undefined) {\n                clearTimeout(timeoutId);\n              }\n            }\n          } else {\n            if (timeoutId !== undefined) {\n              clearTimeout(timeoutId);\n            }\n            result = callbackResult;\n          }\n        } else {\n          const callbackResult = callbackRef.current();\n          if (callbackResult instanceof Promise) {\n            result = await callbackResult;\n          } else {\n            result = callbackResult;\n          }\n        }\n\n        // Store cleanup function if returned\n        if (typeof result === \"function\") {\n          cleanupRef.current = result;\n        }\n\n        if (mountedRef.current) {\n          hasInitializedRef.current = true;\n          setState({\n            isInitialized: true,\n            isInitializing: false,\n            error: null,\n          });\n        }\n\n        initializingRef.current = false;\n        return;\n      } catch (err) {\n        lastError = err instanceof Error ? err : new Error(String(err));\n\n        // If not the last attempt and still mounted, wait before retrying\n        if (attempt < maxAttempts - 1 && mountedRef.current) {\n          await new Promise((resolve) => setTimeout(resolve, retryDelay));\n        }\n      }\n    }\n\n    // All attempts failed\n    if (mountedRef.current) {\n      setState({\n        isInitialized: false,\n        isInitializing: false,\n        error: lastError,\n      });\n    }\n\n    initializingRef.current = false;\n  }, [retry, retryDelay, timeout]);\n\n  const reinitialize = useCallback(() => {\n    if (!when) {\n      return;\n    }\n    runInit();\n  }, [when, runInit]);\n\n  // Track when condition changes from false to true\n  const prevWhenRef = useRef(when);\n  const hasRunOnceRef = useRef(false);\n\n  useEffect(() => {\n    mountedRef.current = true;\n\n    // Run initialization if:\n    // 1. `when` is true AND\n    // 2. Never successfully initialized AND\n    // 3. Either first run OR `when` just changed from false to true\n    const whenJustBecameTrue = !prevWhenRef.current && when;\n    const shouldInit =\n      when &&\n      !hasInitializedRef.current &&\n      (!hasRunOnceRef.current || whenJustBecameTrue);\n\n    prevWhenRef.current = when;\n\n    if (shouldInit) {\n      hasRunOnceRef.current = true;\n      runInit();\n    }\n\n    return () => {\n      mountedRef.current = false;\n      if (cleanupRef.current) {\n        cleanupRef.current();\n        cleanupRef.current = null;\n      }\n    };\n  }, [when, runInit]);\n\n  return {\n    isInitialized: state.isInitialized,\n    isInitializing: state.isInitializing,\n    error: state.error,\n    reinitialize,\n  };\n}\n"],"mappings":";AAAA,SAAS,UAAU,WAAW,QAAQ,mBAAmB;AA+DzD,IAAM,mBAAN,cAA+B,MAAM;AAAA,EACnC,YAAY,SAAiB;AAC3B,UAAM,kCAAkC,OAAO,IAAI;AACnD,SAAK,OAAO;AAAA,EACd;AACF;AA6CO,SAAS,QACd,UACA,UAA0B,CAAC,GACZ;AACf,QAAM,EAAE,OAAO,MAAM,QAAQ,GAAG,aAAa,KAAM,QAAQ,IAAI;AAE/D,QAAM,CAAC,OAAO,QAAQ,IAAI,SAIvB;AAAA,IACD,eAAe;AAAA,IACf,gBAAgB;AAAA,IAChB,OAAO;AAAA,EACT,CAAC;AAED,QAAM,cAAc,OAAqB,QAAQ;AACjD,QAAM,aAAa,OAAyB,IAAI;AAChD,QAAM,oBAAoB,OAAO,KAAK;AACtC,QAAM,aAAa,OAAO,IAAI;AAC9B,QAAM,kBAAkB,OAAO,KAAK;AAGpC,cAAY,UAAU;AAEtB,QAAM,UAAU,YAAY,YAAY;AAEtC,QAAI,gBAAgB,SAAS;AAC3B;AAAA,IACF;AAEA,oBAAgB,UAAU;AAG1B,QAAI,WAAW,SAAS;AACtB,iBAAW,QAAQ;AACnB,iBAAW,UAAU;AAAA,IACvB;AAEA,aAAS;AAAA,MACP,eAAe;AAAA,MACf,gBAAgB;AAAA,MAChB,OAAO;AAAA,IACT,CAAC;AAED,QAAI,YAA0B;AAC9B,UAAM,cAAc,QAAQ;AAE5B,aAAS,UAAU,GAAG,UAAU,aAAa,WAAW;AACtD,UAAI,CAAC,WAAW,SAAS;AACvB,wBAAgB,UAAU;AAC1B;AAAA,MACF;AAEA,UAAI;AACF,YAAI;AAEJ,YAAI,YAAY,QAAW;AAEzB,cAAI;AACJ,gBAAM,iBAAiB,IAAI,QAAe,CAAC,GAAG,WAAW;AACvD,wBAAY,WAAW,MAAM;AAC3B,qBAAO,IAAI,iBAAiB,OAAO,CAAC;AAAA,YACtC,GAAG,OAAO;AAAA,UACZ,CAAC;AAED,gBAAM,iBAAiB,YAAY,QAAQ;AAE3C,cAAI,0BAA0B,SAAS;AACrC,gBAAI;AACF,uBAAS,MAAM,QAAQ,KAAK,CAAC,gBAAgB,cAAc,CAAC;AAAA,YAC9D,UAAE;AACA,kBAAI,cAAc,QAAW;AAC3B,6BAAa,SAAS;AAAA,cACxB;AAAA,YACF;AAAA,UACF,OAAO;AACL,gBAAI,cAAc,QAAW;AAC3B,2BAAa,SAAS;AAAA,YACxB;AACA,qBAAS;AAAA,UACX;AAAA,QACF,OAAO;AACL,gBAAM,iBAAiB,YAAY,QAAQ;AAC3C,cAAI,0BAA0B,SAAS;AACrC,qBAAS,MAAM;AAAA,UACjB,OAAO;AACL,qBAAS;AAAA,UACX;AAAA,QACF;AAGA,YAAI,OAAO,WAAW,YAAY;AAChC,qBAAW,UAAU;AAAA,QACvB;AAEA,YAAI,WAAW,SAAS;AACtB,4BAAkB,UAAU;AAC5B,mBAAS;AAAA,YACP,eAAe;AAAA,YACf,gBAAgB;AAAA,YAChB,OAAO;AAAA,UACT,CAAC;AAAA,QACH;AAEA,wBAAgB,UAAU;AAC1B;AAAA,MACF,SAAS,KAAK;AACZ,oBAAY,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAG9D,YAAI,UAAU,cAAc,KAAK,WAAW,SAAS;AACnD,gBAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,UAAU,CAAC;AAAA,QAChE;AAAA,MACF;AAAA,IACF;AAGA,QAAI,WAAW,SAAS;AACtB,eAAS;AAAA,QACP,eAAe;AAAA,QACf,gBAAgB;AAAA,QAChB,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAEA,oBAAgB,UAAU;AAAA,EAC5B,GAAG,CAAC,OAAO,YAAY,OAAO,CAAC;AAE/B,QAAM,eAAe,YAAY,MAAM;AACrC,QAAI,CAAC,MAAM;AACT;AAAA,IACF;AACA,YAAQ;AAAA,EACV,GAAG,CAAC,MAAM,OAAO,CAAC;AAGlB,QAAM,cAAc,OAAO,IAAI;AAC/B,QAAM,gBAAgB,OAAO,KAAK;AAElC,YAAU,MAAM;AACd,eAAW,UAAU;AAMrB,UAAM,qBAAqB,CAAC,YAAY,WAAW;AACnD,UAAM,aACJ,QACA,CAAC,kBAAkB,YAClB,CAAC,cAAc,WAAW;AAE7B,gBAAY,UAAU;AAEtB,QAAI,YAAY;AACd,oBAAc,UAAU;AACxB,cAAQ;AAAA,IACV;AAEA,WAAO,MAAM;AACX,iBAAW,UAAU;AACrB,UAAI,WAAW,SAAS;AACtB,mBAAW,QAAQ;AACnB,mBAAW,UAAU;AAAA,MACvB;AAAA,IACF;AAAA,EACF,GAAG,CAAC,MAAM,OAAO,CAAC;AAElB,SAAO;AAAA,IACL,eAAe,MAAM;AAAA,IACrB,gBAAgB,MAAM;AAAA,IACtB,OAAO,MAAM;AAAA,IACb;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@usefy/use-init",
+  "version": "0.0.24",
+  "description": "A React hook for one-time initialization with async support, retry, timeout, and conditional execution",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geon0529/usefy.git",
+    "directory": "packages/use-init"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "init",
+    "initialization",
+    "mount",
+    "async",
+    "retry",
+    "timeout"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}