@tachybase/di 1.3.43

package/src/decorators/service.decorator.ts

@@ -0,0 +1,34 @@
+import { Constructable } from '@tachybase/utils';
+
+import { ContainerInstance } from '../container-instance.class';
+import { EMPTY_VALUE } from '../empty.const';
+import { ServiceMetadata } from '../interfaces/service-metadata.interface';
+import { ServiceOptions } from '../interfaces/service-options.interface';
+
+/**
+ * Marks class as a service that can be injected using Container.
+ */
+
+export function Service<T = unknown>(): Function;
+export function Service<T = unknown>(options: ServiceOptions<T>): Function;
+export function Service<T>(options: ServiceOptions<T> = {}) {
+  return (target: Constructable<T>, context: ClassDecoratorContext) => {
+    const serviceMetadata: ServiceMetadata<T> = {
+      id: options.id || target,
+      type: target,
+      factory: (options as any).factory || undefined,
+      multiple: options.multiple || false,
+      eager: options.eager || false,
+      scope: options.scope || 'container',
+      referencedBy: new Map().set(ContainerInstance.default.id, ContainerInstance.default),
+      value: EMPTY_VALUE,
+    };
+
+    ((context.metadata.injects as any[]) || []).forEach((inject) => {
+      inject(target);
+    });
+
+    ContainerInstance.default.set(serviceMetadata);
+    return target;
+  };
+}

package/src/decorators.ts

@@ -0,0 +1,70 @@
+import { Constructable } from '@tachybase/utils';
+
+import { Container } from './container-instance.class';
+import { Inject } from './decorators/inject.decorator';
+import { Service } from './decorators/service.decorator';
+
+export interface ActionDef {
+  type: string;
+  resourceName?: string;
+  actionName?: string;
+  method?: string;
+  options?: {
+    acl?: 'loggedIn' | 'public' | 'private';
+  };
+}
+
+// init actions
+Container.set({ id: 'actions', value: new Map<Function, ActionDef[]>() });
+
+export function App() {
+  return Inject('app');
+}
+
+export function Db() {
+  return Inject('db');
+}
+
+export function InjectLog() {
+  return Inject('logger');
+}
+
+export function Controller(name: string) {
+  return function (target: any, context: ClassDecoratorContext) {
+    const serviceOptions = { id: 'controller', multiple: true };
+    Service(serviceOptions)(target, context);
+    const actions = Container.get('actions') as Map<Function, ActionDef[]>;
+    if (!actions.has(target)) {
+      actions.set(target, []);
+    }
+    actions.get(target).push({
+      type: 'resource',
+      resourceName: name,
+    });
+  };
+}
+
+export function Action(
+  name: string,
+  options?: {
+    acl?: 'loggedIn' | 'public' | 'private';
+  },
+) {
+  return function (_: any, context: ClassMethodDecoratorContext) {
+    if (!context.metadata.injects) {
+      context.metadata.injects = [];
+    }
+    (context.metadata.injects as any[]).push((target: Constructable<unknown>) => {
+      const actions = Container.get('actions') as Map<Function, ActionDef[]>;
+      if (!actions.has(target)) {
+        actions.set(target, []);
+      }
+      actions.get(target).push({
+        type: 'action',
+        method: String(context.name),
+        actionName: name,
+        options: options || { acl: 'private' },
+      });
+    });
+  };
+}

package/src/empty.const.ts

@@ -0,0 +1,6 @@
+/**
+ * Indicates that a service has not been initialized yet.
+ *
+ * _Note: This value is for internal use only._
+ */
+export const EMPTY_VALUE = Symbol('EMPTY_VALUE');

package/src/error/cannot-inject-value.error.ts

@@ -0,0 +1,22 @@
+import { Constructable } from '@tachybase/utils';
+
+/**
+ * Thrown when DI cannot inject value into property decorated by @Inject decorator.
+ */
+export class CannotInjectValueError extends Error {
+  public name = 'CannotInjectValueError';
+
+  get message(): string {
+    return (
+      `Cannot inject value into "${this.target.constructor.name}.${this.propertyName}". ` +
+      `Please make sure you setup reflect-metadata properly and you don't use interfaces without service tokens as injection value.`
+    );
+  }
+
+  constructor(
+    private target: Constructable<unknown>,
+    private propertyName: string,
+  ) {
+    super();
+  }
+}

package/src/error/cannot-instantiate-value.error.ts

