Collection.set ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Method of Collection · stable · since 2.0.0 · called as session.collection(name, options).set

ts
set(spec: CollectionSpec, options?: C & SignalOption): Promise<CollectionReport>;

Keyed reconcile to the whole spec (not a merge patch): items are added, changed in place or removed by key, including items that load() added. Outcome: one commit, look-only; replacing and in the write queue. New content loads hidden and swaps in one frame. Asset failures: problems. Timing: resolves at the commit point, after its loads. Errors: rejects HoloInputError on an invalid spec (validate('collection', spec) checks its shape, keys and parents; { dryRun: true } checks all this call checks and changes nothing). Asset failures are problems ('asset-failed', path the item's address, or the stage layer's for its stage, Problem.path).

Options ​

Through Session:

Option Type Default What it does
actor Actor the expectGroup's actor when one is given, else 'app' Who made the write.
dryRun boolean false Runs and reports, then rolls back by design ('dry-run').
expectGroup HistoryGroup undefined A guard, checked at the call: this write belongs to the undo group you are running.
expectRevision number undefined (no check) If-match on session.revision.
origin string null Your tag, echoed unchanged in Report.origin and cause.origin.
signal AbortSignal undefined Cancels this call; the member's JSDoc says what an abort does.
supersede boolean false (the write is queued behind the transaction and applies after it closes) While a transaction is open: roll it back (it resolves 'superseded'); the writes queued behind it apply in call order, then this one, which supersedes an…
undo 'rebase' | (string & {}) a recorded-state change gets one step labelled 'Change'; a look-only write gets none; the session's first model (cause 'load') gets none, whatever the label: it is the floor of history An undo label makes this write one undo step.

Through Tx:

Option Type Default What it does
signal AbortSignal undefined Cancels this call; the member's JSDoc says what an abort does.

Refused here (typed never, so passing one fails to compile): actor, checkpoint, dryRun, expectGroup, expectRevision, origin, supersede, undo.

Abort (signal) ​

This call is a write (SignalOption.signal, the kinds of call).

A write: before the commit point it rolls back and rejects AbortError; after it, no effect, except that a running camera move stops where the last frame drew it (CameraMoveOptions).

Through a tx the commit point is the transaction's: aborting a write still loading rejects AbortError and stages nothing (catch it: unobserved, it rolls the transaction back, spec section 6.1, O6); aborting one already staged unstages it, its paths keeping the latest other write to them as after a failed savepoint (O7), and its Promise stays resolved 'staged'.

Example ​

Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (examples/declaration/07-Collection.set.ts):

ts
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const postsX: readonly number[];                   // metres along the fence
const fence = session.collection('fence', { role: 'product', signal });
const r = await fence.set({ items: postsX.map((x, i) => ({
  key: `post-${i}`, kind: 'mesh' as const, meta: { segment: i },
  shape: { kind: 'cylinder' as const, radius: 0.04, height: 1.2 },
  at: { position: { x, y: 0.6, z: 0 } },
  material: { baseColor: '#6b4f3a', roughness: 0.8 },
})) });
console.log(r.added.length, r.updated.length, r.removed.length);   // item keys, by reconcile

Generic-API test (spec 3.1) ​

Rule Result
1. Neutral name pass: set names no product
2. A precedent pass: glTF 2.0 node hierarchy (row K1); Unity Object.Destroy (row K1)
3. Two apps, or labs pass: 28 apps (ledger: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508 and 20 more)
4. The cheaper fix first decided per need in Appendix B: rows K1 at tier stable (a member only where no rule, data, asset or app code serves the need)