@sebspark/environment 0.1.0 → 0.1.2

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

@@ -4,9 +4,14 @@ declare const initEnvironment: <T extends Record<string, string>>() => T & {
 } & {
   [key: string]: string;
 };
-declare const initSecretStore: <T extends Record<string, string>>() => T & {
+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 & {
   [key: string]: string;
 };
 //#endregion
-export { initEnvironment, initSecretStore };
+export { initEnvironment, initSecretStore, mergeEnvironments };
 //# 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":";cAGa,eAAA,aAA6B,MAAA,uBAiCnC,CAAA;EAAM,QAAA,EAAU,OAAA,CAAQ,CAAA;AAAA;EAAA,CAAU,GAAA;AAAA;AAAA,cAG5B,eAAA,aAA6B,MAAA,uBAoBnC,CAAA;EAAA,CAAO,GAAA;AAAA"}
+{"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,cAG5B,iBAAA,aACD,MAAA,4BACA,MAAA,kBAEV,GAAA,EAAK,CAAA,EACL,OAAA,EAAS,CAAA,KACR,CAAA,GAAI,CAAA;AAAA,KAYF,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"}

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 //#region src/index.ts
 const initEnvironment = () => {
 	const environmentCache = {};
@@ -19,20 +20,39 @@ const initEnvironment = () => {
 		return environmentCache[key];
 	} });
 };
-const initSecretStore = () => {
+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 ?? {};
 	return new Proxy({}, { get(_, k) {
 		const key = k;
 		if (key in secretCache) return secretCache[key];
+		const filePath = dir ? join(dir, key) : key;
 		try {
-			secretCache[key] = readFileSync(key, "utf-8").trim();
+			secretCache[key] = readFileSync(filePath, "utf-8").trim();
+			return secretCache[key];
+		} catch {}
+		if (fallback === true) {
+			const { [key]: value } = process.env;
+			if (value !== void 0) {
+				secretCache[key] = value;
+				return secretCache[key];
+			}
+		} else if (fallback && key in fallback) {
+			secretCache[key] = fallback[key];
 			return secretCache[key];
-		} catch (err) {
-			throw new Error(`Secret ${key} is required`);
 		}
+		throw new Error(`Secret ${key} is required`);
 	} });
 };
 //#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'\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 initSecretStore = <T extends Record<string, string>>() => {\n  const secretCache: Record<string, string | undefined> = {}\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        try {\n          const value = readFileSync(key, 'utf-8').trim()\n          secretCache[key] = value\n          return secretCache[key]\n        } catch (err) {\n          throw new Error(`Secret ${key} is required`)\n        }\n      },\n    }\n  ) as T & { [key: string]: string }\n}\n"],"mappings":";;;AAGA,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;;AAGH,MAAa,wBAA0D;CACrE,MAAM,cAAkD,EAAE;CAE1D,OAAO,IAAI,MACT,EAAE,EACF,EACE,IAAI,GAAG,GAA8B;EACnC,MAAM,MAAM;EACZ,IAAI,OAAO,aACT,OAAO,YAAY;EAErB,IAAI;GAEF,YAAY,OADE,aAAa,KAAK,QAAQ,CAAC,MACjB;GACxB,OAAO,YAAY;WACZ,KAAK;GACZ,MAAM,IAAI,MAAM,UAAU,IAAI,cAAc;;IAGjD,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,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;;AAGH,MAAa,qBAIX,KACA,YAEA,IAAI,MAAM,EAAE,EAAW,EACrB,IAAI,GAAG,KAAK;CACV,IAAI,OAAO,QAAQ,UAAU,OAAO,KAAA;CACpC,IAAI;EACF,OAAQ,QAAmC;SACrC;EACN,OAAQ,IAA+B;;GAG5C,CAAC;AAOJ,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sebspark/environment",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.mjs",