@sovereignbase/sequencer 0.0.2 → 1.0.0

package/dist/index.d.cts

@@ -1,22 +1,37 @@
 
 //#region src/typescript/types/type.d.ts
-/** Structural words may be typed views or numeric arrays received as JSON. */
+/** Unsigned 32-bit structural words, accepted as a typed view or JSON numeric array. */
 type U32List = Uint32Array | ReadonlyArray<number>;
 /**
  * Exactly six words, in the replication order:
  * `[anchorSession, anchorStart, anchorDiff,
  *   insertionSession, insertionStart, insertionDiff]`.
- * Signed coordinates use their 32-bit bit pattern; WASM interprets those lanes
- * as signed.
+ * The anchor triple names a logical point in an existing Insertion; the Session
+ * and start pair identifies the authored Insertion. A positive diff adds Frames;
+ * a negative diff masks original Frames. Signed values use uint32 bit patterns.
  */
 type InsertionWords = U32List;
-/** Insertion coordinates plus optional JS-owned content. Only words enter WASM. */
-type Insertion<T> = Readonly<[words: InsertionWords, footage?: ReadonlyArray<T | undefined>]>;
-/** `[actorID, sessionID, sessionEnd, ...]`. */
+/**
+ * Canonical replication operation and optional JavaScript-owned Footage.
+ * Positive Insertions may omit Footage; their Frames then read as `undefined`.
+ * Reducing Insertions carry no content into native state.
+ */
+type Insertion<T> = Readonly<[
+/** Stable anchor, identity and signed Frame effect. */
+words: InsertionWords,
+/** Values of a positive Insertion, in original Frame order. */
+footage?: ReadonlyArray<T | undefined>]>;
+/**
+ * Describes one Actor's acknowledgement frontier.
+ * `[actorID, sessionID, sessionEnd, ...]` contains removal Session/frontier pairs.
+ * The application is responsible for acknowledging complete received Session prefixes.
+ */
 type Acknowledgement = U32List;
+/** Ordered replication batch; delivery may be duplicated or causally reordered. */
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
- * One structural array and one JS-owned content array.
+ * Retained state required to hydrate the same visible Projection.
+ * One structural array and one JavaScript-owned content array.
  * Small snapshots use six-word insertion records after length-prefixed ACKs;
  * `words[0]` locates those records. Large snapshots begin with
  * `[0, frontiersEnd, insertionCount]` and omit predictable coordinate fields.
@@ -24,27 +39,116 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * Positive insertion diffs consume successive spans of `footage`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
-type Sequence<T> = Readonly<[words: U32List, footage: ReadonlyArray<T | undefined>]>;
-type Splice<T> = Readonly<[startAt: number, endWith: number, values?: ReadonlyArray<T | undefined>]>;
+type Sequence<T> = Readonly<[
+/** Acknowledgements followed by canonical Insertions in Structural Order. */
+words: U32List,
+/** Consecutive positive Insertion spans, including missing Footage slots. */
+footage: ReadonlyArray<T | undefined>]>;
+/** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
+type Splice<T> = Readonly<[
+/** First affected position in the Projection after preceding Splices. */
+startAt: number,
+/** Exclusive removal boundary; equal to `startAt` for insertion. */
+endWith: number,
+/** Inserted Footage; omitted for removal. */
+values?: ReadonlyArray<T | undefined>]>;
+/** Splices applied in order to reproduce the remote operation's visible effect. */
 type Change<T> = ReadonlyArray<Splice<T>>;
+/** Visible changes and optional Gossip returned by `apply()` or `merge()`. */
 type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/class.d.ts
-/** Public API; algorithms execute synchronously in one WASM instance. */
+/** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
   readonly actorID: number;
+  /** Native instance handle; a negative value marks explicit destruction. */
   private id;
+  /**
+   * Prepares to sequence a projection, optionally hydrating from a trusted sequence stored by the application.
+   *
+   * @param actorID Actor identifier used in acknowledgements.
+   * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   */
   constructor(actorID: number, trustedSequence?: unknown);
+  /**
+   * Applies gossiped Insertions and Acknowledgements.
+   *
+   * @param gossip Batch of Insertion and Acknowledgement tuples.
+   * @returns Visible changes and optional acknowledgement Gossip, or
+   * `undefined` for invalid input. Earlier entries may already have been applied.
+   */
   apply(gossip: unknown): Result<T> | undefined;
