@neondatabase/config 0.0.0

package/src/lib/diff.ts

@@ -0,0 +1,391 @@
+import type {
+	NeonBranchSnapshot,
+	NeonBucketSnapshot,
+	NeonEndpointSnapshot,
+	NeonFunctionSnapshot,
+} from "./neon-api.js";
+import type {
+	BucketAccessLevel,
+	ComputeSettings,
+	ConflictReport,
+	ResolvedBranchConfig,
+	ResolvedFunctionConfig,
+} from "./types.js";
+
+/**
+ * A planned action to perform a single mutation against the Neon API. The diff engine
+ * produces a list of these for `pushConfig` to execute (or report).
+ */
+export type PlanStep =
+	| {
+			kind: "update-branch-ttl";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			expiresAt: string | null;
+	  }
+	| {
+			kind: "update-branch-protected";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			protected: boolean;
+	  }
+	| {
+			kind: "update-endpoint";
+			projectId: string;
+			branchName: string;
+			endpointId: string;
+			settings: ComputeSettings;
+	  }
+	| {
+			kind: "enable-auth";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			databaseName?: string;
+	  }
+	| {
+			kind: "enable-data-api";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			databaseName: string;
+	  }
+	| {
+			kind: "create-bucket";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			bucketName: string;
+			accessLevel: BucketAccessLevel;
+	  }
+	| {
+			kind: "create-function";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			fn: ResolvedFunctionConfig;
+	  }
+	| {
+			/**
+			 * Deploy (or re-deploy) code to a function. Always planned for every desired
+			 * function — deployments are versioned and the newest becomes active, so a push
+			 * ships the current source each time. `functionExists` tells `pushConfig` whether
+			 * it must create the function first (covered by a preceding `create-function` step).
+			 */
+			kind: "deploy-function";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+			fn: ResolvedFunctionConfig;
+	  }
+	| {
+			kind: "enable-ai-gateway";
+			projectId: string;
+			branchId: string;
+			branchName: string;
+	  };
+
+export interface RemoteServiceState {
+	databaseName: string;
+	authEnabled: boolean;
+	dataApiEnabled: boolean;
+}
+
+/**
+ * Snapshot of the branch's current Preview-feature state. Absent (`undefined`) when the
+ * policy has no `preview` block — `pushConfig` only fetches this when needed.
+ */
+export interface RemotePreviewState {
+	buckets: NeonBucketSnapshot[];
+	functions: NeonFunctionSnapshot[];
+	aiGatewayEnabled: boolean;
+}
+
+export interface RemoteState {
+	projectId: string;
+	branch: NeonBranchSnapshot;
+	endpoint?: NeonEndpointSnapshot;
+	services: RemoteServiceState;
+	preview?: RemotePreviewState;
+}
+
+export interface DiffOptions {
+	/**
+	 * Apply mutable drift on the selected branch as plan steps instead of conflicts.
+	 * Default: `false`.
+	 */
+	updateExisting: boolean;
+}
+
+export interface DiffResult {
+	plan: PlanStep[];
+	conflicts: ConflictReport[];
+}
+
+/**
+ * Diff desired branch policy against the selected remote branch. Pure function.
+ */
+export function diffConfig(
+	config: ResolvedBranchConfig,
+	remote: RemoteState,
+	options: DiffOptions,
+): DiffResult {
+	const conflicts: ConflictReport[] = [];
+	const plan: PlanStep[] = [];
+	diffBranchConfig({ config, remote, options, plan, conflicts });
+	diffServices({ config, remote, plan });
+	diffPreview({ config, remote, plan });
+	return { plan, conflicts };
+}
+
+/**
+ * Plan Preview features (functions, buckets, AI Gateway). Like {@link diffServices}, this
+ * is **additive**: it creates desired buckets/functions and enables the AI Gateway, but
+ * never deletes buckets/functions or disables the gateway. Teardown is destructive, so it
+ * stays explicit/manual — matching the existing auth / dataApi behaviour.
+ *
+ * Functions are always (re-)deployed: deployments are versioned and the newest becomes
+ * active, so each push ships the current source. A `create-function` step precedes the
+ * `deploy-function` step when the function does not yet exist remotely.
+ */
+function diffPreview(args: {
+	config: ResolvedBranchConfig;
+	remote: RemoteState;
+	plan: PlanStep[];
+}): void {
+	const { config, remote, plan } = args;
+	const preview = config.preview;
+	if (!preview) return;
+	// `remote.preview` is only fetched when the policy has a preview block; treat a missing
+	// snapshot as "nothing exists yet" so the diff is still well-defined.
+	const state: RemotePreviewState = remote.preview ?? {
+		buckets: [],
+		functions: [],
+		aiGatewayEnabled: false,
+	};
+
+	for (const bucket of preview.buckets) {
+		if (state.buckets.some((b) => b.name === bucket.name)) continue;
+		plan.push({
+			kind: "create-bucket",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			bucketName: bucket.name,
+			accessLevel: bucket.access,
+		});
+	}
+
+	for (const fn of preview.functions) {
+		const exists = state.functions.some((f) => f.slug === fn.slug);
+		if (!exists) {
+			plan.push({
+				kind: "create-function",
+				projectId: remote.projectId,
+				branchId: remote.branch.id,
+				branchName: remote.branch.name,
+				fn,
+			});
+		}
+		plan.push({
+			kind: "deploy-function",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			fn,
+		});
+	}
+
+	if (preview.aiGatewayEnabled && !state.aiGatewayEnabled) {
+		plan.push({
+			kind: "enable-ai-gateway",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+		});
+	}
+}
+
+/**
+ * Plan additive branch-scoped integrations. Disabling remains explicit/manual because
+ * teardown is destructive.
+ */
+function diffServices(args: {
+	config: ResolvedBranchConfig;
+	remote: RemoteState;
+	plan: PlanStep[];
+}): void {
+	const { config, remote, plan } = args;
+	const state = remote.services;
+	if (config.authEnabled && !state.authEnabled) {
+		const step: PlanStep = {
+			kind: "enable-auth",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+		};
+		if (state.databaseName) step.databaseName = state.databaseName;
+		plan.push(step);
+	}
+	if (config.dataApiEnabled && !state.dataApiEnabled) {
+		plan.push({
+			kind: "enable-data-api",
+			projectId: remote.projectId,
+			branchId: remote.branch.id,
+			branchName: remote.branch.name,
+			databaseName: state.databaseName,
+		});
+	}
+}
+
+interface BranchConfigArgs {
+	config: ResolvedBranchConfig;
+	remote: RemoteState;
+	options: DiffOptions;
+	plan: PlanStep[];
+	conflicts: ConflictReport[];
+}
+
+function diffBranchConfig(args: BranchConfigArgs): void {
+	const { config, remote, options, plan, conflicts } = args;
+	const branchName = remote.branch.name;
+	const computeSettings = config.postgres?.computeSettings;
+
+	if (computeSettings) {
+		const endpoint = remote.endpoint;
+		if (!endpoint) {
+			conflicts.push({
+				kind: "branch",
+				identifier: branchName,
+				field: "endpoint",
+				current: undefined,
+				desired: computeSettings,
+				reason: "Branch has no read-write endpoint; cannot apply compute settings.",
+			});
+		} else {
+			const drift = computeDriftBetween(computeSettings, endpoint);
+			if (drift) {
+				if (options.updateExisting) {
+					plan.push({
+						kind: "update-endpoint",
+						projectId: remote.projectId,
+						branchName,
+						endpointId: endpoint.id,
+						settings: computeSettings,
+					});
+				} else {
+					conflicts.push({
+						kind: "branch",
+						identifier: branchName,
+						field: "computeSettings",
+						current: drift.current,
+						desired: drift.desired,
+						reason: "Existing branch has different compute settings. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.",
+					});
+				}
+			}
+		}
+	}
+
+	if (
+		config.protected !== undefined &&
+		config.protected !== remote.branch.protected
+	) {
+		if (options.updateExisting) {
+			plan.push({
+				kind: "update-branch-protected",
+				projectId: remote.projectId,
+				branchId: remote.branch.id,
+				branchName,
+				protected: config.protected,
+			});
+		} else {
+			conflicts.push({
+				kind: "branch",
+				identifier: branchName,
+				field: "protected",
+				current: remote.branch.protected,
+				desired: config.protected,
+				reason: "Existing branch has a different `protected` flag. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.",
+			});
+		}
+	}
+
+	if (config.ttlSeconds !== undefined) {
+		const current = remote.branch.expiresAt
+			? Math.max(
+					0,
+					Math.round(
+						(Date.parse(remote.branch.expiresAt) - Date.now()) /
+							1000,
+					),
+				)
+			: undefined;
+		if (
+			current === undefined ||
+			Math.abs(current - config.ttlSeconds) > 30
+		) {
+			const expiresAt = new Date(
+				Date.now() + config.ttlSeconds * 1000,
+			).toISOString();
+			if (options.updateExisting) {
+				plan.push({
+					kind: "update-branch-ttl",
+					projectId: remote.projectId,
+					branchId: remote.branch.id,
+					branchName,
+					expiresAt,
+				});
+			} else {
+				conflicts.push({
+					kind: "branch",
+					identifier: branchName,
+					field: "ttl",
+					current: remote.branch.expiresAt,
+					desired: expiresAt,
+					reason: "Existing branch has a different TTL. Pass `updateExisting: true` (SDK) or `--update-existing` (CLI) to apply.",
+				});
+			}
+		}
+	}
+}
+
+function computeDriftBetween(
+	desired: ComputeSettings,
+	endpoint: NeonEndpointSnapshot,
+): {
+	current: Partial<ComputeSettings>;
+	desired: Partial<ComputeSettings>;
+} | null {
+	const currentDrift: Partial<ComputeSettings> = {};
+	const desiredDrift: Partial<ComputeSettings> = {};
+	let drift = false;
+
+	if (
+		desired.autoscalingLimitMinCu !== undefined &&
+		desired.autoscalingLimitMinCu !== endpoint.autoscalingLimitMinCu
+	) {
+		currentDrift.autoscalingLimitMinCu = endpoint.autoscalingLimitMinCu;
+		desiredDrift.autoscalingLimitMinCu = desired.autoscalingLimitMinCu;
+		drift = true;
+	}
+	if (
+		desired.autoscalingLimitMaxCu !== undefined &&
+		desired.autoscalingLimitMaxCu !== endpoint.autoscalingLimitMaxCu
+	) {
+		currentDrift.autoscalingLimitMaxCu = endpoint.autoscalingLimitMaxCu;
+		desiredDrift.autoscalingLimitMaxCu = desired.autoscalingLimitMaxCu;
+		drift = true;
+	}
+	if (
+		desired.suspendTimeout !== undefined &&
+		desired.suspendTimeout !== endpoint.suspendTimeout
+	) {
+		currentDrift.suspendTimeout = endpoint.suspendTimeout;
+		desiredDrift.suspendTimeout = desired.suspendTimeout;
+		drift = true;
+	}
+	return drift ? { current: currentDrift, desired: desiredDrift } : null;
+}

