@nmtjs/core 0.6.0

package/lib/container.ts

@@ -0,0 +1,482 @@
+import type { Async } from '@nmtjs/common'
+import { tryCaptureStackTrace } from '@nmtjs/common'
+import {
+  kFactoryInjectable,
+  kInjectable,
+  kLazyInjectable,
+  kOptionalDependency,
+  kValueInjectable,
+} from './constants.ts'
+import { Scope } from './enums.ts'
+import type { Logger } from './logger.ts'
+import type { Registry } from './registry.ts'
+
+const ScopeStrictness = {
+  [Scope.Global]: 0,
+  [Scope.Connection]: 1,
+  [Scope.Call]: 2,
+  [Scope.Transient]: 3,
+}
+
+export type DependencyOptional<T extends AnyInjectable = AnyInjectable> = {
+  [kOptionalDependency]: any
+  injectable: T
+}
+
+export type Depedency = DependencyOptional | AnyInjectable
+
+export type Dependencies = Record<string, Depedency>
+
+export type ResolveInjectableType<T extends AnyInjectable> =
+  T extends Injectable<infer Type, any, any> ? Type : never
+
+export interface Dependant<Deps extends Dependencies = Dependencies> {
+  dependencies: Deps
+  label?: string
+  stack?: string
+}
+
+export type DependencyInjectable<T extends Depedency> = T extends AnyInjectable
+  ? T
+  : T extends DependencyOptional
+    ? T['injectable']
+    : never
+
+export type DependencyContext<Deps extends Dependencies> = {
+  readonly [K in keyof Deps as Deps[K] extends AnyInjectable
+    ? K
+    : never]: Deps[K] extends AnyInjectable
+    ? ResolveInjectableType<Deps[K]>
+    : never
+} & {
+  readonly [K in keyof Deps as Deps[K] extends DependencyOptional
+    ? K
+    : never]?: Deps[K] extends DependencyOptional
+    ? ResolveInjectableType<Deps[K]['injectable']>
+    : never
+}
+
+export type InjectableFactoryType<
+  InjectableType,
+  InjectableDeps extends Dependencies,
+> = (context: DependencyContext<InjectableDeps>) => Async<InjectableType>
+
+export type InjectableDisposeType<
+  InjectableType,
+  InjectableDeps extends Dependencies,
+> = (
+  instance: InjectableType,
+  context: DependencyContext<InjectableDeps>,
+) => any
+
+export interface LazyInjectable<T, S extends Scope = Scope.Global>
+  extends Dependant<{}> {
+  scope: S
+  [kInjectable]: any
+  [kLazyInjectable]: T
+}
+
+export interface ValueInjectable<T> extends Dependant<{}> {
+  scope: Scope.Global
+  value: T
+  [kInjectable]: any
+  [kValueInjectable]: any
+}
+
+export interface FactoryInjectable<
+  T,
+  D extends Dependencies = {},
+  S extends Scope = Scope.Global,
+> extends Dependant<D> {
+  scope: S
+  factory(context: DependencyContext<D>): Async<T>
+  dispose?(instance: T, context: DependencyContext<D>): any
+  [kInjectable]: any
+  [kFactoryInjectable]: any
+}
+
+export type Injectable<
+  InjectableValue = any,
+  InjectableDeps extends Dependencies = {},
+  InjectableScope extends Scope = Scope,
+> =
+  | LazyInjectable<InjectableValue, InjectableScope>
+  | ValueInjectable<InjectableValue>
+  | FactoryInjectable<InjectableValue, InjectableDeps, InjectableScope>
+
+export type AnyInjectable<T = any, S extends Scope = Scope> = Injectable<
+  T,
+  any,
+  S
+>
+
+export class Container {
+  readonly instances = new Map<AnyInjectable, { instance: any; context: any }>()
+  private readonly resolvers = new Map<AnyInjectable, Promise<any>>()
+  private readonly injectables = new Set<AnyInjectable>()
+  private readonly dependants = new Map<AnyInjectable, Set<AnyInjectable>>()
+
+  constructor(
+    private readonly application: {
+      registry: Registry
+      logger: Logger
+    },
+    public readonly scope: Exclude<Scope, Scope.Transient> = Scope.Global,
+    private readonly parent?: Container,
+  ) {
+    if ((scope as any) === Scope.Transient) {
+      throw new Error('Invalid scope')
+    }
+  }
+
+  async load() {
+    const traverse = (dependencies: Dependencies) => {
+      for (const key in dependencies) {
+        const dependency = dependencies[key]
+        const injectable = getDepedencencyInjectable(dependency)
+        this.injectables.add(injectable)
+        traverse(injectable.dependencies)
+      }
+    }
+
+    for (const dependant of this.application.registry.getDependants()) {
+      traverse(dependant.dependencies)
+    }
+
+    const injectables = Array.from(this.findCurrentScopeInjectables())
+    await Promise.all(injectables.map((injectable) => this.resolve(injectable)))
+  }
+
+  fork(scope: Exclude<Scope, Scope.Transient>) {
+    return new Container(this.application, scope, this)
+  }
+
+  async dispose() {
+    this.application.logger.trace('Disposing [%s] scope context...', this.scope)
+
+    // Loop through all instances and dispose them,
+    // until there are no more instances left
+    while (this.instances.size) {
+      for (const injectable of this.instances.keys()) {
+        const dependants = this.dependants.get(injectable)
+        // Firstly, dispose instances that other injectables don't depend on
+        if (!dependants?.size) {
+          await this.disposeInjectable(injectable)
+          for (const dependants of this.dependants.values()) {
+            // Clear current istances as a dependant for other injectables
+            if (dependants.has(injectable)) {
+              dependants.delete(injectable)
+            }
+          }
+        }
+      }
+    }
+
+    this.instances.clear()
+    this.injectables.clear()
+    this.resolvers.clear()
+    this.dependants.clear()
+  }
+
+  containsWithinSelf(injectable: AnyInjectable) {
+    return this.instances.has(injectable) || this.resolvers.has(injectable)
+  }
+
+  contains(injectable: AnyInjectable): boolean {
+    return (
+      this.containsWithinSelf(injectable) ||
+      (this.parent?.contains(injectable) ?? false)
+    )
+  }
+
+  get<T extends AnyInjectable>(injectable: T): ResolveInjectableType<T> {
+    if (this.instances.has(injectable)) {
+      return this.instances.get(injectable)!.instance
+    }
+
+    if (this.parent?.contains(injectable)) {
+      return this.parent.get(injectable)
+    }
+
+    throw new Error('No instance found')
+  }
+
+  resolve<T extends AnyInjectable>(injectable: T) {
+    return this.resolveInjectable(injectable)
+  }
+
+  async createContext<T extends Dependencies>(dependencies: T) {
+    return this.createInjectableContext(dependencies)
+  }
+
+  private async createInjectableContext<T extends Dependencies>(
+    dependencies: T,
+    dependant?: AnyInjectable,
+  ) {
+    const injections: Record<string, any> = {}
+    const deps = Object.entries(dependencies)
+    const resolvers: Promise<any>[] = Array(deps.length)
+    for (let i = 0; i < deps.length; i++) {
+      const [key, dependency] = deps[i]
+      const injectable = getDepedencencyInjectable(dependency)
+      const resolver = this.resolveInjectable(injectable, dependant)
+      resolvers[i] = resolver.then((value) => (injections[key] = value))
+    }
+    await Promise.all(resolvers)
+    return Object.freeze(injections) as DependencyContext<T>
+  }
+
+  async provide<T extends AnyInjectable>(
+    injectable: T,
+    instance: ResolveInjectableType<T>,
+  ) {
+    if (compareScope(injectable.scope, '>', this.scope)) {
+      throw new Error('Invalid scope') // TODO: more informative error
+    }
+    this.instances.set(injectable, { instance, context: undefined })
+  }
+
+  satisfies(injectable: AnyInjectable) {
+    return compareScope(injectable.scope, '<=', this.scope)
+  }
+
+  private *findCurrentScopeInjectables() {
+    for (const injectable of this.injectables) {
+      if (injectable.scope === this.scope) {
+        yield injectable
+      }
+    }
+  }
+
+  private resolveInjectable<T extends AnyInjectable>(
+    injectable: T,
+    dependant?: AnyInjectable,
+  ): Promise<ResolveInjectableType<T>> {
+    if (dependant && compareScope(dependant.scope, '<', injectable.scope)) {
+      throw new Error('Invalid scope: dependant is looser than injectable') // TODO: more informative error
+    }
+
+    if (checkIsValueInjectable(injectable)) {
+      return Promise.resolve(injectable.value)
+    } else if (
+      this.parent?.contains(injectable) ||
+      (this.parent?.satisfies(injectable) &&
+        compareScope(this.parent.scope, '<', this.scope))
+    ) {
+      return this.parent.resolveInjectable(injectable, dependant)
+    } else {
+      const { scope, dependencies, stack, label } = injectable
+
+      if (dependant && compareScope(scope, '=', dependant.scope)) {
+        let dependants = this.dependants.get(injectable)
+        if (!dependants) {
+          this.dependants.set(injectable, (dependants = new Set()))
+        }
+        dependants.add(dependant)
+      }
+
+      if (this.instances.has(injectable)) {
+        return Promise.resolve(this.instances.get(injectable)!.instance)
+      } else if (this.resolvers.has(injectable)) {
+        return this.resolvers.get(injectable)!
+      } else {
+        const isLazy = checkIsLazyInjectable(injectable)
+
+        if (isLazy) {
+          const isOptional = checkIsOptional(injectable)
+          if (isOptional) return Promise.resolve(undefined as any)
+          return Promise.reject(
+            new Error(
+              `No instance provided for ${label || 'an'} injectable:\n${stack}`,
+            ),
+          )
+        } else if (!checkIsFactoryInjectable(injectable)) {
+          throw new Error('Invalid injectable')
+        }
+
+        const resolution = this.createInjectableContext(
+          dependencies,
+          injectable,
+        )
+          .then((context) =>
+            Promise.resolve(injectable.factory(context)).then((instance) => ({
+              instance,
+              context,
+            })),
+          )
+          .then(({ instance, context }) => {
+            if (compareScope(this.scope, '>=', scope))
+              this.instances.set(injectable, { instance, context })
+            if (scope !== Scope.Transient) this.resolvers.delete(injectable)
+            return instance
+          })
+        if (scope !== Scope.Transient)
+          this.resolvers.set(injectable, resolution)
+        return resolution
+      }
+    }
+  }
+
+  private async disposeInjectable(injectable: AnyInjectable) {
+    try {
+      if (kFactoryInjectable in injectable) {
+        const { dispose } = injectable
+        if (dispose) {
+          const { instance, context } = this.instances.get(injectable)!
+          await dispose(instance, context)
+        }
+      }
+    } catch (cause) {
+      const error = new Error(
+        'Injectable disposal error. Potential memory leak',
+        { cause },
+      )
+      this.application.logger.error(error)
+    } finally {
+      this.instances.delete(injectable)
+    }
+  }
+}
+
+function compareScope(
+  left: Scope,
+  operator: '>' | '<' | '>=' | '<=' | '=' | '!=',
+  right: Scope,
+) {
+  const leftScope = ScopeStrictness[left]
+  const rightScope = ScopeStrictness[right]
+  switch (operator) {
+    case '=':
+      return leftScope === rightScope
+    case '!=':
+      return leftScope !== rightScope
+    case '>':
+      return leftScope > rightScope
+    case '<':
+      return leftScope < rightScope
+    case '>=':
+      return leftScope >= rightScope
+    case '<=':
+      return leftScope <= rightScope
+    default:
+      throw new Error('Invalid operator')
+  }
+}
+
+export const checkIsLazyInjectable = (
+  injectable: any,
+): injectable is LazyInjectable<any> => kLazyInjectable in injectable
+export const checkIsFactoryInjectable = (
+  injectable: any,
+): injectable is FactoryInjectable<any> => kFactoryInjectable in injectable
+export const checkIsValueInjectable = (
+  injectable: any,
+): injectable is ValueInjectable<any> => kValueInjectable in injectable
+export const checkIsInjectable = (
+  injectable: any,
+): injectable is AnyInjectable<any> => kInjectable in injectable
+export const checkIsOptional = (
+  injectable: any,
+): injectable is DependencyOptional<any> => kOptionalDependency in injectable
+
+export function getInjectableScope(injectable: AnyInjectable) {
+  let scope = injectable.scope
+  const deps = Object.values(injectable.dependencies as Dependencies)
+  for (const dependency of deps) {
+    const injectable = getDepedencencyInjectable(dependency)
+    const dependencyScope = getInjectableScope(injectable)
+    if (compareScope(dependencyScope, '>', scope)) {
+      scope = dependencyScope
+    }
+  }
+  return scope
+}
+
+export function getDepedencencyInjectable(
+  dependency: Depedency,
+): AnyInjectable {
+  if (kOptionalDependency in dependency) {
+    return dependency.injectable
+  }
+  return dependency
+}
+
+export function markOptional<T extends AnyInjectable>(injectable: T) {
+  return {
+    [kOptionalDependency]: true,
+    injectable,
+  } as DependencyOptional<T>
+}
+
+export function createLazyInjectable<T, S extends Scope = Scope.Global>(
+  scope = Scope.Global as S,
+  label?: string,
+): LazyInjectable<T, S> {
+  return Object.freeze({
+    scope,
+    dependencies: {},
+    label,
+    stack: tryCaptureStackTrace(),
+    [kInjectable]: true,
+    [kLazyInjectable]: true as unknown as T,
+  })
+}
+
+export function createValueInjectable<T>(
+  value: T,
+  label?: string,
+): ValueInjectable<T> {
+  return Object.freeze({
+    value,
+    scope: Scope.Global,
+    dependencies: {},
+    label,
+    stack: tryCaptureStackTrace(),
+    [kInjectable]: true,
+    [kValueInjectable]: true,
+  })
+}
+
+export function createFactoryInjectable<
+  T,
+  D extends Dependencies = {},
+  S extends Scope = Scope.Global,
+>(
+  paramsOrFactory:
+    | {
+        dependencies?: D
+        scope?: S
+        factory: InjectableFactoryType<T, D>
+        dispose?: InjectableDisposeType<T, D>
+      }
+    | InjectableFactoryType<T, D>,
+  label?: string,
+): FactoryInjectable<T, D, S> {
+  const isFactory = typeof paramsOrFactory === 'function'
+  const params = isFactory
+    ? {
+        factory: paramsOrFactory,
+      }
+    : paramsOrFactory
+  const injectable = {
+    dependencies: (params.dependencies ?? {}) as D,
+    scope: (params.scope ?? Scope.Global) as S,
+    factory: params.factory,
+    dispose: params.dispose,
+    label,
+    stack: tryCaptureStackTrace(),
+    [kInjectable]: true,
+    [kFactoryInjectable]: true,
+  }
+  const actualScope = getInjectableScope(injectable)
+  if (
+    !isFactory &&
+    params.scope &&
+    ScopeStrictness[actualScope] > ScopeStrictness[params.scope]
+  )
+    throw new Error(
+      `Invalid scope ${params.scope} for factory injectable: dependencies have stricter scope - ${actualScope}`,
+    )
+  injectable.scope = actualScope as unknown as S
+  return Object.freeze(injectable)
+}