@@ -0,0 +1,34 @@
+import { Token } from '../token.class';
+import { ServiceIdentifier } from '../types/service-identifier.type';
+
+/**
+ * Thrown when DI cannot inject value into property decorated by @Inject decorator.
+ */
+export class CannotInstantiateValueError extends Error {
+  public name = 'CannotInstantiateValueError';
+
+  /** Normalized identifier name used in the error message. */
+  private normalizedIdentifier = '<UNKNOWN_IDENTIFIER>';
+
+  get message(): string {
+    return (
+      `Cannot instantiate the requested value for the "${this.normalizedIdentifier}" identifier. ` +
+      `The related metadata doesn't contain a factory or a type to instantiate.`
+    );
+  }
+
+  constructor(identifier: ServiceIdentifier) {
+    super();
+
+    // TODO: Extract this to a helper function and share between this and NotFoundError.
+    if (typeof identifier === 'string') {
+      this.normalizedIdentifier = identifier;
+    } else if (identifier instanceof Token) {
+      this.normalizedIdentifier = `Token<${identifier.name || 'UNSET_NAME'}>`;
+    } else if (identifier && (identifier.name || identifier.prototype?.name)) {
+      this.normalizedIdentifier = identifier.name
+        ? `MaybeConstructable<${identifier.name}>`
+        : `MaybeConstructable<${(identifier.prototype as { name: string })?.name}>`;
+    }
+  }
+}

package/src/error/service-not-found.error.ts

