@untool/core - npm Package Compare versions

Comparing version 0.1.0 to 0.4.0

CHANGELOG.md

@@ -6,2 +6,10 @@ # Change Log
 
+<a name="0.4.0"></a>
+# [0.4.0](https://github.com/untool/untool/compare/v0.3.2...v0.4.0) (2018-04-16)
+
+
+
+
+**Note:** Version bump only for package @untool/core
+
 <a name="0.0.2"></a>
@@ -8,0 +16,0 @@ ## 0.0.2 (2018-02-26)

lib/config.js

 const { basename, dirname, join } = require('path');
 
+const { create: { sync: createResolver } } = require('enhanced-resolve');
 const { sync: findUp } = require('find-up');
@@ -10,58 +11,52 @@ const cosmiconfig = require('cosmiconfig');
 
-const { create: { sync: createResolver } } = require('enhanced-resolve');
+const merge = (...args) =>
+  mergeWith({}, ...args, (objValue, srcValue, key) => {
+    if (Array.isArray(objValue)) {
+      if ('mixins' === key) {
+        return objValue.concat(srcValue);
+      }
+      return srcValue;
+    }
+  });
 
-function resolvePreset(...args) {
+const resolvePreset = (context, preset) => {
   try {
     return createResolver({
-      extensions: ['.mjs', '.js'],
       mainFiles: ['preset'],
-      mainFields: ['esnext:preset', 'jsnext:preset', 'preset'],
-    })(...args);
+      mainFields: ['preset'],
+    })(context, preset);
   } catch (_) {
-    throw new Error(`preset not found ${args[1]}`);
+    throw new Error(`preset not found ${preset}`);
   }
-}
+};
 
-function resolveMixin(target, ...args) {
+const resolveMixin = (target, context, mixin) => {
   try {
     const config = {
-      extensions: ['.mjs', '.js'],
       mainFiles: [`mixin.${target}`, 'mixin'],
-      mainFields: [
-        `esnext:mixin:${target}`,
-        `jsnext:mixin:${target}`,
-        `mixin:${target}`,
-        'esnext:mixin',
-        'jsnext:mixin',
-        'mixin',
-      ],
+      mainFields: [`mixin:${target}`, 'mixin'],
     };
     if (target !== 'core') {
       config.mainFiles.splice(1, 0, 'mixin.runtime');
-      config.mainFields.splice(
-        3,
-        0,
-        'esnext:mixin:runtime',
-        'jsnext:mixin:runtime',
-        'mixin:runtime'
-      );
+      config.mainFields.splice(1, 0, 'mixin:runtime');
     }
-    return createResolver(config)(...args);
+    return createResolver(config)(context, mixin);
   } catch (_) {
     return null;
   }
-}
+};
 
