@sebspark/environment 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @sebspark/environment
+
+## 0.1.3
+
+### Patch Changes
+
+- 66ac832: * Upgraded to TypeScript 7
+  - Replaced tsup with tsdown for package builds
+  - Fixed cli-tester stdout parsing, resolving flaky e2e tests across the repo
+  - Patched vulnerable transitive dependencies (uuid, socket.io-parser, and others)
+
+## 0.1.2
+
+### Patch Changes
+
+- b5f1b3f: add mergeEnvironment helper function
+
+## 0.1.1
+
+### Patch Changes
+
+- 061b497: adjust filepath and add support for local env
+
+## 0.1.0
+
+### Minor Changes
+
+- 626c170: add initSecretStore function and tests
+
+## 0.0.4
+
+### Patch Changes
+
+- 7d8cc98: Dependabot dependency updates
+
+## 0.0.3
+
+### Patch Changes
+
+- 736a0b3: No bundling of packages in packages
+
+## 0.0.1
+
+### Patch Changes
+
+- 49ca25b: feat: publish @sebspark/environment

package/README.md

@@ -1,3 +1,71 @@
 # `@sebspark/environment`
 
-Environment
+Utilities for reading environment variables and secrets in a type-safe, lazy way.
+
+## `initEnvironment<T>()`
+
+Returns a typed proxy that reads from `process.env` on each property access. Required variables are asserted at access time — an error is thrown if the value is missing.
+
+```typescript
+import { initEnvironment } from '@sebspark/environment'
+
+type Env = {
+  API_URL: string
+  PORT: string
+}
+
+const env = initEnvironment<Env>()
+
+env.API_URL      // reads process.env.API_URL, throws if missing
+env.optional.PORT // reads process.env.PORT, returns undefined if missing
+```
+
+Values are cached after the first access.
+
+## `initSecretStore<T>(opts?)`
+
+Returns a typed proxy that reads secrets from the filesystem. Useful for Kubernetes-mounted secrets where each secret is a file named after the key.
+
+```typescript
+import { initSecretStore } from '@sebspark/environment'
+
+type Secrets = {
+  DB_PASSWORD: string
+  API_KEY: string
+}
+
+const secrets = initSecretStore<Secrets>({
+  dir: '/var/secrets',   // directory containing secret files (optional)
+  fallback: true,        // fall back to process.env if file is missing (optional)
+})
+
+secrets.DB_PASSWORD // reads /var/secrets/DB_PASSWORD
+```
+
+Options:
+
+| Option | Type | Description |
+|---|---|---|
+| `dir` | `string` | Directory to read secret files from. Defaults to CWD. |
+| `fallback` | `boolean \| Partial<T>` | If `true`, falls back to `process.env`. If an object, uses its values as fallback. |
+
+Values are cached after the first access. An error is thrown if the secret cannot be resolved.
+
+## `mergeEnvironments(env, secrets)`
+
+Merges the results of `initEnvironment` and `initSecretStore` into a single typed proxy. Secrets take precedence over environment variables for overlapping keys. Falls back to the environment proxy if a secret is not found.
+
+```typescript
+import { initEnvironment, initSecretStore, mergeEnvironments } from '@sebspark/environment'
+
+type Env = { API_URL: string; DB_PASSWORD: string }
+type Secrets = { DB_PASSWORD: string }
+
+const env = initEnvironment<Env>()
+const secrets = initSecretStore<Secrets>({ dir: '/var/secrets', fallback: true })
+
+export const Environment = mergeEnvironments(env, secrets)
+
+Environment.API_URL     // from process.env
+Environment.DB_PASSWORD // from /var/secrets/DB_PASSWORD, falls back to process.env
+```

package/dist/index.d.mts

@@ -1,16 +1,16 @@
 //#region src/index.d.ts
