molex-env 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,75 @@
+molex-env
+
+Native .menv loader with profiles, typing, origin tracking, and optional reload.
+
+Highlights
+- Deterministic profile merging
+- Typed parsing (boolean, number, json, date)
+- Strict mode for unknown or duplicate keys
+- Origin tracking (file + line)
+- Immutable config objects
+- Optional file watching for reload
+
+Install
+- npm install molex-env
+
+Basic usage
+const { load } = require('molex-env');
+
+const result = load({
+  profile: 'prod',
+  export: true,
+  strict: true,
+  schema: {
+    PORT: 'number',
+    DEBUG: 'boolean',
+    SERVICE_URL: { type: 'string', required: true }
+  }
+});
+
+console.log(result.parsed.PORT);
+console.log(result.origins.SERVICE_URL);
+
+File precedence
+1) .menv
+2) .menv.local
+3) .menv.{profile}
+4) .menv.{profile}.local
+
+API
+load(options)
+- cwd: base directory (default: process.cwd())
+- profile: profile name for .menv.{profile}
+- files: custom file list (absolute or relative to cwd)
+- schema: allowed keys, types, defaults, required
+- strict: reject unknown keys, duplicates, and invalid lines
+- cast: true | false | { boolean, number, json, date }
+- export: write values to process.env
+- override: override existing process.env values
+- freeze: deep-freeze parsed config (default true)
+- onWarning: function(info) for non-strict duplicates
+
+parse(text, options)
+- Parse a string of .menv content using the same typing rules
+
+watch(options, onChange)
+- Watch resolved files and reload on change
+- onChange(err, result)
+
+Schema example
+const schema = {
+  PORT: { type: 'number', default: 3000 },
+  DEBUG: { type: 'boolean', default: false },
+  METADATA: { type: 'json' },
+  START_DATE: { type: 'date' }
+};
+
+Notes
+- Use .menv.local for machine-specific values
+- Use strict mode to detect surprises early
+
+Example project
+An example app is included in examples/basic.
+Run it with:
+- npm install (from examples/basic)
+- npm start

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "molex-env",
+  "version": "0.1.0",
+  "description": "Native .menv loader with profiles, typing, and origin tracking.",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "menv",
+    "config",
+    "profile",
+    "native"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonywied17/molex-env.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonywied17/molex-env/issues"
+  },
+  "homepage": "https://github.com/tonywied17/molex-env#readme"
+}

package/src/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { load, parse } = require('./lib/core');
+const { watch } = require('./lib/watch');
+
+module.exports = {
+    load,
+    parse,
+    /**
+     * Watch resolved .menv files and reload on change.
+     * @param {object} options
+     * @param {(err: Error|null, result?: {parsed: object, origins: object, files: string[]}) => void} onChange
+     * @returns {{close: () => void}}
+     */
+    watch(options, onChange)
+    {
+        return watch(options, onChange, load);
+    }
+};

package/src/lib/apply.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { unknownKeyError, duplicateKeyError } = require('./errors');
+const { coerceType, autoCast } = require('./cast');
+
+/**
+ * Apply a parsed entry to the state with schema/type checks.
+ * @param {{values: object, origins: object, seen: Set<string>}} state
+ * @param {{key: string, raw: string, line: number}} entry
+ * @param {{schema: object|null, strict: boolean, cast: object, onWarning?: Function}} options
+ * @param {string} filePath
+ * @returns {void}
+ */
+function applyEntry(state, entry, options, filePath)
+{
+    const { schema, strict, cast, onWarning } = options;
+    const { key, raw, line } = entry;
+
+    if (schema && strict && !schema[key])
+    {
+        throw unknownKeyError(key, filePath, line);
+    }
+
+    if (state.seen.has(key))
+    {
+        if (strict)
+        {
+            throw duplicateKeyError(key, filePath, line);
+        }
+        if (typeof onWarning === 'function')
+        {
+            onWarning({
+                type: 'duplicate',
+                key,
+                file: filePath,
+                line
+            });
+        }
+    }
+
+    const def = schema ? schema[key] : null;
+    let value;
+    if (def && def.type)
+    {
+        value = coerceType(raw, def.type, filePath, line);
+    } else
+    {
+        value = autoCast(raw, cast);
+    }
+
+    state.values[key] = value;
+    state.origins[key] = { file: filePath, line, raw };
+    state.seen.add(key);
+}
+
+module.exports = {
+    applyEntry
+};

