feat(ulid): port /x/ulid module

ulid/_util.ts

@@ -0,0 +1,111 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+
+interface ULID {
+  (seedTime?: number): string;
+}
+
+interface PRNG {
+  (): number;
+}
+
+// These values should NEVER change. If
+// they do, we're no longer making ulids!
+export const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford's Base32
+export const ENCODING_LEN = ENCODING.length;
+export const TIME_MAX = Math.pow(2, 48) - 1;
+export const TIME_LEN = 10;
+export const RANDOM_LEN = 16;
+
+function replaceCharAt(str: string, index: number, char: string) {
+  return str.substring(0, index) + char + str.substring(index + 1);
+}
+
+export function encodeTime(now: number, len: number = TIME_LEN): string {
+  if (now > TIME_MAX) {
+    throw new Error("cannot encode time greater than " + TIME_MAX);
+  }
+  if (now < 0) {
+    throw new Error("time must be positive");
+  }
+  if (Number.isInteger(now) === false) {
+    throw new Error("time must be an integer");
+  }
+  let str = "";
+  for (; len > 0; len--) {
+    const mod = now % ENCODING_LEN;
+    str = ENCODING[mod] + str;
+    now = (now - mod) / ENCODING_LEN;
+  }
+  return str;
+}
+
+export function encodeRandom(len: number): string {
+  let str = "";
+  const randomBytes = crypto.getRandomValues(new Uint8Array(len));
+  for (let i = 0; i < len; i++) {
+    str += ENCODING[randomBytes[i] % ENCODING_LEN];
+  }
+  return str;
+}
+
+export function incrementBase32(str: string): string {
+  let index = str.length;
+  let char;
+  let charIndex;
+  const maxCharIndex = ENCODING_LEN - 1;
+  while (index-- >= 0) {
+    char = str[index];
+    charIndex = ENCODING.indexOf(char);
+    if (charIndex === -1) {
+      throw new Error("incorrectly encoded string");
+    }
+    if (charIndex === maxCharIndex) {
+      str = replaceCharAt(str, index, ENCODING[0]);
+      continue;
+    }
+    return replaceCharAt(str, index, ENCODING[charIndex + 1]);
+  }
+  throw new Error("cannot increment this string");
+}
+
+/**
+ * Generates a ULID function
+ */
+export function factory(): ULID {
+  return function ulid(seedTime: number = Date.now()): string {
+    return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN);
+  };
+}
+
+/**
+ * Generates a monotonically increasing ULID, optionally given a PRNG.
+ *
+ * @example To generate monotonically increasing ULIDs, create a monotonic counter.
+ * ```ts
+ * import { monotonicFactory } from "https://deno.land/std@$STD_VERSION/ulid/_util.ts";
+ *
+ * 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
+ * ```
+ */
+export function monotonicFactory(encodeRand = encodeRandom): ULID {
+  let lastTime = 0;
+  let lastRandom: string;
+  return function ulid(seedTime: number = Date.now()): string {
+    if (seedTime <= lastTime) {
+      const incrementedRandom = (lastRandom = incrementBase32(lastRandom));
+      return encodeTime(lastTime, TIME_LEN) + incrementedRandom;
+    }
+    lastTime = seedTime;
+    const newRandom = (lastRandom = encodeRand(RANDOM_LEN));
+    return encodeTime(seedTime, TIME_LEN) + newRandom;
+  };
+}

ulid/mod.ts

