0
# Time Utilities
1
2
Functions for encoding and decoding timestamps in ULID format, enabling extraction of creation time from any ULID and custom timestamp encoding.
3
4
## Capabilities
5
6
### Decode Time
7
8
Extracts the timestamp from a ULID string, returning the original millisecond timestamp used during generation.
9
10
```typescript { .api }
11
/**
12
* Decode time from a ULID
13
* @param id - The ULID string to decode
14
* @returns The decoded timestamp in milliseconds since Unix epoch
15
* @throws ULIDError if the ULID is malformed or contains invalid characters
16
*/
17
function decodeTime(id: ULID): number;
18
```
19
20
**Usage Examples:**
21
22
```typescript
23
import { decodeTime, ulid } from "ulid";
24
25
// Generate a ULID and extract its timestamp
26
const id = ulid();
27
const timestamp = decodeTime(id);
28
const createdAt = new Date(timestamp);
29
30
console.log(`ULID ${id} was created at ${createdAt.toISOString()}`);
31
32
// Decode timestamp from existing ULID
33
const existingId = "01HNZX8JGFACFA36RBXDHEQN6E";
34
const originalTime = decodeTime(existingId); // 1469918176385
35
36
// Use with specific ULID
37
try {
38
const time = decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV");
39
console.log(new Date(time)); // Original creation date
40
} catch (error) {
41
console.error("Invalid ULID:", error.message);
42
}
43
```
44
45
**Error Conditions:**
46
47
- Throws `ULIDError` with code `DecodeTimeValueMalformed` if ULID length is incorrect
48
- Throws `ULIDError` with code `DecodeTimeInvalidCharacter` if ULID contains invalid Base32 characters
49
- Throws `ULIDError` with code `DecodeTimeValueMalformed` if decoded timestamp exceeds maximum value
50
51
### Encode Time
52
53
Encodes a timestamp into ULID time format using Crockford Base32 encoding.
54
55
```typescript { .api }
56
/**
57
* Encode the time portion of a ULID
58
* @param now - The timestamp to encode (milliseconds since Unix epoch)
59
* @param len - Length to generate (default: TIME_LEN = 10)
60
* @returns The encoded time string
61
* @throws ULIDError for invalid timestamp values
62
*/
63
function encodeTime(now: number, len?: number): string;
64
```
65
66
**Usage Examples:**
67
68
```typescript
69
import { encodeTime, TIME_LEN } from "ulid";
70
71
// Encode current timestamp
72
const now = Date.now();
73
const encoded = encodeTime(now); // "01HNZXD07M"
74
75
// Encode specific timestamp
76
const specificTime = 1469918176385;
77
const timeStr = encodeTime(specificTime); // "01ARYZ6S41"
78
79
// Encode with custom length (advanced usage)
80
const shortTime = encodeTime(now, 8); // Shorter time encoding
81
82
// Use with Date objects
83
const futureDate = new Date("2030-01-01T00:00:00Z");
84
const futureEncoded = encodeTime(futureDate.getTime());
85
```
86
87
**Error Conditions:**
88
89
- Throws `ULIDError` with code `EncodeTimeValueMalformed` if timestamp is NaN or not an integer
90
- Throws `ULIDError` with code `EncodeTimeNegative` if timestamp is negative
91
- Throws `ULIDError` with code `EncodeTimeSizeExceeded` if timestamp exceeds `TIME_MAX` (2^48 - 1)
92
93
**Time Format Details:**
94
95
- Time portion is always 10 characters (when using default length)
96
- Uses Crockford Base32 alphabet: `0123456789ABCDEFGHJKMNPQRSTVWXYZ`
97
- Represents milliseconds since Unix epoch (January 1, 1970 UTC)
98
- Maximum supported timestamp: 281,474,976,710,655 (approximately year 10,889)
99
100
## Constants
101
102
```typescript { .api }
103
const TIME_LEN: number; // 10 - Standard length of time portion
104
const TIME_MAX: number; // 281474976710655 - Maximum timestamp value (2^48 - 1)
105
```