nmtjs 0.15.0-beta.2 → 0.15.0-beta.20

package/src/index.ts

@@ -0,0 +1,82 @@
+import {
+  CoreInjectables,
+  createConsolePrettyDestination,
+  createFactoryInjectable,
+  createLazyInjectable,
+  createValueInjectable,
+} from '@nmtjs/core'
+import { createTransport, GatewayInjectables } from '@nmtjs/gateway'
+
+import {
+  createContractProcedure,
+  createContractRouter,
+  createFilter,
+  createGuard,
+  createHook,
+  createJob,
+  createJobsRouter,
+  createMiddleware,
+  createPlugin,
+  createProcedure,
+  createRootRouter,
+  createRouter,
+  createStep,
+  defineApplication,
+  defineServer,
+  jobOperation,
+  RuntimeInjectables,
+} from './runtime/index.ts'
+
+export const neemata = {
+  app: defineApplication,
+  server: defineServer,
+  injectables: {
+    ...CoreInjectables,
+    ...GatewayInjectables,
+    ...(RuntimeInjectables as typeof RuntimeInjectables),
+  },
+  transport: createTransport,
+  plugin: createPlugin,
+  logging: {
+    console:
+      // TODO: TSC wants it
+      createConsolePrettyDestination as typeof createConsolePrettyDestination,
+  },
+  value: createValueInjectable,
+  lazy: createLazyInjectable,
+  factory: createFactoryInjectable,
+  rootRouter: createRootRouter,
+  router: createRouter,
+  contractRouter: createContractRouter,
+  procedure: createProcedure,
+  contractProcedure: createContractProcedure,
+  middleware: createMiddleware,
+  guard: createGuard,
+  filter: createFilter,
+  job: createJob,
+  step: createStep,
+  hook: createHook,
+  jobRouter: Object.assign(createJobsRouter, { operation: jobOperation }),
+}
+
+export { c } from '@nmtjs/contract'
+export { Scope } from '@nmtjs/core'
+export {
+  type ConnectionIdentityType,
+  GatewayHook,
+  ProxyableTransportType,
+} from '@nmtjs/gateway'
+export { ConnectionType, ErrorCode, ProtocolBlob } from '@nmtjs/protocol'
+export { t } from '@nmtjs/type'
+
+export {
+  ApiError,
+  defineApplication,
+  JobWorkerPool,
+  LifecycleHook,
+  StoreType,
+  WorkerType,
+} from './runtime/index.ts'
+
+export { neemata as n }
+export default neemata

package/src/resolver.ts

@@ -0,0 +1,16 @@
+import { ResolverFactory } from 'oxc-resolver'
+
+const fallback: Record<string, [string]> = {}
+
+try {
+  // oxc-resolver fails to resolve uWebSockets.js for some reason
+  const mdl = 'uWebSockets.js'
+  const path = import.meta.resolve(mdl)
+  fallback[mdl] = [path]
+} catch {}
+
+export const resolver = new ResolverFactory({
+  tsconfig: 'auto',
+  extensions: ['.ts', '.js', '.mjs', '.mts', '.json', '.node'],
+  fallback,
+})

package/src/runtime/application/api/api.ts

