@navios/di-react 0.1.0 → 0.2.0

package/lib/index.mjs

@@ -1,392 +1,580 @@
-import { createContext, createElement, useContext, useId, useRef, useEffect, useReducer, useState, useCallback, useSyncExternalStore } from 'react';
+import { createContext, useCallback, useContext, useEffect, useId, useReducer, useRef, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
 
-// src/providers/context.mts
-var ContainerContext = createContext(null);
-function ContainerProvider({
-  container,
-  children
-}) {
-  return createElement(
-    ContainerContext.Provider,
-    { value: container },
-    children
-  );
+//#region src/providers/context.mts
+/**
+* Context for the root Container.
+* This is set by ContainerProvider and provides the base container.
+*/
+const ContainerContext = createContext(null);
+/**
+* Context for the current ScopedContainer (if inside a ScopeProvider).
+* This allows nested components to access request-scoped services.
+*/
+const ScopedContainerContext = createContext(null);
+
+//#endregion
+//#region src/providers/container-provider.mts
+function ContainerProvider({ container, children }) {
+	return jsx(ContainerContext.Provider, {
+		value: container,
+		children
+	});
 }
-function useContainer() {
-  const container = 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 = useContext(ContainerContext);
+	if (!container) throw new Error("ScopeProvider must be used within a ContainerProvider");
+	const generatedId = useId();
+	const effectiveScopeId = scopeId ?? generatedId;
+	const scopedContainerRef = useRef(null);
+	if (!scopedContainerRef.current) {
+		if (!container.hasActiveRequest(effectiveScopeId)) scopedContainerRef.current = container.beginRequest(effectiveScopeId, metadata, priority);
+	}
+	useEffect(() => {
+		const scopedContainer = scopedContainerRef.current;
+		return () => {
+			if (scopedContainer) scopedContainer.endRequest();
+		};
+	}, []);
+	if (!scopedContainerRef.current) return null;
+	return jsx(ScopedContainerContext.Provider, {
+		value: scopedContainerRef.current,
+		children
+	});
 }
 
-// src/providers/scope-provider.mts
-var ScopeContext = createContext(null);
-function ScopeProvider({
-  scopeId,
-  metadata,
-  priority = 100,
-  children
-}) {
-  const container = useContainer();
-  const generatedId = useId();
-  const effectiveScopeId = scopeId ?? generatedId;
-  const isInitializedRef = useRef(false);
-  if (!isInitializedRef.current) {
-    const existingContexts = container.getServiceLocator().getRequestContexts();
-    if (!existingContexts.has(effectiveScopeId)) {
-      container.beginRequest(effectiveScopeId, metadata, priority);
-    }
-    isInitializedRef.current = true;
-  }
-  useEffect(() => {
-    return () => {
-      void container.endRequest(effectiveScopeId);
-    };
-  }, [container, effectiveScopeId]);
-  return createElement(
-    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 = useContext(ScopedContainerContext);
+	const container = 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 = 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 = useContext(ScopeContext);
-  const [state, dispatch] = useReducer(serviceReducer, { status: "idle" });
-  const instanceNameRef = useRef(null);
-  const [refetchCounter, setRefetchCounter] = useState(0);
-  {
-    const argsRef = useRef(args);
-    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 = useRef(void 0);
+	const isFirstRenderRef = useRef(true);
+	if (isFirstRenderRef.current) {
+		initialSyncInstanceRef.current = container.tryGetSync(token, args);
+		isFirstRenderRef.current = false;
+	}
+	const [state, dispatch] = useReducer(serviceReducer, initialSyncInstanceRef.current ? {
+		status: "success",
+		data: initialSyncInstanceRef.current
+	} : { status: "idle" });
+	const instanceNameRef = useRef(null);
+	const [refetchCounter, setRefetchCounter] = useState(0);
+	{
+		const argsRef = useRef(args);
+		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]);
-  }
-  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 = 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]);
+	}
+	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 = 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 = useRef(null);
-  {
-    const argsRef = useRef(args);
-    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 = useRef(null);
+	{
+		const argsRef = useRef(args);
+		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 = 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 = useCallback(
-    (callback) => {
-      entry.subscribers.add(callback);
-      return () => {
-        entry.subscribers.delete(callback);
-      };
-    },
-    [entry]
-  );
-  const getSnapshot = useCallback(() => {
-    return `${entry.status}:${entry.version}`;
-  }, [entry]);
-  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-  useEffect(() => {
-    return () => {
-      if (entry.subscribers.size === 0) {
-        entry.unsubscribe?.();
-        cache.delete(cacheKey);
-      }
-    };
-  }, [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;
+				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 = 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 = useCallback((callback) => {
+		entry.subscribers.add(callback);
+		return () => {
+			entry.subscribers.delete(callback);
+		};
+	}, [entry]);
+	const getSnapshot = useCallback(() => {
+		return `${entry.status}:${entry.version}`;
+	}, [entry]);
+	useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	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] = useReducer(optionalServiceReducer, { status: "idle" });
-  const instanceNameRef = useRef(null);
-  {
-    const argsRef = useRef(args);
-    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 = useRef(void 0);
+	const isFirstRenderRef = useRef(true);
+	if (isFirstRenderRef.current) {
+		try {
+			initialSyncInstanceRef.current = container.tryGetSync(token, args);
+		} catch {}
+		isFirstRenderRef.current = false;
+	}
+	const [state, dispatch] = useReducer(optionalServiceReducer, initialSyncInstanceRef.current ? {
+		status: "success",
+		data: initialSyncInstanceRef.current
+	} : { status: "idle" });
+	const instanceNameRef = useRef(null);
+	{
+		const argsRef = useRef(args);
+		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 = 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]);
-  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 = 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
+	]);
+	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 useCallback(async () => {
-    const instanceName = serviceLocator.getInstanceIdentifier(token, args);
-    await serviceLocator.invalidate(instanceName);
-  }, [serviceLocator, token, args]);
+	const serviceLocator = useRootContainer().getServiceLocator();
+	return 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 useCallback(
-    async (instance) => {
-      await container.invalidate(instance);
-    },
-    [container]
-  );
+	const container = useContainer();
+	return 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 useContext(ScopeContext);
+	return 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 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 useContext(ScopedContainerContext)?.getMetadata(key);
 }
 
-export { ContainerContext, ContainerProvider, ScopeContext, ScopeProvider, useContainer, useInvalidate, useInvalidateInstance, useOptionalService, useScope, useScopeOrThrow, useService, useSuspenseService };
-//# sourceMappingURL=index.mjs.map
+//#endregion
+export { ContainerContext, ContainerProvider, ScopeProvider, ScopedContainerContext, useContainer, useInvalidate, useInvalidateInstance, useOptionalService, useRootContainer, useScope, useScopeMetadata, useScopeOrThrow, useScopedContainer, useScopedContainerOrThrow, useService, useSuspenseService };
 //# sourceMappingURL=index.mjs.map