@lakutata/webrtc 0.0.0-stage → 3.1.4

package/dist/cjs/peer/PeerChannel.d.ts

@@ -0,0 +1,248 @@
+import type { RTCDataChannel } from '../lib/peer/dataChannel.js';
+import { type DOMEventListener, type ListenerOptions } from './Events.js';
+/**
+ * The events of a {@link PeerChannel}, with the arguments of their listeners in the Node.js style (`on`).
+ */
+export type PeerChannelEvents = {
+    /**
+     * The channel is open: messages may be sent.
+     */
+    open: [];
+    /**
+     * The channel is closing.
+     */
+    closing: [];
+    /**
+     * The channel is closed.
+     */
+    close: [];
+    /**
+     * A message: a string, or a `Buffer` (an `ArrayBuffer` when `binaryType` is `'arraybuffer'`).
+     */
+    message: [data: string | Buffer | ArrayBuffer];
+    /**
+     * The data waiting to be sent fell to `bufferedAmountLowThreshold`.
+     */
+    bufferedamountlow: [];
+    /**
+     * An error of the channel.
+     */
+    error: [error: Error];
+};
+/**
+ * A data channel of a {@link PeerConnection}, as `RTCDataChannel` of the browsers: `send()`, `close()`, the same
+ * properties and events (`addEventListener`, the `on…` properties). Its events may be listened to in the Node.js style
+ * too: `on('message', (data) => …)` gets the message itself. A binary message is a `Buffer`, or an `ArrayBuffer` when
+ * `binaryType` is `'arraybuffer'`.
+ *
+ * It is created by `PeerConnection.createDataChannel()`, or by the other peer (the `datachannel` event).
+ * @example
+ * ```typescript
+ * import type {PeerChannel, PeerConnection} from '@lakutata/webrtc'
+ *
+ * declare const connection: PeerConnection
+ * const channel: PeerChannel = connection.createDataChannel('chat')
+ * channel.on('open', (): void => channel.send('hello'))
+ * channel.on('message', (data: string | Buffer | ArrayBuffer): void => console.log(data.toString()))
+ * ```
+ */
+export declare class PeerChannel {
+    #private;
+    /**
+     * Wrap a channel of the engine
+     * @param channel
+     * @internal
+     */
+    constructor(channel: RTCDataChannel);
+    /**
+     * The label of the channel.
+     */
+    get label(): string;
+    /**
+     * The id of the channel (its SCTP stream); `null` until the connection decides it.
+     */
+    get id(): number | null;
+    /**
+     * The subprotocol.
+     */
+    get protocol(): string;
+    /**
+     * Whether the messages arrive in order.
+     */
+    get ordered(): boolean;
+    /**
+     * How many times a message is sent again at most; `null` for a reliable channel.
+     */
+    get maxRetransmits(): number | null;
+    /**
+     * How long a message is sent again at most, in milliseconds; `null` for a reliable channel.
+     */
+    get maxPacketLifeTime(): number | null;
+    /**
+     * Whether both peers created the channel themselves.
+     */
+    get negotiated(): boolean;
+    /**
+     * `connecting`, `open`, `closing` or `closed`.
+     */
+    get readyState(): 'connecting' | 'open' | 'closing' | 'closed';
+    /**
+     * The bytes sent but not handed to the network yet: wait for `bufferedamountlow` when it grows, to send a large
+     * amount of data without holding it all in memory.
+     */
+    get bufferedAmount(): number;
+    /**
+     * The value of `bufferedAmount` at which `bufferedamountlow` fires.
+     */
+    get bufferedAmountLowThreshold(): number;
+    set bufferedAmountLowThreshold(value: number);
+    /**
+     * The type of the binary messages received: `'nodebuffer'` (a `Buffer`, by default) or `'arraybuffer'`.
+     */
+    get binaryType(): 'nodebuffer' | 'arraybuffer';
+    set binaryType(value: 'nodebuffer' | 'arraybuffer');
+    /**
+     * The listener of `open`, given the event.
+     */
+    get onopen(): DOMEventListener | null;
+    set onopen(listener: DOMEventListener | null);
+    /**
+     * The listener of `message`, given a `MessageEvent` whose `data` is the message.
+     */
+    get onmessage(): DOMEventListener | null;
+    set onmessage(listener: DOMEventListener | null);
+    /**
+     * The listener of `closing`, given the event.
+     */
+    get onclosing(): DOMEventListener | null;
+    set onclosing(listener: DOMEventListener | null);
+    /**
+     * The listener of `close`, given the event.
+     */
+    get onclose(): DOMEventListener | null;
+    set onclose(listener: DOMEventListener | null);
+    /**
+     * The listener of `bufferedamountlow`, given the event.
+     */
+    get onbufferedamountlow(): DOMEventListener | null;
+    set onbufferedamountlow(listener: DOMEventListener | null);
+    /**
+     * The listener of `error`, given an event whose `error` is the error.
+     */
+    get onerror(): DOMEventListener | null;
+    set onerror(listener: DOMEventListener | null);
+    /**
+     * Send a message: a string, or binary data.
+     * @param data The message; its size may not exceed the maximum of the other peer (`PeerConnection.sctp.maxMessageSize`).
+     * @throws {DOMException} When the channel is not open (`InvalidStateError`).
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.send(JSON.stringify({x: 1, y: 2}))
+     * channel.send(new Uint8Array([1, 2, 3]))
+     * ```
+     */
+    send(data: string | ArrayBuffer | ArrayBufferView): void;
+    /**
+     * Close the channel; the messages sent before are delivered first.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.close()
+     * ```
+     */
+    close(): void;
+    /**
+     * Add a listener of an event, given an event object (the W3C style).
+     * @param type The event: `open`, `message`, `closing`, `close`, `bufferedamountlow`, `error`.
+     * @param listener The listener.
+     * @param options `once`, `signal`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.addEventListener('message', (event: MessageEvent): void => console.log(event.data))
+     * ```
+     */
+    addEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    /**
+     * Remove a listener added with `addEventListener`.
+     * @param type The event.
+     * @param listener The listener.
+     * @param options `capture`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * const listener = (event: MessageEvent): void => console.log(event.data)
+     * channel.addEventListener('message', listener)
+     * channel.removeEventListener('message', listener)
+     * ```
+     */
+    removeEventListener(type: string, listener: DOMEventListener, options?: boolean | ListenerOptions): void;
+    /**
+     * Dispatch an event to the listeners, as `EventTarget.dispatchEvent()`: the ones of the W3C style get it, the ones
+     * of the Node.js style its value (the data of a `MessageEvent`).
+     * @param event The event.
+     * @returns Whether no listener called `preventDefault()`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * //A message given again to the listeners
+     * channel.dispatchEvent(new MessageEvent('message', {data: 'again'}))
+     * ```
+     */
+    dispatchEvent(event: Event): boolean;
+    /**
+     * Add a listener of an event, given the value of the event (the Node.js style).
+     * @param event The event.
+     * @param listener The listener: given the message for `message`, the error for `error`.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.on('message', (data: string | Buffer | ArrayBuffer): void => console.log(data))
+     * ```
+     */
+    on<Event extends keyof PeerChannelEvents>(event: Event, listener: (...args: PeerChannelEvents[Event]) => void): this;
+    /**
+     * Add a listener of the next emission of an event, given the value of the event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.once('open', (): void => channel.send('first'))
+     * ```
+     */
+    once<Event extends keyof PeerChannelEvents>(event: Event, listener: (...args: PeerChannelEvents[Event]) => void): this;
+    /**
+     * Remove a listener added with `on` or `once`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * const listener = (): void => console.log('closed')
+     * channel.on('close', listener)
+     * channel.off('close', listener)
+     * ```
+     */
+    off<Event extends keyof PeerChannelEvents>(event: Event, listener: (...args: PeerChannelEvents[Event]) => void): this;
+}

