hanzio 1.1.0 → 1.2.0

package/dist/src/secrets/vite.js

@@ -1,19 +1,41 @@
+// src/secrets/errors.ts
+class SecretLoadError extends Error {
+  code;
+  operation;
+  status;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SecretLoadError";
+    this.code = code;
+    this.operation = details.operation;
+    this.status = details.status;
+  }
+}
+
 // src/secrets/vite.ts
-function getViteDefine(secretSet) {
-  return Object.fromEntries(Object.entries(secretSet.secrets()).map(([key, value]) => [
-    `import.meta.env.${key}`,
-    JSON.stringify(value)
-  ]));
+function getViteDefine(secretSet, options = {}) {
+  const values = secretSet.secrets();
+  const keys = options.publicKeys ?? Object.keys(values);
+  if (!options.publicKeys && keys.some((key) => !key.startsWith("VITE_"))) {
+    throw new SecretLoadError("CONFIGURATION", "Vite secret sets must contain only VITE_ keys, or provide an explicit publicKeys list.");
+  }
+  for (const key of keys) {
+    if (!Object.hasOwn(values, key) || !/^[A-Za-z_$][\w$]*$/.test(key)) {
+      throw new SecretLoadError("CONFIGURATION", "Vite publicKeys must reference configured keys with valid JavaScript identifiers.");
+    }
+    if (["MODE", "BASE_URL", "PROD", "DEV", "SSR"].includes(key)) {
+      throw new SecretLoadError("CONFIGURATION", "Vite built-in environment constants cannot be overridden by secrets.");
+    }
+  }
+  return Object.fromEntries(keys.map((key) => [`import.meta.env.${key}`, JSON.stringify(values[key])]));
 }
-function viteSecretSetPlugin(secretSet) {
+function viteSecretSetPlugin(secretSet, options = {}) {
   return {
     name: "hanzio-secret-set",
-    config: () => ({
-      define: getViteDefine(secretSet)
-    })
+    config: () => ({ define: getViteDefine(secretSet, options) })
   };
 }
 export {
-  viteSecretSetPlugin,
-  getViteDefine
+  getViteDefine,
+  viteSecretSetPlugin
 };

package/dist/src/secrets/worker.js

@@ -0,0 +1,275 @@
+// src/secrets/errors.ts
+class SecretLoadError extends Error {
+  code;
+  operation;
+  status;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SecretLoadError";
+    this.code = code;
+    this.operation = details.operation;
+    this.status = details.status;
+  }
+}
+
+// src/secrets/deadline.ts
+async function withSecretDeadline(options, operation) {
+  const timeoutMs = options.timeoutMs ?? 30000;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) {
+    throw new SecretLoadError("CONFIGURATION", "Secret timeoutMs must be a positive finite timer duration.");
+  }
+  const controller = new AbortController;
+  const cancel = () => controller.abort(new SecretLoadError("ABORTED", "Secret loading was cancelled."));
+  if (options.signal?.aborted) {
+    cancel();
+  } else {
+    options.signal?.addEventListener("abort", cancel, { once: true });
+  }
+  const timer = setTimeout(() => controller.abort(new SecretLoadError("TIMEOUT", `Secret loading timed out after ${timeoutMs}ms.`)), timeoutMs);
+  let rejectOnAbort = () => {};
+  try {
+    const aborted = new Promise((_, reject) => {
+      rejectOnAbort = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", rejectOnAbort, { once: true });
+    });
+    if (controller.signal.aborted) {
+      throw controller.signal.reason;
+    }
+    return await Promise.race([operation(controller.signal), aborted]);
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", cancel);
+    controller.signal.removeEventListener("abort", rejectOnAbort);
+  }
+}
+
+// src/secrets/environment.ts
+function getProcessEnvironment() {
+  return typeof process === "undefined" ? undefined : process.env;
+}
+function resolveSecretEnvironment(option, env) {
+  const explicit = typeof option === "function" ? option() : option;
+  if (typeof explicit === "object" && explicit !== null) {
+    if (typeof explicit.slug !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(explicit.slug)) {
+      throw new SecretLoadError("CONFIGURATION", "Custom secret environment requires a valid slug.");
+    }
+    return explicit.slug;
+  }
+  const selected = explicit ?? env?.SECRETS_ENV;
+  if (selected !== undefined) {
+    if (selected === "production" || selected === "prod") {
+      return "prod";
+    }
+    if (selected === "development" || selected === "dev") {
+      return "dev";
+    }
+    if (selected === "staging") {
+      return "staging";
+    }
+    throw new SecretLoadError("CONFIGURATION", "Invalid secret environment. Use dev, staging, prod, or an explicit { slug } option.");
+  }
+  if (env?.NODE_ENV === "production" || env?.NODE_ENV === "prod") {
+    return "prod";
+  }
+  if (env?.NODE_ENV === "staging") {
+    return "staging";
+  }
+  return "dev";
+}
+
+// src/secrets/core.ts
+var registryKey = Symbol.for("hanzio.secrets.environmentWrites.v1");
+var shared = globalThis;
+var environmentWrites = shared[registryKey] ?? new WeakMap;
+shared[registryKey] = environmentWrites;
+var defaultLogger = {
+  info: (message, attrs) => console.log(`${message} environment=${attrs.environment} count=${attrs.count} source=${attrs.source} durationMs=${attrs.durationMs}`, { sources: attrs.sources }),
+  error: (message, attrs) => console.error(message, attrs)
+};
+function readOverrides(keys, env) {
+  if (!env) {
+    return {};
+  }
+  const writes = environmentWrites.get(env);
+  return Object.fromEntries(keys.flatMap((key) => {
+    const value = Object.hasOwn(env, key) ? env[key] : undefined;
+    if (writes?.has(key)) {
+      if (writes.get(key) === value) {
+        return [];
+      }
+      writes.delete(key);
+    }
+    return value ? [[key, value]] : [];
+  }));
+}
+async function defineSecretSet(keys, options, environmentVariables) {
+  const keySet = [...new Set(keys)];
+  const environment = resolveSecretEnvironment(options.environment, environmentVariables);
+  const logger = options.logger === false ? undefined : options.logger ?? defaultLogger;
+  let cached;
+  let parsed;
+  let sources;
+  let inFlight;
+  const log = (level, message, attributes) => {
+    try {
+      logger?.[level](message, attributes);
+    } catch {}
+  };
+  const loadSnapshot = async (request, signal) => {
+    const local = readOverrides(keySet, environmentVariables);
+    const missing = keySet.filter((key) => !Object.hasOwn(local, key));
+    let loaderSource = options.loader.source ?? "custom loader";
+    let loaded = {};
+    if (missing.length) {
+      try {
+        loaded = await options.loader({
+          keys: missing,
+          environment,
+          signal,
+          timeoutMs: request.timeoutMs ?? options.timeoutMs ?? 30000,
+          reportSource: (source) => {
+            loaderSource = source;
+          }
+        });
+      } catch (error) {
+        if (error instanceof SecretLoadError) {
+          throw error;
+        }
+        throw new SecretLoadError("LOADER", "Secret loader failed.");
+      }
+    }
+    const overrides = readOverrides(keySet, environmentVariables);
+    const next = Object.fromEntries(keySet.map((key) => {
+      if (Object.hasOwn(overrides, key)) {
+        return [key, overrides[key]];
+      }
+      if (Object.hasOwn(loaded, key)) {
+        return [key, loaded[key]];
+      }
+      return [key, undefined];
+    }));
+    const missingKeys = keySet.filter((key) => typeof next[key] !== "string" || !next[key]);
+    if (missingKeys.length) {
+      throw new SecretLoadError("MISSING_SECRETS", `Missing secrets: ${missingKeys.join(", ")}`);
+    }
+    let nextParsed;
+    try {
+      nextParsed = options.schema ? await options.schema.parseAsync({ ...next }) : { ...next };
+      nextParsed = structuredClone(nextParsed);
+    } catch {
+      throw new SecretLoadError("VALIDATION", "Secret schema validation failed. Check the configured schema; values are omitted.");
+    }
+    signal.throwIfAborted();
+    const nextSources = Object.fromEntries(keySet.map((key) => [
+      key,
+      Object.hasOwn(overrides, key) ? "process.env" : loaderSource
+    ]));
+    if (options.writeToProcessEnv !== false && environmentVariables) {
+      let writes = environmentWrites.get(environmentVariables);
+      if (!writes) {
+        writes = new Map;
+        environmentWrites.set(environmentVariables, writes);
+      }
+      for (const key of keySet) {
+        if (Object.hasOwn(overrides, key)) {
+          continue;
+        }
+        environmentVariables[key] = next[key];
+        writes.set(key, next[key]);
+      }
+    }
+    cached = next;
+    parsed = nextParsed;
+    sources = nextSources;
+  };
+  const load = (request = {}) => {
+    if (inFlight) {
+      return inFlight;
+    }
+    inFlight = (async () => {
+      const start = Date.now();
+      try {
+        await withSecretDeadline({
+          timeoutMs: request.timeoutMs ?? options.timeoutMs,
+          signal: request.signal ?? options.signal
+        }, (signal) => loadSnapshot(request, signal));
+        const sourceCounts = new Map;
+        for (const key of keySet) {
+          const source = sources[key];
+          sourceCounts.set(source, (sourceCounts.get(source) ?? 0) + 1);
+        }
+        const counts = Object.fromEntries(sourceCounts);
+        log("info", "Loaded secrets", {
+          environment,
+          count: keySet.length,
+          durationMs: Date.now() - start,
+          source: Object.keys(counts).join(" + ") || "none",
+          sources: counts
+        });
+      } catch (error) {
+        const safe = error instanceof SecretLoadError ? error : new SecretLoadError("LOADER", "Secret loading failed.");
+        log("error", "Secret loading failed", {
+          environment,
+          count: keySet.length,
+          durationMs: Date.now() - start,
+          code: safe.code
+        });
+        throw safe;
+      }
+    })().finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  };
+  const secretSet = {
+    secret(key) {
+      if (!Object.hasOwn(cached, key)) {
+        throw new SecretLoadError("MISSING_SECRETS", `Secret ${key} not found`);
+      }
+      return cached[key];
+    },
+    secrets: () => ({ ...cached }),
+    parsed: () => structuredClone(parsed),
+    sources: () => ({ ...sources }),
+    async reload(request) {
+      await load(request);
+      return secretSet;
+    }
+  };
+  await load();
+  return secretSet;
+}
+// src/secrets/worker-loader.ts
+function cloudflareWorkerEnvLoader(workerEnv) {
+  const loader = async (ctx) => {
+    const out = Object.create(null);
+    for (const key of ctx.keys) {
+      const str = workerBindingToString(Object.hasOwn(workerEnv, key) ? workerEnv[key] : undefined);
+      if (str !== undefined) {
+        out[key] = str;
+      }
+    }
+    return out;
+  };
+  return Object.assign(loader, { source: "Cloudflare Worker bindings" });
+}
+function workerBindingToString(value) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value === "string") {
+    return value === "" ? undefined : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+export {
+  SecretLoadError,
+  cloudflareWorkerEnvLoader,
+  defineSecretSet
+};

package/dist/src/sitemap/index.js

@@ -28,7 +28,7 @@ class PriorityQueue {
     return this.#queue.filter((item) => Object.entries(options).every(([key, value]) => item[key] === value)).map((item) => item.run);
   }
   setPriority(id, priority) {
-    const index = this.#queue.findIndex((item2) => item2.id === id);
+    const index = this.#queue.findIndex((item) => item.id === id);
     if (index === -1) {
       throw new ReferenceError(`No promise function with the id "${id}" exists in the queue.`);
     }

package/dist/src/zod/index.js

@@ -199,12 +199,12 @@ function normalizeSingleOrArray(value) {
   return [value];
 }
 export {
-  zodToTypeString,
-  zodToExample,
-  zodMinMaxFilter,
-  zSingleOrArray,
-  toGteLteFilter,
-  normalizeSingleOrArray,
+  createZId,
   jsonToZodSchemaMapper,
-  createZId
+  normalizeSingleOrArray,
+  toGteLteFilter,
+  zSingleOrArray,
+  zodMinMaxFilter,
+  zodToExample,
+  zodToTypeString
 };

package/dist/typedswitch/index.d.ts

@@ -67,7 +67,11 @@
 type RawHandlerReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
 /** Get union of all raw return types from a cases object's values */
 type RawCasesReturnType<Cases> = {
-    [K in keyof Cases]: Cases[K] extends undefined ? never : RawHandlerReturnType<Cases[K]>;
+    [K in keyof Cases]: RawHandlerReturnType<Cases[K]>;
+}[keyof Cases];
+/** Only required, defined handlers guarantee that a case is handled. */
+type HandledCaseKeys<Cases> = {
+    [K in keyof Cases]-?: {} extends Pick<Cases, K> ? never : undefined extends Cases[K] ? never : K;
 }[keyof Cases];
 /** Cases for string input - all cases required */
 export type StringSwitchCases<T extends string, R> = {
@@ -90,13 +94,13 @@ export declare function typedSwitch<T extends string, Cases extends {
 }>(value: T, cases: Cases): RawCasesReturnType<Cases>;
 export declare function typedSwitch<T extends string, Cases extends {
     [K in T]?: (value: K) => unknown;
-}, DefaultCase extends (value: T) => unknown>(value: T, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
-export declare function typedSwitch<T extends Record<string, unknown>, K extends keyof T, TKey extends T[K] & string, Cases extends {
+}, DefaultCase extends (value: Exclude<T, HandledCaseKeys<Cases>>) => unknown>(value: T, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
+export declare function typedSwitch<T extends object, K extends keyof T, TKey extends T[K] & string, Cases extends {
     [V in TKey]: (value: Extract<T, Record<K, V>>) => unknown;
 }>(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>;
-export declare function typedSwitch<T extends Record<string, unknown>, K extends keyof T, TKey extends T[K] & string, Cases extends {
+export declare function typedSwitch<T extends object, K extends keyof T, TKey extends T[K] & string, Cases extends {
     [V in TKey]?: (value: Extract<T, Record<K, V>>) => unknown;
-}, DefaultCase extends (value: T) => unknown>(value: T, key: K, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
+}, DefaultCase extends (value: Exclude<T, Record<K, HandledCaseKeys<Cases> & string>>) => unknown>(value: T, key: K, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
 export declare function typedSwitch<Constraint, T extends string = string>(value: T, cases: {
     [K in T]: (value: K) => Constraint;
 }): Constraint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -46,11 +46,17 @@
       "bun": "./src/secrets/vite.ts",
       "import": "./dist/src/secrets/vite.js",
       "default": "./dist/src/secrets/vite.js"
+    },
+    "./secrets/worker": {
+      "types": "./dist/secrets/worker.d.ts",
+      "bun": "./src/secrets/worker.ts",
+      "import": "./dist/src/secrets/worker.js",
+      "default": "./dist/src/secrets/worker.js"
     }
   },
   "scripts": {
     "build": "bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/secrets/index.ts ./src/secrets/infisical.ts ./src/secrets/loaders.ts ./src/secrets/vite.ts --outdir ./dist --target node --packages external",
+    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/secrets/index.ts ./src/secrets/infisical.ts ./src/secrets/loaders.ts ./src/secrets/vite.ts ./src/secrets/worker.ts --outdir ./dist --target node --packages external",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "publish:patch": "npm version patch && npm publish",
@@ -60,14 +66,17 @@
     "lint": "bun run typecheck && bun biome check",
     "lint:write": "bun run typecheck && bun biome check --write",
     "typecheck": "tsgo --noEmit",
-    "prepare": "husky"
+    "prepare": "husky",
+    "test:secrets:runtime": "bun run build && node scripts/verify-secrets.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260306.1",
     "husky": "^9.1.7",
+    "miniflare": "^4.20260730.0",
     "typescript": "^5.7.0",
+    "vite": "^8.2.2",
     "zod": "^4.3.6"
   },
   "peerDependencies": {

package/src/api-wrapper/builders.ts

@@ -9,63 +9,88 @@ import type {
 } from './shared'
 import type { ApiEndpoint } from './types'
 
-export function buildUrl(
-	endpoint: ApiEndpoint,
-	params: PathParams | undefined,
-	reqQuery: QueryParams | undefined,
-	baseApiUrls: Record<string, BaseApiUrl>,
-	defaultBaseApiUrl: string | undefined,
-	url: string | undefined,
+export type BuildUrlOptions = {
+	endpoint: ApiEndpoint
+	params: PathParams | undefined
+	queryParams: Record<string, string>
+	baseApiUrls: Record<string, BaseApiUrl>
+	defaultBaseApiUrl: string | undefined
+	url: string | undefined
+	doNotEncodeQueryParams?: boolean
 	configError: (msg: string) => ConfigError
-) {
+}
+
+export function formatQueryString(
+	queryParams: Record<string, string>,
+	doNotEncode?: boolean
+): string {
+	if (Object.keys(queryParams).length === 0) return ''
+	return doNotEncode
+		? Object.entries(queryParams)
+				.map(([key, value]) => `${key}=${value}`)
+				.join('&')
+		: new URLSearchParams(queryParams).toString()
+}
+
+export function buildUrl(options: BuildUrlOptions) {
+	const {
+		endpoint,
+		params,
+		queryParams,
+		baseApiUrls,
+		defaultBaseApiUrl,
+		url,
+		doNotEncodeQueryParams,
+		configError
+	} = options
+
+	let finalUrl: string
 	if (url) {
-		const finalUrl = replacePathParams(url, params, configError)
-		const queryString = new URLSearchParams(
-			buildQueryParamsRaw(endpoint, reqQuery)
-		).toString()
-		return {
-			finalUrl,
-			fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+		finalUrl = replacePathParams(url, params, configError)
+	} else {
+		const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
+		if (!defaultBaseUrl) {
+			throw configError('At least one base API URL is required')
 		}
-	}
 
-	const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0]
-	if (!defaultBaseUrl) {
-		throw configError('At least one base API URL is required')
-	}
+		const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl
+		const configBaseUrl = baseApiUrls[baseUrlKey]
+		if (!configBaseUrl) {
+			throw configError(`Unknown base API URL: ${baseUrlKey}`)
+		}
 
-	const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl
-	const configBaseUrl = baseApiUrls[baseUrlKey]
-	if (!configBaseUrl) {
-		throw configError(`Unknown base API URL: ${baseUrlKey}`)
+		const baseUrl =
+			typeof configBaseUrl === 'function' ? configBaseUrl() : configBaseUrl
+		const path =
+			typeof endpoint.path === 'function'
+				? endpoint.path(baseUrl)
+				: endpoint.path
+		// Substitute endpoint parameters without interpreting a port or IPv6 host as one.
+		finalUrl = `${baseUrl}${replacePathParams(path, params, configError)}`
 	}
 
-	const baseUrl =
-		typeof configBaseUrl === 'function' ? configBaseUrl() : configBaseUrl
-	const path =
-		typeof endpoint.path === 'function' ? endpoint.path(baseUrl) : endpoint.path
-	const finalUrl = replacePathParams(`${baseUrl}${path}`, params, configError)
-	const queryString = new URLSearchParams(
-		buildQueryParamsRaw(endpoint, reqQuery)
-	).toString()
-
+	const queryString = formatQueryString(queryParams, doNotEncodeQueryParams)
 	return {
 		finalUrl,
 		fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
 	}
 }
 
-export function buildQueryParamsRaw(
+export function buildPathParams(
 	endpoint: ApiEndpoint,
-	query: QueryParams | undefined
-): Record<string, string> {
-	const defaultParams = endpoint.reqDefaultQueryParams ?? {}
-	const merged = { ...defaultParams, ...(query ?? {}) }
-	return Object.fromEntries(
-		Object.entries(merged)
-			.filter(([, value]) => value !== undefined)
-			.map(([key, value]) => [key, String(value)])
-	)
+	params: PathParams | undefined,
+	ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext
+): PathParams | undefined {
+	if (!endpoint.reqParamsSchema) return params
+
+	try {
+		return endpoint.reqParamsSchema.parse(params) as PathParams
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new RequestValidationError(error, 'params', params, ctx())
+		}
+		throw error
+	}
 }
 
 export function buildQueryParams(