@navios/di-react 0.1.1 → 0.2.0

package/lib/index.js

@@ -1,394 +1,595 @@
-'use strict';
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
 
-var react = require('react');
-var jsxRuntime = require('react/jsx-runtime');
+//#region src/providers/context.mts
+/**
+* Context for the root Container.
+* This is set by ContainerProvider and provides the base container.
+*/
+const ContainerContext = (0, react.createContext)(null);
+/**
+* Context for the current ScopedContainer (if inside a ScopeProvider).
+* This allows nested components to access request-scoped services.
+*/
+const ScopedContainerContext = (0, react.createContext)(null);
 
-// src/providers/context.mts
-var ContainerContext = react.createContext(null);
-function ContainerProvider({
-  container,
-  children
-}) {
-  return jsxRuntime.jsx(ContainerContext.Provider, { value: container, children });
+//#endregion
+//#region src/providers/container-provider.mts
+function ContainerProvider({ container, children }) {
+	return (0, react_jsx_runtime.jsx)(ContainerContext.Provider, {
+		value: container,
+		children
+	});
 }
-function useContainer() {
-  const container = react.useContext(ContainerContext);
-  if (!container) {
-    throw new Error("useContainer must be used within a ContainerProvider");
-  }
-  return container;
+
+//#endregion
+//#region src/providers/scope-provider.mts
+/**
+* ScopeProvider creates a new request scope for dependency injection.
+*
+* Services with `scope: 'Request'` will be instantiated once per ScopeProvider
+* and shared among all components within that provider.
+*
+* This is useful for:
+* - Table rows that need isolated state
+* - Modal dialogs with their own service instances
+* - Multi-tenant scenarios
+* - Any case where you need isolated service instances
+*
+* @example
+* ```tsx
+* // Each row gets its own RowStateService instance
+* {rows.map(row => (
+*   <ScopeProvider key={row.id} scopeId={row.id} metadata={{ rowData: row }}>
+*     <TableRow />
+*   </ScopeProvider>
+* ))}
+* ```
+*/
+function ScopeProvider({ scopeId, metadata, priority = 100, children }) {
+	const container = (0, react.useContext)(ContainerContext);
+	if (!container) throw new Error("ScopeProvider must be used within a ContainerProvider");
+	const generatedId = (0, react.useId)();
+	const effectiveScopeId = scopeId ?? generatedId;
+	const scopedContainerRef = (0, react.useRef)(null);
+	if (!scopedContainerRef.current) {
+		if (!container.hasActiveRequest(effectiveScopeId)) scopedContainerRef.current = container.beginRequest(effectiveScopeId, metadata, priority);
+	}
+	(0, react.useEffect)(() => {
+		const scopedContainer = scopedContainerRef.current;
+		return () => {
+			if (scopedContainer) scopedContainer.endRequest();
+		};
+	}, []);
+	if (!scopedContainerRef.current) return null;
+	return (0, react_jsx_runtime.jsx)(ScopedContainerContext.Provider, {
+		value: scopedContainerRef.current,
+		children
+	});
 }
 
-// src/providers/scope-provider.mts
-var ScopeContext = react.createContext(null);
-function ScopeProvider({
-  scopeId,
-  metadata,
-  priority = 100,
-  children
-}) {
-  const container = useContainer();
-  const generatedId = react.useId();
-  const effectiveScopeId = scopeId ?? generatedId;
-  const isInitializedRef = react.useRef(false);
-  if (!isInitializedRef.current) {
-    const existingContexts = container.getServiceLocator().getRequestContexts();
-    if (!existingContexts.has(effectiveScopeId)) {
-      container.beginRequest(effectiveScopeId, metadata, priority);
-    }
-    isInitializedRef.current = true;
-  }
-  react.useEffect(() => {
-    return () => {
-      void container.endRequest(effectiveScopeId);
-    };
-  }, [container, effectiveScopeId]);
-  return jsxRuntime.jsx(ScopeContext.Provider, { value: effectiveScopeId, children });
+//#endregion
+//#region src/hooks/use-container.mts
+/**
+* Hook to get the current container (ScopedContainer if inside ScopeProvider, otherwise Container).
+*
+* This is the primary hook for accessing the DI container. It automatically
+* returns the correct container based on context:
+* - Inside a ScopeProvider: returns the ScopedContainer for request-scoped services
+* - Outside a ScopeProvider: returns the root Container
+*
+* @returns The current container (ScopedContainer or Container)
+*/
+function useContainer() {
+	const scopedContainer = (0, react.useContext)(ScopedContainerContext);
+	const container = (0, react.useContext)(ContainerContext);
+	if (scopedContainer) return scopedContainer;
+	if (!container) throw new Error("useContainer must be used within a ContainerProvider");
+	return container;
+}
+/**
+* Hook to get the root Container, regardless of whether we're inside a ScopeProvider.
+*
+* Use this when you need access to the root container specifically,
+* for example to create new request scopes programmatically.
+*
+* @returns The root Container
+*/
+function useRootContainer() {
+	const container = (0, react.useContext)(ContainerContext);
+	if (!container) throw new Error("useRootContainer must be used within a ContainerProvider");
+	return container;
 }
+
+//#endregion
+//#region src/hooks/use-service.mts
 function serviceReducer(state, action) {
-  switch (action.type) {
-    case "loading":
-      return { status: "loading" };
-    case "success":
-      return { status: "success", data: action.data };
-    case "error":
-      return { status: "error", error: action.error };
-    case "reset":
-      return { status: "idle" };
-    default:
-      return state;
-  }
+	switch (action.type) {
+		case "loading": return { status: "loading" };
+		case "success": return {
+			status: "success",
+			data: action.data
+		};
+		case "error": return {
+			status: "error",
+			error: action.error
+		};
+		case "reset": return { status: "idle" };
+		default: return state;
+	}
 }
 function useService(token, args) {
-  const container = useContainer();
-  const serviceLocator = container.getServiceLocator();
-  const scopeId = react.useContext(ScopeContext);
-  const [state, dispatch] = react.useReducer(serviceReducer, { status: "idle" });
-  const instanceNameRef = react.useRef(null);
-  const [refetchCounter, setRefetchCounter] = react.useState(0);
-  {
-    const argsRef = react.useRef(args);
-    react.useEffect(() => {
-      if (argsRef.current !== args) {
-        if (JSON.stringify(argsRef.current) === JSON.stringify(args)) {
-          console.log(`WARNING: useService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
+	const container = useContainer();
+	const serviceLocator = useRootContainer().getServiceLocator();
+	const initialSyncInstanceRef = (0, react.useRef)(void 0);
+	const isFirstRenderRef = (0, react.useRef)(true);
+	if (isFirstRenderRef.current) {
+		initialSyncInstanceRef.current = container.tryGetSync(token, args);
+		isFirstRenderRef.current = false;
+	}
+	const [state, dispatch] = (0, react.useReducer)(serviceReducer, initialSyncInstanceRef.current ? {
+		status: "success",
+		data: initialSyncInstanceRef.current
+	} : { status: "idle" });
+	const instanceNameRef = (0, react.useRef)(null);
+	const [refetchCounter, setRefetchCounter] = (0, react.useState)(0);
+	if (process.env.NODE_ENV === "development") {
+		const argsRef = (0, react.useRef)(args);
+		(0, react.useEffect)(() => {
+			if (argsRef.current !== args) {
+				if (JSON.stringify(argsRef.current) === JSON.stringify(args)) console.log(`WARNING: useService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
           This is likely because you are using not memoized value that is not stable.
           Please use a memoized value or use a different approach to pass the args.
           Example:
           const args = useMemo(() => ({ userId: '123' }), [])
           return useService(UserToken, args)
           `);
-        }
-        argsRef.current = args;
-      }
-    }, [args]);
-  }
-  react.useEffect(() => {
-    const eventBus = serviceLocator.getEventBus();
-    let unsubscribe;
-    let isMounted = true;
-    const fetchAndSubscribe = async () => {
-      try {
-        if (scopeId) {
-          const requestContexts = serviceLocator.getRequestContexts();
-          if (requestContexts.has(scopeId)) {
-            container.setCurrentRequestContext(scopeId);
-          }
-        }
-        const instance = await container.get(
-          // @ts-expect-error - token is valid
-          token,
-          args
-        );
-        if (!isMounted) return;
-        const instanceName = serviceLocator.getInstanceIdentifier(
-          token,
-          args
-        );
-        instanceNameRef.current = instanceName;
-        dispatch({ type: "success", data: instance });
-        unsubscribe = eventBus.on(instanceName, "destroy", () => {
-          if (isMounted) {
-            dispatch({ type: "loading" });
-            void fetchAndSubscribe();
-          }
-        });
-      } catch (error) {
-        if (isMounted) {
-          dispatch({ type: "error", error });
-        }
-      }
-    };
-    dispatch({ type: "loading" });
-    void fetchAndSubscribe();
-    return () => {
-      isMounted = false;
-      unsubscribe?.();
-    };
-  }, [container, serviceLocator, token, args, scopeId, refetchCounter]);
-  const refetch = react.useCallback(() => {
-    setRefetchCounter((c) => c + 1);
-  }, []);
-  return {
-    data: state.status === "success" ? state.data : void 0,
-    error: state.status === "error" ? state.error : void 0,
-    isLoading: state.status === "loading",
-    isSuccess: state.status === "success",
-    isError: state.status === "error",
-    refetch
-  };
+				argsRef.current = args;
+			}
+		}, [args]);
+	}
+	(0, react.useEffect)(() => {
+		const eventBus = serviceLocator.getEventBus();
+		let unsubscribe;
+		let isMounted = true;
+		const fetchAndSubscribe = async () => {
+			try {
+				const instance = await container.get(token, args);
+				if (!isMounted) return;
+				const instanceName = serviceLocator.getInstanceIdentifier(token, args);
+				instanceNameRef.current = instanceName;
+				dispatch({
+					type: "success",
+					data: instance
+				});
+				unsubscribe = eventBus.on(instanceName, "destroy", () => {
+					if (isMounted) {
+						dispatch({ type: "loading" });
+						fetchAndSubscribe();
+					}
+				});
+			} catch (error) {
+				if (isMounted) dispatch({
+					type: "error",
+					error
+				});
+			}
+		};
+		if (initialSyncInstanceRef.current && refetchCounter === 0) {
+			const instanceName = serviceLocator.getInstanceIdentifier(token, args);
+			instanceNameRef.current = instanceName;
+			unsubscribe = eventBus.on(instanceName, "destroy", () => {
+				if (isMounted) {
+					dispatch({ type: "loading" });
+					fetchAndSubscribe();
+				}
+			});
+		} else {
+			dispatch({ type: "loading" });
+			fetchAndSubscribe();
+		}
+		return () => {
+			isMounted = false;
+			unsubscribe?.();
+		};
+	}, [
+		container,
+		serviceLocator,
+		token,
+		args,
+		refetchCounter
+	]);
+	const refetch = (0, react.useCallback)(() => {
+		setRefetchCounter((c) => c + 1);
+	}, []);
+	return {
+		data: state.status === "success" ? state.data : void 0,
+		error: state.status === "error" ? state.error : void 0,
+		isLoading: state.status === "loading",
+		isSuccess: state.status === "success",
+		isError: state.status === "error",
+		refetch
+	};
 }
-var cacheMap = /* @__PURE__ */ new WeakMap();
+
+//#endregion
+//#region src/hooks/use-suspense-service.mts
+const cacheMap = /* @__PURE__ */ new WeakMap();
 function getCacheKey(token, args) {
-  const tokenId = typeof token === "function" ? token.name : token.id || token.token?.id || String(token);
-  return `${tokenId}:${JSON.stringify(args ?? null)}`;
+	return `${typeof token === "function" ? token.name : token.id || token.token?.id || String(token)}:${JSON.stringify(args ?? null)}`;
 }
 function getCache(container) {
-  let cache = cacheMap.get(container);
-  if (!cache) {
-    cache = /* @__PURE__ */ new Map();
-    cacheMap.set(container, cache);
-  }
-  return cache;
+	let cache = cacheMap.get(container);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		cacheMap.set(container, cache);
+	}
+	return cache;
+}
+/**
+* Sets up invalidation subscription for a cache entry if not already subscribed.
+* When the service is destroyed, clears the cache and notifies subscribers.
+*/
+function setupInvalidationSubscription(entry, serviceLocator) {
+	if (entry.unsubscribe || !entry.instanceName) return;
+	entry.unsubscribe = serviceLocator.getEventBus().on(entry.instanceName, "destroy", () => {
+		entry.result = void 0;
+		entry.error = void 0;
+		entry.status = "pending";
+		entry.promise = null;
+		entry.subscribers.forEach((callback) => callback());
+	});
 }
 function useSuspenseService(token, args) {
-  const container = useContainer();
-  const serviceLocator = container.getServiceLocator();
-  const cache = getCache(container);
-  const cacheKey = getCacheKey(token, args);
-  const entryRef = react.useRef(null);
-  {
-    const argsRef = react.useRef(args);
-    react.useEffect(() => {
-      if (argsRef.current !== args) {
-        if (JSON.stringify(argsRef.current) === JSON.stringify(args)) {
-          console.log(`WARNING: useService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
+	const container = useContainer();
+	const serviceLocator = useRootContainer().getServiceLocator();
+	const cache = getCache(container);
+	const cacheKey = getCacheKey(token, args);
+	const entryRef = (0, react.useRef)(null);
+	if (process.env.NODE_ENV === "development") {
+		const argsRef = (0, react.useRef)(args);
+		(0, react.useEffect)(() => {
+			if (argsRef.current !== args) {
+				if (JSON.stringify(argsRef.current) === JSON.stringify(args)) console.log(`WARNING: useService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
           This is likely because you are using not memoized value that is not stable.
           Please use a memoized value or use a different approach to pass the args.
           Example:
           const args = useMemo(() => ({ userId: '123' }), [])
           return useService(UserToken, args)
           `);
-        }
-        argsRef.current = args;
-      }
-    }, [args]);
-  }
-  if (!cache.has(cacheKey)) {
-    const entry2 = {
-      promise: null,
-      result: void 0,
-      error: void 0,
-      status: "pending",
-      version: 0,
-      subscribers: /* @__PURE__ */ new Set(),
-      instanceName: null,
-      unsubscribe: void 0
-    };
-    cache.set(cacheKey, entry2);
-  }
-  const entry = cache.get(cacheKey);
-  entryRef.current = entry;
-  const fetchService = react.useCallback(() => {
-    const currentEntry = entryRef.current;
-    if (!currentEntry) return;
-    currentEntry.status = "pending";
-    currentEntry.version++;
-    currentEntry.promise = container.get(token, args).then((instance) => {
-      currentEntry.result = instance;
-      currentEntry.status = "resolved";
-      currentEntry.instanceName = serviceLocator.getInstanceIdentifier(
-        token,
-        args
-      );
-      if (!currentEntry.unsubscribe && currentEntry.instanceName) {
-        const eventBus = serviceLocator.getEventBus();
-        currentEntry.unsubscribe = eventBus.on(
-          currentEntry.instanceName,
-          "destroy",
-          () => {
-            currentEntry.result = void 0;
-            currentEntry.error = void 0;
-            currentEntry.status = "pending";
-            currentEntry.promise = null;
-            currentEntry.subscribers.forEach((callback) => callback());
-          }
-        );
-      }
-      currentEntry.subscribers.forEach((callback) => callback());
-      return instance;
-    }).catch((error) => {
-      currentEntry.error = error;
-      currentEntry.status = "rejected";
-      throw error;
-    });
-    return currentEntry.promise;
-  }, [container, serviceLocator, token, args]);
-  const subscribe = react.useCallback(
-    (callback) => {
-      entry.subscribers.add(callback);
-      return () => {
-        entry.subscribers.delete(callback);
-      };
-    },
-    [entry]
-  );
-  const getSnapshot = react.useCallback(() => {
-    return `${entry.status}:${entry.version}`;
-  }, [entry]);
-  react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-  react.useEffect(() => {
-    return () => {
-    };
-  }, []);
-  if (entry.status === "pending" && !entry.promise) {
-    fetchService();
-  }
-  if (entry.status === "pending") {
-    throw entry.promise;
-  }
-  if (entry.status === "rejected") {
-    throw entry.error;
-  }
-  return entry.result;
+				argsRef.current = args;
+			}
+		}, [args]);
+	}
+	if (!cache.has(cacheKey)) {
+		const syncInstance = container.tryGetSync(token, args);
+		const entry$1 = {
+			promise: null,
+			result: syncInstance ?? void 0,
+			error: void 0,
+			status: syncInstance ? "resolved" : "pending",
+			version: 0,
+			subscribers: /* @__PURE__ */ new Set(),
+			instanceName: syncInstance ? serviceLocator.getInstanceIdentifier(token, args) : null,
+			unsubscribe: void 0
+		};
+		cache.set(cacheKey, entry$1);
+	}
+	const entry = cache.get(cacheKey);
+	entryRef.current = entry;
+	const fetchService = (0, react.useCallback)(() => {
+		const currentEntry = entryRef.current;
+		if (!currentEntry) return;
+		currentEntry.status = "pending";
+		currentEntry.version++;
+		currentEntry.promise = container.get(token, args).then((instance) => {
+			currentEntry.result = instance;
+			currentEntry.status = "resolved";
+			currentEntry.instanceName = serviceLocator.getInstanceIdentifier(token, args);
+			setupInvalidationSubscription(currentEntry, serviceLocator);
+			currentEntry.subscribers.forEach((callback) => callback());
+			return instance;
+		}).catch((error) => {
+			currentEntry.error = error;
+			currentEntry.status = "rejected";
+			throw error;
+		});
+		return currentEntry.promise;
+	}, [
+		container,
+		serviceLocator,
+		token,
+		args
+	]);
+	const subscribe = (0, react.useCallback)((callback) => {
+		entry.subscribers.add(callback);
+		return () => {
+			entry.subscribers.delete(callback);
+		};
+	}, [entry]);
+	const getSnapshot = (0, react.useCallback)(() => {
+		return `${entry.status}:${entry.version}`;
+	}, [entry]);
+	(0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+	(0, react.useEffect)(() => {
+		const currentEntry = entryRef.current;
+		if (currentEntry && currentEntry.status === "resolved" && currentEntry.instanceName && !currentEntry.unsubscribe) setupInvalidationSubscription(currentEntry, serviceLocator);
+	}, [serviceLocator, entry]);
+	if (entry.status === "pending" && !entry.promise) fetchService();
+	if (entry.status === "pending") throw entry.promise;
+	if (entry.status === "rejected") throw entry.error;
+	return entry.result;
 }
+
+//#endregion
+//#region src/hooks/use-optional-service.mts
 function optionalServiceReducer(state, action) {
-  switch (action.type) {
-    case "loading":
-      return { status: "loading" };
-    case "success":
-      return { status: "success", data: action.data };
-    case "not-found":
-      return { status: "not-found" };
-    case "error":
-      return { status: "error", error: action.error };
-    case "reset":
-      return { status: "idle" };
-    default:
-      return state;
-  }
+	switch (action.type) {
+		case "loading": return { status: "loading" };
+		case "success": return {
+			status: "success",
+			data: action.data
+		};
+		case "not-found": return { status: "not-found" };
+		case "error": return {
+			status: "error",
+			error: action.error
+		};
+		case "reset": return { status: "idle" };
+		default: return state;
+	}
 }
+/**
+* Hook to optionally load a service from the DI container.
+*
+* Unlike useService, this hook does NOT throw an error if the service is not registered.
+* Instead, it returns `isNotFound: true` when the service doesn't exist.
+*
+* This is useful for:
+* - Optional dependencies that may or may not be configured
+* - Feature flags where a service might not be available
+* - Plugins or extensions that are conditionally registered
+*
+* @example
+* ```tsx
+* function Analytics() {
+*   const { data: analytics, isNotFound } = useOptionalService(AnalyticsService)
+*
+*   if (isNotFound) {
+*     // Analytics service not configured, skip tracking
+*     return null
+*   }
+*
+*   return <AnalyticsTracker service={analytics} />
+* }
+* ```
+*/
 function useOptionalService(token, args) {
-  const container = useContainer();
-  const serviceLocator = container.getServiceLocator();
-  const [state, dispatch] = react.useReducer(optionalServiceReducer, { status: "idle" });
-  const instanceNameRef = react.useRef(null);
-  {
-    const argsRef = react.useRef(args);
-    react.useEffect(() => {
-      if (argsRef.current !== args) {
-        if (JSON.stringify(argsRef.current) === JSON.stringify(args)) {
-          console.log(`WARNING: useOptionalService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
+	const container = useContainer();
+	const serviceLocator = useRootContainer().getServiceLocator();
+	const initialSyncInstanceRef = (0, react.useRef)(void 0);
+	const isFirstRenderRef = (0, react.useRef)(true);
+	if (isFirstRenderRef.current) {
+		try {
+			initialSyncInstanceRef.current = container.tryGetSync(token, args);
+		} catch {}
+		isFirstRenderRef.current = false;
+	}
+	const [state, dispatch] = (0, react.useReducer)(optionalServiceReducer, initialSyncInstanceRef.current ? {
+		status: "success",
+		data: initialSyncInstanceRef.current
+	} : { status: "idle" });
+	const instanceNameRef = (0, react.useRef)(null);
+	if (process.env.NODE_ENV === "development") {
+		const argsRef = (0, react.useRef)(args);
+		(0, react.useEffect)(() => {
+			if (argsRef.current !== args) {
+				if (JSON.stringify(argsRef.current) === JSON.stringify(args)) console.log(`WARNING: useOptionalService called with args that look the same but are different instances: ${JSON.stringify(argsRef.current)} !== ${JSON.stringify(args)}!
           This is likely because you are using not memoized value that is not stable.
           Please use a memoized value or use a different approach to pass the args.
           Example:
           const args = useMemo(() => ({ userId: '123' }), [])
           return useOptionalService(UserToken, args)
           `);
-        }
-        argsRef.current = args;
-      }
-    }, [args]);
-  }
-  const fetchService = react.useCallback(async () => {
-    dispatch({ type: "loading" });
-    try {
-      const [error, instance] = await serviceLocator.getInstance(
-        token,
-        args
-      );
-      if (error) {
-        const errorMessage = error.message?.toLowerCase() ?? "";
-        if (errorMessage.includes("not found") || errorMessage.includes("not registered") || errorMessage.includes("no provider")) {
-          dispatch({ type: "not-found" });
-        } else {
-          dispatch({ type: "error", error });
-        }
-        return;
-      }
-      instanceNameRef.current = serviceLocator.getInstanceIdentifier(
-        token,
-        args
-      );
-      dispatch({ type: "success", data: instance });
-    } catch (error) {
-      const err = error;
-      const errorMessage = err.message?.toLowerCase() ?? "";
-      if (errorMessage.includes("not found") || errorMessage.includes("not registered") || errorMessage.includes("no provider")) {
-        dispatch({ type: "not-found" });
-      } else {
-        dispatch({ type: "error", error: err });
-      }
-    }
-  }, [serviceLocator, token, args]);
-  react.useEffect(() => {
-    const eventBus = serviceLocator.getEventBus();
-    let unsubscribe;
-    void fetchService();
-    const setupSubscription = () => {
-      if (instanceNameRef.current) {
-        unsubscribe = eventBus.on(instanceNameRef.current, "destroy", () => {
-          void fetchService();
-        });
-      }
-    };
-    const timeoutId = setTimeout(setupSubscription, 10);
-    return () => {
-      clearTimeout(timeoutId);
-      unsubscribe?.();
-    };
-  }, [fetchService, serviceLocator]);
-  return {
-    data: state.status === "success" ? state.data : void 0,
-    error: state.status === "error" ? state.error : void 0,
-    isLoading: state.status === "loading",
-    isSuccess: state.status === "success",
-    isNotFound: state.status === "not-found",
-    isError: state.status === "error",
-    refetch: fetchService
-  };
+				argsRef.current = args;
+			}
+		}, [args]);
+	}
+	const fetchService = (0, react.useCallback)(async () => {
+		dispatch({ type: "loading" });
+		try {
+			const instance = await container.get(token, args);
+			instanceNameRef.current = serviceLocator.getInstanceIdentifier(token, args);
+			dispatch({
+				type: "success",
+				data: instance
+			});
+		} catch (error) {
+			const err = error;
+			const errorMessage = err.message?.toLowerCase() ?? "";
+			if (errorMessage.includes("not found") || errorMessage.includes("not registered") || errorMessage.includes("no provider")) dispatch({ type: "not-found" });
+			else dispatch({
+				type: "error",
+				error: err
+			});
+		}
+	}, [
+		container,
+		serviceLocator,
+		token,
+		args
+	]);
+	(0, react.useEffect)(() => {
+		const eventBus = serviceLocator.getEventBus();
+		let unsubscribe;
+		if (initialSyncInstanceRef.current) {
+			instanceNameRef.current = serviceLocator.getInstanceIdentifier(token, args);
+			unsubscribe = eventBus.on(instanceNameRef.current, "destroy", () => {
+				fetchService();
+			});
+		} else {
+			fetchService();
+			const setupSubscription = () => {
+				if (instanceNameRef.current) unsubscribe = eventBus.on(instanceNameRef.current, "destroy", () => {
+					fetchService();
+				});
+			};
+			const timeoutId = setTimeout(setupSubscription, 10);
+			return () => {
+				clearTimeout(timeoutId);
+				unsubscribe?.();
+			};
+		}
+		return () => {
+			unsubscribe?.();
+		};
+	}, [
+		fetchService,
+		serviceLocator,
+		token,
+		args
+	]);
+	return {
+		data: state.status === "success" ? state.data : void 0,
+		error: state.status === "error" ? state.error : void 0,
+		isLoading: state.status === "loading",
+		isSuccess: state.status === "success",
+		isNotFound: state.status === "not-found",
+		isError: state.status === "error",
+		refetch: fetchService
+	};
 }
+
+//#endregion
+//#region src/hooks/use-invalidate.mts
 function useInvalidate(token, args) {
-  const container = useContainer();
-  const serviceLocator = container.getServiceLocator();
-  return react.useCallback(async () => {
-    const instanceName = serviceLocator.getInstanceIdentifier(token, args);
-    await serviceLocator.invalidate(instanceName);
-  }, [serviceLocator, token, args]);
+	const serviceLocator = useRootContainer().getServiceLocator();
+	return (0, react.useCallback)(async () => {
+		const instanceName = serviceLocator.getInstanceIdentifier(token, args);
+		await serviceLocator.invalidate(instanceName);
+	}, [
+		serviceLocator,
+		token,
+		args
+	]);
 }
+/**
+* Hook that returns a function to invalidate a service instance directly.
+*
+* This is useful when you have the service instance and want to invalidate it
+* without knowing its token.
+*
+* @example
+* ```tsx
+* function UserProfile() {
+*   const { data: user } = useService(UserService)
+*   const invalidateInstance = useInvalidateInstance()
+*
+*   const handleRefresh = () => {
+*     if (user) {
+*       invalidateInstance(user)
+*     }
+*   }
+*
+*   return (
+*     <div>
+*       <span>{user?.name}</span>
+*       <button onClick={handleRefresh}>Refresh</button>
+*     </div>
+*   )
+* }
+* ```
+*/
 function useInvalidateInstance() {
-  const container = useContainer();
-  return react.useCallback(
-    async (instance) => {
-      await container.invalidate(instance);
-    },
-    [container]
-  );
+	const container = useContainer();
+	return (0, react.useCallback)(async (instance) => {
+		await container.invalidate(instance);
+	}, [container]);
 }
+
+//#endregion
+//#region src/hooks/use-scope.mts
+/**
+* Hook to get the current scope ID.
+* Returns null if not inside a ScopeProvider.
+*/
 function useScope() {
-  return react.useContext(ScopeContext);
+	return (0, react.useContext)(ScopedContainerContext)?.getRequestId() ?? null;
 }
+/**
+* Hook to get the current scope ID, throwing if not inside a ScopeProvider.
+* Use this when your component requires a scope to function correctly.
+*/
 function useScopeOrThrow() {
-  const scope = useScope();
-  if (scope === null) {
-    throw new Error(
-      "useScopeOrThrow must be used within a ScopeProvider. Wrap your component tree with <ScopeProvider> to create a request scope."
-    );
-  }
-  return scope;
+	const scopeId = useScope();
+	if (scopeId === null) throw new Error("useScopeOrThrow must be used within a ScopeProvider. Wrap your component tree with <ScopeProvider> to create a request scope.");
+	return scopeId;
+}
+/**
+* Hook to get the current ScopedContainer.
+* Returns null if not inside a ScopeProvider.
+*
+* Use this to access scope metadata or other ScopedContainer methods.
+*
+* @example
+* ```tsx
+* function TableRow() {
+*   const scope = useScopedContainer()
+*   const rowData = scope?.getMetadata('rowData')
+*   // ...
+* }
+* ```
+*/
+function useScopedContainer() {
+	return (0, react.useContext)(ScopedContainerContext);
+}
+/**
+* Hook to get the current ScopedContainer, throwing if not inside a ScopeProvider.
+* Use this when your component requires a scope to function correctly.
+*/
+function useScopedContainerOrThrow() {
+	const scopedContainer = useScopedContainer();
+	if (scopedContainer === null) throw new Error("useScopedContainerOrThrow must be used within a ScopeProvider. Wrap your component tree with <ScopeProvider> to create a request scope.");
+	return scopedContainer;
+}
+/**
+* Hook to get metadata from the current scope.
+* Returns undefined if not inside a ScopeProvider or if the key doesn't exist.
+*
+* @example
+* ```tsx
+* // In parent component:
+* <ScopeProvider metadata={{ userId: '123', theme: 'dark' }}>
+*   <ChildComponent />
+* </ScopeProvider>
+*
+* // In child component:
+* function ChildComponent() {
+*   const userId = useScopeMetadata<string>('userId')
+*   const theme = useScopeMetadata<'light' | 'dark'>('theme')
+*   // ...
+* }
+* ```
+*/
+function useScopeMetadata(key) {
+	return (0, react.useContext)(ScopedContainerContext)?.getMetadata(key);
 }
 
+//#endregion
 exports.ContainerContext = ContainerContext;
 exports.ContainerProvider = ContainerProvider;
-exports.ScopeContext = ScopeContext;
 exports.ScopeProvider = ScopeProvider;
+exports.ScopedContainerContext = ScopedContainerContext;
 exports.useContainer = useContainer;
 exports.useInvalidate = useInvalidate;
 exports.useInvalidateInstance = useInvalidateInstance;
 exports.useOptionalService = useOptionalService;
+exports.useRootContainer = useRootContainer;
 exports.useScope = useScope;
+exports.useScopeMetadata = useScopeMetadata;
 exports.useScopeOrThrow = useScopeOrThrow;
+exports.useScopedContainer = useScopedContainer;
+exports.useScopedContainerOrThrow = useScopedContainerOrThrow;
 exports.useService = useService;
 exports.useSuspenseService = useSuspenseService;
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map