Batch & chain

painter.batch runs independent canvas / image / text jobs with bounded concurrency and preserves input order in the returned Buffer[]. painter.chain runs named painter methods sequentially, passing the previous step’s Buffer into the next when you use the placeholder 'current' or { __isCurrentBuffer: true }.

Types: BatchOperation, ChainOperation, BatchChainAssetOpts (lib-next/types/batch.ts, lib-next/batch/batch-operations.ts).

#batch(operations, opts?)

1await painter.batch(2  operations: BatchOperation[],3  opts?: BatchChainAssetOpts4): Promise<Buffer[]>;

##Operation types

1const controller = new AbortController();2 3const [badge, label] = await painter.batch(4  [5    { type: 'canvas', config: { width: 120, height: 40, color: '#0f172a' } },6    {7      type: 'text',8      config: [{ text: 'Hi', x: 12, y: 26, font: { size: 18, family: 'Arial' } }],9    },10  ],11  {12    resolveAssetRefs: true,13    concurrency: 2,14    signal: controller.signal,15  }16);

##Failure semantics

batch is fail-fast at the Promise boundary: if an operation fails, the returned Promise rejects with the failing operation index/type. Results are not returned as a partial array. Work that already started may finish, but the scheduler stops taking new work after failure or cancellation is observed.

#chain(operations, opts?)

1await painter.chain(2  operations: ChainOperation[],3  opts?: BatchChainAssetOpts4): Promise<Buffer>;

Each step is { method: string; args: unknown[] }.

##Args, asset resolution, and cancellation

• 'current' or { __isCurrentBuffer: true } is replaced by the currentBuffer from the previous successful step. On the first step it is undefined unless you pass a real buffer yourself.
• With resolveAssetRefs: true, other arguments are resolved deeply through the shared asset resolver.
• signal is checked before the chain starts and between operations. Cancellation rejects rather than returning a partial result.
• concurrency is accepted by the shared option type for consistency but has no parallelizing effect on chain; chain execution is deliberately sequential.

##Return shape contract

Each step must resolve to a Buffer or { buffer: Buffer } such as CanvasResults. Anything else rejects the chain.

1const ribbon = await painter.chain([2  { method: 'createCanvas', args: [{ width: 400, height: 80, color: '#111827' }] },3  {4    method: 'path2d.draw',5    args: [6      'current',7      [8        { type: 'moveTo', x: 20, y: 40 },9        { type: 'lineTo', x: 380, y: 40 },10      ],11      { stroke: { color: '#f472b6', width: 4 } },12    ],13  },14]);

#Design notes

• batch supports the explicit canvas / image / text operation union. It is not an arbitrary-method dispatcher.
• chain is the sequential escape hatch for methods such as path2d.draw, pixel operations, and image operations that consume a previous buffer.
• Both surfaces use the central operation-count limits; batch concurrency is bounded by the central runtime configuration.
• Errors preserve the failing operation index and operation type/method through structured Apexify input errors.