sane-env 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ole Lammers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# sane-env
+
+Mode-aware environment loading with schema validation.
+
+## Install
+
+```bash
+bun add sane-env
+```
+
+## Usage
+
+#### Inject layered env files into `process.env` - requires `NODE_ENV` to be set:
+
+```ts
+import 'sane-env/config';
+```
+
+Loads these files:
+
+1. `.env`
+2. `.env.local`
+3. `.env.${NODE_ENV}`
+4. `.env.${NODE_ENV}.local`
+
+#### Validate a loaded environment against a schema:
+
+```ts
+import { z } from 'zod'; // Standard Schema compatible, bring your own
+import { createEnvironment } from 'sane-env';
+
+const env = createEnvironment({
+    source: process.env,
+    schema: {
+        NODE_ENV: z.enum(['development', 'test', 'production']),
+        PORT: z.coerce.number().int().positive(),
+    },
+});
+```
+
+#### Custom environment loading logic:
+
+```ts
+import { loadEnvironment } from 'sane-env/load';
+import { createEnvironment } from 'sane-env';
+
+const envRecord = loadEnvironment({
+    // Custom loading configuration (see below)
+});
+
+const env = createEnvironment({
+    source: envRecord,
+    schema: { ... },
+});
+```
+
+## Loading Configuration
+
+| Property                | Description                                                | Required | Default                                          |
+| ----------------------- | ---------------------------------------------------------- | -------- | ------------------------------------------------ |
+| files                   | The file names to load in lowest to highest priority order | ✅       |                                                  |
+| root                    | The root directory at which to load files from             | ❌       | `process.cwd()`                                  |
+| emptyStringsAsUndefined | Whether blank entries are skipped in parsing               | ❌       | `true`                                           |
+| debug                   | Whether to announce which files are being loaded/parsed    | ❌       | `false` (`true` with `/config` in `development`) |

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/index.js

