@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/cli/codegen.ts

@@ -0,0 +1,51 @@
+import type { DiscoveredCapability } from "./discover.js";
+
+/**
+ * Generate the worker entry module for a set of discovered capabilities.
+ *
+ * The module uses only static imports so that the bundler can bundle the
+ * whole worker into a single file. It is written to `.notion/entry.ts` in
+ * the worker project, so imports are relative to that location.
+ */
+export function generateEntry(capabilities: readonly DiscoveredCapability[]): string {
+	const imports: string[] = [];
+	const registryEntries = new Map<string, string[]>();
+
+	capabilities.forEach((capability, index) => {
+		const binding = `capability_${index}`;
+		imports.push(`import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`);
+
+		const entries = registryEntries.get(capability.type) ?? [];
+		entries.push(`\t\t${JSON.stringify(capability.key)}: ${binding},`);
+		registryEntries.set(capability.type, entries);
+	});
+
+	const registry = Array.from(registryEntries.entries())
+		.map(([type, entries]) => `\t${JSON.stringify(type)}: {\n${entries.join("\n")}\n\t},`)
+		.join("\n");
+
+	return `// Generated by \`notion-workers build\`. Do not edit.
+${imports.join("\n")}
+
+type Handler = (context?: unknown, options?: { concreteOutput?: true }) => Promise<unknown>;
+
+export const capabilities: Record<string, Record<string, { handler: Handler }>> = {
+${registry}
+};
+
+export async function run(
+	type: string,
+	key: string,
+	context?: unknown,
+	options?: { concreteOutput?: true },
+): Promise<unknown> {
+	const capability = capabilities[type]?.[key];
+
+	if (!capability) {
+		throw new Error(\`Capability "\${type}/\${key}" not found\`);
+	}
+
+	return capability.handler(context, options);
+}
+`;
+}

package/src/alpha/cli/discover.test.ts

@@ -0,0 +1,43 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { discoverCapabilities } from "./discover.js";
+
+const FIXTURES = fileURLToPath(new URL("../../../test/fixtures/", import.meta.url));
+
+describe("discoverCapabilities", () => {
+	it("finds top-level files in a registered capability type's directory", async () => {
+		const capabilities = await discoverCapabilities(path.join(FIXTURES, "custom-type"), [
+			{ type: "greeting", directory: "greetings", tag: "greeting" },
+		]);
+
+		// Only top-level .ts files count; subdirectories are plain modules.
+		expect(capabilities).toEqual([
+			{
+				type: "greeting",
+				tag: "greeting",
+				key: "hello",
+				sourcePath: path.join("src", "greetings", "hello.ts"),
+			},
+		]);
+	});
+
+	it("finds capability files by convention", async () => {
+		const capabilities = await discoverCapabilities(path.join(FIXTURES, "basic"));
+
+		expect(capabilities).toEqual([
+			{
+				type: "sync",
+				tag: "sync",
+				key: "static",
+				sourcePath: path.join("src", "syncs", "static.ts"),
+			},
+		]);
+	});
+
+	it("returns nothing when no capability directories exist", async () => {
+		expect(await discoverCapabilities(path.join(FIXTURES, "empty"))).toEqual([]);
+	});
+});

