@navios/di-react 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Oleksandr Hanzha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# @navios/di-react
+
+React integration for `@navios/di` dependency injection container.
+
+## Installation
+
+```bash
+npm install @navios/di-react @navios/di react
+# or
+yarn add @navios/di-react @navios/di react
+```
+
+## Usage
+
+### Setting up the Provider
+
+Wrap your application with `ContainerProvider` and pass a `Container` instance:
+
+```tsx
+import { Container } from '@navios/di'
+import { ContainerProvider } from '@navios/di-react'
+
+const container = new Container()
+
+function App() {
+  return (
+    <ContainerProvider container={container}>
+      <YourApp />
+    </ContainerProvider>
+  )
+}
+```
+
+### useContainer
+
+Access the container directly:
+
+```tsx
+import { useContainer } from '@navios/di-react'
+
+function MyComponent() {
+  const container = useContainer()
+
+  // Use container methods directly
+  const handleClick = async () => {
+    const service = await container.get(MyService)
+    service.doSomething()
+  }
+
+  return <button onClick={handleClick}>Do Something</button>
+}
+```
+
+### useService
+
+Fetch a service with loading/error states. Automatically re-fetches when the service is invalidated:
+
+```tsx
+import { useService } from '@navios/di-react'
+import { MyService } from './services/my-service'
+
+function MyComponent() {
+  const { data, isLoading, isError, error, refetch } = useService(MyService)
+
+  if (isLoading) return <div>Loading...</div>
+  if (isError) return <div>Error: {error?.message}</div>
+
+  return (
+    <div>
+      <p>{data.someValue}</p>
+      <button onClick={refetch}>Refresh</button>
+    </div>
+  )
+}
+```
+
+With injection tokens and arguments:
+
+```tsx
+import { InjectionToken } from '@navios/di'
+import { useService } from '@navios/di-react'
+import { z } from 'zod'
+
+const UserToken = InjectionToken.create<User, typeof UserSchema>(
+  'User',
+  z.object({ userId: z.string() })
+)
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading } = useService(UserToken, { userId })
+
+  if (isLoading) return <div>Loading...</div>
+
+  return <div>{user.name}</div>
+}
+```
+
+### useSuspenseService
+
+Use with React Suspense for a cleaner loading experience. Also subscribes to service invalidation:
+
+```tsx
+import { Suspense } from 'react'
+import { useSuspenseService } from '@navios/di-react'
+import { MyService } from './services/my-service'
+
+function MyComponent() {
+  const service = useSuspenseService(MyService)
+
+  return <div>{service.someValue}</div>
+}
+
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <MyComponent />
+    </Suspense>
+  )
+}
+```
+
+## API Reference
+
+### ContainerProvider
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `container` | `Container` | The DI container instance |
+| `children` | `ReactNode` | Child components |
+
+### useContainer
+
+```ts
+function useContainer(): Container
+```
+
+Returns the container from context. Throws if used outside of `ContainerProvider`.
+
+### useService
+
+```ts
+function useService<T>(token: ClassType | InjectionToken<T>, args?: unknown): UseServiceResult<T>
+
+interface UseServiceResult<T> {
+  data: T | undefined
+  error: Error | undefined
+  isLoading: boolean
+  isSuccess: boolean
+  isError: boolean
+  refetch: () => void
+}
+```
+
+Fetches a service asynchronously and subscribes to invalidation events. When the service is invalidated, it automatically re-fetches.
+
+### useSuspenseService
+
+```ts
+function useSuspenseService<T>(token: ClassType | InjectionToken<T>, args?: unknown): T
+```
+
+Fetches a service using React Suspense. Throws a promise during loading and the resolved value on success. Subscribes to invalidation events and triggers re-render when the service is invalidated.
+
+## Service Invalidation
+
+Both `useService` and `useSuspenseService` subscribe to the service's invalidation events via the DI container's event bus. When a service is invalidated (e.g., via `container.invalidate(service)`), the hooks will automatically:
+
+1. Clear the cached instance
+2. Re-fetch the service
+3. Update the component with the new instance
+
+This enables reactive updates when services change.
+
+## License
+
+MIT

package/lib/_tsup-dts-rollup.d.mts

