diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 18aebaf0f..d7536adbb 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -36,6 +36,7 @@ const ENTRY_POINTS = [ "../csv/mod.ts", "../data_structures/mod.ts", "../datetime/mod.ts", + "../dotenv/mod.ts", "../encoding/mod.ts", "../expect/mod.ts", "../fmt/bytes.ts", diff --git a/dotenv/mod.ts b/dotenv/mod.ts index 10a2b8740..4e0f5b8ab 100644 --- a/dotenv/mod.ts +++ b/dotenv/mod.ts @@ -4,6 +4,19 @@ * Parses and loads environment variables from a `.env` file into the current * process, or stringify data into a `.env` file format. * + * ```ts no-eval + * // Automatically load environment variables from a `.env` file + * import "@std/dotenv/load"; + * ``` + * + * ```ts + * import { parse, stringify } from "@std/dotenv"; + * import { assertEquals } from "@std/assert/assert-equals"; + * + * assertEquals(parse("GREETING=hello world"), { GREETING: "hello world" }); + * assertEquals(stringify({ GREETING: "hello world" }), "GREETING='hello world'"); + * ``` + * * @module */ @@ -62,16 +75,29 @@ export interface LoadOptions { defaultsPath?: string | null; } -/** Works identically to {@linkcode load}, but synchronously. */ +/** + * Works identically to {@linkcode load}, but synchronously. + * + * @example Usage + * ```ts no-eval + * import { loadSync } from "@std/dotenv"; + * + * const conf = loadSync(); + * ``` + * + * @param options Options for loading the environment variables. + * @returns The parsed environment variables. + */ export function loadSync( - { + options: LoadOptions = {}, +): Record { + const { envPath = ".env", examplePath = ".env.example", defaultsPath = ".env.defaults", export: _export = false, allowEmptyValues = false, - }: LoadOptions = {}, -): Record { + } = options; const conf = envPath ? parseFileSync(envPath) : {}; if (defaultsPath) { @@ -114,11 +140,12 @@ export function loadSync( * * Then import the environment variables using the `load` function. * - * ```ts + * @example Basic usage + * ```ts no-eval * // app.ts * import { load } from "@std/dotenv"; * - * console.log(await load({export: true})); // { GREETING: "hello world" } + * console.log(await load({ export: true })); // { GREETING: "hello world" } * console.log(Deno.env.get("GREETING")); // hello world * ``` * @@ -131,7 +158,8 @@ export function loadSync( * Import the `load.ts` module to auto-import from the `.env` file and into * the process environment. * - * ```ts + * @example Auto-loading + * ```ts no-eval * // app.ts * import "@std/dotenv/load"; * @@ -209,15 +237,17 @@ export function loadSync( * |allowEmptyValues|false|Allows empty values for specified env variables (throws otherwise) * * ### Example configuration - * ```ts + * + * @example Using with options + * ```ts no-eval * import { load } from "@std/dotenv"; * * const conf = await load({ - * envPath: "./.env_prod", - * examplePath: "./.env_required", - * export: true, - * allowEmptyValues: true, - * }); + * envPath: "./.env_prod", // Uses .env_prod instead of .env + * examplePath: "./.env_required", // Uses .env_required instead of .env.example + * export: true, // Exports all variables to the environment + * allowEmptyValues: true, // Allows empty values for specified env variables + * }); * ``` * * ## Permissions @@ -269,16 +299,20 @@ export function loadSync( * `{ KEY: "default" }`. Also there is possible to do this case * `KEY=${NO_SUCH_KEY:-${EXISTING_KEY:-default}}` which becomes * `{ KEY: "" }`) + * + * @param options The options + * @returns The parsed environment variables */ export async function load( - { + options: LoadOptions = {}, +): Promise> { + const { envPath = ".env", examplePath = ".env.example", defaultsPath = ".env.defaults", export: _export = false, allowEmptyValues = false, - }: LoadOptions = {}, -): Promise> { + } = options; const conf = envPath ? await parseFile(envPath) : {}; if (defaultsPath) { @@ -370,11 +404,57 @@ function assertSafe( /** * Error thrown in {@linkcode load} and {@linkcode loadSync} when required * environment variables are missing. + * + * @example Usage + * ```ts no-eval + * import { MissingEnvVarsError, load } from "@std/dotenv"; + * + * try { + * await load(); + * } catch (e) { + * if (e instanceof MissingEnvVarsError) { + * console.error(e.message); + * } + * } + * ``` */ export class MissingEnvVarsError extends Error { - /** The keys of the missing environment variables. */ + /** + * The keys of the missing environment variables. + * + * @example Usage + * ```ts no-eval + * import { MissingEnvVarsError, load } from "@std/dotenv"; + * + * try { + * await load(); + * } catch (e) { + * if (e instanceof MissingEnvVarsError) { + * console.error(e.missing); + * } + * } + * ``` + */ missing: string[]; - /** Constructs a new instance. */ + /** + * Constructs a new instance. + * + * @example Usage + * ```ts no-eval + * import { MissingEnvVarsError, load } from "@std/dotenv"; + * + * try { + * await load(); + * } catch (e) { + * if (e instanceof MissingEnvVarsError) { + * console.error(e.message); + * } + * } + * ``` + * + * @param message The error message + * @param missing The keys of the missing environment variables + */ constructor(message: string, missing: string[]) { super(message); this.name = "MissingEnvVarsError"; diff --git a/dotenv/parse.ts b/dotenv/parse.ts index 69a49feed..6574a0f8c 100644 --- a/dotenv/parse.ts +++ b/dotenv/parse.ts @@ -57,21 +57,25 @@ function expand(str: string, variablesMap: { [key: string]: string }): string { /** * Parse `.env` file output in an object. * - * @example + * @example Usage * ```ts * import { parse } from "@std/dotenv/parse"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const env = parse("GREETING=hello world"); - * env.GREETING; // "hello world" + * assertEquals(env, { GREETING: "hello world" }); * ``` + * + * @param text The text to parse. + * @returns The parsed object. */ -export function parse(rawDotenv: string): Record { +export function parse(text: string): Record { const env: Record = {}; let match; const keysForExpandCheck = []; - while ((match = RE_KEY_VALUE.exec(rawDotenv)) !== null) { + while ((match = RE_KEY_VALUE.exec(text)) !== null) { const { key, interpolated, notInterpolated, unquoted } = match ?.groups as LineParseResult; diff --git a/dotenv/stringify.ts b/dotenv/stringify.ts index 6e3e90cc3..eca9b2c60 100644 --- a/dotenv/stringify.ts +++ b/dotenv/stringify.ts @@ -4,12 +4,13 @@ /** * Stringify an object into a valid `.env` file format. * - * @example + * @example Usage * ```ts * import { stringify } from "@std/dotenv/stringify"; + * import { assertEquals } from "@std/assert/assert-equals"; * * const object = { GREETING: "hello world" }; - * const string = stringify(object); // GREETING='hello world' + * assertEquals(stringify(object), "GREETING='hello world'"); * ``` * * @param object object to be stringified