@neondatabase/config 0.0.0

package/src/lib/schema.ts

@@ -0,0 +1,252 @@
+import { z } from "zod";
+import { parseDuration, parseSuspendTimeout } from "./duration.js";
+import { isWildcardPattern, validatePattern } from "./patterns.js";
+
+/**
+ * Zod schema for {@link import("./types.js").ComputeSettings}.
+ *
+ * - CU values must be one of: 0.25, 0.5, 1, 2, 4, 8
+ * - `suspendTimeout` can be:
+ *   - `false` (never suspend)
+ *   - duration string like "5m", "1h" (must be 60s-604800s when parsed)
+ *   - number in seconds (60-604800, or -1/0 for special values)
+ *   - `undefined` (use platform default)
+ *
+ * Cross-field invariants (min <= max) are enforced via `superRefine`.
+ */
+export const computeSettingsSchema = z
+	.strictObject({
+		autoscalingLimitMinCu: z
+			.union([
+				z.literal(0.25),
+				z.literal(0.5),
+				z.literal(1),
+				z.literal(2),
+				z.literal(4),
+				z.literal(8),
+			])
+			.optional(),
+		autoscalingLimitMaxCu: z
+			.union([
+				z.literal(0.25),
+				z.literal(0.5),
+				z.literal(1),
+				z.literal(2),
+				z.literal(4),
+				z.literal(8),
+			])
+			.optional(),
+		suspendTimeout: z
+			.union([z.literal(false), z.string(), z.number()])
+			.optional()
+			.superRefine((value, ctx) => {
+				if (value === undefined) return; // undefined is valid (use platform default)
+				const result = parseSuspendTimeout(value);
+				if ("error" in result) {
+					ctx.addIssue({
+						code: "custom",
+						message: result.error,
+					});
+				}
+			}),
+	})
+	.superRefine((settings, ctx) => {
+		const { autoscalingLimitMinCu: min, autoscalingLimitMaxCu: max } =
+			settings;
+		if (min !== undefined && max !== undefined && min > max) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["autoscalingLimitMinCu"],
+				message: `autoscalingLimitMinCu (${min}) must be <= autoscalingLimitMaxCu (${max})`,
+			});
+		}
+	});
+
+export const serviceToggleSchema = z.strictObject({
+	enabled: z.boolean().optional(),
+});
+
+export const postgresConfigSchema = z.strictObject({
+	computeSettings: computeSettingsSchema.optional(),
+});
+
+/**
+ * Branch-unique function slug. Mirrors the Neon Functions API path-segment rule
+ * (`platform/internal/platform/functions/name.go`): lowercase DNS label, 1–40 chars.
+ */
+const functionSlugSchema = z
+	.string()
+	.regex(
+		/^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/,
+		"function slug must be a lowercase DNS label (1-40 chars, letters/digits/hyphens, no leading/trailing hyphen)",
+	);
+
+/**
+ * Per-function environment map. Every value must be a defined string: a `process.env.X`
+ * that is unset surfaces as `undefined` and is rejected here (rather than silently
+ * shipping `undefined` into the deployment).
+ */
+const functionEnvSchema = z.record(z.string(), z.string());
+
+export const functionConfigSchema = z.strictObject({
+	slug: functionSlugSchema,
+	name: z.string().min(1).max(255),
+	source: z.string().min(1),
+	env: functionEnvSchema.optional(),
+	runtime: z.literal("nodejs24").optional(),
+	memoryMib: z
+		.union([
+			z.literal(256),
+			z.literal(512),
+			z.literal(1024),
+			z.literal(2048),
+			z.literal(4096),
+			z.literal(8192),
+		])
+		.optional(),
+});
+
+export const bucketConfigSchema = z.strictObject({
+	name: z.string().min(1).max(255),
+	access: z
+		.union([z.literal("private"), z.literal("public_read")])
+		.optional(),
+});
+
+export const previewConfigSchema = z
+	.strictObject({
+		functions: z.array(functionConfigSchema).optional(),
+		buckets: z.array(bucketConfigSchema).optional(),
+		aiGateway: serviceToggleSchema.optional(),
+	})
+	.superRefine((preview, ctx) => {
+		assertUnique({
+			ctx,
+			path: ["functions"],
+			items: preview.functions ?? [],
+			key: (fn) => fn.slug,
+			label: "function slug",
+		});
+		assertUnique({
+			ctx,
+			path: ["buckets"],
+			items: preview.buckets ?? [],
+			key: (bucket) => bucket.name,
+			label: "bucket name",
+		});
+	});
+
+/**
+ * Flag duplicate keys within a Preview collection so a typo in two function slugs (or two
+ * buckets) surfaces as a config error rather than the second silently clobbering the first
+ * at apply time.
+ */
+function assertUnique<T>(args: {
+	ctx: z.RefinementCtx;
+	path: (string | number)[];
+	items: T[];
+	key: (item: T) => string;
+	label: string;
+}): void {
+	const { ctx, path, items, key, label } = args;
+	const seen = new Set<string>();
+	items.forEach((item, index) => {
+		const value = key(item);
+		if (seen.has(value)) {
+			ctx.addIssue({
+				code: "custom",
+				path: [...path, index],
+				message: `duplicate ${label}: ${JSON.stringify(value)}`,
+			});
+		}
+		seen.add(value);
+	});
+}
+
+export const branchConfigSchema = z
+	.strictObject({
+		parent: z.string().optional(),
+		protected: z.boolean().optional(),
+		ttl: z
+			.union([z.string(), z.number()])
+			.optional()
+			.superRefine((value, ctx) => {
+				if (value === undefined) return;
+				const result = parseDuration(value);
+				if ("error" in result) {
+					ctx.addIssue({ code: "custom", message: result.error });
+				}
+			}),
+		postgres: postgresConfigSchema.optional(),
+		auth: serviceToggleSchema.optional(),
+		dataApi: serviceToggleSchema.optional(),
+		preview: previewConfigSchema.optional(),
+	})
+	.superRefine((cfg, ctx) => {
+		validateParentReference({
+			ctx,
+			path: ["parent"],
+			parent: cfg.parent,
+		});
+	});
+
+function validateParentReference(args: {
+	ctx: z.RefinementCtx;
+	path: (string | number)[];
+	parent: string | undefined;
+}): void {
+	const { ctx, path, parent } = args;
+	if (parent === undefined) return;
+
+	const patternCheck = validatePattern(parent);
+	if ("error" in patternCheck) {
+		ctx.addIssue({ code: "custom", path, message: patternCheck.error });
+	} else if (isWildcardPattern(parent)) {
+		ctx.addIssue({
+			code: "custom",
+			path,
+			message: `parent must be a concrete branch name (no wildcards), got "${parent}"`,
+		});
+	}
+}
+
+export const configSchema = z.function({
+	input: [z.unknown()],
+	output: z.unknown(),
+});
+
+/**
+ * Convert the structured {@link z.ZodError} produced by `configSchema.safeParse` into the
+ * `string[]` shape used by {@link import("./errors.js").ConfigValidationError}.
+ *
+ * Issue paths are rendered as dot-separated property accesses (`postgres.computeSettings`)
+ * and unknown-key issues from `strictObject` are normalised so the message contains the
+ * substring "unknown key" — keeping pre-zod assertions in test suites and downstream tools
+ * stable.
+ */
+export function formatZodIssues(error: z.ZodError): string[] {
+	return error.issues.map((issue) => {
+		const path = renderPath(issue.path);
+		const message = normaliseIssueMessage(issue);
+		return path ? `${path}: ${message}` : message;
+	});
+}
+
+function renderPath(path: ReadonlyArray<PropertyKey>): string {
+	let out = "";
+	for (const segment of path) {
+		if (typeof segment === "number") out += `[${segment}]`;
+		else if (out === "") out += String(segment);
+		else out += `.${String(segment)}`;
+	}
+	return out;
+}
+
+function normaliseIssueMessage(issue: z.core.$ZodIssue): string {
+	if (issue.code === "unrecognized_keys") {
+		const keys = (issue as z.core.$ZodIssueUnrecognizedKeys).keys ?? [];
+		const formatted = keys.map((k) => JSON.stringify(k)).join(", ");
+		return `unknown key${keys.length === 1 ? "" : "s"}: ${formatted}`;
+	}
+	return issue.message;
+}

