@lakutata/webrtc 0.0.0-stage → 3.1.1

package/dist/esm/shared/ChunkedChannel.js

@@ -0,0 +1,178 @@
+import { Emitter } from './Emitter.js';
+/**
+ * The flag of the last chunk of a message
+ */
+const FINAL = 0x01;
+/**
+ * The flag of a text message
+ */
+const TEXT = 0x02;
+/**
+ * Messages of any size over a data channel: each message is cut into chunks (a byte of flags, then up to `chunkSize`
+ * bytes), sent as the channel's buffer empties, and put back together on the other side, so the size limit of the
+ * implementations (64 KiB to 256 KiB) does not apply and a large message does not hold the memory. Both sides wrap the
+ * channel with it; the channel must be ordered and reliable (the default of a data channel). A `Blob` (a file of a
+ * browser) is read a chunk at a time.
+ * @example
+ * ```typescript
+ * import {ChunkedChannel, type PeerChannel} from '@lakutata/webrtc'
+ *
+ * declare const channel: PeerChannel
+ * const files: ChunkedChannel = new ChunkedChannel(channel)
+ * files.on('message', (data: string | Uint8Array): void => console.log(`received ${data.length} bytes`))
+ * await files.send(new Uint8Array(10 * 1024 * 1024))
+ * ```
+ */
+export class ChunkedChannel extends Emitter {
+    #channel;
+    #chunkSize;
+    #highWaterMark;
+    #maxMessageSize;
+    #onMessage;
+    //The sends, one after the other: the chunks of two messages do not mix
+    #sending = Promise.resolve();
+    #parts = [];
+    #received = 0;
+    #dropping = false;
+    /**
+     * Wrap a data channel.
+     * @param channel The channel: ordered and reliable.
+     * @param options The size of the chunks, of the buffer, of a message received.
+     * @throws {TypeError} When the channel is not ordered.
+     */
+    constructor(channel, options = {}) {
+        super();
+        if (!channel.ordered)
+            throw new TypeError('A chunked channel must be ordered');
+        this.#channel = channel;
+        this.#chunkSize = Math.max(1, options.chunkSize ?? 16384);
+        this.#highWaterMark = options.highWaterMark ?? 1048576;
+        this.#maxMessageSize = options.maxMessageSize ?? 67108864;
+        channel.binaryType = 'arraybuffer';
+        if (!channel.bufferedAmountLowThreshold)
+            channel.bufferedAmountLowThreshold = Math.floor(this.#highWaterMark / 2);
+        this.#onMessage = (event) => this.#receive(event.data);
+        channel.addEventListener('message', this.#onMessage);
+    }
+    /**
+     * The data channel.
+     */
+    get channel() {
+        return this.#channel;
+    }
+    /**
+     * Send a message, after the ones sent before.
+     * @param data A string, bytes, or a `Blob`.
+     * @returns Resolves once all its chunks are handed to the channel.
+     * @throws {Error} When the channel closes before.
+     */
+    send(data) {
+        const sending = this.#sending.then(() => this.#send(data));
+        this.#sending = sending.catch(() => undefined);
+        return sending;
+    }
+    /**
+     * Stop listening to the channel, and close it.
+     */
+    close() {
+        this.#channel.removeEventListener('message', this.#onMessage);
+        this.#channel.close();
+    }
+    /**
+     * Send the chunks of a message
+     * @param data
+     */
+    async #send(data) {
+        if (typeof Blob !== 'undefined' && data instanceof Blob) {
+            if (!data.size)
+                return this.#frame(FINAL, new Uint8Array(0));
+            for (let offset = 0; offset < data.size; offset += this.#chunkSize) {
+                const chunk = new Uint8Array(await data.slice(offset, offset + this.#chunkSize).arrayBuffer());
+                await this.#frame(offset + this.#chunkSize >= data.size ? FINAL : 0, chunk);
+            }
+            return;
+        }
+        const text = typeof data === 'string';
+        const bytes = typeof data === 'string'
+            ? new TextEncoder().encode(data)
+            : ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+        const flags = text ? TEXT : 0;
+        if (!bytes.length)
+            return this.#frame(flags | FINAL, new Uint8Array(0));
+        for (let offset = 0; offset < bytes.length; offset += this.#chunkSize) {
+            const end = Math.min(offset + this.#chunkSize, bytes.length);
+            await this.#frame(flags | (end === bytes.length ? FINAL : 0), bytes.subarray(offset, end));
+        }
+    }
+    /**
+     * Send a frame once the buffer of the channel is below the high water mark
+     * @param flags
+     * @param chunk
+     */
+    async #frame(flags, chunk) {
+        if (this.#channel.bufferedAmount > this.#highWaterMark)
+            await this.#drain();
+        if (this.#channel.readyState !== 'open')
+            throw new Error(`The channel is ${this.#channel.readyState}`);
+        const frame = new Uint8Array(chunk.length + 1);
+        frame[0] = flags;
+        frame.set(chunk, 1);
+        this.#channel.send(frame);
+    }
+    /**
+     * Wait for the buffer of the channel to empty, or for the channel to close
+     */
+    #drain() {
+        return new Promise((resolve) => {
+            const done = () => {
+                this.#channel.removeEventListener('bufferedamountlow', done);
+                this.#channel.removeEventListener('close', done);
+                resolve();
+            };
+            this.#channel.addEventListener('bufferedamountlow', done);
+            this.#channel.addEventListener('close', done);
+        });
+    }
+    /**
+     * A frame received
+     * @param data
+     */
+    #receive(data) {
+        if (typeof data === 'string' || !data)
+            return void this.emit('error', new Error('A chunked channel received a text frame'));
+        const frame = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        if (!frame.length)
+            return void this.emit('error', new Error('A chunked channel received an empty frame'));
+        const flags = frame[0];
+        const chunk = frame.subarray(1);
+        if (!this.#dropping) {
+            this.#received += chunk.length;
+            if (this.#received > this.#maxMessageSize) {
+                this.#dropping = true;
+                this.#parts = [];
+                this.emit('error', new Error(`A message over ${this.#maxMessageSize} bytes was dropped`));
+            }
+            else {
+                this.#parts.push(chunk.slice());
+            }
+        }
+        if (!(flags & FINAL))
+            return;
+        const parts = this.#parts;
+        const dropped = this.#dropping;
+        this.#parts = [];
+        this.#received = 0;
+        this.#dropping = false;
+        if (dropped)
+            return;
+        const message = parts.length === 1 ? parts[0] : new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+        if (parts.length > 1) {
+            let offset = 0;
+            for (const part of parts) {
+                message.set(part, offset);
+                offset += part.length;
+            }
+        }
+        this.emit('message', flags & TEXT ? new TextDecoder().decode(message) : message);
+    }
+}

package/dist/esm/shared/Connections.js

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

package/dist/esm/shared/Emitter.js

@@ -0,0 +1,76 @@
+/**
+ * A small typed event emitter, the same in the browsers and in Node.js (it does not use `node:events`). A listener
+ * throwing does not stop the other listeners: its error is reported as an uncaught one, as the listeners of an
+ * `EventTarget` are.
+ */
+export class Emitter {
+    #listeners = new Map();
+    /**
+     * Add a listener of an event.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    on(event, listener) {
+        let listeners = this.#listeners.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.#listeners.set(event, listeners);
+        }
+        listeners.add(listener);
+        return this;
+    }
+    /**
+     * Add a listener of the next emission of an event only.
+     * @param event The event.
+     * @param listener The listener, given the arguments of the event.
+     * @returns This emitter.
+     */
+    once(event, listener) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            listener(...args);
+        };
+        return this.on(event, wrapper);
+    }
+    /**
+     * Remove a listener of an event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns This emitter.
+     */
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+        return this;
+    }
+    /**
+     * Call the listeners of an event
+     * @param event
+     * @param args
+     * @protected
+     */
+    emit(event, ...args) {
+        const listeners = this.#listeners.get(event);
+        if (!listeners?.size)
+            return false;
+        for (const listener of [...listeners]) {
+            try {
+                listener(...args);
+            }
+            catch (error) {
+                queueMicrotask(() => {
+                    throw error;
+                });
+            }
+        }
+        return true;
+    }
+    /**
+     * Whether an event has listeners
+     * @param event
+     * @protected
+     */
+    listened(event) {
+        return !!this.#listeners.get(event)?.size;
+    }
+}