@abw/badger 1.0.0

package/dist/badger.esm.js

@@ -0,0 +1,874 @@
+import process from 'node:process';
+import path from 'node:path';
+import { stat, readFile, writeFile, readdir, rm, mkdir, rmdir } from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+/**
+ * Determines if a value is a string
+ * @param {String} value - value to test
+ * @return {Boolean} true if `value` is a string or false if not
+ */
+function isString(value) {
+  return typeof value === 'string';
+}
+
+/**
+ * Determines if a value is an array
+ * @param {Array} value - value to test
+ * @return {Boolean} true if `value` is an Array or false if not
+ */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
+/**
+ * Determines if a value is a Function
+ * @param {Function} value - value to test
+ * @return {Boolean} true if `value` is a Function or false if not
+ */
+function isFunction(value) {
+  return typeof value === 'function'
+}
+
+/**
+ * Determines if a value is an Object (but not an Array)
+ * @param {Object} value - value to test
+ * @return {Boolean} true if `value` is an Object or false if not
+ */
+function isObject(value) {
+  return typeof value === "object"
+    && ! isArray(value)
+    && ! isNull(value);
+}
+
+/**
+ * Determines if a value is `undefined`
+ * @param {any} value - value to test
+ * @return {Boolean} true if `value` is `undefined` or false if not
+ */
+function isUndefined(value) {
+  return typeof value === 'undefined';
+}
+
+/**
+ * Determines if a value is `null`
+ * @param {any} value - value to test
+ * @return {Boolean} true if `value` is `null` or false if not
+ */
+function isNull(value) {
+  return value === null;
+}
+
+/**
+ * Determines if a value is defined and not null
+ * @param {any} value - value to test
+ * @return {Boolean} true if `value` is not `undefined` or `null`
+ */
+function hasValue(value) {
+  return ! (isUndefined(value) || isNull(value));
+}
+
+/**
+ * Determines if all values are defined and not null
+ * @param {any[]} values - values to test
+ * @return {Boolean} true if all values are not `undefined` or `null`
+ */
+function haveValue(...values) {
+  return values.every( value => hasValue(value) );
+}
+
+/**
+ * Determines if a value is undefined or null
+ * @param {any} value - value to test
+ * @return {Boolean} true if `value` is `undefined` or `null`
+ */
+function noValue(value) {
+  return ! hasValue(value);
+}
+
+/**
+ * Throws a new Error object
+ * @param {String[]} message - error message string(s)
+ * @throws {Error}
+ */
+function fail(...message) {
+  throw new Error(message.join(''));
+}
+
+/**
+ * Re-throw an existing Error object
+ * @param {Error} error - error object
+ * @throws {Error}
+ */
+function rethrow(error) {
+  throw error;
+}
+
+/**
+ * Do nothing.  Nothing at all.
+ */
+function doNothing() {
+  // speak again Cordelia
+}
+
+const ANSIStart  = '\u001B[';
+const ANSIEnd    = 'm';
+const ANSIColors = {
+  reset:    0,
+  bold:     1,
+  bright:   1,
+  dark:     2,
+  black:    0,
+  red:      1,
+  green:    2,
+  yellow:   3,
+  blue:     4,
+  magenta:  5,
+  cyan:     6,
+  grey:     7,
+  white:    8,
+  fg:      30,
+  bg:      40,
+};
+
+const escapeCode = (str, base=0) => {
+  let   codes = [ ];
+  let   pair  = str.split(/ /, 2);
+  const hue   = pair.pop();
+  const code  = (base ? ANSIColors[base] : 0) + ANSIColors[hue];
+  codes.push(code);
+  if (pair.length) {
+    const shade = pair.length ? pair.shift() : 'dark';
+    codes.push(ANSIColors[shade]);
+  }
+  return ANSIStart + codes.join(';') + ANSIEnd;
+};
+
+const escape = (c={}) => {
+  // color c can be specified as a string (e.g. 'red') which is shorthand
+  // for an object containing 'fg' (e.g. { fg: 'red' }) and/or 'bg' for
+  // foreground and background colors respectively
+  const col = isObject(c) ? c : { fg: c };
+  let escapes = [ ];
+  if (col.bg) {
+    escapes.push(escapeCode(col.bg, 'bg'));
+  }
+  if (col.fg) {
+    escapes.push(escapeCode(col.fg, 'fg'));
+  }
+  return escapes.join('');
+};
+
+const reset = () => escapeCode('reset');
+
+/**
+ * Returns a debugging function which is enabled by the first `enabled` argument.
+ * If this is `false` then it returns a function which does nothing.  If it is
+ * true then it returns a function that forwards all arguments to `console.log`.
+ * An optional `prefix` be be specified to prefix each debugging line.  The
+ * optional third argument `color` can be used to specify a color for the prefix.
+ * @param {Boolean} enabled - is debugging enabled?
+ * @param {String} [prefix] - optional prefix for debugging messages
+ * @param {String|Object} [color] - a color name or object (see {@link Badger/Utils/Color})
+ * @param {String} [color.fg] - foreground color
+ * @param {String} [color.bg] - background color
+ * @return {Function} a debugging function
+ * @example
+ * const debug = Debugger(true)
+ * @example
+ * const debug = Debugger(true, 'Debug > ')
+ * @example
+ * const debug = Debugger(true, 'Debug > ', 'blue')
+ * @example
+ * const debug = Debugger(true, 'Debug > ', { bg: 'blue', fg: 'bright yellow' })
+ */
+function Debugger(enabled, prefix='', color) {
+  return enabled
+    ? prefix
+      ? (format, ...args) =>
+        console.log(
+          '%s' + prefix + '%s' + format,
+          color ? escape(color) : '',
+          reset(),
+          ...args,
+        )
+      : console.log.bind(console)
+    : doNothing;
+}
+
+/**
+ * Creates a debugging function via {@link Debugger} and attaches it to the object
+ * passed as the first argument as the `debug` function.
+ * @param {Object} obj - the object to receive the `debug` function
+ * @param {Boolean} enabled - is debugging enabled?
+ * @param {String} [prefix] - optional prefix for debugging messages
+ * @param {String|Object} [color] - a color name or object (see {@link Badger/Utils/Color})
+ * @param {String} [color.fg] - foreground color
+ * @param {String} [color.bg] - background color
+ * @example
+ * const debug = addDebug(myObject, true)
+ * @example
+ * const debug = addDebug(myObject, true, 'Debug > ')
+ * @example
+ * const debug = addDebug(myObject, true, 'Debug > ', 'blue')
+ * @example
+ * const debug = addDebug(myObject, true, 'Debug > ', { bg: 'blue', fg: 'bright yellow' })
+ */
+function addDebug(obj, enabled, prefix='', color) {
+  obj.debug = Debugger(enabled, prefix, color);
+}
+
+const defaultOptions = {
+  encoding: 'utf8'
+};
+
+class Path {
+  constructor(path, options={}) {
+    // allow path/file/directory to be constructed from an existing object
+    if (path instanceof Path) {
+      path = path.path();
+    }
+    this.state = { path, options: { ...defaultOptions, ...options } };
+    addDebug(this, options.debug, options.debugPrefix || 'Path', options.debugColor);
+  }
+  path() {
+    return this.state.path;
+  }
+  relativePath(...parts) {
+    return path.join(this.state.path, ...parts);
+  }
+  options(options={}) {
+    return { ...this.state.options, ...options };
+  }
+  async exists() {
+    try {
+      await this.stat();
+      return true;
+    }
+    catch (error) {
+      return error.code === 'ENOENT'
+        ? false
+        : rethrow(error);
+    }
+  }
+  async stat() {
+    const stats = await stat(this.state.path);
+    return this.state.stats = stats;
+  }
+  unstat() {
+    this.state.stats = undefined;
+    console.log('XXX unstat: ', this.state.stats);
+    return this;
+  }
+}
+
+/**
+ * Function to encode JSON
+ * @param {Object} data - The data to encode as JSON text
+ * @return {String} a JSON encoded string
+ * @example
+ * encode({ message: 'Hello World' })
+ */
+const encode = data => JSON.stringify(data);
+
+/**
+ * Function to decode JSON
+ * @param {String} text - The JSON text to decode
+ * @return {Object|Array} the decoded object or array
+ * @example
+ * decode("{ message: 'Hello World' }")
+ */
+const decode = text => JSON.parse(text);
+
+/**
+ * An object containing the JSON `encode` and `decode` functions
+ */
+const codec = { encode, decode };
+
+// simple wrapper around JSON load/dump
+
+/**
+ * Function to encode YAML
+ * @param {Object} data - The data to encode as YAML text
+ * @return {String} a YAML encoded string
+ * @example
+ * encode({ message: 'Hello World' })
+ */
+const encode$1 = data => yaml.dump(data);
+
+/**
+ * Function to decode YAML
+ * @param {String} text - The YAML text to decode
+ * @return {Object|Array} the decoded object or array
+ * @example
+ * decode("message: Hello World")
+ */
+const decode$1 = text => yaml.load(text);
+
+/**
+ * An object containing the YAML `encode` and `decode` functions
+ */
+const codec$1 = { encode: encode$1, decode: decode$1 };
+
+/**
+ * Codecs provide a consistent encode()/decode() interface for serialising
+ * and de-serialising data.  This standard naming convention makes it possible
+ * for the ../Filesystem/File.js module to support a "codec" option for
+ * files. When this option is set the file.read() and file.write() methods
+ * automatically handle the translation to and from the serialised format
+ * using a codec object returned by the codec() function below.  The codec
+ * name can be specified in any case, e.g. "Yaml", "YAML", "yaml", "YaML",
+ * etc., and it will be converted to lower case.
+ */
+
+/**
+ * Lookup table for codecs
+ */
+const codecs = {
+  json: codec, yaml: codec$1
+};
+
+/**
+ * Function to fetch a codec
+ * @param {string} name - The title of the code, in any case, e.g. "yaml", "YAML", "Yaml"
+ */
+const codec$2 = name => codecs[
+  name.toLowerCase()
+];
+
+class File extends Path {
+  /**
+   * Returns a new {@link Directory} object for the parent directory of the file
+   * @param {Object} [options] - directory configuration options
+   * @param {Boolean} [options.codec] - codec for encoding/decoding file data
+   * @return {Object} a {@link Directory} object for the parent
+   */
+  directory(options) {
+    return dir(path.dirname(this.state.path), options);
+  }
+
+  /**
+   * An alias for the {@link directory} method for lazy people
+   * @return {Object} the parent {@link Directory} object
+   */
+  dir(...args) {
+    return this.directory(...args);
+  }
+
+  /**
+   * Reads the file content.  If a `codec` has been specified then the content is decoded.
+   * @param {Object} [options] - directory configuration options
+   * @param {Boolean} [options.codec] - codec for encoding/decoding file data
+   * @return {String|Object} the file content
+   * @example
+   * const text = file('myfile.txt').read();
+   * @example
+   * const data = file('myfile.json', { codec: 'json' }).read();
+   * @example
+   * const data = file('myfile.json').read({ codec: 'json' });
+   */
+  read(options) {
+    const opts = this.options(options);
+    const file = readFile(this.state.path, opts);
+    return opts.codec
+      ? file.then(text => codec$2(opts.codec).decode(text))
+      : file;
+  }
+
+  /**
+   * Writes the file content.  If a `codec` has been specified then the content will be encoded.
+   * @param {String|Object} data - directory configuration options
+   * @param {Object} [options] - directory configuration options
+   * @param {Boolean} [options.codec] - codec for encoding/decoding file data
+   * @example
+   * file('myfile.txt').write('Hello World');
+   * @example
+   * file('myfile.json', { codec: 'json' }).write({ message: 'Hello World' });
+   * @example
+   * file('myfile.json').write({ message: 'Hello World' }, { codec: 'json' });
+   */
+  write(data, options) {
+    const opts = this.options(options);
+    const text = opts.codec
+      ? codec$2(opts.codec).encode(data)
+      : data;
+    return writeFile(this.state.path, text, opts).then( () => this );
+  }
+}
+
+/**
+ * Function to create a new {@link File} object for a file
+ * @param {String} path - file path
+ * @param {Object} [options] - configuration options
+ * @param {Boolean} [options.codec] - a codec for encoding/decoding files
+ * @return {Object} the {@link File} object
+ */
+const file = (path, options) => {
+  return new File(path, options);
+};
+
+class Directory extends Path {
+  /**
+   * Fetch a new {@link File} object for a file in the directory.
+   * @param {string} path - file path
+   * @param {Object} [options] - file configuration options
+   * @param {String} [options.codec] - codec for encoding/decoding file data
+   * @return {Object} the {@link File} object
+   */
+  file(path, options) {
+    this.debug("file(%s, %o)", path, options);
+    return file(this.relativePath(path), this.options(options));
+  }
+
+  /**
+   * Fetch a new {@link Directory} object for a sub-directory in the directory.
+   * @param {string} path - directory path
+   * @param {Object} [options] - directory configuration options
+   * @param {String} [options.codec] - codec for encoding/decoding file data
+   * @return {Object} the {@link Directory} object
+   */
+  directory(path, options) {
+    this.debug("directory(%s, %o)", path, options);
+    return dir(this.relativePath(path), this.options(options));
+  }
+
+  /**
+   * An alias for the {@link directory} method for lazy people
+   * @return {Object} the {@link Directory} object
+   */
+  dir(path, options) {
+    this.debug("dir(%s, %o)", path, options);
+    return this.directory(path, options);
+  }
+
+  /**
+   * Returns a new {@link Directory} object for the parent directory
+   * @param {Object} [options] - directory configuration options
+   * @param {Boolean} [options.codec] - codec for encoding/decoding file data
+   * @return {Object} a {@link Directory} object for the parent
+   */
+  parent(options) {
+    this.debug("parent()");
+    return this.directory('..', options);
+  }
+
+  /**
+   * Returns the names of the files and sub-directories in the directory
+   * @return {Promise} fulfills with an array of the file and directory names
+   */
+  async read() {
+    this.debug("read()");
+    return await readdir(this.path());
+  }
+
+  /**
+   * Determines if the directory is empty.
+   * @return {Promise} fulfills with a boolean value true (empty) or false (not empty).
+   */
+  async isEmpty() {
+    this.debug("isEmpty()");
+    const entries = await this.read();
+    return entries.length === 0;
+  }
+
+  /**
+   * Determines if the directory is not empty.
+   * @return {Promise} fulfills with a boolean value true (not empty) or false (empty).
+   */
+  async notEmpty() {
+    this.debug("notEmpty()");
+    const empty = await this.isEmpty();
+    return !empty;
+  }
+
+  /**
+   * Empty the directory.
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.force] - force removal of files and directories
+   * @param {Boolean} [options.recursive] - recursively empty and delete sub-directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  async empty(options={}) {
+    this.debug("empty(%o)", options);
+    if (await this.exists() && await this.notEmpty()) {
+      await rm(this.path(), options);
+    }
+    return this;
+  }
+
+  /**
+   * Make the directory.
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.recursive] - create intermediate directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  async mkdir(options={}) {
+    this.debug("mkdir(%o)", options);
+    const exists = await this.exists();
+    if (! exists) {
+      await mkdir(this.path(), options);
+    }
+    return this;
+  }
+
+  /**
+   * Remove the directory.
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.empty] - delete items in directory
+   * @param {Boolean} [options.force] - force delete files and directories
+   * @param {Boolean} [options.recursive] - recursively delete sub-directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  async rmdir(options={}) {
+    this.debug("rmdir(%o)", options);
+    if (options.empty) {
+      await this.empty(options);
+    }
+    if (await this.exists()) {
+      await rmdir(this.path());
+    }
+    return this;
+  }
+
+  /**
+   * Create the directory and any intermediate directories.
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.recursive=true] - recursively create intermediate directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  create(options={ recursive: true }) {
+    this.debug("create(%o)", options);
+    return this.mkdir(options);
+  }
+
+  /**
+   * Empty and delete the directory.
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.empty=true] - empty directory of any files and sub-directories
+   * @param {Boolean} [options.recursive=true] - recursively delete sub-directories
+   * @param {Boolean} [options.force=true] - force deletion of files and sub-directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  destroy(options={ empty: true, recursive: true, force: true }) {
+    this.debug("destroy(%o)", options);
+    return this.rmdir(options);
+  }
+
+  /**
+   * Assert that a directory exists and optionally create it
+   * @param {Object} [options] - configuration options
+   * @param {Boolean} [options.create] - create the directory and any intermediate directories if it doesn't exist - equivalent to adding `mkdir` and `recursive` options or calling {@link create}
+   * @param {Boolean} [options.mkdir] - create the directory, add the `recursive` option to create intermediate directories - equivalent to calling {@link mkdir}
+   * @param {Boolean} [options.recursive] - when used with `mkdir`, creates any intermediate directories
+   * @return {Promise} fulfills to the {@link Directory} object
+   */
+  async mustExist(options={}) {
+    this.debug("mustExist(%o)", options);
+    if (await this.exists()) {
+      return this;
+    }
+    if (options.mkdir) {
+      return this.mkdir(options);
+    }
+    if (options.create) {
+      return this.create();
+    }
+    fail("Directory does not exist: ", this.path());
+  }
+}
+
+/**
+ * Function to create a new {@link Directory} object
+ * @param {string} path - directory path
+ * @param {Object} [options] - configuration options
+ * @param {Boolean} [options.codec] - a codec for encoding/decoding files
+ * @return {Object} the {@link Directory} object
+ */
+const dir = (path, options) => {
+  return new Directory(path, options);
+};
+
+/**
+ * Function to create a new {@link Directory} object for the current working directory
+ * @param {Object} [options] - configuration options
+ * @param {Boolean} [options.codec] - a codec for encoding/decoding files
+ * @return {Object} the {@link Directory} object
+ */
+const cwd = options => {
+  return dir(process.cwd(), options);
+};
+
+/**
+ * Function to create a new {@link Directory} object for the directory of a JS source file
+ * @param {string} url - module url - from `import.meta.url`
+ * @param {Object} [options] - configuration options
+ * @param {Boolean} [options.codec] - a codec for encoding/decoding files
+ * @return {Object} the {@link Directory} object
+ */
+const bin = (url, options) => {
+  return dir(
+    path.dirname(url.replace(/^file:\/\//, '')),
+    options
+  );
+};
+
+/**
+ * Split a comma/whitespace delimited string into an Array
+ * @param {String} [value] - string to split
+ * @return {Array} array of split strings
+ * @example
+ * const strings = splitList('one two three')
+ * @example
+ * const strings = splitList('one,two,three')
+ * @example
+ * const strings = splitList('one, two, three')
+ */
+function splitList(value) {
+  return isString(value)
+    ? value.split(/,\s*|\s+/)
+    : isArray(value)
+      ? value
+      : [value];
+}
+
+/**
+ * Join an Array into a single string
+ * @param {Array} [array] - array to join
+ * @param {String} [joint=' '] - delimiter to join strings
+ * @param {String} [lastJoint=joint] - delimiter for final item
+ * @return {String} joined string
+ * @example
+ * joinList(['one', 'two', 'three']);   // one two three
+ * @example
+ * joinList(['one', 'two', 'three'], ', ');   // one, two, three
+ * @example
+ * joinList(['one', 'two', 'three'], ', ', ' and ');   // one, two and three
+ */
+function joinList(array, joint=' ', lastJoint=joint) {
+  let copy = [...array];
+  const last = copy.pop();
+  return copy.length
+    ? [copy.join(joint), last].join(lastJoint)
+    : last;
+}
+
+/**
+ * Join an Array into a single string using commas for delimiters and ` and ` for the final item
+ * @param {Array} [array] - array to join
+ * @param {String} [joint=', '] - delimiter to join strings
+ * @param {String} [lastJoint=' and '] - delimiter for final item
+ * @return {String} joined string
+ * @example
+ * joinListAnd(['one', 'two', 'three']);   // one, two and three
+ */
+function joinListAnd(array, joint=', ', lastJoint=' and ') {
+  return joinList(array, joint, lastJoint);
+}
+
+/**
+ * Join an Array into a single string using commas for delimiters and ` or ` for the final item
+ * @param {Array} [array] - array to join
+ * @param {String} [joint=', '] - delimiter to join strings
+ * @param {String} [lastJoint=' or '] - delimiter for final item
+ * @return {String} joined string
+ * @example
+ * joinListOr(['one', 'two', 'three']);   // one, two or three
+ */
+function joinListOr(array, joint=', ', lastJoint=' or ') {
+  return joinList(array, joint, lastJoint);
+}
+
+/**
+ * Capitalise a string by converting the first character to upper case and other characters to lower case
+ * @param {String} [word] - word to capitalise
+ * @return {String} capitalised string
+ * @example
+ * capitalise('badger');   // Badger
+ * @example
+ * capitalise('BADGER');   // Badger
+ */
+function capitalise(word) {
+  return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+}
+
+/**
+ * Convert a snake case string to studly caps
+ * @param {String} [snake] - word to capitalise
+ * @return {String} capitalised string
+ * @example
+ * snakeToStudly('happy_badger_dance');   // HappyBadgerDance
+ * @example
+ * snakeToStudly('happy_badger/dance');   // HappyBadger/Dance
+ */
+function snakeToStudly(snake) {
+  return snake.split('/').map(
+    // each segment can be like foo_bar which we convert to FooBar
+    segment => segment.split('_').map(capitalise).join('')
+  ).join('/');
+}
+
+/**
+ * Convert a snake case string to camel case
+ * @param {String} [snake] - word to capitalise
+ * @return {String} capitalised string
+ * @example
+ * snakeToCamel('happy_badger_dance');   // happyBadgerDance
+ * @example
+ * snakeToCamel('happy_badger/dance');   // happyBadger/dance
+ */
+function snakeToCamel(snake) {
+  return snake.split('/').map(
+    // each segment can be like foo_bar which we convert to FooBar
+    segment => segment.split('_').map((i, n) => n ? capitalise(i) : i).join('')
+  ).join('/');
+}
+
+/**
+ * Assert that a parameter object contains an item with a defined/non-null value
+ * @param {Object} params={} - parameters object
+ * @param {String} name - parameter that must be included
+ * @return {any} the parameter value
+ * @throws {Error} if the parameter is not defined or null
+ * @example
+ * const foo = requiredParam({ foo: 10 }, 'foo');
+ */
+function requiredParam(params={}, name) {
+  const value = params[name];
+  if (hasValue(value)) {
+    return value;
+  }
+  else {
+    fail("Missing value for required parameter: ", name);
+  }
+}
+
+/**
+ * Assert that a parameter object contains all specified item with a defined/non-null value
+ * @param {Object} params={} - parameters object
+ * @param {Array|String} names - parameters that must be included, as an Array or whitespace/comma delimited string (see {@link splitList})
+ * @return {Array} the parameter values
+ * @throws {Error} if any parameter is not defined or null
+ * @example
+ * const [foo, bar] = requiredParams({ foo: 10, bar: 20 }, 'foo bar');
+ */
+function requiredParams(params={}, names) {
+  return splitList(names).map( name => requiredParam(params, name) );
+}
+
+/**
+ * An alias for {@link requiredParams} for people who don't like typing long names (and for symmetry with {@link anyParams}))
+ */
+const allParams=requiredParams;
+
+/**
+ * Assert that a parameter object contains any of the specified items with a defined/non-null value
+ * @param {Object} params={} - parameters object
+ * @param {Array|String} names - parameters of which at least one must be included, as an Array or whitespace/comma delimited string (see {@link splitList})
+ * @return {Array} the parameter values
+ * @throws {Error} if any parameter is not defined or null
+ * @example
+ * const [foo, bar] = anyParams({ foo: 10, wiz: 99 }, 'foo bar');
+ */
+function anyParams(params, names) {
+  let found = false;
+  const nlist  = splitList(names);
+  const values = nlist.map(
+    name => {
+      const value = params[name];
+      if (hasValue(value)) {
+        found = true;
+      }
+      return value;
+    }
+  );
+  return found
+    ? values
+    : fail("Missing value for one of: ", joinListOr(nlist));
+}
+
+const defaults = {
+  codecs: 'yaml json',
+};
+
+class Config {
+  constructor(params={}) {
+    const options = { ...defaults, ...params };
+    const [rootDir] = allParams(options, 'dir');
+    const [codec, codecs] = anyParams(options, 'codec codecs');
+
+    this.state = {
+      dir:    dir(rootDir),
+      codecs: splitList(codecs) || [codec],
+    };
+
+    addDebug(this, options.debug, options.debugPrefix, options.debugColor);
+    this.debug('root dir: ', this.state.dir.path());
+    this.debug('codecs: ', this.state.codecs);
+  }
+  async file(uri) {
+    for (let codec of this.state.codecs) {
+      const path = uri + '.' + codec;
+      const file = this.state.dir.file(path, { codec });
+      this.debug('looking for config file: ', file.path());
+      if (await file.exists()) {
+        this.debug('config file exists: ', file.path());
+        return file;
+      }
+    }
+    return undefined;
+  }
+  async config(uri, defaults) {
+    const file = await this.file(uri);
+    return file
+      ? await file.read()
+      : (defaults || fail("No configuration file for " + uri))
+  }
+}
+
+const config = options => new Config(options);
+
+const defaults$1 = {
+  config: {
+    dir: 'config',
+  }
+};
+class Workspace {
+  constructor(props={}) {
+    const rootDir = dir(requiredParam(props, 'dir'));
+    const cfgDir  = rootDir.dir(props.config?.dir || defaults$1.config.dir);
+    const cfgOpts = { ...defaults$1.config, ...(props.config||{}), dir: cfgDir };
+    const cfgObj  = config(cfgOpts);
+
+    this.state = {
+      rootDir:   rootDir,
+      configDir: cfgDir,
+      config:    cfgObj
+    };
+
+    addDebug(this, props.debug, props.debugPrefix, props.debugColor);
+    this.debug('root dir: ', rootDir.path());
+    this.debug('config dir: ', cfgDir.path());
+  }
+  dir(path, options) {
+    this.debug("dir(%s, %o)", path, options);
+    return hasValue(path)
+      ? this.state.rootDir(path, options)
+      : this.state.rootDir;
+  }
+  configDir(path, options) {
+    this.debug("configDir(%s, %o)", path, options);
+    return hasValue(path)
+      ? this.state.configDir(path, options)
+      : this.state.configDir;
+  }
+  config(uri, defaults) {
+    this.debug("config(%s, %o)", uri, defaults);
+    return hasValue(uri)
+      ? this.state.config.config(uri, defaults)
+      : this.state.config;
+  }
+}
+
+const workspace = props => new Workspace(props);
+
+export { Config, Path, Workspace, allParams, anyParams, bin, capitalise, codec$2 as codec, codecs, config, cwd, dir, doNothing, fail, file, hasValue, haveValue, isArray, isFunction, isNull, isObject, isString, isUndefined, joinList, joinListAnd, joinListOr, noValue, requiredParam, requiredParams, rethrow, snakeToCamel, snakeToStudly, splitList, workspace };