@geekmidas/envkit 10.0.0-alpha.99 → 10.0.0

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.
Files changed (83) hide show
  1. package/CHANGELOG.md +117 -0
  2. package/README.md +2 -2
  3. package/dist/{EnvironmentBuilder-Rxq657gm.mjs → EnvironmentBuilder-CFen3oIg.mjs} +6 -5
  4. package/dist/EnvironmentBuilder-CFen3oIg.mjs.map +1 -0
  5. package/dist/{EnvironmentBuilder-DTZ8o3se.d.cts → EnvironmentBuilder-CNgcdzSR.d.cts} +6 -6
  6. package/dist/EnvironmentBuilder-CNgcdzSR.d.cts.map +1 -0
  7. package/dist/{EnvironmentBuilder-wJH3EBbJ.cjs → EnvironmentBuilder-DDgLJAAo.cjs} +17 -17
  8. package/dist/EnvironmentBuilder-DDgLJAAo.cjs.map +1 -0
  9. package/dist/{EnvironmentBuilder-DTZ8o3se.d.mts → EnvironmentBuilder-DHfDXJUm.d.mts} +6 -6
  10. package/dist/EnvironmentBuilder-DHfDXJUm.d.mts.map +1 -0
  11. package/dist/{EnvironmentParser-BmJLlm5_.d.cts → EnvironmentParser-BY1oCUsc.d.mts} +15 -3
  12. package/dist/EnvironmentParser-BY1oCUsc.d.mts.map +1 -0
  13. package/dist/{EnvironmentParser-CmhDxs77.cjs → EnvironmentParser-Bzg5yXG2.cjs} +34 -34
  14. package/dist/EnvironmentParser-Bzg5yXG2.cjs.map +1 -0
  15. package/dist/{EnvironmentParser-BmJLlm5_.d.mts → EnvironmentParser-DoooZm8n.d.cts} +15 -3
  16. package/dist/EnvironmentParser-DoooZm8n.d.cts.map +1 -0
  17. package/dist/{EnvironmentParser-X6Z-jryw.mjs → EnvironmentParser-taAKfzT7.mjs} +12 -10
  18. package/dist/EnvironmentParser-taAKfzT7.mjs.map +1 -0
  19. package/dist/SnifferEnvironmentParser.cjs +7 -5
  20. package/dist/SnifferEnvironmentParser.cjs.map +1 -1
  21. package/dist/SnifferEnvironmentParser.d.cts +9 -5
  22. package/dist/SnifferEnvironmentParser.d.cts.map +1 -1
  23. package/dist/SnifferEnvironmentParser.d.mts +9 -5
  24. package/dist/SnifferEnvironmentParser.d.mts.map +1 -1
  25. package/dist/SnifferEnvironmentParser.mjs +5 -3
  26. package/dist/SnifferEnvironmentParser.mjs.map +1 -1
  27. package/dist/{rolldown-runtime-VH7oDXx4.cjs → chunk-CUT6urMc.cjs} +10 -8
  28. package/dist/credentials.cjs +11 -9
  29. package/dist/credentials.cjs.map +1 -1
  30. package/dist/credentials.d.cts +3 -3
  31. package/dist/credentials.d.cts.map +1 -1
  32. package/dist/credentials.d.mts +3 -3
  33. package/dist/credentials.d.mts.map +1 -1
  34. package/dist/credentials.mjs +8 -4
  35. package/dist/credentials.mjs.map +1 -1
  36. package/dist/index.cjs +4 -4
  37. package/dist/index.d.cts +7 -5
  38. package/dist/index.d.cts.map +1 -1
  39. package/dist/index.d.mts +7 -5
  40. package/dist/index.d.mts.map +1 -1
  41. package/dist/index.mjs +4 -3
  42. package/dist/sst.cjs +48 -59
  43. package/dist/sst.cjs.map +1 -1
  44. package/dist/sst.d.cts +26 -35
  45. package/dist/sst.d.cts.map +1 -1
  46. package/dist/sst.d.mts +26 -35
  47. package/dist/sst.d.mts.map +1 -1
  48. package/dist/sst.mjs +48 -58
  49. package/dist/sst.mjs.map +1 -1
  50. package/docs/api-reference.md +302 -0
  51. package/docs/async-secrets-design.md +355 -0
  52. package/examples/basic-usage.ts +386 -0
  53. package/package.json +2 -9
  54. package/src/EnvironmentBuilder.ts +192 -0
  55. package/src/EnvironmentParser.ts +330 -0
  56. package/src/SnifferEnvironmentParser.ts +334 -0
  57. package/src/SstEnvValidator.ts +369 -0
  58. package/src/SstEnvironmentBuilder.ts +343 -0
  59. package/src/__tests__/ConfigParser.spec.ts +394 -0
  60. package/src/__tests__/EnvironmentBuilder.spec.ts +254 -0
  61. package/src/__tests__/EnvironmentParser.spec.ts +839 -0
  62. package/src/__tests__/SnifferEnvironmentParser.spec.ts +644 -0
  63. package/src/__tests__/SstEnvValidator.spec.ts +236 -0
  64. package/src/__tests__/SstEnvironmentBuilder.spec.ts +397 -0
  65. package/src/__tests__/credentials.integration.spec.ts +239 -0
  66. package/src/__tests__/credentials.spec.ts +136 -0
  67. package/src/__tests__/formatter.spec.ts +268 -0
  68. package/src/__tests__/sst.spec.ts +437 -0
  69. package/src/credentials.ts +112 -0
  70. package/src/formatter.ts +146 -0
  71. package/src/index.ts +24 -0
  72. package/src/sst.ts +76 -0
  73. package/sst-env.d.ts +8 -0
  74. package/tsconfig.json +9 -0
  75. package/tsdown.config.ts +18 -0
  76. package/dist/EnvironmentBuilder-DTZ8o3se.d.cts.map +0 -1
  77. package/dist/EnvironmentBuilder-DTZ8o3se.d.mts.map +0 -1
  78. package/dist/EnvironmentBuilder-Rxq657gm.mjs.map +0 -1
  79. package/dist/EnvironmentBuilder-wJH3EBbJ.cjs.map +0 -1
  80. package/dist/EnvironmentParser-BmJLlm5_.d.cts.map +0 -1
  81. package/dist/EnvironmentParser-BmJLlm5_.d.mts.map +0 -1
  82. package/dist/EnvironmentParser-CmhDxs77.cjs.map +0 -1
  83. package/dist/EnvironmentParser-X6Z-jryw.mjs.map +0 -1
