@4players/odin-common 1.0.6 → 1.1.2

package/lib/esm/utility/bytearray.js

@@ -0,0 +1,24 @@
+import { assert, failure, success } from './result';
+export function toBytes(value) {
+    try {
+        assert(value !== undefined, 'undefined cannot be converted to byte array');
+        assert(value !== null, 'null cannot be converted to byte array');
+        const json = JSON.stringify(value);
+        const decoder = new TextEncoder();
+        return success(decoder.encode(json));
+    }
+    catch (error) {
+        return failure(String(error));
+    }
+}
+export function fromBytes(bytes) {
+    try {
+        assert(bytes.length > 0, 'empty byte array cannot be converted to value');
+        const json = new TextDecoder().decode(bytes);
+        const text = JSON.parse(json);
+        return success(text);
+    }
+    catch (error) {
+        return failure(String(error));
+    }
+}

package/lib/esm/utility/environment.js

@@ -0,0 +1,7 @@
+export function isAudioCapable() {
+    return typeof AudioContext !== 'undefined' && typeof Worker !== 'undefined';
+}
+export function isBlinkBrowser() {
+    const pattern = /(apple)?webkit\/537\.36/i;
+    return (typeof window !== 'undefined' && pattern.test(window.navigator.userAgent));
+}

package/lib/esm/utility/iterable.js

@@ -0,0 +1,7 @@
+export function find(entries, predicate) {
+    for (const entry of entries) {
+        if (predicate(entry))
+            return entry;
+    }
+    return undefined;
+}

package/lib/esm/utility/json.js

@@ -0,0 +1,3 @@
+export function toRaw(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/lib/esm/utility/result.js

@@ -0,0 +1,21 @@
+/* eslint-disable no-redeclare */
+export function assert(condition, message) {
+    if (!condition) {
+        fail(message);
+    }
+}
+export function fail(message) {
+    throw new Error(message);
+}
+export function success(value) {
+    return { type: 'Success', value };
+}
+export function failure(reason) {
+    return { type: 'Failure', reason };
+}
+export function unwrap(result) {
+    if (result.type === 'Failure') {
+        fail(result.reason);
+    }
+    return result.value;
+}

package/lib/esm/utility/rpc.js

@@ -0,0 +1,32 @@
+import * as msgpack from '@msgpack/msgpack';
+import { MessagePackRpcSchema } from '../schema/serialization';
+import { failure, success } from './result';
+export function msgpackEncode(value) {
+    return msgpack.encode(value);
+}
+export function msgpackDecode(buffer) {
+    return msgpack.decode(buffer);
+}
+export function parseRpc(buffer) {
+    try {
+        return success(MessagePackRpcSchema.parse(msgpackDecode(buffer)));
+    }
+    catch (error) {
+        return failure(String(error));
+    }
+}
+export function parseRpcMessage(events, rpc) {
+    if (!isKnownRpcMessage(events, rpc.name))
+        return undefined;
+    const parsed = events[rpc.name].safeParse(rpc.properties);
+    if (!parsed.success) {
+        return undefined;
+    }
+    return {
+        name: rpc.name,
+        properties: parsed.data,
+    };
+}
+export function isKnownRpcMessage(events, name) {
+    return name in events;
+}

package/lib/esm/utility/selector.js

@@ -0,0 +1,27 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export class Selector {
+    constructor(generators) {
+        this.generators = generators;
+        this.futures = generators.map(Selector.addIndex);
+    }
+    next() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const [result, index] = yield Promise.race(this.futures);
+            this.futures[index] = Selector.addIndex(this.generators[index], index);
+            return result;
+        });
+    }
+    static addIndex(generator, index) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return [yield generator(), index];
+        });
+    }
+}

package/lib/esm/utility/sleep.js

@@ -0,0 +1,23 @@
+/* eslint-disable no-redeclare */
+export function sleep(ms, value) {
+    if (ms <= 0) {
+        return Promise.resolve(value);
+    }
+    return new Promise((resolve) => setTimeout(() => resolve(value), ms));
+}
+export function abortableSleep(ms, signal) {
+    if (signal.aborted) {
+        return Promise.resolve('aborted');
+    }
+    return new Promise((resolve) => {
+        const onAbort = () => resolve('aborted');
+        signal.addEventListener('abort', onAbort, { once: true });
+        setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(undefined);
+        }, ms);
+    });
+}
+export function nextTick() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}

package/lib/esm/utility/strand.js

@@ -0,0 +1,44 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+export class Strand {
+    constructor() {
+        this.tasks = [];
+        this.running = false;
+    }
+    enqueue(task) {
+        return new Promise((resolve, reject) => {
+            const wrapped = () => __awaiter(this, void 0, void 0, function* () {
+                try {
+                    const result = yield task();
+                    resolve(result);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            this.tasks.push(wrapped);
+            if (!this.running) {
+                this.execute();
+            }
+        });
+    }
+    execute() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.running = true;
+            while (true) {
+                const task = this.tasks.shift();
+                if (task === undefined)
+                    break;
+                yield task();
+            }
+            this.running = false;
+        });
+    }
+}

