@sovereignbase/sequencer 1.0.2 → 1.1.0

package/dist/index.d.cts

@@ -33,7 +33,7 @@ type Acknowledgement = U32List;
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
  * Retained state required to hydrate the same visible Projection.
- * One structural array and one JavaScript-owned content array.
+ * One structural array and JavaScript-owned Footage.
  * 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.
@@ -41,13 +41,16 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * Eligible masks, deleted Footage and compacted Session claims are omitted;
  * Actor membership remains. Compaction may translate retained coordinates.
  * Positive insertion diffs consume successive spans of `footage`.
+ * String-encoded Footage preserves Insertion order, not visible text order.
+ * 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.
  */
-type Sequence<T> = Readonly<[
+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: ReadonlyArray<T | undefined>]>;
+footage: StringEncoded extends true ? string : 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. */
@@ -63,7 +66,7 @@ type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/errors/class.d.ts
 /** Semantic error codes reported by the Sequencer public API. */
-type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED';
+type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
 export declare class SequencerError extends Error {
   /** Machine-readable code identifying the failure condition. */
@@ -88,7 +91,7 @@ export declare class Projection<T> {
    * 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.
+   * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
    * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
@@ -164,10 +167,12 @@ export declare class Projection<T> {
    * permit masks and deleted Footage to be omitted from the retained checkpoint.
    * Compaction may translate retained anchors without rewriting this instance.
    *
+   * @param stringEncode Whether to concatenate Footage into a string; each text Frame must be one UTF-16 code unit. Defaults to `false`.
    * @returns A Sequence with acknowledged removals compacted in the exported state.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
+   * @throws {@link SequencerError} with code `STRING_ENCODING_FAILED` if Footage concatenation fails.
    */
-  sequence(): Sequence<T>;
+  sequence<StringEncoded extends boolean = false>(stringEncode?: StringEncoded): Sequence<T, StringEncoded>;
   /**
    * Returns the value at a Projection position.
    *

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;;;;;;;;;;;;;KActD,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;;;;KC1EzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;EAeP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}
+{"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;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;;;EAiBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAWf,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type Acknowledgement = U32List;
 type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
 /**
  * Retained state required to hydrate the same visible Projection.
- * One structural array and one JavaScript-owned content array.
+ * One structural array and JavaScript-owned Footage.
  * 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.
@@ -41,13 +41,16 @@ type Gossip<T> = ReadonlyArray<Acknowledgement | Insertion<T>>;
  * Eligible masks, deleted Footage and compacted Session claims are omitted;
  * Actor membership remains. Compaction may translate retained coordinates.
  * Positive insertion diffs consume successive spans of `footage`.
+ * String-encoded Footage preserves Insertion order, not visible text order.
+ * 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.
  */
-type Sequence<T> = Readonly<[
+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: ReadonlyArray<T | undefined>]>;
+footage: StringEncoded extends true ? string : 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. */
@@ -63,7 +66,7 @@ type Result<T> = Readonly<[change: Change<T>, gossip?: Gossip<T>]>;
 //#endregion
 //#region src/typescript/errors/class.d.ts
 /** Semantic error codes reported by the Sequencer public API. */
-type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED';
+type SequencerErrorCode = 'PROJECTION_DESTROYED' | 'NATIVE_OPERATION_FAILED' | 'STRING_ENCODING_FAILED';
 /** Error reported by Sequencer with a stable code and package-prefixed message. */
 export declare class SequencerError extends Error {
   /** Machine-readable code identifying the failure condition. */
@@ -88,7 +91,7 @@ export declare class Projection<T> {
    * 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.
+   * @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
    * @throws {@link SequencerError} if native initialization fails.
    */
   constructor(actorID: number, trustedSequence?: unknown);
@@ -164,10 +167,12 @@ export declare class Projection<T> {
    * permit masks and deleted Footage to be omitted from the retained checkpoint.
    * Compaction may translate retained anchors without rewriting this instance.
    *
+   * @param stringEncode Whether to concatenate Footage into a string; each text Frame must be one UTF-16 code unit. Defaults to `false`.
    * @returns A Sequence with acknowledged removals compacted in the exported state.
    * @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
+   * @throws {@link SequencerError} with code `STRING_ENCODING_FAILED` if Footage concatenation fails.
    */
-  sequence(): Sequence<T>;
+  sequence<StringEncoded extends boolean = false>(stringEncode?: StringEncoded): Sequence<T, StringEncoded>;
   /**
    * Returns the value at a Projection position.
    *

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;;;;;;;;;;;;;KActD,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;;;;KC1EzD;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;EAeP,YAAY,SAAS;;;;;;;;EAWrB,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}
+{"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;;qBAIC,uBAAuB;;WAEzB,MAAM;;;;;;;;EAUb,YAAA,MAAM,oBACN,kBACA,UAAU;;;;;qBCdD,WAAW;WAYJ;;UAVV;;;;;;;;EAUU,YAAA,iBAChB;;;;;;;;;EAaF,MAAM,kBAAkB,OAAO;;;;;;;;;EAY/B,OAAO,QAAQ,MAAM,IAAI,aAAa,OAAO;;;;;;;EAU7C;;;;;;;;;EAYA,MAAM,oBAAoB,OAAO;;;;;;;;;EAYjC,OAAO,kBAAkB,mBAAmB,OAAO;;;;;;;;;;EAanD,QAAQ,YAAY,MAAM,IAAI,kBAAkB,mBAAmB,OAAO;;;;;;;;;;;EAoB1E,OAAO;;;;;;;;;;;;;;EAiBP,SAAS,uCACP,eAAe,gBACd,SAAS,GAAG;;;;;;;;EAWf,MAAM,aAAa;;;;;;;;;EAYnB,OAAO,kBAAkB,mBAAmB,MAAM;;EAKlD"}

package/dist/index.js

@@ -332,6 +332,11 @@ var Runtime = class {
 		const heap = module.HEAPU32;
 		return this.content[id][heap[pointer]]?.[heap[pointer + 1]];
 	}
+	/** Exports native spans directly, with optional string Footage assembled in JavaScript. */
+	sequence(id, stringEncode) {
+		if (id < 0) throw new SequencerError("PROJECTION_DESTROYED", "Projection has been destroyed.");
+		return this.result(Operation.Sequence, id, module._runtime_dispatch(Operation.Sequence, id, 0, 0, 0, 0, 0), stringEncode);
+	}
 	/** Authors trusted local Frames through the dedicated six-word result path. */
 	insert(id, values, at) {
 		if (id < 0) throw new SequencerError("PROJECTION_DESTROYED", "Projection has been destroyed.");
@@ -449,16 +454,16 @@ var Runtime = class {
 			a0 = value ?? absent;
 			a1 = at ?? absent;
 		} else if (operation === Operation.Retire) a0 = value;
-		else if (operation === Operation.Create || operation === Operation.Merge) {
+		else {
 			a0 = operation === Operation.Create ? value : 0;
 			const sequence = operation === Operation.Create ? at : value;
-			const valid = operation === Operation.Create && sequence === void 0 || Array.isArray(sequence) && sequence.length === 2 && (Array.isArray(sequence[0]) || sequence[0] instanceof Uint32Array) && Array.isArray(sequence[1]) && (operation === Operation.Create || sequence[0] instanceof Uint32Array || sequence[0].every((word) => Number.isInteger(word) && word >= 0 && word <= absent));
+			const valid = operation === Operation.Create && sequence === void 0 || Array.isArray(sequence) && sequence.length === 2 && (Array.isArray(sequence[0]) || sequence[0] instanceof Uint32Array) && (Array.isArray(sequence[1]) || typeof sequence[1] === "string") && (operation === Operation.Create || sequence[0] instanceof Uint32Array || sequence[0].every((word) => Number.isInteger(word) && word >= 0 && word <= absent));
 			a2 = valid ? 1 : 0;
 			if (valid && sequence !== void 0) {
 				const words = sequence[0];
 				heap.set(words, base);
 				a1 = contents.length;
-				footage = sequence[1];
+				footage = typeof sequence[1] === "string" ? sequence[1].split("") : sequence[1];
 			}
 		}
 		const resultPointer = module._runtime_dispatch(operation, id, a0, a1, a2, pointer, count);
@@ -472,7 +477,7 @@ var Runtime = class {
 		return this.result(operation, id, resultPointer);
 	}
 	/** Consumes borrowed native output before another call may overwrite its storage. */
-	result(operation, id, pointer) {
+	result(operation, id, pointer, stringEncode) {
 		const heap = module.HEAPU32, header = pointer >>> 2, content = this.content[id];
 		const kind = heap[header], p0 = heap[header + 3], n0 = heap[header + 4], p1 = heap[header + 5], n1 = heap[header + 6];
 		const mutable = this.mutable[id];
@@ -589,6 +594,22 @@ var Runtime = class {
 					metadata.length = n0;
 					for (let i = 0, at = p0 >>> 2; i < n0; ++i) metadata[i] = heap[at + i];
 				} else metadata = words(p0, n0);
+				if (stringEncode) {
+					let text = "";
+					try {
+						for (let at = p1 >>> 2, end = at + n1 * 3; at < end; at += 3) {
+							const source = content[heap[at]], start = heap[at + 1], count = heap[at + 2];
+							for (let i = 0; i < count; ++i) {
+								const value = source?.[start + i];
+								text += value === void 0 ? "\0" : value;
+							}
+						}
+					} catch (cause) {
+						throw new SequencerError("STRING_ENCODING_FAILED", "Sequence Footage could not be encoded as a string.", { cause });
+					}
+					result = [metadata, text];
+					break;
+				}
 				const span = p1 >>> 2, token = heap[span];
 				const shared = n1 === 1 && heap[span + 1] === 0 && content[token]?.length === heap[span + 2] && !!mutable[token];
 				if (shared && mutable[token] !== 3) {
@@ -657,7 +678,7 @@ var Projection = class {
 	* 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.
+	* @param trustedSequence Optional trusted Sequence in Structural Order; string Footage is split into UTF-16 code units.
 	* @throws {@link SequencerError} if native initialization fails.
 	*/
 	constructor(actorID, trustedSequence) {
@@ -750,11 +771,13 @@ var Projection = class {
 	* permit masks and deleted Footage to be omitted from the retained checkpoint.
 	* Compaction may translate retained anchors without rewriting this instance.
 	*
+	* @param stringEncode Whether to concatenate Footage into a string; each text Frame must be one UTF-16 code unit. Defaults to `false`.
 	* @returns A Sequence with acknowledged removals compacted in the exported state.
 	* @throws {@link SequencerError} if destroyed or the native runtime reports an operation failure.
+	* @throws {@link SequencerError} with code `STRING_ENCODING_FAILED` if Footage concatenation fails.
 	*/
-	sequence() {
-		return runtime.call(Operation.Sequence, this.id);
+	sequence(stringEncode) {
+		return runtime.sequence(this.id, stringEncode);
 	}
 	/**
 	* Returns the value at a Projection position.