@beignet/core 0.0.1

package/src/config/index.ts

@@ -0,0 +1,497 @@
+/**
+ * @beignet/core/config
+ *
+ * Environment-first configuration layer using Standard Schema (Zod, Valibot,
+ * ArkType, etc.) for Beignet applications and providers.
+ */
+
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+export type RuntimeEnv = Record<string, string | undefined>;
+export type EnvSchemaShape = Record<string, StandardSchema>;
+type EmptyEnvSchemaShape = Record<keyof never, never>;
+type NoInferType<T> = [T][T extends unknown ? 0 : never];
+
+export type InferOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+export type InferEnvShape<Shape extends EnvSchemaShape> = {
+  [Key in keyof Shape]: InferOutput<Shape[Key]>;
+};
+
+export type ClientEnvSchemaShape<ClientPrefix extends string> =
+  ClientPrefix extends ""
+    ? EnvSchemaShape
+    : Record<`${ClientPrefix}${string}`, StandardSchema>;
+
+type ValidateClientEnvShape<
+  ClientPrefix extends string,
+  Client extends EnvSchemaShape,
+> = ClientPrefix extends ""
+  ? Client
+  : {
+      [Key in keyof Client]: Key extends `${ClientPrefix}${string}`
+        ? Client[Key]
+        : never;
+    };
+
+export type EnvValidationIssue = StandardSchemaV1.Issue;
+
+export class ConfigValidationError extends Error {
+  readonly issues: readonly EnvValidationIssue[];
+
+  constructor(issues: readonly EnvValidationIssue[], message?: string) {
+    super(message ?? formatStandardSchemaIssues(issues));
+    this.name = "ConfigValidationError";
+    this.issues = issues;
+  }
+}
+
+export interface ReadEnvOptions {
+  env?: RuntimeEnv;
+  prefix?: string;
+  emptyStringAsUndefined?: boolean;
+}
+
+export interface DefineEnvOptions<Schema extends StandardSchemaV1> {
+  /**
+   * Standard Schema for validating the full environment object.
+   */
+  schema: Schema;
+
+  /**
+   * Optional prefix to filter env vars. Matching keys are stripped before
+   * validation, so `APP_DATABASE_URL` becomes `DATABASE_URL`.
+   */
+  prefix?: string;
+
+  /**
+   * Runtime environment object. Defaults to `process.env` when available.
+   */
+  runtimeEnv?: RuntimeEnv;
+
+  /**
+   * Treat empty strings as missing values before validation.
+   */
+  emptyStringAsUndefined?: boolean;
+
+  /**
+   * Skip validation and return the raw env object. This is intended for build
+   * phases where real secrets are unavailable.
+   */
+  skipValidation?: boolean;
+
+  /**
+   * Called when validation fails. Throw from this hook to customize the error.
+   */
+  onValidationError?: (issues: readonly EnvValidationIssue[]) => never;
+}
+
+export interface EnvInstance<Out> {
+  load(options?: { env?: RuntimeEnv }): Out;
+}
+
+export interface CreateEnvOptions<
+  Server extends EnvSchemaShape,
+  ClientPrefix extends string,
+  Client extends EnvSchemaShape,
+> {
+  /**
+   * Server-only environment variables. These throw if accessed from a client
+   * runtime through the returned env object.
+   */
+  server?: Server;
+
+  /**
+   * Client-safe environment variables. Keys must use `clientPrefix` when a
+   * prefix is provided.
+   */
+  client?: Client & ValidateClientEnvShape<NoInferType<ClientPrefix>, Client>;
+
+  /**
+   * Prefix required for client variables, e.g. `NEXT_PUBLIC_`.
+   */
+  clientPrefix?: ClientPrefix;
+
+  /**
+   * Runtime environment object. Defaults to `process.env` when available.
+   */
+  runtimeEnv?: RuntimeEnv;
+
+  /**
+   * Strict runtime environment object. Every declared key must be present on the
+   * object, even if the value is `undefined`. This catches framework bundling
+   * mistakes where an env var was not explicitly accessed.
+   */
+  runtimeEnvStrict?: RuntimeEnv;
+
+  /**
+   * Treat empty strings as missing values before validation.
+   *
+   * Defaults to `true` for `createEnv` because it keeps defaults ergonomic in
+   * framework starters.
+   */
+  emptyStringAsUndefined?: boolean;
+
+  /**
+   * Skip validation and return raw values. Use sparingly for build phases where
+   * deployment secrets are unavailable.
+   */
+  skipValidation?: boolean;
+
+  /**
+   * Override server detection. Defaults to checking for `window` on globalThis.
+   */
+  isServer?: boolean;
+
+  /**
+   * Called when validation fails. Throw from this hook to customize the error.
+   */
+  onValidationError?: (issues: readonly EnvValidationIssue[]) => never;
+
+  /**
+   * Called when a server-only variable is read from a client runtime.
+   */
+  onInvalidAccess?: (key: string) => never;
+}
+
+export type CreateEnvResult<
+  Server extends EnvSchemaShape,
+  Client extends EnvSchemaShape,
+> = Readonly<InferEnvShape<Server> & InferEnvShape<Client>>;
+
+function defaultRuntimeEnv(): RuntimeEnv {
+  return typeof process !== "undefined" && process.env ? process.env : {};
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    "then" in value &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function normalizeEnvValue(
+  value: string | undefined,
+  emptyStringAsUndefined: boolean,
+): string | undefined {
+  if (emptyStringAsUndefined && value === "") return undefined;
+  return value;
+}
+
+function issuePath(issue: StandardSchemaV1.Issue): string | undefined {
+  if (!issue.path?.length) return undefined;
+
+  return issue.path
+    .map((segment) => {
+      if (segment && typeof segment === "object" && "key" in segment) {
+        return String(segment.key);
+      }
+
+      if (
+        typeof segment === "string" ||
+        typeof segment === "number" ||
+        typeof segment === "symbol"
+      ) {
+        return String(segment);
+      }
+
+      return undefined;
+    })
+    .filter((segment): segment is string => Boolean(segment))
+    .join(".");
+}
+
+function prependIssuePath(
+  key: string,
+  issue: StandardSchemaV1.Issue,
+): StandardSchemaV1.Issue {
+  return {
+    ...issue,
+    path: [{ key }, ...(issue.path ?? [])],
+  };
+}
+
+export function formatStandardSchemaIssues(
+  issues: readonly StandardSchemaV1.Issue[],
+): string {
+  return issues
+    .map((issue) => {
+      const path = issuePath(issue);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+export function readEnv({
+  env = defaultRuntimeEnv(),
+  prefix,
+  emptyStringAsUndefined = false,
+}: ReadEnvOptions = {}): Record<string, string | undefined> {
+  const raw: Record<string, string | undefined> = {};
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value == null) continue;
+
+    if (prefix && prefix.length > 0) {
+      if (!key.startsWith(prefix)) continue;
+      raw[key.slice(prefix.length)] = normalizeEnvValue(
+        value,
+        emptyStringAsUndefined,
+      );
+      continue;
+    }
+
+    raw[key] = normalizeEnvValue(value, emptyStringAsUndefined);
+  }
+
+  return raw;
+}
+
+function validationResultValue<Schema extends StandardSchemaV1>(
+  result: StandardSchemaV1.Result<InferOutput<Schema>>,
+): InferOutput<Schema> {
+  if (result.issues?.length) {
+    throw new ConfigValidationError(result.issues);
+  }
+
+  if ("value" in result) {
+    return result.value as InferOutput<Schema>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+export function parseStandardSchemaSync<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+): InferOutput<Schema> {
+  const validate = schema?.["~standard"]?.validate;
+
+  if (typeof validate !== "function") {
+    throw new Error("Invalid Standard Schema: missing ~standard.validate()");
+  }
+
+  const result = validate(input);
+
+  if (isPromiseLike(result)) {
+    throw new Error(
+      "[Beignet env] Schema uses async validation, which is not supported by load().",
+    );
+  }
+
+  return validationResultValue<Schema>(result);
+}
+
+export async function parseStandardSchemaAsync<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+): Promise<InferOutput<Schema>> {
+  const validate = schema?.["~standard"]?.validate;
+
+  if (typeof validate !== "function") {
+    throw new Error("Invalid Standard Schema: missing ~standard.validate()");
+  }
+
+  return validationResultValue<Schema>(await validate(input));
+}
+
+function wrapEnvError(err: unknown, prefix?: string): Error {
+  if (err instanceof ConfigValidationError) {
+    return new Error(
+      `[Beignet env] Invalid environment${
+        prefix ? ` for prefix "${prefix}"` : ""
+      }: ${err.message}`,
+    );
+  }
+
+  if (err instanceof Error) {
+    return new Error(
+      `[Beignet env] Invalid environment${
+        prefix ? ` for prefix "${prefix}"` : ""
+      }: ${err.message}`,
+    );
+  }
+
+  return new Error(
+    `[Beignet env] Invalid environment${
+      prefix ? ` for prefix "${prefix}"` : ""
+    }: ${String(err)}`,
+  );
+}
+
+export function defineEnv<Schema extends StandardSchemaV1>(
+  options: DefineEnvOptions<Schema>,
+): EnvInstance<InferOutput<Schema>> {
+  const {
+    schema,
+    prefix,
+    runtimeEnv,
+    emptyStringAsUndefined = false,
+    skipValidation = false,
+    onValidationError,
+  } = options;
+
+  function load({
+    env = runtimeEnv ?? defaultRuntimeEnv(),
+  } = {}): InferOutput<Schema> {
+    const raw = readEnv({ env, prefix, emptyStringAsUndefined });
+
+    if (skipValidation) {
+      return raw as InferOutput<Schema>;
+    }
+
+    try {
+      return parseStandardSchemaSync(schema, raw);
+    } catch (err) {
+      if (err instanceof ConfigValidationError) {
+        onValidationError?.(err.issues);
+      }
+
+      throw wrapEnvError(err, prefix);
+    }
+  }
+
+  return { load };
+}
+
+function validateEnvShape<Shape extends EnvSchemaShape>(
+  shape: Shape,
+  runtimeEnv: RuntimeEnv,
+  emptyStringAsUndefined: boolean,
+): InferEnvShape<Shape> {
+  const output: Record<string, unknown> = {};
+  const issues: StandardSchemaV1.Issue[] = [];
+
+  for (const [key, schema] of Object.entries(shape)) {
+    const value = normalizeEnvValue(runtimeEnv[key], emptyStringAsUndefined);
+
+    try {
+      output[key] = parseStandardSchemaSync(schema, value);
+    } catch (error) {
+      if (error instanceof ConfigValidationError) {
+        issues.push(
+          ...error.issues.map((issue) => prependIssuePath(key, issue)),
+        );
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  if (issues.length) {
+    throw new ConfigValidationError(issues);
+  }
+
+  return output as InferEnvShape<Shape>;
+}
+
+function validateClientPrefix(
+  client: EnvSchemaShape,
+  clientPrefix: string | undefined,
+) {
+  if (!clientPrefix) return;
+
+  for (const key of Object.keys(client)) {
+    if (!key.startsWith(clientPrefix)) {
+      throw new Error(
+        `[Beignet env] Client environment variable "${key}" must start with "${clientPrefix}".`,
+      );
+    }
+  }
+}
+
+function validateRuntimeEnvStrict(
+  runtimeEnv: RuntimeEnv,
+  keys: readonly string[],
+) {
+  const missing = keys.filter((key) => !Object.hasOwn(runtimeEnv, key));
+  if (missing.length === 0) return;
+
+  throw new Error(
+    `[Beignet env] runtimeEnvStrict is missing declared keys: ${missing.join(
+      ", ",
+    )}`,
+  );
+}
+
+export function createEnv<
+  const ClientPrefix extends string = "",
+  Server extends EnvSchemaShape = EmptyEnvSchemaShape,
+  Client extends EnvSchemaShape = EmptyEnvSchemaShape,
+>(
+  options: CreateEnvOptions<Server, ClientPrefix, Client>,
+): CreateEnvResult<Server, Client> {
+  const server = (options.server ?? {}) as Server;
+  const client = (options.client ?? {}) as Client;
+  const runtimeEnv =
+    options.runtimeEnvStrict ?? options.runtimeEnv ?? defaultRuntimeEnv();
+  const emptyStringAsUndefined = options.emptyStringAsUndefined ?? true;
+  const isServer = options.isServer ?? !("window" in globalThis);
+
+  if (options.runtimeEnv && options.runtimeEnvStrict) {
+    throw new Error(
+      "[Beignet env] Specify runtimeEnv or runtimeEnvStrict, not both.",
+    );
+  }
+
+  validateClientPrefix(client, options.clientPrefix);
+
+  const declaredKeys = [...Object.keys(server), ...Object.keys(client)];
+  const validationShape = isServer ? { ...server, ...client } : client;
+  const validationKeys = isServer ? declaredKeys : Object.keys(client);
+
+  if (options.runtimeEnvStrict) {
+    validateRuntimeEnvStrict(runtimeEnv, validationKeys);
+  }
+
+  let parsed: Record<string, unknown>;
+
+  if (options.skipValidation) {
+    parsed = Object.fromEntries(
+      validationKeys.map((key) => [
+        key,
+        normalizeEnvValue(runtimeEnv[key], emptyStringAsUndefined),
+      ]),
+    );
+  } else {
+    try {
+      parsed = validateEnvShape(
+        validationShape,
+        runtimeEnv,
+        emptyStringAsUndefined,
+      );
+    } catch (error) {
+      if (error instanceof ConfigValidationError) {
+        options.onValidationError?.(error.issues);
+      }
+
+      throw wrapEnvError(error);
+    }
+  }
+
+  const serverKeys = new Set(Object.keys(server));
+  const clientKeys = new Set(Object.keys(client));
+
+  return new Proxy(parsed, {
+    get(target, property, receiver) {
+      if (
+        typeof property === "string" &&
+        !isServer &&
+        serverKeys.has(property) &&
+        !clientKeys.has(property)
+      ) {
+        options.onInvalidAccess?.(property);
+        throw new Error(
+          `[Beignet env] Attempted to access server-only environment variable "${property}" from a client runtime.`,
+        );
+      }
+
+      return Reflect.get(target, property, receiver);
+    },
+  }) as CreateEnvResult<Server, Client>;
+}