@naturalcycles/nodejs-lib 15.57.0 → 15.58.0

package/dist/validation/ajv/getAjv.js

@@ -374,6 +374,27 @@ export function createAjv(opt) {
             return true;
         },
     });
+    ajv.addKeyword({
+        keyword: 'keySchema',
+        type: 'object',
+        modifying: true,
+        errors: false,
+        schemaType: 'object',
+        compile(innerSchema, _parentSchema, _it) {
+            const isValidKeyFn = ajv.compile(innerSchema);
+            function validate(data, _ctx) {
+                if (typeof data !== 'object' || data === null)
+                    return true;
+                for (const key of Object.keys(data)) {
+                    if (!isValidKeyFn(key)) {
+                        delete data[key];
+                    }
+                }
+                return true;
+            }
+            return validate;
+        },
+    });
     return ajv;
 }
 const monthLengths = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

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

@@ -9,7 +9,40 @@ export declare const j: {
         infer: typeof objectInfer;
         any(): JsonSchemaObjectBuilder<AnyObject, AnyObject, false>;
         stringMap<S extends JsonSchemaTerminal<any, any, any>>(schema: S): JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>>;
+        /**
+         * @experimental Look around, maybe you find a rule that is better for your use-case.
+         *
+         * For Record<K, V> type of validations.
+         * ```ts
+         * const schema = j.object
+         *  .record(
+         *    j
+         *      .string()
+         *      .regex(/^\d{3,4}$/)
+         *      .branded<B>(),
+         *    j.number().nullable(),
+         *  )
+         *  .isOfType<Record<B, number | null>>()
+         * ```
+         *
+         * When the keys of the Record are values from an Enum, prefer `j.object.withEnumKeys`!
+         *
+         * Non-matching keys will be stripped from the object, i.e. they will not cause an error.
+         *
+         * Caveat: This rule first validates values of every properties of the object, and only then validates the keys.
+         * A consequence of that is that the validation will throw when there is an unexpected property with a value not matching the value schema.
+         */
+        record: typeof record;
+        /**
+         * For Record<ENUM, V> type of validations.
+         *
+         * When the keys of the Record are values from an Enum,
+         * this helper is more performant and behaves in a more conventional manner than `j.object.record` would.
+         *
+         *
+         */
         withEnumKeys: typeof withEnumKeys;
+        withRegexKeys: typeof withRegexKeys;
     };
     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>;
@@ -49,6 +82,8 @@ export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTermin
      *
      * const schemaBad = j.string().isOfType<number>() // ❌
      * schemaBad.build() // TypeError: property "build" does not exist on type "never"