package/src/lib/test-utils.ts

@@ -0,0 +1,83 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { vi } from "vitest";
+
+/**
+ * Every Neon env var (and adjacent OS env var) the platform package reads at runtime.
+ * Used by {@link stubCleanNeonEnv} to give each test a deterministic, empty starting
+ * env regardless of the developer's local `~/.config/neonctl`, exported `NEON_*` vars,
+ * or anything else carried over from the parent shell.
+ */
+const NEON_AND_RELATED_ENV_KEYS = [
+	"NEON_API_KEY",
+	"NEON_PROJECT_ID",
+	"NEON_BRANCH_ID",
+	"NEON_ORG_ID",
+	"NEON_AUTH_BASE_URL",
+	"NEON_DATA_API_URL",
+	"DATABASE_URL",
+	"DATABASE_URL_UNPOOLED",
+	"NEONCTL_CONFIG_DIR",
+	"HOME",
+	"USERPROFILE",
+] as const;
+
+/**
+ * Stub every Neon-related env var to `undefined` (so they look unset to the code under
+ * test). Tests can override individual keys with `vi.stubEnv(key, value)` after calling
+ * this. `vitest.config.ts` sets `unstubEnvs: true` so each test's stubs are auto-reset.
+ *
+ * Call this from a `beforeEach` in any test file that touches `process.env`-driven
+ * resolution (api key / context / connection-string env vars).
+ */
+export function stubCleanNeonEnv(): void {
+	for (const key of NEON_AND_RELATED_ENV_KEYS) {
+		// vitest 3.x: passing `undefined` deletes the env var (rather than setting it
+		// to the literal string "undefined") — exactly what we want, because empty
+		// strings would still trip code that reads `env.HOME` to build paths.
+		vi.stubEnv(key, undefined);
+	}
+}
+
+/**
+ * Build a transient project tree under the OS temp directory.
+ *
+ * Returns the absolute root path plus a `cleanup()` that removes the tree. Tests should
+ * call `cleanup()` from an `afterEach`/`afterAll` hook.
+ *
+ * `files` is a flat map of relative paths → contents; intermediate directories are created
+ * automatically. Directories themselves can be created by passing `null` as the value.
+ *
+ * A `.git/HEAD` marker is seeded at the root by default so the platform's upward walkers
+ * (which stop at `.git`) don't escape the synthetic repo and read the developer's real
+ * `~/.neon`. Pass an explicit `.git` entry in `files` to override or position it elsewhere
+ * (e.g. for tests that exercise the boundary behaviour itself).
+ */
+export function makeTempRepo(files: Record<string, string | null>): {
+	root: string;
+	cleanup: () => void;
+} {
+	const root = mkdtempSync(join(tmpdir(), "neon-ts-test-"));
+	const callerSpecifiesGit = Object.keys(files).some(
+		(p) => p === ".git" || p.startsWith(".git/"),
+	);
+	const entries: Array<[string, string | null]> = callerSpecifiesGit
+		? Object.entries(files)
+		: [[".git/HEAD", "ref: refs/heads/main\n"], ...Object.entries(files)];
+	for (const [relPath, contents] of entries) {
+		const abs = join(root, relPath);
+		mkdirSync(dirname(abs), { recursive: true });
+		if (contents !== null) {
+			writeFileSync(abs, contents, "utf-8");
+		} else {
+			mkdirSync(abs, { recursive: true });
+		}
+	}
+	return {
+		root,
+		cleanup: () => {
+			rmSync(root, { recursive: true, force: true });
+		},
+	};
+}

