@naturalcycles/nodejs-lib 15.37.2 → 15.39.0

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

@@ -1,7 +1,7 @@
 import { type ValidationFunction, type ValidationFunctionResult } from '@naturalcycles/js-lib';
 import type { AnySchema, ValidationOptions } from 'joi';
 import { JoiValidationError } from './joi.validation.error.js';
-export declare function getJoiValidationFunction<T>(schema: AnySchema<T>): ValidationFunction<T, JoiValidationError>;
+export declare function getJoiValidationFunction<T>(schema: AnySchema<T>): ValidationFunction<T, T, JoiValidationError>;
 /**
  * Validates with Joi.
  * Throws JoiValidationError if invalid.

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.37.2",
+  "version": "15.39.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",
     "@types/jsonwebtoken": "^9",
     "@types/yargs": "^16",
     "ajv": "^8",
-    "ajv-formats": "^3",
-    "ajv-keywords": "^5",
     "chalk": "^5",
     "dotenv": "^17",
     "joi": "^18",

package/src/log/log.util.ts

@@ -2,7 +2,7 @@ import { commonLoggerCreate } from '@naturalcycles/js-lib/log'
 import { _inspect } from '../string/inspect.js'
 
 /**
- * CommonLogger that logs to process.stdout directly (bypassing console.log).
+ * CommonLogger that logs to process.stdout directly (bypassing console.log)!
  */
 export const stdoutLogger = commonLoggerCreate((_level, args) => {
   process.stdout.write(args.map(a => _inspect(a)).join(' ') + '\n')

package/src/security/nanoid.ts

@@ -5,7 +5,7 @@ https://github.com/ai/nanoid/
 
  */
 
-/* eslint-disable */
+// oxlint-disable no-bitwise -- NanoID implementation relies on bitwise operations
 
 import { randomFillSync } from 'node:crypto'
 

package/src/validation/ajv/ajvSchema.ts

@@ -4,72 +4,25 @@ import {
   type ValidationFunction,
   type ValidationFunctionResult,
 } from '@naturalcycles/js-lib'
-import type { JsonSchema, JsonSchemaBuilder } from '@naturalcycles/js-lib/json-schema'
-import { JsonSchemaAnyBuilder } from '@naturalcycles/js-lib/json-schema'
+import { _assert } from '@naturalcycles/js-lib/error'
 import { _deepCopy, _filterNullishValues } from '@naturalcycles/js-lib/object'
 import { _substringBefore } from '@naturalcycles/js-lib/string'
-import type { AnyObject } from '@naturalcycles/js-lib/types'
-import { z, ZodType } from '@naturalcycles/js-lib/zod'
-import type { Ajv } from 'ajv'
+import { _typeCast, type AnyObject } from '@naturalcycles/js-lib/types'
+import type { ZodType } from '@naturalcycles/js-lib/zod'
+import { z } from '@naturalcycles/js-lib/zod'
+import type { Ajv, ErrorObject } from 'ajv'
 import { _inspect } from '../../string/inspect.js'
 import { AjvValidationError } from './ajvValidationError.js'
 import { getAjv } from './getAjv.js'
-
-export type SchemaHandledByAjv<T> = JsonSchemaBuilder<T> | JsonSchema<T> | AjvSchema<T> | ZodType<T>
-
-export interface AjvValidationOptions {
-  /**
-   * Defaults to true,
-   * because that's how AJV works by default,
-   * and what gives it performance advantage.
-   * (Because we have found that deep-clone is surprisingly slow,
-   * nearly as slow as Joi validation).
-   *
-   * If set to true - AJV will mutate the input in case it needs to apply transformations
-   * (strip unknown properties, convert types, etc).
-   *
-   * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
-   * Will return the cloned/mutated object.
-   * Please note that JSON.stringify+parse has side-effects,
-   * e.g it will transform Buffer into a weird object.
-   */
-  mutateInput?: boolean
-  inputName?: string
-  inputId?: string
-}
-
-export interface AjvSchemaCfg {
-  /**
-   * Pass Ajv instance, otherwise Ajv will be created with
-   * AjvSchema default (not the same as Ajv defaults) parameters
-   */
-  ajv: Ajv
-
-  inputName?: string
-
-  /**
-   * Option of Ajv.
-   * If set to true - will mutate your input objects!
-   * Defaults to false.
-   *
-   * This option is a "shortcut" to skip creating and passing Ajv instance.
-   */
-  // coerceTypes?: boolean
-
-  /**
-   * If true - schema will be compiled on-demand (lazily).
-   * Default: false.
-   */
-  lazy?: boolean
-}
+import { type JsonSchema, JsonSchemaAnyBuilder } from './jsonSchemaBuilder.js'
 
 /**
  * On creation - compiles ajv validation function.
  * Provides convenient methods, error reporting, etc.
  */
-export class AjvSchema<T = unknown> {
+export class AjvSchema<IN = unknown, OUT = IN> {
   private constructor(
-    public schema: JsonSchema<T>,
+    public schema: JsonSchema<IN, OUT>,
     cfg: Partial<AjvSchemaCfg> = {},
   ) {
     this.cfg = {
@@ -88,10 +41,10 @@ export class AjvSchema<T = unknown> {
   /**
    * Shortcut for AjvSchema.create(schema, { lazy: true })
    */
-  static createLazy<T>(
-    schema: JsonSchemaBuilder<T> | JsonSchema<T> | AjvSchema<T>,
+  static createLazy<IN, OUT>(
+    schema: SchemaHandledByAjv<IN, OUT>,
     cfg?: Partial<AjvSchemaCfg>,
-  ): AjvSchema<T> {
+  ): AjvSchema<IN, OUT> {
     return AjvSchema.create(schema, {
       lazy: true,
       ...cfg,
@@ -107,46 +60,50 @@ export class AjvSchema<T = unknown> {
    * Implementation note: JsonSchemaBuilder goes first in the union type, otherwise TypeScript fails to infer <T> type
    * correctly for some reason.
    */
-  static create<T>(schema: SchemaHandledByAjv<T>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<T> {
+  static create<IN, OUT = IN>(
+    schema: SchemaHandledByAjv<IN, OUT>,
+    cfg?: Partial<AjvSchemaCfg>,
+  ): AjvSchema<IN, OUT> {
     if (schema instanceof AjvSchema) return schema
 
-    if (AjvSchema.isSchemaWithCachedAjvSchema<typeof schema, T>(schema)) {
-      return AjvSchema.requireCachedAjvSchema<typeof schema, T>(schema)
+    if (AjvSchema.isSchemaWithCachedAjvSchema<typeof schema, IN, OUT>(schema)) {
+      return AjvSchema.requireCachedAjvSchema<typeof schema, IN, OUT>(schema)
     }
 
-    let jsonSchema: JsonSchema<T>
+    let jsonSchema: JsonSchema<IN, OUT>
 
     if (AjvSchema.isJsonSchemaBuilder(schema)) {
-      jsonSchema = schema.build()
-    } else if (AjvSchema.isZodSchema(schema)) {
-      jsonSchema = z.toJSONSchema(schema, { target: 'draft-7' }) as JsonSchema<T>
+      jsonSchema = (schema as JsonSchemaAnyBuilder<IN, OUT, any>).build()
+      AjvSchema.requireValidJsonSchema(jsonSchema)
     } else {
-      jsonSchema = schema
+      jsonSchema = schema as JsonSchema<IN, OUT>
     }
 
-    const ajvSchema = new AjvSchema<T>(jsonSchema, cfg)
+    const ajvSchema = new AjvSchema<IN, OUT>(jsonSchema, cfg)
     AjvSchema.cacheAjvSchema(schema, ajvSchema)
 
     return ajvSchema
   }
 
   /**
-   * @deprecated
-   *
-   * Use `AjvSchema.create`
+   * @deprecated Use `j` to build schemas, not `z` or `zod`.
    */
-  static createFromZod<T>(zodSchema: ZodType<T>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<T> {
-    return AjvSchema.create(zodSchema, cfg)
+  static createFromZod<T extends ZodType<any, any, any>>(
+    schema: T,
+  ): AjvSchema<T['_input'], T['_output']> {
+    const jsonSchema = z.toJSONSchema(schema, {
+      target: 'draft-7',
+    }) as unknown as JsonSchema<T['_input'], T['_output']>
+
+    return AjvSchema.create(jsonSchema)
   }
 
-  static isJsonSchemaBuilder<T>(schema: unknown): schema is JsonSchemaBuilder<T> {
+  static isJsonSchemaBuilder<IN, OUT>(
+    schema: unknown,
+  ): schema is JsonSchemaAnyBuilder<IN, OUT, any> {
     return schema instanceof JsonSchemaAnyBuilder
   }
 
-  static isZodSchema<T>(schema: unknown): schema is ZodType<T> {
-    return schema instanceof ZodType
-  }
-
   readonly cfg: AjvSchemaCfg
 
   /**
@@ -157,13 +114,13 @@ export class AjvSchema<T = unknown> {
    *
    * Returned object is always the same object (`===`) that was passed, so it is returned just for convenience.
    */
-  validate(input: T, opt: AjvValidationOptions = {}): T {
+  validate(input: IN, opt: AjvValidationOptions = {}): OUT {
     const [err, output] = this.getValidationResult(input, opt)
     if (err) throw err
     return output
   }
 
-  isValid(input: T, opt?: AjvValidationOptions): boolean {
+  isValid(input: IN, opt?: AjvValidationOptions): boolean {
     // todo: we can make it both fast and non-mutating by using Ajv
     // with "removeAdditional" and "useDefaults" disabled.
     const [err] = this.getValidationResult(input, opt)
@@ -171,9 +128,9 @@ export class AjvSchema<T = unknown> {
   }
 
   getValidationResult(
-    input: T,
+    input: IN,
     opt: AjvValidationOptions = {},
-  ): ValidationFunctionResult<T, AjvValidationError> {
+  ): ValidationFunctionResult<OUT, AjvValidationError> {
     const fn = this.getAJVValidateFunction()
 
     const item =
@@ -182,16 +139,19 @@ export class AjvSchema<T = unknown> {
         : _deepCopy(input) // not mutate
 
     const valid = fn(item) // mutates item
+    _typeCast<OUT>(item)
     if (valid) return [null, item]
 
     const errors = fn.errors!
 
     const {
-      inputId = _isObject(input) ? (input['id' as keyof T] as any) : undefined,
+      inputId = _isObject(input) ? input['id' as keyof IN] : undefined,
       inputName = this.cfg.inputName || 'Object',
     } = opt
     const dataVar = [inputName, inputId].filter(Boolean).join('.')
 
+    this.applyImprovementsOnErrorMessages(errors)
+
     let message = this.cfg.ajv.errorsText(errors, {
       dataVar,
       separator,
@@ -213,7 +173,7 @@ export class AjvSchema<T = unknown> {
     return [err, item]
   }
 
-  getValidationFunction(): ValidationFunction<T, AjvValidationError> {
+  getValidationFunction(): ValidationFunction<IN, OUT, AjvValidationError> {
     return (input, opt) => {
       return this.getValidationResult(input, {
         mutateInput: opt?.mutateInput,
@@ -223,30 +183,109 @@ export class AjvSchema<T = unknown> {
     }
   }
 
-  static isSchemaWithCachedAjvSchema<Base, T>(
+  static isSchemaWithCachedAjvSchema<Base, IN, OUT>(
     schema: Base,
-  ): schema is WithCachedAjvSchema<Base, T> {
+  ): schema is WithCachedAjvSchema<Base, IN, OUT> {
     return !!(schema as any)?.[HIDDEN_AJV_SCHEMA]
   }
 
-  static cacheAjvSchema<Base extends AnyObject, T>(
+  static cacheAjvSchema<Base extends AnyObject, IN, OUT>(
     schema: Base,
-    ajvSchema: AjvSchema<T>,
-  ): WithCachedAjvSchema<Base, T> {
+    ajvSchema: AjvSchema<IN, OUT>,
+  ): WithCachedAjvSchema<Base, IN, OUT> {
     return Object.assign(schema, { [HIDDEN_AJV_SCHEMA]: ajvSchema })
   }
 
-  static requireCachedAjvSchema<Base, T>(schema: WithCachedAjvSchema<Base, T>): AjvSchema<T> {
+  static requireCachedAjvSchema<Base, IN, OUT>(
+    schema: WithCachedAjvSchema<Base, IN, OUT>,
+  ): AjvSchema<IN, OUT> {
     return schema[HIDDEN_AJV_SCHEMA]
   }
 
-  private getAJVValidateFunction = _lazyValue(() => this.cfg.ajv.compile<T>(this.schema))
+  private getAJVValidateFunction = _lazyValue(() => this.cfg.ajv.compile(this.schema as any))
+
+  private static requireValidJsonSchema(schema: JsonSchema): void {
+    // For object schemas we require that it is type checked against an external type, e.g.:
+    // interface Foo { name: string }
+    // const schema = j.object({ name: j.string() }).ofType<Foo>()
+    _assert(
+      schema.type !== 'object' || schema.hasIsOfTypeCheck,
+      'The schema must be type checked against a type or interface, using the `.isOfType()` helper in `j`.',
+    )
+  }
+
+  private applyImprovementsOnErrorMessages(
+    errors: ErrorObject<string, Record<string, any>, unknown>[] | null | undefined,
+  ): void {
+    if (!errors) return
+
+    const { errorMessages } = this.schema
+
+    for (const error of errors) {
+      if (errorMessages?.[error.keyword]) {
+        error.message = errorMessages[error.keyword]
+      }
+
+      error.instancePath = error.instancePath.replaceAll(/\/(\d+)/g, `[$1]`).replaceAll('/', '.')
+    }
+  }
 }
 
 const separator = '\n'
 
 export const HIDDEN_AJV_SCHEMA = Symbol('HIDDEN_AJV_SCHEMA')
 
-export type WithCachedAjvSchema<Base, T> = Base & {
-  [HIDDEN_AJV_SCHEMA]: AjvSchema<T>
+export type WithCachedAjvSchema<Base, IN, OUT> = Base & {
+  [HIDDEN_AJV_SCHEMA]: AjvSchema<IN, OUT>
+}
+
+export interface AjvValidationOptions {
+  /**
+   * Defaults to true,
+   * because that's how AJV works by default,
+   * and what gives it performance advantage.
+   * (Because we have found that deep-clone is surprisingly slow,
+   * nearly as slow as Joi validation).
+   *
+   * If set to true - AJV will mutate the input in case it needs to apply transformations
+   * (strip unknown properties, convert types, etc).
+   *
+   * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
+   * Will return the cloned/mutated object.
+   * Please note that JSON.stringify+parse has side-effects,
+   * e.g it will transform Buffer into a weird object.
+   */
+  mutateInput?: boolean
+  inputName?: string
+  inputId?: string
+}
+
+export interface AjvSchemaCfg {
+  /**
+   * Pass Ajv instance, otherwise Ajv will be created with
+   * AjvSchema default (not the same as Ajv defaults) parameters
+   */
+  ajv: Ajv
+
+  inputName?: string
+
+  /**
+   * Option of Ajv.
+   * If set to true - will mutate your input objects!
+   * Defaults to false.
+   *
+   * This option is a "shortcut" to skip creating and passing Ajv instance.
+   */
+  // coerceTypes?: boolean
+
+  /**
+   * If true - schema will be compiled on-demand (lazily).
+   * Default: false.
+   */
+  lazy?: boolean
 }
+
+export type SchemaHandledByAjv<IN, OUT = IN> =
+  | JsonSchemaAnyBuilder<IN, OUT, any>
+  | JsonSchema<IN, OUT>
+  | AjvSchema<IN, OUT>