Skip to content

Commit 2ccc3cd

Browse files
mplanchardmplanchard
committed
update readmes
1 parent 815168b commit 2ccc3cd

File tree

5 files changed

+61
-24
lines changed

5 files changed

+61
-24
lines changed

‎README.md

+16-9
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,29 @@
11
# cuid-rust
22

33
[![Build Status](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml?query=branch%3Amaster)
4-
[![Crates.io](https://img.shields.io/crates/v/cuid2 "Crates.io")](https://crates.io/crates/cuid2/)
5-
[![docs.rs](https://docs.rs/cuid/badge.svg)](https://docs.rs/cuid2/)
4+
[![Crates.io](https://img.shields.io/crates/v/cuid "Crates.io")](https://crates.io/crates/cuid/)
5+
[![docs.rs](https://docs.rs/cuid/badge.svg)](https://docs.rs/cuid/)
66

7-
This repository is the home of the [cuid] and [cuid2] crates. The
8-
original CUID standard is marked as [deprecated](https://github.com/paralleldrive/cuid2#improvements-over-cuid)
7+
This repository is the home of the [cuid], [cuid1], and [cuid2]
8+
crates. The original CUID standard is marked as
9+
[deprecated](https://github.com/paralleldrive/cuid2#improvements-over-cuid)
910
in favor of CUID2, but we intent to continue supporting v1 CUIDs
1011
indefinitely, since their k-sortability is only insecure in specific
1112
use-cases, while their sortability is quite useful in other
12-
use-cases. `cuid2` is provided as a separate crate because its
13-
generated IDs have different semantics from `cuid`, so it is not
14-
necessarily a drop-in replacement.
13+
use-cases.
1514

16-
If you are using the `cuid` crate already, you can also use `cuid2()`
17-
and related functions from that crate.
15+
The `cuid` crate provides a wrapper around both versions:
16+
- https://github.com/mplanchard/cuid-rust/tree/master/crates/cuid
17+
18+
In addition, both `cuid1` and `cuid2` may be used as standalone crates:
19+
- https://github.com/mplanchard/cuid-rust/tree/master/crates/cuid1
20+
- https://github.com/mplanchard/cuid-rust/tree/master/crates/cuid2
1821

1922
Please see the individual crates' READMEs for more information.
2023

24+
If you are upgrading to `cuid` 2.0, you must swap usages of non-version-specific
25+
calls like `cuid()` for the desired version, i.e. `cuid1()` or `cuid2()`.
26+
2127
## Development
2228

2329
A [`flake.nix`](https://nixos.wiki/wiki/Flakes) file is provided for easy
@@ -40,4 +46,5 @@ source the nix packages into your shell (or editor environment, if you use a
4046
direnv plugin).
4147

4248
[cuid]: https://crates.io/crates/cuid/
49+
[cuid1]: https://crates.io/crates/cuid1/
4350
[cuid2]: https://crates.io/crates/cuid2/

‎crates/cuid/Cargo.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "cuid"
3-
version = "1.3.3"
3+
version = "2.0.0"
44
description = "An ipmlementation of CUID protocol in rust"
55
documentation = "https://docs.rs/cuid/latest/cuid/"
66
resolver = "2"

‎crates/cuid/README.md

+22-6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# cuid-rust
1+
# cuid
22

33
[![Build Status](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml?query=branch%3Amaster)
44
[![Crates.io](https://img.shields.io/crates/v/cuid "Crates.io")](https://crates.io/crates/cuid/)
@@ -25,14 +25,28 @@ therefore up to the users of this crate to choose an ID
2525
appropriately. Therefore, this library will continue to support v1
2626
CUIDs for the foreseeable future. See the original authors' position in more detail [here](https://github.com/paralleldrive/cuid2?tab=readme-ov-file#note-on-k-sortablesequentialmonotonically-increasing-ids).
2727

28-
If you only need `cuid2`, you can use the `cuid2` crate: [cuid2 crate](https://docs.rs/cuid2/latest/cuid2/).
28+
By default, both `cuid1` and `cuid2` algorithms are provided. If you
29+
only need one, you can disable default features and select just the one
30+
you need, for example to only include v2 CUIDs:
31+
32+
```toml
33+
cuid = { version = "2.0.0", default-features = false, features = ["v2"] }
34+
```
35+
36+
You can also use the [cuid1] or [cuid2] crates independently.
37+
38+
## Upgrading to version 2.0
39+
40+
Functions like `cuid()` have been removed in favor of version-specific
41+
functions, like `cuid1()`. You can either update the function calls or
42+
replace your use of the cuid crate with the [cuid1] or [cuid2] crate.
2943

3044
## Installation
3145

3246
In cargo.toml
3347

3448
```toml
35-
cuid = "1.4.0"
49+
cuid = "2.0.0"
3650
```
3751

3852
Or install the binary:
@@ -59,18 +73,18 @@ fn main() -> () {
5973
// the length, counter function, and fingerprinter (note that
6074
// these are const functions, so you can create a static
6175
// constructor if desired.
62-
let constructor = CuidConstructor::new()
76+
static CONSTRUCTOR: Cuid2Constructor = Cuid2Constructor::new()
6377
.with_length(20)
6478
.with_counter(const_counter)
6579
.with_fingerprinter(const_fingerprinter);
6680
println!("{}", constructor.create_id());
6781
}
6882

69-
fn const_counter() -> u64 {
83+
const fn const_counter() -> u64 {
7084
42
7185
}
7286

73-
fn const_fingerprinter() -> String {
87+
const fn const_fingerprinter() -> String {
7488
"fingers".to_string()
7589
}
7690
```
@@ -165,3 +179,5 @@ sudo nice -n -20 su <username> -l -c "cd $PWD && cargo bench"
165179
```
166180

167181
[benches]: ./benches/cuid.rs
182+
[cuid1]: https://crates.io/crates/cuid1/
183+
[cuid2]: https://crates.io/crates/cuid2/

‎crates/cuid1/README.md

+12-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# cuid1
22

33
[![Build Status](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml?query=branch%3Amaster)
4-
[![Crates.io](https://img.shields.io/crates/v/cuid "Crates.io")](https://crates.io/crates/cuid1/)
5-
[![docs.rs](https://docs.rs/cuid/badge.svg)](https://docs.rs/cuid1/)
4+
[![Crates.io](https://img.shields.io/crates/v/cuid1 "Crates.io")](https://crates.io/crates/cuid1/)
5+
[![docs.rs](https://docs.rs/cuid1/badge.svg)](https://docs.rs/cuid1/)
66

77
Cuids are "Collision-resistant ids optimized for horizontal scaling and
88
binary search lookup performance."
@@ -14,16 +14,21 @@ This library provides the `cuid1` algorithm:
1414
- `cuid1` is a k-sortable ID that is extremely fast to generate with
1515
very good randomness properties
1616

17+
Note that the [cuid] crate is also available, and provides access to
18+
both the `cuid1` and `cuid2` algorithms.
19+
1720
**NOTE:** It is the position of the original authors of CUID that
1821
`cuid1` is "insecure" due to its being k-sortable and potentially
1922
exposing information about generation order and/or time of
2023
generation. It is my position that these properties apply to a number
2124
of very good ID-generating algorithms (such as UUIDv7), and it is
2225
therefore up to the users of this crate to choose an ID
2326
appropriately. Therefore, this library will continue to support v1
24-
CUIDs for the foreseeable future. See the original authors' position in more detail [here](https://github.com/paralleldrive/cuid2?tab=readme-ov-file#note-on-k-sortablesequentialmonotonically-increasing-ids).
27+
CUIDs for the foreseeable future. See the original authors' position
28+
in more detail [here](https://github.com/paralleldrive/cuid2?tab=readme-ov-file#note-on-k-sortablesequentialmonotonically-increasing-ids).
2529

26-
If you only need `cuid2`, you can use the `cuid2` crate: [cuid2 crate](https://docs.rs/cuid2/latest/cuid2/).
30+
If you would like an algorithm that is not k-sortable, you can use the
31+
[`cuid2` crate](https://docs.rs/cuid2/latest/cuid2/).
2732

2833
## Installation
2934

@@ -129,3 +134,6 @@ sudo nice -n -20 su <username> -l -c "cd $PWD && cargo bench"
129134
```
130135

131136
[benches]: ./benches/cuid.rs
137+
[cuid]: https://crates.io/crates/cuid/
138+
[cuid1]: https://crates.io/crates/cuid1/
139+
[cuid2]: https://crates.io/crates/cuid2/

‎crates/cuid2/README.md

+10-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Cuid2
1+
# cuid2
22

33
[![Build Status](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/mplanchard/cuid-rust/actions/workflows/ci.yml?query=branch%3Amaster)
44
[![Crates.io](https://img.shields.io/crates/v/cuid2 "Crates.io")](https://crates.io/crates/cuid2/)
5-
[![docs.rs](https://docs.rs/cuid/badge.svg)](https://docs.rs/cuid2/)
5+
[![docs.rs](https://docs.rs/cuid2/badge.svg)](https://docs.rs/cuid2/)
66

77
Secure, collision-resistant ids optimized for horizontal scaling and
88
performance.
@@ -11,8 +11,10 @@ This is a Rust implementation of the CUID2 algorithm, defined by its
1111
reference implementation [here](https://github.com/paralleldrive/cuid2).
1212

1313
Please see that repository for a discussion of the benefits of CUIDs, as
14-
well as for the improvements in CUID2 over the original CUID algorithm
15-
(which is also implemented in Rust [here](https://docs.rs/cuid/latest/cuid/)).
14+
well as for the changes in CUID2 relative to the original CUID algorithm.
15+
16+
Both algorithms are available via the [cuid] crate, while the CUID1
17+
algorithm is available via the [cuid1] crate.
1618

1719
## Usage
1820

@@ -57,3 +59,7 @@ binary, which generates a CUID on the command line. It can be used like:
5759
> cuid2
5860
y3cfw1hafbtezzflns334sb2
5961
```
62+
63+
[cuid]: https://crates.io/crates/cuid/
64+
[cuid1]: https://crates.io/crates/cuid1/
65+
[cuid2]: https://crates.io/crates/cuid2/

0 commit comments

Comments
 (0)