Skip to Content
ErrorsNEXUS_INVALID_MODULE_OPTIONS

This page documents the 0.4 release candidates of @nexusdi/core. The newest on npm is 0.4.0-rc.1. The documentation for 0.3.2, the current release, is at nexus.js.org. Try the release candidate.

NEXUS_INVALID_MODULE_OPTIONS

NEXUS_INVALID_MODULE_OPTIONS means the options a configurable module received failed the module’s schema, a Standard Schema validator such as a valibot or zod schema. Core validates the options when it builds them, so Nexus.create rejects with NEXUS_PROVIDER_FAILED for the options token, and this error is its cause.

Reproduce NEXUS_INVALID_MODULE_OPTIONS

The region gives Comms a valibot schema that requires a positive integer frequency, and imports Comms.forRoot({ frequency: -5 }). The one-line message of the cause names the module, and the schema’s issues are in its issues field. explain() from @nexusdi/errors writes the full text with each issue and its path.

import { Nexus, Token, defineModule, isNexusError } from '@nexusdi/core';
import { provide } from '@nexusdi/core';
import { errors, explain } from '@nexusdi/errors';
import * as v from 'valibot';
 
interface CommsOptions {
  readonly frequency: number;
}
interface ISubspaceLink {
  readonly frequency: number;
}
const COMMS_OPTIONS = new Token<CommsOptions>('CommsOptions');
const SUBSPACE_LINK = new Token<ISubspaceLink>('SubspaceLink');
 
class SubspaceRelay implements ISubspaceLink {
  static deps = [COMMS_OPTIONS] as const;
  readonly frequency: number;
  constructor(options: CommsOptions) {
    this.frequency = options.frequency;
  }
}
 
const Comms = defineModule({
  name: 'Comms',
  options: COMMS_OPTIONS,
  schema: v.object({
    frequency: v.pipe(v.number(), v.integer(), v.minValue(1)),
  }),
  providers: [provide(SUBSPACE_LINK, { useClass: SubspaceRelay })],
  exports: [SUBSPACE_LINK],
});
const Meridian = defineModule({
  name: 'Meridian',
  imports: [Comms.forRoot({ frequency: -5 })],
});
 
const failed = await Nexus.create(Meridian, { plugins: [errors()] }).catch(
  (error: unknown) => error,
);
if (!isNexusError(failed, 'NEXUS_PROVIDER_FAILED')) throw failed;
const cause = failed.cause;
if (!isNexusError(cause, 'NEXUS_INVALID_MODULE_OPTIONS')) throw failed;
const line = cause.message; // -> '[NEXUS_INVALID_MODULE_OPTIONS] module=Comms. https://nexus.js.org/errors/NEXUS_INVALID_MODULE_OPTIONS'
console.log(line);
const text = explain(cause)?.message.split('\n'); // -> ['Comms received options its schema rejects:', '  frequency: Invalid value: Expected >=1 but received -5']
console.log(text);

Try it: install the packages with npm install valibot@1.5.0 @nexusdi/errors@next, save the region as error.ts and run npx tsx error.ts. It prints the one-line message of the cause, then the full text, which names the failing path, frequency. Then save the fix region below as fixed.ts and run npx tsx fixed.ts. It prints 1420.

Fix NEXUS_INVALID_MODULE_OPTIONS

NEXUS_INVALID_MODULE_OPTIONS is fixed by passing options the schema accepts. The issues name each failing path and the schema’s message for it.

import { Nexus, Token, defineModule, provide } from '@nexusdi/core';
import * as v from 'valibot';
 
interface CommsOptions {
  readonly frequency: number;
}
interface ISubspaceLink {
  readonly frequency: number;
}
const COMMS_OPTIONS = new Token<CommsOptions>('CommsOptions');
const SUBSPACE_LINK = new Token<ISubspaceLink>('SubspaceLink');
 
class SubspaceRelay implements ISubspaceLink {
  static deps = [COMMS_OPTIONS] as const;
  readonly frequency: number;
  constructor(options: CommsOptions) {
    this.frequency = options.frequency;
  }
}
 
const Comms = defineModule({
  name: 'Comms',
  options: COMMS_OPTIONS,
  schema: v.object({
    frequency: v.pipe(v.number(), v.integer(), v.minValue(1)),
  }),
  providers: [provide(SUBSPACE_LINK, { useClass: SubspaceRelay })],
  exports: [SUBSPACE_LINK],
});
 
await using ship = await Nexus.create(
  defineModule({
    name: 'Meridian',
    imports: [Comms.forRoot({ frequency: 1420 })],
  }),
);
const frequency = ship.get(SUBSPACE_LINK).frequency; // -> 1420
console.log(frequency);

Try it: change 1420 to -5 in fixed.ts and run it again. Nexus.create rejects with a ProviderError for CommsOptions in Comms, and its cause is the NEXUS_INVALID_MODULE_OPTIONS error. Change it back to 1420 and the program prints 1420 again.

Fields of ModuleOptionsError

ModuleOptionsError carries these fields for this code:

  • module: the configurable module whose options failed.
  • issues: the schema’s issues, each with a message and an optional path, in the Standard Schema shape.
ErrorsRegister a plugin