c12 0.1.0 → 0.1.1

package/README.md

@@ -5,7 +5,7 @@
 [![Github Actions][github-actions-src]][github-actions-href]
 [![Codecov][codecov-src]][codecov-href]
 
-> Smart Config Loader
+> Smart Configuration Loader
 
 ## Features
 
@@ -13,6 +13,7 @@
 - RC config support with [unjs/rc9](https://github.com/unjs/rc9)
 - Multiple sources merged with [unjs/defu](https://github.com/unjs/defu)
 - `.env` support with [dotenv](https://www.npmjs.com/package/dotenv)
+- Support extending nested configurations from multiple local or git sourecs
 
 ## Usage
 
@@ -42,7 +43,11 @@ const { loadConfig } = require('c12')
 Load configuration:
 
 ```js
+// Get loaded config
 const { config } = await loadConfig({})
+
+// Get resolved config and extended layers
+const { config, configFile, layers } = await loadConfig({})
 ```
 
 ## Loading priority
@@ -54,6 +59,7 @@ c12 merged config sources with [unjs/defu](https://github.com/unjs/defu) by belo
 3. RC file in CWD
 4. global RC file in user's home directory
 5. default config passed by options
+6. Extended config layers
 
 ## Options
 
@@ -93,6 +99,85 @@ Specify default configuration. It has the **lowest** priority.
 
 Specify override configuration. It has the **highest** priority.
 
+## Extending configuration
+
+If resolved config contains a `extends` key, it will be used to extend configuration.
+
+Extending can be nested and each layer can extend from one base or more.
+
+Final config is merged result of extended options and user options with [unjs/defu](https://github.com/unjs/defu).
+
+Each item in extends, is a string that can be either an absolute or relative path to current config file pointing to a config file for extending or directory containing config file.
+If it starts with either of `github:`, `gitlab:`, `bitbucket:` or `https:`, c12 autmatically clones it.
+
+For custom merging strategies, you can directly access each layer with `layers` property.
+
+**Example:**
+
+```js
+// config.ts
+export default {
+  colors: {
+    primary: 'user_primary'
+  },
+  extends: [
+    './theme',
+    './config.dev.ts'
+  ]
+}
+```
+
+```js
+// config.dev.ts
+export default {
+  dev: true
+}
+```
+
+```js
+// theme/config.ts
+export default {
+  extends: '../base',
+  colors: {
+    primary: 'theme_primary',
+    secondary: 'theme_secondary'
+  }
+}
+```
+
+```js
+// base/config.ts
+export default {
+  colors: {
+    primary: 'base_primary'
+    text: 'base_text'
+  }
+}
+```
+
+Loaded configuration would look like this:
+
+```js
+{
+  dev: true,
+  colors: {
+    primary: 'user_primary',
+    secondary: 'theme_secondary',
+    text: 'base_text'
+  }
+}
+```
+
+Layers:
+
+```js
+[
+ { config: /* theme config */, configFile: /* path/to/theme/config.ts */, cwd: /* path/to/theme */ },
+ { config: /* base  config */, configFile: /* path/to/base/config.ts  */, cwd: /* path/to/base */ },
+ { config: /* dev   config */, configFile: /* path/to/config.dev.ts  */, cwd: /* path/ */ },
+]
+```
+
 ## 💻 Development
 
 - Clone this repository

package/dist/index.cjs

@@ -5,6 +5,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 const fs = require('fs');
 const pathe = require('pathe');
 const dotenv = require('dotenv');
+const os = require('os');
 const createJiti = require('jiti');
 const rc9 = require('rc9');
 const defu = require('defu');
@@ -24,6 +25,7 @@ function _interopNamespace(e) {
 }
 
 const dotenv__namespace = /*#__PURE__*/_interopNamespace(dotenv);
+const os__default = /*#__PURE__*/_interopDefaultLegacy(os);
 const createJiti__default = /*#__PURE__*/_interopDefaultLegacy(createJiti);
 const rc9__namespace = /*#__PURE__*/_interopNamespace(rc9);
 const defu__default = /*#__PURE__*/_interopDefaultLegacy(defu);
@@ -98,17 +100,22 @@ async function loadConfig(opts) {
   opts.name = opts.name || "config";
   opts.configFile = opts.configFile ?? (opts.name !== "config" ? `${opts.name}.config` : "config");
   opts.rcFile = opts.rcFile ?? `.${opts.name}rc`;
-  const ctx = {
-    config: {}
+  const r = {
+    config: {},
+    cwd: opts.cwd,
+    configFile: pathe.resolve(opts.cwd, opts.configFile),
+    layers: []
   };
   if (opts.dotenv) {
-    ctx.env = await setupDotenv({
+    await setupDotenv({
       cwd: opts.cwd,
       ...opts.dotenv === true ? {} : opts.dotenv
     });
   }
-  const { config, configPath } = await loadConfigFile(opts);
-  ctx.configPath = configPath;
+  const { config, configFile } = await loadConfigFile(opts.cwd, opts.configFile);
+  if (configFile) {
+    r.configFile = configFile;
+  }
   const configRC = {};
   if (opts.rcFile) {
     if (opts.globalRc) {
@@ -116,21 +123,61 @@ async function loadConfig(opts) {
     }
     Object.assign(configRC, rc9__namespace.read({ name: opts.rcFile, dir: opts.cwd }));
   }
-  ctx.config = defu__default(opts.overrides, config, configRC, opts.defaults);
-  return ctx;
+  r.config = defu__default(opts.overrides, config, configRC, opts.defaults);
+  await extendConfig(r.config, opts.configFile, opts.cwd);
+  r.layers = r.config._layers;
+  delete r.config._layers;
+  r.config = defu__default(r.config, ...r.layers.map((e) => e.config));
+  return r;
+}
+const GIT_PREFIXES = ["github:", "gitlab:", "bitbucket:", "https://"];
+async function extendConfig(config, configFile, cwd) {
+  config._layers = config._layers || [];
+  const extendSources = (Array.isArray(config.extends) ? config.extends : [config.extends]).filter(Boolean);
+  delete config.extends;
+  for (let extendSource of extendSources) {
+    if (GIT_PREFIXES.some((prefix) => extendSource.startsWith(prefix))) {
+      const url = new URL(extendSource);
+      const subPath = url.pathname.split("/").slice(2).join("/");
+      const gitRepo = url.protocol + url.pathname.split("/").slice(0, 2).join("/");
+      const tmpdir = pathe.resolve(os__default.tmpdir(), "c12/", gitRepo.replace(/[#:@/\\]/g, "_"));
+      await fs.promises.rm(tmpdir, { recursive: true }).catch(() => {
+      });
+      const gittar = await import('gittar').then((r) => r.default || r);
+      const tarFile = await gittar.fetch(gitRepo);
+      await gittar.extract(tarFile, tmpdir);
+      extendSource = pathe.resolve(tmpdir, subPath);
+    }
+    const isDir = !pathe.extname(extendSource);
+    const _cwd = pathe.resolve(cwd, isDir ? extendSource : pathe.dirname(extendSource));
+    const _config = await loadConfigFile(_cwd, isDir ? configFile : extendSource);
+    if (!_config.config) {
+      continue;
+    }
+    await extendConfig(_config.config, configFile, _cwd);
+    config._layers.push({
+      config: _config.config,
+      cwd: _cwd,
+      configFile: _config.configFile
+    });
+    if (_config.config._layers) {
+      config._layers.push(..._config.config._layers);
+      delete _config.config._layers;
+    }
+  }
 }
 const jiti = createJiti__default(null, { cache: false, interopDefault: true });
-async function loadConfigFile(opts) {
+async function loadConfigFile(cwd, configFile) {
   const res = {
-    configPath: null,
+    configFile: null,
     config: null
   };
-  if (!opts.configFile) {
+  if (!configFile) {
     return res;
   }
   try {
-    res.configPath = jiti.resolve(pathe.resolve(opts.cwd, opts.configFile), { paths: [opts.cwd] });
-    res.config = jiti(res.configPath);
+    res.configFile = jiti.resolve(pathe.resolve(cwd, configFile), { paths: [cwd] });
+    res.config = jiti(res.configFile);
     if (typeof res.config === "function") {
       res.config = await res.config();
     }

package/dist/index.d.ts

@@ -34,22 +34,24 @@ declare function setupDotenv(options: DotenvOptions): Promise<Env>;
 /** Load environment variables into an object. */
 declare function loadDotenv(opts: DotenvOptions): Promise<Env>;
 
-declare type ConfigT = Record<string, any>;
-interface LoadConfigOptions<T extends ConfigT = ConfigT> {
+interface InputConfig extends Record<string, any> {
+}
+interface ResolvedConfig<T extends InputConfig = InputConfig> {
+    config: T;
+    cwd: string;
+    configFile: string;
+    layers: ResolvedConfig<T>[];
+}
+interface LoadConfigOptions<T extends InputConfig = InputConfig> {
     name?: string;
     cwd?: string;
-    configFile?: false | string;
+    configFile?: string;
     rcFile?: false | string;
     globalRc?: boolean;
     dotenv?: boolean | DotenvOptions;
     defaults?: T;
     overrides?: T;
 }
-interface ResolvedConfig<T extends ConfigT = ConfigT> {
-    config: T;
-    configPath?: string;
-    env?: Record<string, any>;
-}
-declare function loadConfig<T extends ConfigT = ConfigT>(opts: LoadConfigOptions<T>): Promise<ResolvedConfig<T>>;
+declare function loadConfig<T extends InputConfig = InputConfig>(opts: LoadConfigOptions<T>): Promise<ResolvedConfig<T>>;
 
-export { ConfigT, DotenvOptions, Env, LoadConfigOptions, ResolvedConfig, loadConfig, loadDotenv, setupDotenv };
+export { DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvedConfig, loadConfig, loadDotenv, setupDotenv };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { existsSync, promises } from 'fs';
-import { resolve } from 'pathe';
+import { resolve, extname, dirname } from 'pathe';
 import * as dotenv from 'dotenv';
+import os from 'os';
 import createJiti from 'jiti';
 import * as rc9 from 'rc9';
 import defu from 'defu';
@@ -75,17 +76,22 @@ async function loadConfig(opts) {
   opts.name = opts.name || "config";
   opts.configFile = opts.configFile ?? (opts.name !== "config" ? `${opts.name}.config` : "config");
   opts.rcFile = opts.rcFile ?? `.${opts.name}rc`;
-  const ctx = {
-    config: {}
+  const r = {
+    config: {},
+    cwd: opts.cwd,
+    configFile: resolve(opts.cwd, opts.configFile),
+    layers: []
   };
   if (opts.dotenv) {
-    ctx.env = await setupDotenv({
+    await setupDotenv({
       cwd: opts.cwd,
       ...opts.dotenv === true ? {} : opts.dotenv
     });
   }
-  const { config, configPath } = await loadConfigFile(opts);
-  ctx.configPath = configPath;
+  const { config, configFile } = await loadConfigFile(opts.cwd, opts.configFile);
+  if (configFile) {
+    r.configFile = configFile;
+  }
   const configRC = {};
   if (opts.rcFile) {
     if (opts.globalRc) {
@@ -93,21 +99,61 @@ async function loadConfig(opts) {
     }
     Object.assign(configRC, rc9.read({ name: opts.rcFile, dir: opts.cwd }));
   }
-  ctx.config = defu(opts.overrides, config, configRC, opts.defaults);
-  return ctx;
+  r.config = defu(opts.overrides, config, configRC, opts.defaults);
+  await extendConfig(r.config, opts.configFile, opts.cwd);
+  r.layers = r.config._layers;
+  delete r.config._layers;
+  r.config = defu(r.config, ...r.layers.map((e) => e.config));
+  return r;
+}
+const GIT_PREFIXES = ["github:", "gitlab:", "bitbucket:", "https://"];
+async function extendConfig(config, configFile, cwd) {
+  config._layers = config._layers || [];
+  const extendSources = (Array.isArray(config.extends) ? config.extends : [config.extends]).filter(Boolean);
+  delete config.extends;
+  for (let extendSource of extendSources) {
+    if (GIT_PREFIXES.some((prefix) => extendSource.startsWith(prefix))) {
+      const url = new URL(extendSource);
+      const subPath = url.pathname.split("/").slice(2).join("/");
+      const gitRepo = url.protocol + url.pathname.split("/").slice(0, 2).join("/");
+      const tmpdir = resolve(os.tmpdir(), "c12/", gitRepo.replace(/[#:@/\\]/g, "_"));
+      await promises.rm(tmpdir, { recursive: true }).catch(() => {
+      });
+      const gittar = await import('gittar').then((r) => r.default || r);
+      const tarFile = await gittar.fetch(gitRepo);
+      await gittar.extract(tarFile, tmpdir);
+      extendSource = resolve(tmpdir, subPath);
+    }
+    const isDir = !extname(extendSource);
+    const _cwd = resolve(cwd, isDir ? extendSource : dirname(extendSource));
+    const _config = await loadConfigFile(_cwd, isDir ? configFile : extendSource);
+    if (!_config.config) {
+      continue;
+    }
+    await extendConfig(_config.config, configFile, _cwd);
+    config._layers.push({
+      config: _config.config,
+      cwd: _cwd,
+      configFile: _config.configFile
+    });
+    if (_config.config._layers) {
+      config._layers.push(..._config.config._layers);
+      delete _config.config._layers;
+    }
+  }
 }
 const jiti = createJiti(null, { cache: false, interopDefault: true });
-async function loadConfigFile(opts) {
+async function loadConfigFile(cwd, configFile) {
   const res = {
-    configPath: null,
+    configFile: null,
     config: null
   };
-  if (!opts.configFile) {
+  if (!configFile) {
     return res;
   }
   try {
-    res.configPath = jiti.resolve(resolve(opts.cwd, opts.configFile), { paths: [opts.cwd] });
-    res.config = jiti(res.configPath);
+    res.configFile = jiti.resolve(resolve(cwd, configFile), { paths: [cwd] });
+    res.config = jiti(res.configFile);
     if (typeof res.config === "function") {
       res.config = await res.config();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c12",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Smart Config Loader",
   "repository": "unjs/c12",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "dependencies": {
     "defu": "^5.0.1",
     "dotenv": "^14.3.2",
+    "gittar": "^0.1.1",
     "jiti": "^1.12.14",
     "mlly": "^0.4.1",
     "pathe": "^0.2.0",