@naturalcycles/nodejs-lib 15.83.0 → 15.85.0

package/dist/stream/stream.model.d.ts

@@ -24,9 +24,9 @@ export interface ReadableTyped<T = unknown> extends Readable {
     take: (limit: number, opt?: ReadableSignalOptions) => ReadableTyped<T>;
     drop: (limit: number, opt?: ReadableSignalOptions) => ReadableTyped<T>;
 }
-export interface WritableTyped<T> extends Writable {
+export interface WritableTyped<_T> extends Writable {
 }
-export interface TransformTyped<IN = unknown, OUT = unknown> extends Transform {
+export interface TransformTyped<_IN = unknown, _OUT = unknown> extends Transform {
 }
 export interface TransformOptions {
     /**

package/dist/validation/ajv/getAjv.js

@@ -1,4 +1,5 @@
 import { _isBetween, _lazyValue } 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';
 import { Ajv2020 } from 'ajv/dist/2020.js';
@@ -165,7 +166,7 @@ export function createAjv(opt) {
                     }
                     idx++;
                 }
-                if (ctx?.parentData && ctx.parentDataProperty) {
+                if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                     ctx.parentData[ctx.parentDataProperty] = set;
                 }
                 return true;
@@ -215,7 +216,7 @@ export function createAjv(opt) {
                     ];
                     return false;
                 }
-                if (ctx?.parentData && ctx.parentDataProperty) {
+                if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                     ctx.parentData[ctx.parentDataProperty] = buffer;
                 }
                 return true;
@@ -258,7 +259,7 @@ export function createAjv(opt) {
                     return false;
                 }
             }
-            if (ctx?.parentData && ctx.parentDataProperty) {
+            if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                 ctx.parentData[ctx.parentDataProperty] = cleanData;
             }
             return true;
@@ -381,18 +382,17 @@ export function createAjv(opt) {
     });
     ajv.addKeyword({
         keyword: 'optionalValues',
-        type: ['string', 'number', 'boolean'],
+        type: ['string', 'number', 'boolean', 'null'],
         modifying: true,
         errors: false,
         schemaType: 'array',
         validate: function validate(optionalValues, data, _schema, ctx) {
             if (!optionalValues)
                 return true;
+            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `optional([x, y, z]) on a property of an object, or on an element of an array due to Ajv mutation issues.');
             if (!optionalValues.includes(data))
                 return true;
-            if (ctx?.parentData && ctx.parentDataProperty) {
-                delete ctx.parentData[ctx.parentDataProperty];
-            }
+            ctx.parentData[ctx.parentDataProperty] = undefined;
             return true;
         },
     });
@@ -417,7 +417,7 @@ export function createAjv(opt) {
             return validate;
         },
     });
-    // This and `maxProperties2` are added because Ajv validates the `min/maxProperties` before validating the properties.
+    // This is added because Ajv validates the `min/maxProperties` before validating the properties.
     // So, in case of `minProperties(1)` and `{ foo: 'bar' }` Ajv will let it pass, even
     // if the property validation would strip `foo` from the data.
     // And Ajv would return `{}` as a successful validation.
@@ -434,7 +434,7 @@ export function createAjv(opt) {
         validate: function validate(minProperties, data, _schema, ctx) {
             if (typeof data !== 'object')
                 return true;
-            const numberOfProperties = Object.getOwnPropertyNames(data).length;
+            const numberOfProperties = Object.entries(data).filter(([, v]) => v !== undefined).length;
             const isValid = numberOfProperties >= minProperties;
             if (!isValid) {
                 ;
@@ -533,7 +533,7 @@ export function createAjv(opt) {
                         break;
                     }
                 }
-                if (result && ctx?.parentData && ctx.parentDataProperty) {
+                if (result && ctx?.parentData && ctx.parentDataProperty !== undefined) {
                     // If we found a validator and the data is valid and we are validating a property inside an object,
                     // then we can inject our result and be done with it.
                     ctx.parentData[ctx.parentDataProperty] = clonedData;

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

@@ -169,8 +169,13 @@ export declare class JsonSchemaStringBuilder<IN extends string | undefined = str
      *
      * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
-    optional(optionalValues?: string[]): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>;
+    optional<T extends readonly (string | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true> : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>;
     regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this;
     pattern(pattern: string, opt?: JsonBuilderRuleOpt): this;
     minLength(minLength: number): this;
@@ -244,8 +249,13 @@ export declare class JsonSchemaNumberBuilder<IN extends number | undefined = num
      *
      * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
-    optional(optionalValues?: number[]): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>;
+    optional<T extends readonly (number | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true> : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>;
     integer(): this;
     branded<B extends number>(): JsonSchemaNumberBuilder<B, B, Opt>;
     multipleOf(multipleOf: number): this;
@@ -283,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.
      */
@@ -345,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.
      */
@@ -457,7 +503,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
         truncate?: number;
     };
     errorMessages?: StringMap<string>;
-    optionalValues?: (string | number | boolean)[];
+    optionalValues?: (string | number | boolean | null)[];
     keySchema?: JsonSchema;
     minProperties2?: number;
     exclusiveProperties?: (readonly string[])[];
@@ -469,7 +515,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {
-    [K in keyof Required<IN>]-?: JsonSchemaAnyBuilder<any, IN[K], any>;
+    [K in keyof Required<IN>]-?: JsonSchemaTerminal<any, IN[K], any>;
 }): JsonSchemaObjectBuilder<IN, IN, false>;
 declare function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any, any>>>(props: P): JsonSchemaObjectInferringBuilder<P, false>;
 declare function objectDbEntity(props: AnyObject): never;

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -4,7 +4,7 @@ import { _isUndefined, _numberEnumValues, _stringEnumValues, getEnumType, } from
 import { _uniq } from '@naturalcycles/js-lib/array';
 import { _assert } from '@naturalcycles/js-lib/error';
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object';
-import { _objectAssign, JWT_REGEX, } from '@naturalcycles/js-lib/types';
+import { _objectAssign, _typeCast, JWT_REGEX, } from '@naturalcycles/js-lib/types';
 import { BASE64URL_REGEX, COUNTRY_CODE_REGEX, CURRENCY_REGEX, IPV4_REGEX, IPV6_REGEX, LANGUAGE_TAG_REGEX, SEMVER_REGEX, SLUG_REGEX, URL_REGEX, UUID_REGEX, } from '../regexes.js';
 import { TIMEZONES } from '../timezones.js';
 import { isEveryItemNumber, isEveryItemPrimitive, isEveryItemString, JSON_SCHEMA_ORDER, mergeJsonSchemaObjects, } from './jsonSchemaBuilder.util.js';
@@ -326,17 +326,33 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
      *
      * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(optionalValues) {
         if (!optionalValues) {
             return super.optional();
         }
-        const newBuilder = new JsonSchemaStringBuilder().optional();
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaStringBuilder().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
             optionalValues,
         });
