@naturalcycles/nodejs-lib 15.53.0 → 15.55.0

package/dist/validation/ajv/ajvSchema.js

@@ -59,6 +59,12 @@ export class AjvSchema {
         else {
             jsonSchema = schema;
         }
+        // This is our own helper which marks a schema as optional
+        // in case it is going to be used in an object schema,
+        // where we need to mark the given property as not-required.
+        // But once all compilation is done, the presence of this field
+        // really upsets Ajv.
+        delete jsonSchema.optionalField;
         const ajvSchema = new AjvSchema(jsonSchema, cfg);
         AjvSchema.cacheAjvSchema(schema, ajvSchema);
         return ajvSchema;

package/dist/validation/ajv/getAjv.js

@@ -91,7 +91,7 @@ export function createAjv(opt) {
     });
     ajv.addKeyword({
         keyword: 'instanceof',
-        modifying: true,
+        modifying: false,
         schemaType: 'string',
         validate(instanceOf, data, _schema, _ctx) {
             if (typeof data !== 'object')
@@ -354,6 +354,23 @@ export function createAjv(opt) {
         keyword: 'hasIsOfTypeCheck',
         schemaType: 'boolean',
     });
+    ajv.addKeyword({
+        keyword: 'optionalValues',
+        type: ['string', 'number', 'boolean'],
+        modifying: true,
+        errors: false,
+        schemaType: 'array',
+        validate: function validate(optionalValues, data, _schema, ctx) {
+            if (!optionalValues)
+                return true;
+            if (!optionalValues.includes(data))
+                return true;
+            if (ctx?.parentData && ctx.parentDataProperty) {
+                ctx.parentData[ctx.parentDataProperty] = undefined;
+            }
+            return true;
+        },
+    });
     return ajv;
 }
 const monthLengths = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

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

@@ -8,6 +8,7 @@ export declare const j: {
         dbEntity: typeof objectDbEntity;
         infer: typeof objectInfer;
         any(): JsonSchemaObjectBuilder<AnyObject, AnyObject, false>;
+        stringMap<S extends JsonSchemaTerminal<any, any, any>>(schema: S): JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>>;
         /**
          * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
          */
@@ -18,6 +19,9 @@ export declare const j: {
     buffer(): JsonSchemaBufferBuilder;
     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>;
+    and(): {
+        silentBob: () => never;
+    };
 };
 export declare class JsonSchemaTerminal<IN, OUT, Opt> {
     protected schema: JsonSchema;
@@ -72,8 +76,15 @@ export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTermin
      */
     final(): JsonSchemaTerminal<IN, OUT, Opt>;
 }
-export declare class JsonSchemaStringBuilder<IN extends string = string, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+export declare class JsonSchemaStringBuilder<IN extends string | undefined = string, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValues?: string[]): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>;
     regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this;
     pattern(pattern: string, opt?: JsonBuilderRuleOpt): this;
     minLength(minLength: number): this;
@@ -133,8 +144,15 @@ export interface JsonSchemaIsoDateOptions {
     after?: string;
     sameOrAfter?: string;
 }
-export declare class JsonSchemaNumberBuilder<IN extends number = number, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+export declare class JsonSchemaNumberBuilder<IN extends number | undefined = number, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValues?: number[]): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>;
     integer(): this;
     branded<B extends number>(): JsonSchemaNumberBuilder<B, B, Opt>;
     multipleOf(multipleOf: number): this;
@@ -159,8 +177,15 @@ export declare class JsonSchemaNumberBuilder<IN extends number = number, OUT = I
     utcOffset(): this;
     utcOffsetHour(): this;
 }
-export declare class JsonSchemaBooleanBuilder<IN extends boolean = boolean, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+export declare class JsonSchemaBooleanBuilder<IN extends boolean | undefined = boolean, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();
+    /**
+     * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValue?: boolean): JsonSchemaBooleanBuilder<IN | undefined, OUT | undefined, true>;
 }
 export declare class JsonSchemaObjectBuilder<IN extends AnyObject, OUT extends AnyObject, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor(props?: AnyObject, opt?: JsonSchemaObjectBuilderOpts);
@@ -179,6 +204,7 @@ export declare class JsonSchemaObjectBuilder<IN extends AnyObject, OUT extends A
 }
 interface JsonSchemaObjectBuilderOpts {
     hasIsOfTypeCheck?: false;
+    patternProperties?: StringMap<JsonSchema<any, any>>;
 }
 export declare class JsonSchemaObjectInferringBuilder<PROPS extends Record<string, JsonSchemaAnyBuilder<any, any, any>>, Opt extends boolean = false> extends JsonSchemaAnyBuilder<Expand<{
     [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never;
@@ -243,6 +269,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     properties?: {
         [K in keyof IN & keyof OUT]: JsonSchema<IN[K], OUT[K]>;
     };
+    patternProperties?: StringMap<JsonSchema<any, any>>;
     required?: string[];
     additionalProperties?: boolean;
     minProperties?: number;
@@ -273,6 +300,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     maxItems?: number;
     uniqueItems?: boolean;
     enum?: any;
+    hasIsOfTypeCheck?: boolean;
     email?: JsonSchemaStringEmailOptions;
     Set2?: JsonSchema;
     Buffer?: true;
@@ -286,7 +314,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
         truncate?: number;
     };
     errorMessages?: StringMap<string>;
-    hasIsOfTypeCheck?: boolean;
+    optionalValues?: (string | number | boolean)[];
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -24,6 +24,17 @@ export const j = {
         any() {
             return j.object({}).allowAdditionalProperties();
         },
+        stringMap(schema) {
+            const builtSchema = schema.build();
+            _assert(!builtSchema?.optionalField, 'In a StringMap schema the value cannot be `undefined`, because `undefined` is not a valid JSON Schema value.');
+            builtSchema.optionalField = undefined;
+            return new JsonSchemaObjectBuilder({}, {
+                hasIsOfTypeCheck: false,
+                patternProperties: {
+                    '^.+$': builtSchema,
+                },
+            });
+        },
         /**
          * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
          */