package/lib/enums.ts

@@ -0,0 +1,19 @@
+export enum Scope {
+  Global = 'Global',
+  Connection = 'Connection',
+  Call = 'Call',
+  Transient = 'Transient',
+}
+
+export enum Hook {
+  BeforeInitialize = 'BeforeInitialize',
+  AfterInitialize = 'AfterInitialize',
+  BeforeStart = 'BeforeStart',
+  AfterStart = 'AfterStart',
+  BeforeStop = 'BeforeStop',
+  AfterStop = 'AfterStop',
+  BeforeTerminate = 'BeforeTerminate',
+  AfterTerminate = 'AfterTerminate',
+  OnConnect = 'OnConnect',
+  OnDisconnect = 'OnDisconnect',
+}

package/lib/hooks.ts

@@ -0,0 +1,70 @@
+import type { Callback } from '@nmtjs/common'
+import { kHookCollection } from './constants.ts'
+import type { Hook } from './enums.ts'
+// import type { HookType } from './types.ts'
+
+export interface HookType {
+  [key: string]: (...args: any[]) => any
+  // [Hook.AfterInitialize]: () => any
+  // [Hook.BeforeStart]: () => any
+  // [Hook.AfterStart]: () => any
+  // [Hook.BeforeStop]: () => any
+  // [Hook.AfterStop]: () => any
+  // [Hook.BeforeTerminate]: () => any
+  // [Hook.AfterTerminate]: () => any
+  // [Hook.OnConnect]: (...args: any[]) => any
+  // [Hook.OnDisconnect]: (...args: any[]) => any
+}
+
+export type CallHook<T extends string> = (
+  hook: T,
+  ...args: T extends keyof HookType ? Parameters<HookType[T]> : any[]
+) => Promise<void>
+
+export class Hooks {
+  static merge(from: Hooks, to: Hooks) {
+    for (const [name, callbacks] of from[kHookCollection]) {
+      for (const callback of callbacks) {
+        to.add(name, callback)
+      }
+    }
+  }
+
+  [kHookCollection] = new Map<string, Set<Callback>>()
+
+  add(name: string, callback: Callback) {
+    let hooks = this[kHookCollection].get(name)
+    if (!hooks) this[kHookCollection].set(name, (hooks = new Set()))
+    hooks.add(callback)
+    return () => this.remove(name, callback)
+  }
+
+  remove(name: string, callback: Callback) {
+    const hooks = this[kHookCollection].get(name)
+    if (hooks) hooks.delete(callback)
+  }
+
+  async call<T extends string | Hook>(
+    name: T,
+    options: { concurrent?: boolean; reverse?: boolean } | undefined,
+    ...args: T extends Hook ? Parameters<HookType[T]> : any[]
+  ) {
+    const { concurrent = true, reverse = false } = options ?? {}
+    const hooks = this[kHookCollection].get(name)
+    if (!hooks) return
+    const hooksArr = Array.from(hooks)
+    if (concurrent) {
+      await Promise.all(hooksArr.map((hook) => hook(...args)))
+    } else {
+      if (reverse) hooksArr.reverse()
+      for (const hook of hooksArr) await hook(...args)
+    }
+  }
+
+  clear() {
+    this[kHookCollection].clear()
+  }
+}
+
+export const createErrForHook = (hook: Hook | (object & string)) =>
+  `Error during [${hook}] hook`