@@ -0,0 +1,265 @@
+import assert from 'node:assert'
+import { inspect } from 'node:util'
+
+import type { Container, Logger } from '@nmtjs/core'
+import type {
+  GatewayApi,
+  GatewayApiCallOptions,
+  GatewayApiCallResult,
+  GatewayConnection,
+} from '@nmtjs/gateway'
+import { withTimeout } from '@nmtjs/common'
+import { IsStreamProcedureContract } from '@nmtjs/contract'
+import { Scope } from '@nmtjs/core'
+import { isAsyncIterable, rpcStreamAbortSignal } from '@nmtjs/gateway'
+import { ErrorCode } from '@nmtjs/protocol'
+import { ProtocolError } from '@nmtjs/protocol/server'
+import { NeemataTypeError, registerDefaultLocale, type } from '@nmtjs/type'
+import { prettifyError } from 'zod/mini'
+
+import type { kDefaultProcedure as kDefaultProcedureKey } from './constants.ts'
+import type { AnyFilter } from './filters.ts'
+import type { AnyGuard } from './guards.ts'
+import type { AnyMiddleware } from './middlewares.ts'
+import type { AnyProcedure } from './procedure.ts'
+import type { AnyRouter } from './router.ts'
+import type { ApiCallContext } from './types.ts'
+import { kDefaultProcedure } from './constants.ts'
+
+registerDefaultLocale()
+
+export type ApiCallOptions<T extends AnyProcedure = AnyProcedure> = Readonly<{
+  connection: GatewayConnection
+  path: AnyRouter[]
+  procedure: T
+  container: Container
+  payload: any
+  signal: AbortSignal
+}>
+
+export type ApiOptions = {
+  timeout?: number
+  container: Container
+  logger: Logger
+  procedures: Map<
+    string | kDefaultProcedureKey,
+    { procedure: AnyProcedure; path: AnyRouter[] }
+  >
+  guards: Set<AnyGuard>
+  middlewares: Set<AnyMiddleware>
+  filters: Set<AnyFilter>
+}
+
+export class ApiError extends ProtocolError {
+  toString() {
+    return `${this.code} ${this.message}: \n${inspect(this.data, true, 10, false)}`
+  }
+}
+
+const NotFound = () => new ApiError(ErrorCode.NotFound, 'Procedure not found')
+
+export class ApplicationApi implements GatewayApi {
+  constructor(public options: ApiOptions) {}
+
+  find(procedureName: string) {
+    const procedure = this.options.procedures.get(procedureName)
+    if (procedure) return procedure
+
+    const fallback = this.options.procedures.get(kDefaultProcedure)
+    if (fallback) return fallback
+
+    throw NotFound()
+  }
+
+  async call(options: GatewayApiCallOptions): Promise<GatewayApiCallResult> {
+    const { payload, container, signal, connection } = options
+
+    const { procedure, path } = this.find(options.procedure)
+
+    options.metadata?.(procedure.metadata)
+
+    const callOptions = Object.freeze({
+      payload,
+      container,
+      signal,
+      connection,
+      procedure,
+      path,
+    })
+
+    assert(
+      container.scope === Scope.Call,
+      'Invalid container scope, expected to be Scope.Call',
+    )
+
+    const timeout = procedure.contract.timeout ?? this.options.timeout
+    const isIterableProcedure = IsStreamProcedureContract(procedure.contract)
+    const streamTimeoutSignal = procedure.streamTimeout
+      ? AbortSignal.timeout(procedure.streamTimeout)
+      : undefined
+
+    if (streamTimeoutSignal) {
+      container.provide(rpcStreamAbortSignal, streamTimeoutSignal)
+    }
+
+    try {
+      const handle = await this.createProcedureHandler(callOptions)
+      const result = timeout
+        ? await this.withTimeout(handle(payload), timeout)
+        : await handle(payload)
+      if (isIterableProcedure) {
+        return this.handleIterableOutput(procedure, result)
+      } else {
+        return this.handleOutput(procedure, result)
+      }
+    } catch (error) {
+      const handled = await this.handleFilters(callOptions, error)
+      if (handled === error && error instanceof ProtocolError === false) {
+        const logError = new Error('Unhandled error', { cause: error })
+        this.options.logger.debug(logError)
+        throw new ApiError(
+          ErrorCode.InternalServerError,
+          'Internal Server Error',
+        )
+      }
+      throw handled
+    }
+  }
+
+  private async createProcedureHandler(callOptions: ApiCallOptions) {
+    const { connection, procedure, container, path } = callOptions
+
+    const callCtx: ApiCallContext = Object.freeze({
+      connection,
+      container,
+      path,
+      procedure,
+    })
+
+    const middlewares = await this.resolveMiddlewares(callOptions)
+
+    const handleProcedure = async (payload: any) => {
+      const middleware = middlewares.next().value
+      if (middleware) {
+        const next = (...args: any[]) =>
+          handleProcedure(args.length === 0 ? payload : args[0])
+        return middleware.handle(middleware.ctx, callCtx, next, payload)
+      } else {
+        await this.handleGuards(callOptions, callCtx)
+        const { dependencies } = procedure
+        const context = await container.createContext(dependencies)
+        const input = this.handleInput(procedure, payload)
+        const result = await procedure.handler(context, input)
+        return result
+      }
+    }
+
+    return handleProcedure
+  }
+
+  private async resolveMiddlewares(callOptions: ApiCallOptions) {
+    const { path, procedure, container } = callOptions
+    const middlewares = [
+      ...this.options.middlewares,
+      ...path.flatMap((router) => [...router.middlewares]),
+      ...procedure.middlewares,
+    ]
+    const result = await Promise.all(
+      middlewares.map(async (middleware) => {
+        const ctx = await container.createContext(middleware.dependencies)
+        return { handle: middleware.handle, ctx }
+      }),
+    )
+    return result[Symbol.iterator]()
+  }
+
+  private withTimeout(response: any, timeout: number): unknown {
+    const applyTimeout = response instanceof Promise && timeout > 0
+    if (!applyTimeout) return response
+    return withTimeout(
+      response,
+      timeout,
+      new ApiError(ErrorCode.RequestTimeout, 'Request Timeout'),
+    )
+  }
+
+  private async handleGuards(
+    callOptions: ApiCallOptions,
+    callCtx: ApiCallContext,
+  ) {
+    const { path, procedure, container } = callOptions
+    const guards = [
+      ...this.options.guards,
+      ...path.flatMap((router) => [...router.guards]),
+      ...procedure.guards,
+    ]
+    for (const guard of guards) {
+      const ctx = await container.createContext(guard.dependencies)
+      const result = await guard.can(ctx, callCtx)
+      if (result === false) throw new ApiError(ErrorCode.Forbidden)
+    }
+  }
+
+  private async handleFilters({ container }: ApiCallOptions, error: any) {
+    if (this.options.filters.size) {
+      for (const filter of this.options.filters) {
+        if (error instanceof filter.errorClass) {
+          const ctx = await container.createContext(filter.dependencies)
+          const handledError = await filter.catch(ctx, error)
+          if (!handledError || handledError instanceof ApiError === false)
+            continue
+          return handledError
+        }
+      }
+    }
+    return error
+  }
+
+  private handleInput(procedure: AnyProcedure, payload: any) {
+    if (procedure.contract.input instanceof type.NeverType === false) {
+      const type = procedure.contract.input
+      try {
+        return type.decode(payload)
+      } catch (error) {
+        if (error instanceof NeemataTypeError)
+          throw new ApiError(
+            ErrorCode.ValidationError,
+            `Input validation error: \n${prettifyError(error)}`,
+            error.issues,
+          )
+        throw error
+      }
+    }
+  }
+
+  private handleIterableOutput(procedure: AnyProcedure, response: any) {
+    if (!isAsyncIterable(response))
+      throw new Error('Response is an async iterable')
+    const chunkType = procedure.contract.output
+    if (chunkType instanceof type.NeverType)
+      throw new Error('Stream procedure must have a defined output type')
+
+    return async function* (onDone?: () => void) {
+      try {
+        if (chunkType instanceof type.AnyType === false) {
+          for await (const chunk of response) {
+            const encoded = chunkType.encode(chunk)
+            yield encoded
+          }
+        } else {
+          yield* response
+        }
+      } finally {
+        onDone?.()
+      }
+    }
+  }
+
+  private handleOutput(procedure: AnyProcedure, response: any) {
+    if (procedure.contract.output instanceof type.NeverType === false) {
+      const type = procedure.contract.output
+      return type.encode(response)
+    }
+    return undefined
+  }
+}

