@guanghechen/env 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
+
+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,158 @@
+<header>
+  <h1 align="center">
+    <a href="https://github.com/guanghechen/sora/tree/@guanghechen/env@1.0.0/packages/env#readme">@guanghechen/env</a>
+  </h1>
+  <div align="center">
+    <a href="https://www.npmjs.com/package/@guanghechen/env">
+      <img
+        alt="Npm Version"
+        src="https://img.shields.io/npm/v/@guanghechen/env.svg"
+      />
+    </a>
+    <a href="https://www.npmjs.com/package/@guanghechen/env">
+      <img
+        alt="Npm Download"
+        src="https://img.shields.io/npm/dm/@guanghechen/env.svg"
+      />
+    </a>
+    <a href="https://www.npmjs.com/package/@guanghechen/env">
+      <img
+        alt="Npm License"
+        src="https://img.shields.io/npm/l/@guanghechen/env.svg"
+      />
+    </a>
+    <a href="#install">
+      <img
+        alt="Module Formats: cjs"
+        src="https://img.shields.io/badge/module_formats-cjs-green.svg"
+      />
+    </a>
+    <a href="https://github.com/nodejs/node">
+      <img
+        alt="Node.js Version"
+        src="https://img.shields.io/node/v/@guanghechen/env"
+      />
+    </a>
+    <a href="https://github.com/facebook/jest">
+      <img
+        alt="Tested with Jest"
+        src="https://img.shields.io/badge/tested_with-jest-9c465e.svg"
+      />
+    </a>
+    <a href="https://github.com/prettier/prettier">
+      <img
+        alt="Code Style: prettier"
+        src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square"
+      />
+    </a>
+  </div>
+</header>
+<br/>
+
+A minimal .env parser with typed value support and variable interpolation. Supports comments,
+`export` prefix, quoted values (single/double), escape sequences, and `${VAR}` interpolation.
+
+## Install
+
+- npm
+
+  ```bash
+  npm install --save @guanghechen/env
+  ```
+
+- yarn
+
+  ```bash
+  yarn add @guanghechen/env
+  ```
+
+## Usage
+
+### Parsing .env Content
+
+```typescript
+import { parse } from '@guanghechen/env'
+
+const content = `
+# Database configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+
+# With export prefix
+export API_KEY=secret123
+
+# Quoted values
+MESSAGE="Hello, World!"
+SINGLE_QUOTED='No interpolation here'
+
+# Variable interpolation (double quotes or unquoted)
+DB_URL="postgres://\${DB_HOST}:\${DB_PORT}/\${DB_NAME}"
+
+# Escape sequences in double quotes
+MULTILINE="Line1\\nLine2\\nLine3"
+`
+
+const env = parse(content)
+console.log(env.DB_HOST)   // 'localhost'
+console.log(env.DB_PORT)   // '5432'
+console.log(env.DB_URL)    // 'postgres://localhost:5432/myapp'
+console.log(env.MULTILINE) // 'Line1\nLine2\nLine3'
+```
+
+### Stringifying to .env Format
+
+```typescript
+import { stringify } from '@guanghechen/env'
+
+const env = {
+  DB_HOST: 'localhost',
+  DB_PORT: '5432',
+  MESSAGE: 'Hello World',
+  SECRET: 'my-secret-key',
+}
+
+// Basic stringify
+const content = stringify(env)
+// DB_HOST=localhost
+// DB_PORT=5432
+// MESSAGE="Hello World"
+// SECRET=my-secret-key
+
+// With exclusion
+const filtered = stringify(env, { exclude: ['SECRET'] })
+// DB_HOST=localhost
+// DB_PORT=5432
+// MESSAGE="Hello World"
+```
+
+### Supported Syntax
+
+```bash
+# Comments start with #
+KEY=value
+
+# Optional export prefix
+export KEY=value
+
+# Double-quoted values (with escape sequences and interpolation)
+KEY="value with spaces"
+KEY="Line1\nLine2"
+KEY="Uses ${OTHER_VAR}"
+
+# Single-quoted values (literal, no processing)
+KEY='${NOT_INTERPOLATED}'
+
+# Inline comments (unquoted values only)
+KEY=value # this is a comment
+
+# Empty values
+KEY=
+```
+
+## Reference
+
+- [homepage][homepage]
+
+[homepage]:
+  https://github.com/guanghechen/sora/tree/@guanghechen/env@1.0.0/packages/env#readme

