@naturalcycles/nodejs-lib 15.57.1 → 15.59.0

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

@@ -39,9 +39,9 @@ export declare class AjvSchema<IN = unknown, OUT = IN> {
      *
      * Returned object is always the same object (`===`) that was passed, so it is returned just for convenience.
      */
-    validate(input: IN, opt?: AjvValidationOptions): OUT;
-    isValid(input: IN, opt?: AjvValidationOptions): boolean;
-    getValidationResult(input: IN, opt?: AjvValidationOptions): ValidationFunctionResult<OUT, AjvValidationError>;
+    validate(input: IN, opt?: AjvValidationOptions<IN>): OUT;
+    isValid(input: IN, opt?: AjvValidationOptions<IN>): boolean;
+    getValidationResult(input: IN, opt?: AjvValidationOptions<IN>): ValidationFunctionResult<OUT, AjvValidationError>;
     getValidationFunction(): ValidationFunction<IN, OUT, AjvValidationError>;
     static isSchemaWithCachedAjvSchema<Base, IN, OUT>(schema: Base): schema is WithCachedAjvSchema<Base, IN, OUT>;
     static cacheAjvSchema<Base extends AnyObject, IN, OUT>(schema: Base, ajvSchema: AjvSchema<IN, OUT>): WithCachedAjvSchema<Base, IN, OUT>;
@@ -54,7 +54,7 @@ export declare const HIDDEN_AJV_SCHEMA: unique symbol;
 export type WithCachedAjvSchema<Base, IN, OUT> = Base & {
     [HIDDEN_AJV_SCHEMA]: AjvSchema<IN, OUT>;
 };
-export interface AjvValidationOptions {
+export interface AjvValidationOptions<IN> {
     /**
      * Defaults to true,
      * because that's how AJV works by default,
@@ -73,6 +73,16 @@ export interface AjvValidationOptions {
     mutateInput?: boolean;
     inputName?: string;
     inputId?: string;
+    /**
+     * Function that returns "original input".
+     * What is original input?
+     * It's an input in its original non-mutated form.
+     * Why is it needed?
+     * Because we mutates the Input here. And after its been mutated - we no longer
+     * can include it "how it was" in an error message. So, for that reason we'll use
+     * `getOriginalInput()`, if it's provided.
+     */
+    getOriginalInput?: () => IN;
 }
 export interface AjvSchemaCfg {
     /**

package/dist/validation/ajv/ajvSchema.js

@@ -108,7 +108,7 @@ export class AjvSchema {
         const item = opt.mutateInput !== false || typeof input !== 'object'
             ? input // mutate
             : _deepCopy(input); // not mutate
-        const valid = fn(item); // mutates item
+        const valid = fn(item); // mutates item, but not input
         _typeCast(item);
         if (valid)
             return [null, item];
@@ -122,7 +122,8 @@ export class AjvSchema {
         });
         // Note: if we mutated the input already, e.g stripped unknown properties,
         // the error message Input would contain already mutated object print, such as Input: {}
-        const inputStringified = _inspect(input, { maxLen: 4000 });
+        // Unless `getOriginalInput` function is provided - then it will be used to preserve the Input pureness.
+        const inputStringified = _inspect(opt.getOriginalInput?.() || input, { maxLen: 4000 });
         message = [message, 'Input: ' + inputStringified].join(separator);
         const err = new AjvValidationError(message, _filterNullishValues({
             errors,

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.59.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/validation/ajv/ajvSchema.ts

@@ -120,13 +120,13 @@ export class AjvSchema<IN = unknown, OUT = IN> {
    *
    * Returned object is always the same object (`===`) that was passed, so it is returned just for convenience.
    */
-  validate(input: IN, opt: AjvValidationOptions = {}): OUT {
+  validate(input: IN, opt: AjvValidationOptions<IN> = {}): OUT {
     const [err, output] = this.getValidationResult(input, opt)
     if (err) throw err
     return output
   }
 
-  isValid(input: IN, opt?: AjvValidationOptions): boolean {
+  isValid(input: IN, opt?: AjvValidationOptions<IN>): boolean {
     // todo: we can make it both fast and non-mutating by using Ajv
     // with "removeAdditional" and "useDefaults" disabled.
     const [err] = this.getValidationResult(input, opt)
@@ -135,7 +135,7 @@ export class AjvSchema<IN = unknown, OUT = IN> {
 
   getValidationResult(
     input: IN,
-    opt: AjvValidationOptions = {},
+    opt: AjvValidationOptions<IN> = {},
   ): ValidationFunctionResult<OUT, AjvValidationError> {
     const fn = this.getAJVValidateFunction()
 
@@ -144,7 +144,7 @@ export class AjvSchema<IN = unknown, OUT = IN> {
         ? input // mutate
         : _deepCopy(input) // not mutate
 
-    const valid = fn(item) // mutates item
+    const valid = fn(item) // mutates item, but not input
     _typeCast<OUT>(item)
     if (valid) return [null, item]
 
@@ -165,7 +165,8 @@ export class AjvSchema<IN = unknown, OUT = IN> {
 
     // Note: if we mutated the input already, e.g stripped unknown properties,
     // the error message Input would contain already mutated object print, such as Input: {}
-    const inputStringified = _inspect(input, { maxLen: 4000 })
+    // Unless `getOriginalInput` function is provided - then it will be used to preserve the Input pureness.
+    const inputStringified = _inspect(opt.getOriginalInput?.() || input, { maxLen: 4000 })
     message = [message, 'Input: ' + inputStringified].join(separator)
 
     const err = new AjvValidationError(
@@ -245,7 +246,7 @@ export type WithCachedAjvSchema<Base, IN, OUT> = Base & {
   [HIDDEN_AJV_SCHEMA]: AjvSchema<IN, OUT>
 }
 
-export interface AjvValidationOptions {
+export interface AjvValidationOptions<IN> {
   /**
    * Defaults to true,
    * because that's how AJV works by default,
@@ -264,6 +265,16 @@ export interface AjvValidationOptions {
   mutateInput?: boolean
   inputName?: string
   inputId?: string
+  /**
+   * Function that returns "original input".
+   * What is original input?
+   * It's an input in its original non-mutated form.
+   * Why is it needed?
+   * Because we mutates the Input here. And after its been mutated - we no longer
+   * can include it "how it was" in an error message. So, for that reason we'll use
+   * `getOriginalInput()`, if it's provided.
+   */
+  getOriginalInput?: () => IN
 }
 
 export interface AjvSchemaCfg {

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