+     *
+     * const result = ajvValidateRequest.body(req, schemaBad) // result will have `unknown` type
      * ```
      */
     isOfType<ExpectedType>(): ExactMatch<ExpectedType, OUT> extends true ? this : never;
@@ -203,6 +238,7 @@ export declare class JsonSchemaObjectBuilder<IN extends AnyObject, OUT extends A
 interface JsonSchemaObjectBuilderOpts {
     hasIsOfTypeCheck?: false;
     patternProperties?: StringMap<JsonSchema<any, any>>;
+    keySchema?: JsonSchema;
 }
 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;
@@ -314,6 +350,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     };
     errorMessages?: StringMap<string>;
     optionalValues?: (string | number | boolean)[];
+    keySchema?: JsonSchema;
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {
@@ -336,6 +373,8 @@ declare function objectDbEntity<IN extends BaseDBEntity & AnyObject, EXTRA_KEYS
 } : {
     updated: BuilderFor<IN['updated']>;
 })): JsonSchemaObjectBuilder<IN, IN, false>;
+declare function record<KS extends JsonSchemaAnyBuilder<any, any, any>, VS extends JsonSchemaAnyBuilder<any, any, any>, Opt extends boolean = SchemaOpt<VS>>(keySchema: KS, valueSchema: VS): JsonSchemaObjectBuilder<Opt extends true ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>> : Record<SchemaIn<KS>, SchemaIn<VS>>, Opt extends true ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>> : Record<SchemaOut<KS>, SchemaOut<VS>>, false>;
+declare function withRegexKeys<S extends JsonSchemaAnyBuilder<any, any, any>, Opt extends boolean = SchemaOpt<S>>(keyRegex: RegExp | string, schema: S): JsonSchemaObjectBuilder<Opt extends true ? StringMap<SchemaIn<S>> : StringMap<SchemaIn<S>>, Opt extends true ? StringMap<SchemaOut<S>> : StringMap<SchemaOut<S>>, false>;
 /**
  * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
  */
@@ -376,5 +415,5 @@ interface JsonBuilderRuleOpt {
 type EnumKeyUnion<T> = T extends readonly (infer U)[] ? U : T extends StringEnum | NumberEnum ? T[keyof T] : never;
 type SchemaIn<S> = S extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never;
 type SchemaOut<S> = S extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never;
-type SchemaOpt<S> = S extends JsonSchemaAnyBuilder<any, any, infer Opt> ? Opt : false;
+type SchemaOpt<S> = S extends JsonSchemaAnyBuilder<any, any, infer Opt> ? (Opt extends true ? true : false) : false;
 export {};

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -26,8 +26,6 @@ export const j = {
         },
         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: {
@@ -35,7 +33,40 @@ export const j = {
                 },
             });
         },
+        /**
+         * @experimental Look around, maybe you find a rule that is better for your use-case.
+         *
+         * For Record<K, V> type of validations.
+         * ```ts
+         * const schema = j.object
+         *  .record(
+         *    j
+         *      .string()
+         *      .regex(/^\d{3,4}$/)
+         *      .branded<B>(),
+         *    j.number().nullable(),
+         *  )
+         *  .isOfType<Record<B, number | null>>()
+         * ```
+         *
+         * When the keys of the Record are values from an Enum, prefer `j.object.withEnumKeys`!
+         *
+         * Non-matching keys will be stripped from the object, i.e. they will not cause an error.
+         *
+         * Caveat: This rule first validates values of every properties of the object, and only then validates the keys.
+         * A consequence of that is that the validation will throw when there is an unexpected property with a value not matching the value schema.
+         */
+        record,
+        /**
+         * For Record<ENUM, V> type of validations.
+         *
+         * When the keys of the Record are values from an Enum,
+         * this helper is more performant and behaves in a more conventional manner than `j.object.record` would.
+         *
+         *
+         */
         withEnumKeys,
+        withRegexKeys,
     }),
     array(itemSchema) {
         return new JsonSchemaArrayBuilder(itemSchema);
@@ -111,7 +142,9 @@ export class JsonSchemaTerminal {
      * Same as if it would be JSON.stringified.
      */
     build() {
-        return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER);
+        const jsonSchema = _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER);
+        delete jsonSchema.optionalField;
+        return jsonSchema;
     }
     clone() {
         return new JsonSchemaAnyBuilder(_deepCopy(this.schema));
@@ -140,6 +173,8 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
      *
      * const schemaBad = j.string().isOfType<number>() // ❌
      * schemaBad.build() // TypeError: property "build" does not exist on type "never"
+     *
+     * const result = ajvValidateRequest.body(req, schemaBad) // result will have `unknown` type
      * ```
      */
     isOfType() {
@@ -525,6 +560,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
             additionalProperties: false,
             hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
             patternProperties: opt?.patternProperties ?? undefined,
+            keySchema: opt?.keySchema ?? undefined,
         });
         if (props)
             this.addProperties(props);
@@ -533,13 +569,11 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         const properties = {};
         const required = [];
         for (const [key, builder] of Object.entries(props)) {
-            const schema = builder.build();
-            if (!schema.optionalField) {
+            const isOptional = builder.getSchema().optionalField;
+            if (!isOptional) {
                 required.push(key);
             }
-            else {
-                schema.optionalField = undefined;
-            }
+            const schema = builder.build();
             properties[key] = schema;
         }
         this.schema.properties = properties;
@@ -595,13 +629,11 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
         const properties = {};
         const required = [];
         for (const [key, builder] of Object.entries(props)) {
-            const schema = builder.build();
-            if (!schema.optionalField) {
+            const isOptional = builder.getSchema().optionalField;
+            if (!isOptional) {
                 required.push(key);
             }
-            else {
-                schema.optionalField = undefined;
-            }
+            const schema = builder.build();
             properties[key] = schema;
         }
         this.schema.properties = properties;
@@ -717,6 +749,27 @@ function objectDbEntity(props) {
         ...props,
     });
 }
