@ayepi/env 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,166 @@
+import { a as mergeSources, i as defaultSource, n as EnvError, o as resolveRaw, r as EnvSource, t as parseDotenv } from "./dotenv.cjs";
+import { z } from "zod";
+
+//#region src/coerce.d.ts
+
+/** The effective (unwrapped) zod type name of a field — e.g. `optional(number)` → `'number'`. */
+declare function effectiveType(schema: z.ZodType): string;
+/** The default strings parsed as `true` / `false` (matched case-insensitively, trimmed). */
+declare const DEFAULT_TRUE: ReadonlySet<string>;
+declare const DEFAULT_FALSE: ReadonlySet<string>;
+/** Override the strings recognized as booleans. Each side omitted falls back to its default set. */
+interface BooleanWords {
+  /** Strings that mean `true` (replaces {@link DEFAULT_TRUE} when given). */
+  readonly true?: ReadonlySet<string>;
+  /** Strings that mean `false` (replaces {@link DEFAULT_FALSE} when given). */
+  readonly false?: ReadonlySet<string>;
+}
+/**
+ * Coerce `value` toward what `schema` expects. Non-string values pass through; strings are
+ * converted per the field's effective type — so a plain `z.number()` / `z.boolean()` / `z.date()`
+ * / `z.object()` works straight from env strings, **no `z.coerce` needed**. Returns the original
+ * string when a conversion is ambiguous or fails, so zod produces the final, authoritative error.
+ * Pass `words` to customize which strings count as boolean `true`/`false`.
+ */
+declare function coerce(schema: z.ZodType, value: unknown, words?: BooleanWords): unknown;
+//#endregion
+//#region src/env.d.ts
+
+/** A field definition: a zod schema, or a factory taking the inherited (earlier-group) values. */
+type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => z.ZodType | any);
+/** The fields passed to {@link env} / {@link Env.add}. `Inherited` is the type resolved so far. */
+type EnvInput<Inherited> = Record<string, EnvFieldDef<Inherited>>;
+/** The resolved output type of an {@link EnvInput} (zod outputs, computed schema outputs, or plain values). */
+type EnvOutput<Inherited, Input extends EnvInput<Inherited>> = { [K in keyof Input]: Input[K] extends z.ZodType ? z.output<Input[K]> : Input[K] extends ((inherited: Inherited) => infer R) ? R extends z.ZodType ? z.output<R> : R : never };
+/** Values accepted by {@link Env.set}: known fields (typed or raw string) plus any extra source keys. */
+type EnvSet<T extends object> = { [K in keyof T]?: T[K] | string } & {
+  [key: string]: unknown;
+};
+/** Build-time options for {@link env} / {@link asyncEnv}. */
+interface EnvOptions {
+  /**
+   * Customize which strings coerce to booleans (case-insensitive). Each side you provide
+   * **replaces** its default set; an omitted side keeps the default. E.g.
+   * `{ booleans: { true: ['enabled'], false: ['disabled'] } }`.
+   */
+  readonly booleans?: {
+    readonly true?: readonly string[];
+    readonly false?: readonly string[];
+  };
+}
+/** Normalize {@link EnvOptions} into the lowercased {@link BooleanWords} the coercer consumes. */
+
+/** Options for {@link Env.on}. */
+interface EnvOnOptions {
+  /** Fire at most once, then auto-unsubscribe. */
+  once?: boolean;
+  /** Compare values structurally (deep-equal) for change detection, instead of by identity. */
+  deep?: boolean;
+  /** Fire immediately on subscribe with the current value(s). */
+  immediate?: boolean;
+}
+/** A typed, lazy, reactive config object built by {@link env}. */
+interface Env<T extends object> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
+  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
+  /** Resolve a single field (lazily). Throws an {@link EnvError} if that field is missing/invalid. */
+  get<K extends keyof T>(key: K): T[K];
+  /** Override a single field/source key (typed value or raw string). */
+  set<K extends keyof T>(key: K, value: T[K] | string): void;
+  /** Override several fields/source keys at once (e.g. pass `process.env` or a loaded `.env`). */
+  set(updates: EnvSet<T>): void;
+  /** Resolve every field. Throws an aggregated {@link EnvError} listing all missing/invalid fields. */
+  parse(): T;
+  /** Subscribe to *all* field changes; the listener gets `(key, value)`. Returns an unsubscribe fn. */
+  on(listener: (key: keyof T, value: T[keyof T]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to one field's changes. */
+  on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to several fields' changes with one listener. */
+  on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Run `fn` with this env (for grouped setup); returns nothing. */
+  with(fn: (env: Env<T>) => void): void;
+  /** Run `fn` with this env and return its result. */
+  map<R>(fn: (env: Env<T>) => R): R;
+}
+/** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
+declare function env<const T extends EnvInput<{}>>(input: T, options?: EnvOptions): Env<EnvOutput<{}, T>>;
+//#endregion
+//#region src/provider.d.ts
+/** A value, or a promise of one. */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * An external source of a single field's **raw** value. `load` provides the initial value; the
+ * optional `watch` pushes live updates and returns an unsubscribe function.
+ */
+interface EnvProvider {
+  /** Fetch the current raw value (e.g. query a DB / call a service). `undefined` means "absent". */
+  load(): MaybePromise<string | undefined>;
+  /** Subscribe to live updates; call `emit` with each new raw value. Return an unsubscribe fn. */
+  watch?(emit: (raw: string | undefined) => void): () => void;
+}
+/** A field bound to a live {@link EnvProvider}, validated by `schema`. Created by {@link dynamic}. */
+interface DynamicBinding<V> {
+  readonly kind: 'dynamic';
+  readonly provider: EnvProvider;
+  readonly schema: z.ZodType<V>;
+}
+/** Bind a field to a live {@link EnvProvider}; values are validated against `schema`. */
+declare function dynamic<V>(provider: EnvProvider, schema: z.ZodType<V>): DynamicBinding<V>;
+/** True if `x` is a {@link DynamicBinding}. */
+declare function isDynamic(x: unknown): x is DynamicBinding<unknown>;
+/** A provider that re-fetches on an interval — the simplest way to make any source "dynamic". */
+declare function pollProvider(fetch: () => MaybePromise<string | undefined>, intervalMs: number): EnvProvider;
+/** A fixed-value provider (no updates) — handy for tests and constants behind the provider interface. */
+declare function staticProvider(value: string | undefined): EnvProvider;
+//#endregion
+//#region src/async.d.ts
+/** A field for {@link asyncEnv}: zod schema, dynamic binding, or a (possibly async) factory. */
+type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<any> | ((inherited: Inherited) => MaybePromise<z.ZodType | any>);
+/** The fields passed to {@link asyncEnv} / {@link AsyncEnv.add}. */
+type AsyncEnvInput<Inherited> = Record<string, AsyncEnvFieldDef<Inherited>>;
+/** The resolved output type of an {@link AsyncEnvInput}. */
+type AsyncEnvOutput<Inherited, Input extends AsyncEnvInput<Inherited>> = { [K in keyof Input]: Input[K] extends DynamicBinding<infer V> ? V : Input[K] extends z.ZodType ? z.output<Input[K]> : Input[K] extends ((inherited: Inherited) => infer R) ? Awaited<R> extends z.ZodType ? z.output<Awaited<R>> : Awaited<R> : never };
+/** A typed, lazy, reactive **async** config object built by {@link asyncEnv}. */
+interface AsyncEnv<T extends object> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link AsyncEnv}. */
+  add<A extends AsyncEnvInput<T>>(input: A): AsyncEnv<T & AsyncEnvOutput<T, A>>;
+  /** Resolve a single field (lazily, async). Rejects with an {@link EnvError} if missing/invalid. */
+  get<K extends keyof T>(key: K): Promise<T[K]>;
+  /** Override a single field/source key (typed value or raw string). */
+  set<K extends keyof T>(key: K, value: T[K] | string): void;
+  /** Override several fields/source keys at once. */
+  set(updates: EnvSet<T>): void;
+  /** Resolve every field. Rejects with an aggregated {@link EnvError} listing all failures. */
+  parse(): Promise<T>;
+  /** Subscribe to *all* field changes; the listener gets `(key, value)`. Returns an unsubscribe fn. */
+  on(listener: (key: keyof T, value: T[keyof T]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to one field's changes. */
+  on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to several fields' changes with one listener. */
+  on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Re-pull dynamic providers (all, or one field) and notify on any change. */
+  refresh(key?: keyof T): Promise<void>;
+  /** Stop all provider watchers. */
+  close(): void;
+  /** Run `fn` with this env (for grouped setup); returns nothing. */
+  with(fn: (env: AsyncEnv<T>) => void): void;
+  /** Run `fn` with this env and return its result. */
+  map<R>(fn: (env: AsyncEnv<T>) => R): R;
+}
+/** Build a typed, lazy, reactive **async** config — supports async factories and live providers. */
+declare function asyncEnv<const T extends AsyncEnvInput<{}>>(input: T, options?: EnvOptions): AsyncEnv<AsyncEnvOutput<{}, T>>;
+//#endregion
+//#region src/meta.d.ts
+/** The aliasing metadata a field may carry. */
+interface EnvMeta {
+  /** A single source key to read this field from. */
+  readonly var?: string;
+  /** Several source keys to read this field from — first present wins. */
+  readonly vars?: readonly string[];
+}
+/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
+declare function varsOf(schema: z.ZodType, key: string): readonly string[];
+/** Attach aliasing metadata: read `schema` from the first present of `keys`. */
+declare function alias<S extends z.ZodType>(schema: S, ...keys: string[]): S;
+//#endregion
+export { type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type MaybePromise, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, isDynamic, mergeSources, parseDotenv, pollProvider, resolveRaw, staticProvider, varsOf };

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import { a as mergeSources, i as defaultSource, n as EnvError, o as resolveRaw, r as EnvSource, t as parseDotenv } from "./dotenv.js";
+import { z } from "zod";
+
+//#region src/coerce.d.ts
+
+/** The effective (unwrapped) zod type name of a field — e.g. `optional(number)` → `'number'`. */
+declare function effectiveType(schema: z.ZodType): string;
+/** The default strings parsed as `true` / `false` (matched case-insensitively, trimmed). */
+declare const DEFAULT_TRUE: ReadonlySet<string>;
+declare const DEFAULT_FALSE: ReadonlySet<string>;
+/** Override the strings recognized as booleans. Each side omitted falls back to its default set. */
+interface BooleanWords {
+  /** Strings that mean `true` (replaces {@link DEFAULT_TRUE} when given). */
+  readonly true?: ReadonlySet<string>;
+  /** Strings that mean `false` (replaces {@link DEFAULT_FALSE} when given). */
+  readonly false?: ReadonlySet<string>;
+}
+/**
+ * Coerce `value` toward what `schema` expects. Non-string values pass through; strings are
+ * converted per the field's effective type — so a plain `z.number()` / `z.boolean()` / `z.date()`
+ * / `z.object()` works straight from env strings, **no `z.coerce` needed**. Returns the original
+ * string when a conversion is ambiguous or fails, so zod produces the final, authoritative error.
+ * Pass `words` to customize which strings count as boolean `true`/`false`.
+ */
+declare function coerce(schema: z.ZodType, value: unknown, words?: BooleanWords): unknown;
+//#endregion
+//#region src/env.d.ts
+
+/** A field definition: a zod schema, or a factory taking the inherited (earlier-group) values. */
+type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => z.ZodType | any);
+/** The fields passed to {@link env} / {@link Env.add}. `Inherited` is the type resolved so far. */
+type EnvInput<Inherited> = Record<string, EnvFieldDef<Inherited>>;
+/** The resolved output type of an {@link EnvInput} (zod outputs, computed schema outputs, or plain values). */
+type EnvOutput<Inherited, Input extends EnvInput<Inherited>> = { [K in keyof Input]: Input[K] extends z.ZodType ? z.output<Input[K]> : Input[K] extends ((inherited: Inherited) => infer R) ? R extends z.ZodType ? z.output<R> : R : never };
+/** Values accepted by {@link Env.set}: known fields (typed or raw string) plus any extra source keys. */
+type EnvSet<T extends object> = { [K in keyof T]?: T[K] | string } & {
+  [key: string]: unknown;
+};
+/** Build-time options for {@link env} / {@link asyncEnv}. */
+interface EnvOptions {
+  /**
+   * Customize which strings coerce to booleans (case-insensitive). Each side you provide
+   * **replaces** its default set; an omitted side keeps the default. E.g.
+   * `{ booleans: { true: ['enabled'], false: ['disabled'] } }`.
+   */
+  readonly booleans?: {
+    readonly true?: readonly string[];
+    readonly false?: readonly string[];
+  };
+}
+/** Normalize {@link EnvOptions} into the lowercased {@link BooleanWords} the coercer consumes. */
+
+/** Options for {@link Env.on}. */
+interface EnvOnOptions {
+  /** Fire at most once, then auto-unsubscribe. */
+  once?: boolean;
+  /** Compare values structurally (deep-equal) for change detection, instead of by identity. */
+  deep?: boolean;
+  /** Fire immediately on subscribe with the current value(s). */
+  immediate?: boolean;
+}
+/** A typed, lazy, reactive config object built by {@link env}. */
+interface Env<T extends object> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
+  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
+  /** Resolve a single field (lazily). Throws an {@link EnvError} if that field is missing/invalid. */
+  get<K extends keyof T>(key: K): T[K];
+  /** Override a single field/source key (typed value or raw string). */
+  set<K extends keyof T>(key: K, value: T[K] | string): void;
+  /** Override several fields/source keys at once (e.g. pass `process.env` or a loaded `.env`). */
+  set(updates: EnvSet<T>): void;
+  /** Resolve every field. Throws an aggregated {@link EnvError} listing all missing/invalid fields. */
+  parse(): T;
+  /** Subscribe to *all* field changes; the listener gets `(key, value)`. Returns an unsubscribe fn. */
+  on(listener: (key: keyof T, value: T[keyof T]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to one field's changes. */
+  on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to several fields' changes with one listener. */
+  on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Run `fn` with this env (for grouped setup); returns nothing. */
+  with(fn: (env: Env<T>) => void): void;
+  /** Run `fn` with this env and return its result. */
+  map<R>(fn: (env: Env<T>) => R): R;
+}
+/** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
+declare function env<const T extends EnvInput<{}>>(input: T, options?: EnvOptions): Env<EnvOutput<{}, T>>;
+//#endregion
+//#region src/provider.d.ts
+/** A value, or a promise of one. */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * An external source of a single field's **raw** value. `load` provides the initial value; the
+ * optional `watch` pushes live updates and returns an unsubscribe function.
+ */
+interface EnvProvider {
+  /** Fetch the current raw value (e.g. query a DB / call a service). `undefined` means "absent". */
+  load(): MaybePromise<string | undefined>;
+  /** Subscribe to live updates; call `emit` with each new raw value. Return an unsubscribe fn. */
+  watch?(emit: (raw: string | undefined) => void): () => void;
+}
+/** A field bound to a live {@link EnvProvider}, validated by `schema`. Created by {@link dynamic}. */
+interface DynamicBinding<V> {
+  readonly kind: 'dynamic';
+  readonly provider: EnvProvider;
+  readonly schema: z.ZodType<V>;
+}
+/** Bind a field to a live {@link EnvProvider}; values are validated against `schema`. */
+declare function dynamic<V>(provider: EnvProvider, schema: z.ZodType<V>): DynamicBinding<V>;
+/** True if `x` is a {@link DynamicBinding}. */
+declare function isDynamic(x: unknown): x is DynamicBinding<unknown>;
+/** A provider that re-fetches on an interval — the simplest way to make any source "dynamic". */
+declare function pollProvider(fetch: () => MaybePromise<string | undefined>, intervalMs: number): EnvProvider;
+/** A fixed-value provider (no updates) — handy for tests and constants behind the provider interface. */
+declare function staticProvider(value: string | undefined): EnvProvider;
+//#endregion
+//#region src/async.d.ts
+/** A field for {@link asyncEnv}: zod schema, dynamic binding, or a (possibly async) factory. */
+type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<any> | ((inherited: Inherited) => MaybePromise<z.ZodType | any>);
+/** The fields passed to {@link asyncEnv} / {@link AsyncEnv.add}. */
+type AsyncEnvInput<Inherited> = Record<string, AsyncEnvFieldDef<Inherited>>;
+/** The resolved output type of an {@link AsyncEnvInput}. */
+type AsyncEnvOutput<Inherited, Input extends AsyncEnvInput<Inherited>> = { [K in keyof Input]: Input[K] extends DynamicBinding<infer V> ? V : Input[K] extends z.ZodType ? z.output<Input[K]> : Input[K] extends ((inherited: Inherited) => infer R) ? Awaited<R> extends z.ZodType ? z.output<Awaited<R>> : Awaited<R> : never };
+/** A typed, lazy, reactive **async** config object built by {@link asyncEnv}. */
+interface AsyncEnv<T extends object> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link AsyncEnv}. */
+  add<A extends AsyncEnvInput<T>>(input: A): AsyncEnv<T & AsyncEnvOutput<T, A>>;
+  /** Resolve a single field (lazily, async). Rejects with an {@link EnvError} if missing/invalid. */
+  get<K extends keyof T>(key: K): Promise<T[K]>;
+  /** Override a single field/source key (typed value or raw string). */
+  set<K extends keyof T>(key: K, value: T[K] | string): void;
+  /** Override several fields/source keys at once. */
+  set(updates: EnvSet<T>): void;
+  /** Resolve every field. Rejects with an aggregated {@link EnvError} listing all failures. */
+  parse(): Promise<T>;
+  /** Subscribe to *all* field changes; the listener gets `(key, value)`. Returns an unsubscribe fn. */
+  on(listener: (key: keyof T, value: T[keyof T]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to one field's changes. */
+  on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Subscribe to several fields' changes with one listener. */
+  on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /** Re-pull dynamic providers (all, or one field) and notify on any change. */
+  refresh(key?: keyof T): Promise<void>;
+  /** Stop all provider watchers. */
+  close(): void;
+  /** Run `fn` with this env (for grouped setup); returns nothing. */
+  with(fn: (env: AsyncEnv<T>) => void): void;
+  /** Run `fn` with this env and return its result. */
+  map<R>(fn: (env: AsyncEnv<T>) => R): R;
+}
+/** Build a typed, lazy, reactive **async** config — supports async factories and live providers. */
+declare function asyncEnv<const T extends AsyncEnvInput<{}>>(input: T, options?: EnvOptions): AsyncEnv<AsyncEnvOutput<{}, T>>;
+//#endregion
+//#region src/meta.d.ts
+/** The aliasing metadata a field may carry. */
+interface EnvMeta {
+  /** A single source key to read this field from. */
+  readonly var?: string;
+  /** Several source keys to read this field from — first present wins. */
+  readonly vars?: readonly string[];
+}
+/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
+declare function varsOf(schema: z.ZodType, key: string): readonly string[];
+/** Attach aliasing metadata: read `schema` from the first present of `keys`. */
+declare function alias<S extends z.ZodType>(schema: S, ...keys: string[]): S;
+//#endregion
+export { type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type MaybePromise, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, isDynamic, mergeSources, parseDotenv, pollProvider, resolveRaw, staticProvider, varsOf };