redb_model 0.6.1

Redb model derive macro and DTO type conversion
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

# Redb Model
A derive macro for generating [redb] table definitions and (optionally) DTO object
conversion methods/implementations.

## Functionality

At a minimum, deriving `Model` on a named `struct` will implement the [Model]
trait, declaring `redb::TableDefinition` as an associated constant.

```rust
#[derive(Model)]
struct User {
    #[entry(position(key))]
    id: u32,
    #[entry(position(value))]
    name: String,
    #[entry(position(value))]
    email: String,
}

assert_eq!(User::DEFINITION.name(), "User");
```

Tables can be customized with optional arguments, and an implementation of
[ModelExt] can be generated to provide common `DTO` functionality.

```rust
#
#[derive(Model)]
#[model(name = "outbound_edge", impl_ext)]
struct Edge {
    #[entry(position(key))]
    source: u32,
    #[entry(position(key))]
    target: u32,
    #[entry(position(value))]
    label: String,
}

assert_eq!(Edge::DEFINITION.name(), "outbound_edge");
let edge = Edge::from_values(((0, 1), "label".to_owned()));

let txn = db.begin_write().unwrap();
{
    let mut table = txn.open_table(Edge::DEFINITION).unwrap();
    let (k, v) = edge.as_values();
    table.insert(k, v).unwrap();
}
txn.commit().unwrap();
```

## Struct Attributes

A model can be customized with the `model` attribute, providing any of the
following arguments:

Argument | Description | Type | Default
---|---|---|---
`table_name` | The table name passed to the definition | `String` | `<Struct name>` (case-sensitive)
`table_type` | Table type, either `table` or `multimap_table` | `String` | `table`
`impl_ext` | Implement [`ModelExt`] for the type | `bool` | `false`
`impl_from` | Implement `From<T>`, mapping `T` to the `from_values(T)` and `from_guards(T)` methods of [`ModelExt`]. Requires `impl_ext`. | `bool` | `false`

## Field Attributes

Values can be customized with the `entry` attribute. Each field must be specified
as either `key` or `value` with the `position` argument. Note that composite
variables (multiple `key` or `value` fields) are combined as tuples in the order
they are defined in the struct.

Argument | Description | Type | Default
---|---|---|---
`position` | The position of the field in an entry, either a `key` or a `value`. | `String` | N/A

## Implementation details

General notes regarding trait and type generation.

### `String` Table Definitions

`redb_model` will replace `String` with `&str` for table definitions. This
is so that composite (tuple) variables can be borrowed and passed to database
handlers without destructuring the DTO.

### Unit type values

The unit type `()` must be passed if no value is defined.

```rust
#[derive(Model)]
#[model(name = "outbound_edge", impl_ext)]
struct Edge {
    #[entry(position(key))]
    source: [u8; 16],
    #[entry(position(key))]
    target: [u8; 16],
}
let k = ([0; 16], [1; 16]);
let v = ();
let e = Edge::from_values((k, v));
```

License: MIT OR Apache-2.0