+        // 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 a StringSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
         return newBuilder;
     }
     regex(pattern, opt) {
@@ -502,17 +518,33 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
      *
      * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(optionalValues) {
         if (!optionalValues) {
             return super.optional();
         }
-        const newBuilder = new JsonSchemaNumberBuilder().optional();
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaNumberBuilder().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
             optionalValues,
         });
+        // 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 a NumberSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
         return newBuilder;
     }
     integer() {
@@ -655,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.
      */
@@ -741,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.83.0",
+  "version": "15.85.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/stream/stream.model.ts

@@ -50,9 +50,11 @@ export interface ReadableTyped<T = unknown> extends Readable {
 }
 
 // oxlint-disable no-unused-vars
-export interface WritableTyped<T> extends Writable {}
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface WritableTyped<_T> extends Writable {}
 
-export interface TransformTyped<IN = unknown, OUT = unknown> extends Transform {}
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface TransformTyped<_IN = unknown, _OUT = unknown> extends Transform {}
 // oxlint-enable
 
 export interface TransformOptions {

package/src/validation/ajv/getAjv.ts

@@ -1,4 +1,5 @@
 import { _isBetween, _lazyValue } 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'
 import type { AnyObject } from '@naturalcycles/js-lib/types'
@@ -195,7 +196,7 @@ export function createAjv(opt?: Options): Ajv2020 {
           idx++
         }
 
-        if (ctx?.parentData && ctx.parentDataProperty) {
+        if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
           ctx.parentData[ctx.parentDataProperty] = set
         }
 
@@ -248,7 +249,7 @@ export function createAjv(opt?: Options): Ajv2020 {
           return false
         }
 
-        if (ctx?.parentData && ctx.parentDataProperty) {
+        if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
           ctx.parentData[ctx.parentDataProperty] = buffer
         }
 
@@ -297,7 +298,7 @@ export function createAjv(opt?: Options): Ajv2020 {
         }
       }
 
-      if (ctx?.parentData && ctx.parentDataProperty) {
+      if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
         ctx.parentData[ctx.parentDataProperty] = cleanData
       }
 
@@ -435,7 +436,7 @@ export function createAjv(opt?: Options): Ajv2020 {
 
   ajv.addKeyword({
     keyword: 'optionalValues',
-    type: ['string', 'number', 'boolean'],
+    type: ['string', 'number', 'boolean', 'null'],
     modifying: true,
     errors: false,
     schemaType: 'array',
@@ -447,11 +448,14 @@ export function createAjv(opt?: Options): Ajv2020 {
     ) {
       if (!optionalValues) return true
 
+      _assert(
+        ctx?.parentData && ctx.parentDataProperty !== undefined,
+        'You should only use `optional([x, y, z]) on a property of an object, or on an element of an array due to Ajv mutation issues.',
+      )
+
       if (!optionalValues.includes(data)) return true
 
-      if (ctx?.parentData && ctx.parentDataProperty) {
-        delete ctx.parentData[ctx.parentDataProperty]
-      }
+      ctx.parentData[ctx.parentDataProperty] = undefined
 
       return true
     },
@@ -482,7 +486,7 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
-  // This and `maxProperties2` are added because Ajv validates the `min/maxProperties` before validating the properties.
+  // This is added because Ajv validates the `min/maxProperties` before validating the properties.
   // So, in case of `minProperties(1)` and `{ foo: 'bar' }` Ajv will let it pass, even
   // if the property validation would strip `foo` from the data.
   // And Ajv would return `{}` as a successful validation.
@@ -499,7 +503,7 @@ export function createAjv(opt?: Options): Ajv2020 {
     validate: function validate(minProperties: number, data: AnyObject, _schema, ctx) {
       if (typeof data !== 'object') return true
 
-      const numberOfProperties = Object.getOwnPropertyNames(data).length
+      const numberOfProperties = Object.entries(data).filter(([, v]) => v !== undefined).length
       const isValid = numberOfProperties >= minProperties
       if (!isValid) {
         ;(validate as any).errors = [
@@ -608,7 +612,7 @@ export function createAjv(opt?: Options): Ajv2020 {
           }
         }
 
-        if (result && ctx?.parentData && ctx.parentDataProperty) {
+        if (result && ctx?.parentData && ctx.parentDataProperty !== undefined) {
           // If we found a validator and the data is valid and we are validating a property inside an object,
           // then we can inject our result and be done with it.
           ctx.parentData[ctx.parentDataProperty] = clonedData

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -13,6 +13,7 @@ import type { Set2 } from '@naturalcycles/js-lib/object'
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
 import {
   _objectAssign,
+  _typeCast,
   type AnyObject,
   type BaseDBEntity,
   type IANATimezone,
@@ -468,26 +469,45 @@ export class JsonSchemaStringBuilder<
    *
    * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
    * due to how mutability works in Ajv.
+   *
+   * Make sure this `optional()` call is at the end of your call chain.
+   *
+   * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
    */
-  override optional(
-    optionalValues?: string[],
-  ): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
+  override optional<T extends readonly (string | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (infer U)[]
+    ? null extends U
+      ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+      : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
     if (!optionalValues) {
-      return super.optional() as unknown as JsonSchemaStringBuilder<
-        IN | undefined,
-        OUT | undefined,
-        true
-      >
+      return super.optional() as any
     }
 
-    const newBuilder = new JsonSchemaStringBuilder<IN, OUT, Opt>().optional()
+    _typeCast<(string | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaStringBuilder<IN, OUT, Opt>().optional()
     const alternativesSchema = j.enum(optionalValues)
     Object.assign(newBuilder.getSchema(), {
       anyOf: [this.build(), alternativesSchema.build()],
       optionalValues,
     })
 
-    return newBuilder
+    // 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 a StringSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
   }
 
   regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
@@ -716,27 +736,45 @@ export class JsonSchemaNumberBuilder<
    *
    * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
    * due to how mutability works in Ajv.
+   *
+   * Make sure this `optional()` call is at the end of your call chain.
+   *
+   * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
    */
-
-  override optional(
-    optionalValues?: number[],
-  ): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
+  override optional<T extends readonly (number | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (infer U)[]
+    ? null extends U
+      ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+      : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
     if (!optionalValues) {
-      return super.optional() as unknown as JsonSchemaNumberBuilder<
-        IN | undefined,
-        OUT | undefined,
-        true
-      >
+      return super.optional() as any
     }
 
-    const newBuilder = new JsonSchemaNumberBuilder<IN, OUT, Opt>().optional()
+    _typeCast<(number | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaNumberBuilder<IN, OUT, Opt>().optional()
     const alternativesSchema = j.enum(optionalValues)
     Object.assign(newBuilder.getSchema(), {
       anyOf: [this.build(), alternativesSchema.build()],
       optionalValues,
     })
 
-    return newBuilder
+    // 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 a NumberSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
   }
 
   integer(): this {
@@ -930,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.
    */
@@ -1108,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.
    */
@@ -1400,7 +1563,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   instanceof?: string | string[]
   transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
   errorMessages?: StringMap<string>
-  optionalValues?: (string | number | boolean)[]
+  optionalValues?: (string | number | boolean | null)[]
   keySchema?: JsonSchema
   minProperties2?: number
   exclusiveProperties?: (readonly string[])[]
@@ -1413,11 +1576,11 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
 
 function object(props: AnyObject): never
 function object<IN extends AnyObject>(props: {
-  [K in keyof Required<IN>]-?: JsonSchemaAnyBuilder<any, IN[K], any>
+  [K in keyof Required<IN>]-?: JsonSchemaTerminal<any, IN[K], any>
 }): JsonSchemaObjectBuilder<IN, IN, false>
 
 function object<IN extends AnyObject>(props: {
-  [key in keyof IN]: JsonSchemaAnyBuilder<any, IN[key], any>
+  [key in keyof IN]: JsonSchemaTerminal<any, IN[key], any>
 }): JsonSchemaObjectBuilder<IN, IN, false> {
   return new JsonSchemaObjectBuilder<IN, IN, false>(props)
 }