Giter VIP home page Giter VIP logo

uuidv7's Introduction

UUIDv7

UUIDv7 generator based on the RFC4122 update proposal (draft-04)

npm (scoped) npm bundle size (scoped) GitHub Workflow Status (branch) Contributor Covenant

Usage

import { uuidv7 } from "@kripod/uuidv7";

let id = uuidv7();
console.log(id); // Example: 00ccebbc-13e0-7000-8b18-6150ad2d0c05

Key features

  • K-sortable with 1ms precision (Safari disallows sub-ms timing to defend against Spectre)
  • Time-ordered when sorted lexicographically
  • Collision-resistant with distributed systems in mind
  • Works until the year 10889, after which timestamps would overflow

Compatibility

Chrome Safari Firefox IE Node.js Deno
≥57 ≥10 ≥48 No (polyfillable) ≥8 ≥1

Supporting additional runtimes

Binary structure

  • unix_ts_ms: Milliseconds elapsed since the Unix epoch – 48 bits
  • ver: UUID version (7) – 4 bits
  • rand_a: Monotonic sequence counter for more precise sorting – 12 bits
  • var: UUID variant (0b10) – 2 bits
  • rand_b: Cryptographically strong random data – 62 bits
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
┌─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┐
│                          unix_ts_ms                           │
├─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┼─┴─┴─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│          unix_ts_ms           │  ver  │        rand_a         │
├─┴─┼─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│var│                        rand_b                             │
├─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┤
│                            rand_b                             │
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

uuidv7's People

Contributors

kripod avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

uuidv7's Issues

Machine ID for Distributed Contexts

I'm not sure if the spec mentions this, but I thought given that one of the inspirations was the usage of snowflake, I thought at the very least there's a way to provide the machine/node-id.

Unless the expectation is for the user to concatenate the uuid with the machine id, but in that case I might as well use the old uuids versions, I could already do this.

Support conversion into ULID

Title says, this library is very helpful in generating sortable keys, but ULIDs are more compact and are also sortable. Can a built-in feature be added to convert the generated UUIDv7 to ULID?

Provide custom clock source for monotonicity

I'm concerned that the usage of Date is not monotonic. I've tested this myself and Date can give back the same datetime when done very closely.

Furthermore if the OS clock drifts or is set backwards, I may want my application to be monotonic even then. So having the ability to provide a custom clock where I enforce monotonicity would be useful.

Can be helpful for testing and mocking if the clocksource can be dependency injected.

Could not find a declaration file for module '@kripod/uuidv7'

With version 0.3.2 types seems broke for some reason.

My tsconfig:

