Interface: AffectedPreviewDto

@kortexya/reasoninglayer

---

@kortexya/reasoninglayer / AffectedPreviewDto

Interface: AffectedPreviewDto

Defined in: src/types/ui.ts:385

What a UI action’s program would do, answered by a dry run without running it.

Remarks

The same program preview OsfqlClient.preview answers, for the program the action would run: statements is that preview’s statements array, and the fields above it summarise it.

Read exact before showing count: count: 0, exact: false is “unknown”, never “nothing”. A program whose MATCH carries an inline destructive write always answers exact: false.

Example

const preview = (await client.ui.executeAction({ ...action, dryRun: true })).affectedPreview;
if (preview?.mutates) {
  console.log(preview.exact ? `${preview.count} rows` : `up to ${preview.count} rows`);
}

Properties

atomicRefusal?

optional atomicRefusal?: OsfqlAtomicRefusal | null

Defined in: src/types/ui.ts:428

Why the program would be refused before it runs, when it would be.

---

count

count: number

Defined in: src/types/ui.ts:394

How many rows the program would remove or rewrite: the sum of every statement’s affected.count in statements, nested statements included. A statement with no affected-row set (a read, an INSERT) adds nothing, and so does a statement the run refuses (its refusal). A refused top-level statement, or an atomic_refusal, makes the count 0: a UI action is all-or-nothing, so the run removes nothing.

---

exact

exact: boolean

Defined in: src/types/ui.ts:401

Whether count is the answer rather than an upper bound or a partial sum: false when any statement’s count is an upper bound (affected.exact: false) or could not be computed (affectedError), or when a nested statement the run would refuse may not run at all.

---

mutates

mutates: boolean

Defined in: src/types/ui.ts:407

Whether ANY statement of the program writes the store — an INSERT included, so a program whose RETRACT matches nothing still answers true when its INSERT writes.

---

sampleRows?

optional sampleRows?: Record<string, OsfqlValue>[]

Defined in: src/types/ui.ts:417

Up to 10 sample rows across the program’s statements, in statement order.

Remarks

Shaped exactly as OsfqlPreviewAffected.sampleRows: a term_id column naming the matched term, the features the statement’s pattern projected, and the sort’s @key features, each a tagged OsfqlValue. The keys are DATA and are left verbatim.

---

statement

statement: string

Defined in: src/types/ui.ts:424

The whole program that WOULD run, exactly as it would run.

---

statements

statements: OsfqlPreviewStatement[]

Defined in: src/types/ui.ts:426

The per-statement preview of that program, in document order.

---

unparsedSampleRows?

optional unparsedSampleRows?: number

Defined in: src/types/ui.ts:422

How many sample rows were dropped because a value in them did not match the published OsfqlValue contract. Absent when every row parsed.