easycli-config 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avijit
+
+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,56 @@
+# @easycli/config
+
+Zero-config configuration loader for EasyCLI apps.
+
+## Features
+
+- **Zero Config**: Works out of the box.
+- **Hierarchical Loading**: Loads from home directory, project directory, and environment variables.
+- **Multiple Formats**: Supports JSON, JS, and TS config files.
+- **Type Safe**: Fully typed with TypeScript.
+
+## Installation
+
+```bash
+pnpm add @easycli/config
+```
+
+## Usage
+
+```ts
+import { loadConfig } from "@easycli/config";
+
+interface MyConfig {
+  port: number;
+  dbUrl: string;
+}
+
+// Loads and merges config from all supported sources
+const config = await loadConfig<MyConfig>();
+
+console.log(config);
+```
+
+## Configuration Search Order
+
+Configuration is merged in the following order (last one wins):
+
+1. **Home Directory**: `~/.easyclirc.json`
+2. **Project Directory** (searched in order):
+   - `.easyclirc.json`
+   - `.easyclirc`
+   - `easycli.config.json`
+   - `easycli.config.js`
+   - `easycli.config.ts`
+3. **Environment Variables**: Variables starting with `EASYCLI_`
+   - `EASYCLI_PORT=3000` -> `{ port: 3000 }`
+   - `EASYCLI_DB_URL=postgres://...` -> `{ db: { url: "postgres://..." } }`
+
+## API
+
+### `loadConfig<T>(options?: ConfigLoaderOptions): Promise<T>`
+
+Loads the configuration.
+
+- **options.cwd**: Directory to search for config files (default: `process.cwd()`)
+- **options.name**: Config name namespace (default: "easycli")

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options for the configuration loader.
+ */
+interface ConfigLoaderOptions {
+    /**
+     * The current working directory to search for configuration files.
+     * Defaults to `process.cwd()`.
+     */
+    cwd?: string;
+    /**
+     * Optional name to use for configuration files (defaults to "easycli").
+     * Not currently used in logic but reserved for future customization.
+     */
+    name?: string;
+}
+/**
+ * Loads configuration from multiple sources, merging them in the following order:
+ * 1. User home directory config (`~/.easyclirc.json`)
+ * 2. Project config files (in order of precedence):
+ *    - `.easyclirc.json`
+ *    - `.easyclirc`
+ *    - `easycli.config.json`
+ *    - `easycli.config.js`
+ *    - `easycli.config.ts`
+ * 3. Environment variables (prefixed with `EASYCLI_`)
+ *
+ * @template T - The expected shape of the configuration object.
+ * @param options - Configuration options.
+ * @returns A promise that resolves to the merged configuration object.
+ *
+ * @example
+ * ```ts
+ * interface MyConfig {
+ *   port: number;
+ *   debug: boolean;
+ * }
+ *
+ * const config = await loadConfig<MyConfig>();
+ * console.log(config.port);
+ * ```
+ */
+declare function loadConfig<T = Record<string, unknown>>(options?: ConfigLoaderOptions): Promise<T>;
+
+export { type ConfigLoaderOptions, loadConfig };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/loader.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { pathToFileURL } from "url";
+var CONFIG_FILES = [
+  ".easyclirc.json",
+  ".easyclirc",
+  "easycli.config.json",
+  "easycli.config.js",
+  "easycli.config.ts"
+];
+async function loadConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configs = [];
+  const homeConfig = await loadJsonConfig(join(homedir(), ".easyclirc.json"));
+  if (homeConfig) {
+    configs.push(homeConfig);
+  }
+  for (const filename of CONFIG_FILES) {
+    const filepath = join(cwd, filename);
+    if (filename.endsWith(".json") || filename === ".easyclirc") {
+      const config = await loadJsonConfig(filepath);
+      if (config) {
+        configs.push(config);
+      }
+    } else if (filename.endsWith(".js") || filename.endsWith(".ts")) {
+      const config = await loadModuleConfig(filepath);
+      if (config) {
+        configs.push(config);
+      }
+    }
+  }
+  const envConfig = loadEnvConfig();
+  if (Object.keys(envConfig).length > 0) {
+    configs.push(envConfig);
+  }
+  return mergeConfigs(configs);
+}
+async function loadJsonConfig(filepath) {
+  try {
+    const content = await readFile(filepath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function loadModuleConfig(filepath) {
+  try {
+    const url = pathToFileURL(filepath).href;
+    const mod = await import(url);
+    return mod.default ?? null;
+  } catch {
+    return null;
+  }
+}
+function loadEnvConfig() {
+  const config = {};
+  const prefix = "EASYCLI_";
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(prefix) && value !== void 0) {
+      const configKey = key.slice(prefix.length).toLowerCase().replace(/_/g, ".");
+      setNestedValue(config, configKey, parseEnvValue(value));
+    }
+  }
+  return config;
+}
+function parseEnvValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  const num = Number(value);
+  if (!Number.isNaN(num)) return num;
+  return value;
+}
+function setNestedValue(obj, path, value) {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (key) {
+      if (!(key in current)) {
+        current[key] = {};
+      }
+      current = current[key];
+    }
+  }
+  const lastKey = keys[keys.length - 1];
+  if (lastKey) {
+    current[lastKey] = value;
+  }
+}
+function mergeConfigs(configs) {
+  const result = {};
+  for (const config of configs) {
+    deepMerge(result, config);
+  }
+  return result;
+}
+function deepMerge(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value) && typeof target[key] === "object" && target[key] !== null && !Array.isArray(target[key])) {
+      deepMerge(
+        target[key],
+        value
+      );
+    } else {
+      target[key] = value;
+    }
+  }
+}
+export {
+  loadConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/loader.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\r\nimport { join } from \"node:path\";\r\nimport { homedir } from \"node:os\";\r\nimport { pathToFileURL } from \"node:url\";\r\n\r\n/**\r\n * Options for the configuration loader.\r\n */\r\nexport interface ConfigLoaderOptions {\r\n  /**\r\n   * The current working directory to search for configuration files.\r\n   * Defaults to `process.cwd()`.\r\n   */\r\n  cwd?: string;\r\n  /**\r\n   * Optional name to use for configuration files (defaults to \"easycli\").\r\n   * Not currently used in logic but reserved for future customization.\r\n   */\r\n  name?: string;\r\n}\r\n\r\nconst CONFIG_FILES = [\r\n  \".easyclirc.json\",\r\n  \".easyclirc\",\r\n  \"easycli.config.json\",\r\n  \"easycli.config.js\",\r\n  \"easycli.config.ts\"\r\n];\r\n\r\n/**\r\n * Loads configuration from multiple sources, merging them in the following order:\r\n * 1. User home directory config (`~/.easyclirc.json`)\r\n * 2. Project config files (in order of precedence):\r\n *    - `.easyclirc.json`\r\n *    - `.easyclirc`\r\n *    - `easycli.config.json`\r\n *    - `easycli.config.js`\r\n *    - `easycli.config.ts`\r\n * 3. Environment variables (prefixed with `EASYCLI_`)\r\n *\r\n * @template T - The expected shape of the configuration object.\r\n * @param options - Configuration options.\r\n * @returns A promise that resolves to the merged configuration object.\r\n *\r\n * @example\r\n * ```ts\r\n * interface MyConfig {\r\n *   port: number;\r\n *   debug: boolean;\r\n * }\r\n *\r\n * const config = await loadConfig<MyConfig>();\r\n * console.log(config.port);\r\n * ```\r\n */\r\nexport async function loadConfig<T = Record<string, unknown>>(\r\n  options: ConfigLoaderOptions = {}\r\n): Promise<T> {\r\n  const cwd = options.cwd ?? process.cwd();\r\n  const configs: Record<string, unknown>[] = [];\r\n\r\n  const homeConfig = await loadJsonConfig(join(homedir(), \".easyclirc.json\"));\r\n  if (homeConfig) {\r\n    configs.push(homeConfig);\r\n  }\r\n\r\n  for (const filename of CONFIG_FILES) {\r\n    const filepath = join(cwd, filename);\r\n    if (filename.endsWith(\".json\") || filename === \".easyclirc\") {\r\n      const config = await loadJsonConfig(filepath);\r\n      if (config) {\r\n        configs.push(config);\r\n      }\r\n    } else if (filename.endsWith(\".js\") || filename.endsWith(\".ts\")) {\r\n      const config = await loadModuleConfig(filepath);\r\n      if (config) {\r\n        configs.push(config);\r\n      }\r\n    }\r\n  }\r\n\r\n  const envConfig = loadEnvConfig();\r\n  if (Object.keys(envConfig).length > 0) {\r\n    configs.push(envConfig);\r\n  }\r\n\r\n  return mergeConfigs(configs) as T;\r\n}\r\n\r\nasync function loadJsonConfig(\r\n  filepath: string\r\n): Promise<Record<string, unknown> | null> {\r\n  try {\r\n    const content = await readFile(filepath, \"utf-8\");\r\n    return JSON.parse(content) as Record<string, unknown>;\r\n  } catch {\r\n    return null;\r\n  }\r\n}\r\n\r\nasync function loadModuleConfig(\r\n  filepath: string\r\n): Promise<Record<string, unknown> | null> {\r\n  try {\r\n    const url = pathToFileURL(filepath).href;\r\n    const mod = (await import(url)) as { default?: Record<string, unknown> };\r\n    return mod.default ?? null;\r\n  } catch {\r\n    return null;\r\n  }\r\n}\r\n\r\nfunction loadEnvConfig(): Record<string, unknown> {\r\n  const config: Record<string, unknown> = {};\r\n  const prefix = \"EASYCLI_\";\r\n\r\n  for (const [key, value] of Object.entries(process.env)) {\r\n    if (key.startsWith(prefix) && value !== undefined) {\r\n      const configKey = key\r\n        .slice(prefix.length)\r\n        .toLowerCase()\r\n        .replace(/_/g, \".\");\r\n      setNestedValue(config, configKey, parseEnvValue(value));\r\n    }\r\n  }\r\n\r\n  return config;\r\n}\r\n\r\nfunction parseEnvValue(value: string): unknown {\r\n  if (value === \"true\") return true;\r\n  if (value === \"false\") return false;\r\n  const num = Number(value);\r\n  if (!Number.isNaN(num)) return num;\r\n  return value;\r\n}\r\n\r\nfunction setNestedValue(\r\n  obj: Record<string, unknown>,\r\n  path: string,\r\n  value: unknown\r\n): void {\r\n  const keys = path.split(\".\");\r\n  let current = obj;\r\n\r\n  for (let i = 0; i < keys.length - 1; i++) {\r\n    const key = keys[i];\r\n    if (key) {\r\n      if (!(key in current)) {\r\n        current[key] = {};\r\n      }\r\n      current = current[key] as Record<string, unknown>;\r\n    }\r\n  }\r\n\r\n  const lastKey = keys[keys.length - 1];\r\n  if (lastKey) {\r\n    current[lastKey] = value;\r\n  }\r\n}\r\n\r\nfunction mergeConfigs(configs: Record<string, unknown>[]): Record<string, unknown> {\r\n  const result: Record<string, unknown> = {};\r\n\r\n  for (const config of configs) {\r\n    deepMerge(result, config);\r\n  }\r\n\r\n  return result;\r\n}\r\n\r\nfunction deepMerge(\r\n  target: Record<string, unknown>,\r\n  source: Record<string, unknown>\r\n): void {\r\n  for (const [key, value] of Object.entries(source)) {\r\n    if (\r\n      value !== null &&\r\n      typeof value === \"object\" &&\r\n      !Array.isArray(value) &&\r\n      typeof target[key] === \"object\" &&\r\n      target[key] !== null &&\r\n      !Array.isArray(target[key])\r\n    ) {\r\n      deepMerge(\r\n        target[key] as Record<string, unknown>,\r\n        value as Record<string, unknown>\r\n      );\r\n    } else {\r\n      target[key] = value;\r\n    }\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "easycli-config",
+  "version": "0.0.1",
+  "description": "Configuration loader for EasyCLI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "rimraf": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}