package/src/runtime/application/api/constants.ts

@@ -0,0 +1,22 @@
+export const kProcedure: unique symbol = Symbol.for('neemata:ProcedureKey')
+export type kProcedure = typeof kProcedure
+
+export const kDefaultProcedure: unique symbol = Symbol.for(
+  'neemata:DefaultProcedureKey',
+)
+export type kDefaultProcedure = typeof kDefaultProcedure
+
+export const kRouter: unique symbol = Symbol.for('neemata:RouterKey')
+export type kRouter = typeof kRouter
+
+export const kRootRouter: unique symbol = Symbol.for('neemata:RootRouterKey')
+export type kRootRouter = typeof kRootRouter
+
+export const kMiddleware: unique symbol = Symbol.for('neemata:MiddlewareKey')
+export type kMiddleware = typeof kMiddleware
+
+export const kGuard: unique symbol = Symbol.for('neemata:GuardKey')
+export type kGuard = typeof kGuard
+
+export const kFilter: unique symbol = Symbol.for('neemata:FilterKey')
+export type kFilter = typeof kFilter

package/src/runtime/application/api/filters.ts

@@ -0,0 +1,39 @@
+import type { ErrorClass, MaybePromise } from '@nmtjs/common'
+import type { Dependant, Dependencies, DependencyContext } from '@nmtjs/core'
+
+import { kFilter } from './constants.ts'
+
+export interface Filter<
+  FilterError extends ErrorClass = ErrorClass,
+  Deps extends Dependencies = Dependencies,
+> extends Dependant<Deps> {
+  [kFilter]: true
+  errorClass: FilterError
+  catch: (
+    ctx: DependencyContext<Deps>,
+    error: InstanceType<FilterError>,
+  ) => MaybePromise<Error>
+}
+
+export type AnyFilter<Error extends ErrorClass = ErrorClass> = Filter<
+  Error,
+  any
+>
+
+export function createFilter<
+  FilterError extends ErrorClass,
+  Deps extends Dependencies = {},
+>(params: {
+  errorClass: FilterError
+  dependencies?: Deps
+  catch: Filter<FilterError, Deps>['catch']
+}): Filter<FilterError, Deps> {
+  const { errorClass, catch: handler, dependencies = {} as Deps } = params
+
+  return Object.freeze({
+    errorClass,
+    dependencies,
+    catch: handler,
+    [kFilter]: true,
+  }) as Filter<FilterError, Deps>
+}