package/lib/esm/utility/url.js

@@ -0,0 +1,23 @@
+import { failure, success } from './result';
+export function normalizeUrl(url) {
+    let normalized = url.trim();
+    if (url.indexOf('://') === -1)
+        normalized = `https://${normalized}`;
+    try {
+        return success(new URL(normalized));
+    }
+    catch (error) {
+        return failure(String(error));
+    }
+}
+export function extendUrl(base, path) {
+    let pathname = base.pathname;
+    if (pathname.endsWith('/') === false)
+        pathname += '/';
+    try {
+        return success(new URL(pathname + path, base));
+    }
+    catch (error) {
+        return failure(String(error));
+    }
+}

package/lib/esm/utility/validation.js

@@ -0,0 +1,21 @@
+export function isProperty(object, name) {
+    return name in object;
+}
+export function isFunction(value) {
+    return typeof value === 'function';
+}
+export function isNull(value) {
+    return typeof value === 'object' && value === null;
+}
+export function isNumber(value) {
+    return typeof value === 'number';
+}
+export function isObject(value) {
+    return typeof value === 'object';
+}
+export function isString(value) {
+    return typeof value === 'string';
+}
+export function isUndefined(value) {
+    return typeof value === 'undefined';
+}

package/lib/esm/utility/websocket.js

@@ -0,0 +1,80 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { WebSocket } from 'ws';
+import { failure, success } from './result';
+import { sleep } from './sleep';
+export function webSocketConnect(url, connectIntervals, clientOptions, onFailure) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const start = performance.now();
+        let connection = failure('no connection was attempted');
+        let cancelled = false;
+        const cancel = () => {
+            cancelled = true;
+        };
+        const connect = () => __awaiter(this, void 0, void 0, function* () {
+            for (let failures = 0; failures < connectIntervals.length && !cancelled; failures++) {
+                const nextReconnectAt = start + whenToConnect(failures, connectIntervals);
+                yield sleep(nextReconnectAt - performance.now(), 'interval');
+                if (cancelled) {
+                    return failure('cancelled');
+                }
+                connection = yield webSocketConnectOnce(url, clientOptions);
+                if (connection.type === 'Success') {
+                    return connection;
+                }
+                else if (onFailure !== undefined) {
+                    onFailure(failures + 1, cancel);
+                }
+            }
+            return connection;
+        });
+        return { connect, cancel };
+    });
+}
+export function webSocketConnectOnce(url, clientOptions) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let webSocket;
+        try {
+            webSocket = new WebSocket(url, clientOptions);
+        }
+        catch (reason) {
+            return failure(`unable to create websocket; ${reason}`);
+        }
+        return new Promise((resolve) => {
+            const onOpen = () => {
+                cleanup();
+                resolve(success(webSocket));
+            };
+            const onError = (event) => {
+                cleanup();
+                resolve(failure(event.message));
+            };
+            const onClose = (event) => {
+                cleanup();
+                resolve(failure(event.reason));
+            };
+            const cleanup = () => {
+                webSocket.removeEventListener('open', onOpen);
+                webSocket.removeEventListener('error', onError);
+                webSocket.removeEventListener('close', onClose);
+            };
+            webSocket.addEventListener('open', onOpen);
+            webSocket.addEventListener('error', onError);
+            webSocket.addEventListener('close', onClose);
+        });
+    });
+}
+function whenToConnect(failures, connectIntervals) {
+    const past_connects = connectIntervals
+        .slice(0, failures)
+        .reduce((a, b) => a + b, 0);
+    const interval = connectIntervals[failures] * Math.random();
+    return past_connects + interval;
+}

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+export * from './schema/serialization';
+export * from './schema/token';
+export * from './schema/room';
+export * from './schema/peer';
+export * from './schema/media';
+export * from './schema/message';
+export * from './schema/webrtc';
+export * from './rpc/commands';
+export * from './rpc/notifications';
+export * from './utility/base64';
+export * from './utility/bytearray';
+export * from './utility/iterable';
+export * from './utility/environment';
+export * from './utility/json';
+export * from './utility/result';
+export * from './utility/rpc';
+export * from './utility/selector';
+export * from './utility/sleep';
+export * from './utility/strand';
+export * from './utility/url';
+export * from './utility/validation';
+export * from './utility/websocket';
+export * from './plugin/api';

package/lib/rpc/commands.d.ts

