pxid 0.2.4

Prefixed Globally Unique Identifier
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

<div>
  <h1 align="center">pxid</h1>
  <h4 align="center">
   Prefixed Globally Unique Identifier
  </h4>
</div>

<div align="center">

  [![Crates.io](https://img.shields.io/crates/v/pxid.svg)](https://crates.io/crates/pxid)
  [![Documentation](https://docs.rs/pxid/badge.svg)](https://docs.rs/pxid)
  ![Build](https://github.com/EstebanBorai/pxid/workflows/build/badge.svg)
  ![Clippy](https://github.com/EstebanBorai/pxid/workflows/clippy/badge.svg)
  ![Formatter](https://github.com/EstebanBorai/pxid/workflows/fmt/badge.svg)

</div>

## Motivation

Extend the [rs/xid][1] implementation by adding capability to have
a prefix and at the same time have a `u16` type support by fitting prefix bits.

This library is inspired in Stripe IDs which have a friendly notation and are
very short IDs. These IDs are prefixed with a maximum of 4 bytes belonging to
the entity behind them.

## Usage

```rust
use pxid::Pxid;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Given that some of the dependencies to build
    // an instance of the Pxid may fail.
    // - Getting current timestamp
    // - Getting machine id
    // - Getting process id
    //
    // A `Result<Pxid, Error>` is returned.
    let id = Pxid::new("acct".as_bytes())?;

    println!("{}", id); // acct_9m4e2mr0ui3e8a215n4g
}
```

To improve memory usage (reduce allocations), and reuse dependencies required,
the `Factory` struct can also be used to build `Pxid` instances.

This is the recommended way to build `Pxid` instances, given that resources are
initialized once, and then reused.

```rust
use pxid::Factory;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let factory = Factory::new_without_prefix()?;
    let id = factory.with_prefix("acct");

    println!("{}", id); // acct_9m4e2mr0ui3e8a215n4g

    let factory_with_prefix = Factory::new("acct")?;
    let id = factory_with_prefix.generate();

    println!("{}", id); // acct_9m4e2mr0ui3e8a215n4g
}
```

### GraphQL Support

You can use `Pxid` on GraphQL via the `async-graphql` crate.
Make sure the `graphql` feature is enabled and import `Pxid` for GraphQL.

```rust
use async_graphql::{Context, InputObject, Result, SimpleObject};
use pxid::graphql::Pxid;

// -- snip --

#[derive(Debug, InputObject)]
pub struct PostCreateInput {
    pub title: String,
    pub content: String,
    pub parent_id: Option<Pxid>,
}

impl PostCreate {
    pub async fn exec(ctx: &Context<'_>, input: PostCreateInput) -> Result<Self> {
// -- snip --
```

> Check out the full example [here][2].

## Layout
A prefixed XID fits nicely on a 16 bytes slice thanks to its packed data format.

<div align="center">
  <table border="1">
    <tr>
      <td>0</td>
      <td>1</td>
      <td>2</td>
      <td>3</td>
      <td>4</td>
      <td>5</td>
      <td>6</td>
      <td>7</td>
      <td>8</td>
      <td>9</td>
      <td>10</td>
      <td>11</td>
      <td>12</td>
      <td>13</td>
      <td>14</td>
      <td>15</td>
    </tr>
    <tr>
      <td colspan="4">Prefix</td>
      <td colspan="4">Timestamp</td>
      <td colspan="3">Machine ID</td>
      <td colspan="2">Process ID</td>
      <td colspan="3">Counter</td>
    </tr>
  </table>
</div>

For a total of 16 bytes.

The prefix allows up to 4 UTF-8 Characters, this allows the ID to provide some
context about its scope.

```txt
acct_9m4e2mr0ui3e8a215n4g
ordr_9m4e2mr0ui3e8a215n4g
usr_9m4e2mr0ui3e8a215n4g
```

This way IDs are not only even harder to collide, but they also provides a bit
of context on record association.

## License

This project is licensed under the MIT License

[1]: https://github.com/rs/xid
[2]: https://github.com/whizzes/gabble/blob/ca10e295ce1386dd15a8f91f968e7aa8085287c4/crates/server/src/graphql/modules/post/mutation/post_create.rs