@o3co/ts.hocon 1.9.0 → 1.11.0

package/dist/adapters/env.d.cts

@@ -0,0 +1,56 @@
+import { C as Config } from '../config-Dlq6rF3w.cjs';
+
+type EnvOptions = {
+    /**
+     * Selects which variables to mount, and is stripped from the resulting path.
+     * Required by {@link loadEnv}: mounting the whole environment would pull in
+     * PATH, HOME and whatever secrets happen to be set (spec F1.1).
+     * {@link parseDotEnv} allows it to be empty, a `.env` file being a closed set
+     * the caller chose deliberately.
+     */
+    prefix?: string;
+    /** Source name for error messages. */
+    originDescription?: string;
+};
+/**
+ * Mount a prefixed slice of the environment as config.
+ *
+ * ```ts
+ * const base = loadEnv({ prefix: 'APP_' })   // APP_DB__HOST -> db.host
+ * ```
+ *
+ * Reading a single variable needs nothing from here — HOCON's own `${?VAR}`
+ * already does that. This is for mounting a whole namespace as a subtree.
+ *
+ * `__` is the only path separator: a single `_` stays part of its segment
+ * (`APP_DB__MAX_CONN` → `db.max_conn`), and a literal `.` in a variable name is
+ * key text rather than a boundary, so `APP_FOO.BAR` becomes the single
+ * top-level key `foo.bar` — addressable as the quoted path `"foo.bar"` — and
+ * coexists with `APP_FOO__BAR` instead of colliding with it (F1.2).
+ *
+ * Two names that do map to one path are an error, the environment having no
+ * order to break the tie with (F1.6). Keys named `__proto__`, `constructor` or
+ * `prototype` are kept like any other (F2.9).
+ *
+ * Values are always strings, and a `${...}` inside one stays literal (F0.2, F1.4).
+ */
+declare function loadEnv(opts?: EnvOptions & {
+    env?: Record<string, string | undefined>;
+}): Config;
+/**
+ * Read `.env` file content.
+ *
+ * The dialect is deliberately small (spec F1.7): `NAME=value`, an optional
+ * `export ` prefix, whole-line `#` comments, single quotes taken literally,
+ * double quotes with `\n \r \t \\ \"`. Multi-line values and trailing comments
+ * are not supported — an unquoted value containing ` #` is an error rather than
+ * a guess about whether a comment was meant. No `${...}` expansion.
+ *
+ * Names map to paths exactly as in {@link loadEnv}: `__` is the only separator,
+ * so a literal `.` stays key text (`FOO.BAR` → the single key `foo.bar`). A
+ * file has a definite line order, so a repeated name is last-wins (F0.7)
+ * rather than the collision error the process environment gets.
+ */
+declare function parseDotEnv(input: string, opts?: EnvOptions): Config;
+
+export { type EnvOptions, loadEnv, parseDotEnv };

package/dist/adapters/env.d.ts

@@ -0,0 +1,56 @@
+import { C as Config } from '../config-Dlq6rF3w.js';
+
+type EnvOptions = {
+    /**
+     * Selects which variables to mount, and is stripped from the resulting path.
+     * Required by {@link loadEnv}: mounting the whole environment would pull in
+     * PATH, HOME and whatever secrets happen to be set (spec F1.1).
+     * {@link parseDotEnv} allows it to be empty, a `.env` file being a closed set
+     * the caller chose deliberately.
+     */
+    prefix?: string;
+    /** Source name for error messages. */
+    originDescription?: string;
+};
+/**
+ * Mount a prefixed slice of the environment as config.
+ *
+ * ```ts
+ * const base = loadEnv({ prefix: 'APP_' })   // APP_DB__HOST -> db.host
+ * ```
+ *
+ * Reading a single variable needs nothing from here — HOCON's own `${?VAR}`
+ * already does that. This is for mounting a whole namespace as a subtree.
+ *
+ * `__` is the only path separator: a single `_` stays part of its segment
+ * (`APP_DB__MAX_CONN` → `db.max_conn`), and a literal `.` in a variable name is
+ * key text rather than a boundary, so `APP_FOO.BAR` becomes the single
+ * top-level key `foo.bar` — addressable as the quoted path `"foo.bar"` — and
+ * coexists with `APP_FOO__BAR` instead of colliding with it (F1.2).
+ *
+ * Two names that do map to one path are an error, the environment having no
+ * order to break the tie with (F1.6). Keys named `__proto__`, `constructor` or
+ * `prototype` are kept like any other (F2.9).
+ *
+ * Values are always strings, and a `${...}` inside one stays literal (F0.2, F1.4).
+ */
+declare function loadEnv(opts?: EnvOptions & {
+    env?: Record<string, string | undefined>;
+}): Config;
+/**
+ * Read `.env` file content.
+ *
+ * The dialect is deliberately small (spec F1.7): `NAME=value`, an optional
+ * `export ` prefix, whole-line `#` comments, single quotes taken literally,
+ * double quotes with `\n \r \t \\ \"`. Multi-line values and trailing comments
+ * are not supported — an unquoted value containing ` #` is an error rather than
+ * a guess about whether a comment was meant. No `${...}` expansion.
+ *
+ * Names map to paths exactly as in {@link loadEnv}: `__` is the only separator,
+ * so a literal `.` stays key text (`FOO.BAR` → the single key `foo.bar`). A
+ * file has a definite line order, so a repeated name is last-wins (F0.7)
+ * rather than the collision error the process environment gets.
+ */
+declare function parseDotEnv(input: string, opts?: EnvOptions): Config;
+
+export { type EnvOptions, loadEnv, parseDotEnv };