@@ -0,0 +1,77 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+// This module is browser compatible.
+
+/**
+ * @module
+ * @example
+ * ```ts
+ * import { ulid } from "https://deno.land/std@$STD_VERSION/ulid/mod.ts";
+ * ulid(); // 01ARZ3NDEKTSV4RRFFQ69G5FAV
+ * ```
+ */
+
+import {
+  ENCODING,
+  ENCODING_LEN,
+  factory,
+  monotonicFactory,
+  RANDOM_LEN,
+  TIME_LEN,
+  TIME_MAX,
+} from "./_util.ts";
+
+/**
+ * Extracts the timestamp given a ULID
+ */
+export function decodeTime(id: string): number {
+  if (id.length !== TIME_LEN + RANDOM_LEN) {
+    throw new Error("malformed ulid");
+  }
+  const time = id
+    .substring(0, TIME_LEN)
+    .split("")
+    .reverse()
+    .reduce((carry, char, index) => {
+      const encodingIndex = ENCODING.indexOf(char);
+      if (encodingIndex === -1) {
+        throw new Error("invalid character found: " + char);
+      }
+      return (carry += encodingIndex * Math.pow(ENCODING_LEN, index));
+    }, 0);
+  if (time > TIME_MAX) {
+    throw new Error("malformed ulid, timestamp too large");
+  }
+  return time;
+}
+
+/**
+ * @example
+ * ```ts
+ * import { monotonicUlid } from "https://deno.land/std@$STD_VERSION/ulid/mod.ts";
+ *
+ * // Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
+ * monotonicUlid(150000); // 000XAL6S41ACTAV9WEVGEMMVR8
+ * monotonicUlid(150000); // 000XAL6S41ACTAV9WEVGEMMVR9
+ * monotonicUlid(150000); // 000XAL6S41ACTAV9WEVGEMMVRA
+ * monotonicUlid(150000); // 000XAL6S41ACTAV9WEVGEMMVRB
+ * monotonicUlid(150000); // 000XAL6S41ACTAV9WEVGEMMVRC
+ *
+ * // Even if a lower timestamp is passed (or generated), it will preserve sort order
+ * monotonicUlid(100000); // 000XAL6S41ACTAV9WEVGEMMVRD
+ * ```
+ */
+export const monotonicUlid = monotonicFactory();
+
+/**
+ * @example
+ * ```ts
+ * import { ulid } from "https://deno.land/std@$STD_VERSION/ulid/mod.ts";
+ * ulid(); // 01ARZ3NDEKTSV4RRFFQ69G5FAV
+ *
+ * // You can also input a seed time which will consistently give you the same string for the time component
+ * ulid(1469918176385); // 01ARYZ6S41TSV4RRFFQ69G5FAV
+ * ```
+ */
+export const ulid = factory();

ulid/test.ts