package/src/lib/duration.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "vitest";
+import { formatDurationSeconds, parseDuration } from "./duration.js";
+
+describe("parseDuration", () => {
+	test.each([
+		["30s", 30],
+		["5m", 300],
+		["1h", 3600],
+		["2h", 7200],
+		["1d", 86_400],
+		["7d", 604_800],
+		["2w", 1_209_600],
+		["1W", 604_800],
+		["3600", 3600],
+	])("parses %s as %d seconds", (input, expected) => {
+		const result = parseDuration(input);
+		expect(result).toEqual({ seconds: expected });
+	});
+
+	test("accepts integer numbers", () => {
+		expect(parseDuration(60)).toEqual({ seconds: 60 });
+	});
+
+	test.each([
+		["", "duration string is empty"],
+		["   ", "duration string is empty"],
+		["abc", 'invalid duration "abc"'],
+		["1h30m", 'invalid duration "1h30m"'],
+		["0", 'must be > 0, got "0"'],
+		["0s", 'must be > 0, got "0s"'],
+		["-5", 'invalid duration "-5"'],
+	])("rejects %s", (input, expectedErrorFragment) => {
+		const result = parseDuration(input);
+		expect(result).toHaveProperty("error");
+		expect((result as { error: string }).error).toContain(
+			expectedErrorFragment,
+		);
+	});
+
+	test("rejects non-integer numbers", () => {
+		expect(parseDuration(1.5)).toEqual({
+			error: expect.stringContaining("must be an integer"),
+		});
+	});
+
+	test("rejects zero and negative numbers", () => {
+		expect(parseDuration(0)).toEqual({
+			error: expect.stringContaining("must be > 0"),
+		});
+		expect(parseDuration(-1)).toEqual({
+			error: expect.stringContaining("must be > 0"),
+		});
+	});
+
+	test("rejects non-finite numbers", () => {
+		expect(parseDuration(Number.POSITIVE_INFINITY)).toEqual({
+			error: expect.stringContaining("not a finite number"),
+		});
+		expect(parseDuration(Number.NaN)).toEqual({
+			error: expect.stringContaining("not a finite number"),
+		});
+	});
+});
+
+describe("formatDurationSeconds", () => {
+	test.each([
+		[30, "30s"],
+		[60, "1m"],
+		[3600, "1h"],
+		[86_400, "1d"],
+		[604_800, "1w"],
+		[1_209_600, "2w"],
+		[7200, "2h"],
+		[120, "2m"],
+		[90, "90s"], // doesn't fit a clean minute boundary above 60 → falls back to seconds
+	])("formats %d seconds as %s", (input, expected) => {
+		expect(formatDurationSeconds(input)).toBe(expected);
+	});
+
+	test("throws on non-positive input", () => {
+		expect(() => formatDurationSeconds(0)).toThrow(RangeError);
+		expect(() => formatDurationSeconds(-1)).toThrow(RangeError);
+	});
+
+	test("round-trips parseDuration → formatDurationSeconds in canonical form", () => {
+		// `7d` and `1w` both represent 604_800 seconds; the formatter chooses the largest
+		// clean unit, so the canonical form is `1w`. This documents the chosen tie-break.
+		const cases: Array<[string, string]> = [
+			["30s", "30s"],
+			["5m", "5m"],
+			["1h", "1h"],
+			["2h", "2h"],
+			["1d", "1d"],
+			["7d", "1w"],
+			["1w", "1w"],
+			["2w", "2w"],
+		];
+		for (const [input, canonical] of cases) {
+			const parsed = parseDuration(input);
+			if (!("seconds" in parsed))
+				throw new Error(`failed to parse ${input}`);
+			expect(formatDurationSeconds(parsed.seconds)).toBe(canonical);
+		}
+	});
+});