@@ -43,7 +54,7 @@ export const j = {
                     enumValues = _stringEnumValues(keys);
                 }
             }
-            _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StrinEnum');
+            _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum');
             const typedValues = enumValues;
             const props = Object.fromEntries(typedValues.map(key => [key, schema]));
             return new JsonSchemaObjectBuilder(props, { hasIsOfTypeCheck: false });
@@ -90,6 +101,13 @@ export const j = {
             oneOf: schemas,
         });
     },
+    and() {
+        return {
+            silentBob: () => {
+                throw new Error('...strike back!');
+            },
+        };
+    },
 };
 const TS_2500 = 16725225600; // 2500-01-01
 const TS_2500_MILLIS = TS_2500 * 1000;
@@ -216,6 +234,16 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
             type: 'string',
         });
     }
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValues) {
+        _objectAssign(this.schema, { optionalValues });
+        return super.optional();
+    }
     regex(pattern, opt) {
         return this.pattern(pattern.source, opt);
     }
@@ -368,6 +396,16 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
             type: 'number',
         });
     }
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValues) {
+        _objectAssign(this.schema, { optionalValues });
+        return super.optional();
+    }
     integer() {
         _objectAssign(this.schema, { type: 'integer' });
         return this;
@@ -466,6 +504,18 @@ export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
             type: 'boolean',
         });
     }
+    /**
+     * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    optional(optionalValue) {
+        if (typeof optionalValue !== 'undefined') {
+            _objectAssign(this.schema, { optionalValues: [optionalValue] });
+        }
+        return super.optional();
+    }
 }
 export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
     constructor(props, opt) {
@@ -475,6 +525,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
             required: [],
             additionalProperties: false,
             hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
+            patternProperties: opt?.patternProperties ?? undefined,
         });
         if (props)
             this.addProperties(props);

package/package.json

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

package/src/validation/ajv/ajvSchema.ts

@@ -79,6 +79,13 @@ export class AjvSchema<IN = unknown, OUT = IN> {
       jsonSchema = schema
     }
 
+    // This is our own helper which marks a schema as optional
+    // in case it is going to be used in an object schema,
+    // where we need to mark the given property as not-required.
+    // But once all compilation is done, the presence of this field
+    // really upsets Ajv.
+    delete jsonSchema.optionalField
+
     const ajvSchema = new AjvSchema<IN, OUT>(jsonSchema, cfg)
     AjvSchema.cacheAjvSchema(schema, ajvSchema)
 

package/src/validation/ajv/getAjv.ts

@@ -109,7 +109,7 @@ export function createAjv(opt?: Options): Ajv {
 
   ajv.addKeyword({
     keyword: 'instanceof',
-    modifying: true,
+    modifying: false,
     schemaType: 'string',
     validate(instanceOf: string, data: unknown, _schema, _ctx) {
       if (typeof data !== 'object') return false
@@ -396,6 +396,30 @@ export function createAjv(opt?: Options): Ajv {
     schemaType: 'boolean',
   })
 
+  ajv.addKeyword({
+    keyword: 'optionalValues',
+    type: ['string', 'number', 'boolean'],
+    modifying: true,
+    errors: false,
+    schemaType: 'array',
+    validate: function validate(
+      optionalValues: (string | number | boolean)[],
+      data: string | number | boolean,
+      _schema,
+      ctx,
+    ) {
+      if (!optionalValues) return true
+
+      if (!optionalValues.includes(data)) return true
+
+      if (ctx?.parentData && ctx.parentDataProperty) {
+        ctx.parentData[ctx.parentDataProperty] = undefined
+      }
+
+      return true
+    },
+  })
+
   return ajv
 }
 

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -66,6 +66,27 @@ export const j = {
       return j.object<AnyObject>({}).allowAdditionalProperties()
     },
 
+    stringMap<S extends JsonSchemaTerminal<any, any, any>>(
+      schema: S,
+    ): JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>> {
+      const builtSchema = schema.build()
+      _assert(
+        !builtSchema?.optionalField,
+        'In a StringMap schema the value cannot be `undefined`, because `undefined` is not a valid JSON Schema value.',
+      )
+      builtSchema.optionalField = undefined
+
+      return new JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>>(
+        {},
+        {
+          hasIsOfTypeCheck: false,
+          patternProperties: {
+            '^.+$': builtSchema,
+          },
+        },
+      )
+    },
+
     /**
      * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
      */
