feat(string): adds support for generating ULID (#2524)

4 files changed, 77 insertions, 18 deletions

diff --git a/src/internal/base32.ts b/src/internal/base32.ts
new file mode 100644
index 00000000..f3e15bb4
--- /dev/null
+++ b/src/internal/base32.ts
@@ -0,0 +1,21 @@
+/**
+ * Crockford's Base32 - Excludes I, L, O, and U which may be confused with numbers
+ */
+export const CROCKFORDS_BASE32 = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+/**
+ * Encodes a Date into 10 characters base32 string.
+ *
+ * @param date The Date to encode.
+ */
+export function dateToBase32(date: Date): string {
+  let value = date.valueOf();
+  let result = '';
+  for (let len = 10; len > 0; len--) {
+    const mod = value % 32;
+    result = CROCKFORDS_BASE32[mod] + result;
+    value = (value - mod) / 32;
+  }
+
+  return result;
+}
diff --git a/src/internal/date.ts b/src/internal/date.ts
new file mode 100644
index 00000000..40751c2d
--- /dev/null
+++ b/src/internal/date.ts
@@ -0,0 +1,22 @@
+import { FakerError } from '../errors/faker-error';
+
+/**
+ * Converts a date passed as a `string`, `number` or `Date` to a valid `Date` object.
+ *
+ * @param date The date to convert.
+ * @param name The reference name used for error messages. Defaults to `'refDate'`.
+ *
+ * @throws If the given date is invalid.
+ */
+export function toDate(
+  date: string | Date | number,
+  name: string = 'refDate'
+): Date {
+  const converted = new Date(date);
+
+  if (Number.isNaN(converted.valueOf())) {
+    throw new FakerError(`Invalid ${name} date: ${date.toString()}`);
+  }
+
+  return converted;
+}
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 53204a03..06890a5d 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -1,28 +1,11 @@
 import type { Faker } from '../..';
 import type { DateEntryDefinition } from '../../definitions';
 import { FakerError } from '../../errors/faker-error';
+import { toDate } from '../../internal/date';
 import { assertLocaleData } from '../../internal/locale-proxy';
 import { SimpleModuleBase } from '../../internal/module-base';
 
 /**
- * Converts a date passed as a `string`, `number` or `Date` to a valid `Date` object.
- *
- * @param date The date to convert.
- * @param name The reference name used for error messages. Defaults to `'refDate'`.
- *
- * @throws If the given date is invalid.
- */
-function toDate(date: string | Date | number, name: string = 'refDate'): Date {
-  const converted = new Date(date);
-
-  if (Number.isNaN(converted.valueOf())) {
-    throw new FakerError(`Invalid ${name} date: ${date.toString()}`);
-  }
-
-  return converted;
-}
-
-/**
  * Module to generate dates (without methods requiring localized data).
  */
 export class SimpleDateModule extends SimpleModuleBase {
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index 7df31fc7..67073242 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -1,4 +1,6 @@
 import { FakerError } from '../../errors/faker-error';
+import { CROCKFORDS_BASE32, dateToBase32 } from '../../internal/base32';
+import { toDate } from '../../internal/date';
 import { SimpleModuleBase } from '../../internal/module-base';
 import type { LiteralUnion } from '../../internal/types';
 
@@ -705,6 +707,37 @@ export class StringModule extends SimpleModuleBase {
   }
 
   /**
+   * Returns a ULID ([Universally Unique Lexicographically Sortable Identifier](https://github.com/ulid/spec)).
+   *
+   * @param options The optional options object.
+   * @param options.refDate The timestamp to encode into the ULID.
+   * The encoded timestamp is represented by the first 10 characters of the result.
+   * Defaults to `faker.defaultRefDate()`.
+   *
+   * @example
+   * faker.string.ulid() // '01ARZ3NDEKTSV4RRFFQ69G5FAV'
+   * faker.string.ulid({ refDate: '2020-01-01T00:00:00.000Z' }) // '01DXF6DT00CX9QNNW7PNXQ3YR8'
+   *
+   * @since 9.1.0
+   */
+  ulid(
+    options: {
+      /**
+       * The date to use as reference point for the newly generated ULID encoded timestamp.
+       * The encoded timestamp is represented by the first 10 characters of the result.
+       *
+       * @default faker.defaultRefDate()
+       */
+      refDate?: string | Date | number;
+    } = {}
+  ): string {
+    const { refDate = this.faker.defaultRefDate() } = options;
+    const date = toDate(refDate);
+
+    return dateToBase32(date) + this.fromCharacters(CROCKFORDS_BASE32, 16);
+  }
+
+  /**
    * Generates a [Nano ID](https://github.com/ai/nanoid).
    *
    * @param length Length of the generated string. Defaults to `21`.