-declare const initEnvironment: <T extends Record<string, string>>() => T & {
+export declare const initEnvironment: <T extends Record<string, string>>() => T & {
   optional: Partial<T>;
 } & {
   [key: string]: string;
 };
+export declare const mergeEnvironments: <T extends Record<string, string>, U extends Record<string, string>>(env: T, secrets: U) => T & U;
 type SecretStoreOptions<T> = {
   dir?: string;
   fallback?: boolean | Partial<T>;
 };
-declare const initSecretStore: <T extends Record<string, string>>(opts?: SecretStoreOptions<T>) => T & {
+export declare const initSecretStore: <T extends Record<string, string>>(opts?: SecretStoreOptions<T>) => T & {
   [key: string]: string;
 };
 //#endregion
-export { initEnvironment, initSecretStore };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";cAIa,eAAA,aAA6B,MAAA,uBAiCnC,CAAA;EAAM,QAAA,EAAU,OAAA,CAAQ,CAAA;AAAA;EAAA,CAAU,GAAA;AAAA;AAAA,KAGpC,kBAAA;EACH,GAAA;EACA,QAAA,aAAqB,OAAA,CAAQ,CAAA;AAAA;AAAA,cAGlB,eAAA,aAA6B,MAAA,kBACxC,IAAA,GAAO,kBAAA,CAAmB,CAAA,MAwCrB,CAAA;EAAA,CAAO,GAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";qBAIa,kBAAmB,UAAU,6BAiCnC;EAAM,UAAU,QAAQ;;GAAU;;qBAG5B,oBACX,UAAU,wBACV,UAAU,wBAAsB,KAE3B,GAAC,SACG,MACR,IAAI;KAYF,mBAAmB;EACtB;EACA,qBAAqB,QAAQ;;qBAGlB,kBAAmB,UAAU,wBAAsB,OACvD,mBAAmB,OAwCrB;GAAO"}

package/dist/index.mjs

@@ -20,6 +20,14 @@ const initEnvironment = () => {
 		return environmentCache[key];
 	} });
 };
+const mergeEnvironments = (env, secrets) => new Proxy({}, { get(_, key) {
+	if (typeof key !== "string") return void 0;
+	try {
+		return secrets[key];
+	} catch {
+		return env[key];
+	}
+} });
 const initSecretStore = (opts) => {
 	const secretCache = {};
 	const { dir, fallback } = opts ?? {};
@@ -28,7 +36,8 @@ const initSecretStore = (opts) => {
 		if (key in secretCache) return secretCache[key];
 		const filePath = dir ? join(dir, key) : key;
 		try {
-			secretCache[key] = readFileSync(filePath, "utf-8").trim();
+			const value = readFileSync(filePath, "utf-8").trim();
+			secretCache[key] = value;
 			return secretCache[key];
 		} catch {}
 		if (fallback === true) {
@@ -45,6 +54,6 @@ const initSecretStore = (opts) => {
 	} });
 };
 //#endregion