@@ -0,0 +1,9 @@
+import * as z from 'zod';
+export type Commands = Record<string, {
+    request: z.ZodTypeAny;
+    response: z.ZodTypeAny;
+}>;
+export declare const MainCommandsRpc: Commands;
+export type MainCommands = typeof MainCommandsRpc;
+export declare const RoomCommandsRpc: Commands;
+export type RoomCommands = typeof RoomCommandsRpc;

package/lib/rpc/notifications.d.ts

@@ -0,0 +1,6 @@
+import * as z from 'zod';
+export type Notifications = Record<string, z.ZodTypeAny>;
+export declare const MainNotificationsRpc: Notifications;
+export type MainNotifications = typeof MainNotificationsRpc;
+export declare const RoomNotificationsRpc: Notifications;
+export type RoomNotifications = typeof RoomNotificationsRpc;

package/lib/utility/base64.d.ts

@@ -0,0 +1,3 @@
+import { Result } from './result';
+export declare function fromBase64(base64: string): Result<string>;
+export declare function fromBase64Url(base64uri: string): Result<string>;

package/lib/utility/base64.spec.d.ts

@@ -0,0 +1,4 @@
+export declare class Base64TestSuite {
+    decodeBase64(): void;
+    decodeBase64Url(): void;
+}

package/lib/utility/bytearray.d.ts

@@ -0,0 +1,4 @@
+import { ByteArray } from '../schema/serialization';
+import { Result } from './result';
+export declare function toBytes(value: any): Result<ByteArray>;
+export declare function fromBytes<T>(bytes: ByteArray): Result<T>;

package/lib/utility/bytearray.spec.d.ts

@@ -0,0 +1,4 @@
+export declare class ByteArrayTestSuite {
+    encodeByteArray(): void;
+    decodeByteArray(): void;
+}

package/lib/utility/environment.d.ts

@@ -0,0 +1,2 @@
+export declare function isAudioCapable(): boolean;
+export declare function isBlinkBrowser(): boolean;

package/lib/utility/environment.spec.d.ts

@@ -0,0 +1,4 @@
+export declare class EnvironmentTestSuite {
+    notAudioCapable(): void;
+    notBlinkBrowser(): void;
+}

package/lib/utility/iterable.d.ts

@@ -0,0 +1 @@
+export declare function find<T>(entries: Iterable<T>, predicate: (entry: T) => boolean): T | undefined;

package/lib/utility/iterable.spec.d.ts

@@ -0,0 +1,4 @@
+export declare class IterableTestSuite {
+    findReturnsElement(): void;
+    findReturnsUndefined(): void;
+}

package/lib/utility/json.d.ts

@@ -0,0 +1,4 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function toRaw<T extends JsonValue>(value: T): T;

package/lib/utility/json.spec.d.ts

@@ -0,0 +1,7 @@
+export declare class ToRawFunctionTestSuite {
+    handleString(): void;
+    handleNumber(): void;
+    handleBoolean(): void;
+    handleNull(): void;
+    handleArray(): void;
+}

package/lib/utility/result.d.ts

@@ -0,0 +1,17 @@
+export declare function assert(condition: unknown, message: string): asserts condition;
+export declare function fail(message: string): never;
+export type Failure = {
+    type: 'Failure';
+    reason: string;
+};
+export type Success<T> = {
+    type: 'Success';
+    value: T;
+};
+export type Result<T> = Success<T> | Failure;
+export declare function success<T>(value: T): Success<T>;
+export declare function success(value: void): Success<void>;
+export declare function failure(reason: string): Failure;
+export declare function unwrap<T>(result: Result<T>): T;
+export type Accept<T> = (result: T) => void;
+export type Reject = (reason: Error) => void;

package/lib/utility/rpc.d.ts

@@ -0,0 +1,20 @@
+import * as z from 'zod';
+import { MessagePackRpc } from '../schema/serialization';
+import { Result } from './result';
+import { Notifications } from '../rpc/notifications';
+export declare function msgpackEncode(value: unknown): ArrayBuffer;
+export declare function msgpackDecode(buffer: ArrayBuffer): unknown;
+export interface RpcMessage {
+    name: string;
+    properties: unknown;
+}
+export interface TypedRpcMessage<Name extends string, Properties> extends RpcMessage {
+    name: Name;
+    properties: Properties;
+}
+export type RealizedEvents<E extends Notifications> = {
+    [Name in Extract<keyof E, string>]: TypedRpcMessage<Name, z.infer<E[Name]>>;
+}[Extract<keyof E, string>];
+export declare function parseRpc(buffer: ArrayBuffer): Result<MessagePackRpc>;
+export declare function parseRpcMessage<E extends Notifications>(events: E, rpc: RpcMessage): RealizedEvents<E> | undefined;
+export declare function isKnownRpcMessage<E extends Notifications>(events: E, name: string): name is Extract<keyof E, string>;

package/lib/utility/selector.d.ts

