molex-env 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,35 @@
-molex-env
+# molex-env
 
-Native .menv loader with profiles, typing, origin tracking, and optional reload.
+[![npm](https://img.shields.io/npm/v/molex-env)](https://www.npmjs.com/package/molex-env)
+[![downloads](https://img.shields.io/npm/dm/molex-env)](https://www.npmjs.com/package/molex-env)
+[![license](https://img.shields.io/npm/l/molex-env)](LICENSE)
+[![deps](https://img.shields.io/badge/deps-0-brightgreen)](package.json)
 
-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
+> Native .menv loader with profiles, typing, origin tracking, and optional reload.
 
-Install
-- npm install molex-env
+## Features
+- Deterministic profile merging - Predictable resolution across base and profile files
+- Typed parsing - Booleans, numbers, JSON, and dates with optional casting control
+- Strict mode - Reject unknown keys, duplicates, and invalid lines
+- Origin tracking - See the file and line for every value
+- Immutable config - Optional deep-freeze for safety
+- Live reload - Watch files and reload on change
 
-Basic usage
+## Install
+```bash
+npm install molex-env
+```
+
+## Quick start
+```js
+// simplest usage
+require('molex-env').load();
+
+// more detailed usage
 const { load } = require('molex-env');
 
 const result = load({
   profile: 'prod',
-  export: true,
   strict: true,
   schema: {
     PORT: 'number',
@@ -29,47 +40,144 @@ const result = load({
 
 console.log(result.parsed.PORT);
 console.log(result.origins.SERVICE_URL);
+console.log(process.menv.PORT);
+```
+
+## Setup
+1) Add one or more .menv files in your project root.
+2) Call `load()` during startup.
+3) Optionally enable profile-specific files (e.g. `prod`).
 
-File precedence
+## File format
+```env
+# Comments start with #
+PORT=3000
+DEBUG=true
+SERVICE_URL="https://api.example.com"
+METADATA={"region":"us-east-1"}
+START_DATE=2026-02-02
+```
+
+## File precedence
 1) .menv
 2) .menv.local
 3) .menv.{profile}
 4) .menv.{profile}.local
 
-API
-load(options)
+## API
+
+## load(options)
+Load, merge, parse, and validate .menv files.
+
+## 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
+- exportEnv: write values to process.env
 - override: override existing process.env values
+- attach: attach parsed values to process.menv (default true)
 - 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
+## Returns
+```js
+{
+  parsed,   // typed values
+  raw,      // raw strings
+  origins,  // { KEY: { file, line } }
+  files     // list of resolved files
+}
+```
+
+## parse(text, options)
+Parse a string of .menv content using the same typing rules as `load()`.
+
+## Options
+- schema
+- strict
+- cast
+- freeze
+
+## watch(options, onChange)
+Watch resolved files and reload on change.
+
+## Arguments
+- options: same as `load()`
+- onChange: function(err, result)
 
-watch(options, onChange)
-- Watch resolved files and reload on change
-- onChange(err, result)
+## Schema
+You can define simple types or richer objects per key.
 
-Schema example
+```js
 const schema = {
   PORT: { type: 'number', default: 3000 },
   DEBUG: { type: 'boolean', default: false },
   METADATA: { type: 'json' },
-  START_DATE: { type: 'date' }
+  START_DATE: { type: 'date' },
+  SERVICE_URL: { type: 'string', required: true }
 };
+```
+
+## Schema options per key
+- type: string | boolean | number | json | date
+- default: value used when key is missing
+- required: true | false
+
+## Typing rules
+- boolean: true/false (case-insensitive)
+- number: integer or float
+- json: JSON.parse on the value
+- date: Date.parse on the value
+
+## Strict mode
+When `strict` is true, the loader rejects:
+- unknown keys not in `schema`
+- duplicate keys across files
+- invalid lines or parse errors
+
+## Non-strict mode
+Duplicates are allowed and `onWarning(info)` is called with:
+```js
+{
+  key,
+  previous: { file, line },
+  next: { file, line }
+}
+```
+
+## Examples
+
+## Custom files
+```js
+load({
+  files: ['config/.menv', 'config/.menv.local'],
+  schema: { PORT: 'number' }
+});
+```
+
+## Disable casting
+```js
+load({ cast: false });
+```
+
+## Freeze control
+```js
+load({ freeze: false });
+```
 
-Notes
+## Notes
 - Use .menv.local for machine-specific values
 - Use strict mode to detect surprises early
+- Parsed values are attached to process.menv by default (disable with attach: false)
 
-Example project
+## Example project
 An example app is included in examples/basic.
 Run it with:
-- npm install (from examples/basic)
-- npm start
+```bash
+cd examples/basic
+npm install
+npm start
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "molex-env",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Native .menv loader with profiles, typing, and origin tracking.",
   "main": "src/index.js",
   "files": [
@@ -28,5 +28,8 @@
   "bugs": {
     "url": "https://github.com/tonywied17/molex-env/issues"
   },
-  "homepage": "https://github.com/tonywied17/molex-env#readme"
+  "homepage": "https://github.com/tonywied17/molex-env#readme",
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/index.js

@@ -3,17 +3,24 @@
 const { load, parse } = require('./lib/core');
 const { watch } = require('./lib/watch');
 
-module.exports = {
-    load,
+function loadEntry(options)
+{
+    return load(options);
+}
+
+/**
+ * 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}}
+ */
+function watchEntry(options, onChange)
+{
+    return watch(options, onChange, loadEntry);
+}
+
+module.exports = Object.assign(loadEntry, {
+    load: loadEntry,
     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);
-    }
-};
+    watch: watchEntry
+});

package/src/lib/core.js

@@ -30,7 +30,7 @@ function buildState()
  */
 function exportToEnv(values, options)
 {
-    if (!options.export) return;
+     if (!options.exportEnv) return;
     for (const [key, value] of Object.entries(values))
     {
         if (!options.override && Object.prototype.hasOwnProperty.call(process.env, key))
@@ -41,6 +41,18 @@ function exportToEnv(values, options)
     }
 }
 
+/**
+ * Attach parsed values to process.menv unless disabled.
+ * @param {object} values
+ * @param {object} options
+ * @returns {void}
+ */
+function attachToProcess(values, options)
+{
+    if (options.attach === false) return;
+    process.menv = values;
+}
+
 /**
  * Load .menv files and return parsed values with origins.
  * @param {object} options
@@ -81,6 +93,8 @@ function load(options = {})
         deepFreeze(state.values);
     }
 
+    attachToProcess(state.values, options);
+
     return {
         parsed: state.values,
         origins: state.origins,