@datadayrepos/js-id-web/README.md

Utils for generating identifiers in javascript browser environment. Using web crypto engine for random number generation.

# js-id-web

Utils for generating identifiers in javascript browser environment. Using web crypto engine for random number generation.

## 🚀 Content
- **XIDs**: ....
- **UID**: ....
- **Timebased**: Timestamo with a twist - increments with an integer if duplicates in the same ms.
- **Random**: Returns x number of chars based on your input.
- **Random Crockford**: Returns random nased on Crockford UI sensitive library.

## 🛠 Usage

```sh
pnpm i @datadayrepos/js-id-web
```

## 💻 Code 

```ts
import { UUID as _UUID, } from '@datadayrepos/js-id-web'

// Function to generate a UUID
export function UUID(): string {
  const { error, result } = _UUID()
  if (error)
    throw new Error('Failed to generate UUID')

  return result
}
```

```ts
import { generateXID as _generateXID } from '@datadayrepos/js-id-web'

// Function to generate a new XID. It returns a promise that resolves with the next ID.
export async function generateXID(): Promise<string> {
  const xidGenerator = await _generateXID()
  const id = xidGenerator.next()
  if (!id)
    throw new Error('Failed to generate XID')

  return id
}
```

```ts
import { genTimeId } from '@datadayrepos/js-id-web'

const id = genTimeId()
```

```ts
import { randomString as _randomString } from '@datadayrepos/js-id-web'

/**
 * Generates a pseudo-random string of a specified length using characters from a predefined charset.
 *
 * In environments like Node.js and the web, this method leverages more cryptographically secure
 * randomization mechanisms, making the generated strings more random and harder to predict.
 *
 * NOTE: Even in Node.js and the web, while the method is more secure than in GAS, it may not meet the
 * standards of high-security applications. Always assess your security requirements and consider
 * using dedicated cryptographic methods if robust security is a necessity.
 *
 * @param {number} keys - Length of the desired random string.
 */
export function randomString(length: number = 32): string {
  const { error, result } = _randomString(length)
  if (error)
    throw new Error('Failed to generate random string')

  return result
}
```

```ts
import { randomCrockford as _randomCrockford } from '@datadayrepos/js-id-web'

/**
 * Generates a pseudo-random string of a specified length using Crockford's Base32 character set.
 * This character set omits visually similar characters like 'i', 'l', 'o', and 'u' to minimize confusion,
 * making it easier for human reading and transcription.
 *
 * In environments like Node.js and the web, this method leverages more cryptographically secure
 * randomization mechanisms, making the generated strings more random and harder to predict.
 *
 * NOTE: Even with these mechanisms, the method may not meet the standards required for high-security
 * applications. Always assess your security requirements and consider using dedicated cryptographic
 * methods if robust security is a necessity.
 *
 * The Crockford's Base32 character set is especially useful in contexts where strings are manually
 * entered or read by humans, as it reduces the risk of errors due to misreading or misinterpreting
 * characters.
 *
 * @param {number} keys - Length of the desired random string.
 * @returns {object} An object with an error field (null if no error) and a result field containing the generated string.
 */
export function randomCrockford(length: number = 12): string {
  const { error, result } = _randomCrockford(length)
  if (error)
    throw new Error('Failed to generate Crockford encoded string')

  return result
}
```

```ts
import { generateSecureRandomPin as _generateSecureRandomPin } from '@datadayrepos/js-id-web'

/**
 * Generates a cryptographically secure random numeric PIN of the specified length.
 *
 * This method uses Web Crypto API in browsers or Node.js crypto module to provide robust security.
 * It is suitable for generating one-time passwords (OTP), verification codes, or numeric tokens.
 *
 * @param {number} length - The length of the PIN to generate. Defaults to 6.
 * @returns {Promise<{ error: string | null, result: string | null }>} An object with an error message if any, and the generated numeric PIN.
 */
export function generateSecureRandomPin(length: number = 6): string {
  const { error, result } = _generateSecureRandomPin(length)
  if (error)
    throw new Error('Failed to generate Crockford encoded string')

  return result
}
```

```ts
import { generateSecureRandomBase64 as _generateSecureRandomBase64 } from '@datadayrepos/js-id-web'

/**
 * Generates a cryptographically secure random 32-byte value and returns it as a base64 encoded string.
 *
 * This method uses Web Crypto API in browsers or Node.js crypto module to provide robust security.
 * It is suitable for generating keys or tokens that require high levels of randomness and security.
 *
 * @returns {Promise<{ error: string | null, result: string | null }>} An object with an error message if any, and the base64 encoded random string.
 */
export function generateSecureRandomBase64(length: number = 32): string {
  const { error, result } = _generateSecureRandomBase64(length)
  if (error)
    throw new Error('Failed to _generateSecureRandomBase64 encoded string')

  return result
}
```


## 🔗 Links
- **Repository**: [GitHub Repository](https://github.com/abyrint/js-id-web)
- **Issues**: [Report Bugs](https://github.com/abyrint/js-id-web/issues)

## 📄 License
[Prop](./LICENSE) License &copy; 2023 [Ivar Strand](https://github.com/datadayrepos)

www.abyrint.com