+function record(keySchema, valueSchema) {
+    const keyJsonSchema = keySchema.build();
+    const valueJsonSchema = valueSchema.build();
+    return new JsonSchemaObjectBuilder([], {
+        hasIsOfTypeCheck: false,
+        keySchema: keyJsonSchema,
+        patternProperties: {
+            ['^.*$']: valueJsonSchema,
+        },
+    });
+}
+function withRegexKeys(keyRegex, schema) {
+    const pattern = keyRegex instanceof RegExp ? keyRegex.source : keyRegex;
+    const jsonSchema = schema.build();
+    return new JsonSchemaObjectBuilder([], {
+        hasIsOfTypeCheck: false,
+        patternProperties: {
+            [pattern]: jsonSchema,
+        },
+    });
+}
 /**
  * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
  */

package/package.json

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

package/src/validation/ajv/getAjv.ts

@@ -1,6 +1,7 @@
 import { _lazyValue } from '@naturalcycles/js-lib'
 import { Set2 } from '@naturalcycles/js-lib/object'
 import { _substringAfterLast } from '@naturalcycles/js-lib/string'
+import type { AnyObject } from '@naturalcycles/js-lib/types'
 import { Ajv, type Options, type ValidateFunction } from 'ajv'
 import { validTLDs } from '../tlds.js'
 import type { JsonSchemaIsoDateOptions, JsonSchemaStringEmailOptions } from './jsonSchemaBuilder.js'
@@ -429,6 +430,31 @@ export function createAjv(opt?: Options): Ajv {
     },
   })
 