package/lib/cjs/index.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parse(content) {
+    const env = {};
+    if (!content)
+        return env;
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+        const line = lines[lineNum];
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice(7).trim() : trimmed;
+        const sepIndex = withoutExport.indexOf('=');
+        if (sepIndex === -1)
+            continue;
+        const key = withoutExport.slice(0, sepIndex);
+        if (!key || !KEY_PATTERN.test(key))
+            continue;
+        let value = withoutExport.slice(sepIndex + 1);
+        if (!value) {
+            env[key] = '';
+            continue;
+        }
+        const quoteChar = value[0];
+        const isDoubleQuote = quoteChar === '"';
+        const isSingleQuote = quoteChar === "'";
+        if (isDoubleQuote || isSingleQuote) {
+            const closeIndex = findClosingQuote(value, quoteChar);
+            if (closeIndex === -1) {
+                throw new SyntaxError(`Unclosed quote at line ${lineNum + 1}: ${line}`);
+            }
+            value = value.slice(1, closeIndex);
+            if (isDoubleQuote) {
+                value = processEscapeSequences(value);
+                value = interpolate(value, env);
+            }
+        }
+        else {
+            const commentIndex = value.search(/\s+#/);
+            if (commentIndex !== -1) {
+                value = value.slice(0, commentIndex);
+            }
+            value = interpolate(value, env);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function findClosingQuote(value, quoteChar) {
+    for (let i = 1; i < value.length; i += 1) {
+        if (value[i] === '\\' && value[i + 1] === quoteChar) {
+            i += 1;
+            continue;
+        }
+        if (value[i] === quoteChar) {
+            return i;
+        }
+    }
+    return -1;
+}
+const BACKSLASH_PLACEHOLDER = '\uE000';
+function processEscapeSequences(value) {
+    return value
+        .replace(/\\\\/g, BACKSLASH_PLACEHOLDER)
+        .replace(/\\n/g, '\n')
+        .replace(/\\r/g, '\r')
+        .replace(/\\t/g, '\t')
+        .replace(/\\"/g, '"')
+        .replace(new RegExp(BACKSLASH_PLACEHOLDER, 'g'), '\\');
+}
+function interpolate(value, env) {
+    return value.replace(/\\?\$\{([^}]+)\}/g, (match, varName) => {
+        if (match.startsWith('\\')) {
+            return match.slice(1);
+        }
+        return env[varName] ?? '';
+    });
+}
+function stringifyValue(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    const needsQuote = escaped !== value || value.includes(' ') || value.includes("'") || value.includes('#');
+    return needsQuote ? `"${escaped}"` : escaped;
+}
+function stringify(env, options) {
+    const excludeSet = new Set(options?.exclude ?? []);
+    const lines = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (excludeSet.has(key))
+            continue;
+        lines.push(`${key}=${stringifyValue(value)}`);
+    }
+    return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+
+exports.parse = parse;
+exports.stringify = stringify;

package/lib/esm/index.mjs

@@ -0,0 +1,100 @@
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parse(content) {
+    const env = {};
+    if (!content)
+        return env;
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+        const line = lines[lineNum];
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const withoutExport = trimmed.startsWith('export ') ? trimmed.slice(7).trim() : trimmed;
+        const sepIndex = withoutExport.indexOf('=');
+        if (sepIndex === -1)
+            continue;
+        const key = withoutExport.slice(0, sepIndex);
+        if (!key || !KEY_PATTERN.test(key))
+            continue;
+        let value = withoutExport.slice(sepIndex + 1);
+        if (!value) {
+            env[key] = '';
+            continue;
+        }
+        const quoteChar = value[0];
+        const isDoubleQuote = quoteChar === '"';
+        const isSingleQuote = quoteChar === "'";
+        if (isDoubleQuote || isSingleQuote) {
+            const closeIndex = findClosingQuote(value, quoteChar);
+            if (closeIndex === -1) {
+                throw new SyntaxError(`Unclosed quote at line ${lineNum + 1}: ${line}`);
+            }
+            value = value.slice(1, closeIndex);
+            if (isDoubleQuote) {
+                value = processEscapeSequences(value);
+                value = interpolate(value, env);
+            }
+        }
+        else {
+            const commentIndex = value.search(/\s+#/);
+            if (commentIndex !== -1) {
+                value = value.slice(0, commentIndex);
+            }
+            value = interpolate(value, env);
+        }
+        env[key] = value;
+    }
+    return env;
+}
+function findClosingQuote(value, quoteChar) {
+    for (let i = 1; i < value.length; i += 1) {
+        if (value[i] === '\\' && value[i + 1] === quoteChar) {
+            i += 1;
+            continue;
+        }
+        if (value[i] === quoteChar) {
+            return i;
+        }
+    }
+    return -1;
+}
+const BACKSLASH_PLACEHOLDER = '\uE000';
+function processEscapeSequences(value) {
+    return value
+        .replace(/\\\\/g, BACKSLASH_PLACEHOLDER)
+        .replace(/\\n/g, '\n')
+        .replace(/\\r/g, '\r')
+        .replace(/\\t/g, '\t')
+        .replace(/\\"/g, '"')
+        .replace(new RegExp(BACKSLASH_PLACEHOLDER, 'g'), '\\');
+}
+function interpolate(value, env) {
+    return value.replace(/\\?\$\{([^}]+)\}/g, (match, varName) => {
+        if (match.startsWith('\\')) {
+            return match.slice(1);
+        }
+        return env[varName] ?? '';
+    });
+}
+function stringifyValue(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    const needsQuote = escaped !== value || value.includes(' ') || value.includes("'") || value.includes('#');
+    return needsQuote ? `"${escaped}"` : escaped;
+}
+function stringify(env, options) {
+    const excludeSet = new Set(options?.exclude ?? []);
+    const lines = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (excludeSet.has(key))
+            continue;
+        lines.push(`${key}=${stringifyValue(value)}`);
+    }
+    return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+
+export { parse, stringify };

package/lib/types/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A minimal .env parser with variable interpolation.
+ *
+ * @module @guanghechen/env
+ */
+/** Record of environment variables (always string values) */
+type IEnvRecord = Record<string, string>;
+/** Options for stringify */
+interface IStringifyEnvOptions {
+    /** Keys to exclude from output */
+    exclude?: string[];
+}
+/**
+ * Parse .env content string into an object.
+ * Supports comments, export prefix, quoted values, and variable interpolation.
+ * @param content - .env file content
+ * @returns Parsed environment record
+ * @throws {SyntaxError} If unclosed quote is detected
+ */
+declare function parse(content: string): IEnvRecord;
+/**
+ * Convert environment record to .env format string.
+ * Values containing spaces, quotes, newlines, or # are double-quoted.
+ * @param env - Environment record to stringify
+ * @param options - Stringify options
+ * @returns .env format string
+ */
+declare function stringify(env: IEnvRecord, options?: IStringifyEnvOptions): string;
+
+export { parse, stringify };
+export type { IEnvRecord, IStringifyEnvOptions };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@guanghechen/env",
+  "version": "2.0.1",
+  "description": "A minimal .env parser with typed value support and variable interpolation.",
+  "author": {
+    "name": "guanghechen",
+    "url": "https://github.com/guanghechen/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/env@2.0.0",
+    "directory": "packages/env"
+  },
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/env@2.0.0/packages/env#readme",
+  "keywords": [
+    "env",
+    "dotenv",
+    "parser",
+    "environment"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./lib/esm/index.mjs",
+      "require": "./lib/cjs/index.cjs"
+    }
+  },
+  "source": "./src/index.ts",
+  "main": "./lib/cjs/index.cjs",
+  "module": "./lib/esm/index.mjs",
+  "types": "./lib/types/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "lib/",
+    "!lib/**/*.map",
+    "package.json",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}