@naturalcycles/nodejs-lib 15.84.0 → 15.86.0

package/dist/validation/ajv/getAjv.js

@@ -1,4 +1,4 @@
-import { _isBetween, _lazyValue } from '@naturalcycles/js-lib';
+import { _isBetween, _lazyValue, _round } from '@naturalcycles/js-lib';
 import { _assert } from '@naturalcycles/js-lib/error';
 import { _deepCopy, _mapObject, Set2 } from '@naturalcycles/js-lib/object';
 import { _substringAfterLast } from '@naturalcycles/js-lib/string';
@@ -560,6 +560,20 @@ export function createAjv(opt) {
             return validate;
         },
     });
+    ajv.addKeyword({
+        keyword: 'precision',
+        type: ['number'],
+        modifying: true,
+        errors: false,
+        schemaType: 'number',
+        validate: function validate(numberOfDigits, data, _schema, ctx) {
+            if (!numberOfDigits)
+                return true;
+            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `precision(n) on a property of an object, or on an element of an array due to Ajv mutation issues.');
+            ctx.parentData[ctx.parentDataProperty] = _round(data, 10 ** (-1 * numberOfDigits));
+            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

@@ -279,6 +279,12 @@ export declare class JsonSchemaNumberBuilder<IN extends number | undefined = num
     unixTimestamp2000Millis(): JsonSchemaNumberBuilder<UnixTimestampMillis, UnixTimestampMillis, Opt>;
     utcOffset(): this;
     utcOffsetHour(): this;
+    /**
+     * Specify the precision of the floating point numbers by the number of digits after the ".".
+     * Excess digits will be cut-off when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    precision(numberOfDigits: number): this;
 }
 export declare class JsonSchemaBooleanBuilder<IN extends boolean | undefined = boolean, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();
@@ -293,6 +299,16 @@ export declare class JsonSchemaBooleanBuilder<IN extends boolean | undefined = b
 export declare class JsonSchemaObjectBuilder<IN extends AnyObject, OUT extends AnyObject, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor(props?: AnyObject, opt?: JsonSchemaObjectBuilderOpts);
     addProperties(props: AnyObject): this;
+    /**
+     * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+     *
+     * This `null` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional<N extends null | undefined = undefined>(nullValue?: N): N extends null ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true> : JsonSchemaAnyBuilder<IN | undefined, OUT | undefined, true>;
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */
@@ -355,6 +371,32 @@ export declare class JsonSchemaObjectInferringBuilder<PROPS extends Record<strin
 }>, Opt> {
     constructor(props?: PROPS);
     addProperties(props: PROPS): this;
+    /**
+     * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+     *
+     * This `null` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional<N extends null | undefined = undefined>(nullValue?: N): N extends null ? JsonSchemaTerminal<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;
+    } & {
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never;
+    }> | undefined, Expand<{
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never;
+    } & {
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never;
+    }> | undefined, true> : 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;
+    } & {
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never;
+    }> | undefined, Expand<{
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never;
+    } & {
+        [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never;
+    }> | undefined, true>;
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */
@@ -476,6 +518,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
         schemaDictionary: Record<string, JsonSchema>;
     };
     anyOfThese?: JsonSchema[];
+    precision?: number;
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -632,6 +632,14 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
     utcOffsetHour() {
         return this.integer().min(-12).max(14);
     }
+    /**
+     * Specify the precision of the floating point numbers by the number of digits after the ".".
+     * Excess digits will be cut-off when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    precision(numberOfDigits) {
+        return this.cloneAndUpdateSchema({ precision: numberOfDigits });
+    }
 }
 export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -687,6 +695,28 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         this.schema.required = _uniq(required).sort();
         return this;
     }
+    /**
+     * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+     *
+     * This `null` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional(nullValue) {
+        if (typeof nullValue === 'undefined') {
+            return super.optional();
+        }
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building an ObjectSchema anymore.
+        return new JsonSchemaTerminal({
+            anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+            optionalField: true,
+        });
+    }
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */
@@ -773,6 +803,29 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
         this.schema.required = _uniq(required).sort();
         return this;
     }
+    /**
+     * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+     *
+     * This `null` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    // @ts-expect-error override adds optional parameter which is compatible but TS can't verify complex mapped types
+    optional(nullValue) {
+        if (nullValue === undefined) {
+            return super.optional();
+        }
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building an ObjectSchema anymore.
+        return new JsonSchemaTerminal({
+            anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+            optionalField: true,
+        });
+    }
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */

package/package.json

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

package/src/validation/ajv/getAjv.ts

@@ -1,4 +1,4 @@
-import { _isBetween, _lazyValue } from '@naturalcycles/js-lib'
+import { _isBetween, _lazyValue, _round } from '@naturalcycles/js-lib'
 import { _assert } from '@naturalcycles/js-lib/error'
 import { _deepCopy, _mapObject, Set2 } from '@naturalcycles/js-lib/object'
 import { _substringAfterLast } from '@naturalcycles/js-lib/string'
@@ -639,6 +639,26 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  ajv.addKeyword({
+    keyword: 'precision',
+    type: ['number'],
+    modifying: true,
+    errors: false,
+    schemaType: 'number',
+    validate: function validate(numberOfDigits: number, data: number, _schema, ctx) {
+      if (!numberOfDigits) return true
+
+      _assert(
+        ctx?.parentData && ctx.parentDataProperty !== undefined,
+        'You should only use `precision(n) on a property of an object, or on an element of an array due to Ajv mutation issues.',
+      )
+
+      ctx.parentData[ctx.parentDataProperty] = _round(data, 10 ** (-1 * numberOfDigits))
+
+      return true
+    },
+  })
+
   return ajv
 }
 

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -888,6 +888,15 @@ export class JsonSchemaNumberBuilder<
   utcOffsetHour(): this {
     return this.integer().min(-12).max(14)
   }
