Document more methods

Author: perry-mitchell

README.md

@@ -60,15 +60,15 @@ To quickly generate a ULID, you can simply import the `ulid` function:
 ```typescript
 import { ulid } from "ulid";
 
-ulid(); // 01ARZ3NDEKTSV4RRFFQ69G5FAV
+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
+ulid(1469918176385) // "01ARYZ6S41TSV4RRFFQ69G5FAV"
 ```
 
 ### Monotonic ULIDs
@@ -83,14 +83,14 @@ import { monotonicFactory } from "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
+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
+ulid(100000); // "000XAL6S41ACTAV9WEVGEMMVRD"
 ```
 
 ### Pseudo-Random Number Generators
@@ -104,7 +104,7 @@ By default, `ulid` will not use `Math.random` to generate random values. You can
 ```typescript
 const ulid = monotonicFactory(() => Math.random());
 
-ulid(); // 01BXAVRG61YJ5YSBRM51702F6M
+ulid(); // "01BXAVRG61YJ5YSBRM51702F6M"
 ```
 
 ### Validity
@@ -118,6 +118,24 @@ 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 "ulid";
+
+decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV"); // 1469918176385
+```
+
+Note that while `decodeTime` works on full ULIDs, `encodeTime` encodes only the _time portion_ of ULIDs:
+
+```typescript
+import { encodeTime } from "ulid";
+
+encodeTime(1469918176385); // "01ARYZ6S41"
+```
+
 ### Tests
 
 Install dependencies using `npm install` first, and then simply run `npm test` to run the test suite.

source/index.ts

@@ -1,6 +1,6 @@
-export { isValid, monotonicFactory, ulid } from "./ulid.js";
+export { decodeTime, encodeTime, isValid, monotonicFactory, ulid } from "./ulid.js";
 export { ulidToUUID, uuidToULID } from "./uuid.js";
 export { fixULIDBase32, incrementBase32 } from "./crockford.js";
 export { ULIDError, ULIDErrorCode } from "./error.js";
-export { MAX_ULID, MIN_ULID } from "./constants.js";
+export { MAX_ULID, MIN_ULID, TIME_LEN, TIME_MAX } from "./constants.js";
 export * from "./types.js";

source/ulid.ts

@@ -90,7 +90,7 @@ export function encodeRandom(len: number, prng: PRNG): string {
  * @param len Length to generate
  * @returns The encoded time
  */
-export function encodeTime(now: number, len: number): string {
+export function encodeTime(now: number, len: number = TIME_LEN): string {
     if (isNaN(now)) {
         throw new ULIDError(
             ULIDErrorCode.EncodeTimeValueMalformed,

test/node/ulid.spec.ts

@@ -1,8 +1,20 @@
 import { describe, expect, it } from "vitest";
-import { monotonicFactory, ulid, ULIDFactory } from "../../";
+import { decodeTime, encodeTime, monotonicFactory, ulid, ULIDFactory } from "../../";
 
 const ULID_REXP = /^[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/;
 
+describe("decodeTime", function () {
+    it("extracts a timestamp from a ULID", () => {
+        expect(decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV")).to.equal(1469918176385);
+    });
+});
+
+describe("encodeTime", function () {
+    it("encodes a timestamp", () => {
+        expect(encodeTime(1469918176385)).to.equal("01ARYZ6S41");
+    });
+});
+
 describe("monotonicFactory", () => {
     function stubbedPrng() {
         return 0.96;