@naturalcycles/nodejs-lib 15.43.2 → 15.44.0

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

@@ -1,5 +1,5 @@
 import type { Set2 } from '@naturalcycles/js-lib/object';
-import { type AnyObject, type IsoDate, type IsoDateTime, type NumberEnum, type StringEnum, type StringMap, type UnixTimestamp, type UnixTimestampMillis } from '@naturalcycles/js-lib/types';
+import { type AnyObject, type IANATimezone, type IsoDate, type IsoDateTime, type NumberEnum, type StringEnum, type StringMap, type UnixTimestamp, type UnixTimestampMillis } from '@naturalcycles/js-lib/types';
 export declare const j: {
     string(): JsonSchemaStringBuilder<string, string, false>;
     number(): JsonSchemaNumberBuilder<number, number, false>;
@@ -12,7 +12,7 @@ export declare const j: {
     array<IN, OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>): JsonSchemaArrayBuilder<IN, OUT, Opt>;
     set<IN, OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>): JsonSchemaSet2Builder<IN, OUT, Opt>;
     buffer(): JsonSchemaBufferBuilder;
-    enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(input: T): JsonSchemaEnumBuilder<T extends readonly (infer U)[] ? U : T extends StringEnum ? T[keyof T] : T extends NumberEnum ? T[keyof T] : never>;
+    enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(input: T, opt?: JsonBuilderRuleOpt): JsonSchemaEnumBuilder<T extends readonly (infer U)[] ? U : T extends StringEnum ? T[keyof T] : T extends NumberEnum ? T[keyof T] : never>;
     oneOf<B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[], IN = BuilderInUnion<B>, OUT = BuilderOutUnion<B>>(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false>;
 };
 export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -91,6 +91,13 @@ export declare class JsonSchemaStringBuilder<IN extends string = string, OUT = I
     languageTag(): this;
     countryCode(): this;
     currency(): this;
+    /**
+     * 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>;
 }
 export interface JsonSchemaStringEmailOptions {
     checkTLD: boolean;
@@ -177,7 +184,8 @@ export declare class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder<string
     constructor();
 }
 export declare class JsonSchemaEnumBuilder<IN extends string | number | boolean | null, OUT extends IN = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
-    constructor(enumValues: readonly IN[]);
+    constructor(enumValues: readonly IN[], opt?: JsonBuilderRuleOpt);
+    branded<B extends IN>(): JsonSchemaEnumBuilder<B | IN, B, Opt>;
 }
 export interface JsonSchema<IN = unknown, OUT = IN> {
     readonly in?: IN;

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -32,7 +32,7 @@ export const j = {
     buffer() {
         return new JsonSchemaBufferBuilder();
     },
-    enum(input) {
+    enum(input, opt) {
         let enumValues;
         if (Array.isArray(input)) {
             enumValues = input;
@@ -47,7 +47,7 @@ export const j = {
             }
         }
         _assert(enumValues, 'Unsupported enum input');
-        return new JsonSchemaEnumBuilder(enumValues);
+        return new JsonSchemaEnumBuilder(enumValues, opt);
     },
     oneOf(items) {
         const schemas = items.map(b => b.build());
@@ -275,6 +275,18 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
         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() {
+        // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
+        return j
+            .enum([...Intl.supportedValuesOf('timeZone'), 'UTC'], { msg: 'is an invalid IANA timezone' })
+            .branded();
+    }
 }
 export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -520,8 +532,13 @@ export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder {
     }
 }
 export class JsonSchemaEnumBuilder extends JsonSchemaAnyBuilder {
-    constructor(enumValues) {
+    constructor(enumValues, opt) {
         super({ enum: enumValues });
+        if (opt?.msg)
+            this.setErrorMessage('enum', opt.msg);
+    }
+    branded() {
+        return this;
     }
 }
 function object(props) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.43.2",
+  "version": "15.44.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -13,6 +13,7 @@ import type { Set2 } from '@naturalcycles/js-lib/object'
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
 import {
   type AnyObject,
+  type IANATimezone,
   type IsoDate,
   type IsoDateTime,
   JWT_REGEX,
@@ -63,6 +64,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 +88,7 @@ export const j = {
     }
 
     _assert(enumValues, 'Unsupported enum input')
-    return new JsonSchemaEnumBuilder(enumValues as any)
+    return new JsonSchemaEnumBuilder(enumValues as any, opt)
   },
 
   oneOf<
@@ -369,6 +371,19 @@ 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([...Intl.supportedValuesOf('timeZone'), 'UTC'], { msg: 'is an invalid IANA timezone' })
+      .branded<IANATimezone>()
+  }
 }
 
 export interface JsonSchemaStringEmailOptions {
@@ -750,8 +765,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?.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>
   }
 }