package/src/alpha/cli/discover.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { CapabilityType } from "../manifest.js";
+
+/**
+ * A capability type the build tool knows how to discover: which directory
+ * under `src/` its files live in, and the `_tag` its default exports must
+ * carry. Adding a new capability type to the SDK means adding an entry here
+ * (plus its factory function).
+ */
+export type CapabilityTypeDefinition = {
+	type: CapabilityType;
+	directory: string;
+	tag: string;
+};
+
+export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
+	{ type: "sync", directory: "syncs", tag: "sync" },
+	{ type: "tool", directory: "tools", tag: "tool" },
+	{ type: "workflow", directory: "workflows", tag: "workflow" },
+];
+
+/**
+ * A capability file found during discovery. The key is the file's basename;
+ * combined with the type it forms the capability's identity (`sync/static`).
+ */
+export type DiscoveredCapability = {
+	type: CapabilityType;
+	tag: string;
+	key: string;
+	/** Path to the source file, relative to the project root. */
+	sourcePath: string;
+};
+
+/**
+ * Discover capability files by convention: every `.ts` file directly under
+ * `src/<directory>/` for each registered capability type. Subdirectories are
+ * not searched — they hold plain modules, not capabilities.
+ *
+ * Only capabilities are discovered by file location. Resources (databases,
+ * pacers) live anywhere and are discovered by walking capability configs at
+ * manifest time.
+ */
+export async function discoverCapabilities(
+	projectRoot: string,
+	capabilityTypes: readonly CapabilityTypeDefinition[] = CAPABILITY_TYPES,
+): Promise<DiscoveredCapability[]> {
+	const discovered: DiscoveredCapability[] = [];
+
+	for (const definition of capabilityTypes) {
+		const directory = path.join(projectRoot, "src", definition.directory);
+
+		let entries: fs.Dirent[];
+		try {
+			entries = await fs.promises.readdir(directory, { withFileTypes: true });
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+				continue;
+			}
+			throw error;
+		}
+
+		entries.sort((a, b) => a.name.localeCompare(b.name));
+
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".ts") || entry.name.endsWith(".d.ts")) {
+				continue;
+			}
+
+			discovered.push({
+				type: definition.type,
+				tag: definition.tag,
+				key: entry.name.slice(0, -".ts".length),
+				sourcePath: path.join("src", definition.directory, entry.name),
+			});
+		}
+	}
+
+	return discovered;
+}

package/src/alpha/cli/emit-manifest.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { assertJsonSafe } from "./emit-manifest.js";
+
+describe("assertJsonSafe", () => {
+	it("accepts plain JSON values, including nested objects and arrays", () => {
+		expect(() =>
+			assertJsonSafe(
+				{
+					name: "sync",
+					count: 3,
+					enabled: true,
+					missing: null,
+					tags: ["a", "b"],
+					nested: { list: [1, 2, { deep: "value" }] },
+				},
+				"config",
+			),
+		).not.toThrow();
+	});
+
+	it("omits undefined-valued object properties without throwing", () => {
+		expect(() => assertJsonSafe({ a: undefined, b: 1 }, "config")).not.toThrow();
+	});
+
+	it.each([
+		["function", { a: () => {} }],
+		["symbol", { a: Symbol("x") }],
+		["bigint", { a: 1n }],
+		["NaN", { a: Number.NaN }],
+		["Infinity", { a: Number.POSITIVE_INFINITY }],
+		["Map", { a: new Map() }],
+		["Set", { a: new Set() }],
+		["Date", { a: new Date(0) }],
+		["undefined array element", { a: [undefined] }],
+	])("throws for non-serializable %s", (_label, value) => {
+		expect(() => assertJsonSafe(value, "config")).toThrow(/not JSON-serializable/);
+	});
+
+	it("includes the path to the offending value in the error", () => {
+		expect(() => assertJsonSafe({ outer: { inner: () => {} } }, "src/syncs/foo.ts config")).toThrow(
+			"src/syncs/foo.ts config.outer.inner",
+		);
+	});
+});

package/src/alpha/cli/emit-manifest.ts

