docs(ulid): finish documentation

.github/CONTRIBUTING.md

@@ -88,12 +88,8 @@ See the source code within
 examples.
 
 Once the documentation for a given package is written, add the package's entry
-point(s) (usually just `mod.ts`) to:
-
-1. The `ENTRY_POINTS` array in the
-   [documentation checker tool](../_tools/check_docs.ts).
-1. The `lint:docs` task in the
-   [`deno.json` file](https://github.com/denoland/deno_std/blob/main/deno.json).
+point(s) (usually just `mod.ts`) to the `ENTRY_POINTS` array in the
+[documentation checker tool](../_tools/check_docs.ts).
 
 Once done, run `deno task lint:docs` which checks that documentation is complete
 in the given entry points.

.github/typos.toml

@@ -15,5 +15,6 @@ extend-exclude = [
   "*.generated.mjs",
   "media_types/vendor",
   "http/testdata",
-  "http/user_agent.ts"
+  "http/user_agent.ts",
+  "ulid/mod.ts"
 ]

_tools/check_docs.ts

@@ -26,13 +26,14 @@ type DocNodeWithJsDoc<T = DocNodeBase> = T & {
 };
 
 const ENTRY_POINTS = [
-  "../bytes/mod.ts",
   "../async/mod.ts",
-  "../datetime/mod.ts",
+  "../bytes/mod.ts",
   "../collections/mod.ts",
-  "../jsonc/mod.ts",
+  "../datetime/mod.ts",
   "../internal/mod.ts",
+  "../jsonc/mod.ts",
   "../media_types/mod.ts",
+  "../ulid/mod.ts",
   "../webgpu/mod.ts",
 ] as const;
 
@@ -313,10 +314,28 @@ async function checkDocs(specifier: string) {
   }
 }
 
+const ENTRY_POINT_URLS = ENTRY_POINTS.map((entry) =>
+  new URL(entry, import.meta.url).href
+);
+
+const lintStatus = await new Deno.Command(Deno.execPath(), {
+  args: ["doc", "--lint", ...ENTRY_POINT_URLS],
+  stdin: "inherit",
+  stdout: "inherit",
+  stderr: "inherit",
+}).output();
+if (!lintStatus.success) {
+  console.error(
+    `%c[error] %c'deno doc --lint' failed`,
+    "color: red",
+    "",
+  );
+  Deno.exit(1);
+}
+
 const promises = [];
