nixamp 0.16.0 → 0.17.1

package/dist/channels.js

@@ -49,6 +49,38 @@ const TAIL = 2000;
  */
 export const BACKLOG_VIDEO = 4 * 1024 * 1024;
 export const BACKLOG_AUDIO = 64 * 1024;
+/**
+ * How far behind a listener may fall before it is let go. Sixteen
+ * megabytes is half a minute of 720p television that a socket has accepted
+ * and not delivered: nobody is watching that, and every byte of it was
+ * sitting in this process. Before this a stalled listener's buffer grew
+ * until the channel ended, however long that was.
+ */
+export const LISTENER_QUEUE = 16 * 1024 * 1024;
+/**
+ * The backlog is really a number of seconds, and four megabytes was that
+ * number for the stream we happened to have.
+ *
+ * Six seconds of 720p is about 4 MB. Six seconds of a 1080p transport stream
+ * copied straight through is nearer 12, and of 4K nearer 30 -- so a fixed
+ * 4 MB hands a 4K joiner under a second of video, which is the live edge with
+ * no cushion, which is the play-wait-play loop the backlog exists to prevent.
+ * So the cap follows the stream: seconds times the rate it is actually
+ * running at, between the old floor and a ceiling that keeps a channel's
+ * memory bounded whatever it is carrying.
+ */
+export const BACKLOG_SECONDS = 6;
+export const BACKLOG_VIDEO_MAX = 48 * 1024 * 1024;
+/**
+ * How long a rate is measured over before it is believed.
+ *
+ * The first seconds of a pull are not a bitrate: ffmpeg opens the source,
+ * reads ahead, and empties what it has as fast as the pipe takes it. Sizing a
+ * buffer off that burst would reserve tens of megabytes for a stream that
+ * turns out to be a podcast. A window is measured, and until one has closed
+ * the floor stands.
+ */
+export const RATE_WINDOW_MS = 5000;
 /** The four-letter name in a box header, or "" for something too short. */
 function boxType(box) {
     return box.length >= 8 ? box.toString("latin1", 4, 8) : "";
@@ -120,6 +152,10 @@ export class Channel {
      */
     recent = [];
     recentBytes = 0;
+    /** The rate window: when it opened, what has arrived in it, and what the last closed one measured. */
+    rateStart = 0;
+    rateBytes = 0;
+    rate = 0;
     /**
      * Started for whoever asked and stopped when nobody is left. A catalog
      * channel is one of thousands; keeping every one that was ever clicked
@@ -321,6 +357,11 @@ export class Channel {
             this.fragments = new Fragments();
         this.recent = [];
         this.recentBytes = 0;
+        // A new source may be a different size of stream, and the rate measured
+        // off the old one is not evidence about this one.
+        this.rateStart = 0;
+        this.rateBytes = 0;
+        this.rate = 0;
         this.hangUp();
     }
     /** Expect output within STALL, or treat the source as gone and dial again. */
@@ -390,17 +431,44 @@ export class Channel {
      * make sense.
      */
     emit(chunk) {
+        this.measure(chunk.byteLength);
         if (!this.fragments) {
             this.remember(chunk, BACKLOG_AUDIO, false);
             this.send(chunk);
             return;
         }
+        const cap = this.backlogCap();
         for (const box of this.fragments.push(chunk)) {
             if (!isOpening(boxType(box)))
-                this.remember(box, BACKLOG_VIDEO, true);
+                this.remember(box, cap, true);
             this.send(box);
         }
     }
+    /** Watch how fast this channel is actually running, a window at a time. */
+    measure(bytes) {
+        const now = Date.now();
+        if (this.rateStart === 0)
+            this.rateStart = now;
+        this.rateBytes += bytes;
+        const elapsed = now - this.rateStart;
+        if (elapsed < (this.options.rateWindowMs ?? RATE_WINDOW_MS))
+            return;
+        this.rate = (this.rateBytes * 1000) / elapsed;
+        this.rateStart = now;
+        this.rateBytes = 0;
+    }
+    /**
+     * Six seconds of whatever this channel turned out to be, within bounds.
+     *
+     * Unmeasured -- the first window of a pull, or a channel that has only just
+     * started -- means the floor, which is what every channel had before.
+     */
+    backlogCap() {
+        if (this.rate <= 0)
+            return BACKLOG_VIDEO;
+        const wanted = this.rate * BACKLOG_SECONDS;
+        return Math.min(BACKLOG_VIDEO_MAX, Math.max(BACKLOG_VIDEO, Math.round(wanted)));
+    }
     /** Keep this for the next arrival, and let the oldest go once it is too much. */
     remember(piece, cap, aligned) {
         this.recent.push(piece);
@@ -440,11 +508,22 @@ export class Channel {
         this.info.bytes += chunk.byteLength;
         this.send(chunk);
     }
-    /** Write to everyone, and drop anybody whose socket has gone. */
+    /**
+     * Write to everyone, and drop anybody whose socket has gone -- or has
+     * stopped taking anything. A write that returns false is ordinary: the
+     * socket is a little behind and will catch up. One that returns false
+     * with a queue past the limit is a listener that is not reading, and
+     * ending it is the only thing that stops its queue growing.
+     */
     send(chunk) {
+        const cap = this.options.maxListenerQueueBytes ?? LISTENER_QUEUE;
         for (const listener of this.listeners) {
             try {
-                listener.write(chunk);
+                const drained = listener.write(chunk);
+                if (!drained && (listener.pending?.() ?? 0) > cap) {
+                    this.listeners.delete(listener);
+                    listener.end();
+                }
             }
             catch {
                 // One listener's broken socket is not the channel's problem.
@@ -453,6 +532,46 @@ export class Channel {
         }
         this.info.listeners = this.listeners.size;
     }
+    /**
+     * What a new listener is written before the live bytes: the opening
+     * boxes when there are any, then the recent backlog. The same rule as
+     * `listen`, handed out so a relay can compress it for one receiver.
+     */
+    opening() {
+        const out = [];
+        if (this.fragments?.ready)
+            out.push(this.fragments.header);
+        if (!this.fragments || this.fragments.ready)
+            out.push(...this.recent);
+        return out;
+    }
+    /**
+     * Bytes decoded from another nixamp's relay: the channel's own output as
+     * it was there, so they go out here exactly as ffmpeg's would, whole
+     * boxes at a time with the backlog kept.
+     */
+    receive(chunk) {
+        if (this.closing)
+            return;
+        this.info.bytes += chunk.byteLength;
+        this.emit(chunk);
+    }
+    /** Ready a channel that will be fed by `receive`: pictures need their boxes tracked. */
+    prepare() {
+        if (this.info.kind === "video")
+            this.fragments = new Fragments();
+    }
+    /**
+     * The feed behind `receive` started over: a new generation upstream, with
+     * new opening boxes. Everybody listening is ended, as they are when our
+     * own ffmpeg is dialled again, and a newcomer gets the new beginning.
+     */
+    rollover() {
+        if (this.closing)
+            return;
+        this.info.redials = (this.info.redials ?? 0) + 1;
+        this.startOver();
+    }
     listen(listener) {
         // What the stream is, before any of what it is currently saying. Without
         // this a listener who arrives after the first second gets fragments that
@@ -704,6 +823,28 @@ export class Channels {
         this.open.set(id, channel);
         return channel;
     }
+    /**
+     * A channel carried in from another nixamp's relay. Like `attach`, no
+     * ffmpeg of our own; unlike it, the kind is known up front, so a picture
+     * gets its fragment tracking and a newcomer gets the opening boxes.
+     */
+    relayIn(id, name, kind, source) {
+        if (this.open.has(id))
+            return null;
+        const channel = new Channel({ id, name: name || id, format: kind === "video" ? "mp4" : "mp3", via: "relay", startedAt: Date.now(), bytes: 0, listeners: 0, kind, source, live: true }, this.options, (gone) => this.open.delete(gone));
+        channel.prepare();
+        this.open.set(id, channel);
+        this.options.onStart?.(channel.info);
+        return channel;
+    }
+    /** What a new listener would be written first, for a relay's preface. */
+    opening(id) {
+        return this.open.get(id)?.opening() ?? [];
+    }
+    /** The kind of a channel, for a relay to say what it is carrying. */
+    kindOf(id) {
+        return this.open.get(id)?.info.kind;
+    }
     stop(id) {
         const channel = this.open.get(id);
         if (!channel)
@@ -739,6 +880,13 @@ export function rememberedChannels(dir, port) {
                     kept.codecs = { video: c["video"], audio: c["audio"], container: c["container"] };
                     if (typeof c["duration"] === "number" && Number.isFinite(c["duration"]))
                         kept.codecs.duration = c["duration"];
+                    // The size of the picture decides whether a re-encode has to come
+                    // down to 1080p; forgetting it across a restart is how a 4K
+                    // channel comes back at a size that cannot keep up.
+                    if (typeof c["width"] === "number" && Number.isFinite(c["width"]))
+                        kept.codecs.width = c["width"];
+                    if (typeof c["height"] === "number" && Number.isFinite(c["height"]))
+                        kept.codecs.height = c["height"];
                 }
             }
             if (typeof one["position"] === "number" && Number.isFinite(one["position"]) && one["position"] > 0)

package/dist/compression/analyze.d.ts

@@ -0,0 +1,105 @@
+import { toolVersions } from "./codec.ts";
+import { type Boundary, type Mode } from "./envelope.ts";
+import { type LosslessPolicy } from "./policy.ts";
+/** Sample limits: bytes, and seconds of a live channel. */
+export declare const SAMPLE_MAX_BYTES: number;
+export declare const SAMPLE_MAX_SECONDS = 30;
+export type Container = "mpegts" | "fmp4" | "mp4" | "mp3" | "webm" | "unknown";
+/** Which container the first bytes say they are. */
+export declare function sniffContainer(bytes: Uint8Array): Container;
+export interface TsReport {
+    packetSize: 188 | 192 | 204;
+    offset: number;
+    packets: number;
+    nullPackets: number;
+    /** Of all packets. Padding a compressor removes for free, and that a copy must keep. */
+    nullShare: number;
+    scrambled: number;
+    transportErrors: number;
+    adaptationOnly: number;
+    /** Bytes not inside an aligned packet: a ragged head or tail. Kept, always. */
+    unsynced: number;
+    pids: {
+        pid: number;
+        packets: number;
+    }[];
+    /** What the PCR clock says the whole stream runs at, when there is a PCR to read. */
+    pcrBitrateKbps?: number;
+}
+/** The transport-stream report, or null for something that is not one. */
+export declare function analyzeTs(bytes: Uint8Array): TsReport | null;
+export interface BenchRow {
+    mode: Mode;
+    level: number;
+    blocks: number;
+    inputBytes: number;
+    /** Payload bytes after the eligibility rule: stored where compression did not pay. */
+    payloadBytes: number;
+    /** The complete representation: stream header, every frame header, every payload. */
+    wireBytes: number;
+    storedBlocks: number;
+    compressedBlocks: number;
+    /** Against the unwrapped original, headers included. Negative means it grew. */
+    savingsPercent: number;
+    encodeMs: number;
+    decodeMs: number;
+    roundTrip: boolean;
+    /** Set when a mode could not be applied at all, e.g. ts-zstd on an MP4. */
+    note?: string;
+}
+export interface BenchOptions {
+    blockBytes?: number;
+    zstdLevels?: number[];
+    policy?: Pick<LosslessPolicy, "minSavingsPercent" | "minSavingsBytes">;
+    /** Try the transport-stream transform too. */
+    tsAware?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Every codec over the same blocks. The identity row is the honest floor:
+ * what the envelope costs when nothing is saved.
+ */
+export declare function benchmark(bytes: Buffer, options?: BenchOptions): Promise<BenchRow[]>;
+export interface Analysis {
+    /** Which bytes these are: the source as it arrived, or the channel's output. */
+    boundary: Boundary;
+    source: {
+        kind: "file" | "channel" | "bytes";
+        name: string;
+    };
+    sampleBytes: number;
+    sampleMs?: number;
+    truncated: boolean;
+    sha256: string;
+    container: Container;
+    ts: TsReport | null;
+    /** From ffprobe, when the caller had one to ask. */
+    codecs?: {
+        video: string;
+        audio: string;
+        container: string;
+        duration?: number;
+    };
+    /** What the sample's own length and duration imply, when a duration is known. */
+    observedKbps?: number;
+    bench: BenchRow[];
+    /** The rows' verdict under the policy thresholds: which mode `auto` would take. */
+    recommendation: {
+        mode: Mode;
+        level: number;
+        reason: string;
+    };
+    tools: ReturnType<typeof toolVersions> & {
+        ffprobe?: string;
+    };
+    at: string;
+}
+export interface AnalyzeOptions extends BenchOptions {
+    boundary: Boundary;
+    source: Analysis["source"];
+    sampleMs?: number;
+    truncated?: boolean;
+    codecs?: Analysis["codecs"];
+    ffprobeVersion?: string;
+}
+export declare function analyzeSample(bytes: Buffer, options: AnalyzeOptions): Promise<Analysis>;

package/dist/compression/analyze.js

@@ -0,0 +1,213 @@
+/**
+ * What is in a sample, and what each codec makes of it.
+ *
+ * Bytes are inspected, not filenames: a .ts that is really an MP4 is told
+ * apart by its sync bytes, or their absence. The transport-stream report
+ * counts what can be counted without decoding anything -- packets, null
+ * packets, PIDs, the bitrate the PCR clock implies. The benchmark then runs
+ * every codec over the same blocks and reports the complete wire size,
+ * headers included, with a round trip checked on every block. Nothing here
+ * is a promise about production sources; it is a measurement of this
+ * sample on this machine, and says so.
+ */
+import { createHash } from "node:crypto";
+import { decode, encode, toolVersions } from "./codec.js";
+import { FRAME_HEADER_BYTES, STREAM_HEADER_BYTES } from "./envelope.js";
+import { DEFAULT_LOSSLESS, eligible } from "./policy.js";
+import { SYNC, TS_PACKET, tsLayout } from "./ts-transform.js";
+/** Sample limits: bytes, and seconds of a live channel. */
+export const SAMPLE_MAX_BYTES = 25 * 1024 * 1024;
+export const SAMPLE_MAX_SECONDS = 30;
+/** Which container the first bytes say they are. */
+export function sniffContainer(bytes) {
+    if (bytes.length >= 12) {
+        const box = Buffer.from(bytes.subarray(4, 8)).toString("latin1");
+        if (box === "ftyp" || box === "styp") {
+            const brand = Buffer.from(bytes.subarray(8, 12)).toString("latin1");
+            return brand === "iso5" || brand === "iso6" || brand === "dash" || brand === "cmfc" ? "fmp4" : "mp4";
+        }
+        if (box === "moof" || box === "moov" || box === "sidx")
+            return "fmp4";
+    }
+    if (tsLayout(bytes) !== null)
+        return "mpegts";
+    if (bytes.length >= 4 && bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3)
+        return "webm";
+    if (bytes.length >= 3 && bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33)
+        return "mp3";
+    if (bytes.length >= 2 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0)
+        return "mp3";
+    return "unknown";
+}
+/** PCR base and extension, as a count of 27 MHz ticks, from an adaptation field that has one. */
+function pcrOf(packet, at) {
+    const afc = (packet[at + 3] >> 4) & 0x3;
+    if ((afc & 0b10) === 0)
+        return null;
+    const length = packet[at + 4];
+    if (length < 7)
+        return null;
+    const flags = packet[at + 5];
+    if ((flags & 0x10) === 0)
+        return null;
+    const b = packet.subarray(at + 6, at + 12);
+    const base = (b[0] * 2 ** 25) + (b[1] << 17) + (b[2] << 9) + (b[3] << 1) + (b[4] >> 7);
+    const ext = ((b[4] & 0x1) << 8) | b[5];
+    return base * 300 + ext;
+}
+/** The transport-stream report, or null for something that is not one. */
+export function analyzeTs(bytes) {
+    const layout = tsLayout(bytes);
+    if (layout === null)
+        return null;
+    const { packetSize, offset } = layout;
+    const skip = packetSize === 192 ? 4 : 0;
+    const pids = new Map();
+    let packets = 0;
+    let nullPackets = 0;
+    let scrambled = 0;
+    let transportErrors = 0;
+    let adaptationOnly = 0;
+    let firstPcr = null;
+    let lastPcr = null;
+    let cursor = offset;
+    while (cursor + packetSize <= bytes.length && bytes[cursor + skip] === SYNC) {
+        const at = cursor + skip;
+        const b1 = bytes[at + 1];
+        const b2 = bytes[at + 2];
+        const b3 = bytes[at + 3];
+        const pid = ((b1 & 0x1f) << 8) | b2;
+        packets += 1;
+        pids.set(pid, (pids.get(pid) ?? 0) + 1);
+        if (pid === 0x1fff)
+            nullPackets += 1;
+        if (b1 & 0x80)
+            transportErrors += 1;
+        if (b3 & 0xc0)
+            scrambled += 1;
+        if (((b3 >> 4) & 0x3) === 0b10)
+            adaptationOnly += 1;
+        const pcr = pcrOf(bytes, at);
+        if (pcr !== null) {
+            if (firstPcr === null)
+                firstPcr = { pid, value: pcr, at: cursor };
+            else if (firstPcr.pid === pid && pcr > firstPcr.value)
+                lastPcr = { value: pcr, at: cursor };
+        }
+        cursor += packetSize;
+    }
+    const report = {
+        packetSize,
+        offset,
+        packets,
+        nullPackets,
+        nullShare: packets === 0 ? 0 : nullPackets / packets,
+        scrambled,
+        transportErrors,
+        adaptationOnly,
+        unsynced: offset + (bytes.length - cursor),
+        pids: [...pids.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 12)
+            .map(([pid, count]) => ({ pid, packets: count })),
+    };
+    if (firstPcr && lastPcr) {
+        const seconds = (lastPcr.value - firstPcr.value) / 27_000_000;
+        if (seconds > 0.5)
+            report.pcrBitrateKbps = Math.round(((lastPcr.at - firstPcr.at) * 8) / seconds / 1000);
+    }
+    return report;
+}
+/**
+ * Every codec over the same blocks. The identity row is the honest floor:
+ * what the envelope costs when nothing is saved.
+ */
+export async function benchmark(bytes, options = {}) {
+    const blockBytes = options.blockBytes ?? DEFAULT_LOSSLESS.maxBlockBytes;
+    const policy = options.policy ?? DEFAULT_LOSSLESS;
+    const plan = [{ mode: "stored", level: 0 }, { mode: "gzip", level: 6 }];
+    for (const level of options.zstdLevels ?? [1, 3])
+        plan.push({ mode: "zstd", level });
+    if (options.tsAware)
+        plan.push({ mode: "ts-zstd", level: 1 });
+    const rows = [];
+    for (const { mode, level } of plan) {
+        if (options.signal?.aborted)
+            break;
+        const row = {
+            mode, level, blocks: 0, inputBytes: bytes.length, payloadBytes: 0, wireBytes: STREAM_HEADER_BYTES + FRAME_HEADER_BYTES,
+            storedBlocks: 0, compressedBlocks: 0, savingsPercent: 0, encodeMs: 0, decodeMs: 0, roundTrip: true,
+        };
+        try {
+            for (let at = 0; at < bytes.length; at += blockBytes) {
+                if (options.signal?.aborted)
+                    throw new Error("cancelled");
+                const block = bytes.subarray(at, Math.min(bytes.length, at + blockBytes));
+                row.blocks += 1;
+                const t0 = performance.now();
+                const encoded = mode === "stored" ? block : await encode(mode, block, level);
+                row.encodeMs += performance.now() - t0;
+                const keep = mode !== "stored" && eligible(block.length, encoded.length, policy);
+                const payload = keep ? encoded : block;
+                if (keep)
+                    row.compressedBlocks += 1;
+                else
+                    row.storedBlocks += 1;
+                row.payloadBytes += payload.length;
+                row.wireBytes += FRAME_HEADER_BYTES + payload.length;
+                const t1 = performance.now();
+                const back = keep ? await decode(mode, payload, block.length) : payload;
+                row.decodeMs += performance.now() - t1;
+                if (!back.equals(block))
+                    row.roundTrip = false;
+            }
+        }
+        catch (error) {
+            row.note = error.message;
+            row.roundTrip = false;
+        }
+        row.savingsPercent = bytes.length === 0 ? 0 : ((bytes.length - row.wireBytes) * 100) / bytes.length;
+        row.encodeMs = Math.round(row.encodeMs * 100) / 100;
+        row.decodeMs = Math.round(row.decodeMs * 100) / 100;
+        row.savingsPercent = Math.round(row.savingsPercent * 100) / 100;
+        rows.push(row);
+    }
+    return rows;
+}
+export async function analyzeSample(bytes, options) {
+    const ts = analyzeTs(bytes);
+    const bench = await benchmark(bytes, { ...options, tsAware: options.tsAware ?? ts?.packetSize === TS_PACKET });
+    const stored = bench.find((row) => row.mode === "stored");
+    const best = bench
+        .filter((row) => row.roundTrip && row.mode !== "stored")
+        .sort((a, b) => a.wireBytes - b.wireBytes)[0];
+    const policy = options.policy ?? DEFAULT_LOSSLESS;
+    let recommendation;
+    if (!best || !stored || !eligible(stored.wireBytes, best.wireBytes, policy)) {
+        recommendation = { mode: "stored", level: 0, reason: "already efficiently compressed: no codec beat stored by the configured margin" };
+    }
+    else {
+        recommendation = { mode: best.mode, level: best.level, reason: `${best.mode} level ${best.level} saves ${best.savingsPercent}% of the complete wire size on this sample` };
+    }
+    const analysis = {
+        boundary: options.boundary,
+        source: options.source,
+        sampleBytes: bytes.length,
+        truncated: options.truncated ?? false,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        container: sniffContainer(bytes),
+        ts,
+        bench,
+        recommendation,
+        tools: { ...toolVersions(), ...(options.ffprobeVersion ? { ffprobe: options.ffprobeVersion } : {}) },
+        at: new Date().toISOString(),
+    };
+    if (options.sampleMs !== undefined)
+        analysis.sampleMs = options.sampleMs;
+    if (options.codecs)
+        analysis.codecs = options.codecs;
+    const seconds = options.sampleMs !== undefined ? options.sampleMs / 1000 : options.codecs?.duration;
+    if (seconds && seconds > 0 && !options.truncated)
+        analysis.observedKbps = Math.round((bytes.length * 8) / seconds / 1000);
+    return analysis;
+}

package/dist/compression/blocks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bytes into blocks, without ever waiting for the stream's convenience.
+ *
+ * A block is flushed when it is full or when its first byte has been held
+ * for `maxHoldMs`, whichever is sooner. It never waits for a packet
+ * boundary that has not come, and a chunk bigger than a block is sliced
+ * rather than refused. Alignment, when asked for, only decides where a full
+ * block is cut; a timed flush sends whatever is there, and the transform
+ * that wanted the alignment copes with a ragged edge.
+ */
+export interface BlockerOptions {
+    maxBlockBytes: number;
+    maxHoldMs: number;
+    /** Cut full blocks at a multiple of this many bytes. 0 for wherever. */
+    align?: number;
+    onBlock: (block: Buffer) => void;
+    /** Injected by tests. */
+    setTimer?: (fn: () => void, ms: number) => {
+        clear(): void;
+    };
+}
+export declare class Blocker {
+    private readonly options;
+    private pieces;
+    private held;
+    private timer;
+    private ended;
+    constructor(options: BlockerOptions);
+    get pendingBytes(): number;
+    push(chunk: Buffer): void;
+    /** Send whatever is held, now. */
+    flush(): void;
+    end(): void;
+    private flushBytes;
+}

package/dist/compression/blocks.js

@@ -0,0 +1,73 @@
+const realTimer = (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    handle.unref?.();
+    return { clear: () => clearTimeout(handle) };
+};
+export class Blocker {
+    options;
+    pieces = [];
+    held = 0;
+    timer = null;
+    ended = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get pendingBytes() {
+        return this.held;
+    }
+    push(chunk) {
+        if (this.ended || chunk.length === 0)
+            return;
+        const { maxBlockBytes, align = 0 } = this.options;
+        let offset = 0;
+        while (offset < chunk.length) {
+            const room = maxBlockBytes - this.held;
+            const take = Math.min(room, chunk.length - offset);
+            this.pieces.push(chunk.subarray(offset, offset + take));
+            this.held += take;
+            offset += take;
+            if (this.held >= maxBlockBytes) {
+                // Cut at the alignment, carrying the remainder into the next block.
+                // Only a full block is cut this way: a whole block with no boundary
+                // in it is sent as it is, or nothing would ever leave.
+                const cut = align > 1 && this.held - (this.held % align) > 0 ? this.held - (this.held % align) : this.held;
+                this.flushBytes(cut);
+            }
+            else if (this.timer === null) {
+                // The clock starts when the first byte enters an empty block.
+                this.timer = (this.options.setTimer ?? realTimer)(() => {
+                    this.timer = null;
+                    this.flush();
+                }, this.options.maxHoldMs);
+            }
+        }
+    }
+    /** Send whatever is held, now. */
+    flush() {
+        this.flushBytes(this.held);
+    }
+    end() {
+        this.flush();
+        this.ended = true;
+    }
+    flushBytes(count) {
+        if (this.timer)
+            this.timer.clear();
+        this.timer = null;
+        if (count <= 0 || this.held === 0)
+            return;
+        const whole = this.pieces.length === 1 ? this.pieces[0] : Buffer.concat(this.pieces, this.held);
+        const block = whole.subarray(0, count);
+        const rest = whole.subarray(count);
+        this.pieces = rest.length > 0 ? [rest] : [];
+        this.held = rest.length;
+        this.options.onBlock(block);
+        // A remainder is a new block whose first byte arrived just now.
+        if (this.held > 0 && this.timer === null && !this.ended) {
+            this.timer = (this.options.setTimer ?? realTimer)(() => {
+                this.timer = null;
+                this.flush();
+            }, this.options.maxHoldMs);
+        }
+    }
+}

package/dist/compression/cli.d.ts

@@ -0,0 +1 @@
+export declare function compression(argv: string[]): Promise<number>;