@ceeblue/web-utils 1.2.0 → 1.4.0

package/README.md

@@ -1,21 +1,62 @@
-# Ceeblue web framework
+[Usage](#usage) | [Building locally](#building-locally) | [Documentation](#documentation) | [Contribution](#contribution) | [License](#license)
 
-This is a web framework for CeeblueTV's web libraries. It is a collection of tools and utilities that are used across all of CeeblueTV's web projects.
+# Ceeblue Web Utilities
 
-## Installation
+This is a basic component library for Ceeblue projects, consisting of a collection of essential tools and utilities used in all Ceeblue web projects.
 
-You can install the package using npm:
+## Usage
 
+Add the library as a dependency to your npm project using:
 ```bash
 npm install @ceeblue/web-utils
 ```
+Then [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) the library into your project, for example:
+ ```javascript
+import { Util, ILog } from '@ceeblue/web-utils';
+```
+> 💡 **TIP**
+> 
+> If your project uses TypeScript, it is recommended that you set target: "ES6" in your configuration to match our use of ES6 features and ensure that your build will succeed (for those requiring a backward-compatible UMD version, a local build is recommended).
+> Then define the "moduleResolution" compiler option: "Node" in tsconfig.json helps with import failures by ensuring that TypeScript uses the correct import resolution strategy based on the targeted Node.js version.
+>   ```json
+>   {
+>      "compilerOptions": {
+>         "target": "ES6",
+>         "moduleResolution": "Node"
+>      }
+>   }
+>   ```
+
+## Building locally
+
+1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this repository
+2. Got to the `web-utils` folder and run `npm install` to install the packages dependencies.
+3. Run `npm run build`. The output will be five files placed in the **/dist/** folder:
+   - **web-utils.d.ts** Typescript definitions file
+   - **web-utils.js**: Bundled JavaScript library
+   - **web-utils.js.map**: Source map that associates the bundled library with the original source files
+   - **web-utils.min.js** Minified version of the library, optimized for size
+   - **web-utils.min.js.map** Source map that associates the minified library with the original source files
+
+```
+git clone https://github.com/CeeblueTV/web-utils.git
+cd web-utils
+npm install
+npm run build
+```
 
-Or manually add it to your `package.json` file:
+## Documentation
 
-```json
-{
-  "dependencies": {
-    "@ceeblue/web-utils": "latest"
-  }
-}
+This monorepo also contains built-in documentation about the APIs in the library, which can be built using the following npm command:
 ```
+npm run build:docs
+```
+You can access the documentation by opening the index.html file in the docs folder with your browser (`./docs/index.html`).
+
+## Contribution
+
+All contributions are welcome. Please see [our contribution guide](/CONTRIBUTING.md) for details.
+
+## License
+
+By contributing code to this project, you agree to license your contribution under the [GNU Affero General Public License](/LICENSE).

package/dist/web-utils.d.ts

@@ -1,11 +1,3 @@
-/**
- * Copyright 2024 Ceeblue B.V.
- * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
- * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
- */
-/**
- * BinaryReader allows to read binary data
- */
 declare class BinaryReader {
     private _data;
     private _size;
@@ -24,13 +16,14 @@ declare class BinaryReader {
     read16(): number;
     read24(): number;
     read32(): number;
+    read64(): number;
     readFloat(): number;
     readDouble(): number;
     read7Bit(bytes?: number): number;
     readString(): string;
     readHex(size: number): string;
     /**
-     * Read bytes, to convert bytes to string use String.fromCharCode(...reader.read(size))
+     * Read bytes, to convert bytes to string use String.fromCharCode(...reader.read(size)) or Util.stringify
      * @param {UInt32} size
      */
     read(size?: number): Uint8Array;
@@ -56,14 +49,19 @@ declare class BinaryWriter {
     size(): number;
     next(count?: number): BinaryWriter;
     clear(size?: number): BinaryWriter;
-    write(data: string | ArrayLike<number>): BinaryWriter;
+    /**
+     * Write binary data
+     * @param data
+     */
+    write(data: ArrayLike<number>): BinaryWriter;
     write8(value: number): BinaryWriter;
     write16(value: number): BinaryWriter;
     write24(value: number): BinaryWriter;
     write32(value: number): BinaryWriter;
+    write64(value: number): BinaryWriter;
     writeFloat(value: number): BinaryWriter;
     writeDouble(value: number): BinaryWriter;
-    write7Bit(value: number, bytes?: number): BinaryWriter;
+    write7Bit(value: number): BinaryWriter;
     writeString(value: string): BinaryWriter;
     writeHex(value: string): BinaryWriter;
     reserve(size: number): BinaryWriter;
@@ -94,6 +92,22 @@ declare class BitReader {
     read32(): number;
 }
 
+/**
+ * Compute ByteRate every delta time
+ */
+declare class ByteRate {
+    onBytes(bytes: number): void;
+    get delta(): number;
+    private _bytes;
+    private _time;
+    private _delta;
+    private _value;
+    constructor(delta?: number);
+    value(): number;
+    exact(): number;
+    addBytes(bytes: number): this;
+}
+
 /**
  * Parameters of connections
  */
@@ -124,11 +138,11 @@ type Params = {
  * Type of connection
  */
 declare enum Type {
-    HESP = "hesp",
-    WEBRTS = "webrts",
-    WEBRTC = "webrtc",
-    META = "meta",
-    DATA = "data"
+    HESP = "HESP",
+    WEBRTS = "WebRTS",
+    WEBRTC = "WebRTC",
+    META = "Meta",
+    DATA = "Data"
 }
 /**
  * Some connection utility functions
@@ -225,6 +239,32 @@ declare class EventEmitter {
     private _event;
 }
 
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+/**
+ * Some fix for JS MAP:
+ * - find(key) search an item in the map and returns undefined if not found
+ * - get(key) return the item if exists or otherwise create and returns it
+ * - set(key, value) returns the value of the item (rather the MAP)
+ */
+declare class FixMap<KeyType, ValueType> {
+    private _initValue;
+    [Symbol.iterator](): IterableIterator<[KeyType, ValueType]>;
+    get size(): number;
+    private _map;
+    constructor(_initValue: () => ValueType);
+    get(key: KeyType): ValueType;
+    find(key: KeyType): ValueType | undefined;
+    has(key: KeyType): boolean;
+    clear(): void;
+    delete(key: KeyType): boolean;
+    set(key: KeyType, value: ValueType): ValueType;
+    forEach(callbackfn: (value: ValueType, key: KeyType, map: Map<KeyType, ValueType>) => void, thisArg?: any): void;
+}
+
 /**
  * Copyright 2024 Ceeblue B.V.
  * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
@@ -593,13 +633,15 @@ declare function objectEntries(value: any): [string, any][];
  * @param obj Any objects, strings, exceptions, errors, or number
  * @param params.space `''`, allows to configure space in the string representation
  * @param params.decimal `2`, allows to choose the number of decimal to display in the string representation
- * @param params.recursive `false`, allows to serialize recursively every object value,  beware if a value refers to a already parsed value an infinite loop will occur.
+ * @param params.recursive `false`, allows to serialize recursively every object value, beware if a value refers to a already parsed value an infinite loop will occur
+ * @param params.noBin `false`, when set skip binary encoding and write inplace a bin-length information
  * @returns the final string representation
  */
 declare function stringify(obj: any, params?: {
     space?: string;
     decimal?: number;
     recursive?: number;
+    noBin?: boolean;
 }): string;
 /**
  * Encode a string to a binary representation
@@ -611,18 +653,36 @@ declare function toBin(value: string): Uint8Array;
  * Execute a promise in a safe way with a timeout if caller doesn't resolve it in the accurate time
  */
 declare function safePromise<T>(timeout: number, promise: Promise<T>): Promise<unknown>;
+/**
+ * Wait in milliseconds, requires a call with await keyword!
+ */
+declare function sleep(ms: number): Promise<unknown>;
+/**
+ * fetch help method with few usefull fix:
+ * - throw an string exception if response code is not 200 with the text of the response or uses statusText
+ */
+declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Extension parser
+ * @param path path to parse
+ * @returns the extension
+ */
+declare function parseExtension(path: string): string;
 
 declare const Util_EMPTY_FUNCTION: typeof EMPTY_FUNCTION;
+declare const Util_fetch: typeof fetch;
 declare const Util_objectEntries: typeof objectEntries;
 declare const Util_objectFrom: typeof objectFrom;
 declare const Util_options: typeof options;
+declare const Util_parseExtension: typeof parseExtension;
 declare const Util_safePromise: typeof safePromise;
+declare const Util_sleep: typeof sleep;
 declare const Util_stringify: typeof stringify;
 declare const Util_time: typeof time;
 declare const Util_timeOrigin: typeof timeOrigin;
 declare const Util_toBin: typeof toBin;
 declare namespace Util {
-  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_objectEntries as objectEntries, Util_objectFrom as objectFrom, Util_options as options, Util_safePromise as safePromise, Util_stringify as stringify, Util_time as time, Util_timeOrigin as timeOrigin, Util_toBin as toBin };
+  export { Util_EMPTY_FUNCTION as EMPTY_FUNCTION, Util_fetch as fetch, Util_objectEntries as objectEntries, Util_objectFrom as objectFrom, Util_options as options, Util_parseExtension as parseExtension, Util_safePromise as safePromise, Util_sleep as sleep, Util_stringify as stringify, Util_time as time, Util_timeOrigin as timeOrigin, Util_toBin as toBin };
 }
 
 /**
@@ -676,6 +736,8 @@ declare class WebSocketReliable extends EventEmitter {
      * binaryType, fix binary type to arrayBuffer
      */
     get binaryType(): BinaryType;
+    get recvByteRate(): number;
+    get sendByteRate(): number;
     /**
      * url of connection
      */
@@ -714,6 +776,8 @@ declare class WebSocketReliable extends EventEmitter {
     private _queueing;
     private _queueingBytes;
     private _ws?;
+    private _recvByteRate;
+    private _sendByteRate;
     /**
      * Create a WebSocketReliable object, and open it if an url is passed in argument
      * @param url URL of the WebSocket endpoint or null to start the connection later
@@ -741,6 +805,7 @@ declare class WebSocketReliable extends EventEmitter {
      * @param error the error reason if is not a proper close
      */
     close(error?: string): void;
+    private _send;
 }
 
 /**
@@ -751,4 +816,4 @@ declare class WebSocketReliable extends EventEmitter {
 
 declare const VERSION: string;
 
-export { BinaryReader, BinaryWriter, BitReader, Connect, EventEmitter, type ILog, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable };
+export { BinaryReader, BinaryWriter, BitReader, ByteRate, Connect, EventEmitter, FixMap, type ILog, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable };