@notionhq/workers 0.0.82

package/src/json-schema.test.ts

@@ -0,0 +1,719 @@
+/**
+ * Type-level invariant tests for JSONSchema.
+ *
+ * Most assertions here are compile-time: a `satisfies` proves a schema is
+ * accepted, and `@ts-expect-error` proves an invalid schema is rejected.
+ * The runtime `it()` blocks exist only to give structure and make vitest
+ * report each invariant by name.
+ *
+ * For negative tests with multi-line object literals, we use two patterns:
+ *  1. Place `@ts-expect-error` directly above the offending property line.
+ *  2. Construct the bad value first, then assign on a single line.
+ * This ensures tsc sees the error on the line immediately after the directive.
+ */
+import { describe, expect, it } from "vitest";
+import type {
+	AnyJSONSchema,
+	JSONSchema,
+	JSONSchemaAnyOfDef,
+	JSONSchemaArrayDef,
+	JSONSchemaBooleanDef,
+	JSONSchemaNullDef,
+	JSONSchemaNumberDef,
+	JSONSchemaObjectDef,
+	JSONSchemaRefDef,
+	JSONSchemaStringDef,
+	JSONSchemaStringFormat,
+} from "./json-schema.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Compile-time assertion that U is assignable to T. */
+type Assert<_T, _U extends _T> = true;
+
+/** Compile-time assertion that U is NOT assignable to T. */
+type AssertNot<_T, _U> = _U extends _T ? never : true;
+
+// Suppress "unused" warnings — these are compile-time only.
+type _UseAssert = Assert<unknown, unknown>;
+type _UseAssertNot = AssertNot<never, unknown>;
+
+// ---------------------------------------------------------------------------
+// 1. Primitive schemas resolve correctly
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — primitive resolution", () => {
+	it("string → JSONSchemaStringDef", () => {
+		const _s = {
+			type: "string",
+		} as const satisfies JSONSchema<string>;
+
+		// Ref is always acceptable in any position
+		const _r = { $ref: "#/$defs/Name" } as const satisfies JSONSchema<string>;
+	});
+
+	it("string with format", () => {
+		const _s = {
+			type: "string",
+			format: "date-time",
+		} as const satisfies JSONSchema<string>;
+
+		const _s2 = {
+			type: "string",
+			format: "uuid",
+		} as const satisfies JSONSchema<string>;
+	});
+
+	it("string with enum", () => {
+		const _s = {
+			type: "string",
+			enum: ["a", "b", "c"] as const,
+		} as const satisfies JSONSchema<"a" | "b" | "c">;
+	});
+
+	it("number → JSONSchemaNumberDef", () => {
+		const _n = {
+			type: "number",
+		} as const satisfies JSONSchema<number>;
+
+		const _i = {
+			type: "integer",
+		} as const satisfies JSONSchema<number>;
+	});
+
+	it("number with enum", () => {
+		const _n = {
+			type: "number",
+			enum: [1, 2, 3] as const,
+		} as const satisfies JSONSchema<1 | 2 | 3>;
+	});
+
+	it("boolean → JSONSchemaBooleanDef", () => {
+		const _b = {
+			type: "boolean",
+		} as const satisfies JSONSchema<boolean>;
+	});
+
+	it("null → JSONSchemaNullDef", () => {
+		const _n = {
+			type: "null",
+		} as const satisfies AnyJSONSchema;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 2. Object schemas enforce structural invariants
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — object invariants", () => {
+	it("valid object schema compiles", () => {
+		const _o = {
+			type: "object",
+			properties: {
+				name: { type: "string" },
+				age: { type: "number" },
+			},
+			required: ["name", "age"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<{ name: string; age: number }>;
+	});
+
+	it("object with nested object compiles", () => {
+		const _o = {
+			type: "object",
+			properties: {
+				address: {
+					type: "object",
+					properties: {
+						street: { type: "string" },
+						zip: { type: "string" },
+					},
+					required: ["street", "zip"],
+					additionalProperties: false,
+				},
+			},
+			required: ["address"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<{
+			address: { street: string; zip: string };
+		}>;
+	});
+
+	it("object with $defs compiles", () => {
+		const _o = {
+			type: "object",
+			properties: {
+				name: { $ref: "#/$defs/Name" },
+			},
+			required: ["name"],
+			additionalProperties: false,
+			$defs: {
+				Name: { type: "string" },
+			},
+		} as const satisfies JSONSchema<{ name: string }>;
+	});
+
+	it("empty object compiles", () => {
+		const _o = {
+			type: "object",
+			properties: {},
+			required: [],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<Record<string, never>>;
+	});
+
+	it("rejects object without additionalProperties: false", () => {
+		const bad = {
+			type: "object",
+			properties: { name: { type: "string" } },
+			required: ["name"],
+		} as const;
+		// @ts-expect-error — additionalProperties is missing
+		const _: JSONSchema<{ name: string }> = bad;
+	});
+
+	it("rejects object with additionalProperties: true", () => {
+		const bad = {
+			type: "object",
+			properties: { name: { type: "string" } },
+			required: ["name"],
+			additionalProperties: true,
+		} as const;
+		// @ts-expect-error — additionalProperties must be literally `false`
+		const _: JSONSchema<{ name: string }> = bad;
+	});
+
+	it("rejects missing property in properties", () => {
+		const bad = {
+			type: "object",
+			properties: { name: { type: "string" } },
+			required: ["name"],
+			additionalProperties: false,
+		} as const;
+		// @ts-expect-error — properties must include all keys of T
+		const _: JSONSchema<{ name: string; age: number }> = bad;
+	});
+
+	it("rejects wrong schema type for a property", () => {
+		const bad = {
+			type: "object",
+			properties: { name: { type: "number" } },
+			required: ["name"],
+			additionalProperties: false,
+		} as const;
+		// @ts-expect-error — `name` should be string schema, not number
+		const _: JSONSchema<{ name: string }> = bad;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 3. Nullable types use anyOf pattern
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — nullable types", () => {
+	it("string | null → anyOf with null", () => {
+		const _s = {
+			anyOf: [{ type: "string" }, { type: "null" }],
+		} as const satisfies JSONSchema<string | null>;
+	});
+
+	it("number | null → anyOf with null", () => {
+		const _n = {
+			anyOf: [{ type: "number" }, { type: "null" }],
+		} as const satisfies JSONSchema<number | null>;
+	});
+
+	it("object | null → anyOf with null", () => {
+		const _o = {
+			anyOf: [
+				{
+					type: "object",
+					properties: { id: { type: "number" } },
+					required: ["id"],
+					additionalProperties: false,
+				},
+				{ type: "null" },
+			],
+		} as const satisfies JSONSchema<{ id: number } | null>;
+	});
+
+	it("rejects bare type for nullable", () => {
+		// @ts-expect-error — string | null must use anyOf pattern, not bare string
+		const _bad: JSONSchema<string | null> = { type: "string" };
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 4. Array schemas
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — array schemas", () => {
+	it("string[] compiles", () => {
+		const _a = {
+			type: "array",
+			items: { type: "string" },
+		} as const satisfies JSONSchema<string[]>;
+	});
+
+	it("number[] compiles", () => {
+		const _a = {
+			type: "array",
+			items: { type: "number" },
+		} as const satisfies JSONSchema<number[]>;
+	});
+
+	it("object[] compiles", () => {
+		const _a = {
+			type: "array",
+			items: {
+				type: "object",
+				properties: { name: { type: "string" } },
+				required: ["name"],
+				additionalProperties: false,
+			},
+		} as const satisfies JSONSchema<{ name: string }[]>;
+	});
+
+	it("minItems 0 or 1 compiles", () => {
+		const _a0 = {
+			type: "array",
+			items: { type: "string" },
+			minItems: 0,
+		} as const satisfies JSONSchema<string[]>;
+
+		const _a1 = {
+			type: "array",
+			items: { type: "string" },
+			minItems: 1,
+		} as const satisfies JSONSchema<string[]>;
+	});
+
+	it("rejects minItems > 1", () => {
+		const bad = {
+			type: "array",
+			items: { type: "string" },
+			minItems: 2,
+		} as const;
+		// @ts-expect-error — minItems can only be 0 or 1
+		const _: JSONSchema<string[]> = bad;
+	});
+
+	it("rejects wrong item type", () => {
+		const bad = { type: "array", items: { type: "number" } } as const;
+		// @ts-expect-error — items should be string schema for string[]
+		const _: JSONSchema<string[]> = bad;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 5. Forbidden composition keywords
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — forbidden composition keywords", () => {
+	it("rejects allOf on string def", () => {
+		const _bad: JSONSchemaStringDef = {
+			type: "string",
+			// @ts-expect-error — allOf is forbidden
+			allOf: [{ type: "string" }],
+		};
+	});
+
+	it("rejects not on number def", () => {
+		const _bad: JSONSchemaNumberDef = {
+			type: "number",
+			// @ts-expect-error — not is forbidden
+			not: { type: "string" },
+		};
+	});
+
+	it("rejects if/then/else on boolean def", () => {
+		const _bad: JSONSchemaBooleanDef = {
+			type: "boolean",
+			// @ts-expect-error — if is forbidden
+			if: { type: "string" },
+		};
+	});
+
+	it("rejects allOf on object def", () => {
+		const _bad: JSONSchemaObjectDef<{ x: number }> = {
+			type: "object",
+			properties: { x: { type: "number" } },
+			required: ["x"],
+			additionalProperties: false,
+			// @ts-expect-error — allOf is forbidden
+			allOf: [],
+		};
+	});
+
+	it("rejects anyOf on concrete string def", () => {
+		const _bad: JSONSchemaStringDef = {
+			type: "string",
+			// @ts-expect-error — anyOf is forbidden on concrete defs
+			anyOf: [{ type: "string" }],
+		};
+	});
+
+	it("rejects allOf on array def", () => {
+		const _bad: JSONSchemaArrayDef = {
+			type: "array",
+			items: { type: "string" },
+			// @ts-expect-error — allOf is forbidden
+			allOf: [],
+		};
+	});
+
+	it("rejects allOf on null def", () => {
+		const _bad: JSONSchemaNullDef = {
+			type: "null",
+			// @ts-expect-error — allOf is forbidden
+			allOf: [],
+		};
+	});
+
+	it("rejects allOf on ref def", () => {
+		const _bad: JSONSchemaRefDef = {
+			$ref: "#/$defs/Foo",
+			// @ts-expect-error — allOf is forbidden
+			allOf: [],
+		};
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 6. String format is restricted
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — string format restrictions", () => {
+	it("accepts all valid formats", () => {
+		const formats: JSONSchemaStringFormat[] = [
+			"date-time",
+			"time",
+			"date",
+			"duration",
+			"email",
+			"hostname",
+			"ipv4",
+			"ipv6",
+			"uuid",
+		];
+		expect(formats).toHaveLength(9);
+	});
+
+	it("rejects invalid formats", () => {
+		// @ts-expect-error — "uri" is not a supported format
+		const _bad: JSONSchemaStringDef = { type: "string", format: "uri" };
+	});
+
+	it("rejects uri-reference format", () => {
+		const _bad: JSONSchemaStringDef = {
+			type: "string",
+			// @ts-expect-error — "uri-reference" is not supported
+			format: "uri-reference",
+		};
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 7. Cross-kind type mismatches are rejected
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — cross-kind type mismatches", () => {
+	it("rejects number schema for string type", () => {
+		// @ts-expect-error — cannot use number schema for string
+		const _bad: JSONSchema<string> = { type: "number" };
+	});
+
+	it("rejects string schema for number type", () => {
+		// @ts-expect-error — cannot use string schema for number
+		const _bad: JSONSchema<number> = { type: "string" };
+	});
+
+	it("rejects boolean schema for string type", () => {
+		// @ts-expect-error — cannot use boolean schema for string
+		const _bad: JSONSchema<string> = { type: "boolean" };
+	});
+
+	it("rejects object schema for string type", () => {
+		const bad = {
+			type: "object",
+			properties: {},
+			required: [],
+			additionalProperties: false,
+		} as const;
+		// @ts-expect-error — cannot use object schema for string
+		const _: JSONSchema<string> = bad;
+	});
+
+	it("rejects array schema for number type", () => {
+		const bad = { type: "array", items: { type: "string" } } as const;
+		// @ts-expect-error — cannot use array schema for number
+		const _: JSONSchema<number> = bad;
+	});
+
+	it("rejects string schema for object type", () => {
+		// @ts-expect-error — cannot use string schema for object
+		const _bad: JSONSchema<{ x: number }> = { type: "string" };
+	});
+
+	it("rejects string schema for array type", () => {
+		// @ts-expect-error — cannot use string schema for string[]
+		const _bad: JSONSchema<string[]> = { type: "string" };
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 8. $ref is valid in any position
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — $ref universality", () => {
+	it("$ref satisfies string schema", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+		} as const satisfies JSONSchema<string>;
+	});
+
+	it("$ref satisfies number schema", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+		} as const satisfies JSONSchema<number>;
+	});
+
+	it("$ref satisfies boolean schema", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+		} as const satisfies JSONSchema<boolean>;
+	});
+
+	it("$ref satisfies object schema", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+		} as const satisfies JSONSchema<{ x: number }>;
+	});
+
+	it("$ref satisfies array schema", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+		} as const satisfies JSONSchema<string[]>;
+	});
+
+	it("$ref with description compiles", () => {
+		const _r = {
+			$ref: "#/$defs/Foo",
+			description: "A reference",
+		} as const satisfies JSONSchema<string>;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 9. AnyJSONSchema (T = unknown) accepts all valid forms
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — unknown/AnyJSONSchema", () => {
+	it("accepts all primitive schemas", () => {
+		const schemas: AnyJSONSchema[] = [
+			{ type: "string" },
+			{ type: "number" },
+			{ type: "integer" },
+			{ type: "boolean" },
+			{ type: "null" },
+		];
+		expect(schemas).toHaveLength(5);
+	});
+
+	it("accepts ref schema", () => {
+		const _r: AnyJSONSchema = { $ref: "#/$defs/Foo" };
+	});
+
+	it("accepts anyOf schema", () => {
+		const _a: AnyJSONSchema = {
+			anyOf: [{ type: "string" }, { type: "null" }],
+		};
+	});
+
+	it("accepts array schema", () => {
+		const _a: AnyJSONSchema = {
+			type: "array",
+			items: { type: "string" },
+		};
+	});
+
+	it("accepts object schema", () => {
+		const _o: AnyJSONSchema = {
+			type: "object",
+			properties: { x: { type: "number" } },
+			required: ["x"],
+			additionalProperties: false,
+		};
+	});
+
+	it("JSONSchema<unknown> equals AnyJSONSchema", () => {
+		type _A = Assert<JSONSchema<unknown>, AnyJSONSchema>;
+		type _B = Assert<AnyJSONSchema, JSONSchema<unknown>>;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 10. Complex / edge-case schemas
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — complex schemas", () => {
+	it("deeply nested objects", () => {
+		type Deep = {
+			level1: {
+				level2: {
+					value: string;
+				};
+			};
+		};
+
+		const _d = {
+			type: "object",
+			properties: {
+				level1: {
+					type: "object",
+					properties: {
+						level2: {
+							type: "object",
+							properties: {
+								value: { type: "string" },
+							},
+							required: ["value"],
+							additionalProperties: false,
+						},
+					},
+					required: ["level2"],
+					additionalProperties: false,
+				},
+			},
+			required: ["level1"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<Deep>;
+	});
+
+	it("object with array property", () => {
+		type WithArray = { tags: string[] };
+
+		const _s = {
+			type: "object",
+			properties: {
+				tags: {
+					type: "array",
+					items: { type: "string" },
+				},
+			},
+			required: ["tags"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<WithArray>;
+	});
+
+	it("object with nullable property", () => {
+		type WithNullable = { name: string; nickname: string | null };
+
+		const _s = {
+			type: "object",
+			properties: {
+				name: { type: "string" },
+				nickname: {
+					anyOf: [{ type: "string" }, { type: "null" }],
+				},
+			},
+			required: ["name", "nickname"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<WithNullable>;
+	});
+
+	it("object with enum property", () => {
+		type WithEnum = { status: "active" | "inactive" };
+
+		const _s = {
+			type: "object",
+			properties: {
+				status: {
+					type: "string",
+					enum: ["active", "inactive"],
+				},
+			},
+			required: ["status"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<WithEnum>;
+	});
+
+	it("object with boolean and number properties", () => {
+		type Mixed = { enabled: boolean; count: number };
+
+		const _s = {
+			type: "object",
+			properties: {
+				enabled: { type: "boolean" },
+				count: { type: "number" },
+			},
+			required: ["enabled", "count"],
+			additionalProperties: false,
+		} as const satisfies JSONSchema<Mixed>;
+	});
+
+	it("array of arrays", () => {
+		const _a = {
+			type: "array",
+			items: {
+				type: "array",
+				items: { type: "number" },
+			},
+		} as const satisfies JSONSchema<number[][]>;
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 11. Type-level assertions (no runtime, purely structural)
+// ---------------------------------------------------------------------------
+
+describe("JSONSchema — structural type assertions", () => {
+	it("JSONSchemaObjectDef requires additionalProperties to be false", () => {
+		type _Proof = Assert<
+			JSONSchemaObjectDef<{ x: number }>["additionalProperties"],
+			false
+		>;
+	});
+
+	it("JSONSchemaArrayDef minItems is restricted to 0 | 1", () => {
+		type MinItems = NonNullable<JSONSchemaArrayDef["minItems"]>;
+		type _Proof = Assert<MinItems, 0 | 1>;
+		// And the reverse — 0 | 1 is exactly MinItems
+		type _Reverse = Assert<0 | 1, MinItems>;
+	});
+
+	it("JSONSchemaStringFormat covers exactly 9 formats", () => {
+		type _1 = Assert<JSONSchemaStringFormat, "date-time">;
+		type _2 = Assert<JSONSchemaStringFormat, "time">;
+		type _3 = Assert<JSONSchemaStringFormat, "date">;
+		type _4 = Assert<JSONSchemaStringFormat, "duration">;
+		type _5 = Assert<JSONSchemaStringFormat, "email">;
+		type _6 = Assert<JSONSchemaStringFormat, "hostname">;
+		type _7 = Assert<JSONSchemaStringFormat, "ipv4">;
+		type _8 = Assert<JSONSchemaStringFormat, "ipv6">;
+		type _9 = Assert<JSONSchemaStringFormat, "uuid">;
+	});
+
+	it("JSONSchemaAnyOfDef does not extend ForbiddenCompositionKeywords", () => {
+		const _a: JSONSchemaAnyOfDef = {
+			anyOf: [{ type: "string" }],
+		};
+		const _b: JSONSchemaAnyOfDef = {
+			anyOf: [{ type: "string" }],
+			description: "test",
+		};
+	});
+
+	it("JSONSchemaRefDef requires $ref string", () => {
+		type _Proof = Assert<JSONSchemaRefDef["$ref"], string>;
+	});
+
+	it("JSONSchemaObjectDef properties keys match T keys", () => {
+		type Schema = JSONSchemaObjectDef<{ a: string; b: number }>;
+		type PropKeys = keyof Schema["properties"];
+		type _Proof = Assert<PropKeys, "a" | "b">;
+		type _Reverse = Assert<"a" | "b", PropKeys>;
+	});
+});