You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Additionally, both ESM and CommonJS entrypoints are provided.
71
55
72
56
## Usage
73
57
74
-
To generate a ULID, simply run the function!
58
+
To quickly generate a ULID, you can simply import the `ulid`function:
75
59
76
-
```javascript
77
-
import { ulid } from'ulid'
60
+
```typescript
61
+
import { ulid } from"ulid";
78
62
79
-
ulid() // 01ARZ3NDEKTSV4RRFFQ69G5FAV
63
+
ulid();// 01ARZ3NDEKTSV4RRFFQ69G5FAV
80
64
```
81
65
82
66
### Seed Time
83
67
84
68
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.
85
69
86
-
```javascript
70
+
```typescript
87
71
ulid(1469918176385) // 01ARYZ6S41TSV4RRFFQ69G5FAV
88
72
```
89
73
90
74
### Monotonic ULIDs
91
75
92
-
To generate monotonically increasing ULIDs, create a monotonic counter.
76
+
To generate monotonically increasing ULIDs, create a monotonic counter with `monotonicFactory`.
93
77
94
-
*Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond*
78
+
> Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond
95
79
96
-
```javascript
97
-
import { monotonicFactory } from'ulid'
80
+
```typescript
81
+
import { monotonicFactory } from"ulid";
98
82
99
-
constulid=monotonicFactory()
83
+
const ulid =monotonicFactory();
100
84
101
85
// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
102
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR8
103
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR9
104
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRA
105
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRB
106
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRC
86
+
ulid(150000);// 000XAL6S41ACTAV9WEVGEMMVR8
87
+
ulid(150000);// 000XAL6S41ACTAV9WEVGEMMVR9
88
+
ulid(150000);// 000XAL6S41ACTAV9WEVGEMMVRA
89
+
ulid(150000);// 000XAL6S41ACTAV9WEVGEMMVRB
90
+
ulid(150000);// 000XAL6S41ACTAV9WEVGEMMVRC
107
91
108
92
// Even if a lower timestamp is passed (or generated), it will preserve sort order
109
-
ulid(100000) // 000XAL6S41ACTAV9WEVGEMMVRD
93
+
ulid(100000);// 000XAL6S41ACTAV9WEVGEMMVRD
110
94
```
111
95
112
96
### Pseudo-Random Number Generators
113
97
114
-
`ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on node it will use `crypto.randomBytes`.
115
-
116
-
#### Allowing the insecure `Math.random`
117
-
118
-
By default, `ulid` will not use `Math.random`, because that is insecure. To allow the use of `Math.random`, you'll have to use `factory` and `detectPrng`.
98
+
`ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on NodeJS it will use `crypto.randomBytes`.
119
99
120
-
```javascript
121
-
import { factory, detectPrng } from'ulid'
100
+
#### Using `Math.random` (insecure)
122
101
123
-
constprng=detectPrng(true) // pass `true` to allow insecure
124
-
constulid=factory(prng)
102
+
By default, `ulid` will not use `Math.random` to generate random values. You can bypass this limitation by overriding the PRNG:
125
103
126
-
ulid() // 01BXAVRG61YJ5YSBRM51702F6M
127
-
```
128
-
129
-
#### Use your own PRNG
130
-
131
-
To use your own pseudo-random number generator, import the factory, and pass it your generator function.
132
-
133
-
```javascript
134
-
import { factory } from'ulid'
135
-
importprngfrom'somewhere'
136
-
137
-
constulid=factory(prng)
138
-
139
-
ulid() // 01BXAVRG61YJ5YSBRM51702F6M
140
-
```
141
-
142
-
You can also pass in a `prng` to the `monotonicFactory` function.
143
-
144
-
```javascript
145
-
import { monotonicFactory } from'ulid'
146
-
importprngfrom'somewhere'
104
+
```typescript
105
+
const ulid =monotonicFactory(() =>Math.random());
147
106
148
-
constulid=monotonicFactory(prng)
149
-
150
-
ulid() // 01BXAVRG61YJ5YSBRM51702F6M
107
+
ulid(); // 01BXAVRG61YJ5YSBRM51702F6M
151
108
```
152
109
153
-
##Implementations in other languages
110
+
### Tests
154
111
155
-
Refer to [ulid/spec](https://github.com/ulid/spec)
112
+
Install dependencies using `npm install` first, and then simply run `npm test`to run the test suite.
156
113
157
114
## Specification
158
115
159
-
Refer to [ulid/spec](https://github.com/ulid/spec)
160
-
161
-
## Test Suite
162
-
163
-
```
164
-
npm test
165
-
```
116
+
You can find the full specification, as well as information regarding implementations in other languages, over at [ulid/spec](https://github.com/ulid/spec).
166
117
167
118
## Performance
168
119
169
-
```
170
-
npm run perf
171
-
```
120
+
You can test `ulid`'s performance by running `npm run bench`:
172
121
173
122
```
174
-
ulid
175
-
336,331,131 op/s » encodeTime
176
-
102,041,736 op/s » encodeRandom
177
-
17,408 op/s » generate
178
-
179
-
180
-
Suites: 1
181
-
Benches: 3
182
-
Elapsed: 7,285.75 ms
123
+
Simple ulid x 56,782 ops/sec ±2.50% (86 runs sampled)
124
+
ulid with timestamp x 58,574 ops/sec ±1.80% (87 runs sampled)
0 commit comments