@e-n-v/env 0.0.2 → 0.0.5

package/README.md

@@ -1,67 +1,61 @@
 <!-- markdownlint-disable-next-line -->
-<img src="./assets/env-logo.png" alt="e-n-v Logo" height="55"/>
+<img src="https://raw.githubusercontent.com/agorischek/e-n-v/main/static/logos/e-n-v.png" alt="e-n-v Logo" height="55"/>
 
 > Environments, niftily? Very!
 
 e·n·v is a suite of handy stuff for working with environment variables and `.env` files, including interactive setup and runtime validation.
 
 ```ts
-// Define environment variables
-const model = define({
-  schemas: { NODE_ENV, DATABASE_URL, PORT },
-});
+/* 1. Define environment variables */
+const model = vars({ PORT, NODE_ENV, API_KEY });
 ```
 
 ```ts
-// Set up during development
-await prompt(model); // or use `e-n-v setup`
+/* 2. Validate at runtime */
+const env = parse(process.env, model);
 ```
 
 ```ts
-// Validate at runtime
-const env = parse(process.env, model);
+/* 3. Set up during development */
+await prompt(model); // or use `e-n-v setup`
 ```
 
 <!-- markdownlint-disable-next-line -->
-<img src="./assets/demo.gif" alt="Demo" width="500"/>
+<img src="https://vhs.charm.sh/vhs-5fQTwW2FbZA42LNteIXA38.gif" alt="Demo" width="500"/>
 
 ## Usage
 
-### 1. Define your model
+### Define your model
 
-An env model defines the structure of your environment variables, including names, schemas, and any preprocessing (e.g. converting `1`/`0` to boolean). This model is used both for development-time setup and runtime validation. e·n·v provides built-in schemas for common variables, and custom schemas can be authored using Zod.
+An env model defines the structure of your environment variables. e·n·v provides built-in schemas for common variables, and custom schemas can be authored using Zod.
 
 ```ts
 // env.model.js
 
-import { define, schemas } from "e-n-v";
-
-const { NODE_ENV, DATABASE_URL, PORT } = schemas;
+import vars, { NODE_ENV, PORT, DATABASE_URL } from "@e-n-v/env/vars";
 
-export default define({
-  schemas: { NODE_ENV, DATABASE_URL, PORT },
-});
+export default vars({ NODE_ENV, PORT, DATABASE_URL });
 ```
 
-### 2. Set up for development
+### Set up for development
 
 Run `e-n-v setup` to interactively author your local `.env` file during development. This can be wrapped in a package script, e.g. `npm run env`. (Alternatively, a `prompt` method is available for programmatic use.)
 
-### 3. Parse at runtime
+### Parse at runtime
 
 In your app, load your environment variables as usual, parse them, and export them for use. A combined error is thrown if any variables fail validation. Reference these exports throughout your code rather than using `process.env` directly.
 
 ```ts
-// env.vars.js
+// env.js
 
 import "dotenv/config";
-import { parse } from "e-n-v";
+import parse from "@e-n-v/env/parse";
 import model from "./env.model";
 
 export const { NODE_ENV, PORT, DATABASE_URL } = parse(process.env, model);
 ```
 
-### 4. Customize
+### Customize
 
 e·n·v provides a variety of customization options, including:
 
@@ -69,4 +63,29 @@ e·n·v provides a variety of customization options, including:
 2. Reading and writing variables via other libraries, e.g. `dotenvx`.
 3. Changing the setup CLI behavior, such as what variables are treated as secrets.
 
-Happy configuration!
+Happy configuring!
+
+## Models
+
+Models define the structure of your environment variables, including names, schemas, and any preprocessing (e.g. converting `1`/`0` to boolean). The `vars` method defines a model with only variable schemas.
+
+```ts
+import vars, { NODE_ENV } from "@e-n-v/env/vars";
+
+export default vars({ NODE_ENV });
+```
+
+If you also want to define custom preprocessing, use `define` instead. Preprocessors are run before values are submitted to schemas for validation.
+
+```ts
+import { define, schemas } from "@e-n-v/env";
+
+const { NODE_ENV } = schemas;
+
+export default define({
+  schemas: { NODE_ENV },
+  preprocess: {
+    boolean: (value) => value === "true",
+  },
+});
+```

