OperationBuilder
Fluent builder for v2 write operations. Get one with client.ops() (or
new OperationBuilder()), queue operations, then pass it to
client.commit.apply, commit.validate or commit.applyStreaming, or
call OperationBuilder.commit.
Every add and revise states its Shapes in exactly one way: shapes,
shapeless, or (revise only) keepShapes. Shape names are bare: a write
always certifies under each Shape’s head version. Anything else is refused
as it is queued, with a WriteOperationError (a WarmHubError with code
VALIDATION_ERROR and the operation’s index), before any request. A
whole-batch refusal (see OperationBuilder.commit) is a
WriteOperationError too, with no index.
Example
Section titled “Example”await client.commit.apply('org', 'repo', 'seed', client.ops() .add('acme', { shapes: ['Deal'], data: { company: 'Acme' } }))// keepShapes reads the committed Thing, so it cannot follow an add of the// same name in one submission: revise in a later request.await client.commit.apply('org', 'repo', 'update', client.ops() .revise('acme', { keepShapes: true, data: { company: 'Acme 2' } }))https://docs.warmhub.ai/sdk/write-methods/
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new OperationBuilder(
options?):OperationBuilder
Create an empty builder. Pass known Shape definitions to validate data locally as operations are queued.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”OperationBuilder
Accessors
Section titled “Accessors”operations
Section titled “operations”Get Signature
Section titled “Get Signature”get operations(): readonly
OperationBuilderOp[]
The queued operations, read-only.
Returns
Section titled “Returns”readonly OperationBuilderOp[]
Get Signature
Section titled “Get Signature”get size():
number
The number of queued operations.
Returns
Section titled “Returns”number
Methods
Section titled “Methods”add(
name,input):this
Queue an add of the Thing name. State its Shapes with shapes or
shapeless. A Shape itself is the Thing shapeName('X') with
shapes: [].
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”this
revise()
Section titled “revise()”revise(
name,input):this
Queue a revise of the Thing name. State its Shapes with shapes,
shapeless, or keepShapes (which reads the current set and version at
submit and sends the version as expectedVersion). keepShapes sends the
Shapes bare, so the revise re-certifies under each Shape’s head version.
keepShapes pins the version it read; a cross-process resubmit of the same submissionId can conflict; explicit shapes is the retry-safe form.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”this
retract()
Section titled “retract()”retract(
name,input?):this
Queue a retract of name.
Parameters
Section titled “Parameters”string
input?
Section titled “input?”RetractInput = {}
Returns
Section titled “Returns”this
restore()
Section titled “restore()”restore(
durableId,input?):this
Queue a restore of a retracted Thing, named by its durable ID: several retracted Things can share a name.
Parameters
Section titled “Parameters”durableId
Section titled “durableId”string
input?
Section titled “input?”RestoreInput = {}
Returns
Section titled “Returns”this
rename()
Section titled “rename()”rename(
name,newName):this
Queue a rename of name to newName, both full names. A Shape renames
to a Shape: rename(shapeName('A'), shapeName('B')).
Parameters
Section titled “Parameters”string
newName
Section titled “newName”string
Returns
Section titled “Returns”this
reaffirm()
Section titled “reaffirm()”reaffirm(
name,input):this
Queue a reaffirm: edit the assertion’s affirmation snapshot without
changing its data. add and remove compose in one operation.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”this
has(
name):boolean
Whether an add of name is queued.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”boolean
validate()
Section titled “validate()”validate():
ValidationResult
Check the batch as a whole without contacting the server: empty batches,
a name added twice, a revise after a retract. Returns
{ valid, errors, warnings }. Per-operation refusals already threw when
the operation was queued.
Returns
Section titled “Returns”commit()
Section titled “commit()”commit(
params):Promise<OperationSubmitResult>
Validate, submit, and seal the builder. Equivalent to passing the builder
to client.commit.apply, but single-use: a success or a
PartialStreamSubmissionError seals it.
Parameters
Section titled “Parameters”params
Section titled “params”client
Section titled “client”{ readonly clientFlags?: readonly string[]; stream: { append(input: StreamAppendInput): Promise<StreamAppendResult>; }; thing?: { getMany(orgName: string, repoName: string, wrefs: string[]): Promise<Pick<ThingGetManyResult, 'items' | 'missing'>>; }; }
WarmHub client or compatible stream client used for submission.
orgName
Section titled “orgName”string
repoName
Section titled “repoName”string
committer?
Section titled “committer?”string
Optional wref identifying the actor on whose behalf the write is made.
message?
Section titled “message?”string
Optional commit message.
chunkSize?
Section titled “chunkSize?”number
Maximum operations per stream append.
streamId?
Section titled “streamId?”string
Caller-managed stream identity for observability and diagnostic correlation.
submissionId?
Section titled “submissionId?”string
Caller-managed UUID shared by every chunk.
returnRepoSeq?
Section titled “returnRepoSeq?”boolean
Return the writer’s own repository-sequence acknowledgement.
retry?
Section titled “retry?”false | RetryPolicyOptions
Retry policy for transient first-chunk failures, or false to disable automatic retry.
Returns
Section titled “Returns”Promise<OperationSubmitResult>