@@ -0,0 +1,209 @@
+// Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
+// Copyright 2023 Yoshiya Hinosawa. All rights reserved. MIT license.
+// Copyright 2017 Alizain Feerasta. All rights reserved. MIT license.
+
+import { FakeTime } from "../testing/time.ts";
+import {
+  assertEquals,
+  assertStrictEquals,
+  assertThrows,
+} from "../assert/mod.ts";
+
+import { decodeTime } from "./mod.ts";
+import {
+  encodeRandom,
+  encodeTime,
+  ENCODING,
+  ENCODING_LEN,
+  factory,
+  incrementBase32,
+  monotonicFactory,
+} from "./_util.ts";
+
+const ulid = factory();
+
+Deno.test("increment base32", async (t) => {
+  await t.step("increments correctly", () => {
+    assertEquals("A109D", incrementBase32("A109C"));
+  });
+
+  await t.step("carries correctly", () => {
+    assertEquals("A1Z00", incrementBase32("A1YZZ"));
+  });
+
+  await t.step("double increments correctly", () => {
+    assertEquals(
+      "A1Z01",
+      incrementBase32(incrementBase32("A1YZZ")),
+    );
+  });
+
+  await t.step("throws when it cannot increment", () => {
+    assertThrows(() => {
+      incrementBase32("ZZZ");
+    });
+  });
+});
+
+Deno.test("encodeTime", async (t) => {
+  await t.step("should return expected encoded result", () => {
+    assertEquals("01ARYZ6S41", encodeTime(1469918176385, 10));
+  });
+
+  await t.step("should change length properly", () => {
+    assertEquals("0001AS99AA60", encodeTime(1470264322240, 12));
+  });
+
+  await t.step("should truncate time if not enough length", () => {
+    assertEquals("AS4Y1E11", encodeTime(1470118279201, 8));
+  });
+
+  await t.step("should throw an error", async (t) => {
+    await t.step("if time greater than (2 ^ 48) - 1", () => {
+      assertThrows(() => {
+        encodeTime(Math.pow(2, 48), 8);
+      }, Error);
+    });
+
+    await t.step("if time is not a number", () => {
+      assertThrows(() => {
+        // deno-lint-ignore no-explicit-any
+        encodeTime("test" as any, 3);
+      }, Error);
+    });
+
+    await t.step("if time is infinity", () => {
+      assertThrows(() => {
+        encodeTime(Infinity);
+      }, Error);
+    });
+
+    await t.step("if time is negative", () => {
+      assertThrows(() => {
+        encodeTime(-1);
+      }, Error);
+    });
+
+    await t.step("if time is a float", () => {
+      assertThrows(() => {
+        encodeTime(100.1);
+      }, Error);
+    });
+  });
+});
+
+Deno.test("encodeRandom", async (t) => {
+  await t.step("should return correct length", () => {
+    assertEquals(12, encodeRandom(12).length);
+  });
+});
+
+Deno.test("decodeTime", async (t) => {
+  await t.step("should return correct timestamp", () => {
+    const timestamp = Date.now();
+    const id = ulid(timestamp);
+    assertEquals(timestamp, decodeTime(id));
+  });
+
+  await t.step("should accept the maximum allowed timestamp", () => {
+    assertEquals(
+      281474976710655,
+      decodeTime("7ZZZZZZZZZZZZZZZZZZZZZZZZZ"),
+    );
+  });
+
+  await t.step("should reject", async (t) => {
+    await t.step("malformed strings of incorrect length", () => {
+      assertThrows(() => {
+        decodeTime("FFFF");
+      }, Error);
+    });
+
+    await t.step("strings with timestamps that are too high", () => {
+      assertThrows(() => {
+        decodeTime("80000000000000000000000000");
+      }, Error);
+    });
+
+    await t.step("invalid character", () => {
+      assertThrows(() => {
+        decodeTime("&1ARZ3NDEKTSV4RRFFQ69G5FAV");
+      }, Error);
+    });
+  });
+});
+
+Deno.test("ulid", async (t) => {
+  await t.step("should return correct length", () => {
+    assertEquals(26, ulid().length);
+  });
+
+  await t.step(
+    "should return expected encoded time component result",
+    () => {
+      assertEquals("01ARYZ6S41", ulid(1469918176385).substring(0, 10));
+    },
+  );
+});
+
+Deno.test("monotonicity", async (t) => {
+  function encodeRandom(len: number): string {
+    let str = "";
+    const randomBytes = new Array(len).fill(30);
+    for (let i = 0; i < len; i++) {
+      str += ENCODING[randomBytes[i] % ENCODING_LEN];
+    }
+    return str;
+  }
+
+  await t.step("without seedTime", async (t) => {
+    const stubbedUlid = monotonicFactory(encodeRandom);
+
+    const time = new FakeTime(1469918176385);
+
+    await t.step("first call", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYYY", stubbedUlid());
+    });
+
+    await t.step("second call", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYYZ", stubbedUlid());
+    });
+
+    await t.step("third call", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYZ0", stubbedUlid());
+    });
+
+    await t.step("fourth call", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYZ1", stubbedUlid());
+    });
+
+    time.restore();
+  });
+
+  await t.step("with seedTime", async (t) => {
+    const stubbedUlid = monotonicFactory(encodeRandom);
+
+    await t.step("first call", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYYY", stubbedUlid(1469918176385));
+    });
+
+    await t.step("second call with the same", () => {
+      assertStrictEquals(
+        "01ARYZ6S41YYYYYYYYYYYYYYYZ",
+        stubbedUlid(1469918176385),
+      );
+    });
+
+    await t.step("third call with less than", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYZ0", stubbedUlid(100000000));
+    });
+
+    await t.step("fourth call with even more less than", () => {
+      assertEquals("01ARYZ6S41YYYYYYYYYYYYYYZ1", stubbedUlid(10000));
+    });
+
+    await t.step("fifth call with 1 greater than", () => {
+      assertEquals("01ARYZ6S42YYYYYYYYYYYYYYYY", stubbedUlid(1469918176386));
+    });
+  });
+});