@@ -0,0 +1,304 @@
+import type { BoundInjectionToken } from '@navios/di';
+import type { ClassType } from '@navios/di';
+import { Container } from '@navios/di';
+import { Context } from 'react';
+import type { Factorable } from '@navios/di';
+import type { FactoryInjectionToken } from '@navios/di';
+import { FunctionComponentElement } from 'react';
+import type { InjectionToken } from '@navios/di';
+import type { InjectionTokenSchemaType } from '@navios/di';
+import { ProviderProps } from 'react';
+import type { ReactNode } from 'react';
+import type { z } from 'zod/v4';
+import type { ZodType } from 'zod/v4';
+
+declare const ContainerContext: Context<Container | null>;
+export { ContainerContext }
+export { ContainerContext as ContainerContext_alias_1 }
+export { ContainerContext as ContainerContext_alias_2 }
+
+declare function ContainerProvider({ container, children, }: ContainerProviderProps): FunctionComponentElement<ProviderProps<Container | null>>;
+export { ContainerProvider }
+export { ContainerProvider as ContainerProvider_alias_1 }
+export { ContainerProvider as ContainerProvider_alias_2 }
+
+declare interface ContainerProviderProps {
+    container: Container;
+    children: ReactNode;
+}
+export { ContainerProviderProps }
+export { ContainerProviderProps as ContainerProviderProps_alias_1 }
+export { ContainerProviderProps as ContainerProviderProps_alias_2 }
+
+declare type InvalidatableToken = ClassType | InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>;
+
+declare type Join<T extends any[], Delimiter extends string> = T extends [] ? '' : T extends [infer First extends string | number | symbol] ? First extends string | number ? `${First}` : never : T extends [
+infer First extends string | number | symbol,
+...infer Rest extends any[]
+] ? First extends string | number ? `${First}${Delimiter}${Join<Rest, Delimiter>}` : never : '';
+export { Join }
+export { Join as Join_alias_1 }
+
+/**
+ * Context for the current scope ID.
+ * This allows nested components to access the current request scope.
+ */
+declare const ScopeContext: Context<string | null>;
+export { ScopeContext }
+export { ScopeContext as ScopeContext_alias_1 }
+export { ScopeContext as ScopeContext_alias_2 }
+
+/**
+ * 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}>
+ *     <TableRow data={row} />
+ *   </ScopeProvider>
+ * ))}
+ * ```
+ */
+declare function ScopeProvider({ scopeId, metadata, priority, children, }: ScopeProviderProps): FunctionComponentElement<ProviderProps<string | null>>;
+export { ScopeProvider }
+export { ScopeProvider as ScopeProvider_alias_1 }
+export { ScopeProvider as ScopeProvider_alias_2 }
+
+declare interface ScopeProviderProps {
+    /**
+     * Optional explicit scope ID. If not provided, a unique ID will be generated.
+     * Useful when you need to reference the scope externally.
+     */
+    scopeId?: string;
+    /**
+     * Optional metadata to attach to the request context.
+     * Can be used to pass data like user info, request headers, etc.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Priority for service resolution. Higher priority scopes take precedence.
+     * @default 100
+     */
+    priority?: number;
+    children: ReactNode;
+}
+export { ScopeProviderProps }
+export { ScopeProviderProps as ScopeProviderProps_alias_1 }
+export { ScopeProviderProps as ScopeProviderProps_alias_2 }
+
+declare type UnionToArray<T> = UnionToArrayImpl<T, never>;
+export { UnionToArray }
+export { UnionToArray as UnionToArray_alias_1 }
+
+declare type UnionToArrayImpl<T, L extends any[]> = T extends any ? UnionToArrayImpl<Exclude<T, T>, [...L, T]> : L;
+
+declare function useContainer(): Container;
+export { useContainer }
+export { useContainer as useContainer_alias_1 }
+export { useContainer as useContainer_alias_2 }
+
+/**
+ * Hook that returns a function to invalidate a service by its token.
+ *
+ * When called, this will:
+ * 1. Destroy the current service instance
+ * 2. Trigger re-fetch in all components using useService/useSuspenseService for that token
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const { data: user } = useService(UserService)
+ *   const invalidateUser = useInvalidate(UserService)
+ *
+ *   const handleRefresh = () => {
+ *     invalidateUser() // All components using UserService will re-fetch
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <span>{user?.name}</span>
+ *       <button onClick={handleRefresh}>Refresh</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useInvalidate<T extends InvalidatableToken>(token: T): () => Promise<void>;
+
+/**
+ * Hook that returns a function to invalidate a service by its token with args.
+ *
+ * @example
+ * ```tsx
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const args = useMemo(() => ({ userId }), [userId])
+ *   const { data: user } = useService(UserToken, args)
+ *   const invalidateUser = useInvalidate(UserToken, args)
+ *
+ *   return (
+ *     <div>
+ *       <span>{user?.name}</span>
+ *       <button onClick={() => invalidateUser()}>Refresh</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useInvalidate<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: S extends undefined ? never : unknown): () => Promise<void>;
+export { useInvalidate }
+export { useInvalidate as useInvalidate_alias_1 }
+export { useInvalidate as useInvalidate_alias_2 }
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+declare function useInvalidateInstance(): (instance: unknown) => Promise<void>;
+export { useInvalidateInstance }
+export { useInvalidateInstance as useInvalidateInstance_alias_1 }
+export { useInvalidateInstance as useInvalidateInstance_alias_2 }
+
+declare function useOptionalService<T extends ClassType>(token: T): UseOptionalServiceResult<InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>>;
+
+declare function useOptionalService<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): UseOptionalServiceResult<T>;
+
+declare function useOptionalService<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? UseOptionalServiceResult<T> : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
+
+declare function useOptionalService<T>(token: InjectionToken<T, undefined>): UseOptionalServiceResult<T>;
+
+declare function useOptionalService<T>(token: BoundInjectionToken<T, any>): UseOptionalServiceResult<T>;
+
+declare function useOptionalService<T>(token: FactoryInjectionToken<T, any>): UseOptionalServiceResult<T>;
+export { useOptionalService }
+export { useOptionalService as useOptionalService_alias_1 }
+export { useOptionalService as useOptionalService_alias_2 }
+
+declare interface UseOptionalServiceResult<T> {
+    /**
+     * The service instance if found and loaded successfully, otherwise undefined.
+     */
+    data: T | undefined;
+    /**
+     * Error that occurred during loading (excludes "not found" which is not an error).
+     */
+    error: Error | undefined;
+    /**
+     * True while the service is being loaded.
+     */
+    isLoading: boolean;
+    /**
+     * True if the service was loaded successfully.
+     */
+    isSuccess: boolean;
+    /**
+     * True if the service was not found (not registered in the container).
+     */
+    isNotFound: boolean;
+    /**
+     * True if an error occurred during loading.
+     */
+    isError: boolean;
+    /**
+     * Function to manually re-fetch the service.
+     */
+    refetch: () => void;
+}
+export { UseOptionalServiceResult }
+export { UseOptionalServiceResult as UseOptionalServiceResult_alias_1 }
+export { UseOptionalServiceResult as UseOptionalServiceResult_alias_2 }
+
+/**
+ * Hook to get the current scope ID.
+ * Returns null if not inside a ScopeProvider.
+ */
+declare function useScope(): string | null;
+export { useScope }
+export { useScope as useScope_alias_1 }
+export { useScope as useScope_alias_2 }
+
+/**
+ * Hook to get the current scope ID, throwing if not inside a ScopeProvider.
+ * Use this when your component requires a scope to function correctly.
+ */
+declare function useScopeOrThrow(): string;
+export { useScopeOrThrow }
+export { useScopeOrThrow as useScopeOrThrow_alias_1 }
+export { useScopeOrThrow as useScopeOrThrow_alias_2 }
+
+declare function useService<T extends ClassType>(token: T): UseServiceResult<InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>>;
+
+declare function useService<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): UseServiceResult<T>;
+
+declare function useService<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? UseServiceResult<T> : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
+
+declare function useService<T>(token: InjectionToken<T, undefined>): UseServiceResult<T>;
+
+declare function useService<T>(token: BoundInjectionToken<T, any>): UseServiceResult<T>;
+
+declare function useService<T>(token: FactoryInjectionToken<T, any>): UseServiceResult<T>;
+export { useService }
+export { useService as useService_alias_1 }
+export { useService as useService_alias_2 }
+
+declare interface UseServiceResult<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    refetch: () => void;
+}
+export { UseServiceResult }
+export { UseServiceResult as UseServiceResult_alias_1 }
+export { UseServiceResult as UseServiceResult_alias_2 }
+
+declare function useSuspenseService<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? R : InstanceType<T>;
+
+declare function useSuspenseService<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): T;
+
+declare function useSuspenseService<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? T : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
+
+declare function useSuspenseService<T>(token: InjectionToken<T, undefined>): T;
+
+declare function useSuspenseService<T>(token: BoundInjectionToken<T, any>): T;
+
+declare function useSuspenseService<T>(token: FactoryInjectionToken<T, any>): T;
+export { useSuspenseService }
+export { useSuspenseService as useSuspenseService_alias_1 }
+export { useSuspenseService as useSuspenseService_alias_2 }
+
+export { }