cesr-ts 0.2.3 → 0.3.0

package/esm/src/core/parser-attachment-collector.js

@@ -0,0 +1,154 @@
+import { parseAttachmentGroup } from "../parser/attachment-parser.js";
+import { sniff } from "../parser/cold-start.js";
+import { ColdStartError, ShortageError } from "./errors.js";
+import { isAttachmentDomain } from "./parser-constants.js";
+/**
+ * Parses and appends attachment groups for both:
+ * - normal trailing-attachment collection after frame start parse
+ * - pending-frame continuation after shortage pauses
+ */
+export class AttachmentCollector {
+    constructor(options) {
+        Object.defineProperty(this, "frameBoundaryPolicy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "attachmentVersionFallbackPolicy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "recoveryDiagnosticObserver", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "isFrameBoundaryAhead", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.frameBoundaryPolicy = options.frameBoundaryPolicy;
+        this.attachmentVersionFallbackPolicy =
+            options.attachmentVersionFallbackPolicy;
+        this.recoveryDiagnosticObserver = options.recoveryDiagnosticObserver;
+        this.isFrameBoundaryAhead = options.isFrameBoundaryAhead;
+    }
+    /**
+     * Collect attachments from the current stream head until a frame boundary
+     * (including `msg` message-domain frame start) or shortage pause is reached.
+     */
+    collectTrailingAttachments(input, version, streamVersion, seed = []) {
+        const attachments = [...seed];
+        let offset = 0;
+        while (offset < input.length) {
+            const nextCold = sniff(input.slice(offset));
+            if (nextCold === "msg") {
+                break;
+            }
+            if (nextCold === "ano") {
+                offset = this.consumeLeadingAno(input, offset);
+                continue;
+            }
+            if (!isAttachmentDomain(nextCold)) {
+                throw new ColdStartError(`Unsupported attachment cold code ${nextCold}`);
+            }
+            try {
+                if (this.isFrameBoundaryAhead(input.slice(offset), streamVersion, nextCold)) {
+                    break;
+                }
+                const { group, consumed } = parseAttachmentGroup(input.slice(offset), version, nextCold, {
+                    versionFallbackPolicy: this.attachmentVersionFallbackPolicy,
+                    onRecoveryDiagnostic: this.recoveryDiagnosticObserver,
+                });
+                attachments.push(group);
+                offset += consumed;
+                if (this.frameBoundaryPolicy.shouldStopAfterAttachmentGroupCollection()) {
+                    break;
+                }
+            }
+            catch (error) {
+                if (error instanceof ShortageError) {
+                    return {
+                        attachments,
+                        consumed: offset,
+                        pausedForShortage: true,
+                    };
+                }
+                throw error;
+            }
+        }
+        return {
+            attachments,
+            consumed: offset,
+            pausedForShortage: false,
+        };
+    }
+    /**
+     * Resume attachment parsing for a pending top-level frame.
+     *
+     * Emits no events directly; parser orchestration decides when to emit pending.
+     */
+    resumePendingFrame(input, pendingFrame, version, streamVersion) {
+        if (input.length === 0) {
+            return { consumed: 0, emitPending: false, shouldContinue: false };
+        }
+        let offset = 0;
+        const nextCold = sniff(input.slice(offset));
+        if (nextCold === "ano") {
+            offset = this.consumeLeadingAno(input, offset);
+            return {
+                consumed: offset,
+                emitPending: false,
+                shouldContinue: offset < input.length,
+            };
+        }
+        if (nextCold === "msg") {
+            return { consumed: 0, emitPending: true, shouldContinue: true };
+        }
+        if (!isAttachmentDomain(nextCold)) {
+            throw new ColdStartError(`Unsupported pending-frame continuation cold code ${nextCold}`);
+        }
+        if (this.isFrameBoundaryAhead(input.slice(offset), streamVersion, nextCold)) {
+            return { consumed: 0, emitPending: true, shouldContinue: true };
+        }
+        const { group, consumed } = parseAttachmentGroup(input.slice(offset), version, nextCold, {
+            versionFallbackPolicy: this.attachmentVersionFallbackPolicy,
+            onRecoveryDiagnostic: this.recoveryDiagnosticObserver,
+        });
+        pendingFrame.attachments.push(group);
+        offset += consumed;
+        if (this.frameBoundaryPolicy.shouldEmitPendingAfterAttachmentResume()) {
+            return { consumed: offset, emitPending: true, shouldContinue: false };
+        }
+        if (offset >= input.length) {
+            return { consumed: offset, emitPending: false, shouldContinue: false };
+        }
+        const afterCold = sniff(input.slice(offset));
+        if (afterCold === "ano") {
+            offset = this.consumeLeadingAno(input, offset);
+            return {
+                consumed: offset,
+                emitPending: false,
+                shouldContinue: offset < input.length,
+            };
+        }
+        if (afterCold === "msg") {
+            return { consumed: offset, emitPending: true, shouldContinue: true };
+        }
+        return { consumed: offset, emitPending: false, shouldContinue: true };
+    }
+    /** Fast-forward consecutive annotation separator bytes from a local offset. */
+    consumeLeadingAno(input, start) {
+        let offset = start;
+        while (offset < input.length && sniff(input.slice(offset)) === "ano") {
+            offset += 1;
+        }
+        return offset;
+    }
+}

package/esm/src/core/parser-constants.js

@@ -0,0 +1,74 @@
+import { CtrDexV2 } from "../tables/counter-codex.js";
+/** Default parser version context when no explicit selector is present. */
+export const DEFAULT_VERSION = { major: 2, minor: 0 };
+/** Native map-body counter codes that permit interleaved label parsing. */
+export const MAP_BODY_CODES = new Set([
+    CtrDexV2.MapBodyGroup,
+    CtrDexV2.BigMapBodyGroup,
+]);
+/** Counter code for stream or nested genus-version selector tokens. */
+export const GENUS_VERSION_CODE = CtrDexV2.KERIACDCGenusVersion;
+const FRAME_BOUNDARY_COUNTER_NAMES = new Set([
+    "BodyWithAttachmentGroup",
+    "BigBodyWithAttachmentGroup",
+    "NonNativeBodyGroup",
+    "BigNonNativeBodyGroup",
+    "FixBodyGroup",
+    "BigFixBodyGroup",
+    "MapBodyGroup",
+    "BigMapBodyGroup",
+    "GenericGroup",
+    "BigGenericGroup",
+    "KERIACDCGenusVersion",
+]);
+/** True when counter begins a top-level frame boundary domain. */
+export function isFrameBoundaryCounter(counter) {
+    return FRAME_BOUNDARY_COUNTER_NAMES.has(counter.name);
+}
+/** Counter names supported as frame starts in CESR-native domain. */
+export const FRAME_START_GROUP_NAMES = new Set([
+    "BodyWithAttachmentGroup",
+    "BigBodyWithAttachmentGroup",
+    "NonNativeBodyGroup",
+    "BigNonNativeBodyGroup",
+    "FixBodyGroup",
+    "BigFixBodyGroup",
+    "MapBodyGroup",
+    "BigMapBodyGroup",
+    "GenericGroup",
+    "BigGenericGroup",
+]);
+/** Wrapper counters whose payload encloses one full body+attachments frame. */
+export const BODY_WITH_ATTACHMENT_GROUP_NAMES = new Set([
+    "BodyWithAttachmentGroup",
+    "BigBodyWithAttachmentGroup",
+]);
+/** Non-native body counters whose payload is a texter-wrapped message body. */
+export const NON_NATIVE_BODY_GROUP_NAMES = new Set([
+    "NonNativeBodyGroup",
+    "BigNonNativeBodyGroup",
+]);
+/** Native body counters (fixed-field or map-body forms). */
+export const NATIVE_BODY_GROUP_NAMES = new Set([
+    "FixBodyGroup",
+    "BigFixBodyGroup",
+    "MapBodyGroup",
+    "BigMapBodyGroup",
+]);
+/** Generic counters whose payload contains one or more enclosed frames. */
+export const GENERIC_GROUP_NAMES = new Set([
+    "GenericGroup",
+    "BigGenericGroup",
+]);
+/** Domain-sensitive token size helper (qb64 vs qb2). */
+export function tokenSize(token, cold) {
+    return cold === "bny" ? token.fullSizeB2 : token.fullSize;
+}
+/** Domain-sensitive counter unit (quadlet count for txt, triplet count for bny). */
+export function quadletUnit(cold) {
+    return cold === "bny" ? 3 : 4;
+}
+/** Attachment parsing domains supported by the parser. */
+export function isAttachmentDomain(cold) {
+    return cold === "txt" || cold === "bny";
+}

package/esm/src/core/parser-deferred-frames.js

@@ -0,0 +1,73 @@
+/**
+ * Manages deferred frame emission lifecycle for parser orchestration.
+ *
+ * Contract reminder:
+ * - `pendingFrame` is older than any `queuedFrames`.
+ * - flush order must preserve stream encounter order.
+ */
+export class DeferredFrameLifecycle {
+    constructor() {
+        Object.defineProperty(this, "pendingFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "queuedFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+    }
+    /** Current pending top-level frame continuation, if any. */
+    get pending() {
+        return this.pendingFrame;
+    }
+    /** Whether enclosed deferred frames are queued for emission. */
+    hasQueued() {
+        return this.queuedFrames.length > 0;
+    }
+    /** Store a pending top-level frame continuation. */
+    setPending(frame, version) {
+        this.pendingFrame = { frame, version };
+    }
+    /** Clear pending top-level frame continuation state. */
+    clearPending() {
+        this.pendingFrame = null;
+    }
+    /** Append enclosed frames parsed from one bounded GenericGroup payload. */
+    enqueueQueued(frames) {
+        if (frames.length === 0) {
+            return;
+        }
+        this.queuedFrames.push(...frames);
+    }
+    /** Emit next queued enclosed frame (FIFO) when no pending frame remains. */
+    shiftQueued() {
+        return this.queuedFrames.shift();
+    }
+    /**
+     * Flush deferred frames in normative order: pending first, queued next.
+     * Buffer-remainder shortage handling is outside this collaborator.
+     */
+    flushDeferred() {
+        const out = [];
+        if (this.pendingFrame) {
+            out.push({ type: "frame", frame: this.pendingFrame.frame });
+            this.pendingFrame = null;
+        }
+        while (this.queuedFrames.length > 0) {
+            const frame = this.queuedFrames.shift();
+            if (frame) {
+                out.push({ type: "frame", frame });
+            }
+        }
+        return out;
+    }
+    /** Clear all deferred frame lifecycle state. */
+    reset() {
+        this.pendingFrame = null;
+        this.queuedFrames = [];
+    }
+}