-for (const entry of ENTRY_POINTS) {
-  const { href } = new URL(entry, import.meta.url);
-  promises.push(checkDocs(href));
+for (const url of ENTRY_POINT_URLS) {
+  promises.push(checkDocs(url));
 }
 
 try {

deno.json

@@ -59,7 +59,7 @@
     "lint:circular": "deno run --allow-env --allow-read --allow-net=deno.land,jsr.io ./_tools/check_circular_package_dependencies.ts",
     "lint:mod-exports": "deno run --allow-env --allow-read ./_tools/check_mod_exports.ts",
     "lint:tools-types": "deno check _tools/*.ts",
-    "lint:docs": "deno doc --lint async/mod.ts collections/mod.ts bytes/mod.ts datetime/mod.ts internal/mod.ts jsonc/mod.ts media_types/mod.ts regexp/mod.ts url/mod.ts webgpu/mod.ts && deno run -A _tools/check_docs.ts",
+    "lint:docs": "deno run -A _tools/check_docs.ts",
     "lint": "deno lint && deno task fmt:licence-headers --check && deno task lint:circular && deno task lint:deprecations && deno task lint:tools-types && deno task lint:mod-exports && deno task lint:docs",
     "typos": "typos -c ./.github/workflows/typos.toml",
     "build:crypto": "deno task --cwd crypto/_wasm wasmbuild",

ulid/mod.ts

@@ -7,6 +7,37 @@
  * Utilities for generating and working with
  * {@link https://github.com/ulid/spec | Universally Unique Lexicographically Sortable Identifiers (ULIDs)}.
  *
+ * To generate a ULID use the {@linkcode ulid} function. This will generate a
+ * ULID based on the current time.
+ *
+ * ```ts
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ```
+ *
+ * {@linkcode ulid} does not guarantee that the ULIDs will be strictly
+ * increasing for the same current time. If you need to guarantee that the ULIDs
+ * will be strictly increasing, even for the same current time, use the
+ * {@linkcode monotonicUlid} function.
+ *
+ * ```ts
+ * import { monotonicUlid } from "@std/ulid";
+ *
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * ```
+ *
+ * Because each ULID encodes the time it was generated, you can extract the
+ * timestamp from a ULID using the {@linkcode decodeTime} function.
+ *
+ * ```ts
+ * import { decodeTime, ulid } from "@std/ulid";
+ *
+ * const x = ulid(150000);
+ * decodeTime(x); // 150000
+ * ```
+ *
  * @module
  */
 
@@ -19,27 +50,28 @@ import {
   RANDOM_LEN,
   TIME_LEN,
   TIME_MAX,
-  type ULID,
 } from "./_util.ts";
 
-export type { ULID } from "./_util.ts";
-
 /**
- * Extracts the timestamp given a ULID.
+ * Extracts the number of milliseconds since the Unix epoch that had passed when
+ * the ULID was generated. If the ULID is malformed, an error will be thrown.
  *
- * @example
+ * @example Decode the time from a ULID
  * ```ts
  * import { ulid, decodeTime } from "@std/ulid";
  *
  * const x = ulid(150000);
  * decodeTime(x); // 150000
  * ```
+ *
+ * @param ulid The ULID to extract the timestamp from.
+ * @returns The number of milliseconds since the Unix epoch that had passed when the ULID was generated.
  */
-export function decodeTime(id: string): number {
-  if (id.length !== TIME_LEN + RANDOM_LEN) {
+export function decodeTime(ulid: string): number {
+  if (ulid.length !== TIME_LEN + RANDOM_LEN) {
     throw new Error("malformed ulid");
   }
-  const time = id
+  const time = ulid
     .substring(0, TIME_LEN)
     .split("")
     .reverse()
@@ -56,38 +88,80 @@ export function decodeTime(id: string): number {
   return time;
 }
 
+const defaultMonotonicUlid = monotonicFactory();
+
 /**
- * Generate a monotonically increasing ULID, optionally based on a given
- * timestamp.
+ * Generate a ULID that monotonically increases even for the same millisecond,
+ * optionally passing the current time. If the current time is not passed, it
+ * will default to `Date.now()`.
  *
- * @example
+ * Unlike the {@linkcode ulid} function, this function is guaranteed to return
+ * strictly increasing ULIDs, even for the same seed time, but only if the seed
+ * time only ever increases. If the seed time ever goes backwards, the ULID will
+ * still be generated, but it will not be guaranteed to be monotonic with
+ * previous ULIDs for that same seed time.
+ *
+ * @example Generate a monotonic ULID
+ * ```ts
+ * import { monotonicUlid } from "@std/ulid";
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAS
+ * monotonicUlid(); // 01HYFKHG5F8RHM2PM3D7NSTDAT
+ * monotonicUlid(); // 01HYFKHHX8H4BRY8BYHAV1BZ2T
+ * ```
+ *
+ * @example Generate a monotonic ULID with a seed time
  * ```ts
  * import { monotonicUlid } from "@std/ulid";
  *
  * // 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
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1Q
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1R
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1S
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1T
+ * monotonicUlid(150000); // 0000004JFHJJ2Z7X64FN2B4F1U
+ *
+ * // A different timestamp will reset the random bits
+ * monotonicUlid(150001); // 0000004JFHJJ2Z7X64FN2B4F1P
+ *
+ * // A previous seed time will not guarantee ordering, and may result in a
+ * // ULID lower than one with the same seed time generated previously
+ * monotonicUlid(150000); // 0000004JFJ7XF6D76ES95SZR0X
  * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID that is guaranteed to be strictly increasing for the same seed time.
  */
-export const monotonicUlid: ULID = monotonicFactory();
+export function monotonicUlid(seedTime: number = Date.now()): string {
+  return defaultMonotonicUlid(seedTime);
+}
 
 /**
- * Generate a ULID, optionally based on a given timestamp.
+ * Generate a ULID, optionally based on a given timestamp. If the timestamp is
+ * not passed, it will default to `Date.now()`.
  *
- * @example
+ * Multiple calls to this function with the same seed time will not guarantee
+ * that the ULIDs will be strictly increasing, even if the seed time is the
+ * same. For that, use the {@linkcode monotonicUlid} function.
+ *
+ * @example Generate a ULID
  * ```ts
  * import { ulid } from "@std/ulid";
- * ulid(); // 01ARZ3NDEKTSV4RRFFQ69G5FAV
+ * ulid(); // 01HYFKMDF3HVJ4J3JZW8KXPVTY
+ * ulid(); // 01HYFKMDF3D2P7G502B9Z2VKV0
+ * ulid(); // 01HYFKMDZQ7JD17CRKDXQSZ3Z4
+ * ```
  *
- * // You can also input a seed time which will consistently give you the same string for the time component
- * ulid(1469918176385); // 01ARYZ6S41TSV4RRFFQ69G5FAV
+ * @example Generate a ULID with a seed time
+ * ```ts
+ * import { ulid } from "@std/ulid";
+ *
+ * ulid(150000); // 0000004JFG3EKDRE04TVVDJW7K
+ * ulid(150000); // 0000004JFGN0KHBH0447AK895X
+ * ulid(150000); // 0000004JFGMRDH0PN7SM8BZN06
  * ```
+ *
+ * @param seedTime The time to base the ULID on, in milliseconds since the Unix epoch. Defaults to `Date.now()`.
+ * @returns A ULID.
  */
 export function ulid(seedTime: number = Date.now()): string {
   return encodeTime(seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN);