Pipeline Definitions

A pipeline definition is the object returned by definePipeline(...). It ties together versions, sources, routes, and execution settings into one typed unit.

The core shape

import { definePipeline } from "@ucdjs/pipeline-core";

export const myPipeline = definePipeline({
  id: "my-pipeline",
  name: "My Pipeline",
  description: "Example pipeline definition",
  versions: ["1.0.0"],
  inputs: [mySource],
  routes: [myRoute],
  include: undefined,
  strict: false,
  concurrency: 4,
  fallback: undefined,
});

Key fields

id: stable pipeline identifier used by the CLI and executor
name: human-readable display name
description: optional summary shown in UIs and listings
versions: versions the pipeline can process
inputs: source definitions that provide files
routes: route definitions that parse and resolve those files
include: optional pipeline-wide file filter applied before route matching
strict: when true, unmatched files without a fallback are treated as errors
concurrency: maximum number of route executions processed in parallel
fallback: optional handler for unmatched files
tags: optional metadata for classification and tooling

DAG validation happens at definition time

When you call definePipeline(...), the core package builds the route DAG immediately from declared route dependencies.

If the dependency graph is invalid, pipeline creation fails early. That means authoring mistakes such as unknown route dependencies or dependency cycles surface before execution.

Example with multiple routes

export const dependentRoutesPipeline = definePipeline({
  id: "dependent-routes",
  name: "Dependent Routes",
  versions: ["1.0.0"],
  inputs: [colorsSource, sizesSource],
  routes: [colorsRoute, sizesAfterColorsRoute],
});

In that example, sizesAfterColorsRoute depends on colorsRoute, so the DAG forces the colors route to finish before the dependent route resolves.

fallback is for files that pass the pipeline-wide include filter but do not match any route. It has its own parser and resolver and is useful when you want a controlled catch-all instead of ignoring unmatched files.

Loading Pipelines

The loader discovers files matching **/*.ucd-pipeline.ts and imports any named exports that are real pipeline definitions.

That discovery model powers:

ucd pipelines list
ucd pipelines run
local and remote loading through @ucdjs/pipeline-loader

Definitions