@neondatabase/config 0.0.0 → 0.1.0

package/src/lib/diff.test.ts

@@ -1,142 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { diffConfig, type RemoteState } from "./diff.js";
-
-describe("diffConfig", () => {
-	const remote: RemoteState = {
-		projectId: "proj",
-		branch: {
-			id: "br-main",
-			name: "main",
-			isDefault: true,
-			protected: false,
-		},
-		endpoint: {
-			id: "ep",
-			branchId: "br-main",
-			type: "read_write" as const,
-			autoscalingLimitMinCu: 0.25,
-			autoscalingLimitMaxCu: 1,
-			suspendTimeout: "5m",
-		},
-		services: {
-			databaseName: "neondb",
-			authEnabled: false,
-			dataApiEnabled: false,
-		},
-	};
-
-	test("plans service enables", () => {
-		const diff = diffConfig(
-			{ authEnabled: true, dataApiEnabled: true },
-			remote,
-			{ updateExisting: false },
-		);
-		expect(diff.plan.map((p) => p.kind)).toEqual([
-			"enable-auth",
-			"enable-data-api",
-		]);
-	});
-
-	test("reports compute drift unless updateExisting is set", () => {
-		const diff = diffConfig(
-			{
-				authEnabled: false,
-				dataApiEnabled: false,
-				postgres: { computeSettings: { autoscalingLimitMaxCu: 2 } },
-			},
-			remote,
-			{ updateExisting: false },
-		);
-		expect(diff.conflicts[0]).toMatchObject({ field: "computeSettings" });
-	});
-
-	test("plans mutable branch updates with updateExisting", () => {
-		const diff = diffConfig(
-			{ authEnabled: false, dataApiEnabled: false, protected: true },
-			remote,
-			{ updateExisting: true },
-		);
-		expect(diff.plan[0]).toMatchObject({
-			kind: "update-branch-protected",
-			branchId: "br-main",
-		});
-	});
-
-	test("plans preview create + deploy + bucket + ai-gateway when nothing exists", () => {
-		const diff = diffConfig(
-			{
-				authEnabled: false,
-				dataApiEnabled: false,
-				preview: {
-					functions: [
-						{
-							slug: "hello-world",
-							name: "Hello World",
-							source: "./hello.ts",
-							env: {},
-							runtime: "nodejs24",
-							memoryMib: 512,
-						},
-					],
-					buckets: [{ name: "uploads", access: "private" }],
-					aiGatewayEnabled: true,
-				},
-			},
-			{
-				...remote,
-				preview: {
-					buckets: [],
-					functions: [],
-					aiGatewayEnabled: false,
-				},
-			},
-			{ updateExisting: false },
-		);
-		expect(diff.plan.map((p) => p.kind)).toEqual([
-			"create-bucket",
-			"create-function",
-			"deploy-function",
-			"enable-ai-gateway",
-		]);
-	});
-
-	test("skips create-function and skips enable-ai-gateway when already present, but still re-deploys", () => {
-		const diff = diffConfig(
-			{
-				authEnabled: false,
-				dataApiEnabled: false,
-				preview: {
-					functions: [
-						{
-							slug: "hello-world",
-							name: "Hello World",
-							source: "./hello.ts",
-							env: {},
-							runtime: "nodejs24",
-							memoryMib: 512,
-						},
-					],
-					buckets: [{ name: "uploads", access: "private" }],
-					aiGatewayEnabled: true,
-				},
-			},
-			{
-				...remote,
-				preview: {
-					buckets: [{ name: "uploads", accessLevel: "private" }],
-					functions: [
-						{
-							id: "fn-1",
-							slug: "hello-world",
-							name: "Hello World",
-							invocationUrl: "https://x/functions/hello-world",
-						},
-					],
-					aiGatewayEnabled: true,
-				},
-			},
-			{ updateExisting: false },
-		);
-		expect(diff.plan.map((p) => p.kind)).toEqual(["deploy-function"]);
-	});
-});

package/src/lib/diff.ts

@@ -1,391 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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);
-		}
-	});
-});