package/dist/BooleanMap-B2eIP3tZ.d.cts

@@ -0,0 +1,32 @@
+import { a as EnumEnvVarSchema, r as NumberEnvVarSchema, s as BooleanEnvVarSchema, t as StringEnvVarSchema } from "./StringEnvVarSchema-BF6C0nyT.cjs";
+
+//#region ../core/src/schemas/EnvVarSchema.d.ts
+
+type EnvVarSchema = StringEnvVarSchema | NumberEnvVarSchema | BooleanEnvVarSchema | EnumEnvVarSchema<any>;
+/**
+ * Type guard to check if a value is a EnvVarSchema instance
+ */
+declare function isEnvVarSchema(value: unknown): value is EnvVarSchema;
+//#endregion
+//#region ../core/src/processing/types/Preprocessor.d.ts
+/**
+ * Custom preprocessing functions to preprocess values before submitting to schema processors.
+ * Provide `false` to skip preprocessing, `true` to use the built-in default, or a function/options object for custom logic.
+ * These functions do not guarantee type casting and can be bypassed to skip preprocessing entirely.
+ */
+type Preprocessor<T> = (value: string) => T | string;
+type PreprocessorToggle<T> = Preprocessor<T> | boolean | undefined;
+//#endregion
+//#region ../core/src/processing/options/BooleanMap.d.ts
+/**
+ * Shared boolean coercion configuration.
+ * These values are recognized as boolean strings across processors and preprocessors.
+ */
+interface BooleanMap {
+  /** Values that map to true */
+  true: readonly string[];
+  /** Values that map to false */
+  false: readonly string[];
+}
+//#endregion
+export { isEnvVarSchema as a, EnvVarSchema as i, Preprocessor as n, PreprocessorToggle as r, BooleanMap as t };

package/dist/BooleanMap-DmFnCA-O.d.ts

@@ -0,0 +1,32 @@
+import { a as EnumEnvVarSchema, r as NumberEnvVarSchema, s as BooleanEnvVarSchema, t as StringEnvVarSchema } from "./StringEnvVarSchema-B8MT7htU.js";
+
+//#region ../core/src/schemas/EnvVarSchema.d.ts
+
+type EnvVarSchema = StringEnvVarSchema | NumberEnvVarSchema | BooleanEnvVarSchema | EnumEnvVarSchema<any>;
+/**
+ * Type guard to check if a value is a EnvVarSchema instance
+ */
+declare function isEnvVarSchema(value: unknown): value is EnvVarSchema;
+//#endregion
+//#region ../core/src/processing/types/Preprocessor.d.ts
+/**
+ * Custom preprocessing functions to preprocess values before submitting to schema processors.
+ * Provide `false` to skip preprocessing, `true` to use the built-in default, or a function/options object for custom logic.
+ * These functions do not guarantee type casting and can be bypassed to skip preprocessing entirely.
+ */
+type Preprocessor<T> = (value: string) => T | string;
+type PreprocessorToggle<T> = Preprocessor<T> | boolean | undefined;
+//#endregion
+//#region ../core/src/processing/options/BooleanMap.d.ts
+/**
+ * Shared boolean coercion configuration.
+ * These values are recognized as boolean strings across processors and preprocessors.
+ */
+interface BooleanMap {
+  /** Values that map to true */
+  true: readonly string[];
+  /** Values that map to false */
+  false: readonly string[];
+}
+//#endregion
+export { isEnvVarSchema as a, EnvVarSchema as i, Preprocessor as n, PreprocessorToggle as r, BooleanMap as t };

