Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/metastable-void/es-first-aid

The Fundamental Utilities for ECMAScript
https://github.com/metastable-void/es-first-aid

base64 crc32 ecmascript promise utf-8 uuid

Last synced: 22 days ago
JSON representation

The Fundamental Utilities for ECMAScript

Awesome Lists containing this project

README 

        
# es-first-aid

The Fundamental Utilities for ECMAScript.



- Missing utility functions for ECMAScript

- Random numbers/bytes...

- UUIDs

- CRC-32

- Most basic general utility classes for various applications

- Base64 encode/decode

- UTF-8 string encode/decode

- Hex string encode/decode

- ...



## API



```typescript

globalThis.firstAid;



// where

declare const firstAid: FirstAid;



interface Iterable {

    [Symbol.iterator](): Iterator;

}



type BufferSource = ArrayBuffer | ArrayBufferView;



type MaybePromise = Promise | T;



interface PromiseComposition extends Promise> {

    promises: Promise[];

    [Symbol.iterator]: () => IterableIterator;

    results: () => Promise;

    rejections: () => Promise;

    fulfilled: (callback: (result: T) => returnType) => PromiseComposition;

    rejected: (callback: (reason: any) => returnType) => PromiseComposition;

}



interface SymbolObject {

    symbol: symbol;

}



interface FirstAid {

    VERSION: string;



    firstAid: FirstAid;



    constructor: new () => FirstAid;



    PromiseComposition: new (... promises: MaybePromise[]) => PromiseComposition;



    // TypedArray constructor. (This is abstract; you cannot instantiate this.)

    TypedArray: Function;



    // Returns true if the passed value is a TypedArray.

    isTypedArray: (value: any) => boolean;



    // -0.

    MINUS_ZERO: number;



    // Creates a new null-prototype object.

    createNullPrototypeObject: () => {};



    // Wraps an object in a read-only Proxy.

    createReadOnlyProxy: (obj: T) => T;



    // Returns true if the function throws.

    checkForError: (f: () => void) => boolean;



    // Returns true if the passed object is a revoked Proxy.

    // This function is no longer always-reliable due to changes made to ECMAScript specs.

    isRevokedProxy: (value: any) => boolean;



    // Returns true if the passed object has a valid [[Construct]] slot.

    isConstructor: (value: any) => boolean;



    // Converts a value into a 32-bit signed integer.

    toInt32: (value: any) => number;



    // Returns true if the passed value is a 32-bit signed integer.

    isInt32: (value: any) => boolean;



    // Tries to convert a value into an integer.

    toInt: (value: any) => number;



    // Returns true if the passed value is a valid safe integer in ECMAScript.

    isInt: (value: any) => boolean;



    // Returns true if the passed value is null.

    isNull: (value: any) => boolean;



    // Returns true if the passed value is an object. (This includes functions but not null.)

    isObject: (value: any) => boolean;



    // Returns true if the passed value is a valid property key (string or symbol).

    isPropertyKey: (value: any) => boolean;



    // Returns Unicode code points of the given string.

    getCodePoints: (str: string) => Iterable;



    // Encodes a string into UTF-8 bytes.

    encodeString: (str: string) => Uint8Array;



    // Decodes a string from UTF-8 bytes.

    decodeString: (utf8Bytes: BufferSource) => string;



    // Converts a buffer or view into a Uint8Array.

    toUint8Array: (buffer: BufferSource) => Uint8Array;



    // Get a copied ArrayBuffer from BufferSource.

    getCopyBuffer: (buffer: BufferSource) => ArrayBuffer;



    // Encodes bytes into a hex string.

    encodeHex: (buffer: BufferSource) => string;



    // Decodes a hex string.

    decodeHex: (hexString: string) => Uint8Array;



    // Encodes bytes into Base-64 encoded string.

    encodeBase64: (buffer: BufferSource) => string;



    // Decodes a Base-64 encoded string.

    decodeBase64: (base64String: string) => Uint8Array;



    // Calculates a CRC-32 check sum of the given buffer. (Signed 32-bit integer)

    crc32: (buffer: BufferSource) => number;



    // Get the CRC-32 sum as a Uint8Array.

    crc32Bytes: (buffer: BufferSource) => Uint8Array;



    // Fills the given buffer with Math.random() values.

    randomFillInsecure: (buffer: BufferSource) => Uint8Array;



    // Fills the given buffer with secure random values.

    // Currently, Node.JS, Web, and Deno is supported.

    randomFill: (buffer: BufferSource) => Uint8Array;



    // Returns a random number in [0, 1) range.

    // Uses Math.random() if isInsecure is true.

    random: (isInsecure?: boolean) => number;



    // Returns a random number in (0, 1] range.

    // Uses Math.random() if isInsecure is true.

    randomNonZero: (isInsecure?: boolean) => number;



    // Returns a standard normal random number.

    // Uses Math.random() if isInsecure is true.

    randomNormal: (isInsecure?: boolean) => number;



    // Returns a standard exponential random number.

    // Uses Math.random() if isInsecure is true.

    randomExponential: (isInsecure?: boolean) => number;



    // Returns a Xenakis random number.

    // Uses Math.random() if isInsecure is true.

    randomXenakis: (isInsecure?: boolean) => number;



    // Returns true in the given probability.

    // Uses Math.random() if isInsecure is true.

    randomProb: (prob: number, isInsecure?: boolean) => boolean;



    // Generates a version-4 UUID string from the given buffer.

    getUuidFromBytes: (arr: BufferSource) => string;



    // Generates a random version-4 UUID string.

    // Uses Math.random() if isInsecure is true.

    getRandomUuid: (isInsecure?: boolean) => string;



    // Returns true if the given value is a valid UUID string.

    validateUuid: (uuid: string) => boolean;



    // Calls the given function in an asynchronous manner.

    callAsync: (callback: (... argumentsList: argumentType[]) => MaybePromise, thisArgument: any, ... argumentList: argumentType[]) => Promise;



    // Converts any value into a Promise.

    toPromise: (value: MaybePromise) => Promise;



    // Returns a current Unix timestamp in milliseconds.

    getTime: () => number;



    // Encodes an object into JSON bytes.

    encodeJson: (value: any) => Uint8Array;



    // Decodes an object from JSON bytes.

    decodeJson: (bytes: BufferSource) => any;



    // Throws an error if assertion is false

    assert: (assertion: boolean, message?: string) => void;



    // Compare two values in a JSON-like manner

    compareJson: (a: any, b: any) => boolean;



    // Returns the passed object as a constructor.

    IdentityConstructor: new (obj: T) => T;



    // Creates an object for a symbol.

    SymbolObject: new (symbol: symbol | SymbolObject) => SymbolObject;

}

```



## License

Copyright © 2021 Menhera.org



Licensed under the Apache 2.0 license.