cesr-ts 0.1.0

package/esm/src/annotate/render.js

@@ -0,0 +1,246 @@
+import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError, } from "../core/errors.js";
+import { sniff } from "../parser/cold-start.js";
+import { parseCounter } from "../primitives/counter.js";
+import { parseMatter } from "../primitives/matter.js";
+import { parseIndexer } from "../primitives/indexer.js";
+import { parseAttachmentDispatchCompat } from "../parser/group-dispatch.js";
+import { counterCodeNameForVersion, matterCodeName, nativeLabelName, } from "./comments.js";
+const TEXT_DECODER = new TextDecoder();
+const TEXT_ENCODER = new TextEncoder();
+const OPAQUE_TOKEN_COMMENT = "opaque token";
+const OPAQUE_WRAPPER_PAYLOAD_COMMENT = "opaque wrapper payload";
+const WRAPPER_GROUP_NAMES = new Set([
+    "AttachmentGroup",
+    "BigAttachmentGroup",
+    "BodyWithAttachmentGroup",
+    "BigBodyWithAttachmentGroup",
+]);
+function toHex(bytes) {
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isRecoverableParseError(error) {
+    return error instanceof UnknownCodeError ||
+        error instanceof DeserializeError ||
+        error instanceof ShortageError ||
+        error instanceof GroupSizeError;
+}
+function spaces(count) {
+    return " ".repeat(Math.max(0, count));
+}
+function asDomain(raw) {
+    try {
+        const cold = sniff(raw);
+        if (cold === "txt" || cold === "bny" || cold === "msg")
+            return cold;
+    }
+    catch (error) {
+        if (!isRecoverableParseError(error)) {
+            throw error;
+        }
+        // Fallback handled below.
+    }
+    return "msg";
+}
+function emitLine(lines, value, comment, indent, options) {
+    const pad = spaces(indent);
+    if (options.commentMode === "above") {
+        lines.push(`${pad}# ${comment}`);
+        lines.push(`${pad}${value}`);
+        return;
+    }
+    lines.push(`${pad}${value} # ${comment}`);
+}
+function describeToken(token, domain, version) {
+    const input = TEXT_ENCODER.encode(token);
+    try {
+        const counter = parseCounter(input, version, domain);
+        return {
+            comment: `${counterCodeNameForVersion(counter.code, version)} counter`,
+            size: domain === "bny" ? counter.fullSizeB2 : counter.fullSize,
+        };
+    }
+    catch (error) {
+        if (!isRecoverableParseError(error)) {
+            throw error;
+        }
+        // Try indexer/matter below.
+    }
+    try {
+        const indexer = parseIndexer(input, domain);
+        return {
+            comment: `Indexer ${indexer.code}`,
+            size: domain === "bny" ? indexer.fullSizeB2 : indexer.fullSize,
+        };
+    }
+    catch (error) {
+        if (!isRecoverableParseError(error)) {
+            throw error;
+        }
+        // Try matter below.
+    }
+    try {
+        const matter = parseMatter(input, domain);
+        return {
+            comment: matterCodeName(matter.code),
+            size: domain === "bny" ? matter.fullSizeB2 : matter.fullSize,
+        };
+    }
+    catch (error) {
+        if (!isRecoverableParseError(error)) {
+            throw error;
+        }
+        return {
+            comment: OPAQUE_TOKEN_COMMENT,
+            size: token.length,
+        };
+    }
+}
+function parseCounterCompat(input, version, domain) {
+    try {
+        return parseCounter(input, version, domain);
+    }
+    catch (error) {
+        if (!isRecoverableParseError(error)) {
+            throw error;
+        }
+        const alternate = version.major >= 2
+            ? { major: 1, minor: 0 }
+            : { major: 2, minor: 0 };
+        return parseCounter(input, alternate, domain);
+    }
+}
+function renderGroupItems(lines, items, version, indent, options) {
+    for (const item of items) {
+        if (typeof item === "string") {
+            const parsed = describeToken(item, "txt", version);
+            emitLine(lines, item, parsed.comment, indent, options);
+            continue;
+        }
+        if (item instanceof Uint8Array) {
+            emitLine(lines, `0x${toHex(item)}`, "raw qb2 quadlet fragment", indent, options);
+            continue;
+        }
+        if (Array.isArray(item)) {
+            renderGroupItems(lines, item, version, indent + options.indent, options);
+            continue;
+        }
+        if (item && typeof item === "object") {
+            const nested = item;
+            if (typeof nested.code === "string" && typeof nested.name === "string") {
+                emitLine(lines, `${nested.code}`, `${nested.name} nested group`, indent, options);
+            }
+            continue;
+        }
+    }
+}
+function renderAttachmentGroupRaw(lines, raw, version, indent, options) {
+    const domain = asDomain(raw);
+    if (domain !== "txt" && domain !== "bny") {
+        return 0;
+    }
+    const parsed = parseAttachmentDispatchCompat(raw, version, domain);
+    const counter = parseCounterCompat(raw, version, domain);
+    emitLine(lines, counter.qb64, `${parsed.group.name} count=${counter.count}`, indent, options);
+    const headerSize = domain === "bny" ? counter.fullSizeB2 : counter.fullSize;
+    const payload = raw.slice(headerSize, parsed.consumed);
+    if (WRAPPER_GROUP_NAMES.has(parsed.group.name)) {
+        // Wrapper groups contain nested groups by convention, but real-world
+        // streams may include trailing opaque segments. Keep annotation resilient.
+        let offset = 0;
+        while (offset < payload.length) {
+            const slice = payload.slice(offset);
+            const sliceCold = asDomain(slice);
+            if (sliceCold === "msg") {
+                break;
+            }
+            if (sliceCold === "txt" && slice[0] !== "-".charCodeAt(0)) {
+                break;
+            }
+            let consumed = 0;
+            try {
+                consumed = renderAttachmentGroupRaw(lines, slice, version, indent + options.indent, options);
+            }
+            catch (error) {
+                if (!isRecoverableParseError(error)) {
+                    throw error;
+                }
+                break;
+            }
+            if (consumed <= 0)
+                break;
+            offset += consumed;
+        }
+        if (offset < payload.length) {
+            const remainder = payload.slice(offset);
+            const unit = domain === "bny" ? 3 : 4;
+            for (let i = 0; i < remainder.length; i += unit) {
+                const chunk = remainder.slice(i, Math.min(i + unit, remainder.length));
+                const rendered = domain === "bny"
+                    ? `0x${toHex(chunk)}`
+                    : TEXT_DECODER.decode(chunk);
+                emitLine(lines, rendered, OPAQUE_WRAPPER_PAYLOAD_COMMENT, indent + options.indent, options);
+            }
+        }
+        return parsed.consumed;
+    }
+    renderGroupItems(lines, parsed.group.items, version, indent + options.indent, options);
+    return parsed.consumed;
+}
+function renderNativeBody(lines, frame, options, version) {
+    const raw = frame.serder.raw;
+    const domain = asDomain(raw);
+    if (domain !== "txt" && domain !== "bny") {
+        return;
+    }
+    const counter = parseCounterCompat(raw, version, domain);
+    emitLine(lines, counter.qb64, `${counterCodeNameForVersion(counter.code, version)} count=${counter.count}`, 0, options);
+    for (const field of frame.serder.native?.fields ?? []) {
+        const label = nativeLabelName(field.label);
+        const comment = label
+            ? `${label} (${matterCodeName(field.code)})`
+            : matterCodeName(field.code);
+        emitLine(lines, field.qb64, comment, options.indent, options);
+    }
+}
+function renderMessageBody(lines, frame, options) {
+    const rawBody = TEXT_DECODER.decode(frame.serder.raw);
+    let body = rawBody;
+    if (options.pretty && frame.serder.kind === "JSON") {
+        try {
+            body = JSON.stringify(JSON.parse(rawBody), null, 2);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError)) {
+                throw error;
+            }
+            body = rawBody;
+        }
+    }
+    const info = [
+        `SERDER`,
+        frame.serder.proto,
+        frame.serder.kind,
+        frame.serder.ilk ? `ilk=${frame.serder.ilk}` : null,
+        frame.serder.said ? `said=${frame.serder.said}` : null,
+    ].filter(Boolean).join(" ");
+    emitLine(lines, body, info, 0, options);
+}
+function renderFrame(frame, index, options) {
+    const lines = [];
+    const version = frame.serder.gvrsn ?? frame.serder.pvrsn;
+    const domain = asDomain(frame.serder.raw);
+    if (domain === "txt" || domain === "bny") {
+        renderNativeBody(lines, frame, options, version);
+    }
+    else {
+        renderMessageBody(lines, frame, options);
+    }
+    for (const group of frame.attachments) {
+        renderAttachmentGroupRaw(lines, group.raw, version, 0, options);
+    }
+    return { index, frame, lines };
+}
+/** Render parsed CESR frames into line-oriented, human-annotated text blocks. */
+export function renderAnnotatedFrames(frames, options) {
+    return frames.map((frame, index) => renderFrame(frame, index + 1, options));
+}

