@naturalcycles/nodejs-lib 15.43.2 → 15.45.0

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -13,6 +13,8 @@ import type { Set2 } from '@naturalcycles/js-lib/object'
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
 import {
   type AnyObject,
+  type IANATimezone,
+  type Inclusiveness,
   type IsoDate,
   type IsoDateTime,
   JWT_REGEX,
@@ -22,6 +24,7 @@ import {
   type UnixTimestamp,
   type UnixTimestampMillis,
 } from '@naturalcycles/js-lib/types'
+import { TIMEZONES } from '../timezones.js'
 import { JSON_SCHEMA_ORDER, mergeJsonSchemaObjects } from './jsonSchemaBuilder.util.js'
 
 export const j = {
@@ -63,6 +66,7 @@ export const j = {
 
   enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(
     input: T,
+    opt?: JsonBuilderRuleOpt,
   ): JsonSchemaEnumBuilder<
     T extends readonly (infer U)[]
       ? U
@@ -86,7 +90,7 @@ export const j = {
     }
 
     _assert(enumValues, 'Unsupported enum input')
-    return new JsonSchemaEnumBuilder(enumValues as any)
+    return new JsonSchemaEnumBuilder(enumValues as any, opt)
   },
 
   oneOf<
@@ -246,6 +250,7 @@ export class JsonSchemaStringBuilder<
   }
 
   pattern(pattern: string, opt?: JsonBuilderRuleOpt): this {
+    if (opt?.name) this.setErrorMessage('pattern', `is not a valid ${opt.name}`)
     if (opt?.msg) this.setErrorMessage('pattern', opt.msg)
     Object.assign(this.schema, { pattern })
     return this
@@ -369,6 +374,17 @@ export class JsonSchemaStringBuilder<
     const regex = /^[A-Z]{3}$/
     return this.regex(regex, { msg: 'is not a valid currency format' })
   }
+
+  /**
+   * Validates that the input is a valid IANATimzone value.
+   *
+   * All previous expectations in the schema chain are dropped - including `.optional()` -
+   * because this call effectively starts a new schema chain as an `enum` validation.
+   */
+  ianaTimezone(): JsonSchemaEnumBuilder<string | IANATimezone, IANATimezone, false> {
+    // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
+    return j.enum(TIMEZONES, { msg: 'is an invalid IANA timezone' }).branded<IANATimezone>()
+  }
 }
 
 export interface JsonSchemaStringEmailOptions {
@@ -420,12 +436,27 @@ export class JsonSchemaNumberBuilder<
     return this
   }
 
-  /**
-   * Both ranges are inclusive.
-   */
-  range(minimum: number, maximum: number): this {
-    Object.assign(this.schema, { minimum, maximum })
-    return this
+  lessThan(value: number): this {
+    return this.exclusiveMax(value)
+  }
+
+  lessThanOrEqual(value: number): this {
+    return this.max(value)
+  }
+
+  moreThan(value: number): this {
+    return this.exclusiveMin(value)
+  }
+
+  moreThanOrEqual(value: number): this {
+    return this.min(value)
+  }
+
+  range(minimum: number, maximum: number, incl: Inclusiveness): this {
+    if (incl === '[)') {
+      return this.moreThanOrEqual(minimum).lessThan(maximum)
+    }
+    return this.moreThanOrEqual(minimum).lessThanOrEqual(maximum)
   }
 
   int32(): this {
@@ -750,8 +781,14 @@ export class JsonSchemaEnumBuilder<
   OUT extends IN = IN,
   Opt extends boolean = false,
 > extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
-  constructor(enumValues: readonly IN[]) {
+  constructor(enumValues: readonly IN[], opt?: JsonBuilderRuleOpt) {
     super({ enum: enumValues })
+    if (opt?.name) this.setErrorMessage('pattern', `is not a valid ${opt.name}`)
+    if (opt?.msg) this.setErrorMessage('enum', opt.msg)
+  }
+
+  branded<B extends IN>(): JsonSchemaEnumBuilder<B | IN, B, Opt> {
+    return this as unknown as JsonSchemaEnumBuilder<B | IN, B, Opt>
   }
 }
 
@@ -879,5 +916,16 @@ type BuilderInUnion<B extends readonly JsonSchemaAnyBuilder<any, any, any>[]> =
 }[number]
 
 interface JsonBuilderRuleOpt {
+  /**
+   * Text of error message to return when the validation fails for the given rule:
+   *
+   * `{ msg: "is not a valid Oompa-loompa" } => "Object.property is not a valid Oompa-loompa"`
+   */
   msg?: string
+  /**
+   * A friendly name for what we are validating, that will be used in error messages:
+   *
+   * `{ name: "Oompa-loompa" } => "Object.property is not a valid Oompa-loompa"`
+   */
+  name?: string
 }