package/dist/cjs/peer/PeerChannel.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PeerChannel = void 0;
+const EngineConnection_js_1 = require("./EngineConnection.js");
+const Events_js_1 = require("./Events.js");
+/**
+ * A data channel of a {@link PeerConnection}, as `RTCDataChannel` of the browsers: `send()`, `close()`, the same
+ * properties and events (`addEventListener`, the `on…` properties). Its events may be listened to in the Node.js style
+ * too: `on('message', (data) => …)` gets the message itself. A binary message is a `Buffer`, or an `ArrayBuffer` when
+ * `binaryType` is `'arraybuffer'`.
+ *
+ * It is created by `PeerConnection.createDataChannel()`, or by the other peer (the `datachannel` event).
+ * @example
+ * ```typescript
+ * import type {PeerChannel, PeerConnection} from '@lakutata/webrtc'
+ *
+ * declare const connection: PeerConnection
+ * const channel: PeerChannel = connection.createDataChannel('chat')
+ * channel.on('open', (): void => channel.send('hello'))
+ * channel.on('message', (data: string | Buffer | ArrayBuffer): void => console.log(data.toString()))
+ * ```
+ */
+class PeerChannel {
+    #channel;
+    #events = new Events_js_1.Events(this);
+    #binaryType = 'nodebuffer';
+    /**
+     * Wrap a channel of the engine
+     * @param channel
+     * @internal
+     */
+    constructor(channel) {
+        this.#channel = channel;
+        EngineConnection_js_1.engineChannels.set(this, channel);
+        channel.stateChanged.subscribe((state) => {
+            this.#events.fire(state === 'closed' ? 'close' : state, {});
+        });
+        channel.onMessage.subscribe((message) => {
+            const data = typeof message === 'string' || this.#binaryType === 'nodebuffer'
+                ? message
+                : message.buffer.slice(message.byteOffset, message.byteOffset + message.byteLength);
+            this.#events.fire('message', { data: data }, data);
+        });
+        channel.bufferedAmountLow.subscribe(() => this.#events.fire('bufferedamountlow', {}));
+        channel.error.subscribe((error) => this.#events.fire('error', { error: error }, error));
+    }
+    /**
+     * The label of the channel.
+     */
+    get label() {
+        return this.#channel.label;
+    }
+    /**
+     * The id of the channel (its SCTP stream); `null` until the connection decides it.
+     */
+    get id() {
+        return this.#channel.id ?? null;
+    }
+    /**
+     * The subprotocol.
+     */
+    get protocol() {
+        return this.#channel.protocol;
+    }
+    /**
+     * Whether the messages arrive in order.
+     */
+    get ordered() {
+        return this.#channel.ordered;
+    }
+    /**
+     * How many times a message is sent again at most; `null` for a reliable channel.
+     */
+    get maxRetransmits() {
+        return this.#channel.maxRetransmits ?? null;
+    }
+    /**
+     * How long a message is sent again at most, in milliseconds; `null` for a reliable channel.
+     */
+    get maxPacketLifeTime() {
+        return this.#channel.maxPacketLifeTime ?? null;
+    }
+    /**
+     * Whether both peers created the channel themselves.
+     */
+    get negotiated() {
+        return this.#channel.negotiated;
+    }
+    /**
+     * `connecting`, `open`, `closing` or `closed`.
+     */
+    get readyState() {
+        return this.#channel.readyState;
+    }
+    /**
+     * The bytes sent but not handed to the network yet: wait for `bufferedamountlow` when it grows, to send a large
+     * amount of data without holding it all in memory.
+     */
+    get bufferedAmount() {
+        return this.#channel.bufferedAmount;
+    }
+    /**
+     * The value of `bufferedAmount` at which `bufferedamountlow` fires.
+     */
+    get bufferedAmountLowThreshold() {
+        return this.#channel.bufferedAmountLowThreshold;
+    }
+    set bufferedAmountLowThreshold(value) {
+        this.#channel.bufferedAmountLowThreshold = value;
+    }
+    /**
+     * The type of the binary messages received: `'nodebuffer'` (a `Buffer`, by default) or `'arraybuffer'`.
+     */
+    get binaryType() {
+        return this.#binaryType;
+    }
+    set binaryType(value) {
+        if (value !== 'nodebuffer' && value !== 'arraybuffer')
+            throw new TypeError(`Unsupported binaryType: ${value}`);
+        this.#binaryType = value;
+    }
+    /**
+     * The listener of `open`, given the event.
+     */
+    get onopen() {
+        return this.#events.handler('open');
+    }
+    set onopen(listener) {
+        this.#events.setHandler('open', listener);
+    }
+    /**
+     * The listener of `message`, given a `MessageEvent` whose `data` is the message.
+     */
+    get onmessage() {
+        return this.#events.handler('message');
+    }
+    set onmessage(listener) {
+        this.#events.setHandler('message', listener);
+    }
+    /**
+     * The listener of `closing`, given the event.
+     */
+    get onclosing() {
+        return this.#events.handler('closing');
+    }
+    set onclosing(listener) {
+        this.#events.setHandler('closing', listener);
+    }
+    /**
+     * The listener of `close`, given the event.
+     */
+    get onclose() {
+        return this.#events.handler('close');
+    }
+    set onclose(listener) {
+        this.#events.setHandler('close', listener);
+    }
+    /**
+     * The listener of `bufferedamountlow`, given the event.
+     */
+    get onbufferedamountlow() {
+        return this.#events.handler('bufferedamountlow');
+    }
+    set onbufferedamountlow(listener) {
+        this.#events.setHandler('bufferedamountlow', listener);
+    }
+    /**
+     * The listener of `error`, given an event whose `error` is the error.
+     */
+    get onerror() {
+        return this.#events.handler('error');
+    }
+    set onerror(listener) {
+        this.#events.setHandler('error', listener);
+    }
+    /**
+     * Send a message: a string, or binary data.
+     * @param data The message; its size may not exceed the maximum of the other peer (`PeerConnection.sctp.maxMessageSize`).
+     * @throws {DOMException} When the channel is not open (`InvalidStateError`).
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.send(JSON.stringify({x: 1, y: 2}))
+     * channel.send(new Uint8Array([1, 2, 3]))
+     * ```
+     */
+    send(data) {
+        if (this.#channel.readyState !== 'open')
+            throw new DOMException(`The channel ${this.label} is ${this.#channel.readyState}`, 'InvalidStateError');
+        if (typeof data === 'string')
+            return this.#channel.send(data);
+        const buffer = ArrayBuffer.isView(data)
+            ? Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+            : Buffer.from(data);
+        this.#channel.send(buffer);
+    }
+    /**
+     * Close the channel; the messages sent before are delivered first.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.close()
+     * ```
+     */
+    close() {
+        if (this.#channel.readyState === 'closing' || this.#channel.readyState === 'closed')
+            return;
+        this.#channel.close();
+    }
+    /**
+     * Add a listener of an event, given an event object (the W3C style).
+     * @param type The event: `open`, `message`, `closing`, `close`, `bufferedamountlow`, `error`.
+     * @param listener The listener.
+     * @param options `once`, `signal`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.addEventListener('message', (event: MessageEvent): void => console.log(event.data))
+     * ```
+     */
+    addEventListener(type, listener, options) {
+        this.#events.addEventListener(type, listener, options);
+    }
+    /**
+     * Remove a listener added with `addEventListener`.
+     * @param type The event.
+     * @param listener The listener.
+     * @param options `capture`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * const listener = (event: MessageEvent): void => console.log(event.data)
+     * channel.addEventListener('message', listener)
+     * channel.removeEventListener('message', listener)
+     * ```
+     */
+    removeEventListener(type, listener, options) {
+        this.#events.removeEventListener(type, listener, options);
+    }
+    /**
+     * Dispatch an event to the listeners, as `EventTarget.dispatchEvent()`: the ones of the W3C style get it, the ones
+     * of the Node.js style its value (the data of a `MessageEvent`).
+     * @param event The event.
+     * @returns Whether no listener called `preventDefault()`.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * //A message given again to the listeners
+     * channel.dispatchEvent(new MessageEvent('message', {data: 'again'}))
+     * ```
+     */
+    dispatchEvent(event) {
+        return this.#events.dispatch(event, ...event instanceof MessageEvent ? [event.data] : []);
+    }
+    /**
+     * Add a listener of an event, given the value of the event (the Node.js style).
+     * @param event The event.
+     * @param listener The listener: given the message for `message`, the error for `error`.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.on('message', (data: string | Buffer | ArrayBuffer): void => console.log(data))
+     * ```
+     */
+    on(event, listener) {
+        this.#events.on(event, listener);
+        return this;
+    }
+    /**
+     * Add a listener of the next emission of an event, given the value of the event.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * channel.once('open', (): void => channel.send('first'))
+     * ```
+     */
+    once(event, listener) {
+        this.#events.once(event, listener);
+        return this;
+    }
+    /**
+     * Remove a listener added with `on` or `once`.
+     * @param event The event.
+     * @param listener The listener.
+     * @returns The channel.
+     * @example
+     * ```typescript
+     * import type {PeerChannel} from '@lakutata/webrtc'
+     *
+     * declare const channel: PeerChannel
+     * const listener = (): void => console.log('closed')
+     * channel.on('close', listener)
+     * channel.off('close', listener)
+     * ```
+     */
+    off(event, listener) {
+        this.#events.off(event, listener);
+        return this;
+    }
+}
+exports.PeerChannel = PeerChannel;