@neon/config 0.0.0 → 0.9.0

package/dist/lib/define-config.d.ts

@@ -0,0 +1,123 @@
+import { BranchTarget, BranchTuningFn, BucketDef, Config, DataApiInput, FunctionDef, PreviewInput, ResolvedBranchConfig, ServiceEnabled, ServiceToggleInput } from "./types.js";
+
+//#region src/lib/define-config.d.ts
+
+/**
+ * Whether a `dataApi` toggle is **enabled and verified by Neon Auth** at the type level: it is
+ * on (see {@link ServiceEnabled}) and not the explicit `authProvider: "external"` variant
+ * (so the default / `"neon"` provider). This is the case that requires top-level Neon Auth.
+ */
+type DataApiUsesNeonAuth<DataApi> = ServiceEnabled<DataApi> extends true ? [DataApi] extends [{
+  authProvider: "external";
+}] ? false : true : false;
+/**
+ * Human-readable hint surfaced as the **expected type** of `dataApi` when a Neon-Auth Data
+ * API is declared without Neon Auth enabled (see {@link DataApiField}). TypeScript prints the
+ * offending value against this string literal — `Type 'true' is not assignable to type
+ * '…requires `auth: true`…'` — which points straight at the fix, instead of the opaque
+ * `Type 'true' is not assignable to type 'never'` an intersection guard produces.
+ *
+ * It documents **both** fixes: enabling Neon Auth (`auth: true`), and running the Data API
+ * *without* Neon Auth by verifying a third-party IdP (`authProvider: 'external'` + `jwksUrl`).
+ */
+type NeonAuthRequiredHint = "`dataApi` with Neon Auth (the default `authProvider: 'neon'`) requires Neon Auth, so add `auth: true`. To enable the Data API WITHOUT Neon Auth, verify a third-party IdP instead: `dataApi: { authProvider: 'external', jwksUrl: 'https://your-idp/.well-known/jwks.json' }`";
+/**
+ * Static cross-field guard for {@link defineConfig}, expressed as the **type of the `dataApi`
+ * field** rather than an intersected requirement on `auth`.
+ *
+ * - A Neon-Auth Data API (`authProvider: "neon"`, the default) with top-level `auth` enabled,
+ *   or any external Data API: the field keeps its normal `DataApi & DataApiInput` type (the
+ *   `& DataApiInput` preserves member autocomplete; the `const DataApi` still types the
+ *   returned {@link Config}).
+ * - A Neon-Auth Data API **without** `auth` enabled: the field's expected type collapses to
+ *   the {@link NeonAuthRequiredHint} message, so the author sees the rule (and the two fixes)
+ *   right on the `dataApi` value.
+ *
+ * The runtime `superRefine` in {@link configInputSchema} enforces the same invariant for
+ * non-typed (plain-JS) callers, so the behavior is identical — only the type-level message
+ * changes.
+ */
+type DataApiField<Auth, DataApi> = DataApiUsesNeonAuth<DataApi> extends true ? ServiceEnabled<Auth> extends true ? DataApi & DataApiInput : NeonAuthRequiredHint : DataApi & DataApiInput;
+/**
+ * Autocomplete bridge for the nested `preview.functions` / `preview.buckets` slug objects.
+ *
+ * {@link PreviewInput} types those records with a string index signature
+ * (`Record<string, FunctionDef>` / `Record<string, BucketDef>`). When `defineConfig` infers
+ * `const Preview`, every authored slug becomes a **named** property on the inferred literal
+ * (e.g. `{ hello: { name; source } }`), and a named property **shadows** the index signature
+ * when the editor computes the contextual type of that slug's value — so the rest of
+ * {@link FunctionDef} / {@link BucketDef} (`env`, `dev`, `access`, …) never surfaces as
+ * completions inside `hello: { … }` / `uploads: { … }`.
+ *
+ * Re-declaring each inferred slug's value as `FunctionDef` / `BucketDef` (a *named* member, via
+ * a mapped type over the already-inferred keys) puts those members back onto the contextual
+ * type without going through an index signature, which restores autocomplete. Intersected with
+ * `Preview & PreviewInput` it neither widens what is accepted (the values were already
+ * `FunctionDef` / `BucketDef`) nor perturbs the inferred `const Preview` — so slug inference for
+ * `BranchTuningFn<Preview>` and the returned {@link Config} is unchanged.
+ */
+type PreviewAutocomplete<Preview> = (Preview extends {
+  functions: infer F;
+} ? {
+  functions: { [Slug in keyof F]: FunctionDef };
+} : unknown) & (Preview extends {
+  buckets: infer B;
+} ? {
+  buckets: { [Name in keyof B]: BucketDef };
+} : unknown);
+/**
+ * Validate and freeze a Neon Platform branch policy.
+ *
+ * Used at the top of `neon.ts`:
+ * ```ts
+ * import { defineConfig } from "@neon/config/v1";
+ *
+ * export default defineConfig({
+ *   auth: true,
+ *   preview: {
+ *     functions: {
+ *       hello: { name: "Hello", source: "./functions/hello.ts", dev: { port: 8787 } },
+ *     },
+ *   },
+ *   branch: (branch) => ({ protected: branch.name === "main" }),
+ * });
+ * ```
+ *
+ * The policy is split into a **static** existential set (top-level `auth` / `dataApi`
+ * toggles and the beta `preview` block) and a **dynamic** per-branch `branch` closure. The
+ * static half determines which secrets exist — so `NeonEnv<typeof config>` and `parseEnv`
+ * are exact — while the closure can only *tune* a branch (lifecycle, compute, per-function
+ * deploy settings), never change what exists.
+ *
+ * The `branch` callback receives a read-only {@link BranchTarget} descriptor of the branch
+ * being decided for (not a live handle); switch on its facts (`branch.name`,
+ * `branch.isDefault`, `branch.exists`, …) and **return** the desired tuning. It runs in two
+ * modes: against an existing branch (fields populated from Neon) and during pre-create
+ * evaluation (`exists: false`, `id` undefined).
+ *
+ * Pure: no I/O, no side effects. The static parts are validated here; the closure's output
+ * is validated every time it is evaluated so errors point at the concrete branch target.
+ */
+declare function defineConfig<const Auth extends ServiceToggleInput | undefined = undefined, const DataApi extends DataApiInput | undefined = undefined, const Preview extends PreviewInput | undefined = undefined>(input: {
+  auth?: Auth & ServiceToggleInput;
+  dataApi?: DataApiField<Auth, DataApi>;
+  preview?: Preview & PreviewInput & PreviewAutocomplete<Preview>;
+  branch?: BranchTuningFn<Preview>;
+}): Config<Auth, DataApi, Preview>;
+/**
+ * Evaluate a branch policy for a specific branch target and return a normalized config.
+ *
+ * Merges the static existential set (services + preview functions/buckets) with the
+ * per-branch tuning returned by the `branch` closure into the same {@link
+ * ResolvedBranchConfig} the rest of the runtime (diff / push / fetchEnv) consumes.
+ */
+declare function resolveConfig(config: Config, branch: BranchTarget): ResolvedBranchConfig;
+/**
+ * Normalize a region identifier to Neon's `<cloud>-<region>` format. When the user writes
+ * `us-east-1` we assume `aws-us-east-1`. Pure helper used by both the validator and the
+ * NeonApi adapter.
+ */
+declare function normalizeRegion(region: string): string;
+//#endregion
+export { DataApiField, NeonAuthRequiredHint, defineConfig, normalizeRegion, resolveConfig };
+//# sourceMappingURL=define-config.d.ts.map

