@nmtjs/core 0.15.0-beta.3 → 0.15.0-beta.4

package/package.json

@@ -8,18 +8,19 @@
   "peerDependencies": {
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
-    "@nmtjs/common": "0.15.0-beta.3",
-    "@nmtjs/type": "0.15.0-beta.3"
+    "@nmtjs/common": "0.15.0-beta.4",
+    "@nmtjs/type": "0.15.0-beta.4"
   },
   "devDependencies": {
     "@types/node": "^24",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
-    "@nmtjs/type": "0.15.0-beta.3",
-    "@nmtjs/common": "0.15.0-beta.3"
+    "@nmtjs/type": "0.15.0-beta.4",
+    "@nmtjs/common": "0.15.0-beta.4"
   },
   "files": [
     "dist",
+    "src",
     "LICENSE.md",
     "README.md"
   ],
@@ -27,7 +28,7 @@
     "hookable": "6.0.0-rc.1",
     "pino-std-serializers": "^7.0.0"
   },
-  "version": "0.15.0-beta.3",
+  "version": "0.15.0-beta.4",
   "scripts": {
     "clean-build": "rm -rf ./dist",
     "build": "tsc --declaration --sourcemap",

package/src/constants.ts

@@ -0,0 +1,34 @@
+export const kOptionalDependency: unique symbol = Symbol.for(
+  'neemata:OptionalDependencyKey',
+)
+export type kOptionalDependency = typeof kOptionalDependency
+
+export const kInjectable: unique symbol = Symbol.for('neemata:InjectableKey')
+export type kInjectable = typeof kInjectable
+
+export const kLazyInjectable: unique symbol = Symbol.for(
+  'neemata:LazyInjectableKey',
+)
+export type kLazyInjectable = typeof kLazyInjectable
+
+export const kValueInjectable: unique symbol = Symbol.for(
+  'neemata:ValueInjectableKey',
+)
+export type kValueInjectable = typeof kValueInjectable
+
+export const kFactoryInjectable: unique symbol = Symbol.for(
+  'neemata:FactoryInjectableKey',
+)
+export type kFactoryInjectable = typeof kFactoryInjectable
+
+export const kProvider: unique symbol = Symbol.for('neemata:ProviderKey')
+export type kProvider = typeof kProvider
+
+export const kPlugin: unique symbol = Symbol.for('neemata:PluginKey')
+export type kPlugin = typeof kPlugin
+
+export const kMetadata: unique symbol = Symbol.for('neemata:MetadataKey')
+export type kMetadata = typeof kMetadata
+
+export const kHook: unique symbol = Symbol.for('neemata:HookKey')
+export type kHook = typeof kHook

package/src/container.ts

@@ -0,0 +1,509 @@
+import type { PerformanceMeasure } from 'node:perf_hooks'
+import assert from 'node:assert'
+
+import { tryCaptureStackTrace } from '@nmtjs/common'
+
+import type {
+  AnyInjectable,
+  Dependencies,
+  DependencyContext,
+  Injection,
+  ResolveInjectableType,
+} from './injectables.ts'
+import type { Logger } from './logger.ts'
+import { Scope } from './enums.ts'
+import {
+  CoreInjectables,
+  compareScope,
+  createValueInjectable,
+  getDepedencencyInjectable,
+  isFactoryInjectable,
+  isInjectable,
+  isLazyInjectable,
+  isOptionalInjectable,
+  isValueInjectable,
+  provide,
+} from './injectables.ts'
+
+type InstanceWrapper = { private: any; public: any; context: any }
+
+type ContainerOptions = { logger: Logger }
+
+export class Container {
+  readonly instances = new Map<AnyInjectable, InstanceWrapper[]>()
+  private readonly resolvers = new Map<AnyInjectable, Promise<any>>()
+  private readonly injectables = new Set<AnyInjectable>()
+  private readonly dependants = new Map<AnyInjectable, Set<AnyInjectable>>()
+  private disposing = false
+
+  constructor(
+    private readonly runtime: ContainerOptions,
+    public readonly scope: Exclude<Scope, Scope.Transient> = Scope.Global,
+    private readonly parent?: Container,
+  ) {
+    if ((scope as any) === Scope.Transient) {
+      throw new Error('Invalid scope')
+    }
+    this.provide(CoreInjectables.inject, this.createInjectFunction())
+    this.provide(CoreInjectables.dispose, this.createDisposeFunction())
+  }
+
+  async initialize(injectables: Iterable<AnyInjectable>) {
+    const measurements: PerformanceMeasure[] = []
+
+    const traverse = (dependencies: Dependencies) => {
+      for (const key in dependencies) {
+        const dependency = dependencies[key]
+        const injectable = getDepedencencyInjectable(dependency)
+        if (injectable.scope === this.scope) {
+          this.injectables.add(injectable)
+        }
+        traverse(injectable.dependencies)
+      }
+    }
+
+    for (const dependant of injectables) {
+      traverse(dependant.dependencies)
+    }
+
+    await Promise.all(
+      [...this.injectables].map((injectable) =>
+        this.resolve(injectable, measurements),
+      ),
+    )
+
+    return measurements
+  }
+
+  fork(scope: Exclude<Scope, Scope.Transient>) {
+    return new Container(this.runtime, scope, this)
+  }
+
+  find(scope: Exclude<Scope, Scope.Transient>): Container | undefined {
+    if (this.scope === scope) {
+      return this
+    } else {
+      return this.parent?.find(scope)
+    }
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.dispose()
+  }
+
+  async dispose() {
+    this.runtime.logger.trace('Disposing [%s] scope context...', this.scope)
+
+    // Prevent new resolutions during disposal
+    this.disposing = true
+
+    // Get proper disposal order using topological sort
+    const disposalOrder = this.getDisposalOrder()
+
+    try {
+      // Dispose in the correct order
+      for (const injectable of disposalOrder) {
+        if (this.instances.has(injectable)) {
+          await this.disposeInjectableInstances(injectable)
+        }
+      }
+    } catch (error) {
+      this.runtime.logger.fatal(
+        { error },
+        'Potential memory leak: error during container disposal',
+      )
+    }
+
+    this.instances.clear()
+    this.injectables.clear()
+    this.resolvers.clear()
+    this.dependants.clear()
+
+    this.disposing = false
+  }
+
+  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 (injectable.scope === Scope.Transient) {
+      throw new Error('Cannot get transient injectable directly')
+    }
+
+    if (this.instances.has(injectable)) {
+      return this.instances.get(injectable)!.at(0)!.public
+    }
+
+    if (this.parent?.contains(injectable)) {
+      return this.parent.get(injectable)
+    }
+
+    throw new Error('No instance found')
+  }
+
+  resolve<T extends AnyInjectable>(
+    injectable: T,
+    measurements?: PerformanceMeasure[],
+  ) {
+    return this.resolveInjectable(
+      injectable,
+      undefined,
+      undefined,
+      measurements,
+    )
+  }
+
+  async createContext<T extends Dependencies>(dependencies: T) {
+    return this.createInjectableContext(dependencies)
+  }
+
+  async provide<T extends Injection[]>(injections: T)
+  async provide<T extends AnyInjectable>(
+    injectable: T,
+    value: ResolveInjectableType<T> | AnyInjectable<ResolveInjectableType<T>>,
+  )
+  async provide<T extends AnyInjectable | Injection[]>(
+    injectable: T,
+    ...[value]: T extends AnyInjectable
+      ? [
+          value:
+            | ResolveInjectableType<T>
+            | AnyInjectable<ResolveInjectableType<T>>,
+        ]
+      : []
+  ) {
+    const injections = Array.isArray(injectable)
+      ? injectable
+      : [provide(injectable, value)]
+    await Promise.all(
+      injections.map(async ({ token, value }) => {
+        if (compareScope(token.scope, '>', this.scope)) {
+          // TODO: more informative error
+          throw new Error('Invalid scope')
+        }
+        const _value = isInjectable(value) ? await this.resolve(value) : value
+        this.instances.set(token, [
+          { private: _value, public: _value, context: undefined },
+        ])
+      }),
+    )
+  }
+
+  satisfies(injectable: AnyInjectable) {
+    return compareScope(injectable.scope, '<=', this.scope)
+  }
+
+  async disposeInjectableInstances(injectable: AnyInjectable) {
+    try {
+      if (this.instances.has(injectable)) {
+        const wrappers = this.instances.get(injectable)!
+        await Promise.all(
+          wrappers.map((wrapper) =>
+            this.disposeInjectableInstance(
+              injectable,
+              wrapper.private,
+              wrapper.context,
+            ),
+          ),
+        )
+      }
+    } catch (cause) {
+      const error = new Error(
+        'Injectable disposal error. Potential memory leak',
+        { cause },
+      )
+      this.runtime.logger.error(error)
+    } finally {
+      this.instances.delete(injectable)
+    }
+  }
+
+  async disposeInjectableInstance(
+    injectable: AnyInjectable,
+    instance: any,
+    context: any,
+  ) {
+    if (isFactoryInjectable(injectable)) {
+      const { dispose } = injectable
+      if (dispose) await dispose(instance, context)
+    }
+  }
+
+  private async createInjectableContext<T extends Dependencies>(
+    dependencies: T,
+    dependant?: AnyInjectable,
+    measurements?: PerformanceMeasure[],
+  ) {
+    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 isOptional = isOptionalInjectable(dependency)
+      const injectable = getDepedencencyInjectable(dependency)
+      const resolver = this.resolveInjectable(
+        injectable,
+        dependant,
+        isOptional,
+        measurements,
+      )
+      resolvers[i] = resolver.then((value) => (injections[key] = value))
+    }
+    await Promise.all(resolvers)
+    return Object.freeze(injections) as DependencyContext<T>
+  }
+
+  private resolveInjectable<T extends AnyInjectable>(
+    injectable: T,
+    dependant?: AnyInjectable,
+    isOptional?: boolean,
+    measurements?: PerformanceMeasure[],
+  ): Promise<ResolveInjectableType<T>> {
+    if (this.disposing) {
+      return Promise.reject(new Error('Cannot resolve during disposal'))
+    }
+
+    if (dependant && compareScope(dependant.scope, '<', injectable.scope)) {
+      // TODO: more informative error
+      return Promise.reject(
+        new Error('Invalid scope: dependant is looser than injectable'),
+      )
+    }
+
+    if (isValueInjectable(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,
+        undefined,
+        measurements,
+      )
+    } else {
+      const { stack, label } = injectable
+
+      if (dependant) {
+        let dependants = this.dependants.get(injectable)
+        if (!dependants) {
+          this.dependants.set(injectable, (dependants = new Set()))
+        }
+        dependants.add(dependant)
+      }
+
+      const isTransient = injectable.scope === Scope.Transient
+
+      if (!isTransient && this.instances.has(injectable)) {
+        return Promise.resolve(this.instances.get(injectable)!.at(0)!.public)
+      } else if (!isTransient && this.resolvers.has(injectable)) {
+        return this.resolvers.get(injectable)!
+      } else {
+        const isLazy = isLazyInjectable(injectable)
+        if (isLazy) {
+          if (isOptional) return Promise.resolve(undefined as any)
+          return Promise.reject(
+            new Error(
+              `No instance provided for ${label || 'an'} injectable:\n${stack}`,
+            ),
+          )
+        } else {
+          const measure = measurements
+            ? performance.measure(injectable.label || injectable.stack || '')
+            : null
+          const resolution = this.createResolution(
+            injectable,
+            measurements,
+          ).finally(() => {
+            this.resolvers.delete(injectable)
+
+            // biome-ignore lint: false
+            // @ts-ignore
+            if (measurements && measure) measurements.push(measure)
+          })
+          if (injectable.scope !== Scope.Transient) {
+            this.resolvers.set(injectable, resolution)
+          }
+          return resolution
+        }
+      }
+    }
+  }
+
+  private async createResolution<T extends AnyInjectable>(
+    injectable: T,
+    measurements?: PerformanceMeasure[],
+  ): Promise<ResolveInjectableType<T>> {
+    const { dependencies } = injectable
+    const context = await this.createInjectableContext(
+      dependencies,
+      injectable,
+      measurements,
+    )
+    const wrapper = {
+      private: null as any,
+      public: null as ResolveInjectableType<T>,
+      context,
+    }
+    if (isFactoryInjectable(injectable)) {
+      wrapper.private = await Promise.resolve(
+        injectable.factory(wrapper.context),
+      )
+      wrapper.public = injectable.pick(wrapper.private)
+    } else {
+      throw new Error('Invalid injectable type')
+    }
+
+    let instances = this.instances.get(injectable)
+
+    if (!instances) {
+      instances = []
+      this.instances.set(injectable, instances)
+    }
+    instances.push(wrapper)
+
+    return wrapper.public
+  }
+
+  private createInjectFunction() {
+    const inject = <T extends AnyInjectable>(
+      injectable: T,
+      context: InlineInjectionDependencies<T>,
+      scope: Exclude<Scope, Scope.Transient> = this.scope,
+    ) => {
+      const container = this.find(scope)
+      if (!container)
+        throw new Error('No container found for the specified scope')
+
+      const dependencies: Dependencies = { ...injectable.dependencies }
+
+      for (const key in context) {
+        const dep = context[key]
+        if (isInjectable(dep) || isOptionalInjectable(dep)) {
+          dependencies[key] = dep
+        } else {
+          dependencies[key] = createValueInjectable(dep)
+        }
+      }
+
+      const newInjectable = {
+        ...injectable,
+        dependencies,
+        scope: Scope.Transient,
+        stack: tryCaptureStackTrace(1),
+      }
+
+      return container.resolve(newInjectable) as Promise<
+        ResolveInjectableType<T>
+      >
+    }
+
+    const explicit = async <T extends AnyInjectable>(
+      injectable: T,
+      context: InlineInjectionDependencies<T>,
+      scope: Exclude<Scope, Scope.Transient> = this.scope,
+    ) => {
+      if ('asyncDispose' in Symbol === false) {
+        throw new Error(
+          'Symbol.asyncDispose is not supported in this environment',
+        )
+      }
+
+      const container = this.find(scope)
+      if (!container)
+        throw new Error('No container found for the specified scope')
+
+      const instance = await inject(injectable, context)
+      const dispose = container.createDisposeFunction()
+
+      return {
+        instance,
+        [Symbol.asyncDispose]: async () => {
+          await dispose(injectable, instance)
+        },
+      }
+    }
+
+    return Object.assign(inject, { explicit })
+  }
+
+  private createDisposeFunction() {
+    return async <T extends AnyInjectable>(injectable: T, instance?: any) => {
+      if (injectable.scope === Scope.Transient) {
+        assert(
+          instance,
+          'Instance is required for transient injectable disposal',
+        )
+        const wrappers = this.instances.get(injectable)
+        if (wrappers) {
+          for (const wrapper of wrappers) {
+            if (wrapper.public === instance) {
+              await this.disposeInjectableInstance(
+                injectable,
+                wrapper.private,
+                wrapper.context,
+              )
+              const index = wrappers.indexOf(wrapper)
+              wrappers.splice(index, 1)
+            }
+          }
+
+          if (wrappers.length === 0) {
+            this.instances.delete(injectable)
+          }
+        }
+      } else {
+        await this.disposeInjectableInstances(injectable)
+      }
+    }
+  }
+
+  private getDisposalOrder(): AnyInjectable[] {
+    const visited = new Set<AnyInjectable>()
+    const result: AnyInjectable[] = []
+
+    const visit = (injectable: AnyInjectable) => {
+      if (visited.has(injectable)) return
+      visited.add(injectable)
+
+      const dependants = this.dependants.get(injectable)
+      if (dependants) {
+        for (const dependant of dependants) {
+          if (this.instances.has(dependant)) {
+            visit(dependant)
+          }
+        }
+      }
+
+      // Only add to result if this container owns the instance
+      if (this.instances.has(injectable)) {
+        result.push(injectable)
+      }
+    }
+
+    for (const injectable of this.instances.keys()) {
+      visit(injectable)
+    }
+
+    return result
+  }
+}
+
+type InlineInjectionDependencies<T extends AnyInjectable> = {
+  [K in keyof T['dependencies']]?:
+    | ResolveInjectableType<T['dependencies'][K]>
+    | AnyInjectable<ResolveInjectableType<T['dependencies'][K]>>
+}
+
+export type InjectFn = ReturnType<Container['createInjectFunction']>
+export type DisposeFn = ReturnType<Container['createDisposeFunction']>

