Migrating Echoes to OrionJS 4.5

OrionJS 4.5 separates Echoes from the rest of the framework. @orion-js/echoes can now run in a plain Node.js service without loading Orion’s schema, services, HTTP, environment, helpers, or logger packages. OrionJS minor releases are coordinated: every @orion-js/* package is published as 4.5.0. Upgrade all OrionJS packages used by an application together instead of mixing 4.4 and 4.5 package dependencies inside the same process. Existing Orion applications keep the same schema cleaning and validation, dependency injection, HTTP routes, logger context, and error classes through the new @orion-js/echoes-orion adapter. The event and request wire formats have not changed, so 4.4 and 4.5 services can communicate while you deploy the migration incrementally.

Choose your migration path

Applications using Components

Upgrade Echoes and Components, along with the rest of the OrionJS packages used by the application:

bun add @orion-js/echoes@^4.5.0 @orion-js/components@^4.5.0

@orion-js/components installs and initializes the Orion adapter automatically. Existing Echoes controllers can continue using raw Orion schemas and @Inject():

import {createEchoRequest, Echoes, EchoRequest} from '@orion-js/echoes'
import {Inject} from '@orion-js/services'

@Echoes()
export class UsersEchoes {
  @Inject(() => UsersService)
  private usersService!: UsersService

  @EchoRequest()
  findUser = createEchoRequest({
    params: {
      userId: {type: String},
    },
    returns: UserSchema,
    resolve: ({userId}) => this.usersService.findById(userId),
  })
}

No controller rewrite is required.

Orion applications using Echoes directly

If the application does not import @orion-js/components, install the adapter explicitly:

bun add @orion-js/echoes@^4.5.0 @orion-js/echoes-orion@^4.5.0

Import it once in the application entrypoint, before importing any module that declares an Echoes controller:

import '@orion-js/echoes-orion'

import {startApplication} from './app'

await startApplication()

Import order matters for decorated classes. The adapter must be installed before @Echoes() runs so Orion can capture @Inject() metadata for that controller.

Services that do not use Orion

Install only the standalone package:

bun add @orion-js/echoes

Echoes accepts SimpleSchema-compatible objects with clean() and validate() methods. Use typedEchoesSchema() when you want to attach a TypeScript value type to the runtime schema:

import SimpleSchema from 'simpl-schema'
import {createEchoRequest, typedEchoesSchema} from '@orion-js/echoes'

const params = typedEchoesSchema<{email: string}>(
  new SimpleSchema({
    email: {type: String},
  }),
)

export const findUser = createEchoRequest({
  params,
  async resolve({email}) {
    return users.findByEmail(email)
  },
})

For another schema library, install an adapter once with configureEchoesRuntime():

import {configureEchoesRuntime} from '@orion-js/echoes'

configureEchoesRuntime({
  schema: {
    async parse(schema, value) {
      return schema.parse(value)
    },
    async clean(schema, value) {
      return schema.clean(value)
    },
  },
})

Runtime schema behavior is preserved

Echoes 4.5 still executes this pipeline for every handler:

Deserialize the incoming value.
Clean handler parameters.
Validate handler parameters.
Run the resolver.
Clean the return value.
Serialize the response.

The Orion adapter delegates parameter cleaning and validation to @orion-js/schema.cleanAndValidate() and return cleaning to @orion-js/schema.clean(). Defaults, custom cleaners, custom validators, field types, and ValidationError therefore behave as they did in 4.4.

Install the event transports you use

Kafka and Pulse are now optional peers. Neither is loaded when a service only uses synchronous Echoes requests. For Kafka:

bun add kafkajs

For Pulse:

bun add @orion-js/pulse mongodb

The existing configuration remains valid:

await startService({
  echoes,
  events: {
    pulse: {
      connectionString: process.env.MONGO_URL,
      databaseName: 'events',
      consumerGroup: 'billing',
      maxPoolSize: 1,
      maxIdleTimeMS: 30_000,
    },
    consumeFrom: ['pulse'],
    publishTo: 'pulse',
  },
})

Pulse now uses polling and reconciliation exclusively. If an application previously configured events.pulse.changeStreams, remove that field during the upgrade. It is no longer part of the Echoes or Pulse public types, and leaving it in a JavaScript configuration makes startup fail fast instead of silently selecting another mode. If you are migrating event traffic from Kafka to Pulse, follow the incremental Kafka-to-Pulse rollout.

Standalone HTTP receivers

Orion applications continue registering /echoes-services through @orion-js/http. Standalone services provide a small registrar for their HTTP framework:

await startService({
  echoes,
  requests: {
    key: process.env.ECHOES_PASSWORD,
    registerHandler(definition) {
      app.post(definition.path, express.json({limit: definition.bodyLimit}), async (req, res) => {
        res.json(await definition.handle(req.body))
      })
    },
  },
})

The default request client now uses Node.js HTTP and HTTPS directly, including redirects, retries, and timeouts. Axios and jssha are no longer required application dependencies.

Recommended rollout

Upgrade listener services first.
Verify that Orion apps load @orion-js/echoes-orion, directly or through Components.
Install kafkajs explicitly in every service that still uses Kafka.
Deploy publishers after listeners are healthy.
Run the compiler, build, and application tests.

bun run typecheck
bun run build
bun test

Because the wire format is unchanged, this can be a normal rolling deployment. No MongoDB data migration, Kafka topic migration, or coordinated downtime is required for the 4.5 package upgrade.

​Choose your migration path

​Applications using Components

​Orion applications using Echoes directly

​Services that do not use Orion

​Runtime schema behavior is preserved

​Install the event transports you use

​Standalone HTTP receivers

​Recommended rollout

Choose your migration path

Applications using Components

Orion applications using Echoes directly

Services that do not use Orion

Runtime schema behavior is preserved

Install the event transports you use

Standalone HTTP receivers

Recommended rollout