package/dist/EnvChannel-LMIRYvT1.d.cts

@@ -0,0 +1,16 @@
+//#region ../core/src/types/EnvChannel.d.ts
+/**
+ * Interface for accessing and modifying environment variables
+ */
+interface EnvChannel {
+  /**
+   * Get environment variables
+   */
+  get(keys?: string[]): Promise<Record<string, string>>;
+  /**
+   * Set environment variables
+   */
+  set(values: Record<string, string>): Promise<void>;
+}
+//#endregion
+export { EnvChannel as t };

package/dist/EnvChannel-w27PEm7x.d.ts

@@ -0,0 +1,16 @@
+//#region ../core/src/types/EnvChannel.d.ts
+/**
+ * Interface for accessing and modifying environment variables
+ */
+interface EnvChannel {
+  /**
+   * Get environment variables
+   */
+  get(keys?: string[]): Promise<Record<string, string>>;
+  /**
+   * Set environment variables
+   */
+  set(values: Record<string, string>): Promise<void>;
+}
+//#endregion
+export { EnvChannel as t };

package/dist/EnvChannelOptions-BPkWDrmr.d.cts

@@ -0,0 +1,108 @@
+import { DotenvConfigOptions, DotenvConfigOutput, GetOptions, SetOptions } from "@dotenvx/dotenvx";
+
+//#region ../channels/src/channels/dotenv/DotEnvInstance.d.ts
+interface DotEnvConfigOptions {
+  path?: string;
+  encoding?: string;
+  debug?: boolean;
+  override?: boolean;
+  [key: string]: unknown;
+}
+interface DotEnvConfigOutput {
+  parsed?: Record<string, string>;
+  error?: Error;
+}
+interface DotEnvParseOptions {
+  debug?: boolean;
+  [key: string]: unknown;
+}
+interface DotEnvInstance {
+  parse(src: string | Buffer, options?: DotEnvParseOptions): Record<string, string | undefined>;
+  config?(options?: DotEnvConfigOptions): DotEnvConfigOutput;
+}
+//#endregion
+//#region ../channels/src/channels/dotenv/DotEnvChannelConfig.d.ts
+interface DotEnvChannelConfig {
+  dotenv: DotEnvInstance;
+  path?: string;
+  get?: DotEnvConfigOptions & {
+    [key: string]: unknown;
+  };
+  parse?: DotEnvParseOptions & {
+    [key: string]: unknown;
+  };
+}
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXInstance.d.ts
+/**
+ * Minimal interface for dotenvx functionality used in ask-env.
+ */
+interface DotEnvXInstance {
+  get(key: string, options?: GetOptions): string;
+  set(key: string, value: string, options?: SetOptions): unknown;
+  config(options?: DotenvConfigOptions): DotenvConfigOutput;
+}
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXGetOptions.d.ts
+/**
+ * Get options without envKeysFile since we manage that ourselves
+ */
+type DotEnvXGetOptions = Omit<GetOptions, "envKeysFile">;
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXSetOptions.d.ts
+/**
+ * Set options without envKeysFile since we manage that ourselves
+ */
+type DotEnvXSetOptions = Omit<SetOptions, "envKeysFile">;
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXChannelConfig.d.ts
+/**
+ * DotEnvX channel configuration
+ */
+interface DotEnvXChannelConfig {
+  dotenvx: DotEnvXInstance;
+  get?: DotEnvXGetOptions & {
+    [key: string]: unknown;
+  };
+  set?: DotEnvXSetOptions & {
+    [key: string]: unknown;
+  };
+}
+//#endregion
+//#region ../channels/src/channels/default/DefaultChannelConfig.d.ts
+/**
+ * Default channel configuration
+ */
+interface DefaultChannelConfig {
+  name: "default";
+}
+//#endregion
+//#region ../channels/src/channels/processenv/ProcessEnvChannelConfig.d.ts
+/**
+ * Configuration for ProcessEnv channel using name
+ */
+interface ProcessEnvChannelConfig {
+  name: "processenv";
+}
+/**
+ * Configuration for ProcessEnv channel using process shorthand
+ */
+interface ProcessChannelConfig {
+  process: NodeJS.Process;
+}
+//#endregion
+//#region ../channels/src/EnvChannelOptions.d.ts
+/**
+ * Channel options can be:
+ * - undefined (uses default channel)
+ * - "default" string (uses default channel)
+ * - "processenv" string (uses process.env channel)
+ * - dotenvx instance (uses dotenvx with default options)
+ * - DotEnvXChannelConfig (uses dotenvx with custom options)
+ * - DefaultChannelConfig (uses default with custom options)
+ * - ProcessEnvChannelConfig (uses process.env with config options)
+ * - ProcessChannelConfig (uses process.env with { process } notation)
+ */
+type EnvChannelOptions = undefined | "default" | "processenv" | DotEnvChannelConfig | DotEnvXChannelConfig | DefaultChannelConfig | ProcessEnvChannelConfig | ProcessChannelConfig;
+//#endregion
+export { DotEnvXChannelConfig as a, DotEnvXInstance as c, DotEnvConfigOutput as d, DotEnvInstance as f, DefaultChannelConfig as i, DotEnvChannelConfig as l, ProcessChannelConfig as n, DotEnvXSetOptions as o, DotEnvParseOptions as p, ProcessEnvChannelConfig as r, DotEnvXGetOptions as s, EnvChannelOptions as t, DotEnvConfigOptions as u };