@@ -97,7 +118,7 @@ export const j = {
         }
       }
 
-      _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StrinEnum')
+      _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum')
 
       const typedValues = enumValues as readonly K[]
       const props = Object.fromEntries(typedValues.map(key => [key, schema])) as any
@@ -172,6 +193,14 @@ export const j = {
       oneOf: schemas,
     })
   },
+
+  and() {
+    return {
+      silentBob: () => {
+        throw new Error('...strike back!')
+      },
+    }
+  },
 }
 
 const TS_2500 = 16725225600 // 2500-01-01
@@ -317,7 +346,7 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, O
 }
 
 export class JsonSchemaStringBuilder<
-  IN extends string = string,
+  IN extends string | undefined = string,
   OUT = IN,
   Opt extends boolean = false,
 > extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -327,6 +356,23 @@ export class JsonSchemaStringBuilder<
     })
   }
 
+  /**
+   * @param optionalValues List of values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  override optional(
+    optionalValues?: string[],
+  ): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
+    _objectAssign(this.schema, { optionalValues })
+    return super.optional() as unknown as JsonSchemaStringBuilder<
+      IN | undefined,
+      OUT | undefined,
+      true
+    >
+  }
+
   regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
     return this.pattern(pattern.source, opt)
   }
@@ -519,7 +565,7 @@ export interface JsonSchemaIsoDateOptions {
 }
 
 export class JsonSchemaNumberBuilder<
-  IN extends number = number,
+  IN extends number | undefined = number,
   OUT = IN,
   Opt extends boolean = false,
 > extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -529,6 +575,23 @@ export class JsonSchemaNumberBuilder<
     })
   }
 
+  /**
+   * @param optionalValues List of values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  override optional(
+    optionalValues?: number[],
+  ): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
+    _objectAssign(this.schema, { optionalValues })
+    return super.optional() as unknown as JsonSchemaNumberBuilder<
+      IN | undefined,
+      OUT | undefined,
+      true
+    >
+  }
+
   integer(): this {
     _objectAssign(this.schema, { type: 'integer' })
     return this
@@ -649,7 +712,7 @@ export class JsonSchemaNumberBuilder<
 }
 
 export class JsonSchemaBooleanBuilder<
-  IN extends boolean = boolean,
+  IN extends boolean | undefined = boolean,
   OUT = IN,
   Opt extends boolean = false,
 > extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -658,6 +721,26 @@ export class JsonSchemaBooleanBuilder<
       type: 'boolean',
     })
   }
+
+  /**
+   * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  override optional(
+    optionalValue?: boolean,
+  ): JsonSchemaBooleanBuilder<IN | undefined, OUT | undefined, true> {
+    if (typeof optionalValue !== 'undefined') {
+      _objectAssign(this.schema, { optionalValues: [optionalValue] })
+    }
+
+    return super.optional() as unknown as JsonSchemaBooleanBuilder<
+      IN | undefined,
+      OUT | undefined,
+      true
+    >
+  }
 }
 
 export class JsonSchemaObjectBuilder<
@@ -672,6 +755,7 @@ export class JsonSchemaObjectBuilder<
       required: [],
       additionalProperties: false,
       hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
+      patternProperties: opt?.patternProperties ?? undefined,
     })
 
     if (props) this.addProperties(props)
@@ -742,6 +826,7 @@ export class JsonSchemaObjectBuilder<
 
 interface JsonSchemaObjectBuilderOpts {
   hasIsOfTypeCheck?: false
+  patternProperties?: StringMap<JsonSchema<any, any>>
 }
 
 export class JsonSchemaObjectInferringBuilder<
@@ -972,6 +1057,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   properties?: {
     [K in keyof IN & keyof OUT]: JsonSchema<IN[K], OUT[K]>
   }
+  patternProperties?: StringMap<JsonSchema<any, any>>
   required?: string[]
   additionalProperties?: boolean
   minProperties?: number
@@ -1012,6 +1098,8 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
 
   enum?: any
 
+  hasIsOfTypeCheck?: boolean
+
   // Below we add custom Ajv keywords
 
   email?: JsonSchemaStringEmailOptions
@@ -1022,7 +1110,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   instanceof?: string | string[]
   transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
   errorMessages?: StringMap<string>
-  hasIsOfTypeCheck?: boolean
+  optionalValues?: (string | number | boolean)[]
 }
 
 function object(props: AnyObject): never