package/dist/lib/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","names":[],"sources":["../../src/lib/define-config.ts"],"mappings":";;;;;;AAwBoB;;;KAYf,mBAA+B,CAAA,OAAA,CAAA,GAAA,cAAA,CAAe,OAAf,CAAA,SAAA,IAAA,GAAA,CAChC,OADgC,CAAA,SAAA,CAAA;cAChC,EAAA,UAAA;AAAO,CAAA,CAAA,GAAA,KAAA,GAAA,IAAA,GAAA,KAAA;AAiBX;AAqBA;;;;;;;;;AAKI,KA1BQ,oBAAA,GA0BR,+QAAA;;AAAsB;AAAC;;;;;;;;AAwBkB;AAoC7C;;;;;AAWQ,KA5EI,YA4EJ,CAAA,IAAA,EAAA,OAAA,CAAA,GA3EP,mBA2EO,CA3Ea,OA2Eb,CAAA,SAAA,IAAA,GA1EJ,cA0EI,CA1EW,IA0EX,CAAA,SAAA,IAAA,GAzEH,OAyEG,GAzEO,YAyEP,GAxEH,oBAwEG,GAvEJ,OAuEI,GAvEM,YAuEN;;;;;;;;;;;;;;;AAUE;AA4BV;;;KAzFK,mBA2FI,CAAA,OAAA,CAAA,GAAA,CA3F4B,OA2F5B,SAAA;WACN,EAAA,KAAA,EAAA;AAAoB,CAAA,GAAA;EAgKP,SAAA,EAAA,iBA3PiB,IAAI;gBAEnC;;;4BAC8B,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCpB,gCACI,kEACG,4DACA;SAQf,OAAO;YAIJ,aAAa,MAAM;YAInB,UAAU,eAAe,oBAAoB;WAC9C,eAAe;IACrB,OAAO,MAAM,SAAS;;;;;;;;iBA4BV,aAAA,SACP,gBACA,eACN;;;;;;iBAgKa,eAAA"}

package/dist/lib/define-config.js

