@voltro/database 0.52.0 → 0.54.0

package/dist/index.d.ts

@@ -1987,6 +1987,30 @@ export declare const count: (alias?: string) => AggregateColumn;
 
 export declare const countDistinct: (column: string, alias?: string) => AggregateColumn;
 
+/**
+ * A whole collaborative DOCUMENT as a column — rich text, nested maps/arrays,
+ * whatever the CRDT backend's document model holds. `crdtText()` is the
+ * single-plain-text specialisation; this is the general form an editor
+ * binding (Tiptap over Yjs) edits.
+ *
+ * Storage, nullability and the authoritative server merge are IDENTICAL to
+ * `crdtText()` — the merge primitive (`Y.mergeUpdates`) is doc-agnostic, so
+ * the same write-path fold converges whole documents. What differs is intent
+ * and the exposure rules:
+ *
+ * - `.serverOnly()` THROWS at declaration (a doc clients write but never read
+ *   cannot be collaborated on);
+ * - `.encrypted()` is allowed but makes the column ONLINE-ONLY for
+ *   local-first purposes: the client mirror refuses to persist decrypted
+ *   content on the device (see `@voltro/local-first`), so offline editing of
+ *   an encrypted doc requires local encryption the framework does not ship.
+ *   Declare it deliberately.
+ *
+ * Anchors (stable positions for inline comments) come from
+ * `@voltro/local-first`'s `CrdtDocHandle.encodeAnchor`/`resolveAnchor`.
+ */
+export declare const crdtDoc: () => ColumnBuilder<Uint8Array | null, "bytes">;
+
 /**
  * The names of a table's CRDT-managed columns (`crdtText()`). These store an
  * encoded CRDT state as `bytes` and get an authoritative SERVER-SIDE merge on
@@ -1996,6 +2020,10 @@ export declare const countDistinct: (column: string, alias?: string) => Aggregat
  */
 export declare const crdtManagedColumns: (table: TableLike) => ReadonlyArray<string>;
 
+/** The `crdtText()`/`crdtDoc()` columns of a table — the set the server merge
+ *  folds and the capture paths (undo, row history) exclude. */
+export declare const crdtManagedColumnsOf: (table: TableLike) => ReadonlyArray<string>;
+
 /**
  * CRDT-managed text column — a field whose value is a CONFLICT-FREE replicated
  * text document rather than a plain string. Two clients editing it at the same
@@ -4325,12 +4353,26 @@ export declare interface MigrationStepContext {
 export declare const min: (column: string, alias?: string) => AggregateColumn;
 
 /**
- * The `conflictColumns` an upsert names that are absent from its payload. An
- * upsert keyed on a column the row doesn't set can't match a conflict target —
- * the dialect fails obscurely (or worse, inserts a duplicate). Naming it at the
- * call is the difference between a one-line fix and reading a driver error.
+ * The `conflictColumns` an upsert names that cannot match its conflict target.
+ * An upsert keyed on a column the row doesn't set can't match — the dialect
+ * fails obscurely (or worse, silently inserts a duplicate on every re-run).
+ * Naming it at the call is the difference between a one-line fix and reading a
+ * driver error.
+ *
+ * Takes the TABLE, exactly like `missingRequiredColumns` above, and for the
+ * same reason six lines up: a generated column (`generatedAs`) is DB-computed
+ * and takes no caller value — MariaDB/Postgres REJECT an explicit one, and the
+ * framework's own stamping STRIPS one — so for a generated conflict column,
+ * absence from the payload is the only correct state. The first version took
+ * only `(conflictColumns, row)` and therefore COULD NOT know: it refused every
+ * upsert keyed on a stored generated column, a condition nobody can satisfy.
+ * The very shape that makes such a unique work (folding NULLs to a constant so
+ * a composite unique can hold, e.g. `CASE WHEN ref IS NULL THEN 1 END`) is the
+ * shape it rejected. `undefined` table = the definition is not available; no
+ * column can be recognised as generated, so none is skipped — pass the table
+ * whenever you have one.
  */
-export declare const missingConflictColumns: (conflictColumns: ReadonlyArray<string>, row: Row) => ReadonlyArray<string>;
+export declare const missingConflictColumns: (table: TableLike | undefined, conflictColumns: ReadonlyArray<string>, row: Row) => ReadonlyArray<UnmatchableConflictColumn>;
 
 /**
  * Columns the row must carry but doesn't. Empty when the row is complete.
@@ -7522,6 +7564,17 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/** Why a conflict column cannot match its target — the two are different bugs
+ *  with different fixes, and one shared word ("missing") sent a reader hunting
+ *  for an absent field that was present-but-NULL. */
+export declare interface UnmatchableConflictColumn {
+    readonly column: string;
+    /** `absent` — not in the payload at all. `null` — present, but NULL, and
+     *  NULL never matches a unique conflict target: the write would always
+     *  INSERT. */
+    readonly reason: 'absent' | 'null';
+}
+
 /**
  * Remove ONE name this process added for a bounded operation.
  *