@sovereignbase/sequencer 1.1.1 → 1.2.0

package/dist/index.d.cts

@@ -1,5 +1,4 @@
 
-//#region src/typescript/types/type.d.ts
 /** Unsigned 32-bit structural words, accepted as a typed view or JSON numeric array. */
 type U32List = Uint32Array | ReadonlyArray<number>;
 /**
@@ -9,6 +8,7 @@ type U32List = Uint32Array | ReadonlyArray<number>;
  * 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.
+ * In tuple mode, `anchorDiff` is the stable index and diff is `1` or `-1`.
  */
 type InsertionWords = U32List;
 /**
@@ -45,13 +45,19 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * It uses one UTF-16 code unit per Frame. Missing slots use
  * NUL (`\u0000`); hydration splits the string with `split('')`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
+ * Tuple metadata prefixes the payload with `[0xffffffff, 1, maxLength, length]`;
+ * `maxLength = 0xffffffff` denotes dynamic growth. Tuple indices are never translated.
  */
 type Sequence<T, StringEncoded extends boolean = false> = Readonly<[
 /** Acknowledgements followed by canonical Insertions in Structural Order. */
 words: U32List,
 /** Consecutive positive Insertion spans, including missing Footage slots. */
 footage: StringEncoded extends true ? string : ReadonlyArray<T | undefined>]>;
-/** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
+/**
+ * Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively.
+ * Tuple changes assign one stable index using `[index, index + 1, [value]]`;
+ * an empty register supplies `undefined`, without shifting other indices.
+ */
 type Splice<T> = Readonly<[
 /** First affected position in the Projection after preceding Splices. */
 startAt: number,
@@ -63,8 +69,13 @@ values?: ReadonlyArray<T | undefined>]>;
 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/errors/class.d.ts
+/** Stable-index register configuration; omitting maxLength permits dynamic growth. */
+type TupleParams = {
+  /** Whether indices remain fixed when values are inserted or removed. */
+  enabled: boolean | 0 | 1;
+  /** Fixed number of registers, indices must be in `0..maxLength - 1`. */
+  maxLength?: number;
+};
 /** Semantic error codes reported by the Sequencer public API. */
 type SequencerErrorCode = 'UNKNOWN_ERROR' | 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
@@ -80,8 +91,6 @@ export declare class SequencerError extends Error {
    */
   constructor(code: SequencerErrorCode, message?: string, options?: ErrorOptions);
 }
-//#endregion
-//#region src/typescript/class.d.ts
 /** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
   readonly actorID: number;
@@ -92,9 +101,10 @@ export declare class Projection<T> {
    *
    * @param actorID Actor identifier used in acknowledgements.
    * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
+   * @param tupleParams Enables stable indices, optionally bounded by a fixed length. Tuple Sequences retain this configuration.
    * @throws {@link SequencerError} if native initialization fails.
    */