@@ -0,0 +1,168 @@
+import { ConfigValidationError } from "./errors.js";
+import { parseBranchTtl } from "./duration.js";
+import { branchTuningSchema, configInputSchema, formatZodIssues } from "./schema.js";
+//#region src/lib/define-config.ts
+/** Default deploy parameters applied to functions that omit them in `neon.ts`. */
+const DEFAULT_FUNCTION_RUNTIME = "nodejs24";
+const REGION_PREFIX = /^(aws|azure|gcp)-/;
+/**
+* Validate and freeze a Neon Platform branch policy.
+*
+* Used at the top of `neon.ts`:
+* ```ts
+* import { defineConfig } from "@neon/config/v1";
+*
+* export default defineConfig({
+*   auth: true,
+*   preview: {
+*     functions: {
+*       hello: { name: "Hello", source: "./functions/hello.ts", dev: { port: 8787 } },
+*     },
+*   },
+*   branch: (branch) => ({ protected: branch.name === "main" }),
+* });
+* ```
+*
+* The policy is split into a **static** existential set (top-level `auth` / `dataApi`
+* toggles and the beta `preview` block) and a **dynamic** per-branch `branch` closure. The
+* static half determines which secrets exist — so `NeonEnv<typeof config>` and `parseEnv`
+* are exact — while the closure can only *tune* a branch (lifecycle, compute, per-function
+* deploy settings), never change what exists.
+*
+* The `branch` callback receives a read-only {@link BranchTarget} descriptor of the branch
+* being decided for (not a live handle); switch on its facts (`branch.name`,
+* `branch.isDefault`, `branch.exists`, …) and **return** the desired tuning. It runs in two
+* modes: against an existing branch (fields populated from Neon) and during pre-create
+* evaluation (`exists: false`, `id` undefined).
+*
+* Pure: no I/O, no side effects. The static parts are validated here; the closure's output
+* is validated every time it is evaluated so errors point at the concrete branch target.
+*/
+function defineConfig(input) {
+	if (typeof input === "function") throw new ConfigValidationError(["defineConfig now expects an object, not a function: `export default defineConfig({ auth: true, preview: { … }, branch: (branch) => ({ … }) })`.", "The static services/preview set moved to the top level; per-branch logic moved into the `branch` closure."]);
+	if (input === null || typeof input !== "object") throw new ConfigValidationError(["defineConfig expects a configuration object: `export default defineConfig({ … })`."]);
+	const parsed = configInputSchema.safeParse(input);
+	if (!parsed.success) throw new ConfigValidationError(formatZodIssues(parsed.error));
+	return Object.freeze({ ...input });
+}
+/**
+* Evaluate a branch policy for a specific branch target and return a normalized config.
+*
+* Merges the static existential set (services + preview functions/buckets) with the
+* per-branch tuning returned by the `branch` closure into the same {@link
+* ResolvedBranchConfig} the rest of the runtime (diff / push / fetchEnv) consumes.
+*/
+function resolveConfig(config, branch) {
+	const tuning = evaluateBranchTuning(config.branch, branch);
+	const resolved = {
+		authEnabled: isServiceEnabled(config.auth),
+		dataApiEnabled: isDataApiEnabled(config.dataApi)
+	};
+	const dataApi = resolveDataApi(config.dataApi);
+	if (dataApi) resolved.dataApi = dataApi;
+	if (tuning.parent !== void 0) resolved.parent = tuning.parent;
+	if (tuning.ttl !== void 0) {
+		const parsedTtl = parseBranchTtl(tuning.ttl);
+		if (!("error" in parsedTtl)) resolved.ttlSeconds = parsedTtl.seconds;
+	}
+	if (tuning.protected !== void 0) resolved.protected = tuning.protected;
+	if (tuning.postgres?.computeSettings) resolved.postgres = { computeSettings: { ...tuning.postgres.computeSettings } };
+	const preview = resolvePreviewConfig(config.preview, tuning);
+	if (preview) resolved.preview = preview;
+	return resolved;
+}
+/**
+* Run the `branch` closure (when present) for the target and validate its output. The
+* closure is optional — a fully static policy resolves with empty tuning.
+*/
+function evaluateBranchTuning(branchFn, target) {
+	if (!branchFn) return {};
+	let raw;
+	try {
+		raw = branchFn(Object.freeze({ ...target }));
+	} catch (cause) {
+		throw new ConfigValidationError([`Branch policy threw while evaluating branch "${target.name}".`, cause?.message ?? String(cause)]);
+	}
+	const parsed = branchTuningSchema.safeParse(raw ?? {});
+	if (!parsed.success) throw new ConfigValidationError(formatZodIssues(parsed.error));
+	return parsed.data;
+}
+function isServiceEnabled(toggle) {
+	if (toggle === void 0) return false;
+	if (typeof toggle === "boolean") return toggle;
+	return toggle.enabled !== false;
+}
+/** Whether a {@link DataApiInput} is enabled (present object/`true` unless `enabled: false`). */
+function isDataApiEnabled(input) {
+	if (input === void 0) return false;
+	if (typeof input === "boolean") return input;
+	return input.enabled !== false;
+}
+/**
+* Normalize a {@link DataApiInput} into a {@link ResolvedDataApiConfig}, or `undefined` when
+* the Data API is not enabled. `authProvider` defaults to `"neon"`; the external-IdP wiring
+* is carried through only for the `"external"` provider; `settings` is copied with its
+* `undefined` entries dropped so diffing only considers fields the policy actually set.
+*/
+function resolveDataApi(input) {
+	if (!isDataApiEnabled(input)) return void 0;
+	if (typeof input !== "object") return { authProvider: "neon" };
+	const authProvider = input.authProvider ?? "neon";
+	const resolved = { authProvider };
+	if (authProvider === "external") {
+		if (input.jwksUrl !== void 0) resolved.jwksUrl = input.jwksUrl;
+		if (input.providerName !== void 0) resolved.providerName = input.providerName;
+		if (input.jwtAudience !== void 0) resolved.jwtAudience = input.jwtAudience;
+	}
+	const settings = normalizeDataApiSettings(input.settings);
+	if (settings) resolved.settings = settings;
+	return resolved;
+}
+/** Copy a {@link DataApiSettings}, dropping `undefined` entries; `undefined` when empty. */
+function normalizeDataApiSettings(settings) {
+	if (!settings) return void 0;
+	const out = {};
+	for (const [key, value] of Object.entries(settings)) if (value !== void 0) out[key] = value;
+	return Object.keys(out).length > 0 ? out : void 0;
+}
+/**
+* Normalize the static {@link PreviewInput} (merged with per-branch function tuning) into a
+* {@link ResolvedPreviewConfig}. Returns `undefined` when the policy declares no `preview`
+* block so the field can be omitted entirely. Function slugs / bucket names come from the
+* record keys.
+*/
+function resolvePreviewConfig(preview, tuning) {
+	if (!preview) return void 0;
+	const fnTuning = tuning.preview?.functions ?? {};
+	return {
+		functions: Object.entries(preview.functions ?? {}).map(([slug, def]) => resolveFunctionConfig(slug, def, fnTuning[slug] ?? {})),
+		buckets: Object.entries(preview.buckets ?? {}).map(([name, def]) => ({
+			name,
+			access: def.access ?? "private"
+		})),
+		aiGatewayEnabled: isServiceEnabled(preview.aiGateway)
+	};
+}
+function resolveFunctionConfig(slug, def, tuning) {
+	return {
+		slug,
+		name: def.name,
+		source: def.source,
+		env: { ...def.env ?? {} },
+		runtime: tuning.runtime ?? DEFAULT_FUNCTION_RUNTIME,
+		...def.dev ? { dev: def.dev } : {}
+	};
+}
+/**
+* Normalize a region identifier to Neon's `<cloud>-<region>` format. When the user writes
+* `us-east-1` we assume `aws-us-east-1`. Pure helper used by both the validator and the
+* NeonApi adapter.
+*/
+function normalizeRegion(region) {
+	if (REGION_PREFIX.test(region)) return region;
+	return `aws-${region}`;
+}
+//#endregion
+export { defineConfig, normalizeRegion, resolveConfig };
+
+//# sourceMappingURL=define-config.js.map