@@ -0,0 +1,56 @@
+// src/load.ts
+import path from "path";
+import fs from "fs";
+var LINE = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?$/gm;
+function parse(content, emptyStringsAsUndefined) {
+  const normalizedContent = content.replace(/\r\n?/g, `
+`);
+  const result = {};
+  for (const match of normalizedContent.matchAll(LINE)) {
+    const key = match[1];
+    let value = (match[2] || "").trim();
+    if (key === undefined)
+      continue;
+    if (value === "" && emptyStringsAsUndefined)
+      continue;
+    const isDoubleQuoted = value[0] === '"';
+    value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+    if (isDoubleQuoted) {
+      value = value.replace(/\\n/g, `
+`);
+      value = value.replace(/\\r/g, "\r");
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadEnvironment(options) {
+  const { root = process.cwd(), files, emptyStringsAsUndefined = true, debug = false } = options;
+  let combinedResult = {};
+  for (const filename of files) {
+    const dotenvPath = path.resolve(root, filename);
+    if (!fs.existsSync(dotenvPath)) {
+      if (debug)
+        console.warn(`Skipping "${filename}", file missing`);
+      continue;
+    }
+    const content = fs.readFileSync(dotenvPath, { encoding: "utf-8" });
+    const result = parse(content, emptyStringsAsUndefined);
+    combinedResult = { ...combinedResult, ...result };
+    if (debug)
+      console.log(`Loaded "${filename}" (${Object.keys(result).length})`);
+  }
+  return combinedResult;
+}
+
+// src/config/index.ts
+var mode = Reflect.get(process.env, "NODE_ENV");
+if (mode === undefined)
+  throw new Error("`NODE_ENV` must be set when injecting environment variables");
+var environment = loadEnvironment({
+  files: [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`],
+  debug: mode === "development"
+});
+for (const [key, value] of Object.entries(environment)) {
+  process.env[key] = value;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+type Environment = Record<string, string | undefined>;
+type SchemaValue = StandardSchemaV1<unknown, any>;
+type Schema = Record<string, SchemaValue>;
+type InferSchema<T extends Schema> = {
+    [K in keyof T]: StandardSchemaV1.InferOutput<T[K]>;
+};
+export interface EnvCreateOptions<T extends Schema> {
+    /**
+     * The raw environment values to compare against the schema.
+     */
+    source: Environment;
+    /**
+     * The schema defining which variables to pull and
+     * validate from the environment source.
+     */
+    schema: T;
+}
+/**
+ * Ensures an environment record matches a schema and returns the
+ * validated result.
+ */
+export declare function createEnvironment<T extends Schema>(opts: EnvCreateOptions<T>): InferSchema<T>;
+export {};

package/dist/index.js

@@ -0,0 +1,37 @@
+// src/index.ts
+function throwValidationError(envKey, parsedValue, issues) {
+  const messages = issues.length === 0 ? "undefined" : issues.length === 1 ? issues[0]?.message : issues.map((v) => `- ${v.message}`).join(`
+`);
+  throw new Error(`Invalid environment variable:
+Key: ${envKey}
+Parsed Value: ${parsedValue}
+Message(s): ${messages}`);
+}
+function resolveSchema(standard) {
+  return standard["~standard"];
+}
+function validateEnvironmentValue(schema, environment, key) {
+  const standard = resolveSchema(schema[key]);
+  const envKey = String(key);
+  const envValue = environment[envKey];
+  const result = standard.validate(envValue);
+  if (result instanceof Promise) {
+    throw new Error(`Validation of key "${envKey}" is not synchronous`);
+  }
+  if (result.issues) {
+    throwValidationError(envKey, envValue, result.issues);
+  }
+  return result.value;
+}
+function createEnvironment(opts) {
+  const { schema, source } = opts;
+  const result = {};
+  for (const key in opts.schema) {
+    const value = validateEnvironmentValue(schema, source, key);
+    result[key] = value;
+  }
+  return result;
+}
+export {
+  createEnvironment
+};

package/dist/load.d.ts

@@ -0,0 +1,27 @@
+export interface EnvLoadOptions {
+    /**
+     * The files (relative to `root`) to load and parse.
+     * In Lowest -> Highest priority order.
+     */
+    files: string[];
+    /**
+     * The root path to load files from.
+     * Default `process.cwd()`
+     */
+    root?: string;
+    /**
+     * Whether empty (`''`) or blank (`'   '`) entries are parsed as `undefined`.
+     * Default `true`
+     */
+    emptyStringsAsUndefined?: boolean;
+    /**
+     * Whether to display logging messages during parsing.
+     * Default `false`
+     */
+    debug?: boolean;
+}
+/**
+ * Reads and parses environment files into a combined
+ * environment record.
+ */
+export declare function loadEnvironment(options: EnvLoadOptions): Record<string, string>;

package/dist/load.js

@@ -0,0 +1,47 @@
+// src/load.ts
+import path from "path";
+import fs from "fs";
+var LINE = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?$/gm;
+function parse(content, emptyStringsAsUndefined) {
+  const normalizedContent = content.replace(/\r\n?/g, `
+`);
+  const result = {};
+  for (const match of normalizedContent.matchAll(LINE)) {
+    const key = match[1];
+    let value = (match[2] || "").trim();
+    if (key === undefined)
+      continue;
+    if (value === "" && emptyStringsAsUndefined)
+      continue;
+    const isDoubleQuoted = value[0] === '"';
+    value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+    if (isDoubleQuoted) {
+      value = value.replace(/\\n/g, `
+`);
+      value = value.replace(/\\r/g, "\r");
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadEnvironment(options) {
+  const { root = process.cwd(), files, emptyStringsAsUndefined = true, debug = false } = options;
+  let combinedResult = {};
+  for (const filename of files) {
+    const dotenvPath = path.resolve(root, filename);
+    if (!fs.existsSync(dotenvPath)) {
+      if (debug)
+        console.warn(`Skipping "${filename}", file missing`);
+      continue;
+    }
+    const content = fs.readFileSync(dotenvPath, { encoding: "utf-8" });
+    const result = parse(content, emptyStringsAsUndefined);
+    combinedResult = { ...combinedResult, ...result };
+    if (debug)
+      console.log(`Loaded "${filename}" (${Object.keys(result).length})`);
+  }
+  return combinedResult;
+}
+export {
+  loadEnvironment
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "sane-env",
+    "version": "0.1.1",
+    "description": "Mode dependent environment loader with schema validation.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./load": {
+            "types": "./dist/load.d.ts",
+            "import": "./dist/load.js",
+            "default": "./dist/load.js"
+        },
+        "./config": {
+            "types": "./dist/config/index.d.ts",
+            "import": "./dist/config/index.js",
+            "default": "./dist/config/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "sideEffects": [
+        "./dist/config/index.js"
+    ],
+    "scripts": {
+        "build": "rm -rf dist && bun build src/index.ts src/load.ts src/config/index.ts --outdir dist --target node --format esm && bunx tsc -p tsconfig.json --noEmit false --emitDeclarationOnly",
+        "prepublishOnly": "bun run build"
+    },
+    "author": {
+        "name": "Zyrakia",
+        "email": "mail@zyrakia.dev",
+        "url": "https://github.com/zyrakia"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "@types/bun": "latest",
+        "zod": "^4.3.6"
+    },
+    "dependencies": {
+        "@standard-schema/spec": "^1.1.0"
+    }
+}