@xlameiro/env-typegen 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,271 @@
+/**
+ * Supported TypeScript types that env-typegen can infer or generate.
+ * The inference engine maps each .env.example value to one of these.
+ */
+type EnvVarType = "string" | "number" | "boolean" | "url" | "email" | "semver" | "json" | "unknown";
+/**
+ * A single parsed environment variable from a .env.example file.
+ * Produced by the parser after reading and associating comment blocks.
+ */
+type ParsedEnvVar = {
+    /** The variable name as written in .env.example (e.g. DATABASE_URL) */
+    key: string;
+    /** Raw string value from .env.example before any processing */
+    rawValue: string;
+    /** Type inferred by the inference engine from key pattern and value */
+    inferredType: EnvVarType;
+    /** Type explicitly declared with @type in a preceding JSDoc comment block */
+    annotatedType?: EnvVarType;
+    /** Description from @description annotation or a free-form comment on the preceding line */
+    description?: string;
+    /** true when the value is non-empty OR the variable has @required annotation */
+    isRequired: boolean;
+    /** true when the value is empty and there is no @required annotation */
+    isOptional: boolean;
+    /** true when the key starts with NEXT_PUBLIC_ */
+    isClientSide: boolean;
+    /** Nearest enclosing section header, e.g. "--- Auth ---" → "Auth" */
+    group?: string;
+    /** 1-based line number of the KEY=VALUE line in the source file */
+    lineNumber: number;
+};
+/**
+ * The complete result of parsing a single .env.example file.
+ * Passed to generators to produce TypeScript / Zod / t3-env output.
+ */
+type ParsedEnvFile = {
+    /** Resolved absolute path to the source .env.example file */
+    filePath: string;
+    /** All parsed variables in source order */
+    vars: ParsedEnvVar[];
+    /** Unique group names found in the file, in order of appearance */
+    groups: string[];
+};
+
+/**
+ * Structured annotations extracted from a JSDoc-style comment block
+ * that precedes an env var declaration.
+ *
+ * @example
+ * ```
+ * # @description PostgreSQL connection string
+ * # @required
+ * # @type string
+ * DATABASE_URL=
+ * ```
+ */
+type CommentAnnotations = {
+    /** Type explicitly declared with `@type` in the comment block */
+    annotatedType?: EnvVarType;
+    /** Description from `@description` or the first free-form comment line */
+    description?: string;
+    /** true when the `@required` annotation is present in the comment block */
+    isRequired: boolean;
+};
+/**
+ * Parse a block of consecutive comment lines (each starting with `#`) and
+ * extract JSDoc-style annotations.
+ *
+ * Recognised annotations:
+ * - `@description <text>` — sets the variable description
+ * - `@required`           — marks the variable as required regardless of value
+ * - `@optional`           — informational (isRequired stays false)
+ * - `@type <EnvVarType>`  — overrides the inferred type
+ *
+ * Non-annotation comment lines act as a fallback description when no
+ * `@description` annotation is present (first non-empty line wins).
+ *
+ * @param lines - Raw comment lines from the .env file, e.g. `["# @required"]`
+ */
+declare function parseCommentBlock(lines: readonly string[]): CommentAnnotations;
+
+type InferenceRule = {
+    id: string;
+    priority: number;
+    match: (key: string, value: string) => boolean;
+    type: EnvVarType;
+};
+declare const inferenceRules: readonly InferenceRule[];
+
+type InferTypeOptions = {
+    fallbackType?: EnvVarType;
+};
+declare function inferType(key: string, value: string, options?: InferTypeOptions): EnvVarType;
+declare function inferTypesFromParsedVars(parsed: {
+    vars: Array<{
+        key: string;
+        rawValue: string;
+    }>;
+}, options?: InferTypeOptions): EnvVarType[];
+
+/**
+ * Parse the string content of a `.env.example` file into a `ParsedEnvFile`.
+ *
+ * Exposed separately from `parseEnvFile` to enable unit testing without
+ * filesystem access.
+ *
+ * @param content  - Raw file content as a UTF-8 string
+ * @param filePath - Used to populate `ParsedEnvFile.filePath` only
+ */
+declare function parseEnvFileContent(content: string, filePath: string): ParsedEnvFile;
+/**
+ * Read and parse a `.env.example` file from disk.
+ *
+ * @param filePath - Absolute or relative path to the file
+ */
+declare function parseEnvFile(filePath: string): ParsedEnvFile;
+
+/**
+ * Generates a TypeScript source file from a parsed .env.example file.
+ *
+ * Output structure:
+ * 1. Header comments — generated-by notice, source file name, ISO timestamp
+ * 2. `declare namespace NodeJS { interface ProcessEnv { ... } }` — global augmentation
+ *    where all properties are typed as `readonly string` (the runtime reality).
+ *    Number and boolean vars include an inline coercion hint comment.
+ * 3. `export type EnvVars = { ... }` — typed module export using semantic types
+ *    (number, boolean, string).
+ * 4. `ServerEnvVars` / `ClientEnvVars` — emitted only when `NEXT_PUBLIC_` vars exist.
+ *
+ * The output is valid as both a `.ts` and `.d.ts` file.
+ * For an ambient-only `.d.ts` (without `export type` statements), use
+ * `generateDeclaration` instead.
+ *
+ * `annotatedType` takes precedence over `inferredType` when both are set.
+ */
+declare function generateTypeScriptTypes(parsed: ParsedEnvFile): string;
+/**
+ * Generates a runtime `validateEnv()` function that throws when any required
+ * environment variable is absent from `process.env`.
+ */
+declare function generateEnvValidation(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates a Zod schema file from a parsed .env.example file.
+ *
+ * Output structure:
+ * ```
+ * // Generated by env-typegen — do not edit manually
+ * import { z } from "zod";
+ *
+ * export const serverEnvSchema = z.object({
+ *   DATABASE_URL: z.string().url(),
+ *   PORT: z.coerce.number(),
+ * });
+ *
+ * export const clientEnvSchema = z.object({
+ *   NEXT_PUBLIC_API_URL: z.string().url(),
+ * });
+ *
+ * export const envSchema = serverEnvSchema.merge(clientEnvSchema);
+ * export type Env = z.infer<typeof envSchema>;
+ * ```
+ *
+ * - Server-side vars (non-`NEXT_PUBLIC_`) go into `serverEnvSchema`
+ * - Client-side vars (`NEXT_PUBLIC_` prefix) go into `clientEnvSchema`
+ * - `envSchema` is the merged union of both, for full-stack validation
+ * - `annotatedType` takes precedence over `inferredType` when both are set
+ * - Optional vars have `.optional()` appended to their Zod expression
+ */
+declare function generateZodSchema(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates an ambient `.d.ts` declaration file from a parsed .env.example.
+ *
+ * Output is a pure `NodeJS.ProcessEnv` augmentation — no `export type` statements.
+ * This makes the file valid as a global ambient declaration that can be dropped
+ * into `lib/` or `types/` without affecting module resolution.
+ *
+ * Output structure:
+ * ```
+ * // Generated by env-typegen — do not edit manually
+ * // Source: .env.example
+ *
+ * declare namespace NodeJS {
+ *   interface ProcessEnv {
+ *     readonly KEY: string;     // all vars are runtime strings
+ *     readonly OPT?: string;    // optional vars use ?: string
+ *     readonly NUM: string;     // coerce to number: Number(process.env.NUM)
+ *     readonly FLAG: string;    // coerce to boolean: process.env.FLAG === 'true'
+ *   }
+ * }
+ * ```
+ *
+ * For a `.ts` output with typed `export type EnvVars` / `ServerEnvVars` /
+ * `ClientEnvVars`, use `generateTypeScriptTypes` instead.
+ *
+ * - `ProcessEnv` uses `readonly string` for every variable (runtime reality)
+ * - Number and boolean vars include an inline coercion hint comment
+ * - `annotatedType` takes precedence over `inferredType`
+ */
+declare function generateDeclaration(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates a `@t3-oss/env-nextjs` configuration file from a parsed .env.example.
+ *
+ * Output structure:
+ * ```
+ * import { createEnv } from "@t3-oss/env-nextjs";
+ * import { z } from "zod";
+ *
+ * export const env = createEnv({
+ *   server: { /* non-NEXT_PUBLIC_ vars *\/ },
+ *   client: { /* NEXT_PUBLIC_ vars *\/ },
+ *   runtimeEnv: { /* all vars mapped to process.env *\/ },
+ * });
+ * ```
+ *
+ * - `server:` is omitted when there are no server-side vars
+ * - `client:` is omitted when there are no client-side vars (NEXT_PUBLIC_ prefix)
+ * - `runtimeEnv:` always includes all vars
+ * - `annotatedType` takes precedence over `inferredType`
+ * - Optional vars have `.optional()` appended
+ * - Vars with a description have `.describe("text")` appended (before `.optional()`)
+ */
+declare function generateT3Env(parsed: ParsedEnvFile): string;
+
+/** Generator identifiers supported by env-typegen. */
+type GeneratorName = "typescript" | "zod" | "t3" | "declaration";
+/** Configuration shape accepted by env-typegen's CLI and programmatic API. */
+type EnvTypegenConfig = {
+    /** Path to the .env.example file to parse. */
+    input: string;
+    /** Output directory for generated files. Defaults to the input file's directory. */
+    output?: string;
+    /** Which generators to run. When omitted, all four generators run. */
+    generators?: GeneratorName[];
+    /** Format generated output with prettier. Defaults to true. */
+    format?: boolean;
+};
+/**
+ * Type-safe config helper.
+ * Returns the config object unchanged — exists purely for IDE autocompletion
+ * and compile-time validation of the config shape.
+ */
+declare function defineConfig(config: EnvTypegenConfig): EnvTypegenConfig;
+/**
+ * Loads env-typegen config by searching for a config file in `cwd`.
+ * Searches for env-typegen.config.ts → .mjs → .js in order.
+ * Returns `undefined` when no config file is found.
+ */
+declare function loadConfig(cwd?: string): Promise<EnvTypegenConfig | undefined>;
+
+/** Options accepted by the runGenerate pipeline. */
+type RunGenerateOptions = {
+    input: string;
+    output: string;
+    generators: GeneratorName[];
+    format: boolean;
+    stdout?: boolean;
+    dryRun?: boolean;
+    silent?: boolean;
+};
+/**
+ * Reads the input file, runs the requested generators, optionally formats each
+ * output, and writes the results to disk.
+ *
+ * Exported for unit testing — call this directly rather than spawning a child process.
+ */
+declare function runGenerate(options: RunGenerateOptions): Promise<void>;
+
+export { type CommentAnnotations, type EnvTypegenConfig, type EnvVarType, type GeneratorName, type InferenceRule, type ParsedEnvFile, type ParsedEnvVar, type RunGenerateOptions, defineConfig, generateDeclaration, generateEnvValidation, generateT3Env, generateTypeScriptTypes as generateTypeScript, generateTypeScriptTypes, generateZodSchema as generateZod, generateZodSchema, inferType, inferTypesFromParsedVars as inferTypes, inferenceRules, loadConfig, parseCommentBlock, parseEnvFile, parseEnvFileContent, runGenerate };

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Supported TypeScript types that env-typegen can infer or generate.
+ * The inference engine maps each .env.example value to one of these.
+ */
+type EnvVarType = "string" | "number" | "boolean" | "url" | "email" | "semver" | "json" | "unknown";
+/**
+ * A single parsed environment variable from a .env.example file.
+ * Produced by the parser after reading and associating comment blocks.
+ */
+type ParsedEnvVar = {
+    /** The variable name as written in .env.example (e.g. DATABASE_URL) */
+    key: string;
+    /** Raw string value from .env.example before any processing */
+    rawValue: string;
+    /** Type inferred by the inference engine from key pattern and value */
+    inferredType: EnvVarType;
+    /** Type explicitly declared with @type in a preceding JSDoc comment block */
+    annotatedType?: EnvVarType;
+    /** Description from @description annotation or a free-form comment on the preceding line */
+    description?: string;
+    /** true when the value is non-empty OR the variable has @required annotation */
+    isRequired: boolean;
+    /** true when the value is empty and there is no @required annotation */
+    isOptional: boolean;
+    /** true when the key starts with NEXT_PUBLIC_ */
+    isClientSide: boolean;
+    /** Nearest enclosing section header, e.g. "--- Auth ---" → "Auth" */
+    group?: string;
+    /** 1-based line number of the KEY=VALUE line in the source file */
+    lineNumber: number;
+};
+/**
+ * The complete result of parsing a single .env.example file.
+ * Passed to generators to produce TypeScript / Zod / t3-env output.
+ */
+type ParsedEnvFile = {
+    /** Resolved absolute path to the source .env.example file */
+    filePath: string;
+    /** All parsed variables in source order */
+    vars: ParsedEnvVar[];
+    /** Unique group names found in the file, in order of appearance */
+    groups: string[];
+};
+
+/**
+ * Structured annotations extracted from a JSDoc-style comment block
+ * that precedes an env var declaration.
+ *
+ * @example
+ * ```
+ * # @description PostgreSQL connection string
+ * # @required
+ * # @type string
+ * DATABASE_URL=
+ * ```
+ */
+type CommentAnnotations = {
+    /** Type explicitly declared with `@type` in the comment block */
+    annotatedType?: EnvVarType;
+    /** Description from `@description` or the first free-form comment line */
+    description?: string;
+    /** true when the `@required` annotation is present in the comment block */
+    isRequired: boolean;
+};
+/**
+ * Parse a block of consecutive comment lines (each starting with `#`) and
+ * extract JSDoc-style annotations.
+ *
+ * Recognised annotations:
+ * - `@description <text>` — sets the variable description
+ * - `@required`           — marks the variable as required regardless of value
+ * - `@optional`           — informational (isRequired stays false)
+ * - `@type <EnvVarType>`  — overrides the inferred type
+ *
+ * Non-annotation comment lines act as a fallback description when no
+ * `@description` annotation is present (first non-empty line wins).
+ *
+ * @param lines - Raw comment lines from the .env file, e.g. `["# @required"]`
+ */
+declare function parseCommentBlock(lines: readonly string[]): CommentAnnotations;
+
+type InferenceRule = {
+    id: string;
+    priority: number;
+    match: (key: string, value: string) => boolean;
+    type: EnvVarType;
+};
+declare const inferenceRules: readonly InferenceRule[];
+
+type InferTypeOptions = {
+    fallbackType?: EnvVarType;
+};
+declare function inferType(key: string, value: string, options?: InferTypeOptions): EnvVarType;
+declare function inferTypesFromParsedVars(parsed: {
+    vars: Array<{
+        key: string;
+        rawValue: string;
+    }>;
+}, options?: InferTypeOptions): EnvVarType[];
+
+/**
+ * Parse the string content of a `.env.example` file into a `ParsedEnvFile`.
+ *
+ * Exposed separately from `parseEnvFile` to enable unit testing without
+ * filesystem access.
+ *
+ * @param content  - Raw file content as a UTF-8 string
+ * @param filePath - Used to populate `ParsedEnvFile.filePath` only
+ */
+declare function parseEnvFileContent(content: string, filePath: string): ParsedEnvFile;
+/**
+ * Read and parse a `.env.example` file from disk.
+ *
+ * @param filePath - Absolute or relative path to the file
+ */
+declare function parseEnvFile(filePath: string): ParsedEnvFile;
+
+/**
+ * Generates a TypeScript source file from a parsed .env.example file.
+ *
+ * Output structure:
+ * 1. Header comments — generated-by notice, source file name, ISO timestamp
+ * 2. `declare namespace NodeJS { interface ProcessEnv { ... } }` — global augmentation
+ *    where all properties are typed as `readonly string` (the runtime reality).
+ *    Number and boolean vars include an inline coercion hint comment.
+ * 3. `export type EnvVars = { ... }` — typed module export using semantic types
+ *    (number, boolean, string).
+ * 4. `ServerEnvVars` / `ClientEnvVars` — emitted only when `NEXT_PUBLIC_` vars exist.
+ *
+ * The output is valid as both a `.ts` and `.d.ts` file.
+ * For an ambient-only `.d.ts` (without `export type` statements), use
+ * `generateDeclaration` instead.
+ *
+ * `annotatedType` takes precedence over `inferredType` when both are set.
+ */
+declare function generateTypeScriptTypes(parsed: ParsedEnvFile): string;
+/**
+ * Generates a runtime `validateEnv()` function that throws when any required
+ * environment variable is absent from `process.env`.
+ */
+declare function generateEnvValidation(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates a Zod schema file from a parsed .env.example file.
+ *
+ * Output structure:
+ * ```
+ * // Generated by env-typegen — do not edit manually
+ * import { z } from "zod";
+ *
+ * export const serverEnvSchema = z.object({
+ *   DATABASE_URL: z.string().url(),
+ *   PORT: z.coerce.number(),
+ * });
+ *
+ * export const clientEnvSchema = z.object({
+ *   NEXT_PUBLIC_API_URL: z.string().url(),
+ * });
+ *
+ * export const envSchema = serverEnvSchema.merge(clientEnvSchema);
+ * export type Env = z.infer<typeof envSchema>;
+ * ```
+ *
+ * - Server-side vars (non-`NEXT_PUBLIC_`) go into `serverEnvSchema`
+ * - Client-side vars (`NEXT_PUBLIC_` prefix) go into `clientEnvSchema`
+ * - `envSchema` is the merged union of both, for full-stack validation
+ * - `annotatedType` takes precedence over `inferredType` when both are set
+ * - Optional vars have `.optional()` appended to their Zod expression
+ */
+declare function generateZodSchema(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates an ambient `.d.ts` declaration file from a parsed .env.example.
+ *
+ * Output is a pure `NodeJS.ProcessEnv` augmentation — no `export type` statements.
+ * This makes the file valid as a global ambient declaration that can be dropped
+ * into `lib/` or `types/` without affecting module resolution.
+ *
+ * Output structure:
+ * ```
+ * // Generated by env-typegen — do not edit manually
+ * // Source: .env.example
+ *
+ * declare namespace NodeJS {
+ *   interface ProcessEnv {
+ *     readonly KEY: string;     // all vars are runtime strings
+ *     readonly OPT?: string;    // optional vars use ?: string
+ *     readonly NUM: string;     // coerce to number: Number(process.env.NUM)
+ *     readonly FLAG: string;    // coerce to boolean: process.env.FLAG === 'true'
+ *   }
+ * }
+ * ```
+ *
+ * For a `.ts` output with typed `export type EnvVars` / `ServerEnvVars` /
+ * `ClientEnvVars`, use `generateTypeScriptTypes` instead.
+ *
+ * - `ProcessEnv` uses `readonly string` for every variable (runtime reality)
+ * - Number and boolean vars include an inline coercion hint comment
+ * - `annotatedType` takes precedence over `inferredType`
+ */
+declare function generateDeclaration(parsed: ParsedEnvFile): string;
+
+/**
+ * Generates a `@t3-oss/env-nextjs` configuration file from a parsed .env.example.
+ *
+ * Output structure:
+ * ```
+ * import { createEnv } from "@t3-oss/env-nextjs";
+ * import { z } from "zod";
+ *
+ * export const env = createEnv({
+ *   server: { /* non-NEXT_PUBLIC_ vars *\/ },
+ *   client: { /* NEXT_PUBLIC_ vars *\/ },
+ *   runtimeEnv: { /* all vars mapped to process.env *\/ },
+ * });
+ * ```
+ *
+ * - `server:` is omitted when there are no server-side vars
+ * - `client:` is omitted when there are no client-side vars (NEXT_PUBLIC_ prefix)
+ * - `runtimeEnv:` always includes all vars
+ * - `annotatedType` takes precedence over `inferredType`
+ * - Optional vars have `.optional()` appended
+ * - Vars with a description have `.describe("text")` appended (before `.optional()`)
+ */
+declare function generateT3Env(parsed: ParsedEnvFile): string;
+
+/** Generator identifiers supported by env-typegen. */
+type GeneratorName = "typescript" | "zod" | "t3" | "declaration";
+/** Configuration shape accepted by env-typegen's CLI and programmatic API. */
+type EnvTypegenConfig = {
+    /** Path to the .env.example file to parse. */
+    input: string;
+    /** Output directory for generated files. Defaults to the input file's directory. */
+    output?: string;
+    /** Which generators to run. When omitted, all four generators run. */
+    generators?: GeneratorName[];
+    /** Format generated output with prettier. Defaults to true. */
+    format?: boolean;
+};
+/**
+ * Type-safe config helper.
+ * Returns the config object unchanged — exists purely for IDE autocompletion
+ * and compile-time validation of the config shape.
+ */
+declare function defineConfig(config: EnvTypegenConfig): EnvTypegenConfig;
+/**
+ * Loads env-typegen config by searching for a config file in `cwd`.
+ * Searches for env-typegen.config.ts → .mjs → .js in order.
+ * Returns `undefined` when no config file is found.
+ */
+declare function loadConfig(cwd?: string): Promise<EnvTypegenConfig | undefined>;
+
+/** Options accepted by the runGenerate pipeline. */
+type RunGenerateOptions = {
+    input: string;
+    output: string;
+    generators: GeneratorName[];
+    format: boolean;
+    stdout?: boolean;
+    dryRun?: boolean;
+    silent?: boolean;
+};
+/**
+ * Reads the input file, runs the requested generators, optionally formats each
+ * output, and writes the results to disk.
+ *
+ * Exported for unit testing — call this directly rather than spawning a child process.
+ */
+declare function runGenerate(options: RunGenerateOptions): Promise<void>;
+
+export { type CommentAnnotations, type EnvTypegenConfig, type EnvVarType, type GeneratorName, type InferenceRule, type ParsedEnvFile, type ParsedEnvVar, type RunGenerateOptions, defineConfig, generateDeclaration, generateEnvValidation, generateT3Env, generateTypeScriptTypes as generateTypeScript, generateTypeScriptTypes, generateZodSchema as generateZod, generateZodSchema, inferType, inferTypesFromParsedVars as inferTypes, inferenceRules, loadConfig, parseCommentBlock, parseEnvFile, parseEnvFileContent, runGenerate };