@ayepi/env 0.2.0

package/dist/load.cjs

@@ -0,0 +1,40 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_dotenv = require("./dotenv.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+//#region src/load.ts
+/**
+* # File loading — `@ayepi/env/load` (the only `node:fs` entry)
+*
+* Read `.env` and `.json` files off disk into a config **source** — a plain record you then feed
+* to an env with `set(...)`. Kept separate from the core so the main entry stays filesystem-free.
+*
+* ```ts
+* import { env } from '@ayepi/env'
+* import { loadEnv } from '@ayepi/env/load'
+*
+* const ENV = env(schema)
+* ENV.set(loadEnv({ files: ['.env', 'config.json'] }))   // files win over process.env
+* ENV.set({ ...loadEnv({ files: ['.env'] }), ...process.env })  // …or let process.env win
+* ```
+*
+* @module
+*/
+/** Read one `.env` or `.json` file into a config source. A `.json` file may carry already-typed values. */
+function readEnvFile(path) {
+	const text = (0, node_fs.readFileSync)(path, "utf8");
+	return (0, node_path.extname)(path) === ".json" ? JSON.parse(text) : require_dotenv.parseDotenv(text);
+}
+/** Read the listed files into a single merged source (later files win). Pass the result to `set(...)`. */
+function loadEnv(opts = {}) {
+	const out = {};
+	const req = opts.required;
+	const mustExist = (file) => req === true || Array.isArray(req) && req.includes(file);
+	for (const file of opts.files ?? []) if ((0, node_fs.existsSync)(file)) Object.assign(out, readEnvFile(file));
+	else if (mustExist(file)) throw new Error(`env file not found: ${file}`);
+	return out;
+}
+//#endregion
+exports.loadEnv = loadEnv;
+exports.parseDotenv = require_dotenv.parseDotenv;
+exports.readEnvFile = readEnvFile;

package/dist/load.d.cts

@@ -0,0 +1,21 @@
+import { r as EnvSource, t as parseDotenv } from "./dotenv.cjs";
+
+//#region src/load.d.ts
+/** Read one `.env` or `.json` file into a config source. A `.json` file may carry already-typed values. */
+declare function readEnvFile(path: string): EnvSource;
+/** Options for {@link loadEnv}. */
+interface LoadOptions {
+  /** Files to read (in order, earlier is lower precedence); `.env` or `.json`. */
+  readonly files?: readonly string[];
+  /**
+   * Which missing files should **throw** instead of being skipped:
+   * - `false` / omitted — ignore every missing file (default),
+   * - `true` — throw if **any** listed file is missing,
+   * - `string[]` — throw only if one of **these specific** files is missing (others are ignored).
+   */
+  readonly required?: boolean | readonly string[];
+}
+/** Read the listed files into a single merged source (later files win). Pass the result to `set(...)`. */
+declare function loadEnv(opts?: LoadOptions): EnvSource;
+//#endregion
+export { type EnvSource, LoadOptions, loadEnv, parseDotenv, readEnvFile };

package/dist/load.d.ts

@@ -0,0 +1,21 @@
+import { r as EnvSource, t as parseDotenv } from "./dotenv.js";
+
+//#region src/load.d.ts
+/** Read one `.env` or `.json` file into a config source. A `.json` file may carry already-typed values. */
+declare function readEnvFile(path: string): EnvSource;
+/** Options for {@link loadEnv}. */
+interface LoadOptions {
+  /** Files to read (in order, earlier is lower precedence); `.env` or `.json`. */
+  readonly files?: readonly string[];
+  /**
+   * Which missing files should **throw** instead of being skipped:
+   * - `false` / omitted — ignore every missing file (default),
+   * - `true` — throw if **any** listed file is missing,
+   * - `string[]` — throw only if one of **these specific** files is missing (others are ignored).
+   */
+  readonly required?: boolean | readonly string[];
+}
+/** Read the listed files into a single merged source (later files win). Pass the result to `set(...)`. */
+declare function loadEnv(opts?: LoadOptions): EnvSource;
+//#endregion
+export { type EnvSource, LoadOptions, loadEnv, parseDotenv, readEnvFile };

package/dist/load.js

@@ -0,0 +1,37 @@
+import { t as parseDotenv } from "./dotenv.js";
+import { existsSync, readFileSync } from "node:fs";
+import { extname } from "node:path";
+//#region src/load.ts
+/**
+* # File loading — `@ayepi/env/load` (the only `node:fs` entry)
+*
+* Read `.env` and `.json` files off disk into a config **source** — a plain record you then feed
+* to an env with `set(...)`. Kept separate from the core so the main entry stays filesystem-free.
+*
+* ```ts
+* import { env } from '@ayepi/env'
+* import { loadEnv } from '@ayepi/env/load'
+*
+* const ENV = env(schema)
+* ENV.set(loadEnv({ files: ['.env', 'config.json'] }))   // files win over process.env
+* ENV.set({ ...loadEnv({ files: ['.env'] }), ...process.env })  // …or let process.env win
+* ```
+*
+* @module
+*/
+/** Read one `.env` or `.json` file into a config source. A `.json` file may carry already-typed values. */
+function readEnvFile(path) {
+	const text = readFileSync(path, "utf8");
+	return extname(path) === ".json" ? JSON.parse(text) : parseDotenv(text);
+}
+/** Read the listed files into a single merged source (later files win). Pass the result to `set(...)`. */
+function loadEnv(opts = {}) {
+	const out = {};
+	const req = opts.required;
+	const mustExist = (file) => req === true || Array.isArray(req) && req.includes(file);
+	for (const file of opts.files ?? []) if (existsSync(file)) Object.assign(out, readEnvFile(file));
+	else if (mustExist(file)) throw new Error(`env file not found: ${file}`);
+	return out;
+}
+//#endregion
+export { loadEnv, parseDotenv, readEnvFile };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ayepi/env",
+  "version": "0.2.0",
+  "description": "Typed, lazy, reactive environment/config on zod — env({...}) reads process.env, records, .env/JSON files; coerces scalars and JSON-decodes complex types; computed fields, aliasing, and async/dynamic (live, subscribable) values",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/env"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/env#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "ayepi-*.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./load": {
+      "import": {
+        "types": "./dist/load.d.ts",
+        "default": "./dist/load.js"
+      },
+      "require": {
+        "types": "./dist/load.d.cts",
+        "default": "./dist/load.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3"
+  },
+  "keywords": [
+    "ayepi",
+    "env",
+    "environment",
+    "config",
+    "dotenv",
+    "zod",
+    "configuration",
+    "12-factor"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}