lib0 1.0.0-rc.26 → 1.0.0-rc.28

package/dist/delta/delta.d.ts

@@ -39,7 +39,7 @@ export const $attribution: s.Schema<Attribution>;
  * @typedef {{ [key: string]: any }} Formats
  */
 /**
- * @typedef {{ id: string, key: number|string, assoc: 1|-1, attrs?: object }} MarkJSON
+ * @typedef {{ id: string, key: number|string, assoc: 1|-1, attrs?: object, transient?: boolean }} MarkJSON
  */
 /**
  * @typedef {{
@@ -423,7 +423,7 @@ export class SetAttrOp<V extends unknown = any, K extends string | number = any>
     get fingerprint(): string;
     toJSON(): {
         type: "insert";
-        value: V | DeltaJSON;
+        value: DeltaJSON | V;
     } & ({
         attribution: Attribution;
     } | {
@@ -549,13 +549,13 @@ export const $anyOp: s.Schema<DeleteOp<any> | TextOp | InsertOp<any> | ModifyOp<
 export const $setAttrOp: s.Schema<SetAttrOp<any>>;
 export const $modifyAttrOp: s.Schema<ModifyAttrOp<any>>;
 export const $deleteAttrOp: s.Schema<DeleteAttrOp<any>>;
-export const $anyAttrOp: s.Schema<ModifyAttrOp<any, string> | SetAttrOp<any, any> | DeleteAttrOp<any, string | number>>;
+export const $anyAttrOp: s.Schema<SetAttrOp<any, any> | DeleteAttrOp<any, string | number> | ModifyAttrOp<any, string>>;
 export function $setAttrOpWith<Content extends fingerprintTrait.Fingerprintable>($content: s.Schema<Content>): s.Schema<SetAttrOp<Content>>;
 export function $insertOpWith<Content extends fingerprintTrait.Fingerprintable>($content: s.Schema<Content>): s.Schema<InsertOp<Content>>;
 export function $modifyOpWith<Modify extends DeltaAny>($content: s.Schema<Modify>): s.Schema<ModifyOp<Modify>>;
 export function $modifyAttrOpWith<Modify extends DeltaAny>($content: s.Schema<Modify>): s.Schema<ModifyAttrOp<Modify>>;
 export const $mark: s.Schema<Mark>;
-export function createMark(key: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null): Mark;
+export function createMark(key: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null, transient?: boolean): Mark;
 /**
  * @template {DeltaConf} [Conf={}]
  * @extends {DeltaData<
@@ -745,9 +745,11 @@ export class DeltaBuilder<Conf extends DeltaConf = {}, FixedConf extends boolean
      *
      * @param {import('./position.js').Pos} pos
      * @param {string} [id]
+     * @param {boolean} [transient] flag the mark as never-to-be-stored (a one-shot mapping probe, see
+     * {@link Mark#transient} and {@link import('./position.js').mapPositionsA})
      * @return {this}
      */
-    addMark(pos: import("./position.js").Pos, id?: string): this;
+    addMark(pos: import("./position.js").Pos, id?: string, transient?: boolean): this;
     /**
      * Remove the mark with `id`, located via `pos` (the position it was added at). On a settled document
      * that holds the mark this removes it in place; on a fresh/markless builder it records a transmittable
@@ -1125,6 +1127,7 @@ export type MarkJSON = {
     key: number | string;
     assoc: 1 | -1;
     attrs?: object;
+    transient?: boolean;
 };
 export type DeltaJSON = {
     type: "delta";
@@ -1307,6 +1310,7 @@ import * as fingerprintTrait from '../trait/fingerprint.js';
  * - `attrs` — optional user-supplied data carried with the mark **by reference**: the same
  *   object is shared across the mark, its `copy`/`clone`s, `toJSON`, and every `MarkPos` from
  *   `marksToPositions`, so the caller must treat it as immutable (do not mutate it after attaching).
+ * - `transient` — the mark only rides through a mapping and must never be stored (see the field doc).
  *
  * A `Mark` is **immutable** — never mutate one in place; to "move" a mark, replace it with a fresh
  * `Mark` via {@link Mark#copy} (the {@link Marks} set keys by id, so re-adding the same id replaces
@@ -1319,8 +1323,9 @@ declare class Mark {
      * @param {string} [id] unique id; defaults to a fresh GUID
      * @param {1|-1} [assoc] gravity at a boundary; defaults to right (`1`)
      * @param {object?} [attrs] optional user data, stored by reference; treat as immutable
+     * @param {boolean} [transient] the mark must never be stored; see the field doc
      */
