\n A UUID v4 utility package that allows generation and encoding/decoding.\n
\n\n---\n\n### Table of Contents\n\n* [1. Getting Started](#-1-getting-started)\n - [1.1. Installation](#11-installation)\n - [1.2. API Reference](#12-api-reference)\n - [1.2.1. `generate([options])`](#121-generateoptions)\n - [1.2.2. `decode(value)`](#122-decodevalue)\n - [1.2.3. `encode(value, [options])`](#123-encodevalue-options)\n - [1.2.4. `IExtraOptions`](#124-iextraoptions)\n* [2. Appendix](#-2-appendix)\n - [2.1. Useful Commands](#21-useful-commands)\n* [3. How To Contribute](#-3-how-to-contribute)\n* [4. License](#-4-license)\n* [5. Credits](#-5-credits)\n\n## 🪄 1. Getting Started\n\n### 1.1. Installation\n\nYou can install the types using:\n```shell\nnpm add @agoralabs-sh/uuid\n```\n\n[Back to top ^][table-of-contents]\n\n### 1.2. API Reference\n\n#### 1.2.1. `generate([options])`\n\n> Generates a random UUID v4 string.\n\n##### Parameters\n\n| Name | Type | Required | Default | Description |\n|---------|---------------------------------------|----------|---------|--------------------------------------------------------------|\n| options | [`IExtraOptions`](#124-iextraoptions) | no | - | Options that allows the UUID to to be returned to uppercase. |\n\n##### Returns\n\n| Type | Description |\n|----------|--------------------------|\n| `string` | A random UUID v4 string. |\n\n##### Example\n\n```typescript\nimport { generate } from '@agoralabs-sh/uuid';\n\nconst uuid = generate();\n\nconsole.log(uuid);\n// 18b0e62a-21c6-4e27-a813-825716f0fedb\n```\n\n[Back to top ^][table-of-contents]\n\n#### 1.2.2. `decode(value)`\n\n> Decodes the UUID into a byte array. This removes any hyphens and case is preserved.\n\n##### Parameters\n\n| Name | Type | Required | Default | Description |\n|-------|----------|----------|---------|--------------------|\n| value | `string` | yes | - | The UUID to decode |\n\n##### Returns\n\n| Type | Description |\n|--------------|--------------------|\n| `Uint8Array` | The UUID as bytes. |\n\n##### Example\n\n```typescript\nimport { decode } from '@agoralabs-sh/uuid';\n\nconst decoded = decode('18b0e62a-21c6-4e27-a813-825716f0fedb');\n\nconsole.log(decoded);\n// [24, 176, 230, 42, 33, 198, 78, 39, 168, 19, 130, 87, 22, 240, 254, 219]\n```\n\n[Back to top ^][table-of-contents]\n\n#### 1.2.3. `encode(value, [options])`\n\n> Encodes the UUID into the human-readable format with hyphens added.\n\n##### Parameters\n\n| Name | Type | Required | Default | Description |\n|---------|---------------------------------------|----------|---------|--------------------------------------------------------------|\n| value | `Uint8Array` | yes | - | A UUID byte array. |\n| options | [`IExtraOptions`](#124-iextraoptions) | no | - | Options that allows the UUID to to be returned to uppercase. |\n\n##### Returns\n\n| Type | Description |\n|----------|-----------------------------------------------------|\n| `string` | The encoded UUID string as a human-readable string. |\n\n##### Example\n\n```typescript\nimport { encode } from '@agoralabs-sh/uuid';\n\nconst uuid = encode(new Uint8Array([24, 176, 230, 42, 33, 198, 78, 39, 168, 19, 130, 87, 22, 240, 254, 219]));\n\nconsole.log(uuid);\n// 18b0e62a-21c6-4e27-a813-825716f0fedb\n```\n\n[Back to top ^][table-of-contents]\n\n#### 1.2.4. `IExtraOptions`\n\n| Name | Type | Required | Default | Description |\n|-----------|----------------------------------------------------------|----------|---------|-----------------------------------------------|\n| uppercase | `boolean` | no | `false` | Whether the UUID is transformed to uppercase. |\n\n[Back to top ^][table-of-contents]\n\n## 📑 2. Appendix\n\n### 2.1. Useful Commands\n\n| Command | Description |\n|---------------------------|-----------------------------------------------------------------------------|\n| `pnpm run build` | Generates build and TypeScript declaration files to the `dist/` directory. |\n| `pnpm run clean` | Deletes the `dist/` directory and the `tsconfig.*.tsbuildinfo` files. |\n| `pnpm run generate:index` | Generates/overwrites the main `index.ts` file used for exporting all files. |\n| `pnpm run lint` | Runs the linter based on the rules in `eslint.config.mjs`. |\n| `pnpm run prettier` | Runs the prettier based on the rules in `prettier.config.mjs`. |\n\n[Back to top ^][table-of-contents]\n\n## 👏 3. How To Contribute\n\nPlease read the [**Contributing Guide**][contribute] to learn about the development process.\n\n[Back to top ^][table-of-contents]\n\n## 📄 4. License\n\nPlease refer to the [LICENSE][license] file.\n\n[Back to top ^][table-of-contents]\n\n## 🫶 5. Credits\n\n* The generation of the UUID is thanks to the amazing [@dhest](https://github.com/dchest) and their amazing [@stablelib](https://github.com/StableLib/stablelib) library.\n\n[Back to top ^][table-of-contents]\n\n\n[contribute]: ../../CONTRIBUTING.md\n[license]: LICENSE\n[table-of-contents]: #table-of-contents\n\n","readmeFilename":"README.md"}