@adimm/x-injection-reactjs 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -1,18 +1,16 @@
 import * as react from 'react';
-import { ProviderModuleOptions, IProviderModule, IProviderModuleNaked, ProviderToken, ProviderModuleGetManyParam, ProviderModuleGetManySignature, ProviderModule } from '@adimm/x-injection';
+import react__default from 'react';
+import { IProviderModule, IProviderModuleNaked, ProviderToken, ProviderModuleGetManyParam, ProviderModuleGetManySignature, ProviderModule, ProviderModuleOptions, CloneParams } from '@adimm/x-injection';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface IComponentProviderModuleNaked extends IComponentProviderModule {
     /** Indicates if this module has been initialized by a React Component or not. */
     _initializedFromComponent: boolean;
-    /** The {@link ProviderModuleOptions | options} with which the module has been originally initialized. */
-    _initialOptions: ProviderModuleOptions;
     /**
-     * Instantiate a new {@link IComponentProviderModule} which will be supplied to the React Component.
-     *
-     * All the `providers` will be injected into a `singleton` scope.
+     * It is used internally by the `ProviderModule` to create a new cloned
+     * module which will be consumed only by that specific component instance.
      */
-    _convertToContextualizedComponentInstance(): IComponentProviderModule;
+    _createContextualizedComponentInstance(): IComponentProviderModule;
 }
 
 interface IComponentProviderModule extends IProviderModule {
@@ -30,214 +28,140 @@ interface IComponentProviderModule extends IProviderModule {
     dispose(): void;
 }
 
-interface UseInjectSharedOptions {
-}
+type PropsWithModule<P extends Record<string, any>> = P & {
+    /**
+     * The {@link IComponentProviderModule | Module} which this component should consume.
+     *
+     * **Note:** _You can easily override this in your unit tests to provide a module having mocked providers_
+     * _without the need to create a new mocked component by using the composable `ProvideModule` method._
+     */
+    module?: IComponentProviderModule;
+};
 
-/**
- * The `React.Context` value to be provided to a `React.Provider`.
- *
- * Its default value is a reference to the {@link AppModule}.
- */
-declare const REACT_X_INJECTION_CONTEXT: react.Context<{
-    ctx: IComponentProviderModule;
-}>;
-declare const REACT_X_INJECTION_EXPOSED_COMPONENT_MODULE_CONTEXT: react.Context<Map<string, IComponentProviderModule>>;
+declare const REACT_X_INJECTION_PROVIDER_MODULE_CONTEXT: react.Context<IComponentProviderModule>;
 
 /**
- * React `hook` which can be used inside a component to inject the required {@link provider | dependency}.
+ * Low-level hook which can be used to resolve a single dependency from the current
+ * context module.
  *
- * **Note:** _By using this hook, the dependency will be injected on each re-render process._
- * _If you need to inject the dependency only once, you must use the `useInject` hook._
- * _It basically acts like a `Transient` scope, ensuring that a new dependency is injected on each re-render._
+ * **Note:** _In order to better modularize your code-base, you should strive to create custom hooks by using the_
+ * _`hookFactory` method to compose a custom hook._
  *
  * @param provider The {@link ProviderToken}.
- * @param options See {@link UseInjectSharedOptions}.
- * @returns Either the {@link T | dependency} or `undefined` if {@link isOptional} is set to `true`.
+ * @param options See {@link UseInjectOptions}.
+ * @returns The resolved {@link T | dependency}.
  */
-declare function useInjectOnRender<T>(provider: ProviderToken<T>, options?: UseInjectOptions): T;
-type UseInjectOptions = UseInjectSharedOptions & {
+declare function useInject<T>(provider: ProviderToken<T>, options?: UseInjectOptions): T;
+type UseInjectOptions = {
     /** When set to `false` _(default)_ an exception will be thrown when the `providerOrIdentifier` isn't bound. */
     isOptional?: boolean;
 };
 
 /**
- * React `hook` which can be used inside a component to inject the required {@link provider | dependency}.
- *
- * **Note:** _By using this hook, the dependency will be injected only once after the first component mount process._
- * _If you need to re-inject the dependency on each re-render, you must use the `useInjectOnRender` hook._
- * _It basically acts like a `Request` scope, ensuring that even a `Transient` dependency does not mutate during re-renders._
- *
- * @param provider The {@link ProviderToken}.
- * @param options See {@link UseInjectSharedOptions}.
- * @returns Either the {@link T | dependency} or `undefined` if {@link isOptional} is set to `true`.
- */
-declare function useInject<T>(provider: ProviderToken<T>, options?: UseInjectOptions): T;
-
-/**
- * Can be used to retrieve many resolved `dependencies` from the module container at once.
- *
- * **Note:** _By using this hook, the dependencies will be injected only once after the first component mount process._
- * _If you need to re-inject the dependencies on each re-render, you must use the `useInjectManyOnRender` hook._
- *
- * @param options See {@link UseInjectSharedOptions}.
- * @param deps Either one or more {@link ProviderToken}.
- * @returns Tuple containing the {@link D | dependencies}.
- */
-declare function useInjectMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>({ deps, options, }: {
-    deps: [...(D | unknown[])];
-    options?: UseInjectSharedOptions;
-}): ProviderModuleGetManySignature<D>;
-
-/**
- * Can be used to retrieve many resolved `dependencies` from the module container at once.
+ * Low-level hook which can be used to resolve multiple dependencies at once from the current
+ * context module.
  *
- * **Note:** _By using this hook, the dependencies will be injected on each re-render process._
- * _If you need to inject the dependencies only once, you must use the `useInjectMany` hook._
+ * **Note:** _In order to better modularize your code-base, you should strive to create custom hooks by using the_
+ * _`hookFactory` method to compose a custom hook._
  *
- * @param options See {@link UseInjectSharedOptions}.
  * @param deps Either one or more {@link ProviderToken}.
  * @returns Tuple containing the {@link D | dependencies}.
  */
-declare function useInjectManyOnRender<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>({ deps, }: {
-    deps: [...(D | unknown[])];
-    options?: UseInjectSharedOptions;
-}): ProviderModuleGetManySignature<D>;
-
-declare function useExposeComponentModuleContext(): void;
-
-/**
- * This is an **experimental** hook which can be used to make sure that a component will re-render when a children
- * exposes its internal context module.
- *
- * It works best with the `useInjectOnRender` hook, as it'll re-resolve all the required dependencies
- * of the injected ProviderToken.
- *
- * **Use it carefully as it may lead to unnecessary re-render cycles or it may even not work as expected!**
- * **It's safer to use the `TapIntoComponent` wrapper component with the `contextInstance` to manually inject the**
- * **contextualized dependencies of the children into a parent component service!**
- *
- * @experimental
- */
-declare function useRerenderOnChildrenModuleContextLoaded(): void;
-
-interface ModuleProviderProps {
-    children?: React.ReactNode;
-    render?: () => React.ReactNode;
-    /** The {@link IComponentProviderModule | ComponentProviderModule} instance which must be accessible by this component. */
-    module: IComponentProviderModule;
-    /**
-     * Provide an object containing the initialization {@link ProviderModuleConstructor | options} so the {@link ModuleProviderProps.module | module}
-     * can be re-initialized when the component re-mounts _**(It'll happen only if it has been previously disposed!)**_.
-     *
-     * **Note:** _This is an advanced option and should be used only if you fully understand how the {@link ModuleProviderProps.module | module}_
-     * _initialization process works!_
-     * _For more details refer to the {@link https://adimarianmutu.github.io/x-injection/index.html | xInjection} offical docs._
-     */
-    tryReInitModuleOnMount?: ProviderModuleOptions;
-    /**
-     * When set to `true` it'll automatically dispose
-     * the provided {@link ModuleProviderProps.module | module} during the
-     * component `unmount` process.
-     *
-     * **Note:** _This is an advanced option and should be used only if you fully understand how the {@link ModuleProviderProps.module | module}_
-     * _dispose process works!_
-     * _For more details refer to the {@link https://adimarianmutu.github.io/x-injection/index.html | xInjection} offical docs._
-     *
-     * Defaults to `false`.
-     */
-    disposeModuleOnUnmount?: boolean;
-}
+declare function useInjectMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>(...deps: D | unknown[]): ProviderModuleGetManySignature<D>;
 
-declare function ModuleProvider({ children, render, module, tryReInitModuleOnMount, disposeModuleOnUnmount, }: ModuleProviderProps): react_jsx_runtime.JSX.Element;
+/** Can be used to retrieve the {@link IComponentProviderModule} from the current context. */
+declare function useComponentModule(): IComponentProviderModule;
 
 /** A superset of the {@link ProviderModule} used to integrate within a `React` component. */
 declare class ComponentProviderModule extends ProviderModule implements IComponentProviderModule {
     protected readonly _initializedFromComponent: IComponentProviderModuleNaked['_initializedFromComponent'];
-    protected readonly _initialOptions: IComponentProviderModuleNaked['_initialOptions'];
     constructor(options: ProviderModuleOptions);
     toNaked(): IComponentProviderModuleNaked & IProviderModuleNaked;
+    clone(options?: CloneParams): IComponentProviderModule;
     dispose(): void;
     /**
      * **Publicly visible when the instance is casted to {@link IComponentProviderModuleNaked}.**
      *
-     * See {@link IComponentProviderModuleNaked._convertToContextualizedComponentInstance}.
+     * See {@link IComponentProviderModuleNaked._createContextualizedComponentInstance}.
      */
-    protected _convertToContextualizedComponentInstance(): IComponentProviderModule;
+    protected _createContextualizedComponentInstance(): IComponentProviderModule;
 }
 
-interface TapIntoComponentContextProps {
-    children: React.ReactNode;
-    /**
-     * A callback can be provided to fully get access to the `ProviderModule` of the component instance,
-     * as long as the component is exposing it by using the `useExposeComponentModuleContext` hook.
-     *
-     * @param ctx A context map of modules.
-     *
-     * @example
-     * ```tsx
-     * function UserComponent(props: UserComponentProps) {
-     *   // This is required in order to correctly expose the ctx!
-     *   useExposeComponentModuleContext();
-     *
-     *   const [userProfileSettings, userSecuritySettings] = useInjectMany({ deps: [UserProfileSettings, UserSecuritySettings] });
-     *
-     *   return null;
-     * }
-     *
-     * function UserPage(props: UserPageProps) {
-     *   return (
-     *     <TapIntoComponent
-     *       contextInstance={(ctx)) => ({
-     *         tryGet: UserComponentModule,
-     *         thenDo: (ctx) => {
-     *           const services = ctx.getMany(...);
-     *         }
-     *       })}>
-     *       <UserComponent {...props.userComponentProps} />
-     *     </TapIntoComponent>
-     *   );
-     * }
-     * ```
-     *
-     * **Or without the fluid syntax:**
-     *
-     * ```tsx
-     * function UserPage(props: UserPageProps) {
-     *   return (
-     *     <TapIntoComponent
-     *       contextInstance={(ctxMap)) => {
-     *         const ctx = ctxMap.get(UserComponentModule.toString());
-     *         if (!ctx) return;
-     *
-     *         const services = ctx.getMany(...);
-     *       }}>
-     *       <UserComponent {...props.userComponentProps} />
-     *     </TapIntoComponent>
-     *   );
-     * }
-     * ````
-     */
-    contextInstance?: (ctx: Map<string, IComponentProviderModule>) => void | WithComponentInstanceCtxFluidSyntax;
-}
-interface WithComponentInstanceCtxFluidSyntax {
-    /** The {@link IComponentProviderModule | module} to look for in the `context map`. */
-    tryGet: IComponentProviderModule;
-    /**
-     * Provide a callback which will be invoked when the `context map` has
-     * the {@link tryGet | module} requested.
-     *
-     * @param module The contextualized instance of the {@link IComponentProviderModule} extracted from the children.
-     */
-    thenDo: (module: IComponentProviderModule) => void | Promise<void>;
-}
+/**
+ * Can be used to easily provide a {@link module} to any component.
+ *
+ * @example
+ * ```tsx
+ * interface MyComponentProps {
+ *   firstName: string;
+ *   lastName: string;
+ * }
+ *
+ * export const MyComponent = provideModuleToComponent(
+ *   MyComponentModule,
+ *   ({ firstName, lastName }: MyComponentProps) => {
+ *     const service = useInject(MyComponentService);
+ *
+ *     return <h1>Hello {service.computeUserName(firstName, lastName)}!</h1>
+ *   }
+ * );
+ *
+ * function App() {
+ *   return <MyComponent firstName={'John'} lastName={'Doe'} />;
+ * }
+ * ```
+ *
+ * @param module The {@link IComponentProviderModule | Module} which should be consumed by the {@link component}.
+ * @returns The provided {@link toComponent | Component}.
+ */
+declare function provideModuleToComponent<P extends Record<string, any>, C extends ReactElementWithProviderModule<P> = ReactElementWithProviderModule<P>>(module: IComponentProviderModule, component: ReactElementWithProviderModule<P>): C;
+type ReactElementWithProviderModule<P extends Record<string, any>> = (p: PropsWithModule<P>) => React.ReactNode;
 
 /**
- * This component is the standard way to "tap into" an instance of the component
- * in order to get access to its scoped module container and its _(exposed)_ dependencies _instances_.
+ * Can be used to easily provide a {@link module} to any component.
  *
- * @param contextInstance See {@link TapIntoComponentContextProps.contextInstance}.
- * @param exposed See {@link TapIntoComponentContextProps.exposed}.
+ * @example
+ * ```tsx
+ * interface MyComponentProps {
+ *   firstName: string;
+ *   lastName: string;
+ * }
+ *
+ * function MyComponent({ firstName, lastName }: MyComponentProps) {
+ *   const service = useInject(MyComponentService);
+ *
+ *   return <h1>Hello {service.computeUserName(firstName, lastName)}!</h1>
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <ProvideModule module={MyComponentModule}>
+ *       <MyComponent firstName={'John'} lastName={'Doe'} />
+ *     </ProvideModule>
+ *   );
+ * }
+ * ```
+ *
+ * @param param0 See {@link ProvideModuleFunctionParams}.
+ * @returns The provided {@link toComponent | Component}.
  */
-declare function TapIntoComponent({ children, contextInstance }: TapIntoComponentContextProps): react_jsx_runtime.JSX.Element;
+declare function ProvideModule({ module, children }: ProvideModuleFunctionParams): react_jsx_runtime.JSX.Element;
+interface ProvideModuleFunctionParams {
+    /** The {@link IComponentProviderModule | Module} which should be consumed by the {@link children | component}. */
+    module: IComponentProviderModule;
+    children: react__default.ReactElement;
+}
+
+declare function hookFactory<P extends HookParams, D extends any[], T>({ use: hook, inject, }: HookFactoryParams<P, D, T>): (p: P) => T;
+interface HookFactoryParams<P extends HookParams, D extends any[], T> {
+    use: HookWithProviderModuleDependencies<P, D, T>;
+    inject: ProviderToken[];
+}
+type HookWithProviderModuleDependencies<P extends HookParams, D extends any[], T> = (p: HookWithDeps<P, D>) => T;
+type HookWithDeps<P extends HookParams, D extends any[]> = P & {
+    /** Array containing the resolved dependencies from the component context. */
+    deps: D;
+};
+type HookParams = Record<string, any> | void;
 
-export { ComponentProviderModule, type IComponentProviderModule, type IComponentProviderModuleNaked, ModuleProvider, REACT_X_INJECTION_CONTEXT, REACT_X_INJECTION_EXPOSED_COMPONENT_MODULE_CONTEXT, TapIntoComponent, type TapIntoComponentContextProps, type UseInjectOptions, type UseInjectSharedOptions, type WithComponentInstanceCtxFluidSyntax, useExposeComponentModuleContext, useInject, useInjectMany, useInjectManyOnRender, useInjectOnRender, useRerenderOnChildrenModuleContextLoaded };
+export { ComponentProviderModule, type HookFactoryParams, type HookWithDeps, type HookWithProviderModuleDependencies, type IComponentProviderModule, type IComponentProviderModuleNaked, type PropsWithModule, ProvideModule, type ProvideModuleFunctionParams, REACT_X_INJECTION_PROVIDER_MODULE_CONTEXT, type ReactElementWithProviderModule, type UseInjectOptions, hookFactory, provideModuleToComponent, useComponentModule, useInject, useInjectMany };