@naturalcycles/backend-lib 9.16.0 → 9.17.0

package/dist/bin/deploy-gae.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runScript } from '@naturalcycles/nodejs-lib';
+import { runScript } from '@naturalcycles/nodejs-lib/runScript';
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs';
 import { deployGae } from '../deploy/deployGae.js';
 import { deployHealthCheckYargsOptions } from '../deploy/deployHealthCheck.js';

package/dist/bin/deploy-health-check.js

@@ -7,7 +7,7 @@ yarn deploy-health-check --url https://service-dot-yourproject.appspot.com
 --intervalSec 2
 
  */
-import { runScript } from '@naturalcycles/nodejs-lib';
+import { runScript } from '@naturalcycles/nodejs-lib/runScript';
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs';
 import { deployHealthCheck, deployHealthCheckYargsOptions } from '../deploy/deployHealthCheck.js';
 runScript(async () => {

package/dist/bin/deploy-prepare.js

@@ -4,7 +4,7 @@
 yarn deploy-prepare
 
  */
-import { runScript } from '@naturalcycles/nodejs-lib';
+import { runScript } from '@naturalcycles/nodejs-lib/runScript';
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs';
 import { deployPrepare, deployPrepareYargsOptions } from '../deploy/deployPrepare.js';
 runScript(async () => {

package/dist/bin/undeploy-gae.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runScript } from '@naturalcycles/nodejs-lib';
+import { runScript } from '@naturalcycles/nodejs-lib/runScript';
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs';
 import { undeployGae } from '../deploy/deployGae.js';
 runScript(async () => {

package/dist/deploy/backend.cfg.util.js

@@ -1,9 +1,11 @@
+import { _lazyValue } from '@naturalcycles/js-lib';
 import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv';
 import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
 import { yaml2 } from '@naturalcycles/nodejs-lib/yaml2';
 import { resourcesDir } from '../paths.cnst.js';
-const backendCfgSchema = AjvSchema.readJsonSync(`${resourcesDir}/backendCfg.schema.json`, {
-    objectName: 'backend.cfg.yaml',
+const getBackendCfgSchema = _lazyValue(() => {
+    const schemaJson = fs2.readJson(`${resourcesDir}/backendCfg.schema.json`);
+    return AjvSchema.create(schemaJson, { objectName: 'backend.cfg.yaml' });
 });
 export function getBackendCfg(projectDir = '.') {
     const backendCfgYamlPath = `${projectDir}/backend.cfg.yaml`;
@@ -11,6 +13,6 @@ export function getBackendCfg(projectDir = '.') {
     const backendCfg = {
         ...yaml2.readYaml(backendCfgYamlPath),
     };
-    backendCfgSchema.validate(backendCfg);
+    getBackendCfgSchema().validate(backendCfg);
     return backendCfg;
 }

package/dist/validation/ajv/ajvValidateRequest.d.ts

@@ -1,6 +1,6 @@
 import type { AjvSchema, AjvValidationError } from '@naturalcycles/nodejs-lib/ajv';
 import type { BackendRequest } from '../../server/server.model.js';
-import type { ReqValidationOptions } from '../joi/joiValidateRequest.js';
+import { type ReqValidationOptions } from '../validateRequest.util.js';
 declare class AjvValidateRequest {
     body<T>(req: BackendRequest, schema: AjvSchema<T>, opt?: ReqValidationOptions<AjvValidationError>): T;
     query<T>(req: BackendRequest, schema: AjvSchema<T>, opt?: ReqValidationOptions<AjvValidationError>): T;

package/dist/validation/ajv/ajvValidateRequest.js

@@ -1,5 +1,4 @@
-import { AppError } from '@naturalcycles/js-lib/error';
-import { _get } from '@naturalcycles/js-lib/object';
+import { handleValidationError } from '../validateRequest.util.js';
 class AjvValidateRequest {
     body(req, schema, opt = {}) {
         return this.validate(req, 'body', schema, opt);
@@ -20,53 +19,23 @@ class AjvValidateRequest {
      * Keep in mind that this will also remove all values that are not in the schema.
      */
     headers(req, schema, opt = {}) {
-        const options = {
-            keepOriginal: true,
+        return this.validate(req, 'headers', schema, {
+            mutate: false,
             ...opt,
-        };
-        return this.validate(req, 'headers', schema, options);
+        });
     }
     validate(req, reqProperty, schema, opt = {}) {
-        const value = { ...req[reqProperty] }; // destructure to avoid being mutated by Ajv
-        // It will mutate the `value`, but not the original object
-        const error = schema.getValidationError(value, {
+        const { mutate = true } = opt;
+        const originalProperty = req[reqProperty] || {};
+        const item = mutate ? originalProperty : { ...originalProperty };
+        // Ajv mutates the input
+        const error = schema.getValidationError(item, {
             objectName: `request ${reqProperty}`,
         });
         if (error) {
-            let report;
-            if (typeof opt.report === 'boolean') {
-                report = opt.report;
-            }
-            else if (typeof opt.report === 'function') {
-                report = opt.report(error);
-            }
-            if (opt.redactPaths) {
-                redact(opt.redactPaths, req[reqProperty], error);
-            }
-            throw new AppError(error.message, {
-                backendResponseStatusCode: 400,
-                report,
-                ...error.data,
-            });
-        }
-        // mutate req to replace the property with the value, converted by Joi
-        if (!opt.keepOriginal && reqProperty !== 'query') {
-            // query is read-only in Express 5
-            req[reqProperty] = value;
+            handleValidationError(error, originalProperty, opt);
         }
-        return value;
+        return item;
     }
 }
 export const ajvValidateRequest = new AjvValidateRequest();
-const REDACTED = 'REDACTED';
-/**
- * Mutates error
- */
-function redact(redactPaths, obj, error) {
-    redactPaths
-        .map(path => _get(obj, path))
-        .filter(Boolean)
-        .forEach(secret => {
-        error.message = error.message.replaceAll(secret, REDACTED);
-    });
-}

package/dist/validation/joi/joiValidateRequest.d.ts

@@ -1,23 +1,6 @@
 import type { AnySchema, JoiValidationError } from '@naturalcycles/nodejs-lib/joi';
 import type { BackendRequest } from '../../server/server.model.js';
-export interface ReqValidationOptions<ERR extends Error> {
-    /**
-     * Pass a 'dot-paths' (e.g `pw`, or `input.pw`) that needs to be redacted from the output, in case of error.
-     * Useful e.g to redact (prevent leaking) plaintext passwords in error messages.
-     */
-    redactPaths?: string[];
-    /**
-     * Set to true, or a function that returns true/false based on the error generated.
-     * If true - `genericErrorHandler` will report it to errorReporter (aka Sentry).
-     */
-    report?: boolean | ((err: ERR) => boolean);
-    /**
-     * When set to true, the validated object will not be replaced with the Joi-converted value.
-     *
-     * The general default is `false`, with the excepction of `headers` validation, where the default is `true`.
-     */
-    keepOriginal?: boolean;
-}
+import { type ReqValidationOptions } from '../validateRequest.util.js';
 declare class ValidateRequest {
     body<T>(req: BackendRequest, schema: AnySchema<T>, opt?: ReqValidationOptions<JoiValidationError>): T;
     query<T>(req: BackendRequest, schema: AnySchema<T>, opt?: ReqValidationOptions<JoiValidationError>): T;

package/dist/validation/joi/joiValidateRequest.js

@@ -1,6 +1,5 @@
-import { AppError } from '@naturalcycles/js-lib/error';
-import { _get } from '@naturalcycles/js-lib/object';
 import { getValidationResult } from '@naturalcycles/nodejs-lib/joi';
+import { handleValidationError } from '../validateRequest.util.js';
 class ValidateRequest {
     body(req, schema, opt = {}) {
         return this.validate(req, 'body', schema, opt);
@@ -21,51 +20,27 @@ class ValidateRequest {
      * Keep in mind that this will also remove all values that are not in the schema.
      */
     headers(req, schema, opt = {}) {
-        const options = {
-            keepOriginal: true,
+        return this.validate(req, 'headers', schema, {
+            mutate: false,
             ...opt,
-        };
-        return this.validate(req, 'headers', schema, options);
+        });
     }
     validate(req, reqProperty, schema, opt = {}) {
-        const { value, error } = getValidationResult(req[reqProperty] || {}, schema, `request ${reqProperty}`);
+        const { mutate = true } = opt;
+        const originalProperty = req[reqProperty] || {};
+        // Joi does not mutate the input
+        const { error, value } = getValidationResult(originalProperty, schema, `request ${reqProperty}`);
         if (error) {
-            let report;
-            if (typeof opt.report === 'boolean') {
-                report = opt.report;
-            }
-            else if (typeof opt.report === 'function') {
-                report = opt.report(error);
-            }
             if (opt.redactPaths) {
-                redact(opt.redactPaths, req[reqProperty], error);
                 error.data.joiValidationErrorItems.length = 0; // clears the array
                 delete error.data.annotation;
             }
-            throw new AppError(error.message, {
-                backendResponseStatusCode: 400,
-                report,
-                ...error.data,
-            });
+            handleValidationError(error, originalProperty, opt);
         }
-        // mutate req to replace the property with the value, converted by Joi
-        if (!opt.keepOriginal && reqProperty !== 'query') {
-            // query is read-only in Express 5
+        if (mutate) {
             req[reqProperty] = value;
         }
         return value;
     }
 }
 export const validateRequest = new ValidateRequest();
-const REDACTED = 'REDACTED';
-/**
- * Mutates error
- */
-function redact(redactPaths, obj, error) {
-    redactPaths
-        .map(path => _get(obj, path))
-        .filter(Boolean)
-        .forEach(secret => {
-        error.message = error.message.replaceAll(secret, REDACTED);
-    });
-}

package/dist/validation/validateRequest.util.d.ts

@@ -0,0 +1,23 @@
+import { AppError } from '@naturalcycles/js-lib/error';
+export declare function handleValidationError<T, ERR extends AppError>(error: ERR, originalProperty: T, opt?: ReqValidationOptions<ERR>): never;
+export interface ReqValidationOptions<ERR extends AppError> {
+    /**
+     * Pass a 'dot-paths' (e.g `pw`, or `input.pw`) that needs to be redacted from the output, in case of error.
+     * Useful e.g to redact (prevent leaking) plaintext passwords in error messages.
+     */
+    redactPaths?: string[];
+    /**
+     * Set to true, or a function that returns true/false based on the error generated.
+     * If true - `genericErrorHandler` will report it to errorReporter (aka Sentry).
+     */
+    report?: boolean | ((err: ERR) => boolean);
+    /**
+     * When set to true, the validated object will not be replaced with the Joi-converted value.
+     *
+     * Defaults to true.
+     * Exception is `headers` validation, where the default is `false`.
+     *
+     * To avoid mutation - shallow copy is performed.
+     */
+    mutate?: boolean;
+}

package/dist/validation/validateRequest.util.js

@@ -0,0 +1,32 @@
+import { AppError } from '@naturalcycles/js-lib/error';
+import { _get } from '@naturalcycles/js-lib/object';
+export function handleValidationError(error, originalProperty, opt = {}) {
+    // const item: T = opt.mutate ? { ...req[reqProperty] } : (req[reqProperty] || {})
+    let report;
+    if (typeof opt.report === 'boolean') {
+        report = opt.report;
+    }
+    else if (typeof opt.report === 'function') {
+        report = opt.report(error);
+    }
+    if (opt.redactPaths) {
+        redact(opt.redactPaths, originalProperty, error);
+    }
+    throw new AppError(error.message, {
+        backendResponseStatusCode: 400,
+        report,
+        ...error.data,
+    });
+}
+const REDACTED = 'REDACTED';
+/**
+ * Mutates error
+ */
+function redact(redactPaths, obj, error) {
+    redactPaths
+        .map(path => _get(obj, path))
+        .filter(Boolean)
+        .forEach(secret => {
+        error.message = error.message.replaceAll(secret, REDACTED);
+    });
+}

package/dist/validation/zod/zodValidateRequest.d.ts

@@ -1,6 +1,6 @@
 import { type ZodType, type ZodValidationError } from '@naturalcycles/js-lib/zod';
 import type { BackendRequest } from '../../server/server.model.js';
-import type { ReqValidationOptions } from '../joi/joiValidateRequest.js';
+import { type ReqValidationOptions } from '../validateRequest.util.js';
 declare class ZodValidateRequest {
     body<T>(req: BackendRequest, schema: ZodType<T>, opt?: ReqValidationOptions<ZodValidationError>): T;
     query<T>(req: BackendRequest, schema: ZodType<T>, opt?: ReqValidationOptions<ZodValidationError>): T;

package/dist/validation/zod/zodValidateRequest.js

@@ -1,6 +1,5 @@
-import { AppError } from '@naturalcycles/js-lib/error';
-import { _get } from '@naturalcycles/js-lib/object';
 import { zSafeValidate } from '@naturalcycles/js-lib/zod';
+import { handleValidationError } from '../validateRequest.util.js';
 class ZodValidateRequest {
     body(req, schema, opt = {}) {
         return this.validate(req, 'body', schema, opt);
@@ -21,49 +20,23 @@ class ZodValidateRequest {
      * Keep in mind that this will also remove all values that are not in the schema.
      */
     headers(req, schema, opt = {}) {
-        const options = {
-            keepOriginal: true,
+        return this.validate(req, 'headers', schema, {
+            mutate: false,
             ...opt,
-        };
-        return this.validate(req, 'headers', schema, options);
+        });
     }
     validate(req, reqProperty, schema, opt = {}) {
-        const { data, error } = zSafeValidate(req[reqProperty] || {}, schema);
+        const { mutate = true } = opt;
+        const originalProperty = req[reqProperty] || {};
+        // Zod does not mutate the input
+        const { error, data } = zSafeValidate(originalProperty, schema);
         if (error) {
-            let report;
-            if (typeof opt.report === 'boolean') {
-                report = opt.report;
-            }
-            else if (typeof opt.report === 'function') {
-                report = opt.report(error);
-            }
-            if (opt.redactPaths) {
-                redact(opt.redactPaths, req[reqProperty], error);
-            }
-            throw new AppError(error.message, {
-                backendResponseStatusCode: 400,
-                report,
-                ...error.data,
-            });
+            handleValidationError(error, originalProperty, opt);
         }
-        // mutate req to replace the property with the value, converted by Joi
-        if (!opt.keepOriginal && reqProperty !== 'query') {
-            // query is read-only in Express 5
+        if (mutate) {
             req[reqProperty] = data;
         }
         return data;
     }
 }
 export const zodValidateRequest = new ZodValidateRequest();
-const REDACTED = 'REDACTED';
-/**
- * Mutates error
- */
-function redact(redactPaths, obj, error) {
-    redactPaths
-        .map(path => _get(obj, path))
-        .filter(Boolean)
-        .forEach(secret => {
-        error.message = error.message.replaceAll(secret, REDACTED);
-    });
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/backend-lib",
   "type": "module",
-  "version": "9.16.0",
+  "version": "9.17.0",
   "peerDependencies": {
     "@sentry/node": "^9"
   },
@@ -34,6 +34,7 @@
   "exports": {
     "./cfg/tsconfig.json": "./cfg/tsconfig.json",
     ".": "./dist/index.js",
+    "./admin": "./dist/admin/index.js",
     "./db": "./dist/db/index.js",
     "./deploy": "./dist/deploy/index.js",
     "./express/createDefaultApp": "./dist/express/createDefaultApp.js",
@@ -61,7 +62,6 @@
     "deploy-prepare": "dist/bin/deploy-prepare.js",
     "deploy-health-check": "dist/bin/deploy-health-check.js"
   },
-  "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public"

package/src/bin/deploy-gae.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { runScript } from '@naturalcycles/nodejs-lib'
+import { runScript } from '@naturalcycles/nodejs-lib/runScript'
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs'
 import { deployGae } from '../deploy/deployGae.js'
 import { deployHealthCheckYargsOptions } from '../deploy/deployHealthCheck.js'

package/src/bin/deploy-health-check.ts

@@ -9,7 +9,7 @@ yarn deploy-health-check --url https://service-dot-yourproject.appspot.com
 
  */
 
-import { runScript } from '@naturalcycles/nodejs-lib'
+import { runScript } from '@naturalcycles/nodejs-lib/runScript'
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs'
 import { deployHealthCheck, deployHealthCheckYargsOptions } from '../deploy/deployHealthCheck.js'
 

package/src/bin/deploy-prepare.ts

@@ -6,7 +6,7 @@ yarn deploy-prepare
 
  */
 
-import { runScript } from '@naturalcycles/nodejs-lib'
+import { runScript } from '@naturalcycles/nodejs-lib/runScript'
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs'
 import { deployPrepare, deployPrepareYargsOptions } from '../deploy/deployPrepare.js'
 

package/src/bin/undeploy-gae.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { runScript } from '@naturalcycles/nodejs-lib'
+import { runScript } from '@naturalcycles/nodejs-lib/runScript'
 import { _yargs } from '@naturalcycles/nodejs-lib/yargs'
 import { undeployGae } from '../deploy/deployGae.js'
 

package/src/deploy/backend.cfg.util.ts

@@ -1,3 +1,5 @@
+import { _lazyValue } from '@naturalcycles/js-lib'
+import type { JsonSchema } from '@naturalcycles/js-lib/json-schema'
 import type { StringMap } from '@naturalcycles/js-lib/types'
 import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv'
 import { fs2 } from '@naturalcycles/nodejs-lib/fs2'
@@ -38,12 +40,10 @@ export interface BackendCfg {
   appYamlPassEnv?: string
 }
 
-const backendCfgSchema = AjvSchema.readJsonSync<BackendCfg>(
-  `${resourcesDir}/backendCfg.schema.json`,
-  {
-    objectName: 'backend.cfg.yaml',
-  },
-)
+const getBackendCfgSchema = _lazyValue(() => {
+  const schemaJson = fs2.readJson<JsonSchema<BackendCfg>>(`${resourcesDir}/backendCfg.schema.json`)
+  return AjvSchema.create(schemaJson, { objectName: 'backend.cfg.yaml' })
+})
 
 export function getBackendCfg(projectDir = '.'): BackendCfg {
   const backendCfgYamlPath = `${projectDir}/backend.cfg.yaml`
@@ -54,6 +54,6 @@ export function getBackendCfg(projectDir = '.'): BackendCfg {
     ...yaml2.readYaml(backendCfgYamlPath),
   }
 
-  backendCfgSchema.validate(backendCfg)
+  getBackendCfgSchema().validate(backendCfg)
   return backendCfg
 }

package/src/validation/ajv/ajvValidateRequest.ts

@@ -1,8 +1,6 @@
-import { AppError } from '@naturalcycles/js-lib/error'
-import { _get } from '@naturalcycles/js-lib/object'
 import type { AjvSchema, AjvValidationError } from '@naturalcycles/nodejs-lib/ajv'
 import type { BackendRequest } from '../../server/server.model.js'
-import type { ReqValidationOptions } from '../joi/joiValidateRequest.js'
+import { handleValidationError, type ReqValidationOptions } from '../validateRequest.util.js'
 
 class AjvValidateRequest {
   body<T>(
@@ -43,11 +41,10 @@ class AjvValidateRequest {
     schema: AjvSchema<T>,
     opt: ReqValidationOptions<AjvValidationError> = {},
   ): T {
-    const options: ReqValidationOptions<AjvValidationError> = {
-      keepOriginal: true,
+    return this.validate(req, 'headers', schema, {
+      mutate: false,
       ...opt,
-    }
-    return this.validate(req, 'headers', schema, options)
+    })
   }
 
   private validate<T>(
@@ -56,53 +53,21 @@ class AjvValidateRequest {
     schema: AjvSchema<T>,
     opt: ReqValidationOptions<AjvValidationError> = {},
   ): T {
-    const value: T = { ...req[reqProperty] } // destructure to avoid being mutated by Ajv
-    // It will mutate the `value`, but not the original object
-    const error = schema.getValidationError(value, {
+    const { mutate = true } = opt
+    const originalProperty = req[reqProperty] || {}
+    const item: T = mutate ? originalProperty : { ...originalProperty }
+
+    // Ajv mutates the input
+    const error = schema.getValidationError(item, {
       objectName: `request ${reqProperty}`,
     })
 
     if (error) {
-      let report: boolean | undefined
-      if (typeof opt.report === 'boolean') {
-        report = opt.report
-      } else if (typeof opt.report === 'function') {
-        report = opt.report(error)
-      }
-
-      if (opt.redactPaths) {
-        redact(opt.redactPaths, req[reqProperty], error)
-      }
-
-      throw new AppError(error.message, {
-        backendResponseStatusCode: 400,
-        report,
-        ...error.data,
-      })
+      handleValidationError(error, originalProperty, opt)
     }
 
-    // mutate req to replace the property with the value, converted by Joi
-    if (!opt.keepOriginal && reqProperty !== 'query') {
-      // query is read-only in Express 5
-      req[reqProperty] = value
-    }
-
-    return value
+    return item
   }
 }
 
 export const ajvValidateRequest = new AjvValidateRequest()
-
-const REDACTED = 'REDACTED'
-
-/**
- * Mutates error
- */
-function redact(redactPaths: string[], obj: any, error: Error): void {
-  redactPaths
-    .map(path => _get(obj, path) as string)
-    .filter(Boolean)
-    .forEach(secret => {
-      error.message = error.message.replaceAll(secret, REDACTED)
-    })
-}

package/src/validation/joi/joiValidateRequest.ts

@@ -1,29 +1,7 @@
-import { AppError } from '@naturalcycles/js-lib/error'
-import { _get } from '@naturalcycles/js-lib/object'
 import type { AnySchema, JoiValidationError } from '@naturalcycles/nodejs-lib/joi'
 import { getValidationResult } from '@naturalcycles/nodejs-lib/joi'
 import type { BackendRequest } from '../../server/server.model.js'
-
-export interface ReqValidationOptions<ERR extends Error> {
-  /**
-   * Pass a 'dot-paths' (e.g `pw`, or `input.pw`) that needs to be redacted from the output, in case of error.
-   * Useful e.g to redact (prevent leaking) plaintext passwords in error messages.
-   */
-  redactPaths?: string[]
-
-  /**
-   * Set to true, or a function that returns true/false based on the error generated.
-   * If true - `genericErrorHandler` will report it to errorReporter (aka Sentry).
-   */
-  report?: boolean | ((err: ERR) => boolean)
-
-  /**
-   * When set to true, the validated object will not be replaced with the Joi-converted value.
-   *
-   * The general default is `false`, with the excepction of `headers` validation, where the default is `true`.
-   */
-  keepOriginal?: boolean
-}
+import { handleValidationError, type ReqValidationOptions } from '../validateRequest.util.js'
 
 class ValidateRequest {
   body<T>(
@@ -64,11 +42,10 @@ class ValidateRequest {
     schema: AnySchema<T>,
     opt: ReqValidationOptions<JoiValidationError> = {},
   ): T {
-    const options: ReqValidationOptions<JoiValidationError> = {
-      keepOriginal: true,
+    return this.validate(req, 'headers', schema, {
+      mutate: false,
       ...opt,
-    }
-    return this.validate(req, 'headers', schema, options)
+    })
   }
 
   private validate<T>(
@@ -77,35 +54,22 @@ class ValidateRequest {
     schema: AnySchema<T>,
     opt: ReqValidationOptions<JoiValidationError> = {},
   ): T {
-    const { value, error } = getValidationResult(
-      req[reqProperty] || {},
-      schema,
-      `request ${reqProperty}`,
-    )
-    if (error) {
-      let report: boolean | undefined
-      if (typeof opt.report === 'boolean') {
-        report = opt.report
-      } else if (typeof opt.report === 'function') {
-        report = opt.report(error)
-      }
+    const { mutate = true } = opt
+    const originalProperty = req[reqProperty] || {}
+
+    // Joi does not mutate the input
+    const { error, value } = getValidationResult(originalProperty, schema, `request ${reqProperty}`)
 
+    if (error) {
       if (opt.redactPaths) {
-        redact(opt.redactPaths, req[reqProperty], error)
         error.data.joiValidationErrorItems.length = 0 // clears the array
         delete error.data.annotation
       }
 
-      throw new AppError(error.message, {
-        backendResponseStatusCode: 400,
-        report,
-        ...error.data,
-      })
+      handleValidationError(error, originalProperty, opt)
     }
 
-    // mutate req to replace the property with the value, converted by Joi
-    if (!opt.keepOriginal && reqProperty !== 'query') {
-      // query is read-only in Express 5
+    if (mutate) {
       req[reqProperty] = value
     }
 
@@ -114,17 +78,3 @@ class ValidateRequest {
 }
 
 export const validateRequest = new ValidateRequest()
-
-const REDACTED = 'REDACTED'
-
-/**
- * Mutates error
- */
-function redact(redactPaths: string[], obj: any, error: Error): void {
-  redactPaths
-    .map(path => _get(obj, path) as string)
-    .filter(Boolean)
-    .forEach(secret => {
-      error.message = error.message.replaceAll(secret, REDACTED)
-    })
-}

package/src/validation/validateRequest.util.ts

@@ -0,0 +1,65 @@
+import { AppError } from '@naturalcycles/js-lib/error'
+import { _get } from '@naturalcycles/js-lib/object'
+
+export function handleValidationError<T, ERR extends AppError>(
+  error: ERR,
+  originalProperty: T,
+  opt: ReqValidationOptions<ERR> = {},
+): never {
+  // const item: T = opt.mutate ? { ...req[reqProperty] } : (req[reqProperty] || {})
+
+  let report: boolean | undefined
+  if (typeof opt.report === 'boolean') {
+    report = opt.report
+  } else if (typeof opt.report === 'function') {
+    report = opt.report(error)
+  }
+
+  if (opt.redactPaths) {
+    redact(opt.redactPaths, originalProperty, error)
+  }
+
+  throw new AppError(error.message, {
+    backendResponseStatusCode: 400,
+    report,
+    ...error.data,
+  })
+}
+
+const REDACTED = 'REDACTED'
+
+/**
+ * Mutates error
+ */
+function redact(redactPaths: string[], obj: any, error: Error): void {
+  redactPaths
+    .map(path => _get(obj, path) as string)
+    .filter(Boolean)
+    .forEach(secret => {
+      error.message = error.message.replaceAll(secret, REDACTED)
+    })
+}
+
+export interface ReqValidationOptions<ERR extends AppError> {
+  /**
+   * Pass a 'dot-paths' (e.g `pw`, or `input.pw`) that needs to be redacted from the output, in case of error.
+   * Useful e.g to redact (prevent leaking) plaintext passwords in error messages.
+   */
+  redactPaths?: string[]
+
+  /**
+   * Set to true, or a function that returns true/false based on the error generated.
+   * If true - `genericErrorHandler` will report it to errorReporter (aka Sentry).
+   */
+  report?: boolean | ((err: ERR) => boolean)
+
+  /**
+   * When set to true, the validated object will not be replaced with the Joi-converted value.
+   *
+   * Defaults to true.
+   * Exception is `headers` validation, where the default is `false`.
+   *
+   * To avoid mutation - shallow copy is performed.
+   */
+  mutate?: boolean
+}

package/src/validation/zod/zodValidateRequest.ts

@@ -1,8 +1,6 @@
-import { AppError } from '@naturalcycles/js-lib/error'
-import { _get } from '@naturalcycles/js-lib/object'
 import { type ZodType, type ZodValidationError, zSafeValidate } from '@naturalcycles/js-lib/zod'
 import type { BackendRequest } from '../../server/server.model.js'
-import type { ReqValidationOptions } from '../joi/joiValidateRequest.js'
+import { handleValidationError, type ReqValidationOptions } from '../validateRequest.util.js'
 
 class ZodValidateRequest {
   body<T>(
@@ -43,11 +41,10 @@ class ZodValidateRequest {
     schema: ZodType<T>,
     opt: ReqValidationOptions<ZodValidationError> = {},
   ): T {
-    const options: ReqValidationOptions<ZodValidationError> = {
-      keepOriginal: true,
+    return this.validate(req, 'headers', schema, {
+      mutate: false,
       ...opt,
-    }
-    return this.validate(req, 'headers', schema, options)
+    })
   }
 
   private validate<T>(
@@ -56,34 +53,21 @@ class ZodValidateRequest {
     schema: ZodType<T>,
     opt: ReqValidationOptions<ZodValidationError> = {},
   ): T {
-    const { data, error } = zSafeValidate(
-      req[reqProperty] || {},
+    const { mutate = true } = opt
+    const originalProperty = req[reqProperty] || {}
+
+    // Zod does not mutate the input
+    const { error, data } = zSafeValidate(
+      originalProperty,
       schema,
-      // `request ${reqProperty}`,
+      // opt2?.itemName,
     )
 
     if (error) {
-      let report: boolean | undefined
-      if (typeof opt.report === 'boolean') {
-        report = opt.report
-      } else if (typeof opt.report === 'function') {
-        report = opt.report(error)
-      }
-
-      if (opt.redactPaths) {
-        redact(opt.redactPaths, req[reqProperty], error)
-      }
-
-      throw new AppError(error.message, {
-        backendResponseStatusCode: 400,
-        report,
-        ...error.data,
-      })
+      handleValidationError(error, originalProperty, opt)
     }
 
-    // mutate req to replace the property with the value, converted by Joi
-    if (!opt.keepOriginal && reqProperty !== 'query') {
-      // query is read-only in Express 5
+    if (mutate) {
       req[reqProperty] = data
     }
 
@@ -92,17 +76,3 @@ class ZodValidateRequest {
 }
 
 export const zodValidateRequest = new ZodValidateRequest()
-
-const REDACTED = 'REDACTED'
-
-/**
- * Mutates error
- */
-function redact(redactPaths: string[], obj: any, error: Error): void {
-  redactPaths
-    .map(path => _get(obj, path) as string)
-    .filter(Boolean)
-    .forEach(secret => {
-      error.message = error.message.replaceAll(secret, REDACTED)
-    })
-}