# hullabaloo-config-manager Manages complex [Babel] config chains, avoiding duplicated work and enabling effective caching. > Hullabaloo: informal of "babel" (noun) > > A confused noise, typically that made by a number of voices: *the babel of voices on the road.* Use this package to resolve [Babel] config chains. The resulting options result in equivalent compilation behavior as if `babel-core` had resolved the config. A Node.js-compatible JavaScript module can be generated which exports a function that provides the options object, applicable for the current environment. This module can be written to disk and reused. Config sources and plugin and preset dependencies can be hashed and used as cache keys. The cache keys and generated module can be verified to avoid having to repeatedly resolve the config chains, and to be sure a previously transformation result can be reused. This module is used by [AVA]. ## Installation ```console $ npm install --save hullabaloo-config-manager ``` ## Usage ```js const configManager = require('hullabaloo-config-manager') ``` ## API ### `currentEnv(): string` Returns the current environment value, just like `babel-core` would determine it. ### `fromDirectory(dir: string, options?: {cache: Cache}): Promise` Asynchronously resolves config chains from the `dir` directory. If no config can be found the promise is resolved with `null`. Otherwise it is resolved with the [resulting config object](#resolvedconfig). The promise is rejected if [errors](#errors) occur. A `cache` object may be provided. ### `createConfig(options: {options: BabelOptions, source: string, dir?: string, hash?: string, json5?: false}): Config` Creates and returns an in-memory [config object](#config). The first argument must be provided, and it must have a valid [`options` object](#babeloptions) and `source` value. If the `dir` value is not provided it's derived from the `source` value. Dependencies are resolved relative to this `dir`. If the config source does not exist on disk the `hash` value should be provided, otherwise hashes cannot be created for the config. The `json5` property can be set to `false` if the `options` object can be serialized using `JSON.stringify()`. Note that the `options` object is cloned (deeply) before use. ### `fromConfig(baseConfig: Config, options?: {cache: Cache}): Promise` Asynchronously resolves config chains, starting with the `baseConfig`. The `baseConfig` must be created using the `createConfig()` method. The promise is resolved with the [resulting config object](#resolvedconfig). The promise is rejected if [errors](#errors) occur. A `cache` object may be provided. ### `restoreVerifier(buffer: Buffer): Verifier` Deserializes a [`Verifier`](#verifier). The `buffer` should be created using `Verifier#toBuffer()`. ### `prepareCache(): Cache` Creates a cache object that can be passed to the above functions. This may improve performance by avoiding repeatedly reading files from disk or computing hashes. --- ### `Config` Use `createConfig()` to create this object. #### `Config#extend(config: Config)` Extend the config with another config. Throws a `TypeError` if the config was created with an `extends` clause in its `options`. It throws an `Error` if it has already been extended. --- ### `BabelOptions` See . --- ### `ResolvedConfig` Returned by `fromConfig()` and `fromDirectory()`. #### `ResolvedConfig#generateModule(): string` Generates a Node.js-compatible JavaScript module which exports a `getOptions()` function. This function returns a unique options object, applicable for the current environment, that can be passed to `babel-core` methods. This module needs to evaluated before the `getOptions()` method can be accessed. #### `ResolvedConfig#createVerifier(): Promise` Asynchronously hashes plugin and preset dependencies of the resolved config, as well as config sources, and resolves the promise with a [`Verifier`](#verifier) object. --- ### `Verifier` Use `restoreVerifier()` or `ResolvedConfig#createVerifier()` to create this object. #### `Verifier#cacheKeysForCurrentEnv(): {dependencies: string, sources: string}` Synchronously returns cache keys for the plugin and preset dependencies, and config sources, that are applicable to the current environment. Use these values to cache the result of `babel-core` transforms. #### `Verifier#verifyCurrentEnv(fixedHashes?: {sources: {[source: string]: string}}, cache?: Cache): Promise<{badDependency: true} | {missingSource: true} | {sourcesChanged: true} | {cacheKeys: {dependencies: string, sources: string}, dependenciesChanged: boolean, sourcesChanged: false, verifier: Verifier}>` Asynchronously verifies whether the config is still valid for the current environment. Provide `fixedHashes` if the verifier was derived from a created config with a fixed `hash` value. A `cache` object may also be provided. The promise is resolved with an object describing the verification result: * If the object has a `badDependency` property then a plugin or preset dependency could not be hashed, presumably because it no longer exists. * If it has a `missingSource` property then a config source no longer exists. * If its `sourcesChanged` property is `true` then config sources have changed and the config is no longer valid. * If its `dependenciesChanged` property is `true` then plugin or preset dependencies have changed, but the config itself is still valid. The `verifier` property holds a new `Verifier` object which takes the new dependencies into account. The `cacheKeys` property contains the same result as calling `Verifier#cacheKeysForCurrentEnv()` on the returned `verifier`. * If its `sourcesChanged` and `dependenciesChanged` properties are both `false` then the config is valid and cache keys won't have changed. The `verifier` property holds the same `Verifier` object. The `cacheKeys` properties contains the same result as calling `Verifier#cacheKeysForCurrentEnv()`. #### `Verifier#toBuffer()` Serializes the verifier state into a `Buffer` object. Use `restoreVerifier()` to deserialize. --- ### Errors Error constructors are not publicly available, but errors can be identified by their `name` property. #### `BadDependencyError` Used when a plugin or preset dependency couldn't be resolved. The corresponding package or file name is available through the `source` property. There may be another error with more details, available through the `parent` property. #### `ExtendsError` Used when an `extends` clause points at a non-existent file. The config file that contains the clause is available through the `source` property. The clause itself is available through the `clause` property. Has a `parent` property that contains a `NoSourceFile` error. #### `InvalidFileError` Used when a config file is invalid. The file path is available through the `source` property. #### `NoSourceFileError` Used when a file does not exist. The file path is available through the `source` property. #### `ParseError` Used when a config file cannot be parsed (this is different from it being invalid). The file path is available through the `source` property. The parsing error is available through the `parent` property. [AVA]: https://ava.li/ [Babel]: https://babeljs.io/