package/src/lib/cast.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { invalidTypeError } = require('./errors');
+
+/**
+ * Normalize cast options into explicit booleans.
+ * @param {boolean|{boolean?: boolean, number?: boolean, json?: boolean, date?: boolean}} cast
+ * @returns {{boolean: boolean, number: boolean, json: boolean, date: boolean}}
+ */
+function normalizeCast(cast)
+{
+    if (cast === true || cast === undefined)
+    {
+        return { boolean: true, number: true, json: true, date: true };
+    }
+    if (cast === false)
+    {
+        return { boolean: false, number: false, json: false, date: false };
+    }
+    return {
+        boolean: cast.boolean !== false,
+        number: cast.number !== false,
+        json: cast.json !== false,
+        date: cast.date !== false
+    };
+}
+
+/**
+ * Check if a string is a number.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isNumber(value)
+{
+    return /^-?\d+(\.\d+)?$/.test(value);
+}
+
+/**
+ * Check if a string looks like an ISO date.
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isIsoDate(value)
+{
+    return /^\d{4}-\d{2}-\d{2}(?:[T\s].*)?$/.test(value);
+}
+
+/**
+ * Coerce a raw string to the requested type.
+ * @param {string} raw
+ * @param {string} type
+ * @param {string} file
+ * @param {number} line
+ * @returns {any}
+ */
+function coerceType(raw, type, file, line)
+{
+    if (type === 'string') return raw;
+    if (type === 'boolean')
+    {
+        if (raw.toLowerCase() === 'true') return true;
+        if (raw.toLowerCase() === 'false') return false;
+        throw invalidTypeError('boolean', raw, file, line);
+    }
+    if (type === 'number')
+    {
+        if (!isNumber(raw)) throw invalidTypeError('number', raw, file, line);
+        return Number(raw);
+    }
+    if (type === 'json')
+    {
+        return JSON.parse(raw);
+    }
+    if (type === 'date')
+    {
+        const date = new Date(raw);
+        if (Number.isNaN(date.getTime())) throw invalidTypeError('date', raw, file, line);
+        return date;
+    }
+    return raw;
+}
+
+/**
+ * Auto-cast a raw string based on enabled rules.
+ * @param {string} raw
+ * @param {{boolean: boolean, number: boolean, json: boolean, date: boolean}} cast
+ * @returns {any}
+ */
+function autoCast(raw, cast)
+{
+    const trimmed = raw.trim();
+    if (cast.boolean)
+    {
+        const lower = trimmed.toLowerCase();
+        if (lower === 'true') return true;
+        if (lower === 'false') return false;
+    }
+    if (cast.number && isNumber(trimmed))
+    {
+        return Number(trimmed);
+    }
+    if (cast.json && (trimmed.startsWith('{') || trimmed.startsWith('[')))
+    {
+        try
+        {
+            return JSON.parse(trimmed);
+        } catch (err)
+        {
+            return trimmed;
+        }
+    }
+    if (cast.date && isIsoDate(trimmed))
+    {
+        const date = new Date(trimmed);
+        if (!Number.isNaN(date.getTime())) return date;
+    }
+    return trimmed;
+}
+
+module.exports = {
+    normalizeCast,
+    coerceType,
+    autoCast
+};