+  /**
+   * Inserts values at a Projection position.
+   *
+   * @param values Nonempty array of values to insert.
+   * @param at Insertion position in `0..length()`, inclusive.
+   * @returns Gossip describing the insertion.
+   */
   insert(values: Array<T>, at: number): Gossip<T>;
+  /**
+   * Returns the length, A.K.A. amount of entries of this projection.
+   *
+   * @returns Current Projection length.
+   */
   length(): number;
+  /**
+   * Applies relevant acknowledgements and nonduplicate insertions from a replica of the sequence.
+   *
+   * @param sequence Sequence to merge.
+   * @returns Visible changes and optional acknowledgement Gossip, or
+   * `undefined` if the Sequence has an invalid runtime shape.
+   */
   merge(sequence: unknown): Result<T> | undefined;
+  /**
+   * Removes an inclusive range of Projection positions.
+   *
+   * @param startAt First position to remove; defaults to 0.
+   * @param endWith Last position to remove; defaults to `length() - 1`.
+   * @returns Reducing Insertions and their acknowledgement as Gossip.
+   */
   remove(startAt?: number, endWith?: number): Gossip<T>;
+  /**
+   * Replaces an inclusive range of Projection positions.
+   *
+   * @param withValues Replacement values; an empty array only removes the range.
+   * @param startAt First position to replace; defaults to 0.
+   * @param endWith Last position to replace; defaults to `length() - 1`.
+   * @returns Removal and insertion Gossip, in that order.
+   */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
+  /**
+   * Retires an Actor from future compaction requirements.
+   *
+   * @remarks
+   * The application is responsible for deciding which Actors are retired and
+   * for propagating that decision to the relevant replicas.
+   *
+   * @param actorID Actor whose Acknowledgements are no longer required for compaction.
+   */
   retire(actorID: number): void;
+  /**
+   * Sequences state into a compact serializable format.
+   *
+   * @returns A Sequence with acknowledged removals compacted in the exported state.
+   */
   sequence(): Sequence<T>;
+  /**
+   * Returns the value at a Projection position.
+   *
+   * @param at Valid visible position in `0..length() - 1`.
+   * @returns The corresponding Footage value.
+   */
   value(at: number): T | undefined;
+  /**
+   * Returns values from an inclusive range of Projection positions.
+   *
+   * @param startAt First included position; defaults to 0.
+   * @param endWith Last included position; defaults to `length() - 1`.
+   * @returns A new array of values, or an empty array for an empty range.
+   */
   values(startAt?: number, endWith?: number): Array<T>;
+  /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
 //#endregion

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;KASxB,iBAAiB;;KAGjB,UAAU,KAAK,UACxB,OAAO,gBAAgB,UAAU,cAAc;;KAItC,kBAAkB;KAElB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;KAWtD,SAAS,KAAK,UACvB,OAAO,SAAS,SAAS,cAAc;KAG9B,OAAO,KAAK,UACrB,iBAAiB,iBAAiB,SAAS,cAAc;KAGhD,OAAO,KAAK,cAAc,OAAO;KACjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;qBCnCxD,WAAW;WAIJ;UAHV;EAGU,YAAA,iBAChB;EAKF,MAAM,kBAAkB,OAAO;EAI/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;EAI7C;EAIA,MAAM,oBAAoB,OAAO;EAIjC,OAAO,kBAAkB,mBAAmB,OAAO;EAInD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;EAU1E,OAAO;EAIP,YAAY,SAAS;EAIrB,MAAM,aAAa;EAInB,OAAO,kBAAkB,mBAAmB,MAAM;EAIlD"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;KAShB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;KAYtD,SAAS,KAAK;;AAGtB,OAAO;;AAEP,SAAS,cAAc;;KAKf,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;qBClExD,WAAW;WAWJ;;UATV;;;;;;;EASU,YAAA,iBAChB;;;;;;;;EAYF,MAAM,kBAAkB,OAAO;;;;;;;;EAW/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;EAS7C;;;;;;;;EAWA,MAAM,oBAAoB,OAAO;;;;;;;;EAWjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;EAYnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAmB1E,OAAO;;;;;;EASP,YAAY,SAAS;;;;;;;EAUrB,MAAM,aAAa;;;;;;;;EAWnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}

