Updated documentation, including type comments

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 ## 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. 
-* **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, 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 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

README.md

@@ -60,7 +60,7 @@ Additionally, support for object transformations is present, allowing for the us
 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 Moleculer to get the proper types after the parameters have passed through validation. 
+* `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. 
 

src/params.ts

@@ -1,13 +1,25 @@
 import { z } from "zod";
 
+import type { ZodRawShape } from "zod";
+
+/**
+ * An adapter for a standard {@link https://github.com/colinhacks/zod#objects ZodObject},
+ * which can be easier to work with in Moleculer than Zod on its own.
+ */
 export class ZodParams<Schema extends Parameters<(typeof z)["object"]>[0]> {
     private _rawSchema: Schema;
     private _rawSchemaWithOptions!: Schema & {
         $$$options: z.infer<typeof ZodParamsOptions>;
     };
     public readonly _validator;
 
-    constructor(schema: Schema, options?: z.infer<typeof ZodParamsOptions>) {
+    /**
+     * Creates a new ZodParams adapter, which can be used to more easily provide typing information to Moleculer services and calls.
+     * @param {ZodRawShape} schema - The schema used in {@link https://github.com/colinhacks/zod#objects z.object()}.
+     * @param {ZodParamsOptionsType} options - This exposes several methods available on the ZodObject type, 
+     * {@link https://github.com/colinhacks/zod#table-of-contents which can be referenced under the Objects section in the Zod documentation}.
+     */
+    constructor(schema: Schema, options?: ZodParamsOptionsType) {
         this._rawSchema = schema;
 
         options = Object.assign(
@@ -19,7 +31,7 @@ export class ZodParams<Schema extends Parameters<(typeof z)["object"]>[0]> {
                 catchall: undefined,
                 strip: false,
                 passthrough: false
-            } as z.infer<typeof ZodParamsOptions>,
+            } as ZodParamsOptionsType,
             options
         );
 
@@ -56,18 +68,63 @@ export class ZodParams<Schema extends Parameters<(typeof z)["object"]>[0]> {
         });
     }
 
+    /**
+     * Returns the raw Zod schema provided in the constructor. This should be passed
+     * to the `params` object in the action definition.
+     *
+     * @example
+     * broker.createService({
+     *     name: "example",
+     *     actions: {
+     *         exampleAction: {
+     *             params: zodParamObject.schema,
+     *             handler(ctx: Context<typeof zodParamObject.context>) { ... }
+     *         }
+     *     }
+     * });
+     */
     get schema() {
         return this._rawSchemaWithOptions;
     }
 
+    /**
+     * Returns the compiled ZodObject validator.
+     */
     get validator() {
         return this._validator;
     }
 
+    /**
+     * 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.
+     *
+     * @example
+     * broker.call<
+     *     ReturnType,
+     *     typeof zodParamObject.call
+     * >({ ... })
+     */
     get call() {
         return this._validator._input;
     }
 
+    /**
+     * 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.
+     *
+     * @example
+     * broker.createService({
+     *     name: "example",
+     *     actions: {
+     *         exampleAction: {
+     *             params: zodParamObject.schema,
+     *             handler(ctx: Context<typeof zodParamObject.context>) { ... }
+     *         }
+     *     }
+     * });
+     */
     get context() {
         return this._validator._output;
     }