package/dist/EnvChannelOptions-CRwDLWjd.d.ts

@@ -0,0 +1,108 @@
+import { DotenvConfigOptions, DotenvConfigOutput, GetOptions, SetOptions } from "@dotenvx/dotenvx";
+
+//#region ../channels/src/channels/dotenv/DotEnvInstance.d.ts
+interface DotEnvConfigOptions {
+  path?: string;
+  encoding?: string;
+  debug?: boolean;
+  override?: boolean;
+  [key: string]: unknown;
+}
+interface DotEnvConfigOutput {
+  parsed?: Record<string, string>;
+  error?: Error;
+}
+interface DotEnvParseOptions {
+  debug?: boolean;
+  [key: string]: unknown;
+}
+interface DotEnvInstance {
+  parse(src: string | Buffer, options?: DotEnvParseOptions): Record<string, string | undefined>;
+  config?(options?: DotEnvConfigOptions): DotEnvConfigOutput;
+}
+//#endregion
+//#region ../channels/src/channels/dotenv/DotEnvChannelConfig.d.ts
+interface DotEnvChannelConfig {
+  dotenv: DotEnvInstance;
+  path?: string;
+  get?: DotEnvConfigOptions & {
+    [key: string]: unknown;
+  };
+  parse?: DotEnvParseOptions & {
+    [key: string]: unknown;
+  };
+}
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXInstance.d.ts
+/**
+ * Minimal interface for dotenvx functionality used in ask-env.
+ */
+interface DotEnvXInstance {
+  get(key: string, options?: GetOptions): string;
+  set(key: string, value: string, options?: SetOptions): unknown;
+  config(options?: DotenvConfigOptions): DotenvConfigOutput;
+}
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXGetOptions.d.ts
+/**
+ * Get options without envKeysFile since we manage that ourselves
+ */
+type DotEnvXGetOptions = Omit<GetOptions, "envKeysFile">;
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXSetOptions.d.ts
+/**
+ * Set options without envKeysFile since we manage that ourselves
+ */
+type DotEnvXSetOptions = Omit<SetOptions, "envKeysFile">;
+//#endregion
+//#region ../channels/src/channels/dotenvx/DotEnvXChannelConfig.d.ts
+/**
+ * DotEnvX channel configuration
+ */
+interface DotEnvXChannelConfig {
+  dotenvx: DotEnvXInstance;
+  get?: DotEnvXGetOptions & {
+    [key: string]: unknown;
+  };
+  set?: DotEnvXSetOptions & {
+    [key: string]: unknown;
+  };
+}
+//#endregion
+//#region ../channels/src/channels/default/DefaultChannelConfig.d.ts
+/**
+ * Default channel configuration
+ */
+interface DefaultChannelConfig {
+  name: "default";
+}
+//#endregion
+//#region ../channels/src/channels/processenv/ProcessEnvChannelConfig.d.ts
+/**
+ * Configuration for ProcessEnv channel using name
+ */
+interface ProcessEnvChannelConfig {
+  name: "processenv";
+}
+/**
+ * Configuration for ProcessEnv channel using process shorthand
+ */
+interface ProcessChannelConfig {
+  process: NodeJS.Process;
+}
+//#endregion
+//#region ../channels/src/EnvChannelOptions.d.ts
+/**
+ * Channel options can be:
+ * - undefined (uses default channel)
+ * - "default" string (uses default channel)
+ * - "processenv" string (uses process.env channel)
+ * - dotenvx instance (uses dotenvx with default options)
+ * - DotEnvXChannelConfig (uses dotenvx with custom options)
+ * - DefaultChannelConfig (uses default with custom options)
+ * - ProcessEnvChannelConfig (uses process.env with config options)
+ * - ProcessChannelConfig (uses process.env with { process } notation)
+ */
+type EnvChannelOptions = undefined | "default" | "processenv" | DotEnvChannelConfig | DotEnvXChannelConfig | DefaultChannelConfig | ProcessEnvChannelConfig | ProcessChannelConfig;
+//#endregion
+export { DotEnvXChannelConfig as a, DotEnvXInstance as c, DotEnvConfigOutput as d, DotEnvInstance as f, DefaultChannelConfig as i, DotEnvChannelConfig as l, ProcessChannelConfig as n, DotEnvXSetOptions as o, DotEnvParseOptions as p, ProcessEnvChannelConfig as r, DotEnvXGetOptions as s, EnvChannelOptions as t, DotEnvConfigOptions as u };