@@ -0,0 +1,7 @@
+export declare class Selector<T extends Array<() => PromiseLike<unknown>>> {
+    private readonly generators;
+    private readonly futures;
+    constructor(generators: T);
+    next(): Promise<Awaited<ReturnType<T[number]>>>;
+    static addIndex(generator: () => PromiseLike<unknown>, index: number): Promise<[unknown, number]>;
+}

package/lib/utility/sleep.d.ts

@@ -0,0 +1,4 @@
+export declare function sleep(ms: number, value: void): Promise<void>;
+export declare function sleep<T extends string>(ms: number, value: T): Promise<T>;
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<void | 'aborted'>;
+export declare function nextTick(): Promise<void>;

package/lib/utility/strand.d.ts

@@ -0,0 +1,6 @@
+export declare class Strand {
+    private readonly tasks;
+    private running;
+    enqueue<T>(task: () => Promise<T>): Promise<T>;
+    private execute;
+}

package/lib/utility/url.d.ts

@@ -0,0 +1,3 @@
+import { Result } from './result';
+export declare function normalizeUrl(url: string): Result<URL>;
+export declare function extendUrl(base: URL, path: string): Result<URL>;

package/lib/utility/validation.d.ts

@@ -0,0 +1,7 @@
+export declare function isProperty<T extends object>(object: T, name: string): name is Extract<keyof T, string>;
+export declare function isFunction(value: any): value is Function;
+export declare function isNull(value: any): boolean;
+export declare function isNumber(value: any): value is Number;
+export declare function isObject(value: any): value is Object;
+export declare function isString(value: any): value is String;
+export declare function isUndefined(value: any): value is undefined;

package/lib/utility/websocket.d.ts

@@ -0,0 +1,7 @@
+import { ClientOptions, WebSocket } from 'ws';
+import { Result } from './result';
+export declare function webSocketConnect(url: URL, connectIntervals: number[], clientOptions?: ClientOptions, onFailure?: (failures: number, cancel: () => void) => void): Promise<{
+    connect: () => Promise<Result<WebSocket>>;
+    cancel: () => void;
+}>;
+export declare function webSocketConnectOnce(url: URL, clientOptions?: ClientOptions): Promise<Result<WebSocket>>;

package/lib/utility/websocket.spec.d.ts

@@ -0,0 +1,6 @@
+export declare class WebSocketTestSuite {
+    connectOnce(): Promise<void>;
+    connectWithRetries(): Promise<void>;
+    resetWebSocket(): void;
+    closeWebSocket(): void;
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@4players/odin-common",
-  "version": "1.0.6",
-  "description": "A collection of commonly used type definitions and schemas across ODIN web projects",
+  "version": "1.1.2",
+  "description": "A collection of commonly used type definitions and utility functions across ODIN web projects",
   "author": "Josho Bleicker <josho.bleicker@4players.io> (https://www.4players.io)",
   "homepage": "https://www.4players.io",
   "keywords": [
     "odin",
     "sdk",
+    "utility",
     "schemas",
     "types",
     "zod"
@@ -15,26 +16,33 @@
   "license": "ISC",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
-  "types": "./lib/types/index.d.js",
+  "types": "./lib/index.d.ts",
   "scripts": {
+    "clean": "rm -rf lib",
     "build": "tsc -b ./tsconfig.cjs.json ./tsconfig.esm.json",
-    "lint": "eslint . --ext .ts"
+    "format": "prettier 'src/**/*.ts' --write",
+    "lint": "eslint . --ext .ts",
+    "test": "testyts"
   },
   "engines": {
     "node": ">=14"
   },
   "dependencies": {
+    "@msgpack/msgpack": "~3.0.0-beta2",
+    "ws": "~8.15.0",
     "zod": "~3.22.0"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "~6.13.0",
-    "@typescript-eslint/parser": "~6.13.0",
-    "eslint": "~8.54.0",
+    "@typescript-eslint/eslint-plugin": "~6.14.0",
+    "@typescript-eslint/parser": "~6.14.0",
+    "@types/ws": "~8.5.0",
+    "eslint": "~8.55.0",
     "eslint-config-semistandard": "~17.0.0",
     "eslint-plugin-import": "~2.29.0",
     "eslint-plugin-node": "~11.1.0",
     "eslint-plugin-promise": "~6.1.0",
-    "prettier": "3.1.0",
+    "prettier": "~3.1.0",
+    "testyts": "~1.5.0",
     "typescript": "~5.2.0"
   }
 }

package/lib/types/index.d.ts

@@ -1,10 +0,0 @@
-export * from './schemas/serialization';
-export * from './schemas/token';
-export * from './schemas/room';
-export * from './schemas/peer';
-export * from './schemas/media';
-export * from './schemas/message';
-export * from './schemas/webrtc';
-export * from './streams/commands';
-export * from './streams/notifications';
-export * from './plugins/api';