@adimm/x-injection-reactjs 0.1.1 → 0.2.0

package/README.md

@@ -18,11 +18,13 @@ xInjection ReactJS&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injectio
 - [Installation](#installation)
   - [TypeScript Configuration](#typescript-configuration)
 - [Getting Started](#getting-started)
+  - [Component ProviderModules](#component-providermodules)
+  - [Component Injection](#component-injection)
+    - [Via anonymous function](#via-anonymous-function)
+    - [Via named function](#via-named-function)
+  - [Hook Injection](#hook-injection)
 - [Examples](#examples)
-  - [Component with private context](#component-with-private-context)
-  - [Component with public context](#component-with-public-context)
-    - [Safe method](#safe-method)
-    - [Experimental method](#experimental-method)
+  - [Composable components](#composable-components)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
 
@@ -65,186 +67,403 @@ Add the following options to your `tsconfig.json` to enable decorator metadata:
 
 ## Getting Started
 
-If you never used the parent library (`xInjection`), then please access the official [xInjection Repository](https://github.com/AdiMarianMutu/x-injection?tab=readme-ov-file#registering-global-providers) to better understand how to use its `ReactJS` implementation.
+If you never used the parent library (`xInjection`), then please access the official [xInjection Repository](https://github.com/AdiMarianMutu/x-injection?tab=readme-ov-file#getting-started) to better understand how to use its `ReactJS` implementation.
 
-## Examples
+### Component ProviderModules
 
-### Component with private context
+A [ComponentProviderModule](https://adimarianmutu.github.io/x-injection-reactjs/interfaces/IComponentProviderModule.html) isn't so different than the original [ProviderModule](https://adimarianmutu.github.io/x-injection/interfaces/IProviderModule.html) from the base `xInjection` library, the main difference being that it'll automatically create a [clone](https://adimarianmutu.github.io/x-injection-reactjs/interfaces/IComponentProviderModule.html#clone) of itself whenever a component is `mounted` and during the `unmount` process it'll [dispose](https://adimarianmutu.github.io/x-injection-reactjs/interfaces/IComponentProviderModule.html#dispose) itself.
 
-A component with a private context it means that when it'll inject dependencies from a module within its instance,
-a parent component will not be able to access those dependencies instances.
+This is needed so:
 
-```tsx
-export class RandomNumberService {
-  generate(): number {
-    /* ... */
+- Each instance of a component has its own instance of the `ProviderModule` _(also known as `ContextualizedModule`)_
+- Whenever a component is unmounted, the container of that `ContextualizedModule` is destroyed, making sure that the resources can be garbage-collected by the JS garbage collector.
+
+> **Note:** By default each `ContextualizedModule` has its `InjectionScope` set to `Singleton`, you can of course change it by providing the [defaultScope](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#defaultscope) property.
+
+### Component Injection
+
+In order to be able to inject dependencies into your components, you must first supply them with a `ComponentProviderModule`.
+
+This is how you can create one:
+
+```ts
+@Injectable()
+export class UserService {
+  firstName: string;
+  lastName: string;
+
+  generateFullName(): string {
+    return `${firstName} ${lastName}`;
   }
 }
 
-// Make sure to use the `ComponentProviderModule` from `@adimm/x-injection-reactjs` not the `ProviderModule` from `@adimm/x-injection`!
-export const RandomNumberComponentModule = new ComponentProviderModule({
-  identifier: Symbol('RandomNumberComponentModule'),
-  providers: [RandomNumberService],
+export const UserComponentModule = new ComponentProviderModule({
+  identifier: Symbol('UserComponentModule'),
+  providers: [UserService],
 });
 
-export function RandomNumberComponent(props: RandomNumberComponentProps) {
-  const service = useInject(RandomNumberService);
+interface UserInfoProps {
+  firstName: string;
+  lastName: string;
+}
+```
+
+Now you have to actually provide the `UserComponentModule` to your component(s). You can do so with 2 different methods:
+
+#### Via anonymous function
 
-  return <h1>A random number: {service.generate()}</h1>;
+If you prefer to use the `const Component = () => {}` syntax, then you must use the [provideModuleToComponent](https://adimarianmutu.github.io/x-injection-reactjs/functions/provideModuleToComponent.html) method as shown below:
+
+> **Note:** _This is the preferred method as it allows you to avoid wrapping your component within another provider once created._
+
+```tsx
+// The UserInfo component will correctly infer the interface of `UserInfoProps` automatically!
+export const UserInfo = provideModuleToComponent(UserComponentModule, ({ firstName, lastName }: UserInfoProps) => {
+  const userService = useInject(UserService);
+
+  userService.firstName = firstName;
+  userService.lastName = lastName;
+
+  return <p>Hello {userService.generateFullName()}!</p>;
+});
+
+function MyApp() {
+  return <UserInfo firstName="John" lastName="Doe" />;
+  // Result
+  //
+  // <p>Hello John Doe!</p>
 }
 ```
 
-### Component with public context
+#### Via named function
+
+Or if you prefer to use the `function Component() {}` syntax, then you must use the [ProvideModule](https://adimarianmutu.github.io/x-injection-reactjs/functions/ProvideModule.html) `HoC` as shown below:
 
-#### Safe method
+> **Note:** _If you need to access the contextualized `module` forwarded to your component, you can wrap the component props with the [PropsWithModule](https://adimarianmutu.github.io/x-injection-reactjs/types/PropsWithModule.html) generic type._
 
 ```tsx
-export class RandomNumberService {
-  generate(): number {
-    /* ... */
-  }
+export function UserInfo({ firstName, lastName }: UserInfoProps) {
+  const userService = useInject(UserService);
+
+  userService.firstName = firstName;
+  userService.lastName = lastName;
+
+  return <p>Hello {userService.generateFullName()}!</p>;
 }
 
-// Make sure to use the `ComponentProviderModule` from `@adimm/x-injection-reactjs` not the `ProviderModule` from `@adimm/x-injection`!
-export const RandomNumberComponentModule = new ComponentProviderModule({
-  identifier: Symbol('RandomNumberComponentModule'),
-  providers: [RandomNumberService],
-  exports: [RandomNumberService],
+function MyApp() {
+  return (
+    <ProvideModule module={UserComponentModule}>
+      <UserInfo firstName="John" lastName="Doe" />
+    </ProvideModule>
+  );
+  // Result
+  //
+  // <p>Hello John Doe!</p>
+}
+```
+
+That's all you need to do, at least for simple components 😃.
+
+> You can find more complex examples at the [Examples](#examples) section.
+
+### Hook Injection
+
+You already have seen in action the low-level [useInject](https://adimarianmutu.github.io/x-injection-reactjs/functions/useInject.html) hook _(take a look also at the [useInjectMany](https://adimarianmutu.github.io/x-injection-reactjs/functions/useInjectMany.html) hook)_. It is quite useful when you just have to inject quickly some dependencies into a component quite simple.
+
+What it does under the hood? Finds the nearest contextualized module and resolves from it the required dependencies into your component, that's all.
+
+But, as your UI will grow, you'll soon discover that you may inject more dependencies into a component, or even in multiple components, therefore you'll end up writing a lot of duplicated code, well, as per the [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself#:~:text=%22Don't%20repeat%20yourself%22,redundancy%20in%20the%20first%20place.) principle, that's not good! 🥲
+
+This means that we can actually use the [hookFactory](https://adimarianmutu.github.io/x-injection-reactjs/functions/hookFactory.html) method to compose a _custom_ hook with access to any dependency available in the component contextualized module.
+
+Having the above examples with the `UserService`, we'll create a custom `generateFullName` hook.
+
+```ts
+// The `HookWithDeps` generic type will help
+// in making sure that the `useGenerateUserFullName` hooks params are correctly visible.
+// The 1st generic param must be the hook params (Like `UserInfoProps`)
+// and starting from the 2nd generic param you must provide the type of your dependencies.
+const useGenerateUserFullName = hookFactory({
+  // The `use` property is where you write your hook implementation.
+  use: ({ firstName, lastName, deps: [userService] }: HookWithDeps<UserInfoProps, UserService>) => {
+    userService.firstName = firstName;
+    userService.lastName = lastName;
+
+    return userService.generateFullName();
+  },
+  // The `inject` array is very important,
+  // here we basically specify which dependencies should be injected into the custom hook.
+  // Also, keep in mind that the order of the `inject` array matters, the order of the `deps` prop
+  // is determined by the order of the `inject` array!
+  inject: [UserService],
 });
+```
 
-export function RandomNumberComponent(props: RandomNumberComponentProps) {
-  <ModuleProvider
-    module={RandomNumberComponentModule}
-    render={() => {
-      // This hook is necessary in order to expose the component instance
-      // context up to the parent component
-      useExposeComponentModuleContext();
+Now you can use it in inside any component which has access to a contextualized module which can provide the `UserService`.
 
-      const service = useInject(RandomNumberService);
+```tsx
+export function UserInfo({ firstName, lastName }: UserInfoProps) {
+  const userFullName = useGenerateFullName({ firstName, lastName });
 
-      return <h1>A random number: {service.generate()}</h1>;
-    }}
-  />;
+  return <p>Hello {userFullName}!</p>;
 }
+```
+
+## Examples
+
+### Composable components
+
+In a real world scenario, you'll definitely have custom components which render other custom components and so on... _(like a [Matryoshka doll](https://en.wikipedia.org/wiki/Matryoshka_doll))_
+
+So you may find yourself wanting to be able to control a dependency/service of a child component from a parent component, with `xInject` this is very easy to achieve thanks to the `ProviderModule` architecture, because each `module` can `import` and `export` other dependencies _(or modules)_ it fits in perfectly within the [declarative programming](https://en.wikipedia.org/wiki/Declarative_programming) world!
+
+In this example, we'll build 4 components, each with its own purpose. However, the `autocomplete` component will be the one capable of accessing the services of all of them.
+
+- An `inputbox`
+- A `list viewer`
+- A `dropdown`
+- An `autocomplete`
+
+<hr>
 
-////////////////////////////////////////
+> Inputbox
 
-export class ParentService {
-  constructor(public readonly randomNumberService: RandomNumberService) {}
+`inputbox.service.ts`
 
-  injectRandomNumberService(service: RandomNumberService): void {
-    this.randomNumberService = service;
+```ts
+@Injectable()
+export class InputboxService {
+  currentValue = '';
+
+  // We'll initialize this soon enough.
+  setStateValue!: (newValue: string) => void;
+
+  /** Can be used to update the {@link currentValue} of the `inputbox`. */
+  setValue(newValue: string): void {
+    this.currentValue = newValue;
+
+    this.setStateValue(this.currentValue);
   }
 }
 
-export const ParentServiceComponentModule = new ComponentProviderModule({
-  identifier: Symbol('ParentServiceComponentModule'),
-  imports: [RandomNumberComponentModule],
-  providers: [ParentService],
+export const InputboxModule = new ComponentProviderModule({
+  identifier: Symbol('InputboxModule'),
+  provides: [InputboxService],
+  exports: [InputboxService],
 });
+```
 
-export function ParentComponent(props: ParentComponentProps) {
-  return (
-    <ModuleProvider
-      module={ParentServiceComponentModule}
-      render={() => {
-        const service = useInject(ParentService);
-
-        return (
-          <>
-            <TapIntoComponent
-              // By using the fluid syntax
-              contextInstance={() => ({
-                // If one of the children did expose the `RandomNumberComponentModule`
-                // module, we'll be able to access its instance.
-                tryGet: RandomNumberComponentModule,
-                thenDo: (ctx) => {
-                  const randomNumberService_FromComponentInstance = ctx.get(RandomNumberComponentModule);
-
-                  service.injectRandomNumberService(randomNumberService_FromComponentInstance);
-                },
-              })}>
-              <RandomNumberComponent />
-            </TapIntoComponent>
-
-            <TapIntoComponent
-              // By accessing the entire underlying context map which may contain even more
-              // modules exposed by more children down the tree.
-              contextInstance={(ctxMap) => {
-                const ctx = ctxMap.get(RandomNumberComponentModule.toString());
-                if (!ctx) return;
-
-                const randomNumberService_FromComponentInstance = ctx.get(RandomNumberComponentModule);
-
-                service.injectRandomNumberService(randomNumberService_FromComponentInstance);
-              }}>
-              <RandomNumberComponent />
-            </TapIntoComponent>
-          </>
-        );
-      }}
-    />
-  );
+`inputbox.tsx`
+
+```tsx
+export interface InputboxProps {
+  initialValue: string;
 }
+
+export const Inputbox = provideModuleToComponent(InputboxModule, ({ initialValue }: InputboxProps) => {
+  const service = useInject(InputboxService);
+  const [, setCurrentValue] = useState(initialValue);
+  service.setStateValue = setCurrentValue;
+
+  useEffect(() => {
+    service.currentValue = initialValue;
+  }, [initialValue]);
+
+  return <input value={service.currentValue} onChange={(e) => service.setValue(e.currentTarget.value)} />;
+});
 ```
 
-#### Experimental method
+<hr>
+
+> Listview
 
-There is another method which is currently in _experimental_ mode and it may not always work as expected, it may even produce unnecessary re-render cycles
-or introduce unknown bugs, please use it carefully and with diligence!
+`listview.service.ts`
+
+```ts
+@Injectable()
+export class ListviewService {
+  items = [];
+
+  /* Remaining fancy implementation */
+}
+
+export const ListviewModule = new ComponentProviderModule({
+  identifier: Symbol('ListviewModule'),
+  provides: [ListviewService],
+  exports: [ListviewService],
+});
+```
+
+`listview.tsx`
 
 ```tsx
-export function ParentComponent(props: ParentComponentProps) {
+export interface ListviewProps {
+  items: any[];
+}
+
+export const Listview = provideModuleToComponent(ListviewModule, ({ items }: ListviewProps) => {
+  const service = useInject(ListviewService);
+
+  /* Remaining fancy implementation */
+
   return (
-    <ModuleProvder
-      module={ParentServiceComponentModule}
-      render={() => {
-        // By using this hook, the component will always re-render whenever
-        // a child using a ProviderModule which is also imported into the parent ProviderModule,
-        // has mounted and rendered!
-        useRerenderOnChildrenModuleContextLoaded();
-
-        // We should use the `useInjectOnRender` instead of the default `useInject`
-        // hook which re-uses the same instance of the injected dependency
-        // between re-renders.
-        //
-        // Note: It may still work with the `useInject` hook too, but it may not be predictable.
-        const service = useInjectOnRender(ParentService);
-
-        // At this point the `service.randomNumberService` instance should be the one
-        // from the `RandomNumberComponent` below.
-        //
-        // Note: Expect during the 1st render cycle to not be the same instance as the one used by the child component!
-        // The `xInjection` container will still supply the correct provider to the
-        // constructor parameter, but it'll be a new transient instance.
-        console.log(service.randomNumberService.generate());
-
-        // As we are now using the `useRerenderOnChildrenModuleContextLoaded` hook
-        // there's no need anymore for the `TapIntoComponent` wrapper.
-        return <RandomNumberComponent />;
-      }}
-    />
+    <div>
+      {service.items.map((item) => (
+        <span key={item}>{item}</span>
+      ))}
+    </div>
   );
+});
+```
+
+<hr>
+
+> Dropdown
+
+Now keep close attention to how we implement the `Dropdown` component, as it'll actually be the _parent_ controlling the `Listview` component own service.
+
+`dropdown.service.ts`
+
+```ts
+@Injectable()
+export class DropdownService {
+  constructor(readonly listviewService: ListviewService) {
+    // We can already take control of the children `ListviewService`!
+    this.listviewService.items = [1, 2, 3, 4, 5];
+  }
+
+  /* Remaining fancy implementation */
 }
+
+export const DropdownModule = new ComponentProviderModule({
+  identifier: Symbol('DropdownModule'),
+  // It is very important that we import all the exportable dependencies from the `ListviewModule`!
+  imports: [ListviewModule],
+  provides: [DropdownService],
+  exports: [
+    // Let's also re-export the dependencies of the `ListviewModule` so once we import the `DropdownModule`
+    // somewhere elese, we get access to the `ListviewModule` exported dependencies as well!
+    ListviewModule,
+    // Let's not forget to also export our `DropdownService` :)
+    DropdownService,
+  ],
+});
 ```
 
-The `ModuleProvider` component also accepts the `children` prop, this means you can also use it like this:
+`dropdown.tsx`
 
 ```tsx
-export function Component() {
-  return <h1>Hello World!</h1>;
+export interface DropdownProps {
+  listviewProps: ListviewProps;
+
+  initialSelectedValue: number;
 }
 
-function MyApp() {
-  return (
-    <ModuleProvider module={ComponentModule}>
-      <Component />
-    </ModuleProvider>
-  );
+export const Dropdown = provideModuleToComponent(
+  ListviewModule,
+  ({
+    listviewProps,
+    initialSelectedValue,
+    // Here it is important that we get access to the contextualized module
+    // so we can forward it to the `Listview` component!
+    module,
+  }: DropdownProps) => {
+    const service = useInject(DropdownService);
+
+    /* Remaining fancy implementation */
+
+    return (
+      <div className="fancy-dropdown">
+        <span>{initialSelectedValue}</span>
+
+        {/* Here we forward the contextualized module which will be sent from the parent component consuming this component,
+        in our case, the `Autocomplete` component. */}
+        <Listview module={module} />
+      </div>
+    );
+  }
+);
+```
+
+<hr>
+
+> Autocomplete
+
+And finally the grand finale!
+
+`autocomplete.service.ts`
+
+```ts
+@Injectable()
+export class AutocompleteService {
+  constructor(
+    readonly inputboxService: InputboxService,
+    readonly dropdownService: DropdownService
+  ) {
+    // Here we can override even what the `Dropdown` has already overriden!
+    this.dropdownService.listviewService.items = [29, 9, 1969];
+
+    // However doing the following, will throw an error because the `Inputbox` component
+    // at this time is not yet mounted, therefore the `setStateValue` state setter
+    // method doesn't exist yet.
+    //
+    // A better way would be to use a store manager so you can generate your application state through
+    // the services, rather than inside the UI (components should be used only to render the data, not to manipulate/manage it).
+    this.inputboxService.setValue('xInjection');
+  }
+
+  /* Remaining fancy implementation */
+}
+
+export const AutocompleteModule = new ComponentProviderModule({
+  identifier: Symbol('AutocompleteModule'),
+  imports: [InputboxModule, DropdownModule],
+  provides: [AutocompleteService],
+  // If we don't plan to share the internal dependencies of the
+  // Autocomplete component, then we can omit the `exports` array declaration.
+});
+```
+
+`autocomplete.tsx`
+
+```tsx
+export interface AutocompleteProps {
+  inputboxProps: InputboxProps;
+  dropdownProps: DropdownProps;
+
+  currentText: string;
 }
+
+export const Autocomplete = provideModuleToComponent(
+  AutocompleteModule,
+  ({
+    dropdownProps,
+    currentText,
+
+    module,
+  }: AutocompleteProps) => {
+    const service = useInject(AutocompleteService);
+
+    console.log(service.dropdownService.listviewService.items);
+    // Produces: [29, 9, 1969]
+
+    /* Remaining fancy implementation */
+
+    return (
+      <div className="fancy-autocomplete">
+        {/* Let's not forget to forward the module to both components we want to control */}
+        <Inputbox {...inputboxProps} module={module} >
+        <Dropdown {...dropdownProps} module={module} />
+      </div>
+    );
+  }
+);
 ```
 
-> **Note:** You don't have to wrap your entire application with a `ModuleProvider` which provides the `AppModule`, the global container is already available to use and all your `ComponentProviderModule` know ouf-of-the-box how to access it when you provide them with providers registered into the `AppModule`.
+This should cover the fundamentals of how you can build a scalable UI by using the `xInjection` Dependency Injection 😊
+
+> **Note:** _Keep in mind that both library ([xInjection](https://www.npmjs.com/package/@adimm/x-injection) & [xInjection ReactJS](https://www.npmjs.com/package/@adimm/x-injection-reactjs)) are still young and being developed, therefore the internals and public API may change in the near future._
 
 ## Documentation