package/dist/EnvModel-CrGclUpJ.d.cts

@@ -0,0 +1,134 @@
+import { a as EnumEnvVarSchema, l as EnvVarSchemaBase, r as NumberEnvVarSchema, s as BooleanEnvVarSchema, t as StringEnvVarSchema } from "./StringEnvVarSchema-BF6C0nyT.cjs";
+import { i as EnvVarSchema, n as Preprocessor, t as BooleanMap } from "./BooleanMap-B2eIP3tZ.cjs";
+import { AnySchema } from "joi";
+import { ZodTypeAny } from "zod";
+import { $ZodType } from "zod/v4/core";
+import { Struct } from "superstruct";
+
+//#region ../models/src/schemas.d.ts
+type JoiSchema = AnySchema;
+type ZodV3Schema = ZodTypeAny;
+type ZodV4Schema = $ZodType;
+type SuperstructSchema = Struct<any, any>;
+type Schema = ZodV3Schema | ZodV4Schema | JoiSchema | SuperstructSchema | EnvVarSchema;
+//#endregion
+//#region ../models/src/types.d.ts
+/**
+ * Supported schema types - local definition to avoid circular dependencies
+ */
+type SupportedSchema = Schema;
+type InferZodOutput<T> = T extends {
+  _output: infer Output;
+} ? Output : T extends {
+  _type: infer LegacyOutput;
+} ? LegacyOutput : never;
+type InferJoiOutput<T> = T extends {
+  validate: (...args: any[]) => infer Result;
+} ? Result extends {
+  value: infer Value;
+} ? Value : Result extends Promise<infer AsyncResult> ? AsyncResult extends {
+  value: infer AsyncValue;
+} ? AsyncValue : unknown : unknown : T extends {
+  validateAsync: (...args: any[]) => Promise<infer AsyncValue>;
+} ? AsyncValue : unknown;
+/**
+ * Infer the TypeScript type from an EnvVarSchema instance
+ * Uses the schema's type property and values to determine the correct TypeScript type
+ */
+type InferSchemaType<T> = T extends {
+  readonly type: "string";
+} ? string : T extends {
+  readonly type: "number";
+} ? number : T extends {
+  readonly type: "boolean";
+} ? boolean : T extends {
+  readonly type: "enum";
+  readonly values: readonly (infer U)[];
+} ? U : T extends EnumEnvVarSchema<infer U> ? U : T extends NumberEnvVarSchema ? number : T extends StringEnvVarSchema ? string : T extends BooleanEnvVarSchema ? boolean : T extends EnvVarSchemaBase<infer U> ? U : T extends AnySchema ? InferJoiOutput<T> : T extends ZodTypeAny ? InferZodOutput<T> : T extends $ZodType ? InferZodOutput<T> : unknown;
+/**
+ * Infer whether a schema field is optional based on its required property
+ */
+type InferOptional<T> = T extends {
+  required: false;
+} ? true : T extends {
+  required: true;
+} ? false : T extends {
+  required: boolean;
+} ? boolean : false;
+/**
+ * Utility type to flatten complex generic types for better IDE display
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Infer the complete environment type from a schemas record
+ * Handles optional vs required fields properly
+ * Uses Simplify to flatten the type display in IDEs
+ */
+type InferEnvType<T extends Record<string, SupportedSchema>> = Simplify<{ [K in keyof T]: InferOptional<T[K]> extends true ? InferSchemaType<T[K]> | undefined : InferSchemaType<T[K]> }>;
+//#endregion
+//#region ../models/src/EnvModelOptions.d.ts
+type PreprocessorToggle<T> = Preprocessor<T> | boolean | undefined;
+interface Preprocessors {
+  /**
+   * Custom string preprocessing function
+   */
+  string?: PreprocessorToggle<string>;
+  /**
+   * Custom number preprocessing function
+   */
+  number?: PreprocessorToggle<number>;
+  /**
+   * Custom boolean preprocessing function
+   */
+  boolean?: boolean | Preprocessor<boolean> | BooleanMap | undefined;
+  /**
+   * Custom enum preprocessing function
+   */
+  enum?: PreprocessorToggle<string>;
+}
+/**
+ * Options for creating an EnvModel instance
+ */
+interface EnvModelOptions<T extends Record<string, SupportedSchema> = Record<string, SupportedSchema>> {
+  /**
+   * Environment variable schemas
+   * Map of variable names to their schema definitions
+   */
+  schemas: T;
+  /**
+   * Preprocessing configuration
+   * - `true`: Use default preprocessors for all types
+   * - `false`: Disable all preprocessing
+   * - Partial object: Customize specific type preprocessors
+   */
+  preprocess?: true | false | Partial<Preprocessors>;
+}
+//#endregion
+//#region ../models/src/EnvModel.d.ts
+/**
+ * Environment variable specification container
+ * Encapsulates schemas and preprocessor configuration
+ */
+declare class EnvModel<T extends Record<string, SupportedSchema> = Record<string, SupportedSchema>> {
+  /**
+   * Resolved environment variable schemas
+   */
+  readonly schemas: Record<string, EnvVarSchema>;
+  /**
+   * Preprocessing configuration for environment variable types
+   */
+  readonly preprocess: Preprocessors;
+  /**
+   * Create an EnvModel instance from options
+   * @param options - Specification options
+   */
+  constructor(options: EnvModelOptions<T>);
+  /**
+   * Resolve preprocessor configuration from options
+   * @param config - Preprocessor configuration (true, false, or partial object)
+   * @returns Resolved preprocessors object
+   */
+  private resolvePreprocessors;
+}
+//#endregion
+export { SupportedSchema as a, InferSchemaType as i, EnvModelOptions as n, Schema as o, InferEnvType as r, EnvModel as t };