@@ -0,0 +1,33 @@
+import { Token } from '../token.class';
+import { ServiceIdentifier } from '../types/service-identifier.type';
+
+/**
+ * Thrown when requested service was not found.
+ */
+export class ServiceNotFoundError extends Error {
+  public name = 'ServiceNotFoundError';
+
+  /** Normalized identifier name used in the error message. */
+  private normalizedIdentifier = '<UNKNOWN_IDENTIFIER>';
+
+  get message(): string {
+    return (
+      `Service with "${this.normalizedIdentifier}" identifier was not found in the container. ` +
+      `Register it before usage via explicitly calling the "Container.set" function or using the "@Service()" decorator.`
+    );
+  }
+
+  constructor(identifier: ServiceIdentifier) {
+    super();
+
+    if (typeof identifier === 'string') {
+      this.normalizedIdentifier = identifier;
+    } else if (identifier instanceof Token) {
+      this.normalizedIdentifier = `Token<${identifier.name || 'UNSET_NAME'}>`;
+    } else if (identifier && (identifier.name || identifier.prototype?.name)) {
+      this.normalizedIdentifier = identifier.name
+        ? `MaybeConstructable<${identifier.name}>`
+        : `MaybeConstructable<${(identifier.prototype as { name: string })?.name}>`;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import { Container } from './container-instance.class';
+
+export * from './decorators/inject-many.decorator';
+export * from './decorators/inject.decorator';
+export * from './decorators/service.decorator';
+
+export * from './error/cannot-inject-value.error';
+export * from './error/cannot-instantiate-value.error';
+export * from './error/service-not-found.error';
+
+export type { Handler } from './interfaces/handler.interface';
+export type { ServiceMetadata } from './interfaces/service-metadata.interface';
+export type { ServiceOptions } from './interfaces/service-options.interface';
+export type { ServiceIdentifier } from './types/service-identifier.type';
+
+export { ContainerInstance, Container } from './container-instance.class';
+export { Token } from './token.class';
+
+export default Container;
+
+export * from './decorators';

package/src/interfaces/container-options.interface.ts

@@ -0,0 +1,48 @@
+export interface ContainerOptions {
+  /**
+   * Controls the behavior when a service is already registered with the same ID. The following values are allowed:
+   *
+   *   - `throw` - a `ContainerCannotBeCreatedError` error is raised
+   *   - `overwrite` - the previous container is disposed and a new one is created
+   *   - `returnExisting` - returns the existing container or raises a `ContainerCannotBeCreatedError` error if the
+   *      specified options differ from the options of the existing container
+   *
+   * The default value is `returnExisting`.
+   */
+  onConflict: 'throw' | 'overwrite' | 'returnExisting';
+
+  /**
+   * Controls the behavior when a requested type doesn't exists in the current container. The following values are allowed:
+   *
+   *   - `allowLookup` - the parent container will be checked for the dependency
+   *   - `localOnly` - a `ServiceNotFoundError` error is raised
+   *
+   * The default value is `allowLookup`.
+   */
+  lookupStrategy: 'allowLookup' | 'localOnly';
+
+  /**
+   * Enables the lookup for global (singleton) services before checking in the current container. By default every
+   * type is first checked in the default container to return singleton services. This check bypasses the lookup strategy,
+   * set in the container so if this behavior is not desired it can be disabled via this flag.
+   *
+   * The default value is `true`.
+   */
+  allowSingletonLookup: boolean;
+
+  /**
+   * Controls how the child container inherits the service definitions from it's parent. The following values are allowed:
+   *
+   *  - `none` - no metadata is inherited
+   *  - `definitionOnly` - only metadata is inherited, a new instance will be created for each class
+   *    - eager classes created as soon as the container is created
+   *    - non-eager classes are created the first time they are requested
+   *  - `definitionWithValues` - both metadata and service instances are inherited
+   *    - when parent class is disposed the instances in this container are preserved
+   *    - if a service is registered but not created yet, it will be shared when created between the two container
+   *    - newly registered services won't be shared between the two container
+   *
+   * The default value is `none`.
+   */
+  inheritanceStrategy: 'none' | 'definitionOnly' | 'definitionWithValues';
+}

package/src/interfaces/handler.interface.ts

@@ -0,0 +1,32 @@
+import { Constructable } from '@tachybase/utils';
+
+import { ContainerInstance } from '../container-instance.class';
+
+/**
+ * Used to register special "handler" which will be executed on a service class during its initialization.
+ * It can be used to create custom decorators and set/replace service class properties and constructor parameters.
+ */
+export interface Handler<T = unknown> {
+  /**
+   * Service object used to apply handler to.
+   */
+  object: Constructable<T>;
+
+  /**
+   * Class property name to set/replace value of.
+   * Used if handler is applied on a class property.
+   */
+  propertyName?: string;
+
+  /**
+   * Parameter index to set/replace value of.
+   * Used if handler is applied on a constructor parameter.
+   */
+  index?: number;
+
+  /**
+   * Factory function that produces value that will be set to class property or constructor parameter.
+   * Accepts container instance which requested the value.
+   */
+  value: (container: ContainerInstance) => any;
+}

package/src/interfaces/service-metadata.interface.ts

@@ -0,0 +1,62 @@
+import { Constructable } from '@tachybase/utils';
+
+import { ContainerInstance } from '../container-instance.class';
+import { ContainerIdentifier } from '../types/container-identifier.type';
+import { ContainerScope } from '../types/container-scope.type';
+import { ServiceIdentifier } from '../types/service-identifier.type';
+
+/**
+ * Service metadata is used to initialize service and store its state.
+ */
+export interface ServiceMetadata<Type = unknown> {
+  /** Unique identifier of the referenced service. */
+  id: ServiceIdentifier;
+
+  /**
+   * The injection scope for the service.
+   *   - a `singleton` service always will be created in the default container regardless of who registering it
+   *   - a `container` scoped service will be created once when requested from the given container
+   *   - a `transient` service will be created each time it is requested
+   */
+  scope: ContainerScope;
+
+  /**
+   * Class definition of the service what is used to initialize given service.
+   * This property maybe null if the value of the service is set manually.
+   * If id is not set then it serves as service id.
+   */
+  type: Constructable<Type> | null;
+
+  /**
+   * Factory function used to initialize this service.
+   * Can be regular function ("createCar" for example),
+   * or other service which produces this instance ([CarFactory, "createCar"] for example).
+   */
+  factory: [Constructable<unknown>, string] | CallableFunction | undefined;
+
+  /**
+   * Instance of the target class.
+   */
+  value: unknown | symbol;
+
+  /**
+   * Allows to setup multiple instances the different classes under a single service id string or token.
+   */
+  multiple: boolean;
+
+  /**
+   * Indicates whether a new instance should be created as soon as the class is registered.
+   * By default the registered classes are only instantiated when they are requested from the container.
+   *
+   * _Note: This option is ignored for transient services._
+   */
+  eager: boolean;
+
+  /**
+   * Map of containers referencing this metadata. This is used when a container
+   * is inheriting it's parents definitions and values to track the lifecycle of
+   * the metadata. Namely, a service can be disposed only if it's only referenced
+   * by the container being disposed.
+   */
+  referencedBy: Map<ContainerIdentifier, ContainerInstance>;
+}

package/src/interfaces/service-options.interface.ts

@@ -0,0 +1,10 @@
+import { ServiceMetadata } from './service-metadata.interface';
+
+/**
+ * The public ServiceOptions is partial object of ServiceMetadata and either one
+ * of the following is set: `type`, `factory`, `value` but not more than one.
+ */
+export type ServiceOptions<T = unknown> =
+  | Omit<Partial<ServiceMetadata<T>>, 'referencedBy' | 'type' | 'factory'>
+  | Omit<Partial<ServiceMetadata<T>>, 'referencedBy' | 'value' | 'factory'>
+  | Omit<Partial<ServiceMetadata<T>>, 'referencedBy' | 'value' | 'type'>;

package/src/token.class.ts

@@ -0,0 +1,11 @@
+/**
+ * Used to create unique typed service identifier.
+ * Useful when service has only interface, but don't have a class.
+ */
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+export class Token<T> {
+  /**
+   * @param name Token name, optional and only used for debugging purposes.
+   */
+  constructor(public name?: string) {}
+}

package/src/types/abstract-constructable.type.ts

@@ -0,0 +1,7 @@
+/**
+ * Generic type for abstract class definitions.
+ *
+ * Explanation: This describes a newable Function with a prototype Which is
+ * what an abstract class is - no constructor, just the prototype.
+ */
+export type AbstractConstructable<T> = NewableFunction & { prototype: T };

package/src/types/container-identifier.type.ts

@@ -0,0 +1,4 @@
+/**
+ * A container identifier. This value must be unique across all containers.
+ */
+export type ContainerIdentifier = string | symbol;

package/src/types/container-scope.type.ts

@@ -0,0 +1 @@
+export type ContainerScope = 'singleton' | 'container' | 'transient';

package/src/types/service-identifier.type.ts

@@ -0,0 +1,15 @@
+import { Constructable } from '@tachybase/utils';
+
+import { Token } from '../token.class';
+import { AbstractConstructable } from './abstract-constructable.type';
+
+/**
+ * Unique service identifier.
+ * Can be some class type, or string id, or instance of Token.
+ */
+export type ServiceIdentifier<T = unknown> =
+  | Constructable<T>
+  | AbstractConstructable<T>
+  | CallableFunction
+  | Token<T>
+  | string;

package/src/utils/resolve-to-type-wrapper.util.ts

@@ -0,0 +1,44 @@
+import { Constructable } from '@tachybase/utils';
+
+import { Token } from '../token.class';
+import { ServiceIdentifier } from '../types/service-identifier.type';
+
+/**
+ * Helper function used in inject decorators to resolve the received identifier to
+ * an eager type when possible or to a lazy type when cyclic dependencies are possibly involved.
+ *
+ * @param typeOrIdentifier a service identifier or a function returning a type acting as service identifier or nothing
+ * @param target the class definition of the target of the decorator
+ * @param propertyName the name of the property in case of a PropertyDecorator
+ * @param index the index of the parameter in the constructor in case of ParameterDecorator
+ */
+export function resolveToTypeWrapper(
+  typeOrIdentifier: ((type?: never) => Constructable<unknown>) | ServiceIdentifier<unknown> | undefined,
+  target: object,
+  propertyName: string | symbol,
+  index?: number,
+): { eagerType: ServiceIdentifier | null; lazyType: (type?: never) => ServiceIdentifier } {
+  /**
+   * ? We want to error out as soon as possible when looking up services to inject, however
+   * ? we cannot determine the type at decorator execution when cyclic dependencies are involved
+   * ? because calling the received `() => MyType` function right away would cause a JS error:
+   * ? "Cannot access 'MyType' before initialization", so we need to execute the function in the handler,
+   * ? when the classes are already created. To overcome this, we use a wrapper:
+   * ?  - the lazyType is executed in the handler so we never have a JS error
+   * ?  - the eagerType is checked when decorator is running and an error is raised if an unknown type is encountered
+   */
+  let typeWrapper!: { eagerType: ServiceIdentifier | null; lazyType: (type?: never) => ServiceIdentifier };
+
+  /** If requested type is explicitly set via a string ID or token, we set it explicitly. */
+  if ((typeOrIdentifier && typeof typeOrIdentifier === 'string') || typeOrIdentifier instanceof Token) {
+    typeWrapper = { eagerType: typeOrIdentifier, lazyType: () => typeOrIdentifier };
+  }
+
+  /** If requested type is explicitly set via a () => MyClassType format, we set it explicitly. */
+  if (typeOrIdentifier && typeof typeOrIdentifier === 'function') {
+    /** We set eagerType to null, preventing the raising of the CannotInjectValueError in decorators.  */
+    typeWrapper = { eagerType: null, lazyType: () => (typeOrIdentifier as CallableFunction)() };
+  }
+
+  return typeWrapper;
+}