ongteckwu / typeid-ts

TypeID UUIDv7 implementation in Typescript (Lib and CLI)

TypeID Typescript

A typescript implementation of TypeIDs

TypeIDs are a modern, type-safe, globally unique identifier based on the upcoming UUIDv7 standard. They provide a ton of nice properties that make them a great choice as the primary identifiers for your data in a database, APIs, and distributed systems. Read more about TypeIDs in their spec.

This particular implementation provides a TS library for generating and parsing TypeIDs.

UUIDv7

Uses the package https://github.com/LiosK/uuidv7

Installation

For library:

npm install typeid-ts

For cli tool:

npm install -g typeid-ts

CLI Usage

To generate a new TypeID, run:

$ typeid new user
New typeid: user_1g64w3jc1ncgr2tcsh6mrjtdsn

To decode an existing TypeID into a UUID run:

$ typeid decode user_01h2xcejqtf2nbrexx3vqjhp41
Decoded typeid: {"type":"user","uuid":"0188bac7-4afa-78aa-bc3b-bd1eef28d881"}

And to encode an existing UUID into a TypeID run:

$ typeid encode user 0188bac7-4afa-78aa-bc3b-bd1eef28d881
Encoded typeid: user_01h2xcejqtf2nbrexx3vqjhp41

Library Usage

Creates a new Typeid

import { typeid, generateNew } from 'typeid-ts'

\\ You can either use:
typeid(<prefix>)
\\ or
generateNew(<prefix>)

returns e.g. user_1g64w3jc1ncgr2tcsh6mrjtdsn

Decodes a Typeid

import { decodeFromString } from 'typeid-ts'

decodeFromString(<typeid>)

returns e.g. {"type":"user","uuid":"0188bac7-4afa-78aa-bc3b-bd1eef28d881"}

Encodes a UUID with a prefix

import { encodeFromUUID } from 'typeid-ts'

encodeFromUUID(<prefix>, <UUID string>)

returns e.g. prefix_1g64w3grk1ccvjtd31csgjtdsr

Related Work

• UUIDv7 - The upcoming UUID standard that TypeIDs are based on.
• typeid-go - Ported from this library
• typeid - Original CLI client in Go

typeid-ts's Issues

Node version requirements too strict?

It looks like the node version requirements for this package are restricted to just the latest LTS:

"node": ">= 18.12 <19"

Is there some reason for this restriction, i.e. does it not work under older or newer versions of Node? Sure, folks should generally want to be on the latest-available LTS, but actually making that decision should be done by the implementer of the requesting package, unless there's reason why this package wouldn't work under any other node range requirement.

0.3.0 release does not have new import method

I think the 0.3.0 version on npm did not have build run successfully on it before being published - it's missing the new await-free import method from #7.

If you update a project's dependency to 0.3.0 of this library and install it, then cat node_modules/typeid-ts/build/cjs/src/lib/basics.js, the old const uuidv7_1 = require("uuidv7"); require method is still there.

Unable to build project using this package in TypeScript strict mode

1. Have strict=true in tsconfig
2. Build project
3. Receive error:

   ./node_modules/typeid-ts/src/lib/basics.ts:6:5
   Type error: Variable 'uuidv7' implicitly has type 'any' in some locations where its type cannot be determined.
   
     4 | import { encode } from '../base32.js'
     5 |
   > 6 | let uuidv7
       |     ^
     7 | (async () => {
     8 |   const mod = await import('uuidv7')
     9 |   uuidv7 = mod.uuidv7
   error Command failed with exit code 1.
   

On v0.3.1, seems related to #7

Very Quick Calls Generate the Same ID

Hi! Not sure if you are using Github issues for this, but I was trying out the project and found that calling generateNew("prefix") quickly generates the same ID, and I was wondering if this was intentional? I can get around it by using encodeFromUUID and generating a UUID, but it looks like I lose the locality.

// Example code
  new Array(30).fill(0).map((_, i) => {
    console.log(generateNew("knot"));
  });

Example Output:
knot_1g64w3jc9g6gs2tchncdjjtdsk
knot_1g64w3jc9g6gs2tchncdjjtdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncdk2tdsk
knot_1g64w3jc9g6gs2tchncgr2tdsq
knot_1g64w3jc9g6gs2tchncgr2tdsq
knot_1g64w3jc9g6gs2tchncgr2tdsq
knot_1g64w3jc9g6gs2tchncgr2tdsq
knot_1g64w3jc9g6gs2tchncgrjtdv3
knot_1g64w3jc9g6gs2tchncgrjtdv3
knot_1g64w3jc9g6gs2tchncgrjtdv3
knot_1g64w3jc9g6gs2tchncgrjtdv3
knot_1g64w3jc9g6gs2tchncgrjtdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3
knot_1g64w3jc9g6gs2tchncgs2tdv3