@naturalcycles/nodejs-lib 15.57.1 → 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>;
@@ -205,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;
@@ -316,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: {
@@ -338,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.
  */
@@ -378,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

@@ -33,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);
@@ -527,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);
@@ -715,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.1",
+  "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

@@ -82,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>(
@@ -749,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)
@@ -820,6 +855,7 @@ export class JsonSchemaObjectBuilder<
 interface JsonSchemaObjectBuilderOpts {
   hasIsOfTypeCheck?: false
   patternProperties?: StringMap<JsonSchema<any, any>>
+  keySchema?: JsonSchema
 }
 
 export class JsonSchemaObjectInferringBuilder<
@@ -1107,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
@@ -1156,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.
  */
@@ -1245,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