@ceeblue/web-utils 1.1.0 → 1.3.0

package/README.md

@@ -1,21 +1,65 @@
-# 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 Web base compoments for CeeblueTV's web libraries : a collection of tools and utilities used across all of CeeblueTV's 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](https://www.typescriptlang.org/), it is recommended to set `"target": "ES6"` in your configuration to align with our usage of ES6 features and ensures that your build will succeed (for those requiring a backwards-compatible [UMD](https://github.com/umdjs/umd) version, a [local build](#building-locally) is advised).
+> Then Defining the compiler option `"moduleResolution": "Node"` in **tsconfig.json** helps with import errors by ensuring that TypeScript uses the correct strategy for resolving imports based on the targeted Node.js version.
+>   ```json
+>   {
+>      "compilerOptions": {
+>         "target": "ES6",
+>         "moduleResolution": "Node"
+>      }
+>   }
+>   ```
+
+## Building locally
 
-Or manually add it to your `package.json` file:
+1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this repository
+2. Enter the `webr-utils` folder and run `npm install` to install packages dependencies.
+3. Execute `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
 
-```json
-{
-  "dependencies": {
-    "@ceeblue/web-utils": "latest"
-  }
-}
 ```
+git clone https://github.com/CeeblueTV/web-utils.git
+cd web-utils
+npm install
+npm run build
+```
+
+## Documentation
+
+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`), or if you have installed and started the [http-server package](https://www.npmjs.com/package/http-server) by navigating to:
+```
+http://localhost:8080/docs/
+```
+
+## 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;
@@ -124,11 +122,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
@@ -549,10 +547,6 @@ declare const SDP: {
 /**
  * Some basic utility functions
  */
-/**
- * Version of the library
- */
-declare const VERSION = "?";
 /**
  * An empty lambda function, pratical to disable default behavior of function or events which are not expected to be null
  * @example
@@ -597,27 +591,56 @@ 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
+ * @param value string value to convert
+ * @returns binary conversion
+ */
 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_VERSION: typeof VERSION;
+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_VERSION as VERSION, Util_objectEntries as objectEntries, Util_objectFrom as objectFrom, Util_options as options, 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 };
 }
 
 /**
@@ -671,6 +694,8 @@ declare class WebSocketReliable extends EventEmitter {
      * binaryType, fix binary type to arrayBuffer
      */
     get binaryType(): BinaryType;
+    get recvByteRate(): number;
+    get sendByteRate(): number;
     /**
      * url of connection
      */
@@ -709,6 +734,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
@@ -736,6 +763,15 @@ declare class WebSocketReliable extends EventEmitter {
      * @param error the error reason if is not a proper close
      */
     close(error?: string): void;
+    private _send;
 }
 
-export { BinaryReader, BinaryWriter, BitReader, Connect, EventEmitter, type ILog, NetAddress, Numbers, Queue, SDP, Util, WebSocketReliable };
+/**
+ * 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.
+ */
+
+declare const VERSION: string;
+
+export { BinaryReader, BinaryWriter, BitReader, Connect, EventEmitter, type ILog, NetAddress, Numbers, Queue, SDP, Util, VERSION, WebSocketReliable };