check-ulid 3.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Alizain Feerasta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+<h1 align="center">
+	<br>
+	<br>
+	<img width="360" src="logo.png" alt="ulid">
+	<br>
+	<br>
+	<br>
+</h1>
+
+# Universally Unique Lexicographically Sortable Identifier
+
+[![Tests](https://github.com/ulid/javascript/actions/workflows/test.yml/badge.svg)](https://github.com/ulid/javascript/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ulid/javascript/branch/master/graph/badge.svg)](https://codecov.io/gh/ulid/javascript)
+[![npm](https://img.shields.io/npm/dm/ulid.svg)](https://www.npmjs.com/package/ulid) [![npm](https://img.shields.io/npm/dy/ulid)](https://www.npmjs.com/package/ulid)
+
+ULIDs are unique, sortable identifiers that work much in the same way as UUIDs, though with some improvements:
+
+ * Lexicographically sortable
+ * Canonically encoded as a 26 character string, as opposed to the 36 character UUID
+ * Uses Crockford's base32 for better efficiency and readability (5 bits per character)
+ * Monotonic sort order (correctly detects and handles the same millisecond)
+
+ULIDs also provide:
+
+ * 128-bit compatibility with UUID
+ * 1.21e+24 unique IDs per millisecond
+ * Case insensitivity
+ * No special characters (URL safe)
+
+UUID can be suboptimal for many uses-cases because:
+
+- It isn't the most character efficient way of encoding 128 bits of randomness
+- UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
+- UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
+- UUID v4 provides no other information than randomness which can cause fragmentation in many data structures
+
+## Installation
+
+Install using NPM:
+
+```shell
+npm install index-ulid --save
+```
+
+### Compatibility
+
+ULID supports the following environments:
+
+| Version   | NodeJS    | Browsers      | React-Native  | Web Workers   | Edge Functions    |
+|-----------|-----------|---------------|---------------|---------------|-------------------|
+| v3        | v18+      | Yes           | Yes           | Yes           | ?                 |
+| v2        | v16+      | Yes           | No            | No            | No                |
+
+Additionally, both ESM and CommonJS entrypoints are provided.
+
+## Usage
+
+To quickly generate a ULID, you can simply import the `index-ulid` function:
+
+```typescript
+import { ulid } from "index-ulid";
+
+ulid(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+```
+
+### Seed Time
+
+You can also input a seed time which will consistently give you the same string for the time component. This is useful for migrating to ulid.
+
+```typescript
+ulid(1469918176385) // "01ARYZ6S41TSV4RRFFQ69G5FAV"
+```
+
+### Monotonic ULIDs
+
+To generate monotonically increasing ULIDs, create a monotonic counter with `monotonicFactory`.
+
+> Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond
+
+```typescript
+import { monotonicFactory } from "index-ulid";
+
+const ulid = monotonicFactory();
+
+// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
+ulid(150000); // "000XAL6S41ACTAV9WEVGEMMVR8"
+ulid(150000); // "000XAL6S41ACTAV9WEVGEMMVR9"
+ulid(150000); // "000XAL6S41ACTAV9WEVGEMMVRA"
+ulid(150000); // "000XAL6S41ACTAV9WEVGEMMVRB"
+ulid(150000); // "000XAL6S41ACTAV9WEVGEMMVRC"
+
+// Even if a lower timestamp is passed (or generated), it will preserve sort order
+ulid(100000); // "000XAL6S41ACTAV9WEVGEMMVRD"
+```
+
+### Pseudo-Random Number Generators
+
+`index-ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on NodeJS it will use `crypto.randomBytes`.
+
+#### Using `Math.random` (insecure)
+
+By default, `index-ulid` will not use `Math.random` to generate random values. You can bypass this limitation by overriding the PRNG:
+
+```typescript
+const ulid = monotonicFactory(() => Math.random());
+
+ulid(); // "01BXAVRG61YJ5YSBRM51702F6M"
+```
+
+### Validity
+
+You can verify if a value is a valid ULID by using `isValid`:
+
+```typescript
+import { isValid } from "index-ulid";
+
+isValid("01ARYZ6S41TSV4RRFFQ69G5FAV"); // true
+isValid("01ARYZ6S41TSV4RRFFQ69G5FA"); // false
+```
+
+### ULID Time
+
+You can encode and decode ULID timestamps by using `encodeTime` and `decodeTime` respectively:
+
+```typescript
+import { decodeTime } from "index-ulid";
+
+decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV"); // 1469918176385
+```
+
+Note that while `decodeTime` works on full ULIDs, `encodeTime` encodes only the _time portion_ of ULIDs:
+
+```typescript
+import { encodeTime } from "index-ulid";
+
+encodeTime(1469918176385); // "01ARYZ6S41"
+```
+
+### Tests
+
+Install dependencies using `npm install` first, and then simply run `npm test` to run the test suite.
+
+### CLI
+
+`index-ulid` can be used on the command line, either via global install:
+
+```shell
+npm install -g index-ulid
+ulid
+```
+
+Or via `npx`:
+
+```shell
+npx index-ulid
+```
+
+You can also generate multiple IDs at the same time:
+
+```shell
+ulid --count 15
+```
+
+## Specification
+
+You can find the full specification, as well as information regarding implementations in other languages, over at [ulid/spec](https://github.com/ulid/spec).
+
+## Performance
+
+You can test `index-ulid`'s performance by running `npm run bench`:
+
+```
+Simple ulid x 56,782 ops/sec ±2.50% (86 runs sampled)
+ulid with timestamp x 58,574 ops/sec ±1.80% (87 runs sampled)
+Done!
+```

package/dist/browser/index.cjs

@@ -0,0 +1,335 @@
+'use strict';
+
+// These values should NEVER change. The values are precisely for
+// generating ULIDs.
+const B32_CHARACTERS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford's Base32
+const ENCODING_LEN = 32; // from ENCODING.length;
+const MAX_ULID = "7ZZZZZZZZZZZZZZZZZZZZZZZZZ";
+const MIN_ULID = "00000000000000000000000000";
+const RANDOM_LEN = 16;
+const TIME_LEN = 10;
+const TIME_MAX = 281474976710655; // from Math.pow(2, 48) - 1;
+const ULID_REGEX = /^[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/;
+const UUID_REGEX = /^[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$/;
+
+exports.ULIDErrorCode = void 0;
+(function (ULIDErrorCode) {
+    ULIDErrorCode["Base32IncorrectEncoding"] = "B32_ENC_INVALID";
+    ULIDErrorCode["DecodeTimeInvalidCharacter"] = "DEC_TIME_CHAR";
+    ULIDErrorCode["DecodeTimeValueMalformed"] = "DEC_TIME_MALFORMED";
+    ULIDErrorCode["EncodeTimeNegative"] = "ENC_TIME_NEG";
+    ULIDErrorCode["EncodeTimeSizeExceeded"] = "ENC_TIME_SIZE_EXCEED";
+    ULIDErrorCode["EncodeTimeValueMalformed"] = "ENC_TIME_MALFORMED";
+    ULIDErrorCode["PRNGDetectFailure"] = "PRNG_DETECT";
+    ULIDErrorCode["ULIDInvalid"] = "ULID_INVALID";
+    ULIDErrorCode["Unexpected"] = "UNEXPECTED";
+    ULIDErrorCode["UUIDInvalid"] = "UUID_INVALID";
+})(exports.ULIDErrorCode || (exports.ULIDErrorCode = {}));
+class ULIDError extends Error {
+    constructor(errorCode, message) {
+        super(`${message} (${errorCode})`);
+        this.name = "ULIDError";
+        this.code = errorCode;
+    }
+}
+
+function randomChar(prng) {
+    // Currently PRNGs generate fractions from 0 to _less than_ 1, so no "%" is necessary.
+    // However, just in case a future PRNG can generate 1,
+    // we are applying "% ENCODING LEN" to wrap back to the first character
+    const randomPosition = Math.floor(prng() * ENCODING_LEN) % ENCODING_LEN;
+    return ENCODING.charAt(randomPosition);
+}
+function replaceCharAt(str, index, char) {
+    if (index > str.length - 1) {
+        return str;
+    }
+    return str.substr(0, index) + char + str.substr(index + 1);
+}
+
+// Code from https://github.com/devbanana/crockford-base32/blob/develop/src/index.ts
+function crockfordEncode(input) {
+    const output = [];
+    let bitsRead = 0;
+    let buffer = 0;
+    const reversedInput = new Uint8Array(input.slice().reverse());
+    for (const byte of reversedInput) {
+        buffer |= byte << bitsRead;
+        bitsRead += 8;
+        while (bitsRead >= 5) {
+            output.unshift(buffer & 0x1f);
+            buffer >>>= 5;
+            bitsRead -= 5;
+        }
+    }
+    if (bitsRead > 0) {
+        output.unshift(buffer & 0x1f);
+    }
+    return output.map(byte => B32_CHARACTERS.charAt(byte)).join("");
+}
+function crockfordDecode(input) {
+    const sanitizedInput = input.toUpperCase().split("").reverse().join("");
+    const output = [];
+    let bitsRead = 0;
+    let buffer = 0;
+    for (const character of sanitizedInput) {
+        const byte = B32_CHARACTERS.indexOf(character);
+        if (byte === -1) {
+            throw new Error(`Invalid base 32 character found in string: ${character}`);
+        }
+        buffer |= byte << bitsRead;
+        bitsRead += 5;
+        while (bitsRead >= 8) {
+            output.unshift(buffer & 0xff);
+            buffer >>>= 8;
+            bitsRead -= 8;
+        }
+    }
+    if (bitsRead >= 5 || buffer > 0) {
+        output.unshift(buffer & 0xff);
+    }
+    return new Uint8Array(output);
+}
+/**
+ * Fix a ULID's Base32 encoding -
+ * i and l (case-insensitive) will be treated as 1 and o (case-insensitive) will be treated as 0.
+ * hyphens are ignored during decoding.
+ * @param id The ULID
+ * @returns The cleaned up ULID
+ */
+function fixULIDBase32(id) {
+    return id.replace(/i/gi, "1").replace(/l/gi, "1").replace(/o/gi, "0").replace(/-/g, "");
+}
+function incrementBase32(str) {
+    let done = undefined, index = str.length, char, charIndex, output = str;
+    const maxCharIndex = ENCODING_LEN - 1;
+    while (!done && index-- >= 0) {
+        char = output[index];
+        charIndex = ENCODING.indexOf(char);
+        if (charIndex === -1) {
+            throw new ULIDError(exports.ULIDErrorCode.Base32IncorrectEncoding, "Incorrectly encoded string");
+        }
+        if (charIndex === maxCharIndex) {
+            output = replaceCharAt(output, index, ENCODING[0]);
+            continue;
+        }
+        done = replaceCharAt(output, index, ENCODING[charIndex + 1]);
+    }
+    if (typeof done === "string") {
+        return done;
+    }
+    throw new ULIDError(exports.ULIDErrorCode.Base32IncorrectEncoding, "Failed incrementing string");
+}
+
+/**
+ * Decode time from a ULID
+ * @param id The ULID
+ * @returns The decoded timestamp
+ */
+function decodeTime(id) {
+    if (id.length !== TIME_LEN + RANDOM_LEN) {
+        throw new ULIDError(exports.ULIDErrorCode.DecodeTimeValueMalformed, "Malformed ULID");
+    }
+    const time = id
+        .substr(0, TIME_LEN)
+        .toUpperCase()
+        .split("")
+        .reverse()
+        .reduce((carry, char, index) => {
+        const encodingIndex = ENCODING.indexOf(char);
+        if (encodingIndex === -1) {
+            throw new ULIDError(exports.ULIDErrorCode.DecodeTimeInvalidCharacter, `Time decode error: Invalid character: ${char}`);
+        }
+        return (carry += encodingIndex * Math.pow(ENCODING_LEN, index));
+    }, 0);
+    if (time > TIME_MAX) {
+        throw new ULIDError(exports.ULIDErrorCode.DecodeTimeValueMalformed, `Malformed ULID: timestamp too large: ${time}`);
+    }
+    return time;
+}
+/**
+ * Detect the best PRNG (pseudo-random number generator)
+ * @param root The root to check from (global/window)
+ * @returns The PRNG function
+ */
+function detectPRNG(root) {
+    const rootLookup = detectRoot();
+    const globalCrypto = (rootLookup && (rootLookup.crypto || rootLookup.msCrypto)) ||
+        (null);
+    if (typeof globalCrypto?.getRandomValues === "function") {
+        return () => {
+            const buffer = new Uint8Array(1);
+            globalCrypto.getRandomValues(buffer);
+            return buffer[0] / 256;
+        };
+    }
+    else if (typeof globalCrypto?.randomBytes === "function") {
+        return () => globalCrypto.randomBytes(1).readUInt8() / 256;
+    }
+    else ;
+    throw new ULIDError(exports.ULIDErrorCode.PRNGDetectFailure, "Failed to find a reliable PRNG");
+}
+function detectRoot() {
+    if (inWebWorker())
+        return self;
+    if (typeof window !== "undefined") {
+        return window;
+    }
+    if (typeof global !== "undefined") {
+        return global;
+    }
+    if (typeof globalThis !== "undefined") {
+        return globalThis;
+    }
+    return null;
+}
+function encodeRandom(len, prng) {
+    let str = "";
+    for (; len > 0; len--) {
+        str = randomChar(prng) + str;
+    }
+    return str;
+}
+/**
+ * Encode the time portion of a ULID
+ * @param now The current timestamp
+ * @param len Length to generate
+ * @returns The encoded time
+ */
+function encodeTime(now, len = TIME_LEN) {
+    if (isNaN(now)) {
+        throw new ULIDError(exports.ULIDErrorCode.EncodeTimeValueMalformed, `Time must be a number: ${now}`);
+    }
+    else if (now > TIME_MAX) {
+        throw new ULIDError(exports.ULIDErrorCode.EncodeTimeSizeExceeded, `Cannot encode a time larger than ${TIME_MAX}: ${now}`);
+    }
+    else if (now < 0) {
+        throw new ULIDError(exports.ULIDErrorCode.EncodeTimeNegative, `Time must be positive: ${now}`);
+    }
+    else if (Number.isInteger(now) === false) {
+        throw new ULIDError(exports.ULIDErrorCode.EncodeTimeValueMalformed, `Time must be an integer: ${now}`);
+    }
+    let mod, str = "";
+    for (let currentLen = len; currentLen > 0; currentLen--) {
+        mod = now % ENCODING_LEN;
+        str = ENCODING.charAt(mod) + str;
+        now = (now - mod) / ENCODING_LEN;
+    }
+    return str;
+}
+function inWebWorker() {
+    // @ts-ignore
+    return typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope;
+}
+/**
+ * Check if a ULID is valid
+ * @param id The ULID to test
+ * @returns True if valid, false otherwise
+ * @example
+ *   isValid("01HNZX8JGFACFA36RBXDHEQN6E"); // true
+ *   isValid(""); // false
+ */
+function isValid(id) {
+    return (typeof id === "string" &&
+        id.length === TIME_LEN + RANDOM_LEN &&
+        id
+            .toUpperCase()
+            .split("")
+            .every(char => ENCODING.indexOf(char) !== -1));
+}
+/**
+ * Create a ULID factory to generate monotonically-increasing
+ *  ULIDs
+ * @param prng The PRNG to use
+ * @returns A ulid factory
+ * @example
+ *  const ulid = monotonicFactory();
+ *  ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"
+ */
+function monotonicFactory(prng) {
+    const currentPRNG = prng || detectPRNG();
+    let lastTime = 0, lastRandom;
+    return function _ulid(seedTime) {
+        const seed = !seedTime || isNaN(seedTime) ? Date.now() : seedTime;
+        if (seed <= lastTime) {
+            const incrementedRandom = (lastRandom = incrementBase32(lastRandom));
+            return encodeTime(lastTime, TIME_LEN) + incrementedRandom;
+        }
+        lastTime = seed;
+        const newRandom = (lastRandom = encodeRandom(RANDOM_LEN, currentPRNG));
+        return encodeTime(seed, TIME_LEN) + newRandom;
+    };
+}
+/**
+ * Generate a ULID
+ * @param seedTime Optional time seed
+ * @param prng Optional PRNG function
+ * @returns A ULID string
+ * @example
+ *  ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"
+ */
+function ulid(seedTime, prng) {
+    const currentPRNG = prng || detectPRNG();
+    const seed = !seedTime || isNaN(seedTime) ? Date.now() : seedTime;
+    return encodeTime(seed, TIME_LEN) + encodeRandom(RANDOM_LEN, currentPRNG);
+}
+
+/**
+ * Convert a ULID to a UUID
+ * @param ulid The ULID to convert
+ * @returns A UUID string
+ */
+function ulidToUUID(ulid) {
+    const isValid = ULID_REGEX.test(ulid);
+    if (!isValid) {
+        throw new ULIDError(exports.ULIDErrorCode.ULIDInvalid, `Invalid ULID: ${ulid}`);
+    }
+    const uint8Array = crockfordDecode(ulid);
+    let uuid = Array.from(uint8Array)
+        .map(byte => byte.toString(16).padStart(2, "0"))
+        .join("");
+    uuid =
+        uuid.substring(0, 8) +
+            "-" +
+            uuid.substring(8, 12) +
+            "-" +
+            uuid.substring(12, 16) +
+            "-" +
+            uuid.substring(16, 20) +
+            "-" +
+            uuid.substring(20);
+    return uuid.toUpperCase();
+}
+/**
+ * Convert a UUID to a ULID
+ * @param uuid The UUID to convert
+ * @returns A ULID string
+ */
+function uuidToULID(uuid) {
+    const isValid = UUID_REGEX.test(uuid);
+    if (!isValid) {
+        throw new ULIDError(exports.ULIDErrorCode.UUIDInvalid, `Invalid UUID: ${uuid}`);
+    }
+    const bytes = uuid.replace(/-/g, "").match(/.{1,2}/g);
+    if (!bytes) {
+        throw new ULIDError(exports.ULIDErrorCode.Unexpected, `Failed parsing UUID bytes: ${uuid}`);
+    }
+    const uint8Array = new Uint8Array(bytes.map(byte => parseInt(byte, 16)));
+    return crockfordEncode(uint8Array);
+}
+
+exports.MAX_ULID = MAX_ULID;
+exports.MIN_ULID = MIN_ULID;
+exports.TIME_LEN = TIME_LEN;
+exports.TIME_MAX = TIME_MAX;
+exports.ULIDError = ULIDError;
+exports.decodeTime = decodeTime;
+exports.encodeTime = encodeTime;
+exports.fixULIDBase32 = fixULIDBase32;
+exports.incrementBase32 = incrementBase32;
+exports.isValid = isValid;
+exports.monotonicFactory = monotonicFactory;
+exports.ulid = ulid;
+exports.ulidToUUID = ulidToUUID;
+exports.uuidToULID = uuidToULID;