molex-env 0.3.1 → 0.3.3

package/README.md

@@ -1,4 +1,10 @@
-# molex-env-npm
+<p align="center">
+  <img src="docs/images/logo.svg" alt="molex-env logo" width="222" height="222">
+</p>
+
+<h1 align="center">molex-env-npm</h1>
+
+<p align="center">
 
 [![npm version](https://img.shields.io/npm/v/molex-env)](https://www.npmjs.com/package/molex-env)
 [![npm downloads](https://img.shields.io/npm/dm/molex-env.svg)](https://www.npmjs.com/package/molex-env)
@@ -7,6 +13,8 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14-brightgreen.svg)](https://nodejs.org)
 [![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
 
+</p>
+
 > **Native .menv environment loader with profile support, typed parsing, origin tracking, and live reload. Zero dependencies.**
 
 ## Features
@@ -50,7 +58,7 @@ const result = load({
 
 console.log(result.parsed.PORT);              // 3000 (number)
 console.log(result.parsed.DEBUG);             // false (boolean)
-console.log(result.origins.SERVICE_URL);      // { file: '.menv', line: 3 }
+console.log(result.origins.SERVICE_URL);      // { file: '.menv', line: 3, raw: 'https://api.example.com' }
 console.log(process.menv.METADATA.region);    // 'us-east-1' (parsed JSON)
 ```
 
@@ -180,9 +188,9 @@ Load, merge, parse, and validate .menv files. This is the primary method you'll
 ```javascript
 {
   parsed: Object,   // Typed configuration values
-  raw: Object,      // Raw string values before parsing
-  origins: Object,  // Source tracking: { KEY: { file, line } }
-  files: Array      // List of resolved file paths
+  raw: Object,      // Raw string values before type casting
+  origins: Object,  // Source tracking: { KEY: { file, line, raw } }
+  files: Array      // List of resolved file paths that were read
 }
 ```
 
@@ -230,6 +238,8 @@ Parse a string of .menv content without loading files. Useful for testing or pro
 | `strict` | `boolean` | `false` | Enable strict validation (rejects unknown keys, within-file duplicates, invalid lines) |
 | `cast` | `boolean\|Object` | `true` | Enable/disable type casting |
 | `freeze` | `boolean` | `true` | Deep-freeze the result |
+| `filePath` | `string` | `'<inline>'` | Virtual file path used in origin tracking and error messages |
+| `onWarning` | `Function` | `undefined` | Callback for non-strict warnings (e.g., within-string duplicates) |
 
 > **Note:** The `parse()` function processes a single string, so the `debug` option for file precedence and cross-file features don't apply here.
 
@@ -238,8 +248,9 @@ Parse a string of .menv content without loading files. Useful for testing or pro
 ```javascript
 {
   parsed: Object,   // Typed values
-  raw: Object,      // Raw string values
-  origins: Object   // Line numbers: { KEY: { line } }
+  raw: Object,      // Raw string values before type casting
+  origins: Object,  // Source tracking: { KEY: { file, line, raw } }
+  files: Array      // Contains [filePath] if filePath option was set, otherwise []
 }
 ```
 
@@ -266,7 +277,7 @@ const result = parse(envContent, {
 console.log(result.parsed.PORT);       // 3000 (number)
 console.log(result.parsed.DEBUG);      // true (boolean)
 console.log(result.parsed.METADATA);   // { env: 'production' } (object)
-console.log(result.origins.PORT);      // { line: 2 }
+console.log(result.origins.PORT);      // { file: '<inline>', line: 2, raw: '3000' }
 ```
 
 ---
@@ -599,9 +610,9 @@ const result = load({ profile: 'prod' });
 
 console.log(result.origins);
 // {
-//   PORT: { file: '.menv', line: 1 },
-//   DEBUG: { file: '.menv.local', line: 2 },
-//   SERVICE_URL: { file: '.menv.prod', line: 3 }
+//   PORT: { file: '.menv', line: 1, raw: '3000' },
+//   DEBUG: { file: '.menv.local', line: 2, raw: 'false' },
+//   SERVICE_URL: { file: '.menv.prod', line: 3, raw: 'https://api.production.com' }
 // }
 
 // Debug where a value came from
@@ -791,10 +802,10 @@ Production:    .menv + .menv.prod + .menv.prod.local
 
 ## Example Project
 
-A complete example application is included in `examples/basic`.
+A complete example application is included in `examples/full`.
 
 ```bash
-cd examples/basic
+cd examples/full
 npm install
 npm start
 ```
@@ -886,4 +897,4 @@ console.log(result.origins.PORT);  // { file: '.menv.prod', line: 1, raw: '8080'
 
 ## License
 
-ISC License
+MIT License

package/index.d.ts

@@ -0,0 +1,134 @@
+// Type definitions for molex-env
+// Project: https://github.com/tonywied17/molex-env-npm
+
+/* ------------------------------------------------------------------ */
+/*  Option types                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface CastOptions
+{
+    boolean?: boolean;
+    number?: boolean;
+    json?: boolean;
+    date?: boolean;
+}
+
+export interface SchemaDefinition
+{
+    type: 'string' | 'boolean' | 'number' | 'json' | 'date';
+    required?: boolean;
+    default?: any;
+}
+
+export interface Warning
+{
+    type: string;
+    key: string;
+    file: string;
+    line: number;
+}
+
+export interface LoadOptions
+{
+    /** Base directory to resolve files from. */
+    cwd?: string;
+    /** Profile name for `.menv.{profile}` files. */
+    profile?: string;
+    /** Custom file list (absolute or relative to cwd). */
+    files?: string[];
+    /** Schema definition for validation and typing. */
+    schema?: Record<string, SchemaDefinition | string>;
+    /** Reject unknown keys, within-file duplicates, and invalid lines. */
+    strict?: boolean;
+    /** Enable/disable type casting. */
+    cast?: boolean | CastOptions;
+    /** Write parsed values to `process.env`. */
+    exportEnv?: boolean;
+    /** Override existing `process.env` values. */
+    override?: boolean;
+    /** Attach parsed values to `process.menv`. */
+    attach?: boolean;
+    /** Deep-freeze the parsed config object. */
+    freeze?: boolean;
+    /** Log file precedence overrides to console. */
+    debug?: boolean;
+    /** Callback for non-strict warnings. */
+    onWarning?: (warning: Warning) => void;
+}
+
+export interface ParseOptions
+{
+    /** Schema definition for validation. */
+    schema?: Record<string, SchemaDefinition | string>;
+    /** Enable strict validation. */
+    strict?: boolean;
+    /** Enable/disable type casting. */
+    cast?: boolean | CastOptions;
+    /** Deep-freeze the result. */
+    freeze?: boolean;
+    /** Virtual file path for origin tracking. */
+    filePath?: string;
+    /** Callback for non-strict warnings. */
+    onWarning?: (warning: Warning) => void;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Result types                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface Origin
+{
+    file: string;
+    line: number;
+    raw: string | undefined;
+}
+
+export interface LoadResult
+{
+    /** Typed configuration values. */
+    parsed: Record<string, any>;
+    /** Raw string values before type casting. */
+    raw: Record<string, string>;
+    /** Source tracking: file, line, and raw value per key. */
+    origins: Record<string, Origin>;
+    /** List of resolved file paths that were read. */
+    files: string[];
+}
+
+export interface WatchHandle
+{
+    /** Stop watching all files. */
+    close(): void;
+}
+
+export type WatchCallback = (error: Error | null, result?: LoadResult) => void;
+
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Load .menv files, merge, parse, and validate.
+ */
+export function load(options?: LoadOptions): LoadResult;
+
+/**
+ * Parse a string of .menv content without loading files.
+ */
+export function parse(text: string, options?: ParseOptions): LoadResult;
+
+/**
+ * Watch .menv files and reload automatically on change.
+ */
+export function watch(options: LoadOptions, onChange: WatchCallback): WatchHandle;
+
+/**
+ * Default export — `load` function with named exports attached.
+ */
+declare const molexEnv: typeof load & {
+    load: typeof load;
+    parse: typeof parse;
+    watch: typeof watch;
+};
+
+export = molexEnv;

package/package.json

@@ -1,35 +1,46 @@
-{
-  "name": "molex-env",
-  "version": "0.3.1",
-  "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": "Anthony Wiedman/Molex",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tonywied17/molex-env-npm.git"
-  },
-  "bugs": {
-    "url": "https://github.com/tonywied17/molex-env-npm/issues"
-  },
-  "homepage": "https://github.com/tonywied17/molex-env-npm#readme",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "molex-env",
+  "version": "0.3.3",
+  "description": "Native .menv loader with profiles, typing, and origin tracking.",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "files": [
+    "src",
+    "index.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check src/**/*.js",
+    "publish:npm": "npm publish",
+    "publish:github": "node -e \"const fs=require('fs');const pkg=JSON.parse(fs.readFileSync('package.json'));pkg.name='@tonywied17/molex-env';fs.writeFileSync('package.json',JSON.stringify(pkg,null,2))\" && npm publish --registry=https://npm.pkg.github.com && git checkout package.json"
+  },
+  "keywords": [
+    "env",
+    "dotenv",
+    "menv",
+    "config",
+    "profile",
+    "native",
+    "schema",
+    "typed",
+    "zero-dependency"
+  ],
+  "author": "Anthony Wiedman/Molex",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonywied17/molex-env-npm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonywied17/molex-env-npm/issues"
+  },
+  "homepage": "https://github.com/tonywied17/molex-env-npm#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -1,26 +1,27 @@
-'use strict';
-
-const { load, parse } = require('./lib/core');
-const { watch } = require('./lib/watch');
-
-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: watchEntry
-});
+'use strict';
+
+const { load, parse } = require('./lib/core');
+const { watch } = require('./lib/watch');
+
+/**
+ * Watch resolved .menv files and reload on change.
+ * @param {object} options         Same options as load().
+ * @param {Function} onChange      Callback: (err, result) => void.
+ * @returns {{close: () => void}}
+ */
+function watchFiles(options, onChange) {
+  return watch(options, onChange, load);
+}
+
+/*
+ * Default export is `load` itself so callers can do:
+ *   require('molex-env')()          — quick load
+ *   require('molex-env').load()     — explicit
+ *   require('molex-env').parse()    — string parsing
+ *   require('molex-env').watch()    — file watching
+ */
+module.exports = Object.assign(load, {
+  load,
+  parse,
+  watch: watchFiles,
+});

package/src/lib/apply.js

@@ -1,75 +1,61 @@
-'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, seenPerFile: Map<string, Set<string>>}} state
- * @param {{key: string, raw: string, line: number}} entry
- * @param {{schema: object|null, strict: boolean, cast: object, onWarning?: Function, debug?: boolean}} options
- * @param {string} filePath
- * @returns {void}
- */
-function applyEntry(state, entry, options, filePath)
-{
-    const { schema, strict, cast, onWarning, debug } = options;
-    const { key, raw, line } = entry;
-
-    if (schema && strict && !schema[key])
-    {
-        throw unknownKeyError(key, filePath, line);
-    }
-
-    // Initialize per-file tracking if needed
-    if (!state.seenPerFile.has(filePath))
-    {
-        state.seenPerFile.set(filePath, new Set());
-    }
-    const fileKeys = state.seenPerFile.get(filePath);
-
-    // Check for duplicates ONLY within the same file
-    if (fileKeys.has(key))
-    {
-        if (strict)
-        {
-            throw duplicateKeyError(key, filePath, line);
-        }
-        if (typeof onWarning === 'function')
-        {
-            onWarning({
-                type: 'duplicate',
-                key,
-                file: filePath,
-                line
-            });
-        }
-    }
-
-    // Debug logging for file precedence
-    if (debug && state.values[key] !== undefined)
-    {
-        const prevOrigin = state.origins[key];
-        console.log(`[molex-env] Override: ${key}`);
-        console.log(`  Previous: ${prevOrigin.file}:${prevOrigin.line} = ${prevOrigin.raw}`);
-        console.log(`  New:      ${filePath}:${line} = ${raw}`);
-    }
-
-    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 };
-    fileKeys.add(key);
-}
-
-module.exports = {
-    applyEntry
-};
+'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, raw: object, origins: object, seenPerFile: Map<string, Set<string>>}} state
+ * @param {{key: string, raw: string, line: number}} entry
+ * @param {{schema: object|null, strict: boolean, cast: object, onWarning?: Function, debug?: boolean}} options
+ * @param {string} filePath
+ */
+function applyEntry(state, entry, options, filePath)
+{
+    const { schema, strict, cast, onWarning, debug } = options;
+    const { key, raw, line } = entry;
+
+    // Reject keys not defined in schema when strict
+    if (schema && strict && !schema[key])
+    {
+        throw unknownKeyError(key, filePath, line);
+    }
+
+    // Per-file duplicate tracking
+    if (!state.seenPerFile.has(filePath))
+    {
+        state.seenPerFile.set(filePath, new Set());
+    }
+    const fileKeys = state.seenPerFile.get(filePath);
+
+    if (fileKeys.has(key))
+    {
+        if (strict) throw duplicateKeyError(key, filePath, line);
+        if (typeof onWarning === 'function')
+        {
+            onWarning({ type: 'duplicate', key, file: filePath, line });
+        }
+    }
+
+    // Debug logging for cross-file overrides
+    if (debug && state.values[key] !== undefined)
+    {
+        const prev = state.origins[key];
+        console.log(`[molex-env] Override: ${key}`);
+        console.log(`  Previous: ${prev.file}:${prev.line} = ${prev.raw}`);
+        console.log(`  New:      ${filePath}:${line} = ${raw}`);
+    }
+
+    // Type coercion: schema type takes precedence, otherwise auto-cast
+    const def = schema ? schema[key] : null;
+    const value = (def && def.type)
+        ? coerceType(raw, def.type, filePath, line)
+        : autoCast(raw, cast);
+
+    state.values[key] = value;
+    state.raw[key] = raw;
+    state.origins[key] = { file: filePath, line, raw };
+    fileKeys.add(key);
+}
+
+module.exports = { applyEntry };