begat

📖

begat

Build families of composable project (re-)generators.

• Usage
  • pipeline
  • compose
• Types
  • Context
  • Generator
  • Options
• Standard library
  • begat/std/clone (generator)
  • begat/std/template (generator)
  • begat/std/aside (generator)
  • begat/std/diff
  • begat/std/write

Usage

pipeline

The happy path, presenting a series of dotchained functions, e.g.:

import * as begat from "begat"

begat
  .pipeline([ /* a pipeline of generator functions */ ])
  .withOptions({ /* the union of options for the composed generators */ })
  .then( /* apply the result using the regular promises API */ )

compose

Composes a pipeline of generators into... (you guessed it)...

(generators: Generator[]) => Generator

import * as begat from "begat"

const pipeline = begat.compose([ /* a pipeline of generator functions */ ])
const run = pipeline({ /* the union of options for the composed generators */ })

run( /* use the default context, or create one explicitly */ )
  .then( /* apply the result */ )

Types

Context

A chunk of state that gets passed down the pipeline of generators.

Notably includes a memfs volume.

Generator

(options?: Options) => Context => Promise<Context>

Takes some options, and does useful work to the passed context.

Basically a function that modifies a volume in some way.

Options

Options are whatever your generators collectively need them to be. The type of each generator is parameterised by the type of its individual options, and the options type of a composition of generators is the union of those options.

The intention is that options are reused within ecosystems of generators — i.e. you should design your generator's options in such a way that people you haven't met could write their own generators which extend yours in ways you hadn't considered.

Standard library

General-purpose generators and utilities, as a stepping-off point for building other generators.

begat/std/clone (generator)

Copies the contents of the current directory to the root of the volume.

A good first step in a generator pipeline which modifies an existing project.

begat/std/template (generator)

Renders eta templates (similar to ejs) to the output volume.

See the example workspaces for an example based on this generator.

begat/std/aside (generator)

(fn: (context: Context) => void) => Generator

Runs the passed function on a deep copy of the context. Useful for debugging pipelines, e.g.:

begat.compose([
  clone,
  buggyGenerator,
  aside(({ volume }) => console.log(volume.toJSON())),
  anotherGenerator,
])

begat/std/diff

Open your git difftool, comparing the state of the volume against your working directory.

import * as begat from "begat"
import { diff } from "begat/std/diff"

begat
  .pipeline([ ... ])
  .withOptions({ ... })
  .then(diff)

begat/std/write

Copy all files from the root of the volume into your working directory.

import * as begat from "begat"
import { write } from "begat/std/write"

begat
  .pipeline([ ... ])
  .withOptions({ ... })
  .then(write)