package/dist/lib/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","names":[],"sources":["../../src/lib/define-config.ts"],"sourcesContent":["import { parseBranchTtl } from \"./duration.js\";\nimport { ConfigValidationError } from \"./errors.js\";\nimport {\n\tbranchTuningSchema,\n\tconfigInputSchema,\n\tformatZodIssues,\n} from \"./schema.js\";\nimport type {\n\tBranchTarget,\n\tBranchTuning,\n\tBranchTuningFn,\n\tBucketDef,\n\tConfig,\n\tDataApiInput,\n\tDataApiSettings,\n\tFunctionDef,\n\tFunctionTuning,\n\tPreviewInput,\n\tResolvedBranchConfig,\n\tResolvedDataApiConfig,\n\tResolvedFunctionConfig,\n\tResolvedPreviewConfig,\n\tServiceEnabled,\n\tServiceToggleInput,\n} from \"./types.js\";\n\n/** Default deploy parameters applied to functions that omit them in `neon.ts`. */\nconst DEFAULT_FUNCTION_RUNTIME = \"nodejs24\" as const;\n\nconst REGION_PREFIX = /^(aws|azure|gcp)-/;\n\n/**\n * Whether a `dataApi` toggle is **enabled and verified by Neon Auth** at the type level: it is\n * on (see {@link ServiceEnabled}) and not the explicit `authProvider: \"external\"` variant\n * (so the default / `\"neon\"` provider). This is the case that requires top-level Neon Auth.\n */\ntype DataApiUsesNeonAuth<DataApi> = ServiceEnabled<DataApi> extends true\n\t? [DataApi] extends [{ authProvider: \"external\" }]\n\t\t? false\n\t\t: true\n\t: false;\n\n/**\n * Human-readable hint surfaced as the **expected type** of `dataApi` when a Neon-Auth Data\n * API is declared without Neon Auth enabled (see {@link DataApiField}). TypeScript prints the\n * offending value against this string literal — `Type 'true' is not assignable to type\n * '…requires `auth: true`…'` — which points straight at the fix, instead of the opaque\n * `Type 'true' is not assignable to type 'never'` an intersection guard produces.\n *\n * It documents **both** fixes: enabling Neon Auth (`auth: true`), and running the Data API\n * *without* Neon Auth by verifying a third-party IdP (`authProvider: 'external'` + `jwksUrl`).\n */\n// Exported (type-only) for the type tests in `define-config.test-d.ts`; intentionally not\n// re-exported from `v1.ts` / `index.ts`, so it stays an internal implementation detail.\nexport type NeonAuthRequiredHint =\n\t\"`dataApi` with Neon Auth (the default `authProvider: 'neon'`) requires Neon Auth, so add `auth: true`. To enable the Data API WITHOUT Neon Auth, verify a third-party IdP instead: `dataApi: { authProvider: 'external', jwksUrl: 'https://your-idp/.well-known/jwks.json' }`\";\n\n/**\n * Static cross-field guard for {@link defineConfig}, expressed as the **type of the `dataApi`\n * field** rather than an intersected requirement on `auth`.\n *\n * - A Neon-Auth Data API (`authProvider: \"neon\"`, the default) with top-level `auth` enabled,\n *   or any external Data API: the field keeps its normal `DataApi & DataApiInput` type (the\n *   `& DataApiInput` preserves member autocomplete; the `const DataApi` still types the\n *   returned {@link Config}).\n * - A Neon-Auth Data API **without** `auth` enabled: the field's expected type collapses to\n *   the {@link NeonAuthRequiredHint} message, so the author sees the rule (and the two fixes)\n *   right on the `dataApi` value.\n *\n * The runtime `superRefine` in {@link configInputSchema} enforces the same invariant for\n * non-typed (plain-JS) callers, so the behavior is identical — only the type-level message\n * changes.\n */\n// Exported (type-only) for the type tests in `define-config.test-d.ts`; intentionally not\n// re-exported from `v1.ts` / `index.ts`, so it stays an internal implementation detail.\nexport type DataApiField<Auth, DataApi> =\n\tDataApiUsesNeonAuth<DataApi> extends true\n\t\t? ServiceEnabled<Auth> extends true\n\t\t\t? DataApi & DataApiInput\n\t\t\t: NeonAuthRequiredHint\n\t\t: DataApi & DataApiInput;\n\n/**\n * Autocomplete bridge for the nested `preview.functions` / `preview.buckets` slug objects.\n *\n * {@link PreviewInput} types those records with a string index signature\n * (`Record<string, FunctionDef>` / `Record<string, BucketDef>`). When `defineConfig` infers\n * `const Preview`, every authored slug becomes a **named** property on the inferred literal\n * (e.g. `{ hello: { name; source } }`), and a named property **shadows** the index signature\n * when the editor computes the contextual type of that slug's value — so the rest of\n * {@link FunctionDef} / {@link BucketDef} (`env`, `dev`, `access`, …) never surfaces as\n * completions inside `hello: { … }` / `uploads: { … }`.\n *\n * Re-declaring each inferred slug's value as `FunctionDef` / `BucketDef` (a *named* member, via\n * a mapped type over the already-inferred keys) puts those members back onto the contextual\n * type without going through an index signature, which restores autocomplete. Intersected with\n * `Preview & PreviewInput` it neither widens what is accepted (the values were already\n * `FunctionDef` / `BucketDef`) nor perturbs the inferred `const Preview` — so slug inference for\n * `BranchTuningFn<Preview>` and the returned {@link Config} is unchanged.\n */\ntype PreviewAutocomplete<Preview> = (Preview extends { functions: infer F }\n\t? { functions: { [Slug in keyof F]: FunctionDef } }\n\t: unknown) &\n\t(Preview extends { buckets: infer B }\n\t\t? { buckets: { [Name in keyof B]: BucketDef } }\n\t\t: unknown);\n\n/**\n * Validate and freeze a Neon Platform branch policy.\n *\n * Used at the top of `neon.ts`:\n * ```ts\n * import { defineConfig } from \"@neon/config/v1\";\n *\n * export default defineConfig({\n *   auth: true,\n *   preview: {\n *     functions: {\n *       hello: { name: \"Hello\", source: \"./functions/hello.ts\", dev: { port: 8787 } },\n *     },\n *   },\n *   branch: (branch) => ({ protected: branch.name === \"main\" }),\n * });\n * ```\n *\n * The policy is split into a **static** existential set (top-level `auth` / `dataApi`\n * toggles and the beta `preview` block) and a **dynamic** per-branch `branch` closure. The\n * static half determines which secrets exist — so `NeonEnv<typeof config>` and `parseEnv`\n * are exact — while the closure can only *tune* a branch (lifecycle, compute, per-function\n * deploy settings), never change what exists.\n *\n * The `branch` callback receives a read-only {@link BranchTarget} descriptor of the branch\n * being decided for (not a live handle); switch on its facts (`branch.name`,\n * `branch.isDefault`, `branch.exists`, …) and **return** the desired tuning. It runs in two\n * modes: against an existing branch (fields populated from Neon) and during pre-create\n * evaluation (`exists: false`, `id` undefined).\n *\n * Pure: no I/O, no side effects. The static parts are validated here; the closure's output\n * is validated every time it is evaluated so errors point at the concrete branch target.\n */\nexport function defineConfig<\n\tconst Auth extends ServiceToggleInput | undefined = undefined,\n\tconst DataApi extends DataApiInput | undefined = undefined,\n\tconst Preview extends PreviewInput | undefined = undefined,\n>(input: {\n\t// Each field is intersected with its concrete interface (not just typed as the bare\n\t// generic). The generic alone — e.g. `preview?: Preview` — gives editors no members to\n\t// complete against in the object-literal position (they see `{} | undefined`), so you\n\t// lose hints for `aiGateway` / `functions` / `buckets`. `& PreviewInput` restores the\n\t// full shape for autocomplete while still inferring the `const` literal that types the\n\t// `branch` closure's slugs (BranchTuningFn<Preview>) and the returned Config.\n\tauth?: Auth & ServiceToggleInput;\n\t// The `dataApi` field carries the Neon-Auth cross-field guard at the type level (see\n\t// `DataApiField`): a Neon-Auth Data API without `auth` enabled surfaces a readable hint\n\t// as the field's expected type instead of collapsing the value to `never`.\n\tdataApi?: DataApiField<Auth, DataApi>;\n\t// `& PreviewInput` restores top-level member hints (aiGateway/functions/buckets);\n\t// `& PreviewAutocomplete<Preview>` restores hints *inside* each function/bucket slug\n\t// object (see `PreviewAutocomplete`), which the bare index signature otherwise hides.\n\tpreview?: Preview & PreviewInput & PreviewAutocomplete<Preview>;\n\tbranch?: BranchTuningFn<Preview>;\n}): Config<Auth, DataApi, Preview> {\n\tif (typeof input === \"function\") {\n\t\tthrow new ConfigValidationError([\n\t\t\t\"defineConfig now expects an object, not a function: `export default defineConfig({ auth: true, preview: { … }, branch: (branch) => ({ … }) })`.\",\n\t\t\t\"The static services/preview set moved to the top level; per-branch logic moved into the `branch` closure.\",\n\t\t]);\n\t}\n\tif (input === null || typeof input !== \"object\") {\n\t\tthrow new ConfigValidationError([\n\t\t\t\"defineConfig expects a configuration object: `export default defineConfig({ … })`.\",\n\t\t]);\n\t}\n\n\tconst parsed = configInputSchema.safeParse(input);\n\tif (!parsed.success) {\n\t\tthrow new ConfigValidationError(formatZodIssues(parsed.error));\n\t}\n\n\treturn Object.freeze({ ...input }) as Config<Auth, DataApi, Preview>;\n}\n\n/**\n * Evaluate a branch policy for a specific branch target and return a normalized config.\n *\n * Merges the static existential set (services + preview functions/buckets) with the\n * per-branch tuning returned by the `branch` closure into the same {@link\n * ResolvedBranchConfig} the rest of the runtime (diff / push / fetchEnv) consumes.\n */\nexport function resolveConfig(\n\tconfig: Config,\n\tbranch: BranchTarget,\n): ResolvedBranchConfig {\n\tconst tuning = evaluateBranchTuning(config.branch, branch);\n\n\tconst resolved: ResolvedBranchConfig = {\n\t\tauthEnabled: isServiceEnabled(config.auth),\n\t\tdataApiEnabled: isDataApiEnabled(config.dataApi),\n\t};\n\tconst dataApi = resolveDataApi(config.dataApi);\n\tif (dataApi) resolved.dataApi = dataApi;\n\tif (tuning.parent !== undefined) resolved.parent = tuning.parent;\n\tif (tuning.ttl !== undefined) {\n\t\t// `branchTuningSchema` already validated `ttl` with the same `parseBranchTtl`, so\n\t\t// this only converts the validated value to seconds — it cannot fail here.\n\t\tconst parsedTtl = parseBranchTtl(tuning.ttl);\n\t\tif (!(\"error\" in parsedTtl)) resolved.ttlSeconds = parsedTtl.seconds;\n\t}\n\tif (tuning.protected !== undefined) resolved.protected = tuning.protected;\n\tif (tuning.postgres?.computeSettings) {\n\t\tresolved.postgres = {\n\t\t\tcomputeSettings: { ...tuning.postgres.computeSettings },\n\t\t};\n\t}\n\n\tconst preview = resolvePreviewConfig(config.preview, tuning);\n\tif (preview) resolved.preview = preview;\n\n\treturn resolved;\n}\n\n/**\n * Run the `branch` closure (when present) for the target and validate its output. The\n * closure is optional — a fully static policy resolves with empty tuning.\n */\nfunction evaluateBranchTuning(\n\tbranchFn: BranchTuningFn | undefined,\n\ttarget: BranchTarget,\n): BranchTuning {\n\tif (!branchFn) return {};\n\tlet raw: unknown;\n\ttry {\n\t\traw = branchFn(Object.freeze({ ...target }));\n\t} catch (cause) {\n\t\tthrow new ConfigValidationError([\n\t\t\t`Branch policy threw while evaluating branch \"${target.name}\".`,\n\t\t\t(cause as Error)?.message ?? String(cause),\n\t\t]);\n\t}\n\tconst parsed = branchTuningSchema.safeParse(raw ?? {});\n\tif (!parsed.success) {\n\t\tthrow new ConfigValidationError(formatZodIssues(parsed.error));\n\t}\n\treturn parsed.data as BranchTuning;\n}\n\nfunction isServiceEnabled(toggle: ServiceToggleInput | undefined): boolean {\n\tif (toggle === undefined) return false;\n\tif (typeof toggle === \"boolean\") return toggle;\n\treturn toggle.enabled !== false;\n}\n\n/** Whether a {@link DataApiInput} is enabled (present object/`true` unless `enabled: false`). */\nfunction isDataApiEnabled(input: DataApiInput | undefined): boolean {\n\tif (input === undefined) return false;\n\tif (typeof input === \"boolean\") return input;\n\treturn input.enabled !== false;\n}\n\n/**\n * Normalize a {@link DataApiInput} into a {@link ResolvedDataApiConfig}, or `undefined` when\n * the Data API is not enabled. `authProvider` defaults to `\"neon\"`; the external-IdP wiring\n * is carried through only for the `\"external\"` provider; `settings` is copied with its\n * `undefined` entries dropped so diffing only considers fields the policy actually set.\n */\nfunction resolveDataApi(\n\tinput: DataApiInput | undefined,\n): ResolvedDataApiConfig | undefined {\n\tif (!isDataApiEnabled(input)) return undefined;\n\tif (typeof input !== \"object\") {\n\t\t// Bare `true`: enabled with Neon Auth and all-default settings.\n\t\treturn { authProvider: \"neon\" };\n\t}\n\tconst authProvider = input.authProvider ?? \"neon\";\n\tconst resolved: ResolvedDataApiConfig = { authProvider };\n\tif (authProvider === \"external\") {\n\t\tif (input.jwksUrl !== undefined) resolved.jwksUrl = input.jwksUrl;\n\t\tif (input.providerName !== undefined)\n\t\t\tresolved.providerName = input.providerName;\n\t\tif (input.jwtAudience !== undefined)\n\t\t\tresolved.jwtAudience = input.jwtAudience;\n\t}\n\tconst settings = normalizeDataApiSettings(input.settings);\n\tif (settings) resolved.settings = settings;\n\treturn resolved;\n}\n\n/** Copy a {@link DataApiSettings}, dropping `undefined` entries; `undefined` when empty. */\nfunction normalizeDataApiSettings(\n\tsettings: DataApiSettings | undefined,\n): DataApiSettings | undefined {\n\tif (!settings) return undefined;\n\tconst out: DataApiSettings = {};\n\tfor (const [key, value] of Object.entries(settings)) {\n\t\tif (value !== undefined) {\n\t\t\t(out as Record<string, unknown>)[key] = value;\n\t\t}\n\t}\n\treturn Object.keys(out).length > 0 ? out : undefined;\n}\n\n/**\n * Normalize the static {@link PreviewInput} (merged with per-branch function tuning) into a\n * {@link ResolvedPreviewConfig}. Returns `undefined` when the policy declares no `preview`\n * block so the field can be omitted entirely. Function slugs / bucket names come from the\n * record keys.\n */\nfunction resolvePreviewConfig(\n\tpreview: PreviewInput | undefined,\n\ttuning: BranchTuning,\n): ResolvedPreviewConfig | undefined {\n\tif (!preview) return undefined;\n\tconst fnTuning = tuning.preview?.functions ?? {};\n\tconst functions: ResolvedFunctionConfig[] = Object.entries(\n\t\tpreview.functions ?? {},\n\t).map(([slug, def]) =>\n\t\tresolveFunctionConfig(slug, def, fnTuning[slug] ?? {}),\n\t);\n\tconst buckets = Object.entries(preview.buckets ?? {}).map(\n\t\t([name, def]) => ({\n\t\t\tname,\n\t\t\taccess: def.access ?? \"private\",\n\t\t}),\n\t);\n\treturn {\n\t\tfunctions,\n\t\tbuckets,\n\t\taiGatewayEnabled: isServiceEnabled(preview.aiGateway),\n\t};\n}\n\nfunction resolveFunctionConfig(\n\tslug: string,\n\tdef: FunctionDef,\n\ttuning: FunctionTuning,\n): ResolvedFunctionConfig {\n\treturn {\n\t\tslug,\n\t\tname: def.name,\n\t\tsource: def.source,\n\t\tenv: { ...(def.env ?? {}) },\n\t\truntime: tuning.runtime ?? DEFAULT_FUNCTION_RUNTIME,\n\t\t// Passed through untouched (no defaults); only `neon dev` reads it.\n\t\t...(def.dev ? { dev: def.dev } : {}),\n\t};\n}\n\n/**\n * Normalize a region identifier to Neon's `<cloud>-<region>` format. When the user writes\n * `us-east-1` we assume `aws-us-east-1`. Pure helper used by both the validator and the\n * NeonApi adapter.\n */\nexport function normalizeRegion(region: string): string {\n\tif (REGION_PREFIX.test(region)) return region;\n\treturn `aws-${region}`;\n}\n"],"mappings":"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"}