-  constructor(actorID: number, trustedSequence?: unknown);
+  constructor(actorID: number, trustedSequence?: unknown, tupleParams?: TupleParams);
   /**
    * Applies gossiped Insertions and Acknowledgements.
    *
@@ -108,7 +118,7 @@ export declare class Projection<T> {
    * Inserts values at a Projection position.
    *
    * @param values Nonempty array of values to insert.
-   * @param at Insertion position in `0..length()`, inclusive.
+   * @param at Insertion position in `0..length()`, inclusive. In tuple mode, the first stable index to write; each value creates a competing version.
    * @returns Gossip describing the insertion.
    * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
@@ -116,7 +126,7 @@ export declare class Projection<T> {
   /**
    * Returns the length, A.K.A. amount of entries of this projection.
    *
-   * @returns Current Projection length.
+   * @returns Current Projection length. Tuples retain their fixed length or highest written boundary, including empty registers.
    * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   length(): number;
@@ -134,7 +144,7 @@ export declare class Projection<T> {
    *
    * @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.
+   * @returns Reducing Insertions and their acknowledgement as Gossip. Tuple removal targets all known active versions without shifting indices.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   remove(startAt?: number, endWith?: number): Gossip<T>;
@@ -144,7 +154,7 @@ export declare class Projection<T> {
    * @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.
+   * @returns Removal and insertion Gossip, in that order. Tuple replacement removes known versions and writes consecutive stable indices.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
@@ -193,6 +203,5 @@ export declare class Projection<T> {
   /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
-//#endregion
-export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, U32List };
+export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, TupleParams, U32List };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;KAiBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;KAKrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KC7EzD;;qBAOC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBChBD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAuBF,MAAM,kBAAkB,OAAO;;;;;;;;;EAoB/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAkB7C;;;;;;;;;EAoBA,MAAM,oBAAoB,OAAO;;;;;;;;;EAoBjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAqBnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EA4B1E,OAAO;;;;;;;;;;;;;;EAyBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAmBf,MAAM,aAAa;;;;;;;;;EAoBnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAalD"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;KACY,UAAU,cAAc;;;;;;;;;;KAWxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;;;KAmBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;;;;;KASrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;KAGzD;;EAEV;;EAEA;;;KC3FU;;qBAOC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;qBChBD,WAAW;WAaJ;;UAXV;;;;;;;;;EAWU,YAAA,iBAChB,2BACA,cAAc;;;;;;;;;EAuBhB,MAAM,kBAAkB,OAAO;;;;;;;;;EAoB/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAkB7C;;;;;;;;;EAoBA,MAAM,oBAAoB,OAAO;;;;;;;;;EAoBjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAqBnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EA4B1E,OAAO;;;;;;;;;;;;;;EAyBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAmBf,MAAM,aAAa;;;;;;;;;EAoBnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAalD"}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 
-//#region src/typescript/types/type.d.ts
 /** Unsigned 32-bit structural words, accepted as a typed view or JSON numeric array. */
 type U32List = Uint32Array | ReadonlyArray<number>;
 /**
@@ -9,6 +8,7 @@ type U32List = Uint32Array | ReadonlyArray<number>;
  * 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.
+ * In tuple mode, `anchorDiff` is the stable index and diff is `1` or `-1`.
  */
 type InsertionWords = U32List;
 /**
@@ -45,13 +45,19 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * It uses one UTF-16 code unit per Frame. Missing slots use
  * NUL (`\u0000`); hydration splits the string with `split('')`.
  * `[[], []]` is an empty Sequence. Both numeric arrays and typed views are accepted.
+ * Tuple metadata prefixes the payload with `[0xffffffff, 1, maxLength, length]`;
+ * `maxLength = 0xffffffff` denotes dynamic growth. Tuple indices are never translated.
  */
 type Sequence<T, StringEncoded extends boolean = false> = Readonly<[
 /** Acknowledgements followed by canonical Insertions in Structural Order. */
 words: U32List,
 /** Consecutive positive Insertion spans, including missing Footage slots. */
 footage: StringEncoded extends true ? string : ReadonlyArray<T | undefined>]>;
-/** Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively. */
+/**
+ * Visible mutation: insertion uses `[at, at, values]`; removal ends exclusively.
+ * Tuple changes assign one stable index using `[index, index + 1, [value]]`;
+ * an empty register supplies `undefined`, without shifting other indices.
+ */
 type Splice<T> = Readonly<[
 /** First affected position in the Projection after preceding Splices. */
 startAt: number,
@@ -63,8 +69,13 @@ values?: ReadonlyArray<T | undefined>]>;
 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/errors/class.d.ts
+/** Stable-index register configuration; omitting maxLength permits dynamic growth. */
+type TupleParams = {
+  /** Whether indices remain fixed when values are inserted or removed. */
+  enabled: boolean | 0 | 1;
+  /** Fixed number of registers, indices must be in `0..maxLength - 1`. */
+  maxLength?: number;
+};
 /** Semantic error codes reported by the Sequencer public API. */
 type SequencerErrorCode = 'UNKNOWN_ERROR' | 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
@@ -80,8 +91,6 @@ export declare class SequencerError extends Error {
    */
   constructor(code: SequencerErrorCode, message?: string, options?: ErrorOptions);
 }
