OperationBuilder

Fluent builder for composing, validating, and submitting WarmHub commit operations.

Use this when a caller needs to build a batch incrementally, run local preflight checks, optionally validate data against known shapes, and submit through the SDK stream-append path with continuation and retry options.

The builder is not a promise — there is no build() method, and await cb alone will not submit anything. Finalize the batch by calling await cb.commit({ client, orgName, repoName, ... }), which validates, submits, and seals the builder in one step. Reusing a sealed builder throws.

Example

const cb = new OperationBuilder();
cb
  .add({ name: "Sensor/temp-1", data: { location: "A" } })
  .revise({ name: "Sensor/temp-1", data: { location: "B" } });
const result = await cb.commit({ client, orgName: "acme", repoName: "world" });

See

https://docs.warmhub.ai/sdk/write-methods/

Constructors

Constructor

new OperationBuilder(options?): OperationBuilder

Create an empty operation builder.

Pass known shape definitions when you want local data validation before submitting operations.

Parameters

options?

OperationBuilderOptions

Returns

OperationBuilder

Accessors

operations

Get Signature

get operations(): readonly OperationBuilderOp[]

Return the queued operations.

The returned array is read-only; use add, revise, and retract to modify the builder.

Returns

readonly OperationBuilderOp[]

---

size

Get Signature

get size(): number

Return the number of queued operations.

Returns

number

Methods

add()

add(op): this

Add a shape, thing, assertion, or collection operation.

For things and assertions, names use Shape/localName. Supplying about makes the operation an assertion. Supplying collection type and members makes it a collection. Otherwise the builder infers kind from the name.

Set kind: 'thing' explicitly for hierarchical thing names that would otherwise look like assertion paths.

Parameters

op

Omit<AddOp, 'operation'> | AddOp

Returns

this

---

revise()

revise(op): this

Add a revise operation.

The target can be supplied as name or wref. When shape definitions were provided to the constructor, revise data is validated locally before the operation is queued.

Parameters

op

Omit<ReviseOp, 'operation'> | ReviseOp

Returns

this

---

retract()

retract(target): this

Add a retract operation.

Pass a wref string shorthand or an object with a target name, optional kind safety hint, and optional reason.

Parameters

target

string | { name: string; kind?: "shape" | "thing" | "assertion" | "collection"; reason?: string; leaseId?: string; }

Returns

this

---

has()

has(name): boolean

Return whether this builder has queued an add operation for a name.

Parameters

name

string

Returns

boolean

---

validate()

validate(): ValidationResult

Run client-side validation without contacting the server.

Validation checks for empty commits, duplicate adds, missing revise targets, revise-after-retract patterns, local shape-data errors when shapes were provided, and the same preflight diagnostics used before commit submission.

Returns a ValidationResult object ({ valid, errors, warnings }) — not a boolean. Read result.valid to gate submission, and iterate result.errors for blocking diagnostics or result.warnings for informational ones.

Returns

ValidationResult

Example

const cb = new OperationBuilder();
cb.add({ name: "Location/cave", data: { x: 0, y: 0 } });
const result = cb.validate();
if (!result.valid) {
  for (const err of result.errors) {
    console.error(`op ${err.operationIndex}: ${err.code} — ${err.message}`);
  }
  throw new Error("validation failed");
}
for (const warn of result.warnings) console.warn(warn.message);

---

commit()

commit(params): Promise<OperationSubmitResult>

Validate, submit, and seal the builder.

A successful call submits operations through the same stream path as client.commit.apply and makes the builder single-use. Validation failures throw before any server request is made. Ambiguous multi-chunk failures surface as PartialStreamSubmissionError; deterministic all-failed batches surface as AllStreamOperationsFailedError with per-op failure data.

Parameters

params

client

{ stream: { append(input: StreamAppendInput): Promise<StreamAppendResult>; }; }

WarmHub client or compatible stream client used for submission.

orgName

string

repoName

string

committer?

string

Optional wref identifying the actor on whose behalf the write is made.

message?

string

Optional commit message.

chunkSize?

number

Maximum operations per stream append.

streamId?

string

Advanced continuation hook for caller-managed streams.

allocatedTokens?

object[]

Advanced continuation hook for $N / #N token allocation state.

retry?

false | RetryPolicyOptions

Retry policy for transient first-chunk failures, or false to disable automatic retry.

Returns

Promise<OperationSubmitResult>