+  ajv.addKeyword({
+    keyword: 'keySchema',
+    type: 'object',
+    modifying: true,
+    errors: false,
+    schemaType: 'object',
+    compile(innerSchema, _parentSchema, _it) {
+      const isValidKeyFn: ValidateFunction = ajv.compile(innerSchema)
+
+      function validate(data: AnyObject, _ctx: any): boolean {
+        if (typeof data !== 'object' || data === null) return true
+
+        for (const key of Object.keys(data)) {
+          if (!isValidKeyFn(key)) {
+            delete data[key]
+          }
+        }
+
+        return true
+      }
+
+      return validate
+    },
+  })
+
   return ajv
 }
 

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -70,11 +70,6 @@ export const j = {
       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>>>(
         {},
@@ -87,7 +82,41 @@ export const j = {
       )
     },
 
+    /**
+     * @experimental Look around, maybe you find a rule that is better for your use-case.
+     *
+     * For Record<K, V> type of validations.
+     * ```ts
+     * const schema = j.object
+     *  .record(
+     *    j
+     *      .string()
+     *      .regex(/^\d{3,4}$/)
+     *      .branded<B>(),
+     *    j.number().nullable(),
+     *  )
+     *  .isOfType<Record<B, number | null>>()
+     * ```
+     *
+     * When the keys of the Record are values from an Enum, prefer `j.object.withEnumKeys`!
+     *
+     * Non-matching keys will be stripped from the object, i.e. they will not cause an error.
+     *
+     * Caveat: This rule first validates values of every properties of the object, and only then validates the keys.
+     * A consequence of that is that the validation will throw when there is an unexpected property with a value not matching the value schema.
+     */
+    record,
+
+    /**
+     * For Record<ENUM, V> type of validations.
+     *
+     * When the keys of the Record are values from an Enum,
+     * this helper is more performant and behaves in a more conventional manner than `j.object.record` would.
+     *
+     *
+     */
     withEnumKeys,
+    withRegexKeys,
   }),
 
   array<IN, OUT, Opt>(
@@ -193,7 +222,14 @@ export class JsonSchemaTerminal<IN, OUT, Opt> {
    * Same as if it would be JSON.stringified.
    */
   build(): JsonSchema<IN, OUT> {
-    return _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER)
+    const jsonSchema = _sortObject(
+      JSON.parse(JSON.stringify(this.schema)),
+      JSON_SCHEMA_ORDER,
+    ) as JsonSchema<IN, OUT>
+
+    delete jsonSchema.optionalField
+
+    return jsonSchema
   }
 
   clone(): JsonSchemaAnyBuilder<IN, OUT, Opt> {
@@ -226,6 +262,8 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, O
    *
    * const schemaBad = j.string().isOfType<number>() // ❌
    * schemaBad.build() // TypeError: property "build" does not exist on type "never"
+   *
+   * const result = ajvValidateRequest.body(req, schemaBad) // result will have `unknown` type
    * ```
    */
   isOfType<ExpectedType>(): ExactMatch<ExpectedType, OUT> extends true ? this : never {
@@ -745,6 +783,7 @@ export class JsonSchemaObjectBuilder<
       additionalProperties: false,
       hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
       patternProperties: opt?.patternProperties ?? undefined,
+      keySchema: opt?.keySchema ?? undefined,
     })
 
     if (props) this.addProperties(props)
@@ -755,12 +794,12 @@ export class JsonSchemaObjectBuilder<
     const required: string[] = []
 
     for (const [key, builder] of Object.entries(props)) {
-      const schema = builder.build()
-      if (!schema.optionalField) {
+      const isOptional = (builder as JsonSchemaTerminal<any, any, any>).getSchema().optionalField
+      if (!isOptional) {
         required.push(key)
-      } else {
-        schema.optionalField = undefined
       }
+
+      const schema = builder.build()
       properties[key] = schema
     }
 
@@ -816,6 +855,7 @@ export class JsonSchemaObjectBuilder<
 interface JsonSchemaObjectBuilderOpts {
   hasIsOfTypeCheck?: false
   patternProperties?: StringMap<JsonSchema<any, any>>
+  keySchema?: JsonSchema
 }
 
 export class JsonSchemaObjectInferringBuilder<
@@ -870,12 +910,12 @@ export class JsonSchemaObjectInferringBuilder<
     const required: string[] = []
 
     for (const [key, builder] of Object.entries(props)) {
-      const schema = builder.build()
-      if (!schema.optionalField) {
+      const isOptional = (builder as JsonSchemaTerminal<any, any, any>).getSchema().optionalField
+      if (!isOptional) {
         required.push(key)
-      } else {
-        schema.optionalField = undefined
       }
+
+      const schema = builder.build()
       properties[key] = schema
     }
 
@@ -1103,6 +1143,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
   errorMessages?: StringMap<string>
   optionalValues?: (string | number | boolean)[]
+  keySchema?: JsonSchema
 }
 
 function object(props: AnyObject): never
@@ -1152,6 +1193,68 @@ function objectDbEntity(props: AnyObject): any {
   })
 }
 
+function record<
+  KS extends JsonSchemaAnyBuilder<any, any, any>,
+  VS extends JsonSchemaAnyBuilder<any, any, any>,
+  Opt extends boolean = SchemaOpt<VS>,
+>(
+  keySchema: KS,
+  valueSchema: VS,
+): JsonSchemaObjectBuilder<
+  Opt extends true
+    ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>>
+    : Record<SchemaIn<KS>, SchemaIn<VS>>,
+  Opt extends true
+    ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>>
+    : Record<SchemaOut<KS>, SchemaOut<VS>>,
+  false
+> {
+  const keyJsonSchema = keySchema.build()
+  const valueJsonSchema = valueSchema.build()
+
+  return new JsonSchemaObjectBuilder<
+    Opt extends true
+      ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>>
+      : Record<SchemaIn<KS>, SchemaIn<VS>>,
+    Opt extends true
+      ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>>
+      : Record<SchemaOut<KS>, SchemaOut<VS>>,
+    false
+  >([], {
+    hasIsOfTypeCheck: false,
+    keySchema: keyJsonSchema,
+    patternProperties: {
+      ['^.*$']: valueJsonSchema,
+    },
+  })
+}
+
+function withRegexKeys<
+  S extends JsonSchemaAnyBuilder<any, any, any>,
+  Opt extends boolean = SchemaOpt<S>,
+>(
+  keyRegex: RegExp | string,
+  schema: S,
+): JsonSchemaObjectBuilder<
+  Opt extends true ? StringMap<SchemaIn<S>> : StringMap<SchemaIn<S>>,
+  Opt extends true ? StringMap<SchemaOut<S>> : StringMap<SchemaOut<S>>,
+  false
+> {
+  const pattern = keyRegex instanceof RegExp ? keyRegex.source : keyRegex
+  const jsonSchema = schema.build()
+
+  return new JsonSchemaObjectBuilder<
+    Opt extends true ? StringMap<SchemaIn<S>> : StringMap<SchemaIn<S>>,
+    Opt extends true ? StringMap<SchemaOut<S>> : StringMap<SchemaOut<S>>,
+    false
+  >([], {
+    hasIsOfTypeCheck: false,
+    patternProperties: {
+      [pattern]: jsonSchema,
+    },
+  })
+}
+
 /**
  * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
  */
@@ -1241,4 +1344,5 @@ type EnumKeyUnion<T> =
 
 type SchemaIn<S> = S extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
 type SchemaOut<S> = S extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
-type SchemaOpt<S> = S extends JsonSchemaAnyBuilder<any, any, infer Opt> ? Opt : false
+type SchemaOpt<S> =
+  S extends JsonSchemaAnyBuilder<any, any, infer Opt> ? (Opt extends true ? true : false) : false