package/src/enums.ts

@@ -0,0 +1,6 @@
+export enum Scope {
+  Global = 'Global',
+  Connection = 'Connection',
+  Call = 'Call',
+  Transient = 'Transient',
+}

package/src/hooks.ts

@@ -0,0 +1,24 @@
+import type { NestedHooks } from 'hookable'
+import { Hookable } from 'hookable'
+
+import type { HookTypes } from './types.ts'
+
+export class Hooks<T extends HookTypes = HookTypes> extends Hookable<T> {
+  _!: { config: NestedHooks<T> }
+
+  createSignal<T extends keyof T>(
+    hook: T,
+  ): {
+    controller: AbortController
+    signal: AbortSignal
+    unregister: () => void
+  } {
+    const controller = new AbortController()
+    const unregister = this.hookOnce(
+      String(hook),
+      //@ts-expect-error
+      () => controller.abort(),
+    )
+    return { controller, signal: controller.signal, unregister }
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// // biome-ignore lint/correctness/noUnusedImports: TSC wants it
+// // biome-ignore assist/source/organizeImports: TSC wants it
+// import {} from 'pino'
+
+export * from './constants.ts'
+export * from './container.ts'
+export * from './enums.ts'
+export * from './hooks.ts'
+export * from './injectables.ts'
+export * from './logger.ts'
+export * from './metadata.ts'
+export * from './plugin.ts'
+export * from './types.ts'
+export * from './utils/index.ts'

package/src/injectables.ts

@@ -0,0 +1,359 @@
+import type { Async } from '@nmtjs/common'
+import { tryCaptureStackTrace } from '@nmtjs/common'
+
+import type { DisposeFn, InjectFn } from './container.ts'
+import type { Logger } from './logger.ts'
+import {
+  kFactoryInjectable,
+  kInjectable,
+  kLazyInjectable,
+  kOptionalDependency,
+  kValueInjectable,
+} from './constants.ts'
+import { Scope } from './enums.ts'
+
+const ScopeStrictness = {
+  [Scope.Transient]: Number.NaN, // this should make it always fail to compare with other scopes
+  [Scope.Global]: 1,
+  [Scope.Connection]: 2,
+  [Scope.Call]: 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 InjectablePickType<Input, Output> = (injectable: Input) => Output
+
+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
+  $withType<O extends T>(): LazyInjectable<O, S>
+  optional(): DependencyOptional<LazyInjectable<T, 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,
+  P = T,
+> extends Dependant<D> {
+  scope: S
+  factory: InjectableFactoryType<P, D>
+  pick: InjectablePickType<P, T>
+  dispose?: InjectableDisposeType<P, D>
+  optional(): DependencyOptional<FactoryInjectable<T, D, S, P>>
+  [kInjectable]: any
+  [kFactoryInjectable]: any
+}
+
+export type Injectable<
+  V = any,
+  D extends Dependencies = {},
+  S extends Scope = Scope,
+> = LazyInjectable<V, S> | ValueInjectable<V> | FactoryInjectable<V, D, S, any>
+
+export type AnyInjectable<T = any, S extends Scope = Scope> = Injectable<
+  T,
+  any,
+  S
+>
+
+export const isLazyInjectable = (
+  injectable: any,
+): injectable is LazyInjectable<any> => injectable[kLazyInjectable]
+
+export const isFactoryInjectable = (
+  injectable: any,
+): injectable is FactoryInjectable<any> => injectable[kFactoryInjectable]
+
+export const isValueInjectable = (
+  injectable: any,
+): injectable is ValueInjectable<any> => injectable[kValueInjectable]
+
+export const isInjectable = (
+  injectable: any,
+): injectable is AnyInjectable<any> => injectable[kInjectable]
+
+export const isOptionalInjectable = (
+  injectable: any,
+): injectable is DependencyOptional<any> => injectable[kOptionalDependency]
+
+export function getInjectableScope(injectable: AnyInjectable) {
+  let scope = injectable.scope
+  const deps = injectable.dependencies as Dependencies
+  for (const key in deps) {
+    const dependency = deps[key]
+    const injectable = getDepedencencyInjectable(dependency)
+    const dependencyScope = getInjectableScope(injectable)
+    if (
+      dependencyScope !== Scope.Transient &&
+      scope !== Scope.Transient &&
+      compareScope(dependencyScope, '>', scope)
+    ) {
+      scope = dependencyScope
+    }
+  }
+  return scope
+}
+
+export function getDepedencencyInjectable(
+  dependency: Depedency,
+): AnyInjectable {
+  if (kOptionalDependency in dependency) {
+    return dependency.injectable
+  }
+  return dependency
+}
+
+export function createOptionalInjectable<T extends AnyInjectable>(
+  injectable: T,
+) {
+  return Object.freeze({
+    [kOptionalDependency]: true,
+    injectable,
+  }) as DependencyOptional<T>
+}
+
+export function createLazyInjectable<T, S extends Scope = Scope.Global>(
+  scope = Scope.Global as S,
+  label?: string,
+  stackTraceDepth = 0,
+): LazyInjectable<T, S> {
+  const injectable = Object.freeze({
+    scope,
+    dependencies: {},
+    label,
+    stack: tryCaptureStackTrace(stackTraceDepth),
+    optional: () => createOptionalInjectable(injectable),
+    $withType: () => injectable as any,
+    [kInjectable]: true,
+    [kLazyInjectable]: true as unknown as T,
+  })
+  return injectable
+}
+
+export function createValueInjectable<T>(
+  value: T,
+  label?: string,
+  stackTraceDepth = 0,
+): ValueInjectable<T> {
+  return Object.freeze({
+    value,
+    scope: Scope.Global,
+    dependencies: {},
+    label,
+    stack: tryCaptureStackTrace(stackTraceDepth),
+    [kInjectable]: true,
+    [kValueInjectable]: true,
+  })
+}
+
+export function createFactoryInjectable<
+  T,
+  D extends Dependencies = {},
+  S extends Scope = Scope.Global,
+  P = T,
+>(
+  paramsOrFactory:
+    | {
+        dependencies?: D
+        scope?: S
+        pick?: InjectablePickType<P, T>
+        factory: InjectableFactoryType<P, D>
+        dispose?: InjectableDisposeType<P, D>
+      }
+    | InjectableFactoryType<P, D>,
+  label?: string,
+  stackTraceDepth = 0,
+): FactoryInjectable<null extends T ? P : T, D, S, P> {
+  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,
+    pick: params.pick ?? ((instance: P) => instance as unknown as T),
+    label,
+    stack: tryCaptureStackTrace(stackTraceDepth),
+    optional: () => createOptionalInjectable(injectable),
+    [kInjectable]: true,
+    [kFactoryInjectable]: true,
+  }
+  injectable.scope = resolveInjectableScope(
+    typeof params.scope === 'undefined',
+    injectable,
+  ) as S
+  return Object.freeze(injectable) as any
+}
+
+export type DependenciesSubstitution<T extends Dependencies> = {
+  [K in keyof T]?: T[K] extends AnyInjectable<infer Type>
+    ? AnyInjectable<Type> | DependenciesSubstitution<T[K]['dependencies']>
+    : never
+}
+
+export function substitute<T extends FactoryInjectable<any, any, Scope>>(
+  injectable: T,
+  substitution: DependenciesSubstitution<T['dependencies']>,
+  stackTraceDepth = 0,
+): T {
+  const dependencies = { ...injectable.dependencies }
+  const depth = stackTraceDepth + 1
+  for (const key in substitution) {
+    const value = substitution[key]!
+    if (key in dependencies) {
+      const original = dependencies[key]
+      if (isInjectable(value)) {
+        dependencies[key] = value
+      } else if (isFactoryInjectable(original)) {
+        dependencies[key] = substitute(original, value, depth)
+      }
+    }
+  }
+
+  if (isFactoryInjectable(injectable)) {
+    // @ts-expect-error
+    return createFactoryInjectable(
+      { ...injectable, dependencies },
+      injectable.label,
+      depth,
+    )
+  }
+
+  throw new Error('Invalid injectable type')
+}
+
+export 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')
+  }
+}
+
+const logger = Object.assign(
+  (label: string) =>
+    createFactoryInjectable({
+      dependencies: { logger },
+      scope: Scope.Global,
+      factory: ({ logger }) => logger.child({ $label: label }),
+    }),
+  createLazyInjectable<Logger>(Scope.Global, 'Logger'),
+) as unknown as ((
+  label: string,
+) => FactoryInjectable<Logger, { logger: LazyInjectable<Logger> }>) &
+  LazyInjectable<Logger>
+
+const inject = createLazyInjectable<InjectFn>(Scope.Global, 'Inject function')
+const dispose = createLazyInjectable<DisposeFn>(
+  Scope.Global,
+  'Dispose function',
+)
+
+function resolveInjectableScope(
+  isDefaultScope: boolean,
+  injectable: AnyInjectable,
+) {
+  const actualScope = getInjectableScope(injectable)
+  if (!isDefaultScope && compareScope(actualScope, '>', injectable.scope))
+    throw new Error(
+      `Invalid scope ${injectable.scope} for an injectable: dependencies have stricter scope - ${actualScope}`,
+    )
+  return actualScope
+}
+
+export const CoreInjectables = { logger, inject, dispose }
+
+export type Injection<
+  T extends AnyInjectable<any, any> = AnyInjectable<any, any>,
+> = {
+  token: T
+  value: T extends AnyInjectable<infer R, Scope> ? R | AnyInjectable<R> : never
+}
+
+export const provide = <
+  T extends AnyInjectable<any, any>,
+  V extends T extends AnyInjectable<infer R, Scope>
+    ? R | AnyInjectable<R>
+    : never,
+>(
+  token: T,
+  value: V,
+): Injection<T> => {
+  return { token, value }
+}