@@ -0,0 +1,355 @@
1
+ # Async Secrets Resolution Design
2
+
3
+ ## Problem Statement
4
+
5
+ Applications often need to fetch sensitive configuration values (secrets) from external providers like HashiCorp Vault, AWS Secrets Manager, or other secret management systems. The current `EnvironmentParser` only supports synchronous parsing of environment variables, which doesn't accommodate async secret fetching.
6
+
7
+ Additionally, environment variables for secrets typically contain **references** to the actual secret (e.g., a Vault path), not the secret value itself:
8
+
9
+ ```bash
10
+ # Environment variables
11
+ DB_HOST=localhost # Actual value
12
+ DB_PASSWORD=/vault/prod/db # Reference to secret, not the actual password
13
+ API_KEY=/vault/prod/api # Reference to secret
14
+ ```
15
+
16
+ ## Proposed Solution
17
+
18
+ Extend `EnvironmentParser` with:
19
+ 1. A separate `getSecret()` getter to distinguish secrets from regular env vars
20
+ 2. A configurable `secretsResolver` that fetches actual values from refs
21
+ 3. A cache to avoid redundant fetches for the same ref
22
+ 4. An `echoSecretsResolver` for testing that returns refs as values
23
+
24
+ ## API Design
25
+
26
+ ### Constructor Options
27
+
28
+ ```typescript
29
+ interface EnvironmentParserOptions {
30
+ /**
31
+ * Function to resolve secret references to actual values.
32
+ * Receives an array of refs (values from env vars marked as secrets).
33
+ * Returns a Map of ref → resolved value.
34
+ */
35
+ secretsResolver?: SecretsResolver;
36
+ }
37
+
38
+ type SecretsResolver = (refs: string[]) => Promise<Map<string, string>>;
39
+ ```
40
+
41
+ ### Getters
42
+
43
+ ```typescript
44
+ parser.create((get, getSecret) => ({
45
+ // Regular env var - resolved synchronously
46
+ host: get('DB_HOST').string(),
47
+ port: get('PORT').string().transform(Number),
48
+
49
+ // Secret env var - resolved asynchronously via secretsResolver
50
+ // The env var value is treated as a ref, not the actual value
51
+ password: getSecret('DB_PASSWORD').string(),
52
+ apiKey: getSecret('API_KEY').string(),
53
+ }));
54
+ ```
55
+
56
+ ### Parsed Config Types
57
+
58
+ ```typescript
59
+ // Regular values are their actual types
60
+ config.host // string
61
+ config.port // number
62
+
63
+ // Secret values are Promises of their types
64
+ config.password // Promise<string>
65
+ config.apiKey // Promise<string>
66
+
67
+ // Usage
68
+ const password = await config.password;
69
+ ```
70
+
71
+ ### Built-in Resolvers
72
+
73
+ ```typescript
74
+ import { echoSecretsResolver } from '@geekmidas/envkit';
75
+
76
+ /**
77
+ * Echo resolver returns the ref as the value.
78
+ * Useful for testing where the "ref" IS the actual test value.
79
+ */
80
+ export const echoSecretsResolver: SecretsResolver = async (refs) =>
81
+ new Map(refs.map((ref) => [ref, ref]));
82
+ ```
83
+
84
+ ## Resolution Flow
85
+
86
+ ```
87
+ ┌─────────────────────────────────────────────────────────────────────┐
88
+ │ parse() called │
89
+ └─────────────────────────────────────────────────────────────────────┘
90
+ │
91
+ ▼
92
+ ┌─────────────────────────────────────────────────────────────────────┐
93
+ │ 1. Regular env vars (get) are parsed synchronously as normal │
94
+ │ config.host = "localhost" │
95
+ │ config.port = 3000 │
96
+ └─────────────────────────────────────────────────────────────────────┘
97
+ │
98
+ ▼
99
+ ┌─────────────────────────────────────────────────────────────────────┐
100
+ │ 2. Secret env vars (getSecret) return Promises │
101
+ │ config.password = Promise<string> │
102
+ │ config.apiKey = Promise<string> │
103
+ └─────────────────────────────────────────────────────────────────────┘
104
+ │
105
+ ▼
106
+ ┌─────────────────────────────────────────────────────────────────────┐
107
+ │ 3. When Promise is awaited: │
108
+ │ a. Read ref from env var (e.g., "/vault/prod/db") │
109
+ │ b. Check cache - if cached, return cached value │
110
+ │ c. If not cached, call secretsResolver([ref]) │
111
+ │ d. Cache the resolved value │
112
+ │ e. Apply Zod validation/transformation │
113
+ │ f. Return validated value │
114
+ └─────────────────────────────────────────────────────────────────────┘
115
+ ```
116
+
117
+ ## Caching Strategy
118
+
119
+ A resolved secrets cache prevents redundant API calls:
120
+
121
+ ```typescript
122
+ // Internal cache (per EnvironmentParser instance)
123
+ private resolvedCache = new Map<string, string>();
124
+
125
+ async resolveSecret(ref: string): Promise<string> {
126
+ // Return cached value if available
127
+ if (this.resolvedCache.has(ref)) {
128
+ return this.resolvedCache.get(ref)!;
129
+ }
130
+
131
+ // Fetch from resolver
132
+ const resolved = await this.secretsResolver([ref]);
133
+ const value = resolved.get(ref);
134
+
135
+ if (value === undefined) {
136
+ throw new Error(`Secret resolver did not return value for ref: ${ref}`);
137
+ }
138
+
139
+ // Cache for future use
140
+ this.resolvedCache.set(ref, value);
141
+ return value;
142
+ }
143
+ ```
144
+
145
+ Benefits:
146
+ - Same ref accessed multiple times → single resolver call
147
+ - Consistent values within a parser instance
148
+ - Reduces load on secret providers
149
+
150
+ ## Usage Examples
151
+
152
+ ### Production with Vault
153
+
154
+ ```typescript
155
+ import { EnvironmentParser } from '@geekmidas/envkit';
156
+
157
+ // Vault resolver implementation
158
+ const vaultResolver: SecretsResolver = async (refs) => {
159
+ const secrets = await vaultClient.batchRead(refs);
160
+ return new Map(refs.map((ref, i) => [ref, secrets[i].value]));
161
+ };
162
+
163
+ const parser = new EnvironmentParser(process.env, {
164
+ secretsResolver: vaultResolver,
165
+ });
166
+
167
+ const config = parser.create((get, getSecret) => ({
168
+ database: {
169
+ host: get('DB_HOST').string(),
170
+ port: get('DB_PORT').coerce.number(),
171
+ password: getSecret('DB_PASSWORD').string(),
172
+ },
173
+ api: {
174
+ baseUrl: get('API_BASE_URL').string().url(),
175
+ key: getSecret('API_KEY').string().min(32),
176
+ },
177
+ })).parse();
178
+
179
+ // Use in service registration
180
+ const databaseService = {
181
+ serviceName: 'database' as const,
182
+ async register(envParser: EnvironmentParser<{}>) {
183
+ const config = envParser.create((get, getSecret) => ({
184
+ host: get('DB_HOST').string(),
185
+ password: getSecret('DB_PASSWORD').string(),
186
+ })).parse();
187
+
188
+ // Await the secret
189
+ const password = await config.password;
190
+
191
+ return new Database({
192
+ host: config.host,
193
+ password,
194
+ });
195
+ },
196
+ };
197
+ ```
198
+
199
+ ### Testing with Echo Resolver
200
+
201
+ ```typescript
202
+ import { EnvironmentParser, echoSecretsResolver } from '@geekmidas/envkit';
203
+
204
+ describe('DatabaseService', () => {
205
+ it('should connect with credentials', async () => {
206
+ // In tests, the "ref" IS the actual test value
207
+ const env = {
208
+ DB_HOST: 'localhost',
209
+ DB_PORT: '5432',
210
+ DB_PASSWORD: 'test-password-123', // This IS the password for tests
211
+ };
212
+
213
+ const parser = new EnvironmentParser(env, {
214
+ secretsResolver: echoSecretsResolver,
215
+ });
216
+
217
+ const service = await databaseService.register(parser);
218
+
219
+ expect(service.isConnected()).toBe(true);
220
+ });
221
+ });
222
+ ```
223
+
224
+ ### AWS Secrets Manager
225
+
226
+ ```typescript
227
+ import { SecretsManagerClient, BatchGetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
228
+
229
+ const awsResolver: SecretsResolver = async (refs) => {
230
+ const client = new SecretsManagerClient({});
231
+ const command = new BatchGetSecretValueCommand({
232
+ SecretIdList: refs,
233
+ });
234
+
235
+ const response = await client.send(command);
236
+ const result = new Map<string, string>();
237
+
238
+ for (const secret of response.SecretValues ?? []) {
239
+ if (secret.ARN && secret.SecretString) {
240
+ result.set(secret.ARN, secret.SecretString);
241
+ }
242
+ }
243
+
244
+ return result;
245
+ };
246
+ ```
247
+
248
+ ## Type Definitions
249
+
250
+ ```typescript
251
+ /**
252
+ * Function type for resolving secret references to actual values.
253
+ */
254
+ export type SecretsResolver = (refs: string[]) => Promise<Map<string, string>>;
255
+
256
+ /**
257
+ * Extended getter that includes secret() method.
258
+ */
259
+ export type SecretEnvFetcher<TPath extends string = string> = (
260
+ name: TPath,
261
+ ) => typeof z;
262
+
263
+ /**
264
+ * Builder function signature with both getters.
265
+ */
266
+ export type EnvironmentBuilderWithSecrets<TResponse extends EmptyObject> = (
267
+ get: EnvFetcher,
268
+ getSecret: SecretEnvFetcher,
269
+ ) => TResponse;
270
+
271
+ /**
272
+ * Infers config type, wrapping secret values in Promise.
273
+ */
274
+ export type InferConfigWithSecrets<T extends EmptyObject> = {
275
+ [K in keyof T]: T[K] extends SecretSchema<infer U>
276
+ ? Promise<U>
277
+ : T[K] extends z.ZodSchema
278
+ ? z.infer<T[K]>
279
+ : T[K] extends Record<string, unknown>
280
+ ? InferConfigWithSecrets<T[K]>
281
+ : T[K];
282
+ };
283
+ ```
284
+
285
+ ## Error Handling
286
+
287
+ ### Missing Resolver
288
+
289
+ ```typescript
290
+ // If getSecret() is used but no resolver provided
291
+ const parser = new EnvironmentParser(env); // no resolver
292
+
293
+ const config = parser.create((get, getSecret) => ({
294
+ password: getSecret('DB_PASSWORD').string(),
295
+ })).parse();
296
+
297
+ await config.password;
298
+ // Error: SecretsResolver is required when using getSecret().
299
+ // Configure it via EnvironmentParser options.
300
+ ```
301
+
302
+ ### Missing Ref in Environment
303
+
304
+ ```typescript
305
+ // If env var doesn't exist
306
+ const env = { DB_HOST: 'localhost' }; // DB_PASSWORD not set
307
+
308
+ const config = parser.create((get, getSecret) => ({
309
+ password: getSecret('DB_PASSWORD').string(),
310
+ })).parse();
311
+
312
+ await config.password;
313
+ // Error: Environment variable "DB_PASSWORD" is not defined.
314
+ // Expected a secret reference.
315
+ ```
316
+
317
+ ### Resolver Doesn't Return Value
318
+
319
+ ```typescript
320
+ // If resolver doesn't return value for a ref
321
+ const brokenResolver: SecretsResolver = async (refs) => new Map();
322
+
323
+ await config.password;
324
+ // Error: Secret resolver did not return value for ref: /vault/prod/db
325
+ ```
326
+
327
+ ## Migration Path
328
+
329
+ Existing code using `EnvironmentParser` continues to work unchanged:
330
+
331
+ ```typescript
332
+ // Before (still works)
333
+ const config = parser.create((get) => ({
334
+ port: get('PORT').string().transform(Number),
335
+ })).parse();
336
+
337
+ // After (opt-in to secrets)
338
+ const config = parser.create((get, getSecret) => ({
339
+ port: get('PORT').string().transform(Number),
340
+ password: getSecret('DB_PASSWORD').string(),
341
+ })).parse();
342
+ ```
343
+
344
+ ## Open Questions
345
+
346
+ 1. **Batch resolution timing**: Should we batch all secret resolutions when `parse()` is called, or resolve lazily when each Promise is awaited?
347
+ - **Lazy (proposed)**: Each secret resolved on first await, cached for subsequent access
348
+ - **Eager**: All secrets resolved upfront in parse(), requires parseAsync()
349
+
350
+ 2. **Cache scope**: Should the cache be per-parser instance or global?
351
+ - **Per-instance (proposed)**: Isolated, predictable behavior
352
+ - **Global**: More efficient for multiple parsers with same refs
353
+
354
+ 3. **Cache invalidation**: Should there be a way to clear the cache?
355
+ - Could add `parser.clearSecretCache()` method if needed