{
  "exclude": ["**/node_modules"],
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig.json to read more about this file */

    /* Projects */
    // "incremental": true,                              /* Enable incremental compilation */
    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
    // "tsBuildInfoFile": "./",                          /* Specify the folder for .tsbuildinfo incremental compilation files. */
    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects */
    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */

    /* Language and Environment */
    "target": "ES2021" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
    // "lib": ["ES2022"],                                /* Specify a set of bundled library declaration files that describe the target runtime environment. */
    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h' */
    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using `jsx: react-jsx*`.` */
    // "reactNamespace": "",                             /* Specify the object invoked for `createElement`. This only applies when targeting `react` JSX emit. */
    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
    "useDefineForClassFields": true /* Emit ECMAScript-standard-compliant class fields. */,

    /* Modules */
    "module": "ES2022" /* Specify what module code is generated. For node 14+ - ES6, for browser - ES6 */,
    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
    "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
    // "typeRoots": [],                                  /* Specify multiple folders that act like `./node_modules/@types`. */
    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
    "resolveJsonModule": true /* Enable importing .json files */,
    // "noResolve": true,                                /* Disallow `import`s, `require`s or `<reference>`s from expanding the number of files TypeScript should add to a project. */

    /* JavaScript Support */
    "allowJs": true /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */,
    "checkJs": true /* Enable error reporting in type-checked JavaScript files. */,
    // "maxNodeModuleJsDepth": 0,                        /* Specify the maximum folder depth used for checking JavaScript files from `node_modules`. Only applicable with `allowJs`. */

    /* Emit */
    "declaration": true /* Generate .d.ts files from TypeScript and JavaScript files in your project. */,
    "declarationMap": true /* Create sourcemaps for d.ts files. */,
    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
    "sourceMap": true /* Create source map files for emitted JavaScript files. */,
    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If `declaration` is true, also designates a file that bundles all .d.ts output. */
    // "outDir": "./",                                   /* Specify an output folder for all emitted files. */
    "removeComments": true /* Disable emitting comments. */,
    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
    "importHelpers": true /* Allow importing helper functions from tslib (needs to be installed) once per project, instead of including them per-file. */,
    "importsNotUsedAsValues": "error" /* Specify emit/checking behavior for imports that are only used for types */,
    "preserveValueImports": true /* When combined with isolatedModules imported types must be marked as type-only */,
    "downlevelIteration": true /* Emit more compliant, but verbose and less performant JavaScript for iteration. */,
    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
    "newLine": "LF" /* Set the newline character for emitting files. */,
    // "stripInternal": true,                            /* Disable emitting declarations that have `@internal` in their JSDoc comments. */
    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like `__extends` in compiled output. */
    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
    // "preserveConstEnums": true,                       /* Disable erasing `const enum` declarations in generated code. */
    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */

    /* Interop Constraints */
    "isolatedModules": true /* Ensure that each file can be safely transpiled without relying on other imports. */,
    "allowSyntheticDefaultImports": true /* Allow 'import x from y' when a module doesn't have a default export. */,
    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */,
    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,

    /* Type Checking */
    "strict": true /* Enable all strict type-checking options. */,
    // "noImplicitAny": true,                            /* Part of strict. Enable error reporting for expressions and declarations with an implied `any` type.. */
    // "strictNullChecks": true,                         /* Part of strict. When type checking, take into account `null` and `undefined`. */
    // "strictFunctionTypes": true,                      /* Part of strict. When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
    // "strictBindCallApply": true,                      /* Part of strict. Check that the arguments for `bind`, `call`, and `apply` methods match the original function. */
    // "strictPropertyInitialization": true,             /* Part of strict. Check for class properties that are declared but not set in the constructor. */
    // "noImplicitThis": true,                           /* Part of strict. Enable error reporting when `this` is given the type `any`. */
    // "useUnknownInCatchVariables": true,               /* Part of strict. Type catch clause variables as 'unknown' instead of 'any'. */
    // "alwaysStrict": true,                             /* Part of strict. Ensure 'use strict' is always emitted. */
    "noUnusedLocals": false /* Enable error reporting when a local variables aren't read. */,
    "noUnusedParameters": false /* Raise an error when a function parameter isn't read */,
    "exactOptionalPropertyTypes": true /* Interpret optional property types as written, rather than adding 'undefined'. */,
    "noImplicitReturns": true /* Enable error reporting for codepaths that do not explicitly return in a function. */,
    "noFallthroughCasesInSwitch": true /* Enable error reporting for fallthrough cases in switch statements. */,
    "noUncheckedIndexedAccess": true /* Include 'undefined' in index signature results */,
    "noImplicitOverride": true /* Ensure overriding members in derived classes are marked with an override modifier. */,
    "noPropertyAccessFromIndexSignature": true /* Enforces using indexed accessors for keys declared using an indexed type */,
    "allowUnusedLabels": false /* Disable error reporting for unused labels. */,
    "allowUnreachableCode": false /* Disable error reporting for unreachable code. */,

    /* Completeness */
    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. Use skipLibCheck instead. */
    "skipLibCheck": true /* Skip type checking all .d.ts files. */
  }
}

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.