-export { initEnvironment, initSecretStore };
+export { initEnvironment, initSecretStore, mergeEnvironments };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import assert from 'node:assert'\nimport { readFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nexport const initEnvironment = <T extends Record<string, string>>() => {\n  const environmentCache: Record<string, string | undefined> = {}\n\n  return new Proxy(\n    {},\n    {\n      get(_, k: keyof T | 'optional' | string | symbol) {\n        const key = k as string\n        if (key === 'optional') {\n          return new Proxy(\n            {},\n            {\n              get(_, k: keyof T | string | symbol) {\n                const key = k as string\n                if (key in environmentCache) {\n                  return environmentCache[key]\n                }\n                const { [key]: value } = process.env\n                environmentCache[key] = value\n                return environmentCache[key]\n              },\n            }\n          ) as T\n        }\n        if (key in environmentCache) {\n          return environmentCache[key]\n        }\n        const { [key]: value } = process.env\n        assert(value, `${key} is required`)\n        environmentCache[key] = value\n        return environmentCache[key]\n      },\n    }\n  ) as T & { optional: Partial<T> } & { [key: string]: string }\n}\n\ntype SecretStoreOptions<T> = {\n  dir?: string\n  fallback?: boolean | Partial<T>\n}\n\nexport const initSecretStore = <T extends Record<string, string>>(\n  opts?: SecretStoreOptions<T>\n) => {\n  const secretCache: Record<string, string | undefined> = {}\n  const { dir, fallback } = opts ?? {}\n\n  return new Proxy(\n    {},\n    {\n      get(_, k: keyof T | string | symbol) {\n        const key = k as string\n        if (key in secretCache) {\n          return secretCache[key]\n        }\n\n        // 1. Try reading from file (dir/KEY or just KEY if no dir)\n        const filePath = dir ? join(dir, key) : key\n        try {\n          const value = readFileSync(filePath, 'utf-8').trim()\n          secretCache[key] = value\n          return secretCache[key]\n        } catch {\n          // file not found — continue to fallback\n        }\n\n        // 2. Try fallback\n        if (fallback === true) {\n          // auto-read from process.env using the same key name\n          const { [key]: value } = process.env\n          if (value !== undefined) {\n            secretCache[key] = value\n            return secretCache[key]\n          }\n        } else if (fallback && key in fallback) {\n          secretCache[key] = fallback[key as keyof T] as string\n          return secretCache[key]\n        }\n\n        throw new Error(`Secret ${key} is required`)\n      },\n    }\n  ) as T & { [key: string]: string }\n}\n"],"mappings":";;;;AAIA,MAAa,wBAA0D;CACrE,MAAM,mBAAuD,EAAE;CAE/D,OAAO,IAAI,MACT,EAAE,EACF,EACE,IAAI,GAAG,GAA2C;EAChD,MAAM,MAAM;EACZ,IAAI,QAAQ,YACV,OAAO,IAAI,MACT,EAAE,EACF,EACE,IAAI,GAAG,GAA8B;GACnC,MAAM,MAAM;GACZ,IAAI,OAAO,kBACT,OAAO,iBAAiB;GAE1B,MAAM,GAAG,MAAM,UAAU,QAAQ;GACjC,iBAAiB,OAAO;GACxB,OAAO,iBAAiB;KAE3B,CACF;EAEH,IAAI,OAAO,kBACT,OAAO,iBAAiB;EAE1B,MAAM,GAAG,MAAM,UAAU,QAAQ;EACjC,OAAO,OAAO,GAAG,IAAI,cAAc;EACnC,iBAAiB,OAAO;EACxB,OAAO,iBAAiB;IAE3B,CACF;;AAQH,MAAa,mBACX,SACG;CACH,MAAM,cAAkD,EAAE;CAC1D,MAAM,EAAE,KAAK,aAAa,QAAQ,EAAE;CAEpC,OAAO,IAAI,MACT,EAAE,EACF,EACE,IAAI,GAAG,GAA8B;EACnC,MAAM,MAAM;EACZ,IAAI,OAAO,aACT,OAAO,YAAY;EAIrB,MAAM,WAAW,MAAM,KAAK,KAAK,IAAI,GAAG;EACxC,IAAI;GAEF,YAAY,OADE,aAAa,UAAU,QAAQ,CAAC,MACtB;GACxB,OAAO,YAAY;UACb;EAKR,IAAI,aAAa,MAAM;GAErB,MAAM,GAAG,MAAM,UAAU,QAAQ;GACjC,IAAI,UAAU,KAAA,GAAW;IACvB,YAAY,OAAO;IACnB,OAAO,YAAY;;SAEhB,IAAI,YAAY,OAAO,UAAU;GACtC,YAAY,OAAO,SAAS;GAC5B,OAAO,YAAY;;EAGrB,MAAM,IAAI,MAAM,UAAU,IAAI,cAAc;IAE/C,CACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import assert from 'node:assert'\nimport { readFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nexport const initEnvironment = <T extends Record<string, string>>() => {\n  const environmentCache: Record<string, string | undefined> = {}\n\n  return new Proxy(\n    {},\n    {\n      get(_, k: keyof T | 'optional' | string | symbol) {\n        const key = k as string\n        if (key === 'optional') {\n          return new Proxy(\n            {},\n            {\n              get(_, k: keyof T | string | symbol) {\n                const key = k as string\n                if (key in environmentCache) {\n                  return environmentCache[key]\n                }\n                const { [key]: value } = process.env\n                environmentCache[key] = value\n                return environmentCache[key]\n              },\n            }\n          ) as T\n        }\n        if (key in environmentCache) {\n          return environmentCache[key]\n        }\n        const { [key]: value } = process.env\n        assert(value, `${key} is required`)\n        environmentCache[key] = value\n        return environmentCache[key]\n      },\n    }\n  ) as T & { optional: Partial<T> } & { [key: string]: string }\n}\n\nexport const mergeEnvironments = <\n  T extends Record<string, string>,\n  U extends Record<string, string>,\n>(\n  env: T,\n  secrets: U\n): T & U =>\n  new Proxy({} as T & U, {\n    get(_, key) {\n      if (typeof key !== 'string') return undefined\n      try {\n        return (secrets as Record<string, string>)[key]\n      } catch {\n        return (env as Record<string, string>)[key]\n      }\n    },\n  })\n\ntype SecretStoreOptions<T> = {\n  dir?: string\n  fallback?: boolean | Partial<T>\n}\n\nexport const initSecretStore = <T extends Record<string, string>>(\n  opts?: SecretStoreOptions<T>\n) => {\n  const secretCache: Record<string, string | undefined> = {}\n  const { dir, fallback } = opts ?? {}\n\n  return new Proxy(\n    {},\n    {\n      get(_, k: keyof T | string | symbol) {\n        const key = k as string\n        if (key in secretCache) {\n          return secretCache[key]\n        }\n\n        // 1. Try reading from file (dir/KEY or just KEY if no dir)\n        const filePath = dir ? join(dir, key) : key\n        try {\n          const value = readFileSync(filePath, 'utf-8').trim()\n          secretCache[key] = value\n          return secretCache[key]\n        } catch {\n          // file not found — continue to fallback\n        }\n\n        // 2. Try fallback\n        if (fallback === true) {\n          // auto-read from process.env using the same key name\n          const { [key]: value } = process.env\n          if (value !== undefined) {\n            secretCache[key] = value\n            return secretCache[key]\n          }\n        } else if (fallback && key in fallback) {\n          secretCache[key] = fallback[key as keyof T] as string\n          return secretCache[key]\n        }\n\n        throw new Error(`Secret ${key} is required`)\n      },\n    }\n  ) as T & { [key: string]: string }\n}\n"],"mappings":";;;;AAIA,MAAa,wBAA0D;CACrE,MAAM,mBAAuD,CAAC;CAE9D,OAAO,IAAI,MACT,CAAC,GACD,EACE,IAAI,GAAG,GAA2C;EAChD,MAAM,MAAM;EACZ,IAAI,QAAQ,YACV,OAAO,IAAI,MACT,CAAC,GACD,EACE,IAAI,GAAG,GAA8B;GACnC,MAAM,MAAM;GACZ,IAAI,OAAO,kBACT,OAAO,iBAAiB;GAE1B,MAAM,GAAG,MAAM,UAAU,QAAQ;GACjC,iBAAiB,OAAO;GACxB,OAAO,iBAAiB;EAC1B,EACF,CACF;EAEF,IAAI,OAAO,kBACT,OAAO,iBAAiB;EAE1B,MAAM,GAAG,MAAM,UAAU,QAAQ;EACjC,OAAO,OAAO,GAAG,IAAI,aAAa;EAClC,iBAAiB,OAAO;EACxB,OAAO,iBAAiB;CAC1B,EACF,CACF;AACF;AAEA,MAAa,qBAIX,KACA,YAEA,IAAI,MAAM,CAAC,GAAY,EACrB,IAAI,GAAG,KAAK;CACV,IAAI,OAAO,QAAQ,UAAU,OAAO,KAAA;CACpC,IAAI;EACF,OAAQ,QAAmC;CAC7C,QAAQ;EACN,OAAQ,IAA+B;CACzC;AACF,EACF,CAAC;AAOH,MAAa,mBACX,SACG;CACH,MAAM,cAAkD,CAAC;CACzD,MAAM,EAAE,KAAK,aAAa,QAAQ,CAAC;CAEnC,OAAO,IAAI,MACT,CAAC,GACD,EACE,IAAI,GAAG,GAA8B;EACnC,MAAM,MAAM;EACZ,IAAI,OAAO,aACT,OAAO,YAAY;EAIrB,MAAM,WAAW,MAAM,KAAK,KAAK,GAAG,IAAI;EACxC,IAAI;GACF,MAAM,QAAQ,aAAa,UAAU,OAAO,CAAC,CAAC,KAAK;GACnD,YAAY,OAAO;GACnB,OAAO,YAAY;EACrB,QAAQ,CAER;EAGA,IAAI,aAAa,MAAM;GAErB,MAAM,GAAG,MAAM,UAAU,QAAQ;GACjC,IAAI,UAAU,KAAA,GAAW;IACvB,YAAY,OAAO;IACnB,OAAO,YAAY;GACrB;EACF,OAAO,IAAI,YAAY,OAAO,UAAU;GACtC,YAAY,OAAO,SAAS;GAC5B,OAAO,YAAY;EACrB;EAEA,MAAM,IAAI,MAAM,UAAU,IAAI,aAAa;CAC7C,EACF,CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebspark/environment",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.mjs",
@@ -20,10 +20,18 @@
     "dev": "tsc --watch --noEmit",
     "lint": "biome check .",
     "test": "vitest run --passWithNoTests --coverage",
-    "typecheck": "vitest --typecheck.only --passWithNoTests"
+    "typecheck": "vitest --typecheck.only --passWithNoTests --run"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/seb-oss/Spark-packages.git"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.12",
+    "@sebspark/tsconfig": "*",
+    "depcheck": "1.4.7",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vitest": "5.0.0"
   }
-}
+}