-    constructor(key: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null);
+    constructor(key: number | string, id?: string, assoc?: 1 | -1, attrs?: object | null, transient?: boolean);
     /**
      * @readonly
      * @type {number|string}
@@ -1341,6 +1346,18 @@ declare class Mark {
      * @type {object?}
      */
     readonly attrs: object | null;
+    /**
+     * A transient mark exists only to ride through a mapping (see
+     * {@link import('./position.js').mapPositionsA}) and must never be stored: a consumer that
+     * maintains persistent state (a document, a transformer's internal model of one) either filters
+     * transient marks before applying a change to that state, or removes them when found on
+     * final/settled state. How that is achieved is left to the implementation — the core does not
+     * enforce it (today nothing in lib0 stores marks outside a document, so nothing needs to).
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly transient: boolean;
     /**
      * A copy of this mark, optionally at a different `key` (used to "move" an otherwise-immutable mark).
      *

package/dist/delta/position.d.ts

@@ -35,6 +35,8 @@ export function equals(a: Pos | MarkPos, b: Pos | MarkPos): boolean;
  */
 export const $markPos: s.Schema<MarkPos>;
 export function marksToPositions(d: delta.DeltaAny): Array<MarkPos>;
+export function mapPositionsA(tr: import("./transformer/core.js").Transformer<any, any>, positions: Array<Pos>): Array<Pos | null>;
+export function mapPositionsB(tr: import("./transformer/core.js").Transformer<any, any>, positions: Array<Pos>): Array<Pos | null>;
 /**
  * A single step of a {@link Pos} path: a `string` attribute key, or a `number` content index.
  */

package/dist/random.d.ts

@@ -2,5 +2,9 @@ export const rand: () => number;
 export function uint32(): number;
 export function uint53(): number;
 export function oneOf<T>(arr: Array<T>): T;
-export function uuidv4(): string;
+export function _uuidv4Polyfill(): string;
+/**
+ * @type {() => string}
+ */
+export const uuidv4: () => string;
 //# sourceMappingURL=random.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lib0",
-  "version": "1.0.0-rc.26",
+  "version": "1.0.0-rc.28",
   "description": "isomorphic utility functions",
   "sideEffects": false,
   "type": "module",

package/src/delta/delta.js