package/esm/src/annotate/types.js

@@ -0,0 +1 @@
+export {};

package/esm/src/core/bytes.js

@@ -0,0 +1,70 @@
+export const encoder = new TextEncoder();
+export const decoder = new TextDecoder();
+const B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+export function concatBytes(...chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+export function intToB64(value, length = 1) {
+    if (value < 0) {
+        throw new Error(`value must be >= 0, got ${value}`);
+    }
+    let v = value;
+    let out = "";
+    do {
+        out = B64_ALPHABET[v & 63] + out;
+        v = Math.floor(v / 64);
+    } while (v > 0);
+    if (out.length > length) {
+        throw new Error(`value ${value} too large for base64 length ${length}`);
+    }
+    return out.padStart(length, "A");
+}
+export function b64ToInt(text) {
+    let out = 0;
+    for (const ch of text) {
+        const idx = B64_ALPHABET.indexOf(ch);
+        if (idx < 0) {
+            throw new Error(`Invalid base64 char ${ch}`);
+        }
+        out = out * 64 + idx;
+    }
+    return out;
+}
+export function encodeB64(data) {
+    const str = btoa(String.fromCharCode(...data));
+    return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+export function decodeB64(text) {
+    const padded = text + "===".slice((text.length + 3) % 4);
+    const raw = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
+    const out = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++) {
+        out[i] = raw.charCodeAt(i);
+    }
+    return out;
+}
+export function sceil(value) {
+    return Math.ceil(value);
+}
+export function codeB64ToB2(text) {
+    const n = sceil((text.length * 3) / 4);
+    const full = text + "A".repeat((4 - (text.length % 4)) % 4);
+    return decodeB64(full).slice(0, n);
+}
+export function codeB2ToB64(bytes, sextets) {
+    const n = sceil((sextets * 3) / 4);
+    if (n > bytes.length) {
+        throw new Error(`Not enough bytes to convert ${sextets} sextets`);
+    }
+    return encodeB64(bytes.slice(0, n)).slice(0, sextets);
+}
+export function nabSextets(bytes, sextets) {
+    return codeB64ToB2(codeB2ToB64(bytes, sextets));
+}

package/esm/src/core/errors.js

@@ -0,0 +1,45 @@
+export class ParserError extends Error {
+    constructor(message, offset, context) {
+        super(message);
+        Object.defineProperty(this, "offset", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: offset
+        });
+        Object.defineProperty(this, "context", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: context
+        });
+        this.name = globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).name;
+    }
+}
+export class ShortageError extends ParserError {
+    constructor(needed, available, offset) {
+        super(`Need ${needed} bytes but only ${available} available`, offset);
+        Object.defineProperty(this, "needed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: needed
+        });
+        Object.defineProperty(this, "available", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: available
+        });
+    }
+}
+export class ColdStartError extends ParserError {
+}
+export class VersionError extends ParserError {
+}
+export class UnknownCodeError extends ParserError {
+}
+export class GroupSizeError extends ParserError {
+}
+export class DeserializeError extends ParserError {
+}