Planner

Defined in: plan/planner.ts:222

Fluent builder for constructing execution plans.

Planner is a mutable, single-use builder. The typical workflow is:

1. Create a new Planner
2. Chain method calls to define the pipeline
3. Call compile() to produce an immutable Plan

Example

const plan = new Planner()
  .in(loadFile('config.json'))
  .mapIn(parseJson())
  .emit((out, $) => out
    .add('host', $.get('host').string())
    .add('port', $.get('port').number())
  )
  .compile()

const result = await run(plan, { readFile: fs.readFile })
// result.value: { host: string, port: number }

Type Parameters

In

In = never

Current input type flowing through the pipeline

Out

Out = { }

Current accumulated output type

Constructors

Constructor

new Planner<In, Out>(): Planner<In, Out>

Returns

Planner<In, Out>

Methods

compile()

compile(): Plan<Out>

Defined in: plan/planner.ts:437

Compile the planner into an immutable execution plan.

Must be called after at least one emit() to define the output. The returned Plan is immutable and can be executed multiple times.

Returns

Plan<Out>

Compiled Plan ready for execution

Throws

Error if called without emit() (no output defined)

Example

const plan = new Planner()
  .in(load({ name: 'test' }))
  .emit((out, $) => out.add('result', $.get('name').string()))
  .compile()

// Execute the plan
const result = await run(plan)

---

emit()

emit<B>(builder): Planner<In, B>

Defined in: plan/planner.ts:331

Declaratively emit values to the output using a builder pattern.

Multiple emit() calls can be chained to accumulate values from different inputs.

Type Parameters

B

B

Parameters

builder

(out, $) => EmitBuilder<B>

Returns

Planner<In, B>

Example

new Planner()
  .in(loadFile('config.json'))
  .mapIn(parseJson())
  .emit((out, $) => out
    .add('host', $.get('host').string())
    .add('port', $.get('port').number())
    .addLiteral('version', '1.0.0')
  )
  .in(loadFile('users.json'))
  .mapIn(parseJson())
  .emit((out, $) => out
    .add('users', $.get('data').array(u => u.get('name').string()))
  )
  .compile()

---

in()

Call Signature

in<T>(input): Planner<DataSpecProxy<T>, Out>

Defined in: plan/planner.ts:251

Define the input source for the pipeline.

Type Parameters

T

T

The type produced by this input

Parameters

input

DirectInput<T>

Input specification (FileInput, FilesInput, DirectInput, or SourcesInput)

Returns

Planner<DataSpecProxy<T>, Out>

This planner for chaining

Example

new Planner()
  .in(loadFile('data.json'))    // Load from file
  .in(load({ key: 'value' }))   // Or use inline data
  .in(sources({ a: load(1) })) // Or combine multiple sources

Call Signature

in<T>(input): Planner<SpecBuilder, Out>

Defined in: plan/planner.ts:252

Define the input source for the pipeline.

Type Parameters

T

T extends Record<string, unknown>

The type produced by this input

Parameters

input

SourcesInput<T>

Input specification (FileInput, FilesInput, DirectInput, or SourcesInput)

Returns

Planner<SpecBuilder, Out>

This planner for chaining

Example

new Planner()
  .in(loadFile('data.json'))    // Load from file
  .in(load({ key: 'value' }))   // Or use inline data
  .in(sources({ a: load(1) })) // Or combine multiple sources

Call Signature

in<T>(input): Planner<SpecBuilder, Out>

Defined in: plan/planner.ts:255

Define the input source for the pipeline.

Type Parameters

T

T

The type produced by this input

Parameters

input

Input<T>

Input specification (FileInput, FilesInput, DirectInput, or SourcesInput)

Returns

Planner<SpecBuilder, Out>

This planner for chaining

Example

new Planner()
  .in(loadFile('data.json'))    // Load from file
  .in(load({ key: 'value' }))   // Or use inline data
  .in(sources({ a: load(1) })) // Or combine multiple sources

---

mapIn()

Call Signature

mapIn<SB>(transform): Planner<SB, Out>

Defined in: plan/planner.ts:287

Apply a transform to the current input.

Type Parameters

SB

SB

Parameters

transform

TypedTransformAst<SB>

Transform AST specification

Returns

Planner<SB, Out>

This planner for chaining

Throws

Error if called before in()

Example

new Planner()
  .in(loadFile('data.json'))
  .mapIn(parseJson())  // Apply JSON parsing transform

Call Signature

mapIn(transform): Planner<SpecBuilder, Out>

Defined in: plan/planner.ts:288

Apply a transform to the current input.

Parameters

transform

TransformAst

Transform AST specification

Returns

Planner<SpecBuilder, Out>

This planner for chaining

Throws

Error if called before in()

Example

new Planner()
  .in(loadFile('data.json'))
  .mapIn(parseJson())  // Apply JSON parsing transform

---

mapOut()

mapOut<NewOut>(builder): Planner<In, NewOut>

Defined in: plan/planner.ts:383

Apply structural transformations to the output after extraction.

Each .mapOut() call adds a new AST node that transforms the accumulated output. Multiple .mapOut() calls chain sequentially.

Type Parameters

NewOut

NewOut = unknown

Parameters

builder

(out) => OutputTransformBuilder<NewOut>

Returns

Planner<In, NewOut>

Example

new Planner()
  .in(load({ items: [{cat: 'A', v: 1}, {cat: 'B', v: 2}] }))
  .emit((out, $) => out.add('items', $.get('items').array(i => ({
    kind: 'object',
    properties: { cat: i.get('cat').string(), v: i.get('v').number() }
  }))))
  .mapOut($ => $.groupBy(o => o.items, 'cat'))
  .compile()

---

merge()

static merge<T>(…plans): Plan<MergeOutputs<T>>

Defined in: plan/planner.ts:477

Merge multiple plans into a single plan with combined output. Later plans take precedence in case of key conflicts.

Type Parameters

T

T extends Plan<unknown>[]

Parameters

plans

…T

Returns

Plan<MergeOutputs<T>>

Example

const configPlan = new Planner()
  .in(load('config.json'))
  .mapIn(parseJson())
  .emit((out, $) => out.add('host', $.get('host').string()))
  .compile()

const usersPlan = new Planner()
  .in(load('users.json'))
  .mapIn(parseJson())
  .emit((out, $) => out.add('users', $.get('data').strings()))
  .compile()

const combined = Planner.merge(configPlan, usersPlan)
// Result type: { host: string } & { users: string[] }

---

mergeAs()

static mergeAs<T>(plans): Plan<{ [K in string | number | symbol]: T[K] extends Plan<O> ? O : never }>

Defined in: plan/planner.ts:493

Merge multiple plans with each plan’s output nested under a key.

Type Parameters

T

T extends Record<string, Plan<unknown>>

Parameters

plans

T

Returns

Plan<{ [K in string | number | symbol]: T[K] extends Plan<O> ? O : never }>

Example

const combined = Planner.mergeAs({
  config: configPlan,
  users: usersPlan,
})
// Result type: { config: { host: string }, users: { users: string[] } }