@beignet/core
Version:
Core framework primitives for Beignet
206 lines • 7.59 kB
TypeScript
/**
* @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";
/**
* Any Standard Schema compatible validator.
*/
export type StandardSchema = StandardSchemaV1<unknown, unknown>;
/**
* Runtime environment object shape.
*/
export type RuntimeEnv = Record<string, string | undefined>;
/**
* Map of environment variable names to Standard Schema validators.
*/
export type EnvSchemaShape = Record<string, StandardSchema>;
type EmptyEnvSchemaShape = Record<keyof never, never>;
type NoInferType<T> = [T][T extends unknown ? 0 : never];
/**
* Infer the parsed output type from a Standard Schema.
*/
export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
/**
* Infer the parsed output object for an env schema shape.
*/
export type InferEnvShape<Shape extends EnvSchemaShape> = {
[Key in keyof Shape]: InferOutput<Shape[Key]>;
};
/**
* Env schema shape constrained to a client prefix.
*/
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;
};
/**
* Raw Standard Schema validation issue produced while loading config.
*/
export type EnvValidationIssue = StandardSchemaV1.Issue;
/**
* Error thrown when Beignet config validation fails.
*/
export declare class ConfigValidationError extends Error {
/**
* Raw Standard Schema validation issues.
*/
readonly issues: readonly EnvValidationIssue[];
constructor(issues: readonly EnvValidationIssue[], message?: string);
}
/**
* Options for reading raw environment variables.
*/
export interface ReadEnvOptions {
/**
* Runtime environment object. Defaults to `process.env`.
*/
env?: RuntimeEnv;
/**
* Optional prefix to filter and strip from matching keys.
*/
prefix?: string;
/**
* Treat empty strings as missing values.
*/
emptyStringAsUndefined?: boolean;
}
/**
* Options for creating a single validated env loader.
*/
export interface CreateEnvLoaderOptions<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;
}
/**
* Validated env loader returned by `createEnvLoader(...)`.
*/
export interface EnvInstance<Out> {
/**
* Read and validate the environment.
*/
load(options?: {
env?: RuntimeEnv;
}): Out;
}
/**
* Options for `createEnv(...)`.
*/
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;
}
/**
* Parsed env object returned by `createEnv(...)`.
*/
export type CreateEnvResult<Server extends EnvSchemaShape, Client extends EnvSchemaShape> = Readonly<InferEnvShape<Server> & InferEnvShape<Client>>;
/**
* Format Standard Schema issues into a single readable message.
*/
export declare function formatStandardSchemaIssues(issues: readonly StandardSchemaV1.Issue[]): string;
/**
* Read raw environment variables, optionally filtering by prefix.
*
* When a prefix is provided, matching keys are stripped before being returned.
*/
export declare function readEnv({ env, prefix, emptyStringAsUndefined, }?: ReadEnvOptions): Record<string, string | undefined>;
/**
* Validate input with a synchronous Standard Schema.
*
* Throws when the schema returns a promise because env loading is synchronous.
*/
export declare function parseStandardSchemaSync<Schema extends StandardSchemaV1>(schema: Schema, input: unknown): InferOutput<Schema>;
/**
* Validate input with a Standard Schema that may be synchronous or async.
*/
export declare function parseStandardSchemaAsync<Schema extends StandardSchemaV1>(schema: Schema, input: unknown): Promise<InferOutput<Schema>>;
/**
* Create a reusable validated env loader.
*
* This is useful for provider config and app-level config objects that are
* loaded from a prefixed subset of the environment.
*/
export declare function createEnvLoader<Schema extends StandardSchemaV1>(options: CreateEnvLoaderOptions<Schema>): EnvInstance<InferOutput<Schema>>;
/**
* Create a server/client split env object.
*
* Server variables are available only on the server. Client variables must use
* `clientPrefix` when provided. Validation is synchronous, empty strings are
* treated as undefined by default, and client access to server-only keys throws
* through the returned proxy.
*/
export declare function createEnv<const ClientPrefix extends string = "", Server extends EnvSchemaShape = EmptyEnvSchemaShape, Client extends EnvSchemaShape = EmptyEnvSchemaShape>(options: CreateEnvOptions<Server, ClientPrefix, Client>): CreateEnvResult<Server, Client>;
export {};
//# sourceMappingURL=index.d.ts.map