README.md

@agoralabs/uuid

A UUID v4 utility package that allows generation and encoding/decoding.

---

Table of Contents

• 1. Getting Started
  • 1.1. Installation
  • 1.2. API Reference
    • 1.2.1. generate([options])
    • 1.2.2. decode(value)
    • 1.2.3. encode(value, [options])
    • 1.2.4. IExtraOptions
• 2. Appendix
  • 2.1. Useful Commands
• 3. How To Contribute
• 4. License
• 5. Credits

🪄 1. Getting Started

1.1. Installation

You can install the types using:

npm add @agoralabs-sh/uuid

^{Back to top ^}

1.2. API Reference

1.2.1. generate([options])

Generates a random UUID v4 string.

Parameters

Name	Type	Required	Default	Description
options	IExtraOptions	no	-	Options that allows the UUID to to be returned to uppercase.

Returns

Type	Description
string	A random UUID v4 string.

Example

import { generate } from '@agoralabs-sh/uuid';

const uuid = generate();

console.log(uuid);
// 18b0e62a-21c6-4e27-a813-825716f0fedb

^{Back to top ^}

1.2.2. decode(value)

Decodes the UUID into a byte array. This removes any hyphens and case is preserved.

Parameters

Name	Type	Required	Default	Description
value	string	yes	-	The UUID to decode

Returns

Type	Description
Uint8Array	The UUID as bytes.

Example

import { decode } from '@agoralabs-sh/uuid';

const decoded = decode('18b0e62a-21c6-4e27-a813-825716f0fedb');

console.log(decoded);
// [24, 176, 230, 42, 33, 198, 78, 39, 168, 19, 130, 87, 22, 240, 254, 219]

^{Back to top ^}

1.2.3. encode(value, [options])

Encodes the UUID into the human-readable format with hyphens added.

Parameters

Name	Type	Required	Default	Description
value	Uint8Array	yes	-	A UUID byte array.
options	IExtraOptions	no	-	Options that allows the UUID to to be returned to uppercase.

Returns

Type	Description
string	The encoded UUID string as a human-readable string.

Example

import { encode } from '@agoralabs-sh/uuid';

const uuid = encode(new Uint8Array([24, 176, 230, 42, 33, 198, 78, 39, 168, 19, 130, 87, 22, 240, 254, 219]));

console.log(uuid);
// 18b0e62a-21c6-4e27-a813-825716f0fedb

^{Back to top ^}

1.2.4. IExtraOptions

Name	Type	Required	Default	Description
uppercase	boolean	no	false	Whether the UUID is transformed to uppercase.

^{Back to top ^}

📑 2. Appendix

2.1. Useful Commands

Command	Description
pnpm run build	Generates build and TypeScript declaration files to the dist/ directory.
pnpm run clean	Deletes the dist/ directory and the tsconfig.*.tsbuildinfo files.
pnpm run generate:index	Generates/overwrites the main index.ts file used for exporting all files.
pnpm run lint	Runs the linter based on the rules in eslint.config.mjs.
pnpm run prettier	Runs the prettier based on the rules in prettier.config.mjs.

^{Back to top ^}

👏 3. How To Contribute

Please read the Contributing Guide to learn about the development process.

^{Back to top ^}

📄 4. License

Please refer to the LICENSE file.

^{Back to top ^}

🫶 5. Credits

• The generation of the UUID is thanks to the amazing @dhest and their amazing @stablelib library.

^{Back to top ^}