package/lib/injectables.ts

@@ -0,0 +1,7 @@
+import { createLazyInjectable } from './container.ts'
+import { Scope } from './enums.ts'
+import type { Logger } from './logger.ts'
+
+const logger = createLazyInjectable<Logger>(Scope.Global, 'Logger')
+
+export const CoreInjectables = { logger }

package/lib/logger.ts

@@ -0,0 +1,99 @@
+import { threadId } from 'node:worker_threads'
+import {
+  type DestinationStream,
+  type Level,
+  type Logger as PinoLogger,
+  type StreamEntry,
+  pino,
+  stdTimeFunctions,
+} from 'pino'
+import { build as pretty } from 'pino-pretty'
+
+export type Logger = PinoLogger
+export type LoggingOptions = {
+  destinations?: Array<DestinationStream | StreamEntry<Level>>
+  pinoOptions?: any
+}
+
+// TODO: use node:util inspect
+const bg = (value, color) => `\x1b[${color}m${value}\x1b[0m`
+const fg = (value, color) => `\x1b[38;5;${color}m${value}\x1b[0m`
+
+const levelColors = {
+  10: 100,
+  20: 102,
+  30: 106,
+  40: 104,
+  50: 101,
+  60: 105,
+  [Number.POSITIVE_INFINITY]: 0,
+}
+const messageColors = {
+  10: 0,
+  20: 2,
+  30: 6,
+  40: 4,
+  50: 1,
+  60: 5,
+  [Number.POSITIVE_INFINITY]: 0,
+}
+
+const levelLabels = {
+  10: ' TRACE ',
+  20: ' DEBUG ',
+  30: ' INFO  ',
+  40: ' WARN  ',
+  50: ' ERROR ',
+  60: ' FATAL ',
+  [Number.POSITIVE_INFINITY]: 'SILENT',
+}
+
+export const createLogger = (options: LoggingOptions = {}, $group: string) => {
+  let { destinations, pinoOptions } = options
+
+  if (!destinations || !destinations?.length) {
+    destinations = [createConsolePrettyDestination('info')]
+  }
+
+  const lowestLevelValue = destinations!.reduce(
+    (acc, destination) =>
+      Math.min(
+        acc,
+        'stream' in destination
+          ? pino.levels.values[destination.level!]
+          : Number.POSITIVE_INFINITY,
+      ),
+    Number.POSITIVE_INFINITY,
+  )
+  const level = pino.levels.labels[lowestLevelValue]
+  return pino(
+    {
+      timestamp: stdTimeFunctions.isoTime,
+      ...pinoOptions,
+      level,
+    },
+    pino.multistream(destinations!),
+  ).child({ $group, $threadId: threadId })
+}
+
+export const createConsolePrettyDestination = (
+  level: Level,
+  sync = true,
+): StreamEntry => ({
+  level,
+  stream: pretty({
+    colorize: true,
+    ignore: 'hostname,$group,$threadId',
+    errorLikeObjectKeys: ['err', 'error', 'cause'],
+    messageFormat: (log, messageKey) => {
+      const group = fg(`[${log.$group}]`, 11)
+      const msg = fg(log[messageKey], messageColors[log.level as number])
+      const thread = fg(`(Thread-${log.$threadId})`, 89)
+      return `\x1b[0m${thread} ${group} ${msg}`
+    },
+    customPrettifiers: {
+      level: (level: any) => bg(levelLabels[level], levelColors[level]),
+    },
+    sync,
+  }),
+})

package/lib/plugin.ts

@@ -0,0 +1,25 @@
+import type { Async } from '@nmtjs/common'
+import { kPlugin } from './constants.ts'
+import type { PluginContext } from './types.ts'
+
+export interface BasePlugin<
+  Type = any,
+  Options = unknown,
+  Context extends PluginContext = PluginContext,
+> {
+  name: string
+  init: (context: Context, options: Options) => Async<Type>
+}
+
+export interface Plugin<
+  Type = void,
+  Options = unknown,
+  Context extends PluginContext = PluginContext,
+> extends BasePlugin<Type, Options, Context> {
+  [kPlugin]: any
+}
+
+export const createPlugin = <Options = unknown, Type = void>(
+  name: string,
+  init: Plugin<Type, Options>['init'],
+): Plugin<Type, Options> => ({ name, init, [kPlugin]: true })