uuid-base58

KO | EN

gitlite — search

#python #typescript #go #machine-learning #rust #docker #awesome #cli #vue #awesome-list #security #pytorch #ios #open-source

(★ 20)

Generate a RFC4122 compliant v4 UUID and return it encoded in base-58. This is great for creating unique IDs which only consume 22 characters of storage. Also provides base-58 encoding and decoding.

uuid-base58 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# uuid-base58

Generate a RFC4122 compliant v4 UUID and return it encoded in base-58. This is great for creating unique IDs which only consume 22 characters of storage (_some encodes are 21 characters_). Also library also provides base-58 encoding, decoding and validation.

## Installation

```sh
npm install uuid-base58
```

## Usage: creating a base58 UUID string

```typescript
import { uuid58 } from 'uuid-base58';

const id = uuid58();
```

## Usage: validation of a base58 UUID string

```typescript
import { strict as assert } from 'assert';
import { uuid58, valid } from 'uuid-base58';

const id = uuid58();
assert(valid(id)); // true
```

## API

The uuid58 package provides the following functions:

- `uuid58` - creates the RFC4122 v4 UUID encoded in base-58
- `encode(string)` - encodes a base-16 string in base-58
- `decode(string)` - decodes a string from base-58 to base-16
- `valid(string)` - returns true if the string is a valid base-58 string
- `uuidV4NoDash()` - creates a RFC4122 v4 UUID without dashes

## Notes on validation with valid(string)

The validation is optimistic such that if the encoding will decode into a valid UUID it will return true. The validation will return false if the representative number overflows 128bits or if the base58 number is zero (0). A UUID-based base58 value of `1` is a valid UUID of `00000000-0000-0000-0000-000000000000` and a base58 value of `2` is `00000000-0000-0000-0000-000000000001`. These are valid base58 values that can become valid UUIDs. The `valid()` function will also return false if a character in the base58 is not supported in the encoding hash alphabet which does not include `l` or `0` as an example.

## Testing

```sh
npm run test
```

## Performance

### <= v1.1

There is finite performance cost to translate a v4 UUID into base58. Testing the overhead for the translation to base58 exposes an additional 25% increase. Three quarters of the runtime was consumed calculating the v4 uuid. Additional work could be done to bring the uuid calculation internal and attempt to increase performance.

![performance graph](https://raw.githubusercontent.com/cbschuld/uuid-base58/master/__tests__/performance.png)

### Performance Update (>=v1.2.0)

In version =>1.2 additional performance work was completed by removing the validation process from the v4 UUID calculation and the runtime from the amazing [uuid](https://github.com/uuidjs/uuid) project was lifted and placed into `src/uuid` of this project. The package reduction was significant: 340kB to 5kB (18kB unpacked). Unfortunately little to no substantial performance increase although it was noticed v1.2 did consistently score better in realtime results but user+system remained nearly the same over 4M test generations. Additionally, the UUID string management process was updated to not create a traditional dashed uuid and the `uuid` v4 validation process was removed (_which addresses specific user input and does not intersect v4 calculation_). Performance increases are likely at a point of diminishing returns.

![performance graph](https://user-images.githubusercontent.com/231867/111826829-65468080-88a6-11eb-86ad-3f254c017a89.png)

## Package Size

For version >= 1.2.X the official dependency on the [uuid](https://github.com/uuidjs/uuid) project was removed. The solution and dependency are still in use but only the portion required for a v4 UUID was marshalled over. The runtime was altered slightly and added to the `src/uuid` path. Current sizing is around 5kB (18kB unpacked), down from 340kB.

## Base58 Alphabet

This solution uses the Bitcoin / IPFS hash alphabet:

```
123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
```

[Additional information on Base-58](https://en.wikipedia.org/wiki/Base58).

## Environment Support

- CommonJS: `const { uuid58 } = require('uuid-base58')`
- ESM (Node/bundlers): `import { uuid58 } from 'uuid-base58'`
- Node versions: tested on Node 18/20/22; engines set to `>=14`.
- Browser: RNG prefers `globalThis.crypto.getRandomValues`. If unavailable (very old browsers), a secure RNG is required and an error is thrown. Most modern browsers support Web Crypto.

### Examples

CommonJS (Node):

```js
// index.cjs
const { uuid58, encode, decode, valid, uuidV4NoDash } = require('uuid-base58');

const id = uuid58();
console.log('uuid58:', id);
console.log('valid:', valid(id));
```

ESM (Node or bundlers):

```js
// index.mjs or in a TypeScript file
import { uuid58, encode, decode, valid, uuidV4NoDash } from 'uuid-base58';

const id = uuid58();
console.log('uuid58:', id);
console.log('valid:', valid(id));
```

Browser (with bundler):

```ts
// In a front-end app (Vite, Webpack, etc.)
import { uuid58 } from 'uuid-base58';

// Requires Web Crypto (available in modern browsers)
const id = uuid58();
document.body.textContent = id;
```

See a runnable Vite example in `examples/vite-basic`.

## Migration from v1.x to v2.0

**Breaking Changes:**
- **Node.js 14+ required** - upgrade Node.js if using older versions
- **Package exports enforced** - only use documented import paths (`import { uuid58 } from 'uuid-base58'`)

**Non-breaking:**
- All API functions work identically
- CommonJS imports unchanged
- Enhanced browser compatibility

## Contact

**Twitter** - @cbschuld

## Contributing

Yes, thank you! Please update the docs and tests and add your name to the package.json file.

uuid-base58

uuid-base58 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

uuid-base58

uuid-base58 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README