package/dist/index.d.ts

@@ -1,22 +1,37 @@
 
 //#region src/typescript/types/type.d.ts
-/** Structural words may be typed views or numeric arrays received as JSON. */
+/** Unsigned 32-bit structural words, accepted as a typed view or JSON numeric array. */
 type U32List = Uint32Array | ReadonlyArray<number>;
 /**
  * Exactly six words, in the replication order:
  * `[anchorSession, anchorStart, anchorDiff,
  *   insertionSession, insertionStart, insertionDiff]`.
- * Signed coordinates use their 32-bit bit pattern; WASM interprets those lanes
- * as signed.
+ * The anchor triple names a logical point in an existing Insertion; the Session
+ * and start pair identifies the authored Insertion. A positive diff adds Frames;
+ * a negative diff masks original Frames. Signed values use uint32 bit patterns.
  */
 type InsertionWords = U32List;
-/** Insertion coordinates plus optional JS-owned content. Only words enter WASM. */
-type Insertion<T> = Readonly<[words: InsertionWords, footage?: ReadonlyArray<T | undefined>]>;
-/** `[actorID, sessionID, sessionEnd, ...]`. */
+/**
+ * Canonical replication operation and optional JavaScript-owned Footage.
+ * Positive Insertions may omit Footage; their Frames then read as `undefined`.
+ * Reducing Insertions carry no content into native state.
+ */
+type Insertion<T> = Readonly<[
+/** Stable anchor, identity and signed Frame effect. */
+words: InsertionWords,
+/** Values of a positive Insertion, in original Frame order. */
+footage?: ReadonlyArray<T | undefined>]>;
+/**
+ * Describes one Actor's acknowledgement frontier.
+ * `[actorID, sessionID, sessionEnd, ...]` contains removal Session/frontier pairs.
+ * The application is responsible for acknowledging complete received Session prefixes.
+ */
 type Acknowledgement = U32List;
+/** Ordered replication batch; delivery may be duplicated or causally reordered. */
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
- * One structural array and one JS-owned content array.
+ * Retained state required to hydrate the same visible Projection.
+ * One structural array and one JavaScript-owned content array.
  * Small snapshots use six-word insertion records after length-prefixed ACKs;
  * `words[0]` locates those records. Large snapshots begin with
  * `[0, frontiersEnd, insertionCount]` and omit predictable coordinate fields.
@@ -24,27 +39,116 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * Positive insertion diffs consume successive spans of `footage`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
  */
-type Sequence<T> = Readonly<[words: U32List, footage: ReadonlyArray<T | undefined>]>;
-type Splice<T> = Readonly<[startAt: number, endWith: number, values?: ReadonlyArray<T | undefined>]>;
+type Sequence<T> = Readonly<[
+/** Acknowledgements followed by canonical Insertions in Structural Order. */
+words: U32List,
+/** Consecutive positive Insertion spans, including missing Footage slots. */
+footage: ReadonlyArray<T | undefined>]>;
+/** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
+type Splice<T> = Readonly<[
+/** First affected position in the Projection after preceding Splices. */
+startAt: number,
+/** Exclusive removal boundary; equal to `startAt` for insertion. */
+endWith: number,
+/** Inserted Footage; omitted for removal. */
+values?: ReadonlyArray<T | undefined>]>;
+/** Splices applied in order to reproduce the remote operation's visible effect. */
 type Change<T> = ReadonlyArray<Splice<T>>;
+/** Visible changes and optional Gossip returned by `apply()` or `merge()`. */
 type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/class.d.ts
-/** Public API; algorithms execute synchronously in one WASM instance. */
+/** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
   readonly actorID: number;
+  /** Native instance handle; a negative value marks explicit destruction. */
   private id;
+  /**
+   * Prepares to sequence a projection, optionally hydrating from a trusted sequence stored by the application.
+   *
+   * @param actorID Actor identifier used in acknowledgements.
+   * @param trustedSequence Optional trusted Sequence in Structural Order, stored by the application.
+   */
   constructor(actorID: number, trustedSequence?: unknown);
+  /**
+   * Applies gossiped Insertions and Acknowledgements.
+   *
+   * @param gossip Batch of Insertion and Acknowledgement tuples.
+   * @returns Visible changes and optional acknowledgement Gossip, or
+   * `undefined` for invalid input. Earlier entries may already have been applied.
+   */
   apply(gossip: unknown): Result<T> | undefined;