-function merge(...args) {
-  return mergeWith({}, ...args, (objValue, srcValue, key) => {
-    if (Array.isArray(objValue)) {
-      if ('mixins' === key) {
-        return objValue.concat(srcValue);
+const applyEnv = result => {
+  const env = process.env.UNTOOL_ENV || process.env.NODE_ENV;
+  const config = result && result.config;
+  return result
+    ? {
+        ...result,
+        config: config && config.env ? merge(config, config.env[env]) : config,
       }
-      return srcValue;
-    }
-  });
-}
+    : result;
+};
 
-function loadConfig(context, preset) {
+const loadConfig = (context, preset) => {
+  const nsp = process.env.UNTOOL_NSP || 'untool';
   try {
@@ -71,47 +66,51 @@ const options = preset
       : { rcExtensions: true, stopDir: context, sync: true };
-    const explorer = cosmiconfig('untool', options);
-    return explorer.load(context);
+    const explorer = cosmiconfig(nsp, options);
+    return applyEnv(explorer.load(context));
   } catch (_) {
     return null;
   }
-}
+};
 
-function loadSettings(...args) {
-  const result = loadConfig(...args);
+const loadSettings = context => {
+  const result = loadConfig(context);
   return result ? result.config : {};
-}
+};
 
-function loadPresets(context, presets = []) {
-  return presets.reduce((result, preset) => {
-    const { config, filepath } =
+const loadPresets = (context, presets = []) =>
+  presets.reduce((result, preset) => {
+    const loadedConfig =
       loadConfig(context, preset) ||
       loadConfig(dirname(resolvePreset(context, join(preset, 'package.json'))));
-    const newContext = dirname(filepath);
-    if (config.mixins) {
-      config.mixins = config.mixins.map(
-        mixin => (mixin.startsWith('.') ? join(newContext, mixin) : mixin)
-      );
+    if (loadedConfig) {
+      const { config, filepath } = loadedConfig;
+      const newContext = dirname(filepath);
+      if (config.mixins) {
+        config.mixins = config.mixins.map(
+          mixin => (mixin.startsWith('.') ? join(newContext, mixin) : mixin)
+        );
+      }
+      return merge(result, loadPresets(newContext, config.presets), config);
+    } else {
+      throw new Error(`preset not found: ${preset}`);
     }
-    return merge(result, loadPresets(newContext, config.presets), config);
   }, {});
-}
 
-function resolvePlaceholders(config) {
+const substitutePlaceholders = config => {
   const flatConfig = flatten(config);
   const keys = Object.keys(flatConfig);
   const regExp = new RegExp(`<(${keys.map(escapeRegExp).join('|')})>`, 'g');
-  const replaceRecursive = item => {
+  const substituteRecursive = item => {
+    if (Array.isArray(item)) {
+      return item.map(substituteRecursive);
+    }
     if (isPlainObject(item)) {
       return Object.keys(item).reduce((result, key) => {
-        result[key] = replaceRecursive(item[key]);
+        result[key] = substituteRecursive(item[key]);
         return result;
       }, {});
     }
-    if (Array.isArray(item)) {
-      return item.map(replaceRecursive);
-    }
     if (typeof item === 'string') {
       return item.replace(regExp, function(_, match) {
         var result = flatConfig[match].toString();
-        return regExp.test(result) ? replaceRecursive(result) : result;
+        return regExp.test(result) ? substituteRecursive(result) : result;
       });
@@ -121,4 +120,4 @@ }
   };
-  return replaceRecursive(config);
-}
+  return substituteRecursive(config);
+};
 
@@ -128,3 +127,2 @@ exports.getConfig = () => {
   const rootDir = dirname(pkgFile);
-
   const {
@@ -136,22 +134,16 @@ name: namespace = basename(rootDir),
   const defaults = { rootDir, namespace, version, mixins: [] };
-
   const settings = loadSettings(rootDir);
-
   const presets = loadPresets(rootDir, settings.presets);
+  const rawConfig = merge(defaults, presets, settings);
 
-  const rawConfig = (config =>
-    config.env ? merge(config, config.env[process.env.NODE_ENV]) : config)(
-    merge(defaults, presets, settings)
-  );
-
   delete rawConfig.presets;
   delete rawConfig.env;
 
-  const config = resolvePlaceholders(rawConfig);
+  const config = substitutePlaceholders(rawConfig);
 
   config.mixins = ['core', 'server', 'browser'].reduce(
-    (result, key) => ({
+    (result, target) => ({
       ...result,
-      [key]: config.mixins
-        .map(mixin => resolveMixin(key, config.rootDir, mixin))
+      [target]: config.mixins
+        .map(mixin => resolveMixin(target, config.rootDir, mixin))
         .filter((mixin, index, self) => mixin && self.indexOf(mixin) === index),
@@ -158,0 +150,0 @@ }),

lib/core.js

 const define = require('mixinable');
 
 const { getConfig } = require('./config');
-const { bindAll } = require('./util');
 
-exports.Mixin = class Mixin {
-  constructor(core, config) {
-    this.core = core;
-    this.config = config;
-    this.options = {};
-    bindAll(this);
-  }
-};
+exports.Mixin = require('./mixin');
 
@@ -15,0 +7,0 @@ exports.bootstrap = function bootstrap(...args) {

lib/runtime.js

 const define = require('mixinable');
 
-const { bindAll } = require('./util');
+exports.Mixin = require('./mixin');
 
-const { override } = define;
-
-exports.Mixin = class Mixin {
-  constructor(core, config) {
-    this.core = core;
-    this.config = config;
-    this.options = {};
-    bindAll(this);
-  }
-};
-
 exports.render = function render(...renderArgs) {
   return config => {
     const { mixins } = config;
-    const strategies = {
-      ...mixins.reduce(
-        (result, mixin) => ({ ...result, ...mixin.strategies }),
-        {}
-      ),
-      render: override,
-    };
+    const strategies = mixins.reduce(
+      (result, mixin) => ({ ...result, ...mixin.strategies }),
+      {}
+    );
     const createMixinable = define(strategies)(...mixins);
@@ -37,5 +23,5 @@ return (...callArgs) => {
       );
-      return core.render(...callArgs);
+      core.render(...callArgs);
     };
   };
 };

package.json

 {
   "name": "@untool/core",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "untool core",
@@ -5,0 +5,0 @@ "main": "lib/core.js",

README.md

@@ -1,1 +0,192 @@
-# Coming soon.
+# `@untool/core`
+
+[![npm](https://img.shields.io/npm/v/@untool%2Fcore.svg)](https://www.npmjs.com/package/@untool%2Fcore)
+
+`@untool/core` is the functional foundation every other `untool` component is built upon. It contains a comprehensive configuration engine and a mixin base class.
+
+### Installation
+
+```bash
+$ yarn add @untool/core # OR npm install @untool/core
+```
+
+## Configuration
+
+Apart from a couple of very basic properties (`namespace`, `version` and `rootDir`), `@untool/core` does not provide configuration of its own. It does, however, provide an elaborate configuration mechanism.
+
+It allows you to set up mixins and pull in presets. Mixins provide extra functionality. Presets provide configuration defaults and often additionally include custom mixins. Read more about mixins and presets below.
+
+```json
+{
+  "mixins": ["@untool/yargs"],
+  "presets": ["@untool/express"]
+}
+```
+
+`@untool/core` comes with support for environment specific configuration. For example, you can pin [`@untool/express`](https://github.com/untool/untool/blob/master/packages/express/README.md)'s port to a specific value in production and have it search for a free port in develoment and test environments.
+
+```json
+{
+  "port": null,
+  "env": {
+    "production": {
+      "port": 12345
+    }
+  }
+}
+```
+
+You can even use placeholders everywhere throughout your configuration. Nested configuration structures will be flattened before being used for placeholder substitution.
+
+```json
+{
+  "foo": "foo",
+  "bar": {
+    "baz": "<foo>"
+  },
+  "qux": "<bar.baz>"
+}
+```
+
+`@untool/core` looks for configuration data in rather many places. It only uses the first config it finds, so make sure you do not have multiple configs lying around:
+
+* an `untool` property in your project's `package.json` file
+* an `.untoolrc` file in your project's root folder (JSON, YAML, or JS)
+* an `.untoolrc.{json,yaml,yml,js}` file in your project's root folder
+* an `untool.config.js` file in your project's root folder
+
+We strongly encourage organizing and publishing reusable bits of configuration as custom presets. You can even use any other `untool` project as a preset: just install it (e.g. `yarn add <git remote url>`) and add it to the `presets` section in your project's `untool` configuration.
+
+### Presets
+
+`untool` presets are JavaScript files or standard NPM modules. Presets can define or override arbitrary configuration properties, including mixins and other presets.
+
+Just as with your own project, presets can be written using JavaScript, JSON or YAML syntax. They are plain nested objects (or hashes) and they fully support the features outlined above: placeholders and environment specificity.
+
+##### JavaScript preset
+
+```javascript
+module.exports = {
+  foo: 'bar',
+  baz: {
+    quux: [23],
+  },
+};
+```
+
+##### JSON preset
+
+```json
+{
+  "foo": "bar",
+  "baz": {
+    "quux": [23]
+  }
+}
+```
+
+##### YAML preset
+
+```yaml
+foo: bar
+baz:
+  quux:
+    - 23
+```
+
+In preset packages, `@untool/core` will try to load a config from the same places as in your project and in addition, it will look in two more places:
+
+* a file defined in the `preset` property in the preset's `package.json` file
+* a `preset.js` file in the preset package's root folder
+
+If you want to not only override and extend config values, but rather provide actual features, you can include custom mixins directly in your preset. Some of `untool`'s default presets do just that.
+
+### Mixins
+
+Mixins are the primary mechanism in `untool` to extend and alter its features and behaviour. Using mixins, you can, for example, add your own Yargs commands, Express middlewares or React add-ons such as Redux.
+
+You can even build custom mixins that provide hooks for others to tap into, extending and altering their capabilities. There are three distinct types of mixins that are supported in `untool`: `core`, `browser` and `server`.
+
+`untool` uses a single config key for all three kinds of mixins: `mixins`. It expects an array of module path strings. `@untool/core` looks for mixins in the following places beneath those module paths:
+
+* a file defined in the `mixin:{core,server,browser}` property in the preset's `package.json` file
+* a file defined in the `mixin:runtime` property in the preset's `package.json` file (for `server`+`browser`)
+* a file defined in the `mixin` property in the preset's `package.json` file (for `core`+`server`+`browser`)
+* a `mixin.{core,server,browser}.js` file in the preset package's root folder
+* a `mixin.runtime.js` file in the preset package's root folder (for `server`+`browser`)
+* a `mixin.js` file in the preset package's root folder (for `core`+`server`+`browser`)
+
+By using this mechanism, you can use a single NPM module to provide all three types of mixins, one mixin each for build and runtime or even a single mixin used for all contexts.
+
+Every and all functionality in and around `untool` is expected to be organized in mixins. In `untool`, mixins are a bit special: they do not share state, i.e. they do not provide methods to a single 'host' object.
+
+Instead, they are based on a library called [`mixinable`](https://github.com/untool/mixinable). Their methods are, therefore, applied according to specific strategies: `override`, `parallel`, `sequence`, and `pipe` are some examples.
+
+If you create custom mixins that define additional mixin strategies, you probably want to call the appropriate methods yourself to allow others to, for example, modify your mixin's specific config.
+
+## API
+
+### `Mixin(core, config, [...args])`
+
+```javascript
+import { Mixin } from '@untool/core';
+
+class MyMixin extends Mixin {
+  myMethod() {}
+}
+
+export default MyMixin;
+```
+
+`Mixin` is a base class to build custom mixins upon. As such, it only provides a class constructor that accepts and handles a couple of arguments. You do not, however, usually instantiate your mixins - `@untool/core` does that for you if configured to use them.
+
+The `Mixin` constructor expects at least two arguments: `core`, a proxy object mimicking the mixin container and thus allowing you to call all defined mixin methods and `config`, the main configuration object. Both arguments are made available as homonymous instance properties.
+
+```javascript
+import { override } from 'mixinable';
+import { Mixin } from '@untool/core';
+
+class MyMixin extends Mixin {
+  constructor(core, config, ...args) {
+    super(core, config, ...args);
+  }
+  myMethod(...args) {
+    const { myHookMethod } = this.core;
+    return myHookMethod(...args);
+  }
+}
+
+MyMixin.strategies = {
+  myHookMethod: override,
+};
+
+export default MyMixin;
+```
+
+If inheriting from `Mixin`, all methods of your mixin are automatically bound to the repective instance, so you do not have to call `this.method.bind(this)` yourself even if you use them in asynchronous contexts.
+
+Note that you cannot call any of the methods of the core object from inside your mixin's custom `constructor` function: they only become available after all mixins have been instantiated.
+
+### `render([...args])` (runtime only)
+
+This function, that you are expected to call in your applications main entry file, is essentialy a shorthand: it creates and bootstraps a core mixin container and calls its `render` method.
+
+Whatever arguments it receives are being passed along to its container's mixins' constructors. For it to work, you need to register at least one mixin implementing the `render` method. The default render mixin is [`@untool/react`](https://github.com/untool/untool/blob/master/packages/react/README.md).
+
+Render mixins are expected to return functions from their render implementations: an [Express middleware](https://expressjs.com/en/guide/using-middleware.html) on the server or a function that bootstraps and starts a client side app in the browser.
+
+```javascript
+import React from 'react';
+import { render } from '@untool/core';
+export default render(<h1>hello world</h1>);
+```
+
+The render function serves two main purposes: 'universalifying' or 'isomorphizing' you application, i.e. making sure your app's code can run both on a server and in a browser, and integrating `untool`'s build and runtime environments.
+
+`Mixin` aside, `render` probably is the only part of `untool` you will directly interact with in your own code. It certainly is the only one of its APIs you will ever use within your application.
+
+### `bootstrap([...args])` (build only)
+
+This is a semi-private function that is mainly being used internally, for example by [`@untool/yargs`](https://github.com/untool/untool/blob/master/packages/yargs/README.md). It returns a proxy object mimicking the core mixin container and thus allowing you to call all defined mixin methods.
+
+You will only ever have to call it if you want to use `@untool/core` programmatically. Whatever arguments it receives are being passed along to the core container's mixins' constructors.

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 2 instances in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17007

increased by109.81%

Number of package files

8

increased by14.29%

Number of lines in readme file

193

increased by9550%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Lines of code

215

decreased by-6.52%

Number of low supply chain risk alerts

5

increased by66.67%

No dependency changes