@notionhq/workers 0.0.85 → 0.0.86

package/src/schema-builder.ts

@@ -0,0 +1,203 @@
+/**
+ * Zod-like builder for JSONSchema objects.
+ *
+ * Guarantees output always complies with the model provider constraints
+ * enforced by `json-schema.ts` — all object properties in `required`,
+ * `additionalProperties: false`, no forbidden composition keywords, etc.
+ *
+ * @example
+ * ```ts
+ * import { j } from "@notionhq/workers/schema-builder";
+ *
+ * const schema = j.object({
+ *   foo: j.enum("a", "b", "c").describe("The foo field"),
+ *   bar: j.string(),
+ *   count: j.number(),
+ *   tags: j.array(j.string()),
+ *   nickname: j.string().nullable(),
+ *   createdAt: j.datetime(),
+ * });
+ * ```
+ */
+
+import type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
+
+const SCHEMA: unique symbol = Symbol("schema");
+
+export interface SchemaBuilder<T> {
+	readonly [SCHEMA]: AnyJSONSchema;
+	/** Set the JSONSchema description field. Chainable. */
+	describe(text: string): SchemaBuilder<T>;
+	/** Wrap in anyOf with null. Chainable. */
+	nullable(): SchemaBuilder<T | null>;
+}
+
+/** Extracts `T` from `SchemaBuilder<T>` (type-level only). */
+export type Infer<S> = S extends SchemaBuilder<infer T> ? T : never;
+
+/** Extract the plain JSONSchema from a builder. */
+export function getSchema<T>(builder: SchemaBuilder<T>): JSONSchema<T> {
+	return builder[SCHEMA] as JSONSchema<T>;
+}
+
+function makeBuilder<T>(schema: AnyJSONSchema): SchemaBuilder<T> {
+	return {
+		[SCHEMA]: schema,
+		describe(text: string) {
+			return makeBuilder<T>({ ...schema, description: text });
+		},
+		nullable() {
+			const { description: desc, ...rest } = schema as unknown as Record<
+				string,
+				unknown
+			>;
+			const inner =
+				desc !== undefined ? (rest as unknown as AnyJSONSchema) : schema;
+			const wrapper: Record<string, unknown> = {
+				anyOf: [inner, { type: "null" }],
+			};
+			if (desc !== undefined) wrapper.description = desc;
+			return makeBuilder<T | null>(wrapper as unknown as AnyJSONSchema);
+		},
+	};
+}
+
+// ---- Primitives ----
+
+export function string(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string" });
+}
+
+export function number(): SchemaBuilder<number> {
+	return makeBuilder<number>({ type: "number" });
+}
+
+export function integer(): SchemaBuilder<number> {
+	return makeBuilder<number>({ type: "integer" });
+}
+
+export function boolean(): SchemaBuilder<boolean> {
+	return makeBuilder<boolean>({ type: "boolean" });
+}
+
+// ---- Enum ----
+
+function enumBuilder<T extends string>(
+	...values: readonly T[]
+): SchemaBuilder<T>;
+function enumBuilder<T extends number>(
+	...values: readonly T[]
+): SchemaBuilder<T>;
+function enumBuilder(
+	...values: readonly (string | number)[]
+): SchemaBuilder<unknown> {
+	const type = typeof values[0] === "string" ? "string" : "number";
+	return makeBuilder({ type, enum: values } as AnyJSONSchema);
+}
+export { enumBuilder as enum };
+
+// ---- String format shorthands ----
+
+export function datetime(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "date-time" });
+}
+
+export function date(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "date" });
+}
+
+export function time(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "time" });
+}
+
+export function duration(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "duration" });
+}
+
+export function email(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "email" });
+}
+
+export function hostname(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "hostname" });
+}
+
+export function ipv4(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "ipv4" });
+}
+
+export function ipv6(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "ipv6" });
+}
+
+export function uuid(): SchemaBuilder<string> {
+	return makeBuilder<string>({ type: "string", format: "uuid" });
+}
+
+// ---- Composites ----
+
+export function array<T>(
+	items: SchemaBuilder<T>,
+	options?: { minItems?: 0 | 1 },
+): SchemaBuilder<T[]> {
+	const schema: Record<string, unknown> = {
+		type: "array",
+		items: getSchema(items),
+	};
+	if (options?.minItems !== undefined) schema.minItems = options.minItems;
+	return makeBuilder<T[]>(schema as unknown as AnyJSONSchema);
+}
+
+export function object<P extends Record<string, SchemaBuilder<unknown>>>(
+	properties: P,
+): SchemaBuilder<{ [K in keyof P]: Infer<P[K]> }> {
+	const schemaProps: Record<string, AnyJSONSchema> = {};
+	const keys = Object.keys(properties);
+	for (const key of keys) {
+		// biome-ignore lint/style/noNonNullAssertion: key comes from Object.keys(properties)
+		schemaProps[key] = getSchema(properties[key]!);
+	}
+	return makeBuilder({
+		type: "object",
+		properties: schemaProps,
+		required: keys,
+		additionalProperties: false,
+	} as AnyJSONSchema);
+}
+
+export function anyOf<S extends SchemaBuilder<unknown>[]>(
+	...schemas: S
+): SchemaBuilder<Infer<S[number]>> {
+	return makeBuilder({
+		anyOf: schemas.map(getSchema),
+	} as AnyJSONSchema);
+}
+
+// ---- Reference ----
+
+export function ref(path: string): SchemaBuilder<unknown> {
+	return makeBuilder({ $ref: path });
+}
+
+// ---- Namespace export ----
+
+export const j = {
+	string,
+	number,
+	integer,
+	boolean,
+	enum: enumBuilder,
+	datetime,
+	date,
+	time,
+	duration,
+	email,
+	hostname,
+	ipv4,
+	ipv6,
+	uuid,
+	array,
+	object,
+	anyOf,
+	ref,
+};

package/src/worker.ts

@@ -112,23 +112,18 @@ export class Worker {
 	 * Example:
 	 *
 	 * ```ts
+	 * import { j } from "@notionhq/workers/schema-builder";
+	 *
 	 * worker.tool<{ name: string }, string>("sayHello", {
 	 *   title: "Say Hello",
 	 *   description: "Say hello to the user",
-	 *   schema: {
-	 *     type: "object",
-	 *     properties: {
-	 *       name: { type: "string" },
-	 *     },
-	 *     required: ["name"],
-	 *   },
+	 *   schema: j.object({ name: j.string() }),
 	 *   execute: ({ name }, { notion }) => {
 	 *     return `Hello, ${name}!`;
 	 *   },
 	 * })
 	 * ```
 	 *
-	 *
 	 * @param key - The unique key for this capability.
 	 * @param config - The tool configuration.
 	 * @returns The capability object.