package/dist/lib/diff.d.ts

@@ -0,0 +1,120 @@
+import { BucketAccessLevel, ComputeSettings, ConflictReport, DataApiSettings, ResolvedBranchConfig, ResolvedFunctionConfig } from "./types.js";
+import { EnableDataApiInput, NeonBranchSnapshot, NeonBucketSnapshot, NeonEndpointSnapshot, NeonFunctionSnapshot } from "./neon-api.js";
+
+//#region src/lib/diff.d.ts
+
+/**
+ * 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).
+ */
+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;
+  /** Create-time auth wiring + initial settings from the policy. */
+  input?: EnableDataApiInput;
+} | {
+  /**
+   * Reconcile the runtime settings of an already-enabled Data API integration.
+   * Only `settings` are mutable post-create, so this is the lone Data API
+   * *update* step — and it is an override (requires `updateExisting`).
+   */
+  kind: "update-data-api";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  databaseName: string;
+  settings: DataApiSettings;
+} | {
+  kind: "create-bucket";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  bucketName: string;
+  accessLevel: BucketAccessLevel;
+} | {
+  /**
+   * Deploy code to a function. Planned for every desired function — deployments are
+   * versioned and the newest becomes active, so a push ships the current source each
+   * time. Neon has no separate "create function" endpoint: the first deployment to a
+   * slug creates the function. `functionExists` therefore only drives whether this
+   * surfaces as a `create` (first deploy) or an `update` (re-deploy).
+   */
+  kind: "deploy-function";
+  projectId: string;
+  branchId: string;
+  branchName: string;
+  fn: ResolvedFunctionConfig;
+  /** Whether the function already existed remotely when the plan was computed. */
+  functionExists: boolean;
+};
+interface RemoteServiceState {
+  databaseName: string;
+  authEnabled: boolean;
+  dataApiEnabled: boolean;
+  /**
+   * Current Data API runtime settings, when the integration is enabled and the API reports
+   * them (SubZero only). `null`/absent means "not reported" — settings drift can't be
+   * computed, so no update step is planned.
+   */
+  dataApiSettings?: DataApiSettings | null;
+}
+/**
+ * Snapshot of the branch's current Preview-feature state. Absent (`undefined`) when the
+ * policy has no `preview` block — `pushConfig` only fetches this when needed.
+ */
+interface RemotePreviewState {
+  buckets: NeonBucketSnapshot[];
+  functions: NeonFunctionSnapshot[];
+}
+interface RemoteState {
+  projectId: string;
+  branch: NeonBranchSnapshot;
+  endpoint?: NeonEndpointSnapshot;
+  services: RemoteServiceState;
+  preview?: RemotePreviewState;
+}
+interface DiffOptions {
+  /**
+   * Apply mutable drift on the selected branch as plan steps instead of conflicts.
+   * Default: `false`.
+   */
+  updateExisting: boolean;
+}
+interface DiffResult {
+  plan: PlanStep[];
+  conflicts: ConflictReport[];
+}
+/**
+ * Diff desired branch policy against the selected remote branch. Pure function.
+ */
+declare function diffConfig(config: ResolvedBranchConfig, remote: RemoteState, options: DiffOptions): DiffResult;
+//#endregion
+export { DiffOptions, DiffResult, PlanStep, RemotePreviewState, RemoteServiceState, RemoteState, diffConfig };
+//# sourceMappingURL=diff.d.ts.map