package/src/lib/core.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const fs = require('fs');
+
+const { normalizeCast } = require('./cast');
+const { normalizeSchema, applySchemaDefaults } = require('./schema');
+const { parseEntries } = require('./parser');
+const { applyEntry } = require('./apply');
+const { resolveFiles } = require('./files');
+const { deepFreeze } = require('./utils');
+
+/**
+ * Build a new parsing state container.
+ * @returns {{values: object, origins: object, seen: Set<string>}}
+ */
+function buildState()
+{
+    return {
+        values: {},
+        origins: {},
+        seen: new Set()
+    };
+}
+
+/**
+ * Export parsed values to process.env if enabled.
+ * @param {object} values
+ * @param {object} options
+ * @returns {void}
+ */
+function exportToEnv(values, options)
+{
+    if (!options.export) return;
+    for (const [key, value] of Object.entries(values))
+    {
+        if (!options.override && Object.prototype.hasOwnProperty.call(process.env, key))
+        {
+            continue;
+        }
+        process.env[key] = value === undefined ? '' : String(value);
+    }
+}
+
+/**
+ * Load .menv files and return parsed values with origins.
+ * @param {object} options
+ * @returns {{parsed: object, origins: object, files: string[]}}
+ */
+function load(options = {})
+{
+    const normalizedSchema = normalizeSchema(options.schema);
+    const cast = normalizeCast(options.cast);
+    const strict = Boolean(options.strict);
+
+    const state = buildState();
+    const files = resolveFiles(options);
+    const readFiles = [];
+
+    for (const filePath of files)
+    {
+        if (!fs.existsSync(filePath)) continue;
+        const text = fs.readFileSync(filePath, 'utf8');
+        const entries = parseEntries(text, { strict, filePath });
+        for (const entry of entries)
+        {
+            applyEntry(state, entry, {
+                schema: normalizedSchema,
+                strict,
+                cast,
+                onWarning: options.onWarning
+            }, filePath);
+        }
+        readFiles.push(filePath);
+    }
+
+    applySchemaDefaults(state.values, state.origins, normalizedSchema, strict);
+    exportToEnv(state.values, options);
+
+    if (options.freeze !== false)
+    {
+        deepFreeze(state.values);
+    }
+
+    return {
+        parsed: state.values,
+        origins: state.origins,
+        files: readFiles
+    };
+}
+
+/**
+ * Parse a string containing .menv content.
+ * @param {string} text
+ * @param {object} options
+ * @returns {{parsed: object, origins: object, files: string[]}}
+ */
+function parse(text, options = {})
+{
+    const normalizedSchema = normalizeSchema(options.schema);
+    const cast = normalizeCast(options.cast);
+    const strict = Boolean(options.strict);
+    const state = buildState();
+    const filePath = options.filePath || '<inline>';
+
+    const entries = parseEntries(text, { strict, filePath });
+    for (const entry of entries)
+    {
+        applyEntry(state, entry, {
+            schema: normalizedSchema,
+            strict,
+            cast,
+            onWarning: options.onWarning
+        }, filePath);
+    }
+
+    applySchemaDefaults(state.values, state.origins, normalizedSchema, strict);
+
+    if (options.freeze !== false)
+    {
+        deepFreeze(state.values);
+    }
+
+    return {
+        parsed: state.values,
+        origins: state.origins,
+        files: options.filePath ? [options.filePath] : []
+    };
+}
+
+module.exports = {
+    load,
+    parse
+};

