@daiso-tech/core
Version:
The library offers flexible, framework-agnostic solutions for modern web applications, built on adaptable components that integrate seamlessly with popular frameworks like Next Js.
79 lines (78 loc) • 3.1 kB
TypeScript
/**
* @module EnvAccessor
*/
import { type StandardSchemaV1 } from "@standard-schema/spec";
import { type BaseEnvConfig, type IEnvAccessor, type RawEnvConfig } from "../../env-accessor/contracts/_module.js";
import { type UndefinedToNull, type OneOrMore, type AsyncLazyable } from "../../utilities/_module.js";
/**
* Settings for configuring an {@link EnvAccessor | `EnvAccessor`} instance.
*
* @template TEnvConfig The environment config type.
*/
export type EnvAccessorSettings<TEnvConfig extends BaseEnvConfig = BaseEnvConfig> = {
/**
* The schema used to validate and type the environment config.
*/
schema: StandardSchemaV1<Partial<Record<string, string>>, TEnvConfig>;
/**
* One or more sources (sync/async/lazy) providing raw environment config values.
*/
sources: OneOrMore<AsyncLazyable<RawEnvConfig>>;
};
/**
* `EnvAccessor` provides type-safe access to environment variables, with optional schema validation.
*
* It supports multiple sources (sync/async/lazy), schema validation, and convenient access patterns.
*
* @template TEnvConfig The environment config type.
* @group Implementations
*/
export declare class EnvAccessor<TEnvConfig extends BaseEnvConfig> implements IEnvAccessor<TEnvConfig> {
private envConfig;
private readonly schema;
private readonly sources;
/**
* @example
* ```ts
* import { EnvAccessor } from "@daiso-tech/core/env-accessor";
* import { z } from "zod";
* import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
*
*
* // Combine AWS Secrets Manager and process.env as sources
* // Note: The order matters—later sources override previous ones for overlapping keys.
* const secretsManager = new SecretsManagerClient({ region: "us-east-1" });
* const sources = [
* process.env,
* async () => {
* const secret = await secretsManager.send(
* new GetSecretValueCommand({ SecretId: "my-app/env" })
* );
* return JSON.parse(secret.SecretString ?? "{}");
* },
* ];
*
* // Define a schema for your environment variables
* const schema = z.object({
* NODE_ENV: z.string(),
* PORT: z.string().default("3000").pipe(z.coerce.number()),
* });
*
* // Initialize the accessor
* const accessor = new EnvAccessor({ schema, sources });
* await accessor.init();
*
* // Retrieve a value
* const port = accessor.get("PORT");
* ```
*/
constructor(settings: EnvAccessorSettings<TEnvConfig>);
/**
* Initialize the EnvAccessor by resolving all sources and validating the merged config.
*
* @returns Promise that resolves when initialization is complete.
*/
init(): Promise<void>;
get<TField extends keyof TEnvConfig, TValue extends TEnvConfig[TField]>(field: TField): UndefinedToNull<TValue>;
getOr<TField extends keyof TEnvConfig, TValue extends TEnvConfig[TField]>(field: TField, defaultValue: NonNullable<TValue>): NonNullable<TValue>;
}