package/src/logger.ts

@@ -0,0 +1,103 @@
+import { threadId } from 'node:worker_threads'
+
+import type * as pinoType from 'pino'
+import { pino, stdTimeFunctions } from 'pino'
+import { build as pretty } from 'pino-pretty'
+
+export type { StreamEntry } from 'pino'
+export type Logger = pinoType.Logger
+export type LoggerOptions = pinoType.LoggerOptions
+export type LoggerChildOptions = pinoType.ChildLoggerOptions
+export type LoggingOptions = {
+  destinations?: Array<
+    pinoType.DestinationStream | pinoType.StreamEntry<pinoType.Level>
+  >
+  pinoOptions?: LoggerOptions
+}
+
+import { errWithCause } from 'pino-std-serializers'
+
+// 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 = {}, $lable: string) => {
+  let { destinations, pinoOptions } = options
+
+  if (!destinations || !destinations?.length) {
+    destinations = [
+      createConsolePrettyDestination(
+        (options.pinoOptions?.level || 'info') as pinoType.Level,
+      ),
+    ]
+  }
+
+  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]
+  const serializers = { ...pinoOptions?.serializers, err: errWithCause }
+
+  return pino(
+    { timestamp: stdTimeFunctions.isoTime, ...pinoOptions, level, serializers },
+    pino.multistream(destinations!),
+  ).child({ $lable, $threadId: threadId })
+}
+
+export const createConsolePrettyDestination = (
+  level: pinoType.Level,
+  sync = true,
+): pinoType.StreamEntry => ({
+  level,
+  stream: pretty({
+    colorize: true,
+    ignore: 'hostname,$lable,$threadId',
+    errorLikeObjectKeys: ['err', 'error', 'cause'],
+    messageFormat: (log, messageKey) => {
+      const group = fg(`[${log.$lable}]`, 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/src/metadata.ts

@@ -0,0 +1,24 @@
+import { kMetadata } from './constants.ts'
+
+export type Metadata<T = any> = { key: MetadataKey<T>; value: T }
+
+export type MetadataKey<T = any> = {
+  [kMetadata]: string
+  as(value: T): Metadata<T>
+}
+
+export const createMetadataKey = <T>(key: string): MetadataKey<T> => {
+  const metadataKey = {
+    [kMetadata]: key,
+    as(value: T) {
+      return { key: metadataKey, value }
+    },
+  }
+  return metadataKey
+}
+
+export class MetadataStore extends Map<MetadataKey, Metadata> {
+  get<T>(key: MetadataKey<T>): T | undefined {
+    return super.get(key) as T | undefined
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,16 @@
+import type { Async } from '@nmtjs/common'
+
+import { kPlugin } from './constants.ts'
+
+export interface Plugin<Type = void, Context = unknown> {
+  name: string
+  factory: (context: Context) => Async<Type>
+  [kPlugin]: any
+}
+
+export const createPlugin = <Type = void, Context = unknown>(
+  name: string,
+  factory: Plugin<Type, Context>['factory'],
+): Plugin<Type, Context> => ({ name, factory, [kPlugin]: true })
+
+export const isPlugin = (value: any): value is Plugin => kPlugin in value

package/src/types.ts

@@ -0,0 +1,3 @@
+export type { Pattern } from '@nmtjs/common'
+
+export type HookTypes = Record<string | symbol, any>

package/src/utils/functions.ts

@@ -0,0 +1,31 @@
+export { match } from '@nmtjs/common'
+
+export function isJsFile(name: string) {
+  if (name.endsWith('.d.ts')) return false
+  const leading = name.split('.').slice(1)
+  const ext = leading.join('.')
+  return ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts'].includes(ext)
+}
+
+export function pick<
+  T extends object,
+  K extends {
+    [KK in keyof T as T[KK] extends (...args: any[]) => any ? never : KK]?: true
+  },
+>(
+  obj: T,
+  keys: K,
+): Pick<
+  T,
+  keyof {
+    [KK in keyof K as K[KK] extends true ? KK : never]: K[KK]
+  }
+> {
+  const result = {} as any
+  for (const key in keys) {
+    if (key in obj) {
+      result[key] = obj[key as unknown as keyof typeof obj]
+    }
+  }
+  return result
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './functions.ts'
+export * from './pool.ts'
+export * from './semaphore.ts'

package/src/utils/pool.ts

@@ -0,0 +1,111 @@
+import type { Callback } from '@nmtjs/common'
+
+interface PoolOptions {
+  timeout?: number
+}
+
+interface PoolQueueItem {
+  resolve?: Callback
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export class PoolError extends Error {}
+
+// Fixed pool from https://github.com/metarhia/metautil
+export class Pool<T = unknown> {
+  #items: Array<T> = []
+  #free: Array<boolean> = []
+  #queue: PoolQueueItem[] = []
+  #current: number = 0
+  #size: number = 0
+  #available: number = 0
+
+  constructor(private readonly options: PoolOptions = {}) {}
+
+  add(item: T) {
+    if (this.#items.includes(item)) throw new PoolError('Item already exists')
+    this.#size++
+    this.#available++
+    this.#items.push(item)
+    this.#free.push(true)
+  }
+
+  remove(item: T) {
+    if (this.#size === 0) throw new PoolError('Pool is empty')
+    const index = this.#items.indexOf(item)
+    if (index < 0) throw new PoolError('Item is not in the pool')
+    const isCaptured = this.isFree(item)
+    if (isCaptured) this.#available--
+    this.#size--
+    this.#current--
+    this.#items.splice(index, 1)
+    this.#free.splice(index, 1)
+  }
+
+  capture(timeout = this.options.timeout) {
+    return this.next(true, timeout)
+  }
+
+  async next(exclusive = false, timeout = this.options.timeout): Promise<T> {
+    if (this.#size === 0) throw new PoolError('Pool is empty')
+    if (this.#available === 0) {
+      return new Promise((resolve, reject) => {
+        const waiting: PoolQueueItem = {
+          resolve: (item: T) => {
+            if (exclusive) this.#capture(item)
+            resolve(item)
+          },
+          timer: undefined,
+        }
+        if (timeout) {
+          waiting.timer = setTimeout(() => {
+            waiting.resolve = undefined
+            this.#queue.shift()
+            reject(new PoolError('Next item timeout'))
+          }, timeout)
+        }
+        this.#queue.push(waiting)
+      })
+    }
+    let item: T | undefined
+    let free = false
+    do {
+      item = this.#items[this.#current]
+      free = this.#free[this.#current]
+      this.#current++
+      if (this.#current >= this.#size) this.#current = 0
+    } while (typeof item === 'undefined' || !free)
+    if (exclusive) this.#capture(item)
+    return item
+  }
+
+  release(item: T) {
+    const index = this.#items.indexOf(item)
+    if (index < 0) throw new PoolError('Unexpected item')
+    if (this.#free[index])
+      throw new PoolError('Unable to release not captured item')
+    this.#free[index] = true
+    this.#available++
+    if (this.#queue.length > 0) {
+      const { resolve, timer } = this.#queue.shift()!
+      clearTimeout(timer)
+      if (resolve) setTimeout(resolve, 0, item)
+    }
+  }
+
+  isFree(item: T) {
+    const index = this.#items.indexOf(item)
+    if (index < 0) return false
+    return this.#free[index]
+  }
+
+  get items() {
+    return [...this.#items]
+  }
+
+  #capture(item: T) {
+    const index = this.#items.indexOf(item)
+    this.#free[index] = false
+    this.#available--
+  }
+}

package/src/utils/semaphore.ts

@@ -0,0 +1,63 @@
+import type { Callback } from '@nmtjs/common'
+
+interface SemaphoreQueueItem {
+  resolve?: Callback
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export class SemaphoreError extends Error {}
+
+// Semaphore from https://github.com/metarhia/metautil
+export class Semaphore {
+  private counter: number
+
+  private readonly queue: SemaphoreQueueItem[] = []
+
+  constructor(
+    concurrency: number,
+    private readonly size: number = 0,
+    private readonly timeout: number = 0,
+  ) {
+    this.counter = concurrency
+  }
+
+  enter(): Promise<void> {
+    if (this.counter > 0) {
+      this.counter--
+      return Promise.resolve()
+    } else if (this.queue.length >= this.size) {
+      return Promise.reject(new SemaphoreError('Queue is full'))
+    } else {
+      return new Promise((resolve, reject) => {
+        const waiting: SemaphoreQueueItem = { resolve }
+        waiting.timer = setTimeout(() => {
+          waiting.resolve = undefined
+          this.queue.shift()
+          reject(new SemaphoreError('Timeout'))
+        }, this.timeout)
+        this.queue.push(waiting)
+      })
+    }
+  }
+
+  leave() {
+    if (this.queue.length === 0) {
+      this.counter++
+    } else {
+      const item = this.queue.shift()
+      if (item) {
+        const { resolve, timer } = item
+        if (timer) clearTimeout(timer)
+        if (resolve) setTimeout(resolve, 0)
+      }
+    }
+  }
+
+  get isEmpty() {
+    return this.queue.length === 0
+  }
+
+  get queueLength() {
+    return this.queue.length
+  }
+}