Muse

Bind data into anything

Overview

Muse is a CLI and toolchain for operating on data collected from json, yaml, toml, and markdown files.

Muse scans included files, parses them into data, and streams the loaded data through plugins.

Each plugin can modify the data as well as enact side effects such as writing files to disk.

Usage

Usage:
  muse [/path/to/binding.yaml] <options>

Options:
  --stdout    -s  Output final data to stdout
  --verbose,  -v  Enable verbose logging
  --help,     -h  Show this help message

Binding File

Each Muse project should specify a binding file with the following shape:

sources:                    # Optional
  - file: "**/*.yaml"
  - web: "https://example.com/data.json"
contentKey: "content"       # Optional
options:                    # Optional
  someOption: someValue
processors:
  - first-processor
  - second-processor

The binding file can be any of the supported file types for Muse and can be named anything. If the CLI is invoked with a directory instead of a file, Muse will look for a binding file in the directory with the following order:

1. binding.json
2. binding.yaml
3. binding.toml
4. binding.md

Markdown Files

Muse supports loading and parsing Markdown files with optional YAML frontmatter.

---
someKey: someValue
---

Your markdown content here

When loading markdown files, Muse will load the content of the file into a key called content by default. This can be changed in the binding configuration by setting a contentKey value as an override.

Plugin API

Muse plugins are written in TypeScript/JavaScript and expose information describing the plugin, as well as the functions to operate with:

export const name = "Plugin Name";
export const description = "Plugin Description";
export async function step(binding: Binding): Promise<Binding> {}

The main function of a plugin is step, which takes a Binding object and returns a modified Binding object.

When returning a new Binding object, it is best practice to make immutable changes:

export async function step(binding: Binding): Promise<Binding> {
  const newBinding = { ...binding };
  newBinding.options.someOption = "newValue";
  return {
    ...binding,
    meta: {
      ...binding.meta,
      customValue: true,
    }
  };
}