-//#endregion
-//#region src/typescript/class.d.ts
 /** Visible Projection of a replicated Sequence. */
 export declare class Projection<T> {
   readonly actorID: number;
@@ -92,9 +101,10 @@ export declare class Projection<T> {
    *
    * @param actorID Actor identifier used in acknowledgements.
    * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
+   * @param tupleParams Enables stable indices, optionally bounded by a fixed length. Tuple Sequences retain this configuration.
    * @throws {@link SequencerError} if native initialization fails.
    */
-  constructor(actorID: number, trustedSequence?: unknown);
+  constructor(actorID: number, trustedSequence?: unknown, tupleParams?: TupleParams);
   /**
    * Applies gossiped Insertions and Acknowledgements.
    *
@@ -108,7 +118,7 @@ export declare class Projection<T> {
    * Inserts values at a Projection position.
    *
    * @param values Nonempty array of values to insert.
-   * @param at Insertion position in `0..length()`, inclusive.
+   * @param at Insertion position in `0..length()`, inclusive. In tuple mode, the first stable index to write; each value creates a competing version.
    * @returns Gossip describing the insertion.
    * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
@@ -116,7 +126,7 @@ export declare class Projection<T> {
   /**
    * Returns the length, A.K.A. amount of entries of this projection.
    *
-   * @returns Current Projection length.
+   * @returns Current Projection length. Tuples retain their fixed length or highest written boundary, including empty registers.
    * @throws {@link SequencerError} with code `PROJECTION_DESTROYED` after destruction.
    */
   length(): number;
@@ -134,7 +144,7 @@ export declare class Projection<T> {
    *
    * @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.
+   * @returns Reducing Insertions and their acknowledgement as Gossip. Tuple removal targets all known active versions without shifting indices.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   remove(startAt?: number, endWith?: number): Gossip<T>;
@@ -144,7 +154,7 @@ export declare class Projection<T> {
    * @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.
+   * @returns Removal and insertion Gossip, in that order. Tuple replacement removes known versions and writes consecutive stable indices.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
    */
   replace(withValues: Array<T>, startAt?: number, endWith?: number): Gossip<T>;
@@ -193,6 +203,5 @@ export declare class Projection<T> {
   /** Destroys the Projection. Repeated calls have no effect. */
   destroy(): void;
 }
-//#endregion
-export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, U32List };
+export type { Acknowledgement, Change, Gossip, Insertion, InsertionWords, Result, Sequence, SequencerErrorCode, Splice, TupleParams, U32List };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;;KACY,UAAU,cAAc;;;;;;;;;KAUxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;KAiBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;KAKrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;;;KC7EzD;;qBAOC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBChBD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAuBF,MAAM,kBAAkB,OAAO;;;;;;;;;EAoB/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAkB7C;;;;;;;;;EAoBA,MAAM,oBAAoB,OAAO;;;;;;;;;EAoBjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAqBnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EA4B1E,OAAO;;;;;;;;;;;;;;EAyBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAmBf,MAAM,aAAa;;;;;;;;;EAoBnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAalD"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/typescript/types/type.ts","../src/typescript/errors/class.ts","../src/typescript/class.ts"],"mappings":";;KACY,UAAU,cAAc;;;;;;;;;;KAWxB,iBAAiB;;;;;;KAOjB,UAAU,KAAK;;AAGvB,OAAO;;AAEP,UAAU,cAAc;;;;;;;;KAWhB,kBAAkB;;KAGlB,OAAO,KAAK,cAAc,kBAAkB,UAAU;;;;;;;;;;;;;;;;;;KAmBtD,SAAS,GAAG,yCAAyC;;AAG7D,OAAO;;AAEP,SAAS,sCAAsC,cAAc;;;;;;KASrD,OAAO,KAAK;;AAGpB;;AAEA;;AAEA,SAAS,cAAc;;KAKf,OAAO,KAAK,cAAc,OAAO;;KAEjC,OAAO,KAAK,UAAU,QAAQ,OAAO,IAAI,SAAS,OAAO;;KAGzD;;EAEV;;EAEA;;;KC3FU;;qBAOC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;qBChBD,WAAW;WAaJ;;UAXV;;;;;;;;;EAWU,YAAA,iBAChB,2BACA,cAAc;;;;;;;;;EAuBhB,MAAM,kBAAkB,OAAO;;;;;;;;;EAoB/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAkB7C;;;;;;;;;EAoBA,MAAM,oBAAoB,OAAO;;;;;;;;;EAoBjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAqBnD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EA4B1E,OAAO;;;;;;;;;;;;;;EAyBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAmBf,MAAM,aAAa;;;;;;;;;EAoBnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAalD"}