package/dist/lib/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","names":[],"sources":["../../src/lib/diff.ts"],"mappings":";;;;;;;AAqBA;;AAoBa,KApBD,QAAA,GAoBC;MAgBF,EAAA,mBAAA;WAaE,EAAA,MAAA;UAQG,EAAA,MAAA;YAcT,EAAA,MAAA;EAAsB,SAAA,EAAA,MAAA,GAAA,IAAA;AAK7B,CAAA,GAAiB;EAgBA,IAAA,EAAA,yBAAkB;EAAA,SAAA,EAAA,MAAA;UACzB,EAAA,MAAA;YACE,EAAA,MAAA;EAAoB,SAAA,EAAA,OAAA;AAGhC,CAAA,GAAiB;EAAW,IAAA,EAAA,iBAAA;WAEnB,EAAA,MAAA;YACG,EAAA,MAAA;YACD,EAAA,MAAA;UACA,EAlFE,eAkFF;AAAkB,CAAA,GAAA;EAGZ,IAAA,EAAA,aAAW;EAQX,SAAA,EAAA,MAAU;EAAA,QAAA,EAAA,MAAA;YACpB,EAAA,MAAA;cACK,CAAA,EAAA,MAAA;AAAc,CAAA,GAAA;EAMV,IAAA,EAAA,iBAAU;EAAA,SAAA,EAAA,MAAA;UACjB,EAAA,MAAA;YACA,EAAA,MAAA;cACC,EAAA,MAAA;;EACG,KAAA,CAAA,EAzFF,kBAyFE;;;;;;;;;;;;YA5EA;;;;;;;eAQG;;;;;;;;;;;;;MAcT;;;;UAKU,kBAAA;;;;;;;;;oBASE;;;;;;UAOF,kBAAA;WACP;aACE;;UAGK,WAAA;;UAER;aACG;YACD;YACA;;UAGM,WAAA;;;;;;;UAQA,UAAA;QACV;aACK;;;;;iBAMI,UAAA,SACP,8BACA,sBACC,cACP"}