@naturalcycles/nodejs-lib 15.96.1 → 15.97.1

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

@@ -184,7 +184,18 @@ export declare class JBuilder<OUT, Opt> extends JSchema<OUT, Opt> {
     type(type: string): this;
     default(v: any): this;
     instanceof(of: string): this;
-    optional(): JBuilder<OUT | undefined, true>;
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * 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 `JSchema`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional<T extends readonly (string | number | boolean | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (string | number | boolean | null)[] ? JSchema<OUT | undefined, true> : JBuilder<OUT | undefined, true>;
     nullable(): JBuilder<OUT | null, Opt>;
     /**
      * @deprecated
@@ -216,18 +227,6 @@ export declare class JBuilder<OUT, Opt> extends JSchema<OUT, Opt> {
 }
 export declare class JString<OUT extends string | undefined = string, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
     constructor();
-    /**
-     * @param optionalValues List of values that should be considered/converted as `undefined`.
-     *
-     * 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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional<T extends readonly (string | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JSchema<OUT | undefined, true> : JString<OUT | undefined, true> : JString<OUT | undefined, true>;
     regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this;
     pattern(pattern: string, opt?: JsonBuilderRuleOpt): this;
     minLength(minLength: number): this;
@@ -277,16 +276,6 @@ export interface JsonSchemaStringEmailOptions {
 }
 export declare class JIsoDate<Opt extends boolean = false> extends JBuilder<IsoDate, Opt> {
     constructor();
-    /**
-     * @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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional<N extends null | undefined = undefined>(nullValue?: N): N extends null ? JSchema<IsoDate | undefined, true> : JBuilder<IsoDate | undefined, true>;
     before(date: string): this;
     sameOrBefore(date: string): this;
     after(date: string): this;
@@ -303,18 +292,6 @@ export interface JsonSchemaIsoMonthOptions {
 }
 export declare class JNumber<OUT extends number | undefined = number, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
     constructor();
-    /**
-     * @param optionalValues List of values that should be considered/converted as `undefined`.
-     *
-     * 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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional<T extends readonly (number | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JSchema<OUT | undefined, true> : JNumber<OUT | undefined, true> : JNumber<OUT | undefined, true>;
     integer(): this;
     branded<B extends number>(): JNumber<B, Opt>;
     multipleOf(multipleOf: number): this;
@@ -347,26 +324,9 @@ export declare class JNumber<OUT extends number | undefined = number, Opt extend
 }
 export declare class JBoolean<OUT extends boolean | undefined = boolean, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
     constructor();
-    /**
-     * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
-     *
-     * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
-     * due to how mutability works in Ajv.
-     */
-    optional(optionalValue?: boolean): JBoolean<OUT | undefined, true>;
 }
 export declare class JObject<OUT extends AnyObject, Opt extends boolean = false> extends JBuilder<OUT, Opt> {
     constructor(props?: AnyObject, opt?: JObjectOpts);
-    /**
-     * @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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional<N extends null | undefined = undefined>(nullValue?: N): N extends null ? JSchema<OUT | undefined, true> : JBuilder<OUT | undefined, true>;
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */
@@ -401,35 +361,17 @@ interface JObjectOpts {
     patternProperties?: StringMap<JsonSchema<any>>;
     keySchema?: JsonSchema;
 }
-export declare class JObjectInfer<PROPS extends Record<string, JBuilder<any, any>>, Opt extends boolean = false> extends JBuilder<Expand<{
-    [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
+export declare class JObjectInfer<PROPS extends Record<string, JSchema<any, any>>, Opt extends boolean = false> extends JBuilder<Expand<{
+    [K in keyof PROPS as PROPS[K] extends JSchema<any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JSchema<infer OUT, any> ? OUT : never;
 } & {
-    [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
+    [K in keyof PROPS as PROPS[K] extends JSchema<any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JSchema<infer OUT, any> ? OUT : never;
 }>, Opt> {
     constructor(props?: PROPS);
-    /**
-     * @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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional<N extends null | undefined = undefined>(nullValue?: N): N extends null ? JSchema<Expand<{
-        [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
-    } & {
-        [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
-    }> | undefined, true> : JBuilder<Expand<{
-        [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? never : K : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
-    } & {
-        [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt> ? IsOpt extends true ? K : never : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never;
-    }> | undefined, true>;
     /**
      * When set, the validation will not strip away properties that are not specified explicitly in the schema.
      */
     allowAdditionalProperties(): this;
-    extend<NEW_PROPS extends Record<string, JBuilder<any, any>>>(props: NEW_PROPS): JObjectInfer<{
+    extend<NEW_PROPS extends Record<string, JSchema<any, any>>>(props: NEW_PROPS): JObjectInfer<{
         [K in keyof PROPS | keyof NEW_PROPS]: K extends keyof NEW_PROPS ? NEW_PROPS[K] : K extends keyof PROPS ? PROPS[K] : never;
     }, Opt>;
     /**
@@ -466,7 +408,7 @@ declare function object(props: AnyObject): never;
 declare function object<OUT extends AnyObject>(props: {
     [K in keyof Required<OUT>]-?: JSchema<OUT[K], any>;
 }): JObject<OUT, false>;
-declare function objectInfer<P extends Record<string, JBuilder<any, any>>>(props: P): JObjectInfer<P, false>;
+declare function objectInfer<P extends Record<string, JSchema<any, any>>>(props: P): JObjectInfer<P, false>;
 declare function objectDbEntity(props: AnyObject): never;
 declare function objectDbEntity<OUT extends BaseDBEntity, EXTRA_KEYS extends Exclude<keyof OUT, keyof BaseDBEntity> = Exclude<keyof OUT, keyof BaseDBEntity>>(props: {
     [K in EXTRA_KEYS]-?: BuilderFor<OUT[K]>;

package/dist/validation/ajv/jSchema.js

@@ -405,9 +405,58 @@ export class JBuilder extends JSchema {
     instanceof(of) {
         return this.cloneAndUpdateSchema({ type: 'object', instanceof: of });
     }
-    optional() {
-        const clone = this.cloneAndUpdateSchema({ optionalField: true });
-        return clone;
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * 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 `JSchema`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional(optionalValues) {
+        if (!optionalValues?.length) {
+            const clone = this.cloneAndUpdateSchema({ optionalField: true });
+            return clone;
+        }
+        const builtSchema = this.build();
+        // When optionalValues is just [null], use a simple null-wrapping structure.
+        // If the schema already has anyOf with a null branch (from nullable()),
+        // inject optionalValues directly into it.
+        if (optionalValues.length === 1 && optionalValues[0] === null) {
+            if (builtSchema.anyOf) {
+                const nullBranch = builtSchema.anyOf.find(b => b.type === 'null');
+                if (nullBranch) {
+                    nullBranch.optionalValues = [null];
+                    return new JSchema({ ...builtSchema, optionalField: true });
+                }
+            }
+            // Wrap with null type branch
+            return new JSchema({
+                anyOf: [{ type: 'null', optionalValues: [null] }, builtSchema],
+                optionalField: true,
+            });
+        }
+        // General case: create anyOf with current schema + alternatives.
+        // Preserve the original type for Ajv strict mode (optionalValues keyword requires a type).
+        const alternativesSchema = j.enum(optionalValues).build();
+        const innerSchema = {
+            ...(builtSchema.type ? { type: builtSchema.type } : {}),
+            anyOf: [builtSchema, alternativesSchema],
+            optionalValues: [...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.
+        if (optionalValues.includes(null)) {
+            return new JSchema({
+                anyOf: [{ type: 'null', optionalValues: [...optionalValues] }, innerSchema],
+                optionalField: true,
+            });
+        }
+        return new JSchema({ ...innerSchema, optionalField: true });
     }
     nullable() {
         return new JBuilder({
@@ -468,40 +517,6 @@ export class JString extends JBuilder {
             type: 'string',
         });
     }
-    /**
-     * @param optionalValues List of values that should be considered/converted as `undefined`.
-     *
-     * 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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional(optionalValues) {
-        if (!optionalValues) {
-            return super.optional();
-        }
-        _typeCast(optionalValues);
-        let newBuilder = new JString().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 JSchema({
-                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
-                optionalField: true,
-            });
-        }
-        return newBuilder;
-    }
     regex(pattern, opt) {
         _assert(!pattern.flags, `Regex flags are not supported by JSON Schema. Received: /${pattern.source}/${pattern.flags}`);
         return this.pattern(pattern.source, opt);
@@ -626,28 +641,6 @@ export class JIsoDate extends JBuilder {
             IsoDate: {},
         });
     }
-    /**
-     * @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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    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 JSchema({
-            anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
-            optionalField: true,
-        });
-    }
     before(date) {
         return this.cloneAndUpdateSchema({ IsoDate: { before: date } });
     }
@@ -677,40 +670,6 @@ export class JNumber extends JBuilder {
             type: 'number',
         });
     }
-    /**
-     * @param optionalValues List of values that should be considered/converted as `undefined`.
-     *
-     * 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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    optional(optionalValues) {
-        if (!optionalValues) {
-            return super.optional();
-        }
-        _typeCast(optionalValues);
-        let newBuilder = new JNumber().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 JSchema({
-                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
-                optionalField: true,
-            });
-        }
-        return newBuilder;
-    }
     integer() {
         return this.cloneAndUpdateSchema({ type: 'integer' });
     }
@@ -811,24 +770,6 @@ export class JBoolean extends JBuilder {
             type: 'boolean',
         });
     }
-    /**
-     * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
-     *
-     * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
-     * due to how mutability works in Ajv.
-     */
-    optional(optionalValue) {
-        if (typeof optionalValue === 'undefined') {
-            return super.optional();
-        }
-        const newBuilder = new JBoolean().optional();
-        const alternativesSchema = j.enum([optionalValue]);
-        Object.assign(newBuilder.getSchema(), {
-            anyOf: [this.build(), alternativesSchema.build()],
-            optionalValues: [optionalValue],
-        });
-        return newBuilder;
-    }
 }
 export class JObject extends JBuilder {
     constructor(props, opt) {
@@ -844,28 +785,6 @@ export class JObject extends JBuilder {
         if (props)
             addPropertiesToSchema(this.schema, props);
     }
-    /**
-     * @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 `JSchema`
-     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-     */
-    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 JSchema({
-            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.
      */
@@ -926,29 +845,6 @@ export class JObjectInfer extends JBuilder {
         if (props)
             addPropertiesToSchema(this.schema, props);
     }
-    /**
-     * @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 `JSchema`
-     * (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 JSchema({
-            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.96.1",
+  "version": "15.97.1",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/validation/ajv/jSchema.ts

@@ -567,9 +567,68 @@ export class JBuilder<OUT, Opt> extends JSchema<OUT, Opt> {
     return this.cloneAndUpdateSchema({ type: 'object', instanceof: of })
   }
 
-  optional(): JBuilder<OUT | undefined, true> {
-    const clone = this.cloneAndUpdateSchema({ optionalField: true })
-    return clone as unknown as JBuilder<OUT | undefined, true>
+  /**
+   * @param optionalValues List of values that should be considered/converted as `undefined`.
+   *
+   * 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 `JSchema`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   */
+  optional<T extends readonly (string | number | boolean | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (string | number | boolean | null)[]
+    ? JSchema<OUT | undefined, true>
+    : JBuilder<OUT | undefined, true> {
+    if (!optionalValues?.length) {
+      const clone = this.cloneAndUpdateSchema({ optionalField: true })
+      return clone as any
+    }
+
+    const builtSchema = this.build()
+
+    // When optionalValues is just [null], use a simple null-wrapping structure.
+    // If the schema already has anyOf with a null branch (from nullable()),
+    // inject optionalValues directly into it.
+    if (optionalValues.length === 1 && optionalValues[0] === null) {
+      if (builtSchema.anyOf) {
+        const nullBranch = builtSchema.anyOf.find(b => b.type === 'null')
+        if (nullBranch) {
+          nullBranch.optionalValues = [null]
+          return new JSchema({ ...builtSchema, optionalField: true }) as any
+        }
+      }
+
+      // Wrap with null type branch
+      return new JSchema({
+        anyOf: [{ type: 'null', optionalValues: [null] }, builtSchema],
+        optionalField: true,
+      }) as any
+    }
+
+    // General case: create anyOf with current schema + alternatives.
+    // Preserve the original type for Ajv strict mode (optionalValues keyword requires a type).
+    const alternativesSchema = j.enum(optionalValues).build()
+    const innerSchema: JsonSchema = {
+      ...(builtSchema.type ? { type: builtSchema.type } : {}),
+      anyOf: [builtSchema, alternativesSchema],
+      optionalValues: [...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.
+    if (optionalValues.includes(null)) {
+      return new JSchema({
+        anyOf: [{ type: 'null', optionalValues: [...optionalValues] }, innerSchema],
+        optionalField: true,
+      }) as any
+    }
+
+    return new JSchema({ ...innerSchema, optionalField: true }) as any
   }
 
   nullable(): JBuilder<OUT | null, Opt> {
@@ -643,51 +702,6 @@ export class JString<
     })
   }
 
-  /**
-   * @param optionalValues List of values that should be considered/converted as `undefined`.
-   *
-   * 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 `JSchema`
-   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-   */
-  override optional<T extends readonly (string | null)[] | undefined = undefined>(
-    optionalValues?: T,
-  ): T extends readonly (infer U)[]
-    ? null extends U
-      ? JSchema<OUT | undefined, true>
-      : JString<OUT | undefined, true>
-    : JString<OUT | undefined, true> {
-    if (!optionalValues) {
-      return super.optional() as any
-    }
-
-    _typeCast<(string | null)[]>(optionalValues)
-
-    let newBuilder: JSchema<OUT | undefined, true> = new JString<OUT, Opt>().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 JSchema({
-        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
-        optionalField: true,
-      })
-    }
-
-    return newBuilder as any
-  }
-
   regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
     _assert(
       !pattern.flags,
@@ -846,32 +860,6 @@ export class JIsoDate<Opt extends boolean = false> extends JBuilder<IsoDate, Opt
     })
   }
 
-  /**
-   * @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 `JSchema`
-   * (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 ? JSchema<IsoDate | undefined, true> : JBuilder<IsoDate | 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 JSchema({
-      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
-      optionalField: true,
-    }) as any
-  }
-
   before(date: string): this {
     return this.cloneAndUpdateSchema({ IsoDate: { before: date } })
   }
@@ -920,51 +908,6 @@ export class JNumber<
     })
   }
 
-  /**
-   * @param optionalValues List of values that should be considered/converted as `undefined`.
-   *
-   * 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 `JSchema`
-   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-   */
-  override optional<T extends readonly (number | null)[] | undefined = undefined>(
-    optionalValues?: T,
-  ): T extends readonly (infer U)[]
-    ? null extends U
-      ? JSchema<OUT | undefined, true>
-      : JNumber<OUT | undefined, true>
-    : JNumber<OUT | undefined, true> {
-    if (!optionalValues) {
-      return super.optional() as any
-    }
-
-    _typeCast<(number | null)[]>(optionalValues)
-
-    let newBuilder: JSchema<OUT | undefined, true> = new JNumber<OUT, Opt>().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 JSchema({
-        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
-        optionalField: true,
-      })
-    }
-
-    return newBuilder as any
-  }
-
   integer(): this {
     return this.cloneAndUpdateSchema({ type: 'integer' })
   }
@@ -1092,27 +1035,6 @@ export class JBoolean<
       type: 'boolean',
     })
   }
-
-  /**
-   * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
-   *
-   * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
-   * due to how mutability works in Ajv.
-   */
-  override optional(optionalValue?: boolean): JBoolean<OUT | undefined, true> {
-    if (typeof optionalValue === 'undefined') {
-      return super.optional() as unknown as JBoolean<OUT | undefined, true>
-    }
-
-    const newBuilder = new JBoolean<OUT, Opt>().optional()
-    const alternativesSchema = j.enum([optionalValue])
-    Object.assign(newBuilder.getSchema(), {
-      anyOf: [this.build(), alternativesSchema.build()],
-      optionalValues: [optionalValue],
-    })
-
-    return newBuilder
-  }
 }
 
 export class JObject<OUT extends AnyObject, Opt extends boolean = false> extends JBuilder<
@@ -1133,32 +1055,6 @@ export class JObject<OUT extends AnyObject, Opt extends boolean = false> extends
     if (props) addPropertiesToSchema(this.schema, props)
   }
 
-  /**
-   * @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 `JSchema`
-   * (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 ? JSchema<OUT | undefined, true> : JBuilder<OUT | 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 JSchema({
-      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.
    */
@@ -1248,22 +1144,22 @@ interface JObjectOpts {
 }
 
 export class JObjectInfer<
-  PROPS extends Record<string, JBuilder<any, any>>,
+  PROPS extends Record<string, JSchema<any, any>>,
   Opt extends boolean = false,
 > extends JBuilder<
   Expand<
     {
-      [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+      [K in keyof PROPS as PROPS[K] extends JSchema<any, infer IsOpt>
         ? IsOpt extends true
           ? never
           : K
-        : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+        : never]: PROPS[K] extends JSchema<infer OUT, any> ? OUT : never
     } & {
-      [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+      [K in keyof PROPS as PROPS[K] extends JSchema<any, infer IsOpt>
         ? IsOpt extends true
           ? K
           : never
-        : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+        : never]?: PROPS[K] extends JSchema<infer OUT, any> ? OUT : never
     }
   >,
   Opt
@@ -1279,71 +1175,6 @@ export class JObjectInfer<
     if (props) addPropertiesToSchema(this.schema, props)
   }
 
-  /**
-   * @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 `JSchema`
-   * (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
-    ? JSchema<
-        | Expand<
-            {
-              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? never
-                  : K
-                : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
-            } & {
-              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? K
-                  : never
-                : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
-            }
-          >
-        | undefined,
-        true
-      >
-    : JBuilder<
-        | Expand<
-            {
-              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? never
-                  : K
-                : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
-            } & {
-              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? K
-                  : never
-                : never]?: PROPS[K] extends JBuilder<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 JSchema({
-      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.
    */
@@ -1352,7 +1183,7 @@ export class JObjectInfer<
     return this.cloneAndUpdateSchema({ additionalProperties: true })
   }
 
-  extend<NEW_PROPS extends Record<string, JBuilder<any, any>>>(
+  extend<NEW_PROPS extends Record<string, JSchema<any, any>>>(
     props: NEW_PROPS,
   ): JObjectInfer<
     {
@@ -1495,7 +1326,7 @@ function object<OUT extends AnyObject>(props: {
   return new JObject<OUT, false>(props)
 }
 
-function objectInfer<P extends Record<string, JBuilder<any, any>>>(
+function objectInfer<P extends Record<string, JSchema<any, any>>>(
   props: P,
 ): JObjectInfer<P, false> {
   return new JObjectInfer<P, false>(props)