@navios/di 0.1.11 → 0.1.12

package/docs/concepts/injectable.md

@@ -0,0 +1,182 @@
+# @Injectable decorator
+
+The `@Injectable` decorator is used to define a class or a factory class as an injectable service.
+
+## Parameters
+
+The `@Injectable` decorator accepts the following fields in its options:
+
+- `token`: The injection token to use for the service. If not provided, will create a new token using the class itself.
+- `scope`: The lifetime of the service. Accepts `InjectableScope.Singleton` or `InjectableScope.Instance`. By default, it will be `InjectableScope.Singleton`.
+- `type`: The type of the service. Accepts `InjectableType.Class` or `InjectableType.Factory`. By default, it will be `InjectableType.Class`.
+- `registry`: The registry to use for the service. Uses the default registry if not provided.
+
+## Usage
+
+Injectable can be used as a class decorator or a factory decorator.
+
+Inside a class that you're decorating with `@Injectable` you can use `inject` and `syncInject` functions to inject the services.
+
+```ts
+@Injectable()
+class GreeterService {
+  sayHello(name: string) {
+    return `Hello ${name}`
+  }
+}
+
+@Injectable()
+class UserService {
+  private readonly greeterService = syncInject(GreeterService)
+
+  makeGreeting(name: string) {
+    return this.greeterService.sayHello(name)
+  }
+}
+```
+
+Please note that `syncInject` can be used only with services that are created with `InjectableScope.Singleton`.
+
+If you need to inject a service that is created with `InjectableScope.Instance`, you can use `inject` function. and it will return a Promise.
+
+For example:
+
+```ts
+@Injectable({ scope: InjectableScope.Instance })
+class GreeterService {
+  private readonly createdAt = new Date()
+
+  sayHello(name: string) {
+    return `Hello ${name} ${this.createdAt.toISOString()}`
+  }
+}
+
+@Injectable()
+class UserService {
+  private readonly greeterService = inject(GreeterService)
+
+  async makeGreeting(name: string) {
+    const service = await this.greeterService
+    return service.sayHello(name)
+  }
+}
+```
+
+## Examples
+
+### Simple class
+
+```ts
+@Injectable()
+class GreeterService {
+  sayHello(name: string) {
+    return `Hello ${name}`
+  }
+}
+
+const greeterService = await inject(GreeterService)
+console.log(greeterService.sayHello('John'))
+```
+
+### Simple Factory
+
+```ts
+@Injectable({ type: InjectableType.Factory })
+class GreeterServiceFactory {
+  create() {
+    return new GreeterService()
+  }
+}
+
+const greeterService = await inject(GreeterServiceFactory)
+console.log(greeterService.sayHello('John'))
+```
+
+### Class with token
+
+```ts
+export interface GreeterServiceInterface {
+  sayHello(name: string): string
+}
+
+const GreeterServiceParams = z.object({
+  context: z.string(),
+})
+
+export const GREETER_SERVICE = InjectionToken.create<
+  GreeterServiceInterface,
+  typeof GreeterServiceParams
+>('GreeterService', GreeterServiceParams)
+
+@Injectable({ token: GREETER_SERVICE })
+class GreeterService {
+  constructor(private readonly config: z.infer<typeof GreeterServiceParams>) {}
+
+  sayHello(name: string) {
+    return `Hello ${name} ${this.config.context}`
+  }
+}
+
+const greeterService = await inject(GREETER_SERVICE, { context: 'World' })
+console.log(greeterService.sayHello('John'))
+```
+
+### Factory with token
+
+```ts
+export interface GreeterServiceInterface {
+  sayHello(name: string): string
+}
+
+const GreeterServiceParams = z.object({
+  context: z.string(),
+})
+
+export const GREETER_SERVICE = InjectionToken.create<
+  GreeterServiceInterface,
+  typeof GreeterServiceParams
+>('GreeterService', GreeterServiceParams)
+
+@Injectable({ type: InjectableType.Factory, token: GREETER_SERVICE })
+class GreeterServiceFactory {
+  create(ctx: FactoryContext, args: z.infer<typeof GreeterServiceParams>) {
+    return new GreeterService(args)
+  }
+}
+
+const greeterService = await inject(GREETER_SERVICE, { context: 'World' })
+console.log(greeterService.sayHello('John'))
+```
+
+## InjectableScope
+
+The `InjectableScope` enum defines the scope of the service.
+
+- `InjectableScope.Singleton`: The service will be created once and reused.
+- `InjectableScope.Instance`: The service will be created every time it is injected.
+
+## InjectableType
+
+The `InjectableType` enum defines the type of the service.
+
+- `InjectableType.Class`: The service will be a class.
+- `InjectableType.Factory`: The service will be a factory.
+
+## Registry
+
+The `Registry` is the registry of the service. It is used to store the service and its dependencies.
+
+## FactoryContext
+
+The `FactoryContext` is the context of the factory. It is used to add additional information to the factory.
+
+Context API:
+
+- `inject`: Injects the service, same as global inject, but additionally it will track the dependencies of the service.
+- `on`: Adds a listener to the service locator event bus.
+- `getDependencies`: Returns the dependencies of the service.
+- `invalidate`: Invalidates self and all the services that depend on it.
+- `addEffect`: Adds an effect to the service. Effect is a function that will be called when the service is invalidated.
+- `setTtl`: Sets the ttl of the service.
+- `getTtl`: Returns the ttl of the service.
+- `locator`: Returns the service locator you are currently in.