package/src/lib/types.ts

@@ -0,0 +1,268 @@
+/**
+ * Valid Neon Compute Unit values.
+ * Most plans support 0.25, 0.5, 1, 2, 4, 8. Higher values may be available on Business plans.
+ */
+export type ComputeUnit = 0.25 | 0.5 | 1 | 2 | 4 | 8;
+
+/**
+ * Compute settings applied to the read/write endpoint of a branch.
+ *
+ * Mirrors the subset of {@link https://api-docs.neon.tech/reference/getting-started-with-neon-api Neon endpoint}
+ * fields that we expose as IaC primitives. Anything left undefined falls back to the project's
+ * `default_endpoint_settings` (which themselves fall back to Neon platform defaults).
+ */
+export interface ComputeSettings {
+	/**
+	 * Minimum number of Compute Units. Set to 0.25 for true scale-to-zero.
+	 * @example 0.25  // scale-to-zero
+	 * @example 1     // always-on with 1 CU minimum
+	 */
+	autoscalingLimitMinCu?: ComputeUnit;
+	/**
+	 * Maximum number of Compute Units for autoscaling.
+	 * @example 2
+	 * @example 8
+	 */
+	autoscalingLimitMaxCu?: ComputeUnit;
+	/**
+	 * How long to wait before suspending an idle compute.
+	 *
+	 * - `false` — never suspend (always-on compute)
+	 * - `"5m"` — duration string (supports "30s", "5m", "1h", "7d", etc)
+	 * - `300` — custom timeout in seconds (60-604800)
+	 * - `undefined` — use Neon platform default (currently 300s / 5 minutes)
+	 *
+	 * @example false       // never suspend
+	 * @example "5m"        // 5 minutes
+	 * @example "1h"        // 1 hour
+	 * @example 300         // 5 minutes in seconds
+	 */
+	suspendTimeout?: false | "5m" | "1h" | string | number;
+}
+
+/**
+ * Read-only descriptor of the branch a {@link Config} policy is being evaluated for — the
+ * `branch` argument passed to your `defineConfig((branch) => …)` callback. It describes
+ * **which** branch this invocation decides for; it is not a live branch handle and must not
+ * be mutated. Switch on its fields and return the desired {@link BranchConfig}.
+ */
+export interface BranchTarget {
+	/** Branch name being evaluated. For `branch dev`, this is the generated branch name. */
+	name: string;
+	/** Neon branch id when the branch already exists. Undefined during pre-create eval. */
+	id?: string;
+	/** Whether this branch already exists on Neon. */
+	exists: boolean;
+	/** Parent branch id from Neon when known. */
+	parentId?: string;
+	/** Whether Neon marks this branch as the project default. */
+	isDefault?: boolean;
+	/** Whether Neon currently marks this branch protected. */
+	isProtected?: boolean;
+	/** Current expiration timestamp from Neon, when set. */
+	expiresAt?: string;
+}
+
+export interface ServiceToggle {
+	/** Defaults to `true` when the service namespace is present. Set `false` to opt out. */
+	enabled?: boolean;
+}
+
+export interface PostgresConfig {
+	computeSettings?: ComputeSettings;
+}
+
+/**
+ * Supported function runtimes. Mirrors the Neon Functions deploy API `runtime` enum.
+ * Only `nodejs24` exists today; kept as a union so adding runtimes later is a
+ * non-breaking, type-checked change.
+ */
+export type FunctionRuntime = "nodejs24";
+
+/**
+ * Memory sizes (MiB) accepted by the Neon Functions deploy API. Mirrors the
+ * `memory_mib` enum in the spec.
+ */
+export type FunctionMemoryMib = 256 | 512 | 1024 | 2048 | 4096 | 8192;
+
+/**
+ * A single Neon Function deployed to a branch (Preview feature).
+ *
+ * A function is invoked like a Cloudflare/Vercel handler — its source module
+ * `export default { fetch }` or `export async function handler(req): Response`. The
+ * `source` path is bundled (esbuild) and uploaded as a deployment; the newest
+ * deployment becomes active.
+ */
+export interface FunctionConfig {
+	/**
+	 * Branch-unique, lowercase DNS-label used as the path segment in the function's
+	 * invocation URL. Immutable once created. 1–40 chars, `^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$`.
+	 * @example "hello-world"
+	 */
+	slug: string;
+	/** Free-form display name. @example "Hello World" */
+	name: string;
+	/**
+	 * Path to the function's entry module, **relative to `neon.ts`** (or absolute). The
+	 * module's default export (`{ fetch }`) or `handler` export is the function entry. This
+	 * path is resolved against the loaded `neon.ts` location and bundled with esbuild at
+	 * deploy time.
+	 *
+	 * We require a string path rather than an imported handler because a JS function value
+	 * carries no reference back to its source file, so esbuild has nothing to bundle from.
+	 * @example "./functions/hello-world.ts"
+	 */
+	source: string;
+	/**
+	 * Environment variables injected into the deployed function. Every value must be a
+	 * defined string — a `process.env.X` that is `undefined` (unset) errors at validation
+	 * time rather than silently shipping `undefined`.
+	 * @example { RESEND_API_KEY: process.env.RESEND_API_KEY }
+	 */
+	env?: Record<string, string>;
+	/** Runtime to execute the function with. Defaults to `"nodejs24"`. */
+	runtime?: FunctionRuntime;
+	/** Memory allotted to each invocation, in MiB. Defaults to `512`. */
+	memoryMib?: FunctionMemoryMib;
+}
+
+/** Anonymous-access level for a branchable object-storage bucket. */
+export type BucketAccessLevel = "private" | "public_read";
+
+/**
+ * A branchable object-storage bucket on a branch (Preview feature).
+ */
+export interface BucketConfig {
+	/** Bucket name, unique within a branch. 1–255 chars. */
+	name: string;
+	/**
+	 * Anonymous access level. `private` (default) requires authenticated reads/writes;
+	 * `public_read` allows anonymous GetObject/HeadObject.
+	 */
+	access?: BucketAccessLevel;
+}
+
+/**
+ * Branch-scoped Preview features. Grouped under `preview` to signal they are backed by
+ * Neon `x-stability-level: beta` endpoints and may change before GA.
+ */
+export interface PreviewConfig {
+	/** Functions to deploy on the branch. */
+	functions?: FunctionConfig[];
+	/** Object-storage buckets to create on the branch. */
+	buckets?: BucketConfig[];
+	/** Enable/disable the AI Gateway on the branch (toggle, like auth / dataApi). */
+	aiGateway?: ServiceToggle;
+}
+
+interface BranchConfigBase {
+	/** Parent branch name used when creating a new branch. Not a Postgres setting. */
+	parent?: string;
+	/** Time-to-live applied when creating a new branch, or reconciled on existing branches. */
+	ttl?: string | number;
+	/** Whether the selected branch should be protected. Undefined means "leave as-is". */
+	protected?: boolean;
+	postgres?: PostgresConfig;
+	/**
+	 * Branch-scoped Preview features (functions, object-storage buckets, AI Gateway).
+	 * Backed by Neon `x-stability-level: beta` endpoints — see {@link PreviewConfig}.
+	 */
+	preview?: PreviewConfig;
+}
+
+type BranchServiceConfig =
+	| { auth?: never; dataApi?: never }
+	| { auth: ServiceToggle; dataApi?: never }
+	| { auth?: never; dataApi: ServiceToggle }
+	| { auth: ServiceToggle; dataApi: ServiceToggle };
+
+export type BranchConfig = BranchConfigBase & BranchServiceConfig;
+
+export type Config = (branch: BranchTarget) => BranchConfig;
+
+/**
+ * A function with all deploy defaults applied. `resolveConfig` fills in `runtime` and
+ * `memoryMib` so downstream diff/apply never has to re-derive them.
+ */
+export interface ResolvedFunctionConfig {
+	slug: string;
+	name: string;
+	source: string;
+	env: Record<string, string>;
+	runtime: FunctionRuntime;
+	memoryMib: FunctionMemoryMib;
+}
+
+/** A bucket with its access level defaulted to `private`. */
+export interface ResolvedBucketConfig {
+	name: string;
+	access: BucketAccessLevel;
+}
+
+/**
+ * Normalized {@link PreviewConfig}. Only present on {@link ResolvedBranchConfig} when the
+ * policy returned a `preview` block. `aiGatewayEnabled` follows the same
+ * "present-and-not-`false`" semantics as `authEnabled` / `dataApiEnabled`.
+ */
+export interface ResolvedPreviewConfig {
+	functions: ResolvedFunctionConfig[];
+	buckets: ResolvedBucketConfig[];
+	aiGatewayEnabled: boolean;
+}
+
+export interface ResolvedBranchConfig {
+	parent?: string;
+	ttlSeconds?: number;
+	protected?: boolean;
+	postgres?: PostgresConfig;
+	authEnabled: boolean;
+	dataApiEnabled: boolean;
+	preview?: ResolvedPreviewConfig;
+}
+
+/**
+ * One concrete change `pushConfig` made (or, in dry-run, would make) on the remote.
+ */
+export interface AppliedChange {
+	/**
+	 * `service` covers branch-scoped integrations driven by the branch policy (e.g.
+	 * Neon Auth, Data API).
+	 */
+	kind: "branch" | "service";
+	action: "create" | "update" | "noop";
+	identifier: string;
+	details?: Record<string, unknown>;
+}
+
+/**
+ * A diff entry that conflicts with the desired config. `pushConfig` throws
+ * {@link PushConflictError} on the first call when conflicts exist; pass
+ * `updateExisting: true` to apply mutable drift (settings, `protected`, TTL, project
+ * rename). Immutable fields (region, Postgres major version) are always conflicts —
+ * recreate the project to change them.
+ */
+export interface ConflictReport {
+	kind: "branch";
+	identifier: string;
+	field: string;
+	current: unknown;
+	desired: unknown;
+	reason: string;
+}
+
+/**
+ * Result of a `pushConfig` invocation.
+ */
+export interface PushResult {
+	projectId: string;
+	orgId?: string;
+	branchId: string;
+	branchName: string;
+	/**
+	 * `true` when `pushConfig` was called with `{ dryRun: true }`. `applied` then records
+	 * what **would** be applied on a real push; no API mutations were performed.
+	 */
+	dryRun: boolean;
+	applied: AppliedChange[];
+	conflicts: ConflictReport[];
+}