# aguid

> A Standard-Compliant Globally Unique IDentifier (GUID) generator for Node.js and Browser

Latest version **2.0.0** (published 2017-01-27) · ISC license · 0 weekly downloads

## Install

```sh
npm install aguid
pnpm add aguid
yarn add aguid
bun add aguid
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2017-01-27 |
| First published | 2015-02-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 57 |
| Author | @nelsonic |
| Maintainers | nelsonic |
| Keywords | RFC4122, GUID, Generate, Node, Browser |

## Links

- npm: https://www.npmjs.com/package/aguid
- Repository: https://github.com/dwyl/aguid
- Issues: https://github.com/dwyl/aguid/issues
- npm.io page: https://npm.io/package/aguid

## Dependencies (1)

- [uuid](https://npm.io/package/uuid.md) ^3.0.1

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2017-01-27
- 1.0.4 — 2015-11-19
- 1.0.3 — 2015-03-04
- 1.0.2 — 2015-03-04
- 1.0.1 — 2015-03-04
- 1.0.0 — 2015-02-25

## README

# aguid

A **G**lobally **U**nique **ID**entifier (GUID) generator in JS.

[![Node.js Version][node-version-image]][node-version-url]
[![NPM Version][npm-image]][npm-url]
[![Build Status](https://travis-ci.org/dwyl/aguid.svg)](https://travis-ci.org/dwyl/aguid)
[![codecov.io](https://codecov.io/github/dwyl/aguid/coverage.svg?branch=master)](https://codecov.io/github/dwyl/aguid?branch=master)
[![Code Climate](https://codeclimate.com/github/dwyl/aguid/badges/gpa.svg)](https://codeclimate.com/github/dwyl/aguid)
[![Dependency Status](https://david-dm.org/dwyl/aguid.svg)](https://david-dm.org/dwyl/aguid)

## Why?

There are already *great* **node** module(s) for generating *random* UUIDs:
https://www.npmjs.com/search?q=uuid

What we need is a way to return the *same* UUID/GUID for a *given* input string;
i.e. [***Deterministic***](http://en.wikipedia.org/wiki/Deterministic_system) !

### Use Case

The **use-case** is very specific: generate a **key** for a record in a **database**.

Imagine you want to store a person's *personal* details in a record
but don't want use a *username* or *email* as the ***key*** for the record.
We solved this by creating a UUID (string) from the username or email address
and using that instead. (see usage below)


## Usage

### Install

```sh
npm install aguid --save
```

### Generate a Deterministic GUID given an input

```javascript
var aguid = require('aguid');
var guid  = aguid("hello@world.io"); // d828ed52-32ed-4908-86df-df934d3c315d (ALWAYS)
// use the guid as the key for our record in Redis, ElasticSearch, Postgres, etc.

```

***Note***: even though the GUID we are returning for a given input is *deterministic*,
it's *still* ***globally unique*** because we are using SHA256 hash for the characters.
and in our *specific* use-case we are hashing an email address
(which is its' self *unique* be *definition*!)


### Generate a *Random* GUID when invoked without argument

```javascript
var aguid = require('aguid');
var guid  = aguid(); // 525be54a-1101-46bf-97d7-2e9c89dd1b16 (*Random*)
// use for what ever you need a *random* guid

```


## Research

### Background

+ Wikipedia UUID (*gentler* intro):
http://en.wikipedia.org/wiki/Universally_unique_identifier
+ Universally Unique IDentifier (UUID) Specification:
http://tools.ietf.org/html/rfc4122
+ V.4 *Random* UUID:
http://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_.28random.29

### Implementation

+ Hex to Base64 and back:
http://stackoverflow.com/questions/23190056/hex-to-base64-converter-for-javascript
+ Snowflake approach:
http://blog.tompawlak.org/generate-unique-identifier-nodejs-javascript
+ GUIDs using Math.random() https://gist.github.com/jed/982883

### Dependency

Instead of trying to re-invent this, I invested the time to read,
download and play with the source-code
for **node-uuid** (the most popular & *performant* module for creating GUIDs):
https://github.com/broofa/node-uuid
See: [#3](https://github.com/dwyl/aguid/issues/3)

[node-version-image]: https://img.shields.io/node/v/aguid.svg?style=flat
[node-version-url]: http://nodejs.org/download/
[npm-image]: https://img.shields.io/npm/v/aguid.svg?style=flat
[npm-url]: https://npmjs.org/package/aguid

---
_Source: https://npm.io/package/aguid · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._