/locally-unique-id-generator-esm

ESM based Trivial generator for ids which are unique within an application for SSR web applications

Primary LanguageTypeScriptMIT LicenseMIT

locally-unique-id-generator-esm

Special credits to Andreas Rozek on whose repo this library is based

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Installation

locally-unique-id-generator-esm may be used as an ECMAScript module (ESM), a CommonJS or AMD module or from a global variable.

You may either install the package into your build environment using NPM with the command

npm install locally-unique-id-generator-esm

or load the plain script file directly

<script src="https://unpkg.com/locally-unique-id-generator-esm"></script>

Access

How to access the package depends on the type of module you prefer

  • ESM (or Svelte): import newUniqueId from 'locally-unique-id-generator-esm'
  • CommonJS: const newUniqueId = require('locally-unique-id-generator-esm')
  • AMD: require(['locally-unique-id-generator-esm'], (newUniqueId) => {...})

Alternatively, you may access the global variable newUniqueId directly.

Usage within Svelte

For Svelte it is recommended to import the package within a module context:

<script context="module">
  import newUniqueId from 'locally-unique-id-generator-esm'
</script>

<script>
  console.log('next unique id:',newUniqueId())
</script>

Usage as ECMAscript, CommonJS or AMD Module (or as a global Variable)

Let's assume that you already "required" or "imported" (or simply loaded) the module according to your local environment. In that case, you may use it as follows:

console.log('next unique id:',newUniqueId())

Background Information

From time to time, it may be necessary to generate unique ids (e.g., for the ids of data lists in a web page). This module provides a trivial solution for this problem by using a counter to generate ids of the form uid-<counter>. Within the same application, such keys are guaranteed to be unique (unless more than 2^53 of them are created while that application is running) - but only while the application is running: as soon as the application is restarted, the counter starts from 0 again.

If you need universally unique ids, you should better generate UUIDs/GUIDs of type 4 (see below)

JavaScript API

This package offers a JavaScript default export, which may be imported (or required) as shown in the "Access" section above.

With such an import, the JavaScript API can be used as follows:

  • newUniqueId() - returns a new, unique literal id of the form uid-<counter> with "counter" starting at 1

Example

An example is available on the Svelte REPL - feel free to play with it!

Alternative for Universally Unique Ids

UUIDs/GUIDs of type 4 may be easily created using the following code:

   function newUUID ():string {
    let Id = '', IdPart
    IdPart = Math.round(Math.random()*0xffffffff).toString(16)
      Id += IdPart + '00000000'.slice(IdPart.length) + '-'
      IdPart = Math.round(Math.random()*0xffff).toString(16)
      Id += IdPart + '0000'.slice(IdPart.length) + '-4'
      IdPart = Math.round(Math.random()*0xfff).toString(16)
      Id += IdPart + '000'.slice(IdPart.length) + '-'
      IdPart = Math.round(Math.random()*0x3fff+0x8000).toString(16)
      Id += IdPart + '-'
      IdPart = Math.round(Math.random()*0xffffffffffff).toString(16)
      Id += IdPart + '000000000000'.slice(IdPart.length)
    return Id.toLowerCase()
  }

provided that cryptographic uniqueness is not required.

License

MIT License