package/docs/concepts/injection-token.md

@@ -0,0 +1,145 @@
+# Injection Token
+
+Injection tokens are used to identify and retrieve services from the dependency injection container. They are typically defined as constants and used to inject services into classes.
+
+## Creating an Injection Token
+
+To create an injection token, you can use the `InjectionToken` class from the `@navios/di` or `@navios/core` package. Here's an example:
+
+```ts
+import { InjectionToken } from '@navios/di'
+
+export const GREETER_SERVICE =
+  InjectionToken.create<GreeterService>('GreeterService')
+
+@Injectable({ token: GREETER_SERVICE })
+class GreeterService {}
+```
+
+## Using an Injection Token
+
+To use an injection token, you can inject it into a class or a function.
+
+```ts
+import { inject } from '@navios/di'
+
+const greeterService = await inject(GREETER_SERVICE)
+```
+
+or
+
+```ts
+@Injectable()
+class UserService {
+  private readonly greeterService = inject(GREETER_SERVICE) // This will be a Promise<GreeterService>
+  private readonly greeterServiceSync = syncInject(GREETER_SERVICE) // This will be a GreeterService
+}
+```
+
+## Adding a parameter to the injection token
+
+You can add a parameter to the injection token to make it more specific.
+
+```ts
+import { z } from 'zod'
+
+const GreeterServiceParams = z.object({
+  context: z.string(),
+})
+
+export const GREETER_SERVICE = InjectionToken.create<
+  GreeterService,
+  typeof GreeterServiceParams
+>('GreeterService', GreeterServiceParams)
+
+@Injectable({ token: GREETER_SERVICE })
+class GreeterService {}
+
+const greeterService = await inject(GREETER_SERVICE, { context: 'Hello' })
+```
+
+## Providing a value to an injection token
+
+You can provide a value to an injection token by using the `bound` function.
+
+```ts
+import { inject, InjectionToken } from '@navios/di'
+
+const helloGreeterService = InjectionToken.bound(GREETER_SERVICE, {
+  context: 'Hello',
+})
+
+const greeterService = await inject(helloGreeterService)
+```
+
+## Providing a factory to an injection token
+
+You can provide a factory to an injection token by using the `factory` function.
+
+It is useful, when you need to bind a value to a result of another service (e.g. a configuration).
+
+```ts
+import { inject, InjectionToken } from '@navios/di'
+
+@Injectable()
+class GreeterConfigService {
+  getContext() {
+    return 'Hello'
+  }
+}
+const helloGreeterService = InjectionToken.factory(
+  GREETER_SERVICE,
+  async () => {
+    const config = await inject(GreeterConfigService)
+    return { context: config.getContext() }
+  },
+)
+
+const greeterService = await inject(helloGreeterService)
+```
+
+## API
+
+### `InjectionToken.create`
+
+Creates a new injection token.
+
+Generic arguments:
+
+- `T`: The type of the value to bind to the injection token.
+- `P`: Zod schema type of the parameters of the injection token.
+
+Arguments:
+
+- `name: string | Class | symbol`: The name of the injection token.
+- `params: ZodSchema | undefined`: The parameters of the injection token.
+
+Returns:
+
+- `InjectionToken`: The new injection token.
+
+### `InjectionToken.bound`
+
+Creates a new injection token that is bound to a value.
+
+Arguments:
+
+- `token: InjectionToken`: The injection token to bind.
+- `value: any`: The value to bind to the injection token.
+
+Returns:
+
+- `BoundInjectionToken`: The new injection token.
+
+### `InjectionToken.factory`
+
+Creates a new injection token that is a factory.
+
+Arguments:
+
+- `token: InjectionToken`: The injection token to bind.
+- `factory: () => Promise<any>`: The factory to bind to the injection token.
+
+Returns:
+
+- `FactoryInjectionToken`: The new injection token.