package/src/lib/duration.ts

@@ -0,0 +1,147 @@
+/**
+ * Parse a TTL value into whole seconds.
+ *
+ * Accepted formats:
+ * - a positive finite number → interpreted as seconds (must be an integer)
+ * - a positive integer string ("3600") → seconds
+ * - `<number><unit>` where unit is one of `s`, `m`, `h`, `d`, `w` (e.g. `30s`, `5m`, `1h`, `7d`, `2w`)
+ *
+ * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+ */
+export function parseDuration(
+	input: string | number,
+): { seconds: number } | { error: string } {
+	if (typeof input === "number") {
+		if (!Number.isFinite(input))
+			return { error: `not a finite number: ${input}` };
+		if (!Number.isInteger(input))
+			return {
+				error: `must be an integer when passed as number: ${input}`,
+			};
+		if (input <= 0) return { error: `must be > 0, got ${input}` };
+		return { seconds: input };
+	}
+
+	const trimmed = input.trim();
+	if (trimmed === "") return { error: "duration string is empty" };
+
+	const numericMatch = /^(\d+)$/.exec(trimmed);
+	if (numericMatch) {
+		const n = Number(numericMatch[1]);
+		if (n <= 0) return { error: `must be > 0, got "${trimmed}"` };
+		return { seconds: n };
+	}
+
+	const unitMatch = /^(\d+)([smhdw])$/i.exec(trimmed);
+	if (!unitMatch) {
+		return {
+			error: `invalid duration "${input}"; expected a number followed by one of: s, m, h, d, w (e.g. "30s", "1h", "7d")`,
+		};
+	}
+
+	const value = Number(unitMatch[1]);
+	const unit = unitMatch[2].toLowerCase() as "s" | "m" | "h" | "d" | "w";
+	if (value <= 0) return { error: `must be > 0, got "${trimmed}"` };
+
+	const seconds = value * UNIT_SECONDS[unit];
+	return { seconds };
+}
+
+const UNIT_SECONDS = {
+	s: 1,
+	m: 60,
+	h: 60 * 60,
+	d: 24 * 60 * 60,
+	w: 7 * 24 * 60 * 60,
+} as const;
+
+/**
+ * Render a TTL in seconds back to the canonical "<n><unit>" form. Used for round-trip
+ * serialization when {@link pullConfig} emits a TTL value (it always falls back to seconds
+ * when no clean unit boundary matches).
+ */
+export function formatDurationSeconds(totalSeconds: number): string {
+	if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) {
+		throw new RangeError(
+			`formatDurationSeconds expected a positive finite number, got ${totalSeconds}`,
+		);
+	}
+	const candidates = [
+		["w", UNIT_SECONDS.w],
+		["d", UNIT_SECONDS.d],
+		["h", UNIT_SECONDS.h],
+		["m", UNIT_SECONDS.m],
+	] as const;
+	for (const [unit, perUnit] of candidates) {
+		if (totalSeconds % perUnit === 0) {
+			return `${totalSeconds / perUnit}${unit}`;
+		}
+	}
+	return `${totalSeconds}s`;
+}
+
+/**
+ * Parse a suspend timeout value into seconds for the Neon API.
+ *
+ * Accepted formats:
+ * - `false` → -1 (never suspend)
+ * - `undefined` → 0 (use platform default)
+ * - duration string → parsed seconds ("5m", "1h", "7d")
+ * - number → validated seconds (must be 60-604800 or -1/0)
+ *
+ * Returns `{ seconds }` on success or `{ error }` on failure. Pure function — never throws.
+ */
+export function parseSuspendTimeout(
+	input: false | string | number | undefined,
+): { seconds: number } | { error: string } {
+	// false means "never suspend"
+	if (input === false) return { seconds: -1 };
+
+	// undefined means "use platform default"
+	if (input === undefined) return { seconds: 0 };
+
+	// If it's a number, validate the range
+	if (typeof input === "number") {
+		if (!Number.isFinite(input))
+			return { error: `not a finite number: ${input}` };
+		if (!Number.isInteger(input))
+			return { error: `must be an integer: ${input}` };
+
+		// Allow special values: -1 (never), 0 (default)
+		if (input === -1 || input === 0) return { seconds: input };
+
+		// Validate range for custom timeout: 60s (1 min) to 604800s (1 week)
+		if (input < 60 || input > 604_800) {
+			return {
+				error: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), got ${input}`,
+			};
+		}
+		return { seconds: input };
+	}
+
+	// Parse duration string
+	const result = parseDuration(input);
+	if ("error" in result) return result;
+
+	// Validate the parsed duration is in the valid range
+	const { seconds } = result;
+	if (seconds < 60 || seconds > 604_800) {
+		return {
+			error: `suspend timeout must be between 60 and 604800 seconds (1 minute to 1 week), "${input}" = ${seconds}s`,
+		};
+	}
+
+	return { seconds };
+}
+
+/**
+ * Format a suspend timeout value from API seconds back to the user-facing type.
+ * Returns `false` for -1 (never suspend), `undefined` for 0 (default), or a duration string.
+ */
+export function formatSuspendTimeout(
+	seconds: number,
+): false | string | undefined {
+	if (seconds === -1) return false; // never suspend
+	if (seconds === 0) return undefined; // platform default
+	return formatDurationSeconds(seconds);
+}

package/src/lib/errors.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "vitest";
+import { ConfigValidationError, PushConflictError } from "./errors.js";
+
+describe("ConfigValidationError", () => {
+	test("formats issues", () => {
+		const err = new ConfigValidationError(["ttl: invalid duration"]);
+		expect(err.message).toContain("ttl: invalid duration");
+	});
+});
+
+describe("PushConflictError", () => {
+	test("formats branch conflicts with updateExisting hint", () => {
+		const err = new PushConflictError([
+			{
+				kind: "branch",
+				identifier: "main",
+				field: "protected",
+				current: false,
+				desired: true,
+				reason: "different protected flag",
+			},
+		]);
+		expect(err.message).toContain("[branch:main] protected");
+		expect(err.message).toContain("--update-existing");
+	});
+});