package/src/runtime/application/api/guards.ts

@@ -0,0 +1,29 @@
+import type { MaybePromise } from '@nmtjs/common'
+import type { Dependant, Dependencies, DependencyContext } from '@nmtjs/core'
+
+import type { ApiCallContext } from './types.ts'
+import { kGuard } from './constants.ts'
+
+export interface Guard<Deps extends Dependencies = Dependencies>
+  extends Dependant<Deps> {
+  [kGuard]: true
+  can: (
+    ctx: DependencyContext<Deps>,
+    call: ApiCallContext,
+  ) => MaybePromise<boolean>
+}
+
+export type AnyGuard = Guard<any>
+
+export function createGuard<Deps extends Dependencies = {}>(
+  paramsOrHandler:
+    | { dependencies?: Deps; can: Guard<Deps>['can'] }
+    | Guard<Deps>['can'],
+): Guard<Deps> {
+  const { dependencies = {} as Deps, can } =
+    typeof paramsOrHandler === 'function'
+      ? { can: paramsOrHandler }
+      : paramsOrHandler
+
+  return Object.freeze({ dependencies, can, [kGuard]: true }) as Guard<Deps>
+}

package/src/runtime/application/api/index.ts

@@ -0,0 +1,8 @@
+export * from './api.ts'
+export * from './constants.ts'
+export * from './filters.ts'
+export * from './guards.ts'
+export * from './middlewares.ts'
+export * from './procedure.ts'
+export * from './router.ts'
+export * from './types.ts'

package/src/runtime/application/api/middlewares.ts

@@ -0,0 +1,37 @@
+import type { MaybePromise } from '@nmtjs/common'
+import type { Dependant, Dependencies, DependencyContext } from '@nmtjs/core'
+
+import type { ApiCallContext } from './types.ts'
+import { kMiddleware } from './constants.ts'
+
+export type MiddlewareNext = (payload?: any) => any
+
+export interface Middleware<Deps extends Dependencies = Dependencies>
+  extends Dependant<Deps> {
+  [kMiddleware]: true
+  handle: (
+    ctx: DependencyContext<Deps>,
+    call: ApiCallContext,
+    next: MiddlewareNext,
+    payload: any,
+  ) => MaybePromise<any>
+}
+
+export type AnyMiddleware = Middleware<any>
+
+export function createMiddleware<Deps extends Dependencies = {}>(
+  paramsOrHandler:
+    | { dependencies?: Deps; handle: Middleware<Deps>['handle'] }
+    | Middleware<Deps>['handle'],
+): Middleware<Deps> {
+  const { dependencies = {} as Deps, handle } =
+    typeof paramsOrHandler === 'function'
+      ? { handle: paramsOrHandler }
+      : paramsOrHandler
+
+  return Object.freeze({
+    dependencies,
+    handle,
+    [kMiddleware]: true,
+  }) as Middleware<Deps>
+}