<commit_before># lazers-traits - laze RS interface

## General philosophy

This library models the general interactions with CouchDB-like storages,
be it a CouchDB server itself or a local K/V store with a CouchDB interface.

### Techniques

* All operations return Results. An Error value describes a _failed
  interaction_, not a negative query result (such as a database missing).

* Responses with multiple semantic meanings are mapped to enums.
* The library uses decorations of Result types and these enums for easier
access.

## Dependencies

We use `serde`s definitions for serialisation/deserialisation.

serde provides many features we want, including the ability to read
documents
in a typesafe manner.

```rust
extern crate serde;
```

We use the error chain macro to provide the ability to wrap external errors
in an easy fashion.

```rust
#[macro_use]
extern crate error_chain;
```

To express asynchronicity, we use futures-rs.

```rust
extern crate futures;
```

## Exports

The library exports two modules.

[`result`](/lazers-traits/src/result) defines our own `Result` type. See the module page for details.

[`prelude`](/lazers-traits/src/prelude) exports all definitions needed for day-to-day work, this allows
users
to simply `use lazers_traits::prelude::*` instead of loading a huge block of
codes imports themselves.

[`decorations`](/lazers-traits/src/decorations) collects all convenience decorations of the library on, for
example, `Result` types.

```rust
pub mod result;
pub mod prelude;
pub mod decorations;
```

## Use of externals

We use a custom error created using error_chain!.

```rust
use result::Error;
```

Futures, we use mainly through the BoxFuture interface. This carries with it the information that we expect all futures to be `Send`.

```rust
use futures::BoxFuture;
```

We don't implement our own `Deserialize` and `Serialize` traits, but instead
use the ones from serde.

```rust
use serde::de::Deserialize;
use serde::ser::Serialize;
```

We have to provide custom `Debug` implementations, so we import the trait.

```rust
use std::fmt::Debug;
```

## Definitions

### DatabaseName

The DatabaseName is anything we can use to name a database. Currently, this
type is just an alias for String.

```rust
pub type DatabaseName = String;
```

### Document

CouchDB is all about handling documents, which means we have to find a
definition for what constitutes a document. In our case, we decide that
anything that can be serialised and deserialised by serde is a document.

Also, we provide a blanket implementation that ensures that every type that
is Deserialize and Serialize.

The Document trait is a marker trait and holds not methods.

Documents, as a design choice, don't hold information about the database
they were loaded from.

Finally, all Documents must be `Send`, as the represent plain data.

```rust
pub trait Document: Deserialize + Serialize + Send {}

impl<D: Deserialize + Serialize + Send + ?Sized> Document for D {}
```

### Key

Keys are the main method of addressing Documents in CouchDB. As keys can
take
many forms and are regularly used to encode data, we only express the bare
minimum as a trait.

Keys also encode the revision of the current document. The revision is
optional, but must be given for documents already in the database.<commit_msg>Typo: not → no<commit_after># lazers-traits - laze RS interface

## General philosophy

This library models the general interactions with CouchDB-like storages,
be it a CouchDB server itself or a local K/V store with a CouchDB interface.

### Techniques

* All operations return Results. An Error value describes a _failed
  interaction_, not a negative query result (such as a database missing).

* Responses with multiple semantic meanings are mapped to enums.
* The library uses decorations of Result types and these enums for easier
access.

## Dependencies

We use `serde`s definitions for serialisation/deserialisation.

serde provides many features we want, including the ability to read
documents
in a typesafe manner.

```rust
extern crate serde;
```

We use the error chain macro to provide the ability to wrap external errors
in an easy fashion.

```rust
#[macro_use]
extern crate error_chain;
```

To express asynchronicity, we use futures-rs.

```rust
extern crate futures;
```

## Exports

The library exports two modules.

[`result`](/lazers-traits/src/result) defines our own `Result` type. See the module page for details.

[`prelude`](/lazers-traits/src/prelude) exports all definitions needed for day-to-day work, this allows
users
to simply `use lazers_traits::prelude::*` instead of loading a huge block of
codes imports themselves.

[`decorations`](/lazers-traits/src/decorations) collects all convenience decorations of the library on, for
example, `Result` types.

```rust
pub mod result;
pub mod prelude;
pub mod decorations;
```

## Use of externals

We use a custom error created using error_chain!.

```rust
use result::Error;
```

Futures, we use mainly through the BoxFuture interface. This carries with it the information that we expect all futures to be `Send`.

```rust
use futures::BoxFuture;
```

We don't implement our own `Deserialize` and `Serialize` traits, but instead
use the ones from serde.

```rust
use serde::de::Deserialize;
use serde::ser::Serialize;
```

We have to provide custom `Debug` implementations, so we import the trait.

```rust
use std::fmt::Debug;
```

## Definitions

### DatabaseName

The DatabaseName is anything we can use to name a database. Currently, this
type is just an alias for String.

```rust
pub type DatabaseName = String;
```

### Document

CouchDB is all about handling documents, which means we have to find a
definition for what constitutes a document. In our case, we decide that
anything that can be serialised and deserialised by serde is a document.

Also, we provide a blanket implementation that ensures that every type that
is Deserialize and Serialize.

The Document trait is a marker trait and holds no methods.

Documents, as a design choice, don't hold information about the database
they were loaded from.

Finally, all Documents must be `Send`, as the represent plain data.

```rust
pub trait Document: Deserialize + Serialize + Send {}

impl<D: Deserialize + Serialize + Send + ?Sized> Document for D {}
```

### Key

Keys are the main method of addressing Documents in CouchDB. As keys can
take
many forms and are regularly used to encode data, we only express the bare
minimum as a trait.

Keys also encode the revision of the current document. The revision is
optional, but must be given for documents already in the database.
{'fraction_non_alphanumeric': 0.076158940397351, 'fraction_numerical': 0.0, 'mean_word_length': 4.602866779089376, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3915781', 'n_tokens_mistral': 1899, 'n_tokens_neox': 1798, 'n_words': 932}