+  /**
+   * Inserts values at a Projection position.
+   *
+   * @param values Nonempty array of values to insert.
+   * @param at Insertion position in `0..length()`, inclusive.
+   * @returns Gossip describing the insertion.
+   */
   insert(values: Array<T>, at: number): Gossip<T>;
+  /**
+   * Returns the length, A.K.A. amount of entries of this projection.
+   *
+   * @returns Current Projection length.
+   */
   length(): number;
+  /**
+   * Applies relevant acknowledgements and nonduplicate insertions from a replica of the sequence.
+   *
+   * @param sequence Sequence to merge.
+   * @returns Visible changes and optional acknowledgement Gossip, or
+   * `undefined` if the Sequence has an invalid runtime shape.
+   */
   merge(sequence: unknown): Result<T> | undefined;
+  /**
+   * Removes an inclusive range of Projection positions.
+   *
+   * @param startAt First position to remove; defaults to 0.
+   * @param endWith Last position to remove; defaults to `length() - 1`.
+   * @returns Reducing Insertions and their acknowledgement as Gossip.
+   */
   remove(startAt?: number, endWith?: number): Gossip<T>;
+  /**
+   * Replaces an inclusive range of Projection positions.
+   *
+   * @param withValues Replacement values; an empty array only removes the range.
+   * @param startAt First position to replace; defaults to 0.
+   * @param endWith Last position to replace; defaults to `length() - 1`.
+   * @returns Removal and insertion Gossip, in that order.
+   */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
+  /**
+   * Retires an Actor from future compaction requirements.
+   *
+   * @remarks
+   * The application is responsible for deciding which Actors are retired and
+   * for propagating that decision to the relevant replicas.
+   *
+   * @param actorID Actor whose Acknowledgements are no longer required for compaction.
+   */
   retire(actorID: number): void;
+  /**
+   * Sequences state into a compact serializable format.
+   *
+   * @returns A Sequence with acknowledged removals compacted in the exported state.
+   */
   sequence(): Sequence<T>;
+  /**
+   * Returns the value at a Projection position.
+   *
+   * @param at Valid visible position in `0..length() - 1`.
+   * @returns The corresponding Footage value.
+   */
   value(at: number): T | undefined;
+  /**
+   * Returns values from an inclusive range of Projection positions.
+   *
+   * @param startAt First included position; defaults to 0.
+   * @param endWith Last included position; defaults to `length() - 1`.
+   * @returns A new array of values, or an empty array for an empty range.
+   */
   values(startAt?: number, endWith?: number): Array<T>;
+  /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
 //#endregion

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;KASxB,iBAAiB;;KAGjB,UAAU,KAAK,UACxB,OAAO,gBAAgB,UAAU,cAAc;;KAItC,kBAAkB;KAElB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;KAWtD,SAAS,KAAK,UACvB,OAAO,SAAS,SAAS,cAAc;KAG9B,OAAO,KAAK,UACrB,iBAAiB,iBAAiB,SAAS,cAAc;KAGhD,OAAO,KAAK,cAAc,OAAO;KACjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;qBCnCxD,WAAW;WAIJ;UAHV;EAGU,YAAA,iBAChB;EAKF,MAAM,kBAAkB,OAAO;EAI/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;EAI7C;EAIA,MAAM,oBAAoB,OAAO;EAIjC,OAAO,kBAAkB,mBAAmB,OAAO;EAInD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;EAU1E,OAAO;EAIP,YAAY,SAAS;EAIrB,MAAM,aAAa;EAInB,OAAO,kBAAkB,mBAAmB,MAAM;EAIlD"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;KAShB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;KAYtD,SAAS,KAAK;;AAGtB,OAAO;;AAEP,SAAS,cAAc;;KAKf,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;qBClExD,WAAW;WAWJ;;UATV;;;;;;;EASU,YAAA,iBAChB;;;;;;;;EAYF,MAAM,kBAAkB,OAAO;;;;;;;;EAW/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;EAS7C;;;;;;;;EAWA,MAAM,oBAAoB,OAAO;;;;;;;;EAWjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;EAYnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAmB1E,OAAO;;;;;;EASP,YAAY,SAAS;;;;;;;EAUrB,MAAM,aAAa;;;;;;;;EAWnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}