+
+  /**
+   * Specify the precision of the floating point numbers by the number of digits after the ".".
+   * Excess digits will be cut-off when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  precision(numberOfDigits: number): this {
+    return this.cloneAndUpdateSchema({ precision: numberOfDigits })
+  }
 }
 
 export class JsonSchemaBooleanBuilder<
@@ -968,6 +977,34 @@ export class JsonSchemaObjectBuilder<
     return this
   }
 
+  /**
+   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+   *
+   * This `null` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   *
+   * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   */
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null
+    ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+    : JsonSchemaAnyBuilder<IN | undefined, OUT | undefined, true> {
+    if (typeof nullValue === 'undefined') {
+      return super.optional()
+    }
+
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building an ObjectSchema anymore.
+    return new JsonSchemaTerminal({
+      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+      optionalField: true,
+    }) as any
+  }
+
   /**
    * When set, the validation will not strip away properties that are not specified explicitly in the schema.
    */
@@ -1146,6 +1183,103 @@ export class JsonSchemaObjectInferringBuilder<
     return this
   }
 
+  /**
+   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+   *
+   * This `null` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   *
+   * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   */
+  // @ts-expect-error override adds optional parameter which is compatible but TS can't verify complex mapped types
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null
+    ? JsonSchemaTerminal<
+        | 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
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            }
+          >
+        | undefined,
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            }
+          >
+        | undefined,
+        true
+      >
+    : 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
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            }
+          >
+        | undefined,
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            }
+          >
+        | undefined,
+        true
+      > {
+    if (nullValue === undefined) {
+      return super.optional() as any
+    }
+
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building an ObjectSchema anymore.
+    return new JsonSchemaTerminal({
+      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+      optionalField: true,
+    }) as any
+  }
+
   /**
    * When set, the validation will not strip away properties that are not specified explicitly in the schema.
    */
@@ -1447,6 +1581,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     schemaDictionary: Record<string, JsonSchema>
   }
   anyOfThese?: JsonSchema[]
+  precision?: number
 }
 
 function object(props: AnyObject): never