@@ -90,7 +90,7 @@ export const $attribution = /* @__PURE__ */(() => s.$object({
  */
 
 /**
- * @typedef {{ id: string, key: number|string, assoc: 1|-1, attrs?: object }} MarkJSON
+ * @typedef {{ id: string, key: number|string, assoc: 1|-1, attrs?: object, transient?: boolean }} MarkJSON
  */
 
 /**
@@ -1136,6 +1136,7 @@ export const $modifyAttrOpWith = $content => s.$custom(o => $modifyAttrOp.check(
  * - `attrs` — optional user-supplied data carried with the mark **by reference**: the same
  *   object is shared across the mark, its `copy`/`clone`s, `toJSON`, and every `MarkPos` from
  *   `marksToPositions`, so the caller must treat it as immutable (do not mutate it after attaching).
+ * - `transient` — the mark only rides through a mapping and must never be stored (see the field doc).
  *
  * A `Mark` is **immutable** — never mutate one in place; to "move" a mark, replace it with a fresh
  * `Mark` via {@link Mark#copy} (the {@link Marks} set keys by id, so re-adding the same id replaces
@@ -1148,8 +1149,9 @@ class Mark {
    * @param {string} [id] unique id; defaults to a fresh GUID
    * @param {1|-1} [assoc] gravity at a boundary; defaults to right (`1`)
    * @param {object?} [attrs] optional user data, stored by reference; treat as immutable
+   * @param {boolean} [transient] the mark must never be stored; see the field doc
    */
-  constructor (key, id = rand.uuidv4(), assoc = 1, attrs = null) {
+  constructor (key, id = rand.uuidv4(), assoc = 1, attrs = null, transient = false) {
     /**
      * @readonly
      * @type {number|string}
@@ -1170,6 +1172,18 @@ class Mark {
      * @type {object?}
      */
     this.attrs = attrs
+    /**
+     * A transient mark exists only to ride through a mapping (see
+     * {@link import('./position.js').mapPositionsA}) and must never be stored: a consumer that
+     * maintains persistent state (a document, a transformer's internal model of one) either filters
+     * transient marks before applying a change to that state, or removes them when found on
+     * final/settled state. How that is achieved is left to the implementation — the core does not
+     * enforce it (today nothing in lib0 stores marks outside a document, so nothing needs to).
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    this.transient = transient
   }
 
   /**
@@ -1179,23 +1193,26 @@ class Mark {
    * @return {Mark}
    */
   copy (key = this.key) {
-    return new Mark(key, this.id, this.assoc, this.attrs)
+    return new Mark(key, this.id, this.assoc, this.attrs, this.transient)
   }
 
   /**
    * @return {MarkJSON}
    */
   toJSON () {
-    return this.attrs === null
+    /** @type {MarkJSON} */
+    const json = this.attrs === null
       ? { id: this.id, key: this.key, assoc: this.assoc }
       : { id: this.id, key: this.key, assoc: this.assoc, attrs: this.attrs }
+    if (this.transient) json.transient = true
+    return json
   }
 
   /**
    * @param {Mark} other
    */
   [equalityTrait.EqualityTraitSymbol] (other) {
-    return $mark.check(other) && this.id === other.id && this.key === other.key && this.assoc === other.assoc && fun.equalityDeep(this.attrs, other.attrs)
+    return $mark.check(other) && this.id === other.id && this.key === other.key && this.assoc === other.assoc && this.transient === other.transient && fun.equalityDeep(this.attrs, other.attrs)
   }
 }
 
@@ -1203,16 +1220,17 @@ export const $mark = /** @type {s.Schema<Mark>} */ (Mark.prototype.$type = s.$ty
 
 /**
  * Create a {@link Mark} (use this instead of `new Mark(...)`). `id` defaults to a fresh GUID, `assoc`
- * to right gravity (`1`), `attrs` to `null`. A `Mark` is stored on a delta node's own
- * {@link Marks} set (see {@link DeltaBuilder#addMark}).
+ * to right gravity (`1`), `attrs` to `null`, `transient` to `false`. A `Mark` is stored on a delta
+ * node's own {@link Marks} set (see {@link DeltaBuilder#addMark}).
  *
  * @param {number|string} key
  * @param {string} [id]
  * @param {1|-1} [assoc]
  * @param {object?} [attrs]
+ * @param {boolean} [transient] never to be stored (see {@link Mark#transient})
  * @return {Mark}
  */
-export const createMark = (key, id, assoc, attrs) => new Mark(key, id, assoc, attrs)
+export const createMark = (key, id, assoc, attrs, transient) => new Mark(key, id, assoc, attrs, transient)
 
 /**
  * @typedef {Delta<any>} DeltaAny
@@ -2135,12 +2153,14 @@ export class DeltaBuilder extends Delta {
    *
    * @param {import('./position.js').Pos} pos
    * @param {string} [id]
+   * @param {boolean} [transient] flag the mark as never-to-be-stored (a one-shot mapping probe, see
+   * {@link Mark#transient} and {@link import('./position.js').mapPositionsA})
    * @return {this}
    */
-  addMark (pos, id = rand.uuidv4()) {
+  addMark (pos, id = rand.uuidv4(), transient = false) {
     // apply with the default `final = this.isFinal` (do NOT force `{ final: true }`): a fresh change
     // builder is non-final so a sibling `removeMark` stays transmittable; a final doc collects nothing
-    this.apply(/** @type {Delta<Conf>} */ (markChange(pos, id, false)))
+    this.apply(/** @type {Delta<Conf>} */ (markChange(pos, id, false, transient)))
     return this
   }
 
@@ -3363,14 +3383,15 @@ const rebaseRootMarks = (node, other, priority) => {
  * @param {import('./position.js').Pos} pos
  * @param {string} id
  * @param {boolean} isDelete
+ * @param {boolean} [transient] never to be stored (see {@link Mark#transient})
  * @return {DeltaBuilderAny}
  */
-const markChange = (pos, id, isDelete) => {
+const markChange = (pos, id, isDelete, transient = false) => {
   const path = pos.path
   // a mark anchors at the terminal step of its path (a content offset or attribute key); the root
   // position `[]` has no terminal and cannot carry a mark - reject it instead of recursing forever
   if (path.length === 0) throw error.create('cannot place a mark at the root position (empty path): a mark needs a terminal content-offset or attribute-key step')
-  const mark = isDelete ? null : createMark(path[path.length - 1], id, pos.assoc, pos.attrs ?? null)
+  const mark = isDelete ? null : createMark(path[path.length - 1], id, pos.assoc, pos.attrs ?? null, transient)
   /**
    * @param {number} i
    * @return {DeltaBuilderAny}

package/src/delta/position.js

@@ -104,9 +104,12 @@ export const $markPos = /* @__PURE__ */ s.$object({
 })
 
 /**
- * Reconstruct every {@link MarkPos} stored as a {@link import('./delta.js').Mark mark} inside `d` (a
- * settled delta). A mark's `path` is the content indices / attribute keys walked to reach it, plus the
- * mark's own `key`. Add marks with {@link import('./delta.js').DeltaBuilder#addMark}.
+ * Reconstruct every {@link MarkPos} stored as a {@link import('./delta.js').Mark mark} inside `d` — a
+ * settled delta or a change delta (e.g. a raw transformer output, or the change `addMark` builds). A
+ * mark's `path` is the content indices / attribute keys walked to reach it, plus the mark's own `key`;
+ * the walk descends insert embeds, `modify` values, and `setAttr`/`modifyAttr` values. In a change
+ * delta the indices are post-change coordinates (delete ops span no slot). Add marks with
+ * {@link import('./delta.js').DeltaBuilder#addMark}.
  *
  * Subtrees are pruned via each node's conservative `maybeHasMarks` flag (`false` ⇒ guaranteed empty,
  * skipped). This is also the **sole resetter** of that flag: a descended subtree that turns out to hold
@@ -137,7 +140,8 @@ export const marksToPositions = d => {
           : { id: m.id, path: [...path, m.key], assoc: m.assoc, attrs: m.attrs })
       }
     }
-    // a settled delta has only text/insert children; descend the delta-valued embeds
+    // descend the delta-valued insert embeds and the modify values (a change delta's mark rides on a
+    // modify's nested root marks - see markChange; `apply` may also leave a modify on a settled node)
     let i = 0
     for (const op of node.children) {
       if (delta.$insertOp.check(op)) {
@@ -145,7 +149,12 @@ export const marksToPositions = d => {
           if (delta.$deltaAny.check(el) && el.maybeHasMarks && walk(el, [...path, i])) found = true
           i++
         }
-      } else {
+      } else if (delta.$modifyOp.check(op)) {
+        if (op.value.maybeHasMarks && walk(op.value, [...path, i])) found = true
+        i++
+      } else if (!delta.$deleteOp.check(op)) {
+        // text / retain advance the content index; a delete occupies only the pre-change coordinate -
+        // mark paths (like mark keys, see delta.js's shiftMarkKey) are post-change content indices
         i += op.length
       }
     }
@@ -163,3 +172,66 @@ export const marksToPositions = d => {
   walk(d, [])
   return out
 }
+
+/**
+ * Shared body of {@link mapPositionsA}/{@link mapPositionsB}: encode `positions` as marks on one
+ * synthetic change (ids are the input indices), run it through `transform` once, and read the images
+ * back off the raw output. Nothing is ever applied to a document, so no mark persists anywhere.
+ *
+ * @param {Array<Pos>} positions
+ * @param {(change: delta.DeltaBuilderAny) => delta.DeltaAny?} transform
+ * @return {Array<Pos?>}
+ */
+const mapPositionsThrough = (positions, transform) => {
+  if (positions.length === 0) return []
+  const change = /** @type {delta.DeltaBuilderAny} */ (delta.create())
+  positions.forEach((pos, i) => change.addMark(pos, '' + i, true)) // transient probes - never to be stored
+  const mapped = transform(change)
+  /**
+   * @type {Map<string, MarkPos>}
+   */
+  const byId = new Map()
+  if (mapped != null) {
+    // the raw output may alias transformer-internal state; marksToPositions' `maybeHasMarks`
+    // self-correction is safe there (`false` is only written where verifiably no marks exist)
+    for (const m of marksToPositions(mapped)) {
+      if (!byId.has(m.id)) byId.set(m.id, m) // fan-out (e.g. one datum in several project holes): first image in doc order wins
+    }
+  }
+  return positions.map((_, i) => {
+    const m = byId.get('' + i)
+    return m === undefined ? null : create(m.path, m.assoc, m.attrs ?? null)
+  })
+}
+
+/**
+ * One-shot map of `positions` living on a transformer's **A side** to the B side (the mirror of
+ * {@link mapPositionsB}) — for when you want an answer *now* without maintaining a position-set as
+ * stored marks. One transform pass maps the whole batch; the result is in input order, each entry the
+ * B-side image or `null` when the position has none (a transformer maps marks best-effort — see the
+ * readme). `assoc` and `attrs` ride through on the probe mark.
+ *
+ * The probes are `transient` marks ({@link import('./delta.js').createMark Mark}`#transient`): a
+ * transformer that keeps marks in internal state must not store them (none does today). Beyond that
+ * the call is state-neutral by construction — a mark-only change shifts no content and is never
+ * applied to any document, so neither the documents nor the transformer are (semantically) modified.
+ *
+ * The transformer must already have been fed the document state (a live
+ * {@link import('./rdt.js').Binding} always has): with no document behind it there is nothing for a
+ * position to point into — and e.g. a fresh `project` transformer would consume its initial render.
+ *
+ * @param {import('./transformer/core.js').Transformer<any, any>} tr
+ * @param {Array<Pos>} positions positions on the A side
+ * @return {Array<Pos?>} their images on the B side (input order; `null` = no image)
+ */
+export const mapPositionsA = (tr, positions) => mapPositionsThrough(positions, c => tr.applyA(c).b)
+
+/**
+ * One-shot map of `positions` living on a transformer's **B side** to the A side — see
+ * {@link mapPositionsA} for the contract (this is the same mapping, fed through `applyB`).
+ *
+ * @param {import('./transformer/core.js').Transformer<any, any>} tr
+ * @param {Array<Pos>} positions positions on the B side
+ * @return {Array<Pos?>} their images on the A side (input order; `null` = no image)
+ */
+export const mapPositionsB = (tr, positions) => mapPositionsThrough(positions, c => tr.applyB(c).a)

package/src/function.js

@@ -61,8 +61,6 @@ export const equalityStrict = (a, b) => a === b
  */
 export const equalityFlat = (a, b) => a === b || (a != null && b != null && a.constructor === b.constructor && ((array.isArray(a) && array.equalFlat(a, /** @type {Array<T>} */ (b))) || (typeof a === 'object' && object.equalFlat(a, b))))
 
-/* c8 ignore start */
-
 /**
  * @param {any} a
  * @param {any} b
@@ -72,13 +70,20 @@ export const equalityDeep = (a, b) => {
   if (a === b) {
     return true
   }
-  if (a == null || b == null || (a.constructor !== b.constructor && (a.constructor || Object) !== (b.constructor || Object))) {
+  if (a == null || b == null) {
+    return false
+  }
+  // read the constructor off the prototype, not the object — a plain object may declare an own
+  // property named "constructor" (e.g. `{ constructor: 4 }`)
+  const aC = Object.getPrototypeOf(a)?.constructor
+  const bC = Object.getPrototypeOf(b)?.constructor
+  if (aC !== bC && (aC || Object) !== (bC || Object)) {
     return false
   }
   if (a[equalityTrait.EqualityTraitSymbol] != null) {
     return a[equalityTrait.EqualityTraitSymbol](b)
   }
-  switch (a.constructor) {
+  switch (aC) {
     case ArrayBuffer:
       a = new Uint8Array(a)
       b = new Uint8Array(b)
@@ -152,7 +157,6 @@ export const equalityDeep = (a, b) => {
  */
 // @ts-ignore
 export const isOneOf = (value, options) => options.includes(value)
-/* c8 ignore stop */
 
 export const isArray = array.isArray
 

package/src/random.js

@@ -1,7 +1,9 @@
 /**
  * Isomorphic module for true random numbers / buffers / uuids.
  *
- * Attention: falls back to Math.random if the browser does not support crypto.
+ * uuidv4 uses the native `crypto.randomUUID` when available and falls back to a
+ * `getRandomValues`-based implementation otherwise (insecure browser contexts,
+ * react-native).
  *
  * @module random
  */
@@ -30,8 +32,20 @@ export const oneOf = arr => arr[math.floor(rand() * arr.length)]
 const uuidv4Template = [1e7] + -1e3 + -4e3 + -8e3 + -1e11
 
 /**
+ * Fallback for environments without `crypto.randomUUID` (insecure browser
+ * contexts, react-native).
+ *
  * @return {string}
  */
-export const uuidv4 = () => uuidv4Template.replace(/[018]/g, /** @param {number} c */ c =>
+export const _uuidv4Polyfill = () => uuidv4Template.replace(/[018]/g, /** @param {number} c */ c =>
   (c ^ uint32() & 15 >> c / 4).toString(16)
 )
+
+/**
+ * @type {() => string}
+ */
+export const uuidv4 = /* @__PURE__ */ (() =>
+  typeof crypto !== 'undefined' && crypto.randomUUID != null
+    ? crypto.randomUUID.bind(crypto)
+    : _uuidv4Polyfill
+)()