Merge pull request #200 from ping-maxwell/experimental

feat(experimental): allow null when schema is optional

Author: ping-maxwell

packages/experimental/src/fn.test.ts

@@ -88,9 +88,9 @@ describe("omittable input", () => {
 
 	it("optional object omit is undefined - field defaults do not run", () => {
 		// `{ optional: true }` on the object means "may be absent". An absent
-		// payload stays undefined; size's default only applies when an object
-		// was actually sent. InferInput must carry `| undefined` so
-		// `c.input.size` is not typed as a bare number.
+		// payload stays undefined/null; size's default only applies when an
+		// object was actually sent. InferInput must carry `| undefined | null`
+		// so `c.input.size` is not typed as a bare number.
 		const generateId = v.fn(
 			"fnt.generateId",
 			{
@@ -101,14 +101,17 @@ describe("omittable input", () => {
 				output: v.string(),
 			},
 			(c) => {
-				expectTypeOf(c.input).toEqualTypeOf<{ size: number } | undefined>();
-				if (c.input === undefined) return "missing";
+				expectTypeOf(c.input).toEqualTypeOf<
+					{ size: number } | undefined | null
+				>();
+				if (c.input == null) return "missing";
 				expectTypeOf(c.input.size).toEqualTypeOf<number>();
 				return `s${c.input.size}`;
 			},
 		);
 		expect(generateId()).toBe("missing");
 		expect(generateId(undefined)).toBe("missing");
+		expect(generateId(null)).toBe("missing");
 		// An empty object is present - field defaults apply.
 		expect(generateId({})).toBe("s32");
 		expect(generateId({ size: 8 })).toBe("s8");
@@ -528,7 +531,7 @@ describe("fn as input schema", () => {
 		});
 		const run = v.fn({ input: hooks }, (c) => {
 			expectTypeOf(c.input.onCreate).toEqualTypeOf<
-				((input: { id: string }) => any) | undefined
+				((input: { id: string }) => any) | undefined | null
 			>();
 			expectTypeOf(c.input.onDelete).toEqualTypeOf<
 				(input: { id: string }) => any
@@ -537,6 +540,7 @@ describe("fn as input schema", () => {
 		});
 		// Required sibling stays required - omit onCreate only.
 		expect(run({ onDelete: () => null })).toBe("skipped");
+		expect(run({ onDelete: () => null, onCreate: null })).toBe("skipped");
 		expect(
 			run({
 				onDelete: () => null,

packages/experimental/src/schema-dx.test.ts

@@ -8,7 +8,7 @@ describe("v.string type-arg + optional DX", () => {
 		const field = v.string<"a" | "b">({ optional: true });
 		expectTypeOf<InferType<typeof field>>().toEqualTypeOf<"a" | "b">();
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			"a" | "b" | undefined
+			"a" | "b" | undefined | null
 		>();
 	});
 
@@ -40,42 +40,46 @@ describe("other vTypes type-arg + optional DX", () => {
 	it("v.any with type param accepts optional: true", () => {
 		const field = v.any<{ id: string }>({ optional: true });
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			{ id: string } | undefined
+			{ id: string } | undefined | null
 		>();
 	});
 
 	it("v.number accepts optional: true without a type param", () => {
 		const field = v.number({ optional: true });
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			number | undefined
+			number | undefined | null
 		>();
 	});
 
 	it("v.number with output type param accepts optional: true", () => {
 		const field = v.number<number>({ optional: true });
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			number | undefined
+			number | undefined | null
 		>();
 	});
 
 	it("v.boolean/date accept optional: true", () => {
 		const b = v.boolean({ optional: true });
 		const d = v.date({ optional: true });
-		expectTypeOf<InferOutput<typeof b>>().toEqualTypeOf<boolean | undefined>();
-		expectTypeOf<InferOutput<typeof d>>().toEqualTypeOf<Date | undefined>();
+		expectTypeOf<InferOutput<typeof b>>().toEqualTypeOf<
+			boolean | undefined | null
+		>();
+		expectTypeOf<InferOutput<typeof d>>().toEqualTypeOf<
+			Date | undefined | null
+		>();
 	});
 
 	it("v.array with element accepts optional: true", () => {
 		const field = v.array(v.string<"a" | "b">(), { optional: true });
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			("a" | "b")[] | undefined
+			("a" | "b")[] | undefined | null
 		>();
 	});
 
 	it("v.object with shape accepts optional: true", () => {
 		const field = v.object({ kind: v.string<"a" | "b">() }, { optional: true });
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
-			{ kind: "a" | "b" } | undefined
+			{ kind: "a" | "b" } | undefined | null
 		>();
 	});
 
@@ -108,9 +112,9 @@ describe("other vTypes type-arg + optional DX", () => {
 			{ optional: true, default: {} },
 		);
 		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<{
-			password: { hash?: string; verify?: string };
+			password: { hash?: string | null; verify?: string | null };
 			minPasswordLength: number;
-			maxPasswordLength?: number;
+			maxPasswordLength?: number | null;
 		}>();
 	});
 
@@ -251,8 +255,9 @@ describe("v.union", () => {
 	it("optional and default behave like other types", () => {
 		const optional = v.union([v.string(), v.number()], { optional: true });
 		expect(validate(optional, undefined, "x")).toBeUndefined();
+		expect(validate(optional, null, "x")).toBeNull();
 		expectTypeOf<InferOutput<typeof optional>>().toEqualTypeOf<
-			string | number | undefined
+			string | number | undefined | null
 		>();
 
 		const withDefault = v.union([v.string(), v.number()], { default: 0 });
@@ -262,6 +267,27 @@ describe("v.union", () => {
 		>();
 	});
 
+	it("optional accepts null the same way as undefined", () => {
+		const field = v.string({ optional: true });
+		expect(validate(field, null, "x")).toBeNull();
+		expect(validate(field, undefined, "x")).toBeUndefined();
+		expectTypeOf<InferArgs<typeof field>>().toEqualTypeOf<string | null>();
+		expectTypeOf<InferOutput<typeof field>>().toEqualTypeOf<
+			string | undefined | null
+		>();
+
+		const withDefault = v.string({ optional: true, default: "hi" });
+		expect(validate(withDefault, null, "x")).toBe("hi");
+		expect(validate(withDefault, undefined, "x")).toBe("hi");
+
+		const shaped = v.object({
+			name: v.string({ optional: true }),
+		});
+		expect(validate(shaped, { name: null }, "x")).toEqual({ name: null });
+		expect(validate(shaped, {}, "x")).toEqual({});
+		expect(() => validate(v.string(), null, "x")).toThrow(/expected string/);
+	});
+
 	it("aggregates issues from every failing branch", () => {
 		const field = v.union([v.string({ min: 2 }), v.number({ min: 10 })]);
 		try {

packages/experimental/src/schema.ts

@@ -38,7 +38,7 @@ export interface TypeDefination<T, O, D = never> extends Rules {
 	 * is called (fresh value per validate) except on `function` schemas,
 	 * where the default IS the fn. */
 	default?: D | (() => D);
-	/** When true, `undefined` passes straight through unvalidated. */
+	/** When true, `undefined` and `null` pass straight through unvalidated. */
 	optional?: boolean;
 	transform?: (value: any) => O;
 	/** Opaque plugin attributes - ignored by validate / Infer*. */
@@ -52,8 +52,9 @@ export type TypeOptions<T, O> = {
 };
 
 /**
- * `optional` widens the output; `default` keeps it narrow because a value
- * is always produced. Declaring both means optional to send, never absent.
+ * `optional` widens the output with `| undefined | null`; `default` keeps
+ * it narrow because a value is always produced. Declaring both means
+ * optional to send, never absent.
  *
  * Helpers select among these via option-shape overloads rather than `Opt` /
  * `D` type parameters: providing a partial type argument (e.g.
@@ -62,7 +63,7 @@ export type TypeOptions<T, O> = {
  */
 type OutOf<O, D, Opt> = [Opt] extends [true]
 	? [D] extends [never]
-		? O | undefined
+		? O | undefined | null
 		: O
 	: O;
 
@@ -71,15 +72,15 @@ type OutOf<O, D, Opt> = [Opt] extends [true]
  * `TypeDefination<any, infer O, …>` drops `| undefined` because `output?`
  * is optional and TypeScript attributes the undefined to the property.
  * When the third type arg is `undefined` (optional, no default), put
- * `| undefined` back so handlers see the same absence validate produces
- * at runtime.
+ * `| undefined | null` back so handlers see the same absence validate
+ * produces at runtime.
  */
 type OutputOf<F> =
 	F extends TypeDefination<any, infer O, infer D>
 		? [D] extends [never]
 			? O
 			: undefined extends D
-				? O | undefined
+				? O | undefined | null
 				: O
 		: never;
 
@@ -256,20 +257,23 @@ type FieldIn<F> = F extends { $var: true; schema?: infer S }
 	? InferArgs<NonNullable<S>>
 	: F extends { $fnSchema: { input?: infer FI; output?: infer FO } }
 		? SchemaFnIn<FI, FO> & FnVarBrand<FI>
-		: F extends TypeDefination<infer T, any, any>
-			? T
+		: F extends TypeDefination<infer T, any, infer D>
+			? undefined extends D
+				? T | null
+				: T
 			: F extends Record<string, unknown>
 				? ArgsShape<F>
 				: F;
 
 /**
  * `optional: true` on `v.fn.type` widens the same way a type's `optional`
- * does: absent without a default means the value may be `undefined`.
+ * does: absent without a default means the value may be `undefined` or
+ * `null`.
  */
 type FnSchemaOut<F, Fn> = F extends { optional: true }
 	? F extends { default: infer _D }
 		? Fn
-		: Fn | undefined
+		: Fn | undefined | null
 	: Fn;
 
 /**
@@ -331,8 +335,10 @@ export type InferArgs<I> = I extends { $var: true; schema?: infer S }
 		? SchemaFnIn<FI, FO> & FnVarBrand<FI>
 		: I extends readonly unknown[]
 			? { -readonly [K in keyof I]: InferArgs<I[K]> }
-			: I extends TypeDefination<infer T, any, any>
-				? T
+			: I extends TypeDefination<infer T, any, infer D>
+				? undefined extends D
+					? T | null
+					: T
 				: ArgsShape<I>;
 
 export const isType = (value: any): value is TypeDefination<any, any> =>
@@ -542,11 +548,12 @@ export const validate = (
 	value: unknown,
 	path: string,
 ): any => {
-	// `undefined` falls back to the declared default before anything else,
-	// then to `optional`, which passes it through untouched. A shaped
-	// object with no default treats omit as `{}` so all-optional fields
-	// can be left off the call without a dummy payload.
-	if (value === undefined) {
+	// `undefined` / (when optional) `null` fall back to the declared
+	// default before anything else, then to `optional`, which passes the
+	// absence through untouched. A shaped object with no default treats
+	// omit as `{}` so all-optional fields can be left off the call without
+	// a dummy payload. Non-optional `null` falls through to the type check.
+	if (value === undefined || (value === null && def.optional)) {
 		if (def.default !== undefined) {
 			// Factories produce a fresh value each time - needed for Date /
 			// object / array defaults. Skip on `function` schemas: there the
@@ -555,7 +562,7 @@ export const validate = (
 				typeof def.default === "function" && def.name !== "function"
 					? (def.default as () => unknown)()
 					: def.default;
-		} else if (def.optional) return undefined;
+		} else if (def.optional) return value;
 		else if (def.name === "object" && def.shape !== undefined) value = {};
 	}
 	// A var used as an input field validates against its own schema. An
@@ -881,7 +888,7 @@ type ArrayFn = {
 	(
 		element?: undefined,
 		options?: ArrayOptions<undefined, any[]> & { optional: true },
-	): TypeDefination<any[], any[] | undefined, undefined>;
+	): TypeDefination<any[], any[] | undefined | null, undefined>;
 	(
 		element?: undefined,
 		options?: ArrayOptions<undefined, any[]> & {