package/lib/index.js

@@ -1,63 +1,6 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.mts
-var index_exports = {};
-__export(index_exports, {
-  BoundInjectionToken: () => BoundInjectionToken,
-  ErrorsEnum: () => ErrorsEnum,
-  EventEmitter: () => EventEmitter,
-  FactoryInjectionToken: () => FactoryInjectionToken,
-  FactoryNotFound: () => FactoryNotFound,
-  FactoryTokenNotResolved: () => FactoryTokenNotResolved,
-  Injectable: () => Injectable,
-  InjectableScope: () => InjectableScope,
-  InjectableTokenMeta: () => InjectableTokenMeta,
-  InjectableType: () => InjectableType,
-  InjectionToken: () => InjectionToken,
-  InjectorsBase: () => InjectorsBase,
-  InstanceDestroying: () => InstanceDestroying,
-  InstanceExpired: () => InstanceExpired,
-  InstanceNotFound: () => InstanceNotFound,
-  ProxyServiceLocator: () => ProxyServiceLocator,
-  Registry: () => Registry,
-  ServiceLocator: () => ServiceLocator,
-  ServiceLocatorEventBus: () => ServiceLocatorEventBus,
-  ServiceLocatorInstanceHolderKind: () => ServiceLocatorInstanceHolderKind,
-  ServiceLocatorInstanceHolderStatus: () => ServiceLocatorInstanceHolderStatus,
-  ServiceLocatorManager: () => ServiceLocatorManager,
-  UnknownError: () => UnknownError,
-  getGlobalServiceLocator: () => getGlobalServiceLocator,
-  getInjectableToken: () => getInjectableToken,
-  getInjectors: () => getInjectors,
-  globalRegistry: () => globalRegistry,
-  inject: () => inject,
-  makeProxyServiceLocator: () => makeProxyServiceLocator,
-  provideServiceLocator: () => provideServiceLocator,
-  resolveService: () => resolveService,
-  syncInject: () => syncInject,
-  wrapSyncInit: () => wrapSyncInit
-});
-module.exports = __toCommonJS(index_exports);
+'use strict';
 
 // src/decorators/injectable.decorator.mts
