@neon/env 0.0.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +178 -0
- package/README.md +96 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +86 -0
- package/dist/cli.js.map +1 -0
- package/dist/config/dist/lib/neon-api.d.ts +375 -0
- package/dist/config/dist/lib/neon-api.d.ts.map +1 -0
- package/dist/config/dist/lib/types.d.ts +445 -0
- package/dist/config/dist/lib/types.d.ts.map +1 -0
- package/dist/config/dist/v1.d.ts +4 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/lib/cli/commands.d.ts +64 -0
- package/dist/lib/cli/commands.d.ts.map +1 -0
- package/dist/lib/cli/commands.js +219 -0
- package/dist/lib/cli/commands.js.map +1 -0
- package/dist/lib/cli/resolve-context.d.ts +33 -0
- package/dist/lib/cli/resolve-context.d.ts.map +1 -0
- package/dist/lib/cli/resolve-context.js +87 -0
- package/dist/lib/cli/resolve-context.js.map +1 -0
- package/dist/lib/env.d.ts +410 -0
- package/dist/lib/env.d.ts.map +1 -0
- package/dist/lib/env.js +561 -0
- package/dist/lib/env.js.map +1 -0
- package/package.json +56 -17
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
import { Config } from "../config/dist/lib/types.js";
|
|
2
|
+
import { NeonApi } from "../config/dist/lib/neon-api.js";
|
|
3
|
+
import "../config/dist/v1.js";
|
|
4
|
+
|
|
5
|
+
//#region src/lib/env.d.ts
|
|
6
|
+
declare const NEON_ENV_VAR_KEYS: {
|
|
7
|
+
/**
|
|
8
|
+
* Branch identity. `NEON_BRANCH` carries the branch **name** and is injected into the
|
|
9
|
+
* Neon Functions runtime on every branch (including the default) by default. `env pull` /
|
|
10
|
+
* `neon dev` / `neon-env run` emit it too so local dev mirrors the deployed runtime.
|
|
11
|
+
*/
|
|
12
|
+
readonly branch: {
|
|
13
|
+
readonly name: "NEON_BRANCH";
|
|
14
|
+
};
|
|
15
|
+
readonly postgres: {
|
|
16
|
+
readonly databaseUrl: "DATABASE_URL";
|
|
17
|
+
readonly databaseUrlUnpooled: "DATABASE_URL_UNPOOLED";
|
|
18
|
+
};
|
|
19
|
+
readonly auth: {
|
|
20
|
+
readonly baseUrl: "NEON_AUTH_BASE_URL";
|
|
21
|
+
readonly jwksUrl: "NEON_AUTH_JWKS_URL";
|
|
22
|
+
};
|
|
23
|
+
readonly dataApi: {
|
|
24
|
+
readonly url: "NEON_DATA_API_URL";
|
|
25
|
+
};
|
|
26
|
+
/**
|
|
27
|
+
* Object storage (Preview). The S3 SDKs read `AWS_*` from their standard config chain, so
|
|
28
|
+
* a branch credential + `neon dev` / `env pull` makes object storage work from env alone.
|
|
29
|
+
* `region` is injected under the SDK-standard `AWS_REGION`.
|
|
30
|
+
*/
|
|
31
|
+
readonly storage: {
|
|
32
|
+
readonly accessKeyId: "AWS_ACCESS_KEY_ID";
|
|
33
|
+
readonly secretAccessKey: "AWS_SECRET_ACCESS_KEY";
|
|
34
|
+
readonly endpoint: "AWS_ENDPOINT_URL_S3";
|
|
35
|
+
readonly region: "AWS_REGION";
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* AI Gateway (Preview). Mapped onto the OpenAI SDK's standard env vars so the OpenAI
|
|
39
|
+
* clients work from env alone; `baseUrl` carries the gateway's OpenAI-dialect route prefix
|
|
40
|
+
* (`/ai-gateway/openai/v1`). The `NEON_AI_GATEWAY_*` aliases are also emitted: `neonToken`
|
|
41
|
+
* mirrors the OpenAI key, and `neonBaseUrl` is the bare branch gateway host
|
|
42
|
+
* (`scheme://host`, no path) — the `@ai-sdk/neon` provider appends the
|
|
43
|
+
* `/ai-gateway/<dialect>/…` routes itself (https://github.com/vercel/ai/pull/15997).
|
|
44
|
+
*/
|
|
45
|
+
readonly aiGateway: {
|
|
46
|
+
readonly apiKey: "OPENAI_API_KEY";
|
|
47
|
+
readonly baseUrl: "OPENAI_BASE_URL";
|
|
48
|
+
readonly neonToken: "NEON_AI_GATEWAY_TOKEN";
|
|
49
|
+
readonly neonBaseUrl: "NEON_AI_GATEWAY_BASE_URL";
|
|
50
|
+
};
|
|
51
|
+
};
|
|
52
|
+
/**
|
|
53
|
+
* Branch identity for the resolved branch. Always present on a `fetchEnv` result (the branch
|
|
54
|
+
* name is always known); on a `parseEnv` result it's present only when `NEON_BRANCH` was
|
|
55
|
+
* injected into `process.env` (the Functions runtime injects it by default, as do `neon dev` /
|
|
56
|
+
* `neon-env run` / `env pull`). `name` is the branch **name** (e.g. `main`, `preview/foo`).
|
|
57
|
+
*/
|
|
58
|
+
interface NeonBranchEnv {
|
|
59
|
+
name: string;
|
|
60
|
+
}
|
|
61
|
+
/** Per-namespace inner shapes. Exposed so consumers can name the parts independently. */
|
|
62
|
+
interface NeonPostgresEnv {
|
|
63
|
+
/**
|
|
64
|
+
* Pooled connection string (via Neon's PgBouncer pooler). The right default for
|
|
65
|
+
* serverless drivers (`@neondatabase/serverless`, edge runtimes, Postgres.js, …).
|
|
66
|
+
*/
|
|
67
|
+
databaseUrl: string;
|
|
68
|
+
/**
|
|
69
|
+
* Direct (unpooled) connection string. Use this when you need session-level
|
|
70
|
+
* features (`LISTEN`/`NOTIFY`, prepared statements across calls, transactions
|
|
71
|
+
* spanning round-trips) that PgBouncer's transaction-mode pooling drops.
|
|
72
|
+
*/
|
|
73
|
+
databaseUrlUnpooled: string;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Bits of a Neon Auth integration for the resolved branch. Only present on `NeonEnv`
|
|
77
|
+
* when the branch policy enables `auth`.
|
|
78
|
+
*
|
|
79
|
+
* Neon Auth exposes the `baseUrl` (which doubles as the publishable client identifier) and
|
|
80
|
+
* the `jwksUrl` used to verify tokens it issues. `fetchEnv` reads both from the live
|
|
81
|
+
* integration; `parseEnv` reads them from `process.env` (`NEON_AUTH_BASE_URL` /
|
|
82
|
+
* `NEON_AUTH_JWKS_URL`).
|
|
83
|
+
*/
|
|
84
|
+
interface NeonAuthEnv {
|
|
85
|
+
baseUrl: string;
|
|
86
|
+
/** JWKS URL for verifying tokens issued by Neon Auth (`NEON_AUTH_JWKS_URL`). */
|
|
87
|
+
jwksUrl: string;
|
|
88
|
+
}
|
|
89
|
+
/** Bits of a Neon Data API integration. Only present when the branch policy enables it. */
|
|
90
|
+
interface NeonDataApiEnv {
|
|
91
|
+
url: string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* S3-compatible object-storage access for the branch (Preview). Present on `NeonEnv` only
|
|
95
|
+
* when the policy declares `preview.buckets`. Combines a minted branch credential's access
|
|
96
|
+
* keys (`accessKeyId` = the credential's full token id, e.g. `nak_live_…`, which is what the
|
|
97
|
+
* storage gateway authenticates against; `secretAccessKey` = its
|
|
98
|
+
* `s3_secret_access_key`) with the branch's non-secret connection details
|
|
99
|
+
* (`endpoint`/`region`, from `GET .../storage`). Projects to the AWS SDK's
|
|
100
|
+
* standard config env (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`,
|
|
101
|
+
* `AWS_REGION`) so the S3 client works from env alone. Neon's storage gateway always
|
|
102
|
+
* requires path-style addressing, so set `forcePathStyle: true` on your S3 client.
|
|
103
|
+
*/
|
|
104
|
+
interface NeonStorageEnv {
|
|
105
|
+
accessKeyId: string;
|
|
106
|
+
secretAccessKey: string;
|
|
107
|
+
/** S3-compatible endpoint URL for the branch. */
|
|
108
|
+
endpoint: string;
|
|
109
|
+
/** AWS region string (e.g. `us-east-2`). Injected as `AWS_REGION`. */
|
|
110
|
+
region: string;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* AI Gateway access for the branch (Preview). Present on `NeonEnv` only when the policy
|
|
114
|
+
* enables `preview.aiGateway`. `apiKey` is the minted credential's bearer (`api_token`);
|
|
115
|
+
* `baseUrl` is the gateway's OpenAI-dialect endpoint on the branch-scoped gateway host
|
|
116
|
+
* (`https://<branchId>-api.ai.<region>.…/ai-gateway/openai/v1`). Projects to the OpenAI SDK's
|
|
117
|
+
* standard env (`OPENAI_API_KEY`, `OPENAI_BASE_URL`), plus the `NEON_AI_GATEWAY_*` aliases.
|
|
118
|
+
*/
|
|
119
|
+
interface NeonAiGatewayEnv {
|
|
120
|
+
apiKey: string;
|
|
121
|
+
baseUrl: string;
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Empty record alias used as the "false" branch of the conditional namespace adds below.
|
|
125
|
+
* `Record<never, never>` is the no-op for intersection — the cleaner alternative to `{}`,
|
|
126
|
+
* which biome rejects (it means "any non-null", not "empty object").
|
|
127
|
+
*/
|
|
128
|
+
type NoNamespace = Record<never, never>;
|
|
129
|
+
/**
|
|
130
|
+
* Resolve a **static** service toggle (the value of `config.auth` / `config.dataApi`) to a
|
|
131
|
+
* type-level boolean. The whole-thing wrapping (`[T] extends […]`) turns off distribution
|
|
132
|
+
* so a union/`undefined` is checked as one unit:
|
|
133
|
+
*
|
|
134
|
+
* - `false` / `{ enabled: false }` / `undefined` → `false`
|
|
135
|
+
* - `true` / `{ enabled: true }` / any other object (`{}`, `{ enabled?: boolean }`) → `true`
|
|
136
|
+
* (a present toggle defaults to enabled)
|
|
137
|
+
* - the bare `boolean | ServiceToggle | undefined` (the default `Config` param, no literal
|
|
138
|
+
* info) → `false`, so an untyped policy yields just `{ postgres }`.
|
|
139
|
+
*/
|
|
140
|
+
type ServiceOn<T> = [T] extends [false] ? false : [T] extends [{
|
|
141
|
+
enabled: false;
|
|
142
|
+
}] ? false : [T] extends [undefined] ? false : [T] extends [true] ? true : [T] extends [{
|
|
143
|
+
enabled: true;
|
|
144
|
+
}] ? true : [T] extends [object] ? true : false;
|
|
145
|
+
/** True when `T` has at least one known key; `false` for `{}` / `never`. */
|
|
146
|
+
type HasKeys<T> = [keyof T] extends [never] ? false : true;
|
|
147
|
+
/**
|
|
148
|
+
* Whether the policy's **static** `preview` block declares at least one object-storage bucket
|
|
149
|
+
* (`preview.buckets`). Drives whether {@link NeonEnv} carries the `storage` namespace.
|
|
150
|
+
*
|
|
151
|
+
* The leading `[never]` guard is load-bearing: when a policy has no `preview` at all,
|
|
152
|
+
* `NonNullable<C["preview"]>` is `never`, and without the guard the `extends { … }` probe
|
|
153
|
+
* below would vacuously match (everything extends `never`-derived shapes) and `HasKeys<never>`
|
|
154
|
+
* would resolve `true`, wrongly adding the namespace. The guard short-circuits to `false`.
|
|
155
|
+
*/
|
|
156
|
+
type HasBuckets<C extends Config> = [NonNullable<C["preview"]>] extends [never] ? false : NonNullable<C["preview"]> extends {
|
|
157
|
+
buckets: infer B;
|
|
158
|
+
} ? HasKeys<NonNullable<B>> : false;
|
|
159
|
+
/**
|
|
160
|
+
* Whether the policy's **static** `preview` block enables the AI Gateway
|
|
161
|
+
* (`preview.aiGateway`). Drives whether {@link NeonEnv} carries the `aiGateway` namespace.
|
|
162
|
+
*
|
|
163
|
+
* The leading `[never]` guard is load-bearing for the same reason as {@link HasBuckets}: when
|
|
164
|
+
* a policy has no `preview`, `NonNullable<C["preview"]>` is `never`, and a naked `never` in the
|
|
165
|
+
* `extends` below would *distribute* (collapsing the result — and the whole `NeonEnv`
|
|
166
|
+
* intersection — to `never`). The tuple-wrapped guard short-circuits that to `false`.
|
|
167
|
+
*/
|
|
168
|
+
type AiGatewayOn<C extends Config> = [NonNullable<C["preview"]>] extends [never] ? false : NonNullable<C["preview"]> extends {
|
|
169
|
+
aiGateway: infer A;
|
|
170
|
+
} ? ServiceOn<NonNullable<A>> : false;
|
|
171
|
+
/**
|
|
172
|
+
* Static, namespaced shape of `fetchEnv` / `parseEnv`'s return value. Generic over the
|
|
173
|
+
* {@link Config} so the type system knows which optional namespaces are present.
|
|
174
|
+
*
|
|
175
|
+
* Because the secret-bearing toggles now live in the **static** top-level `config.auth` /
|
|
176
|
+
* `config.dataApi` (not inside a per-branch closure), the namespace presence is a direct
|
|
177
|
+
* read of those fields — no union-across-branches, no default-config escape hatch:
|
|
178
|
+
*
|
|
179
|
+
* - `postgres` is always present.
|
|
180
|
+
* - `auth` is added iff `config.auth` is statically enabled.
|
|
181
|
+
* - `dataApi` is added iff `config.dataApi` is statically enabled.
|
|
182
|
+
* - `storage` is added iff `config.preview.buckets` declares at least one bucket.
|
|
183
|
+
* - `aiGateway` is added iff `config.preview.aiGateway` is statically enabled.
|
|
184
|
+
*/
|
|
185
|
+
type NeonEnv<C extends Config = Config> = {
|
|
186
|
+
postgres: NeonPostgresEnv;
|
|
187
|
+
/**
|
|
188
|
+
* Branch identity (`NEON_BRANCH`). Optional because `parseEnv` only surfaces it when the
|
|
189
|
+
* var was injected; `fetchEnv` always populates it.
|
|
190
|
+
*/
|
|
191
|
+
branch?: NeonBranchEnv;
|
|
192
|
+
} & (ServiceOn<NonNullable<C["auth"]>> extends true ? {
|
|
193
|
+
auth: NeonAuthEnv;
|
|
194
|
+
} : NoNamespace) & (ServiceOn<NonNullable<C["dataApi"]>> extends true ? {
|
|
195
|
+
dataApi: NeonDataApiEnv;
|
|
196
|
+
} : NoNamespace) & (HasBuckets<C> extends true ? {
|
|
197
|
+
storage: NeonStorageEnv;
|
|
198
|
+
} : NoNamespace) & (AiGatewayOn<C> extends true ? {
|
|
199
|
+
aiGateway: NeonAiGatewayEnv;
|
|
200
|
+
} : NoNamespace);
|
|
201
|
+
/** The static `preview.functions` record of a config, or an empty record when absent. */
|
|
202
|
+
type PreviewFunctionsOf<C extends Config> = NonNullable<C["preview"]> extends {
|
|
203
|
+
functions: infer F;
|
|
204
|
+
} ? F : Record<never, never>;
|
|
205
|
+
/** The declared function slugs of a config (record keys), as a string union. */
|
|
206
|
+
type FunctionSlugOf<C extends Config> = Extract<keyof PreviewFunctionsOf<C>, string>;
|
|
207
|
+
/** The declared env-var keys of one function `S`, as a string union. */
|
|
208
|
+
type FunctionEnvKeysOf<C extends Config, S extends string> = S extends keyof PreviewFunctionsOf<C> ? NonNullable<PreviewFunctionsOf<C>[S]> extends {
|
|
209
|
+
env: infer E;
|
|
210
|
+
} ? Extract<keyof E, string> : never : never;
|
|
211
|
+
/**
|
|
212
|
+
* The extra `function` namespace added to `parseEnv`'s result when called with a function
|
|
213
|
+
* slug scope: the declared env-var keys for that function, each resolved to a `string`.
|
|
214
|
+
*/
|
|
215
|
+
type NeonFunctionEnv<C extends Config, S extends string> = {
|
|
216
|
+
function: Record<FunctionEnvKeysOf<C, S>, string>;
|
|
217
|
+
};
|
|
218
|
+
/**
|
|
219
|
+
* OS-level env-var keys grouped by the {@link NeonEnv} namespace they populate. Only the
|
|
220
|
+
* **input** vars `parseEnv` validates are listed — the output-only aliases in
|
|
221
|
+
* {@link NEON_ENV_VAR_KEYS} (`NEON_AI_GATEWAY_TOKEN`, …) are intentionally absent, so they
|
|
222
|
+
* are not selectable in a `parseEnv(config, keys)` filter. Keep in sync with
|
|
223
|
+
* {@link EnvKeyToProp}.
|
|
224
|
+
*/
|
|
225
|
+
interface EnvKeysByNamespace {
|
|
226
|
+
postgres: "DATABASE_URL" | "DATABASE_URL_UNPOOLED";
|
|
227
|
+
auth: "NEON_AUTH_BASE_URL" | "NEON_AUTH_JWKS_URL";
|
|
228
|
+
dataApi: "NEON_DATA_API_URL";
|
|
229
|
+
storage: "AWS_ACCESS_KEY_ID" | "AWS_SECRET_ACCESS_KEY" | "AWS_ENDPOINT_URL_S3" | "AWS_REGION";
|
|
230
|
+
aiGateway: "OPENAI_API_KEY" | "OPENAI_BASE_URL";
|
|
231
|
+
}
|
|
232
|
+
/** The {@link NeonEnv} namespace interface backing each namespace key. */
|
|
233
|
+
interface NamespaceEnv {
|
|
234
|
+
postgres: NeonPostgresEnv;
|
|
235
|
+
auth: NeonAuthEnv;
|
|
236
|
+
dataApi: NeonDataApiEnv;
|
|
237
|
+
storage: NeonStorageEnv;
|
|
238
|
+
aiGateway: NeonAiGatewayEnv;
|
|
239
|
+
}
|
|
240
|
+
/** OS-level env-var key → the camelCase property it sets on its namespace object. */
|
|
241
|
+
interface EnvKeyToProp {
|
|
242
|
+
DATABASE_URL: "databaseUrl";
|
|
243
|
+
DATABASE_URL_UNPOOLED: "databaseUrlUnpooled";
|
|
244
|
+
NEON_AUTH_BASE_URL: "baseUrl";
|
|
245
|
+
NEON_AUTH_JWKS_URL: "jwksUrl";
|
|
246
|
+
NEON_DATA_API_URL: "url";
|
|
247
|
+
AWS_ACCESS_KEY_ID: "accessKeyId";
|
|
248
|
+
AWS_SECRET_ACCESS_KEY: "secretAccessKey";
|
|
249
|
+
AWS_ENDPOINT_URL_S3: "endpoint";
|
|
250
|
+
AWS_REGION: "region";
|
|
251
|
+
OPENAI_API_KEY: "apiKey";
|
|
252
|
+
OPENAI_BASE_URL: "baseUrl";
|
|
253
|
+
}
|
|
254
|
+
/**
|
|
255
|
+
* The OS-level env-var keys selectable for a given policy: the union of input vars across
|
|
256
|
+
* exactly the namespaces {@link NeonEnv}<C> carries. Drives the typesafe autocomplete of the
|
|
257
|
+
* `keys` filter — selecting a var from a namespace the policy does not enable is a type error
|
|
258
|
+
* (e.g. `NEON_AUTH_BASE_URL` is only offered once the policy turns on `auth`).
|
|
259
|
+
*/
|
|
260
|
+
type SelectableEnvKey<C extends Config> = EnvKeysByNamespace[keyof NeonEnv<C> & keyof EnvKeysByNamespace];
|
|
261
|
+
/**
|
|
262
|
+
* The result shape of a **filtered** `parseEnv(config, keys)` call: the namespaced
|
|
263
|
+
* {@link NeonEnv} restricted to exactly the selected OS-level keys `K`. Namespaces with no
|
|
264
|
+
* selected key are dropped, and within a kept namespace only the selected properties survive
|
|
265
|
+
* — selecting just `["DATABASE_URL"]` yields `{ postgres: { databaseUrl: string } }`, with no
|
|
266
|
+
* `databaseUrlUnpooled`.
|
|
267
|
+
*
|
|
268
|
+
* The policy gating lives on the `parseEnv` overload (which binds `K` to
|
|
269
|
+
* {@link SelectableEnvKey}); this type only needs the selection, so it takes a bare
|
|
270
|
+
* `K extends string` and filters with `Extract`. The outer mapped type's `as` clause drops
|
|
271
|
+
* any namespace whose intersection with the selection is empty (`[…] extends [never]`,
|
|
272
|
+
* tuple-wrapped to switch off distribution); the inner one re-keys each selected OS var to its
|
|
273
|
+
* camelCase property and looks the value type up on the canonical namespace interface, so it
|
|
274
|
+
* stays correct if a field ever stops being a plain `string`.
|
|
275
|
+
*/
|
|
276
|
+
type FilteredNeonEnv<K extends string> = { [N in keyof EnvKeysByNamespace as [Extract<K, EnvKeysByNamespace[N]>] extends [never] ? never : N]: { [P in Extract<K, EnvKeysByNamespace[N]> as EnvKeyToProp[P & keyof EnvKeyToProp]]: NamespaceEnv[N][EnvKeyToProp[P & keyof EnvKeyToProp] & keyof NamespaceEnv[N]] } };
|
|
277
|
+
interface FetchEnvOptions {
|
|
278
|
+
/**
|
|
279
|
+
* Neon project id. **Required** — the management API addresses branches through their
|
|
280
|
+
* project. Resolve it in your CLI (e.g. neonctl) and pass it in.
|
|
281
|
+
*/
|
|
282
|
+
projectId: string;
|
|
283
|
+
/** Neon branch id (`br-…`). **Required.** Resolve names to ids before calling. */
|
|
284
|
+
branchId: string;
|
|
285
|
+
/**
|
|
286
|
+
* Neon API key. Resolved via the standard chain (option → `NEON_API_KEY` →
|
|
287
|
+
* `~/.config/neonctl/credentials.json`) when omitted. Ignored when a custom `api`
|
|
288
|
+
* is supplied.
|
|
289
|
+
*/
|
|
290
|
+
apiKey?: string;
|
|
291
|
+
/**
|
|
292
|
+
* Neon **management** API base URL (not the Auth base URL). Falls back to
|
|
293
|
+
* `NEON_API_HOST`, then production. Ignored when a custom `api` is supplied.
|
|
294
|
+
*/
|
|
295
|
+
apiHost?: string;
|
|
296
|
+
/**
|
|
297
|
+
* Inject a custom NeonApi adapter. Primarily used by tests; production callers can rely
|
|
298
|
+
* on the default real adapter built from `apiKey`.
|
|
299
|
+
*/
|
|
300
|
+
api?: NeonApi;
|
|
301
|
+
/**
|
|
302
|
+
* Role name to fetch credentials for. When omitted, the connection role is auto-picked:
|
|
303
|
+
* the only role on the branch, else Neon's default owner (`neondb_owner`), else the
|
|
304
|
+
* single role left after dropping the managed Auth/Data API roles
|
|
305
|
+
* (`authenticator`/`anonymous`/`authenticated`). Throws {@link PlatformError} with
|
|
306
|
+
* `PLATFORM_AMBIGUOUS_BRANCH_AUTH` only when more than one app role remains.
|
|
307
|
+
*/
|
|
308
|
+
roleName?: string;
|
|
309
|
+
/**
|
|
310
|
+
* Database name. When omitted, the only database on the branch is auto-picked; throws
|
|
311
|
+
* {@link PlatformError} with `PLATFORM_AMBIGUOUS_BRANCH_AUTH` if the branch has more
|
|
312
|
+
* than one database.
|
|
313
|
+
*/
|
|
314
|
+
databaseName?: string;
|
|
315
|
+
/**
|
|
316
|
+
* Env source used for one-time Auth keys that cannot be refetched after integration
|
|
317
|
+
* creation. Defaults to `process.env`; callers may layer values from `.env.local`.
|
|
318
|
+
*/
|
|
319
|
+
env?: NodeJS.ProcessEnv;
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* Resolve the project + branch this process should target, then fetch live Neon
|
|
323
|
+
* connection strings for that branch over the network. Async — calls the Neon API.
|
|
324
|
+
*
|
|
325
|
+
* Use this from build scripts and the `neon-env run` command, where top-level await is
|
|
326
|
+
* fine. For application code that needs a synchronous bootstrap (most frameworks: Drizzle
|
|
327
|
+
* config, Next.js, Vite, etc.), inject env vars via `neon-env run -- <cmd>` and use
|
|
328
|
+
* {@link parseEnv} instead — same {@link NeonEnv} shape, but a sync call against
|
|
329
|
+
* `process.env`.
|
|
330
|
+
*
|
|
331
|
+
* Filesystem- and env-agnostic: pass `projectId` and the target `branchId` explicitly
|
|
332
|
+
* (resolve them in your CLI, e.g. neonctl).
|
|
333
|
+
*
|
|
334
|
+
* ```ts
|
|
335
|
+
* import config from "../neon";
|
|
336
|
+
* import { fetchEnv } from "@neon/env";
|
|
337
|
+
*
|
|
338
|
+
* const env = await fetchEnv(config, { projectId: "patient-art-12345", branchId: "br-…" });
|
|
339
|
+
* const db = drizzle(neon(env.postgres.databaseUrl), { schema });
|
|
340
|
+
* ```
|
|
341
|
+
*
|
|
342
|
+
* The package does **not** mutate `process.env` or the filesystem itself.
|
|
343
|
+
*/
|
|
344
|
+
declare function fetchEnv<const C extends Config>(config: C, options: FetchEnvOptions): Promise<NeonEnv<C>>;
|
|
345
|
+
/**
|
|
346
|
+
* Synchronous, network-free counterpart to {@link fetchEnv}. Reads `process.env`, validates
|
|
347
|
+
* the required Neon env vars with zod, and returns the same {@link NeonEnv} shape — so the
|
|
348
|
+
* rest of your app touches `env.postgres.databaseUrl` instead of stringly-typed
|
|
349
|
+
* `process.env.DATABASE_URL` lookups.
|
|
350
|
+
*
|
|
351
|
+
* Designed for the **"env-vars-already-injected"** path:
|
|
352
|
+
* - You wrapped your dev command with `neon-env run -- <cmd>` or `neon dev`.
|
|
353
|
+
* - Your platform (Vercel, Fly, Railway, …) injected the vars via its own integration.
|
|
354
|
+
* - You are **inside a deployed Neon Function**, whose env was uploaded at `config apply`.
|
|
355
|
+
*
|
|
356
|
+
* Unlike the old API, `parseEnv` does **not** take a branch name: the secret set is now
|
|
357
|
+
* static (top-level `config.auth` / `config.dataApi`), so it reads those directly without
|
|
358
|
+
* evaluating the per-branch closure.
|
|
359
|
+
*
|
|
360
|
+
* The second argument is a **scope** or a **key filter**:
|
|
361
|
+
* - omitted — *external* scope (app bootstrap, build scripts, your dev machine). Returns the
|
|
362
|
+
* full `{ postgres, auth?, dataApi?, … }` the policy enables.
|
|
363
|
+
* - a **function slug** (a key of `config.preview.functions`) — *function* scope: you are
|
|
364
|
+
* running inside that function. Returns the same branch secrets **plus** a typed
|
|
365
|
+
* `function` namespace with the function's declared env-var keys.
|
|
366
|
+
* - an **array of OS-level env-var keys** (e.g. `["DATABASE_URL", "NEON_AUTH_BASE_URL"]`) —
|
|
367
|
+
* *filtered* mode: only those vars are required and returned, as a narrowed namespaced
|
|
368
|
+
* shape. The keys autocomplete from the policy ({@link SelectableEnvKey}), so you can only
|
|
369
|
+
* pick vars the policy actually enables. Use this when a process needs just a subset (a
|
|
370
|
+
* Next.js app that reads `DATABASE_URL` but not `DATABASE_URL_UNPOOLED`, say) and you don't
|
|
371
|
+
* want `parseEnv` to throw over vars you never use.
|
|
372
|
+
*
|
|
373
|
+
* Throws `PlatformError(EnvNotInjected)` listing every missing/invalid var when the env
|
|
374
|
+
* isn't fully populated, with a fix hint pointing back at `neon dev` / `neon-env run`.
|
|
375
|
+
*
|
|
376
|
+
* ```ts
|
|
377
|
+
* import config from "../neon";
|
|
378
|
+
* import { parseEnv } from "@neon/env";
|
|
379
|
+
*
|
|
380
|
+
* // External (app / build):
|
|
381
|
+
* const env = parseEnv(config);
|
|
382
|
+
* const db = drizzle(neon(env.postgres.databaseUrl), { schema });
|
|
383
|
+
*
|
|
384
|
+
* // Inside the "hello" function:
|
|
385
|
+
* const env = parseEnv(config, "hello");
|
|
386
|
+
* env.function.resendApiKey; // typed from hello's declared env keys
|
|
387
|
+
*
|
|
388
|
+
* // Filtered: only enforce + return the pooled URL.
|
|
389
|
+
* const { postgres } = parseEnv(config, ["DATABASE_URL"]);
|
|
390
|
+
* postgres.databaseUrl; // string — `databaseUrlUnpooled` is absent
|
|
391
|
+
* ```
|
|
392
|
+
*/
|
|
393
|
+
declare function parseEnv<const C extends Config>(config: C): NeonEnv<C>;
|
|
394
|
+
declare function parseEnv<const C extends Config, const K extends SelectableEnvKey<C>>(config: C, keys: readonly K[]): FilteredNeonEnv<K>;
|
|
395
|
+
declare function parseEnv<const C extends Config, const S extends FunctionSlugOf<C>>(config: C, scope: S): NeonEnv<C> & NeonFunctionEnv<C, S>;
|
|
396
|
+
/**
|
|
397
|
+
* Project a fully-resolved {@link NeonEnv} into the OS-level `{ KEY: value }` pairs used
|
|
398
|
+
* for cross-process transport. Named after the web-platform `.entries()` convention
|
|
399
|
+
* (`URLSearchParams` / `Headers` / `FormData`); returns a `Record` rather than an
|
|
400
|
+
* iterator of tuples since that's the shape env injection needs (wrap with
|
|
401
|
+
* `Object.entries(...)` if you want literal `[key, value]` pairs). Used by `neon-env run`
|
|
402
|
+
* to inject the vars into a subprocess's `process.env`.
|
|
403
|
+
*
|
|
404
|
+
* Walks the value at runtime so it works for any `NeonEnv<C>` regardless of which
|
|
405
|
+
* conditional namespaces are present.
|
|
406
|
+
*/
|
|
407
|
+
declare function toEntries(env: NeonEnv<Config>): Record<string, string>;
|
|
408
|
+
//#endregion
|
|
409
|
+
export { FetchEnvOptions, FilteredNeonEnv, FunctionSlugOf, NEON_ENV_VAR_KEYS, NeonAiGatewayEnv, NeonAuthEnv, NeonBranchEnv, NeonDataApiEnv, NeonEnv, NeonFunctionEnv, NeonPostgresEnv, NeonStorageEnv, SelectableEnvKey, fetchEnv, parseEnv, toEntries };
|
|
410
|
+
//# sourceMappingURL=env.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"env.d.ts","names":[],"sources":["../../src/lib/env.ts"],"mappings":"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"}
|