package/src/lib/errors.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Base error type for molex-env.
+ */
+class MenvError extends Error
+{
+    constructor(message, details)
+    {
+        super(message);
+        this.name = 'MenvError';
+        if (details)
+        {
+            this.details = details;
+        }
+    }
+}
+
+/**
+ * Format a file/line suffix for error messages.
+ * @param {string} file
+ * @param {number} line
+ * @returns {string}
+ */
+function formatLocation(file, line)
+{
+    if (!file) return '';
+    if (!line) return ` (${file})`;
+    return ` (${file}:${line})`;
+}
+
+/**
+ * Create an invalid line error.
+ * @param {number} line
+ * @param {string} rawLine
+ * @param {string} file
+ * @returns {MenvError}
+ */
+function invalidLineError(line, rawLine, file)
+{
+    return new MenvError(`Invalid line ${line}: ${rawLine}${formatLocation(file)}`);
+}
+
+/**
+ * Create an unknown key error.
+ * @param {string} key
+ * @param {string} file
+ * @param {number} line
+ * @returns {MenvError}
+ */
+function unknownKeyError(key, file, line)
+{
+    return new MenvError(`Unknown key: ${key}${formatLocation(file, line)}`);
+}
+
+/**
+ * Create a duplicate key error.
+ * @param {string} key
+ * @param {string} file
+ * @param {number} line
+ * @returns {MenvError}
+ */
+function duplicateKeyError(key, file, line)
+{
+    return new MenvError(`Duplicate key: ${key}${formatLocation(file, line)}`);
+}
+
+/**
+ * Create a missing required key error.
+ * @param {string} key
+ * @returns {MenvError}
+ */
+function missingRequiredError(key)
+{
+    return new MenvError(`Missing required key: ${key}`);
+}
+
+/**
+ * Create an invalid type error.
+ * @param {string} type
+ * @param {string} raw
+ * @param {string} file
+ * @param {number} line
+ * @returns {MenvError}
+ */
+function invalidTypeError(type, raw, file, line)
+{
+    return new MenvError(`Invalid ${type}: ${raw}${formatLocation(file, line)}`);
+}
+
+module.exports = {
+    MenvError,
+    invalidLineError,
+    unknownKeyError,
+    duplicateKeyError,
+    missingRequiredError,
+    invalidTypeError
+};

package/src/lib/files.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Resolve .menv file paths based on options.
+ * @param {{cwd?: string, files?: string[], profile?: string}} options
+ * @returns {string[]}
+ */
+function resolveFiles(options)
+{
+    const cwd = options.cwd || process.cwd();
+    if (Array.isArray(options.files) && options.files.length > 0)
+    {
+        return options.files.map((file) => (path.isAbsolute(file) ? file : path.join(cwd, file)));
+    }
+
+    const files = [
+        path.join(cwd, '.menv'),
+        path.join(cwd, '.menv.local')
+    ];
+
+    if (options.profile)
+    {
+        files.push(
+            path.join(cwd, `.menv.${options.profile}`),
+            path.join(cwd, `.menv.${options.profile}.local`)
+        );
+    }
+
+    return files;
+}
+
+module.exports = {
+    resolveFiles
+};