-var import_zod3 = require("zod");
 
 // src/enums/injectable-scope.enum.mts
 var InjectableScope = /* @__PURE__ */ ((InjectableScope3) => {
@@ -72,9 +15,6 @@ var InjectableType = /* @__PURE__ */ ((InjectableType2) => {
   InjectableType2["Factory"] = "Factory";
   return InjectableType2;
 })(InjectableType || {});
-
-// src/injection-token.mts
-var import_zod = require("zod");
 var InjectionToken = class _InjectionToken {
   constructor(name, schema) {
     this.name = name;
@@ -149,9 +89,6 @@ var FactoryInjectionToken = class {
     return this.token.toString();
   }
 };
-
-// src/registry.mts
-var import_zod2 = require("zod");
 var Registry = class {
   constructor(parent) {
     this.parent = parent;
@@ -450,9 +387,6 @@ var UnknownError = class extends Error {
   }
 };
 
-// src/interfaces/factory.interface.mts
-var import_zod4 = require("zod");
-
 // src/event-emitter.mts
 var EventEmitter = class {
   listeners = /* @__PURE__ */ new Map();
@@ -988,40 +922,39 @@ var inject = values.inject;
 var syncInject = values.syncInject;
 var wrapSyncInit = values.wrapSyncInit;
 var provideServiceLocator = values.provideServiceLocator;
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  BoundInjectionToken,
-  ErrorsEnum,
-  EventEmitter,
-  FactoryInjectionToken,
-  FactoryNotFound,
-  FactoryTokenNotResolved,
-  Injectable,
-  InjectableScope,
-  InjectableTokenMeta,
-  InjectableType,
-  InjectionToken,
-  InjectorsBase,
-  InstanceDestroying,
-  InstanceExpired,
-  InstanceNotFound,
-  ProxyServiceLocator,
-  Registry,
-  ServiceLocator,
-  ServiceLocatorEventBus,
-  ServiceLocatorInstanceHolderKind,
-  ServiceLocatorInstanceHolderStatus,
-  ServiceLocatorManager,
-  UnknownError,
-  getGlobalServiceLocator,
-  getInjectableToken,
-  getInjectors,
-  globalRegistry,
-  inject,
-  makeProxyServiceLocator,
-  provideServiceLocator,
-  resolveService,
-  syncInject,
-  wrapSyncInit
-});
+
+exports.BoundInjectionToken = BoundInjectionToken;
+exports.ErrorsEnum = ErrorsEnum;
+exports.EventEmitter = EventEmitter;
+exports.FactoryInjectionToken = FactoryInjectionToken;
+exports.FactoryNotFound = FactoryNotFound;
+exports.FactoryTokenNotResolved = FactoryTokenNotResolved;
+exports.Injectable = Injectable;
+exports.InjectableScope = InjectableScope;
+exports.InjectableTokenMeta = InjectableTokenMeta;
+exports.InjectableType = InjectableType;
+exports.InjectionToken = InjectionToken;
+exports.InjectorsBase = InjectorsBase;
+exports.InstanceDestroying = InstanceDestroying;
+exports.InstanceExpired = InstanceExpired;
+exports.InstanceNotFound = InstanceNotFound;
+exports.ProxyServiceLocator = ProxyServiceLocator;
+exports.Registry = Registry;
+exports.ServiceLocator = ServiceLocator;
+exports.ServiceLocatorEventBus = ServiceLocatorEventBus;
+exports.ServiceLocatorInstanceHolderKind = ServiceLocatorInstanceHolderKind;
+exports.ServiceLocatorInstanceHolderStatus = ServiceLocatorInstanceHolderStatus;
+exports.ServiceLocatorManager = ServiceLocatorManager;
+exports.UnknownError = UnknownError;
+exports.getGlobalServiceLocator = getGlobalServiceLocator;
+exports.getInjectableToken = getInjectableToken;
+exports.getInjectors = getInjectors;
+exports.globalRegistry = globalRegistry;
+exports.inject = inject;
+exports.makeProxyServiceLocator = makeProxyServiceLocator;
+exports.provideServiceLocator = provideServiceLocator;
+exports.resolveService = resolveService;
+exports.syncInject = syncInject;
+exports.wrapSyncInit = wrapSyncInit;
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map