moleculer-zod-validator

moleculer-zod-validator

Validate Moleculer action parameters using the Zod validator.

Supports

• Supports Moleculer v0.14.x
• Supports Zod v3.x.x

Requires

As of v3.0.0, this package requires Node.js v17.0.0 or above.

Install

npm install moleculer-zod-validator

Usage

Broker

Import ZodValidator, then set up the validator in your broker settings using the validator property. For example:

// JavaScript
const { ServiceBroker } = require("moleculer");
const { ZodValidator } = require("moleculer-zod-validator");

// TypeScript
import { ServiceBroker } from "moleculer";
import { ZodValidator } from "moleculer-zod-validator";

const broker = new ServiceBroker({
    validator: new ZodValidator()
});

As of v3.0.0, moleculer-zod-validator implements the default Moleculer validator (fastest-validator) as a compatibility fallback for fastest-validator schemas, like those used in Moleculer's internal services, so calling services using that should not be a problem.

Actions

One of Zod's main features is how it can infer TypeScript types from a schema. To simplify the usage of this, there is a convenience utility called ZodParams that allows for easy access to the necessary data.

The ZodParams constructor takes one or two arguments, schema and optionally options.

• schema - This is a schema object that gets passed directly into z.object. For all available schema options, please look at the Zod documentation.
• options - This provides access to some of the different functions available on a standard Zod object. All booleans default to false except for strip, which is implicitly set to true.
  • partial (boolean) - Shallowly makes all properties optional. (docs)
  • deepPartial (boolean) - Deeply makes all properties optional. (docs)
  • strip (boolean) - Removes unrecognized keys from the parsed input. This is Zod's default behavior and this validator's default behavior. Mutually exclusive with passthrough and strict, and will override them if set. (docs)
  • passthrough (boolean) - Passes through unrecognized keys. Mutually exclusive with strict and strip. (docs)
  • strict (boolean) - Throws an error if unrecognized keys are present. Mutually exclusive with passthrough and strip. (docs)
  • catchall (Zod validator) - Validates all unknown keys against this schema. Obviates strict, passthrough, and strip. (docs)

Additionally, support for object transformations is present, allowing for the use of features such as preprocessing, refinements, transforms, and defaults.

Once constructed, there are four properties exposed on the ZodParams object.

• schema - The raw schema passed in. This should be passed to the params object in the action definition.
• context - The inferred output type from the compiled validator. This should be used within the Context object in the action definition to get the proper types after the parameters have passed through validation.
• call - The inferred input type from the compiled validator. This should be used with broker.call or ctx.call as the second type parameter to get proper types for the action call.
• validator - The compiled validator.

// It's easier to set up your validator objects outside of the service constructor so you can more easily access the typings later.
const simpleValidator = new ZodParams({
    string: z.string(),
    number: z.number(),
    optional: z.any().optional()
});

const complexValidator = new ZodParams({
    string: z.string(),
    number: z.number(),
    object: z.object({
        nestedString: z.string(),
        nestedBoolean: z.boolean()
    })
}, {
    partial: true,
    catchall: z.number()
}});

broker.createService({
    name: "example",
    actions: {
        simpleExample: {
            params: simpleValidator.schema, 
            handler(ctx: Context<typeof simpleValidator.context>) { ... }
        },
        complexExample: {
            params: complexValidator.schema,
            handler(ctx: Context<typeof complexExample.context>) { ... }
        }
    }
});

// ...

broker.call<
    ReturnType, 
    typeof simpleValidator.call
>({ string: "yes", number: 42 }); // calls successfully

broker.call<
    ReturnType, 
    typeof complexValidator.call
>({
    object: { 
        nestedString: "not optional", 
        nestedBoolean: false 
    }, 
    unrecognizedKey: 69 
}); // throws ValidationError

Changelog

3.0.0 (2023/4/13)

• BREAKING CHANGE - The minimum compatible Node.js version is now Node.js v17.0.0. This is due to the requirement of the structuredClone function in the fastest-validator fallback (described below), which in Node.js is only available in v17.0.0 and above. I tried using Lodash's cloneDeep method like Moleculer itself uses, but for a reason unknown to me it kept causing crashes during unit testing that I couldn't figure out. structuredClone does work, however, which should solve the same problem.
• Added support for passing in fastest-validator schemas. This is required because the $node internal services built into Moleculer assume that fastest-validator is the current validator, which poses a problem given as moleculer-zod-validator had no idea what to do with those schemas. By checking for the existence of property in the Zod schema that is not used in fastest-validator, this can now automatically switch into a failsafe that uses fastest-validator instead.
• Added new unit tests for the FV fallback
• Added descriptive type comments to ZodParams
• Added some files to the NPM build that should have been present before
• Updated dependencies
• Updated Github workflows to use newer Node.js versions
• Updated copyright year in LICENSE