@neondatabase/config 0.0.0 → 0.2.0

package/src/lib/schema.ts

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

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

@@ -1,268 +0,0 @@
-/**
- * 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[];
-}