@@ -0,0 +1,409 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+import { Ajv } from "ajv";
+
+import type { DatabaseManifestEntry, PacerManifestEntry, WorkerManifest } from "../manifest.js";
+import { clearRegisteredPacers, registeredPacers } from "../pacer.js";
+import type { DiscoveredCapability } from "./discover.js";
+
+const SDK_VERSION = (() => {
+	const require = createRequire(import.meta.url);
+	const packageJson: unknown = require("../../../package.json");
+
+	if (
+		typeof packageJson !== "object" ||
+		packageJson === null ||
+		!("version" in packageJson) ||
+		typeof packageJson.version !== "string"
+	) {
+		throw new Error("Failed to read SDK version from package.json");
+	}
+
+	return packageJson.version;
+})();
+
+const MANIFEST_SCHEMA = {
+	type: "object",
+	properties: {
+		sdkVersion: { type: "string" },
+		databases: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
+		pacers: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
+		capabilities: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					type: { type: "string" },
+					key: { type: "string" },
+					config: {},
+				},
+				required: ["type", "key", "config"],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ["sdkVersion", "databases", "pacers", "capabilities"],
+	additionalProperties: false,
+} as const;
+
+type TaggedObject = { _tag: string; config: Record<string, unknown> };
+
+type DatabaseObject = TaggedObject & { name: string };
+
+/**
+ * Collects the databases reachable from capability configs, deduplicating
+ * by object identity within the build and by `name` across deploys.
+ */
+class DatabaseCollector {
+	/** Database object → name, for identity-based dedup. */
+	#names = new Map<unknown, string>();
+	/** Name → database object, for detecting distinct objects sharing a name. */
+	#byName = new Map<string, DatabaseObject>();
+	/** Names in first-seen order, for deterministic manifest output. */
+	#order: string[] = [];
+
+	/**
+	 * Register a database and, transitively, every database its schema's
+	 * relation properties reference. Returns the database's name.
+	 */
+	collect(value: unknown, referencedFrom: string): string {
+		const known = this.#names.get(value);
+		if (known !== undefined) {
+			return known;
+		}
+
+		const database = asDatabase(value);
+		if (!database) {
+			throw new Error(`${referencedFrom}: expected a database created with createDatabase(...)`);
+		}
+
+		const existing = this.#byName.get(database.name);
+		if (existing && existing !== value) {
+			throw new Error(
+				`Two distinct databases are named "${database.name}" (found via ${referencedFrom}). ` +
+					`A name identifies one database — share a single createDatabase(...) instance ` +
+					`via import instead of declaring it twice`,
+			);
+		}
+
+		this.#names.set(value, database.name);
+		this.#byName.set(database.name, database);
+		this.#order.push(database.name);
+
+		validatePrimaryKey(database);
+
+		// Relations pull their target databases into the manifest even when
+		// no sync writes to them directly.
+		for (const [propertyName, property] of schemaProperties(database)) {
+			if (isRelationProperty(property)) {
+				this.collect(
+					property.database,
+					`relation property "${propertyName}" of database "${database.name}"`,
+				);
+			}
+		}
+
+		return database.name;
+	}
+
+	/** Manifest entries with relation references resolved to names. */
+	entries(): DatabaseManifestEntry[] {
+		return this.#order.map((name) => {
+			const database = this.#byName.get(name)!;
+			const resolvedProperties: Record<string, unknown> = {};
+
+			for (const [propertyName, property] of schemaProperties(database)) {
+				if (isRelationProperty(property)) {
+					const { database: target, ...rest } = property;
+					resolvedProperties[propertyName] = {
+						...rest,
+						relatedDatabaseKey: this.#names.get(target)!,
+					};
+				} else {
+					resolvedProperties[propertyName] = property;
+				}
+			}
+
+			const schema = database.config.schema as Record<string, unknown>;
+			return {
+				key: name,
+				config: { ...database.config, schema: { ...schema, properties: resolvedProperties } },
+			};
+		});
+	}
+}
+
+/**
+ * Extract the worker manifest from a built bundle.
+ *
+ * This is the one place the build executes worker code: the bundle is
+ * imported once (running module top-level code only — handlers are never
+ * invoked), each discovered capability's default export is validated
+ * against the tag its directory requires, and the handler-free configs are
+ * assembled into the manifest.
+ *
+ * Resources are not discovered from the filesystem. Databases are collected
+ * by walking capability configs — a sync's `database`, and transitively any
+ * database referenced by a schema's `relation` properties. Pacers register
+ * themselves when created, so importing the bundle populates the pacer
+ * registry as a side effect. Within a build, resources deduplicate by
+ * object identity; across deploys their `name` is the stable key. Two
+ * distinct resource objects sharing a name fail the build.
+ */
+export async function extractManifest(
+	bundlePath: string,
+	capabilities: readonly DiscoveredCapability[],
+): Promise<WorkerManifest> {
+	// Importing the bundle registers every pacer created at module top level;
+	// clear first so repeated builds in one process don't see stale entries.
+	clearRegisteredPacers();
+	const bundle = await importBundle(bundlePath);
+	const pacerEntries: PacerManifestEntry[] = registeredPacers().map((pacer) => ({
+		key: pacer.name,
+		config: pacer.config,
+	}));
+
+	const capabilityRegistry = getCapabilityRegistry(bundle);
+	const databaseCollector = new DatabaseCollector();
+
+	const capabilityEntries = capabilities.map((capability) => {
+		const value = capabilityRegistry[capability.type]?.[capability.key];
+		const tagged = asTagged(value);
+
+		if (!tagged) {
+			throw new Error(`${capability.sourcePath}: default export is not a capability`);
+		}
+
+		if (tagged._tag !== capability.tag) {
+			throw new Error(
+				`${capability.sourcePath}: default export is not a ${capability.type} — ` +
+					`files under this directory must default-export create${capitalize(capability.type)}(...)`,
+			);
+		}
+
+		const config = { ...tagged.config };
+
+		if (capability.type === "sync") {
+			config.databaseKey = databaseCollector.collect(config.database, capability.sourcePath);
+			config.database = undefined;
+		}
+
+		// Verify after the sync transform above swaps the non-plain database
+		// object out for its string key.
+		assertJsonSafe(config, `${capability.sourcePath} config`);
+
+		return { type: capability.type, key: capability.key, config };
+	});
+
+	const databaseEntries = databaseCollector.entries();
+	for (const entry of databaseEntries) {
+		assertJsonSafe(entry.config, `database "${entry.key}" config`);
+	}
+	for (const entry of pacerEntries) {
+		assertJsonSafe(entry.config, `pacer "${entry.key}" config`);
+	}
+
+	// Every config was verified JSON-safe above, so this round-trip is lossless;
+	// it normalizes the already-validated values into plain JSON before the
+	// manifest-structure check below.
+	const manifest: unknown = JSON.parse(
+		JSON.stringify({
+			sdkVersion: SDK_VERSION,
+			databases: databaseEntries,
+			pacers: pacerEntries,
+			capabilities: capabilityEntries,
+		} satisfies WorkerManifest),
+	);
+
+	const ajv = new Ajv();
+	if (!ajv.validate(MANIFEST_SCHEMA, manifest)) {
+		throw new Error(`Generated manifest is invalid: ${ajv.errorsText(ajv.errors)}`);
+	}
+
+	return manifest as WorkerManifest;
+}
+
+function schemaProperties(database: DatabaseObject): [string, unknown][] {
+	const schema = database.config.schema;
+	if (
+		typeof schema !== "object" ||
+		schema === null ||
+		!("properties" in schema) ||
+		typeof schema.properties !== "object" ||
+		schema.properties === null
+	) {
+		throw new Error(`Database "${database.name}" has no schema.properties`);
+	}
+
+	return Object.entries(schema.properties);
+}
+
+function validatePrimaryKey(database: DatabaseObject): void {
+	const propertyNames = schemaProperties(database).map(([name]) => name);
+	const primaryKey = database.config.primaryKey;
+
+	if (typeof primaryKey !== "string" || !propertyNames.includes(primaryKey)) {
+		throw new Error(
+			`Database "${database.name}": primaryKey "${String(primaryKey)}" is not a property ` +
+				`in the schema`,
+		);
+	}
+}
+
+function isRelationProperty(property: unknown): property is { database: unknown } {
+	return (
+		typeof property === "object" &&
+		property !== null &&
+		"type" in property &&
+		property.type === "relation" &&
+		"database" in property
+	);
+}
+
+// Node's ESM module cache is keyed by URL and never evicts, so importing
+// the same bundle path twice in one process (tests, watch mode) would
+// return whichever module loaded first: stale code after a rebuild, and —
+// even when the code is unchanged — a cache hit skips re-running module
+// top-level side effects, which manifest extraction depends on (e.g.
+// pacers register themselves at creation). A per-import nonce forces a
+// fresh module instance every time; the abandoned cache entries are
+// negligible for a build process. Irrelevant for a single `notion-workers
+// build`, which imports exactly once.
+let importNonce = 0;
+
+async function importBundle(bundlePath: string): Promise<unknown> {
+	try {
+		return await import(`${pathToFileURL(bundlePath).href}?import=${importNonce++}`);
+	} catch (error) {
+		throw new Error(
+			`Failed to import built worker bundle. Capability modules must be importable ` +
+				`without secrets or network access — check for top-level code that throws.\n` +
+				`Caused by: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+}
+
+function getCapabilityRegistry(
+	bundle: unknown,
+): Record<string, Record<string, unknown> | undefined> {
+	if (
+		typeof bundle !== "object" ||
+		bundle === null ||
+		!("capabilities" in bundle) ||
+		typeof bundle.capabilities !== "object" ||
+		bundle.capabilities === null
+	) {
+		throw new Error(`Built worker bundle does not export a capability registry`);
+	}
+
+	return bundle.capabilities as Record<string, Record<string, unknown> | undefined>;
+}
+
+function asTagged(value: unknown): TaggedObject | undefined {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		"_tag" in value &&
+		typeof value._tag === "string" &&
+		"config" in value &&
+		typeof value.config === "object" &&
+		value.config !== null
+	) {
+		return value as TaggedObject;
+	}
+
+	return undefined;
+}
+
+function asDatabase(value: unknown): DatabaseObject | undefined {
+	const tagged = asTagged(value);
+	if (tagged?._tag === "database" && "name" in tagged && typeof tagged.name === "string") {
+		return tagged as DatabaseObject;
+	}
+
+	return undefined;
+}
+
+function capitalize(value: string): string {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/**
+ * Throw if `value` contains anything `JSON.stringify` would silently drop or
+ * rewrite, so a config that can't round-trip fails the build here rather than
+ * producing a manifest that quietly disagrees with the author's source.
+ *
+ * Rejects functions, symbols, bigints, non-finite numbers, `undefined` array
+ * elements, and non-plain objects (Map, Set, Date, class instances). Allows
+ * null, booleans, finite numbers, strings, plain arrays, and plain objects.
+ * `undefined`-valued object properties are permitted and omitted, mirroring
+ * JSON semantics for unset optional fields.
+ */
+export function assertJsonSafe(value: unknown, path: string): void {
+	const reject = (reason: string): never => {
+		throw new Error(`${path}: not JSON-serializable (${reason})`);
+	};
+
+	switch (typeof value) {
+		case "function":
+			reject("function");
+			break;
+		case "symbol":
+			reject("symbol");
+			break;
+		case "bigint":
+			reject("bigint");
+			break;
+		case "number":
+			if (!Number.isFinite(value)) reject(String(value));
+			return;
+		case "string":
+		case "boolean":
+		case "undefined":
+			return;
+	}
+
+	if (value === null) return;
+
+	if (Array.isArray(value)) {
+		value.forEach((element, index) => {
+			if (element === undefined) reject(`undefined at [${index}]`);
+			assertJsonSafe(element, `${path}[${index}]`);
+		});
+		return;
+	}
+
+	const object = value as { constructor?: { name?: string } };
+	const prototype = Object.getPrototypeOf(object);
+	if (prototype !== null && prototype !== Object.prototype) {
+		reject(object.constructor?.name ?? "non-plain object");
+	}
+
+	for (const [key, property] of Object.entries(object as Record<string, unknown>)) {
+		if (property === undefined) continue;
+		assertJsonSafe(property, `${path}.${key}`);
+	}
+}

package/src/alpha/cli/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import * as path from "node:path";
+
+import { buildWorker } from "./build.js";
+
+const USAGE = `Usage: notion-workers <command>
+
+Commands:
+  build    Build the worker in the current directory
+`;
+
+async function main(): Promise<void> {
+	const command = process.argv[2];
+
+	switch (command) {
+		case "build": {
+			const projectRoot = process.cwd();
+			const { manifest, bundlePath, manifestPath } = await buildWorker(projectRoot);
+			const count = manifest.capabilities.length;
+			console.log(
+				`Built ${path.relative(projectRoot, bundlePath)} and ` +
+					`${path.relative(projectRoot, manifestPath)} ` +
+					`(${count} ${count === 1 ? "capability" : "capabilities"})`,
+			);
+			break;
+		}
+		case undefined:
+		case "help":
+		case "--help":
+			console.log(USAGE);
+			break;
+		default:
+			console.error(`Unknown command: ${command}\n\n${USAGE}`);
+			process.exitCode = 1;
+	}
+}
+
+main().catch((error: unknown) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});