@zvndev/powdb-client 0.8.1 → 0.10.0

package/dist/cjs/protocol.js

@@ -0,0 +1,645 @@
+"use strict";
+/**
+ * PowDB wire protocol.
+ *
+ * Frame format: [type(1)][flags(1)][len(4 LE)][payload]
+ * Strings are encoded as [len(4 LE)][utf-8 bytes].
+ *
+ * This mirrors crates/server/src/protocol.rs — keep them in sync.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.MSG_PONG = exports.MSG_PING = exports.MSG_DISCONNECT = exports.MSG_RESULT_MSG = exports.MSG_ERROR = exports.MSG_RESULT_OK = exports.MSG_RESULT_SCALAR = exports.MSG_RESULT_ROWS = exports.MSG_SYNC_ACK_RESULT = exports.MSG_SYNC_PULL_RESULT = exports.MSG_SYNC_STATUS_RESULT = exports.MSG_SYNC_ACK = exports.MSG_SYNC_PULL = exports.MSG_SYNC_STATUS = exports.MSG_QUERY_SQL = exports.MSG_QUERY_PARAMS = exports.MSG_QUERY = exports.MSG_CONNECT_OK = exports.MSG_CONNECT = void 0;
+exports.encode = encode;
+exports.tryDecode = tryDecode;
+exports.MSG_CONNECT = 0x01;
+exports.MSG_CONNECT_OK = 0x02;
+exports.MSG_QUERY = 0x03;
+/**
+ * Query carrying positional `$N` parameters. Pure protocol addition: old
+ * servers reject it with the existing "unknown message type" error, and the
+ * plain `MSG_QUERY` frame is unchanged. Requires powdb-server ≥ 0.4.7.
+ */
+exports.MSG_QUERY_PARAMS = 0x04;
+/** SQL query frame. Plain Query remains PowQL for backward compatibility. */
+exports.MSG_QUERY_SQL = 0x05;
+/** Private embedded-sync control frames. Requires authenticated server support. */
+exports.MSG_SYNC_STATUS = 0x20;
+exports.MSG_SYNC_PULL = 0x21;
+exports.MSG_SYNC_ACK = 0x22;
+exports.MSG_SYNC_STATUS_RESULT = 0x23;
+exports.MSG_SYNC_PULL_RESULT = 0x24;
+exports.MSG_SYNC_ACK_RESULT = 0x25;
+exports.MSG_RESULT_ROWS = 0x07;
+exports.MSG_RESULT_SCALAR = 0x08;
+exports.MSG_RESULT_OK = 0x09;
+exports.MSG_ERROR = 0x0a;
+exports.MSG_RESULT_MSG = 0x0b;
+exports.MSG_DISCONNECT = 0x10;
+exports.MSG_PING = 0x11;
+exports.MSG_PONG = 0x12;
+// ───── Size limits (mirror crates/server/src/protocol.rs) ──────────────────
+/** Maximum payload size accepted from the wire (64 MB). */
+exports.MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
+/** Maximum number of rows allowed in a single result message. */
+exports.MAX_ROWS = 10_000_000;
+/** Maximum number of columns allowed in a result set. */
+exports.MAX_COLUMNS = 4096;
+/** Maximum number of bound parameters in a QueryWithParams message. */
+exports.MAX_PARAMS = 4096;
+/** Maximum retained units accepted in one sync pull result. */
+exports.MAX_SYNC_UNITS = 4096;
+/** Maximum retained units accepted by the server for one sync pull request. */
+exports.MAX_SYNC_PULL_UNITS = 4096;
+/** Maximum retained-unit payload budget accepted by the server for one sync pull. */
+exports.MAX_SYNC_PULL_BYTES = 16 * 1024 * 1024;
+// ───── Encoding ────────────────────────────────────────────────────────────
+function encode(msg) {
+    let msgType;
+    let payload;
+    switch (msg.type) {
+        case "Connect": {
+            const dbBuf = encodeString(msg.dbName);
+            const pwBuf = msg.password === null ? u32LE(0) : encodeString(msg.password);
+            // Username rides after the password (append-only extension, mirrors
+            // crates/server/src/protocol.rs). The server reads it only when bytes
+            // remain after the password, so omitting it when null keeps the frame
+            // byte-identical to the legacy 0.3.x shape.
+            const parts = [dbBuf, pwBuf];
+            if (msg.username !== null) {
+                parts.push(encodeString(msg.username));
+            }
+            payload = Buffer.concat(parts);
+            msgType = exports.MSG_CONNECT;
+            break;
+        }
+        case "ConnectOk":
+            payload = encodeString(msg.version);
+            msgType = exports.MSG_CONNECT_OK;
+            break;
+        case "Query":
+            payload = encodeString(msg.query);
+            msgType = exports.MSG_QUERY;
+            break;
+        case "QuerySql":
+            payload = encodeString(msg.query);
+            msgType = exports.MSG_QUERY_SQL;
+            break;
+        case "QueryWithParams": {
+            const parts = [encodeString(msg.query)];
+            const count = Buffer.alloc(2);
+            count.writeUInt16LE(msg.params.length, 0);
+            parts.push(count);
+            for (const p of msg.params) {
+                switch (p.tag) {
+                    case "null":
+                        parts.push(Buffer.from([0]));
+                        break;
+                    case "int": {
+                        const b = Buffer.alloc(9);
+                        b.writeUInt8(1, 0);
+                        b.writeBigInt64LE(p.value, 1);
+                        parts.push(b);
+                        break;
+                    }
+                    case "float": {
+                        const b = Buffer.alloc(9);
+                        b.writeUInt8(2, 0);
+                        b.writeDoubleLE(p.value, 1);
+                        parts.push(b);
+                        break;
+                    }
+                    case "bool":
+                        parts.push(Buffer.from([3, p.value ? 1 : 0]));
+                        break;
+                    case "str":
+                        parts.push(Buffer.from([4]), encodeString(p.value));
+                        break;
+                }
+            }
+            payload = Buffer.concat(parts);
+            msgType = exports.MSG_QUERY_PARAMS;
+            break;
+        }
+        case "SyncStatus":
+            payload = encodeString(msg.replicaId);
+            msgType = exports.MSG_SYNC_STATUS;
+            break;
+        case "SyncPull": {
+            if (msg.databaseId.length !== 16) {
+                throw new Error(`sync databaseId must be exactly 16 bytes, got ${msg.databaseId.length}`);
+            }
+            payload = Buffer.concat([
+                encodeString(msg.replicaId),
+                u64LE(msg.sinceLsn),
+                u32LE(msg.maxUnits),
+                u64LE(msg.maxBytes),
+                msg.databaseId,
+                u64LE(msg.primaryGeneration),
+                u16LE(msg.walFormatVersion),
+                u16LE(msg.catalogVersion),
+                u16LE(msg.segmentFormatVersion),
+            ]);
+            msgType = exports.MSG_SYNC_PULL;
+            break;
+        }
+        case "SyncAck":
+            payload = Buffer.concat([
+                encodeString(msg.replicaId),
+                u64LE(msg.appliedLsn),
+                u64LE(msg.remoteLsn),
+            ]);
+            msgType = exports.MSG_SYNC_ACK;
+            break;
+        case "SyncStatusResult":
+            payload = encodeSyncStatus(msg.status);
+            msgType = exports.MSG_SYNC_STATUS_RESULT;
+            break;
+        case "SyncPullResult": {
+            const parts = [
+                encodeSyncStatus(msg.status),
+                u32LE(msg.units.length),
+            ];
+            for (const unit of msg.units) {
+                parts.push(encodeRetainedUnit(unit));
+            }
+            parts.push(Buffer.from([msg.hasMore ? 1 : 0]));
+            payload = Buffer.concat(parts);
+            msgType = exports.MSG_SYNC_PULL_RESULT;
+            break;
+        }
+        case "SyncAckResult":
+            payload = Buffer.concat([
+                u64LE(msg.previousAppliedLsn),
+                u64LE(msg.appliedLsn),
+                u64LE(msg.remoteLsn),
+                Buffer.from([msg.advanced ? 1 : 0]),
+                encodeSyncStatus(msg.status),
+            ]);
+            msgType = exports.MSG_SYNC_ACK_RESULT;
+            break;
+        case "ResultRows": {
+            const parts = [];
+            const colCount = Buffer.alloc(2);
+            colCount.writeUInt16LE(msg.columns.length, 0);
+            parts.push(colCount);
+            for (const col of msg.columns)
+                parts.push(encodeString(col));
+            parts.push(u32LE(msg.rows.length));
+            for (const row of msg.rows) {
+                for (const val of row)
+                    parts.push(encodeString(val));
+            }
+            payload = Buffer.concat(parts);
+            msgType = exports.MSG_RESULT_ROWS;
+            break;
+        }
+        case "ResultScalar":
+            payload = encodeString(msg.value);
+            msgType = exports.MSG_RESULT_SCALAR;
+            break;
+        case "ResultOk": {
+            payload = Buffer.alloc(8);
+            payload.writeBigUInt64LE(msg.affected, 0);
+            msgType = exports.MSG_RESULT_OK;
+            break;
+        }
+        case "ResultMessage":
+            payload = encodeString(msg.message);
+            msgType = exports.MSG_RESULT_MSG;
+            break;
+        case "Error":
+            payload = encodeString(msg.message);
+            msgType = exports.MSG_ERROR;
+            break;
+        case "Disconnect":
+            payload = Buffer.alloc(0);
+            msgType = exports.MSG_DISCONNECT;
+            break;
+        case "Ping":
+            payload = Buffer.alloc(0);
+            msgType = exports.MSG_PING;
+            break;
+        case "Pong":
+            payload = Buffer.alloc(0);
+            msgType = exports.MSG_PONG;
+            break;
+    }
+    const frame = Buffer.alloc(6 + payload.length);
+    frame.writeUInt8(msgType, 0);
+    frame.writeUInt8(0, 1); // flags
+    frame.writeUInt32LE(payload.length, 2);
+    payload.copy(frame, 6);
+    return frame;
+}
+// ───── Decoding ────────────────────────────────────────────────────────────
+/**
+ * Attempts to parse a single frame from the start of `buf`. Returns the parsed
+ * message and the number of bytes consumed, or `null` if the buffer does not
+ * yet contain a complete frame.
+ */
+function tryDecode(buf) {
+    if (buf.length < 6)
+        return null;
+    const msgType = buf.readUInt8(0);
+    // flags byte at offset 1 is currently unused
+    const payloadLen = buf.readUInt32LE(2);
+    if (payloadLen > exports.MAX_PAYLOAD_SIZE) {
+        throw new Error(`payload too large: ${payloadLen} bytes (max ${exports.MAX_PAYLOAD_SIZE})`);
+    }
+    if (buf.length < 6 + payloadLen)
+        return null;
+    const payload = buf.subarray(6, 6 + payloadLen);
+    const msg = decodePayload(msgType, payload);
+    return { msg, consumed: 6 + payloadLen };
+}
+function decodePayload(msgType, payload) {
+    const cursor = { pos: 0 };
+    switch (msgType) {
+        case exports.MSG_CONNECT: {
+            const dbName = decodeString(payload, cursor);
+            let password = null;
+            if (cursor.pos < payload.length) {
+                const p = decodeString(payload, cursor);
+                password = p.length === 0 ? null : p;
+            }
+            // Optional trailing username (mirror the server: present only when
+            // bytes remain after the password; empty string means null).
+            let username = null;
+            if (cursor.pos < payload.length) {
+                const u = decodeString(payload, cursor);
+                username = u.length === 0 ? null : u;
+            }
+            return { type: "Connect", dbName, password, username };
+        }
+        case exports.MSG_CONNECT_OK:
+            return { type: "ConnectOk", version: decodeString(payload, cursor) };
+        case exports.MSG_QUERY:
+            return { type: "Query", query: decodeString(payload, cursor) };
+        case exports.MSG_QUERY_SQL: {
+            const query = decodeString(payload, cursor);
+            return { type: "QuerySql", query };
+        }
+        case exports.MSG_QUERY_PARAMS: {
+            const query = decodeString(payload, cursor);
+            const count = readU16(payload, cursor, "param count");
+            if (count > exports.MAX_PARAMS) {
+                throw new Error(`too many parameters: ${count} (max ${exports.MAX_PARAMS})`);
+            }
+            const params = [];
+            for (let i = 0; i < count; i++) {
+                const tag = readU8(payload, cursor, "param tag");
+                switch (tag) {
+                    case 0:
+                        params.push({ tag: "null" });
+                        break;
+                    case 1:
+                        params.push({ tag: "int", value: readI64(payload, cursor, "int param") });
+                        break;
+                    case 2:
+                        params.push({ tag: "float", value: readF64(payload, cursor, "float param") });
+                        break;
+                    case 3:
+                        params.push({ tag: "bool", value: readU8(payload, cursor, "bool param") !== 0 });
+                        break;
+                    case 4:
+                        params.push({ tag: "str", value: decodeString(payload, cursor) });
+                        break;
+                    default:
+                        throw new Error(`unknown param tag: ${tag}`);
+                }
+            }
+            return { type: "QueryWithParams", query, params };
+        }
+        case exports.MSG_SYNC_STATUS:
+            return { type: "SyncStatus", replicaId: decodeString(payload, cursor) };
+        case exports.MSG_SYNC_PULL: {
+            const replicaId = decodeString(payload, cursor);
+            const sinceLsn = readU64(payload, cursor, "sync pull since LSN");
+            const maxUnits = readU32(payload, cursor, "sync pull max units");
+            const maxBytes = readU64(payload, cursor, "sync pull max bytes");
+            const databaseId = readFixedBytes(payload, cursor, 16, "sync database id");
+            const primaryGeneration = readU64(payload, cursor, "sync primary generation");
+            const walFormatVersion = readU16(payload, cursor, "sync WAL format version");
+            const catalogVersion = readU16(payload, cursor, "sync catalog version");
+            const segmentFormatVersion = readU16(payload, cursor, "sync segment format version");
+            return {
+                type: "SyncPull",
+                replicaId,
+                sinceLsn,
+                maxUnits,
+                maxBytes,
+                databaseId,
+                primaryGeneration,
+                walFormatVersion,
+                catalogVersion,
+                segmentFormatVersion,
+            };
+        }
+        case exports.MSG_SYNC_ACK: {
+            const replicaId = decodeString(payload, cursor);
+            const appliedLsn = readU64(payload, cursor, "sync ack applied LSN");
+            const remoteLsn = readU64(payload, cursor, "sync ack remote LSN");
+            return { type: "SyncAck", replicaId, appliedLsn, remoteLsn };
+        }
+        case exports.MSG_SYNC_STATUS_RESULT:
+            return {
+                type: "SyncStatusResult",
+                status: decodeSyncStatus(payload, cursor),
+            };
+        case exports.MSG_SYNC_PULL_RESULT: {
+            const status = decodeSyncStatus(payload, cursor);
+            const count = readU32(payload, cursor, "sync retained unit count");
+            if (count > exports.MAX_SYNC_UNITS) {
+                throw new Error(`too many retained units: ${count} (max ${exports.MAX_SYNC_UNITS})`);
+            }
+            const units = [];
+            for (let i = 0; i < count; i++) {
+                units.push(decodeRetainedUnit(payload, cursor));
+            }
+            const hasMore = readBool(payload, cursor, "sync has_more");
+            return { type: "SyncPullResult", status, units, hasMore };
+        }
+        case exports.MSG_SYNC_ACK_RESULT: {
+            const previousAppliedLsn = readU64(payload, cursor, "previous applied LSN");
+            const appliedLsn = readU64(payload, cursor, "applied LSN");
+            const remoteLsn = readU64(payload, cursor, "remote LSN");
+            const advanced = readBool(payload, cursor, "sync ack advanced");
+            const status = decodeSyncStatus(payload, cursor);
+            return {
+                type: "SyncAckResult",
+                previousAppliedLsn,
+                appliedLsn,
+                remoteLsn,
+                advanced,
+                status,
+            };
+        }
+        case exports.MSG_RESULT_ROWS: {
+            const colCount = readU16(payload, cursor, "column count");
+            if (colCount > exports.MAX_COLUMNS) {
+                throw new Error(`too many columns: ${colCount} (max ${exports.MAX_COLUMNS})`);
+            }
+            const columns = [];
+            for (let i = 0; i < colCount; i++) {
+                columns.push(decodeString(payload, cursor));
+            }
+            const rowCount = readU32(payload, cursor, "row count");
+            if (rowCount > exports.MAX_ROWS) {
+                throw new Error(`too many rows: ${rowCount} (max ${exports.MAX_ROWS})`);
+            }
+            if (colCount === 0 && rowCount > 0) {
+                throw new Error("nonzero row count with zero columns");
+            }
+            const remaining = BigInt(payload.length - cursor.pos);
+            const minRowBytes = BigInt(rowCount) * BigInt(colCount) * 4n;
+            if (remaining < minRowBytes) {
+                throw new Error(`row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
+            }
+            const rows = [];
+            for (let r = 0; r < rowCount; r++) {
+                const row = [];
+                for (let c = 0; c < colCount; c++) {
+                    row.push(decodeString(payload, cursor));
+                }
+                rows.push(row);
+            }
+            return { type: "ResultRows", columns, rows };
+        }
+        case exports.MSG_RESULT_SCALAR:
+            return { type: "ResultScalar", value: decodeString(payload, cursor) };
+        case exports.MSG_RESULT_OK: {
+            const affected = readU64(payload, cursor, "affected count");
+            return { type: "ResultOk", affected };
+        }
+        case exports.MSG_RESULT_MSG:
+            return { type: "ResultMessage", message: decodeString(payload, cursor) };
+        case exports.MSG_ERROR:
+            return { type: "Error", message: decodeString(payload, cursor) };
+        case exports.MSG_DISCONNECT:
+            return { type: "Disconnect" };
+        case exports.MSG_PING:
+            return { type: "Ping" };
+        case exports.MSG_PONG:
+            return { type: "Pong" };
+        default:
+            throw new Error(`unknown message type: 0x${msgType.toString(16)}`);
+    }
+}
+function encodeSyncStatus(status) {
+    return Buffer.concat([
+        encodeString(status.replicaId),
+        Buffer.from([status.active ? 1 : 0]),
+        encodeOptionalU64(status.lastAppliedLsn),
+        u64LE(status.remoteLsn),
+        encodeOptionalU64(status.servableLsn),
+        encodeOptionalU64(status.unarchivedLsn),
+        encodeOptionalU64(status.lagLsn),
+        encodeOptionalU64(status.lagBytes),
+        encodeOptionalU64(status.lagMs),
+        Buffer.from([
+            status.stale ? 1 : 0,
+            encodeRepairAction(status.repairAction),
+        ]),
+        encodeOptionalString(status.lastSyncError),
+    ]);
+}
+function decodeSyncStatus(buf, cursor) {
+    const replicaId = decodeString(buf, cursor);
+    const active = readBool(buf, cursor, "sync status active");
+    const lastAppliedLsn = readOptionalU64(buf, cursor, "sync status last applied LSN");
+    const remoteLsn = readU64(buf, cursor, "sync status remote LSN");
+    const servableLsn = readOptionalU64(buf, cursor, "sync status servable LSN");
+    const unarchivedLsn = readOptionalU64(buf, cursor, "sync status unarchived LSN");
+    const lagLsn = readOptionalU64(buf, cursor, "sync status lag LSN");
+    const lagBytes = readOptionalU64(buf, cursor, "sync status lag bytes");
+    const lagMs = readOptionalU64(buf, cursor, "sync status lag milliseconds");
+    const stale = readBool(buf, cursor, "sync status stale");
+    const repairAction = decodeRepairAction(readU8(buf, cursor, "sync repair action"));
+    const lastSyncError = readOptionalString(buf, cursor, "sync status last error");
+    return {
+        replicaId,
+        active,
+        lastAppliedLsn,
+        remoteLsn,
+        servableLsn,
+        unarchivedLsn,
+        lagLsn,
+        lagBytes,
+        lagMs,
+        stale,
+        repairAction,
+        lastSyncError,
+    };
+}
+function encodeRetainedUnit(unit) {
+    return Buffer.concat([
+        u64LE(unit.txId),
+        Buffer.from([u8(unit.recordType, "sync retained unit record type")]),
+        u64LE(unit.lsn),
+        encodeBytes(unit.data),
+    ]);
+}
+function decodeRetainedUnit(buf, cursor) {
+    const txId = readU64(buf, cursor, "sync retained unit tx id");
+    const recordType = readU8(buf, cursor, "sync retained unit record type");
+    const lsn = readU64(buf, cursor, "sync retained unit LSN");
+    const data = readBytes(buf, cursor, "sync retained unit payload");
+    return { txId, recordType, lsn, data };
+}
+function encodeRepairAction(action) {
+    switch (action) {
+        case "none":
+            return 0;
+        case "pull":
+            return 1;
+        case "awaitArchive":
+            return 2;
+        case "rebootstrap":
+            return 3;
+    }
+}
+function decodeRepairAction(raw) {
+    switch (raw) {
+        case 0:
+            return "none";
+        case 1:
+            return "pull";
+        case 2:
+            return "awaitArchive";
+        case 3:
+            return "rebootstrap";
+        default:
+            throw new Error(`unknown sync repair action: ${raw}`);
+    }
+}
+function encodeOptionalU64(value) {
+    return value === null
+        ? Buffer.from([0])
+        : Buffer.concat([Buffer.from([1]), u64LE(value)]);
+}
+function readOptionalU64(buf, cursor, label) {
+    return readBool(buf, cursor, label) ? readU64(buf, cursor, label) : null;
+}
+function encodeOptionalString(value) {
+    return value === null
+        ? Buffer.from([0])
+        : Buffer.concat([Buffer.from([1]), encodeString(value)]);
+}
+function readOptionalString(buf, cursor, label) {
+    return readBool(buf, cursor, label) ? decodeString(buf, cursor) : null;
+}
+function encodeBytes(bytes) {
+    return Buffer.concat([u32LE(bytes.length), bytes]);
+}
+// ───── String helpers ──────────────────────────────────────────────────────
+function encodeString(s) {
+    const bytes = Buffer.from(s, "utf8");
+    const out = Buffer.alloc(4 + bytes.length);
+    out.writeUInt32LE(bytes.length, 0);
+    bytes.copy(out, 4);
+    return out;
+}
+function decodeString(buf, cursor) {
+    if (cursor.pos + 4 > buf.length) {
+        throw new Error("truncated string length");
+    }
+    const len = readU32(buf, cursor, "string length");
+    if (cursor.pos + len > buf.length) {
+        throw new Error("truncated string data");
+    }
+    const s = buf.toString("utf8", cursor.pos, cursor.pos + len);
+    cursor.pos += len;
+    return s;
+}
+function readU8(buf, cursor, label) {
+    if (cursor.pos + 1 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readUInt8(cursor.pos);
+    cursor.pos += 1;
+    return value;
+}
+function readBool(buf, cursor, label) {
+    const raw = readU8(buf, cursor, label);
+    if (raw === 0)
+        return false;
+    if (raw === 1)
+        return true;
+    throw new Error(`invalid boolean for ${label}: ${raw}`);
+}
+function readI64(buf, cursor, label) {
+    if (cursor.pos + 8 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readBigInt64LE(cursor.pos);
+    cursor.pos += 8;
+    return value;
+}
+function readF64(buf, cursor, label) {
+    if (cursor.pos + 8 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readDoubleLE(cursor.pos);
+    cursor.pos += 8;
+    return value;
+}
+function readU16(buf, cursor, label) {
+    if (cursor.pos + 2 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readUInt16LE(cursor.pos);
+    cursor.pos += 2;
+    return value;
+}
+function readU32(buf, cursor, label) {
+    if (cursor.pos + 4 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readUInt32LE(cursor.pos);
+    cursor.pos += 4;
+    return value;
+}
+function readU64(buf, cursor, label) {
+    if (cursor.pos + 8 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readBigUInt64LE(cursor.pos);
+    cursor.pos += 8;
+    return value;
+}
+function readFixedBytes(buf, cursor, len, label) {
+    if (cursor.pos + len > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = Buffer.from(buf.subarray(cursor.pos, cursor.pos + len));
+    cursor.pos += len;
+    return value;
+}
+function readBytes(buf, cursor, label) {
+    const len = readU32(buf, cursor, label);
+    return readFixedBytes(buf, cursor, len, label);
+}
+function u16LE(n) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16LE(n, 0);
+    return b;
+}
+function u8(n, label) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xff) {
+        throw new Error(`${label} must fit in u8`);
+    }
+    return n;
+}
+function u32LE(n) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(n, 0);
+    return b;
+}
+function u64LE(n) {
+    if (n < 0n || n > 0xffffffffffffffffn) {
+        throw new Error(`u64 value out of range: ${n}`);
+    }
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(n, 0);
+    return b;
+}

package/dist/cjs/script.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Statement-aware PowQL script splitting.
+ *
+ * Mirrors the server-side splitter (`powdb_query::lexer::split_statements`)
+ * exactly, so a script file behaves the same whether it is fed to the CLI's
+ * `--exec` / `.powql` path or to {@link Client.execScript} over the wire:
+ *
+ *   - `;` splits statements only at the top level.
+ *   - `;` inside a `"..."` string literal never splits. A backslash inside a
+ *     string consumes the next character unconditionally (mirroring the
+ *     PowQL lexer), so `\"` and `\;` stay inside the string.
+ *   - `#` starts a comment that runs to end-of-line; a `;` inside a comment
+ *     never splits.
+ *   - Segments are trimmed; empty segments (leading/doubled/trailing `;`,
+ *     blank lines) are dropped.
+ *   - Never errors: an unterminated string simply makes the rest of the
+ *     input the final segment.
+ */
+/**
+ * Split a PowQL script into individual statements.
+ *
+ * String-literal- and `#`-comment-aware `;` splitting with the exact
+ * semantics of the CLI/server splitter (see module docs above).
+ */
+export declare function splitStatements(input: string): string[];