@naturalcycles/nodejs-lib 15.84.0 → 15.85.0

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

@@ -293,6 +293,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 +365,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.
      */

package/dist/validation/ajv/jsonSchemaBuilder.js

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

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -968,6 +968,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 +1174,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.
    */