package/src/lib/parser.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const { invalidLineError } = require('./errors');
+
+/**
+ * Strip inline comments while preserving quoted values.
+ * @param {string} line
+ * @returns {string}
+ */
+function stripInlineComment(line)
+{
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < line.length; i += 1)
+    {
+        const ch = line[i];
+        if (escaped)
+        {
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\')
+        {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"' && !inSingle)
+        {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (ch === "'" && !inDouble)
+        {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '#' && !inSingle && !inDouble)
+        {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+
+/**
+ * Remove wrapping quotes and unescape common sequences.
+ * @param {string} value
+ * @returns {string}
+ */
+function stripQuotes(value)
+{
+    const trimmed = value.trim();
+    if (trimmed.length >= 2)
+    {
+        const first = trimmed[0];
+        const last = trimmed[trimmed.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'"))
+        {
+            return trimmed
+                .slice(1, -1)
+                .replace(/\\n/g, '\n')
+                .replace(/\\r/g, '\r')
+                .replace(/\\t/g, '\t')
+                .replace(/\\\\/g, '\\');
+        }
+    }
+    return trimmed;
+}
+
+/**
+ * Parse raw text into key/value entries.
+ * @param {string} text
+ * @param {{strict?: boolean, filePath?: string}} options
+ * @returns {{key: string, raw: string, line: number}[]}
+ */
+function parseEntries(text, options)
+{
+    const strict = Boolean(options.strict);
+    const filePath = options.filePath;
+    const lines = text.split(/\r?\n/);
+    const entries = [];
+
+    for (let i = 0; i < lines.length; i += 1)
+    {
+        const rawLine = lines[i];
+        const cleaned = stripInlineComment(rawLine);
+        if (!cleaned.trim()) continue;
+
+        const match = cleaned.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+        if (!match)
+        {
+            if (strict)
+            {
+                throw invalidLineError(i + 1, rawLine, filePath);
+            }
+            continue;
+        }
+
+        const key = match[1];
+        const rawValue = stripQuotes(match[2] || '');
+
+        entries.push({
+            key,
+            raw: rawValue,
+            line: i + 1
+        });
+    }
+
+    return entries;
+}
+
+module.exports = {
+    parseEntries
+};

package/src/lib/schema.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { missingRequiredError } = require('./errors');
+
+/**
+ * Normalize schema definitions into objects.
+ * @param {object} schema
+ * @returns {object|null}
+ */
+function normalizeSchema(schema)
+{
+    if (!schema) return null;
+    const normalized = {};
+    for (const key of Object.keys(schema))
+    {
+        const def = schema[key];
+        if (typeof def === 'string')
+        {
+            normalized[key] = { type: def };
+        } else if (def && typeof def === 'object')
+        {
+            normalized[key] = { ...def };
+        }
+    }
+    return normalized;
+}
+
+/**
+ * Apply defaults and required checks from schema.
+ * @param {object} values
+ * @param {object} origins
+ * @param {object|null} schema
+ * @param {boolean} strict
+ * @returns {void}
+ */
+function applySchemaDefaults(values, origins, schema, strict)
+{
+    if (!schema) return;
+    for (const key of Object.keys(schema))
+    {
+        const def = schema[key];
+        if (values[key] === undefined)
+        {
+            if (def && Object.prototype.hasOwnProperty.call(def, 'default'))
+            {
+                values[key] = def.default;
+                origins[key] = { file: '<default>', line: 0, raw: undefined };
+            } else if (strict && def && def.required)
+            {
+                throw missingRequiredError(key);
+            }
+        }
+    }
+}
+
+module.exports = {
+    normalizeSchema,
+    applySchemaDefaults
+};

package/src/lib/utils.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Recursively freeze an object graph.
+ * @param {object} obj
+ * @returns {object}
+ */
+function deepFreeze(obj)
+{
+    if (!obj || typeof obj !== 'object' || Object.isFrozen(obj)) return obj;
+    Object.freeze(obj);
+    for (const key of Object.keys(obj))
+    {
+        deepFreeze(obj[key]);
+    }
+    return obj;
+}
+
+module.exports = {
+    deepFreeze
+};

package/src/lib/watch.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveFiles } = require('./files');
+
+/**
+ * Watch resolved files and reload on changes.
+ * @param {object} options
+ * @param {(err: Error|null, result?: {parsed: object, origins: object, files: string[]}) => void} onChange
+ * @param {(options: object) => {parsed: object, origins: object, files: string[]}} load
+ * @returns {{close: () => void}}
+ */
+function watch(options, onChange, load)
+{
+    if (typeof onChange !== 'function')
+    {
+        throw new Error('onChange callback is required');
+    }
+    if (typeof load !== 'function')
+    {
+        throw new Error('load function is required');
+    }
+
+    const files = resolveFiles(options);
+    const cwd = options.cwd || process.cwd();
+    const basenames = new Set(files.map((file) => path.basename(file)));
+    const watchers = [];
+    let timer = null;
+
+    const trigger = () =>
+    {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() =>
+        {
+            try
+            {
+                const result = load(options);
+                onChange(null, result);
+            } catch (err)
+            {
+                onChange(err);
+            }
+        }, 50);
+    };
+
+    for (const filePath of files)
+    {
+        if (!fs.existsSync(filePath)) continue;
+        watchers.push(fs.watch(filePath, trigger));
+    }
+
+    if (options.watchMissing !== false)
+    {
+        watchers.push(fs.watch(cwd, (event, filename) =>
+        {
+            if (!filename) return;
+            if (basenames.has(filename))
+            {
+                trigger();
+            }
+        }));
+    }
+
+    return {
+        close()
+        {
+            watchers.forEach((watcher) => watcher.close());
+            watchers.length = 0;
+        }
+    };
+}
+
+module.exports = {
+    watch
+};