edge/doc/apps/server-api/store.md

184 lines
4.0 KiB
Markdown

# Module `store`
Ce module permet de stocker et récupérer des données structurées ("documents") sur le serveur.
## Méthodes
### `store.upsert(ctx: Context, collection: string, doc: Object)`
Enregistre un document dans une collection.
Si le document a une propriété `_id` celle ci est utilisée comme identifiant. Dans le cas contraire elle sera autogénérée par le moteur de stockage.
#### Arguments
- `ctx` **Context** Le contexte d'exécution. Voir la documentation du module [`context`](./context.md)
- `collection` **string** Nom de la collection dans laquelle retrouver le document
- `doc` **Object** Le document à enregistrer
#### Valeur de retour
Le document dans sa forme après enregistrement.
#### Usage
```js
var ctx = context.new();
var obj = store.upsert(ctx, "myCollection", {"foo": "bar"});
```
### `store.get(ctx: Context, collection: string, docId: string)`
Retourne le document associé à l'identifiant `docId` ou `null` si celui ci n'est pas trouvé.
#### Arguments
- `ctx` **Context** Le contexte d'exécution. Voir la documentation du module [`context`](./context.md)
- `collection` **string** Nom de la collection dans laquelle retrouver le document
- `docId` **string** Identifiant du document à récupérer
#### Valeur de retour
le document stocké si il existe, `null` sinon.
#### Usage
```js
function onInit() {
var ctx = context.new();
var obj = store.get(ctx, "myCollection", "doc-id");
}
```
### `store.delete(ctx: Context, collection: string, docId: string)`
Supprime le document associé à l'identifiant dans la collection.
#### Arguments
- `ctx` **Context** Le contexte d'exécution. Voir la documentation du module [`context`](./context.md)
- `collection` **string** Nom de la collection dans laquelle retrouver le document
- `docId` **string** Identifiant de le document à supprime
#### Valeur de retour
Aucune
#### Usage
```js
var ctx = context.new();
store.delete(ctx, "myCollection", "my-item-id");
```
### `store.query(ctx: Context, collection: string, doc: Object, filter: Filter?, options: QueryOptions?)`
Filtre la collection et récupère les documents associés à la requête.
#### Arguments
- `ctx` **Context** Le contexte d'exécution. Voir la documentation du module [`context`](./context.md)
- `collection` **string** Nom de la collection dans laquelle retrouver le document
- `filter` **Filter?** Filtre à appliquer à la collection, voir "Filtres".
- `options` **QueryOptions?** Options de filtrage, voir "Options".
## Propriétés
### `store.DIRECTION_ASC`
> `TODO`
### `store.DIRECTION_DESC`
> `TODO`
## Objets
### `Filter`
Un filtre se construit à partir d'une hiérarchie d'opérateurs sous la forme d'un document.
On distingue deux types d'opérateurs:
- Les opérateurs de combinaison logique;
- Les opérateurs de filtrage.
Les opérateurs d'combinaison logique prennent la forme suivante:
```
{
"<comb_op>": [
<filter_op>,
<filter_op>,
etc
]
}
```
**Exemple**
```json
{
"and": [
{ "eq": { "myAttr1": "foo" } },
{ "neq": { "myAttr2": "bar" } }
]
}
```
Ce filtre serait traduit en syntaxe SQL en `myAttr1 = "foo" AND myAttr2 != "bar"`.
Voici la liste des opérateurs de combinaison logique:
- `and` - "ET" logique
- `or` - "OU" logique
- `not` - Négation logique
Les opérateurs de filtrage prennent la forme suivantes:
```
{
<filter_op>: {
"key1": "val1",
"key2": "val2",
"key3": "val3",
etc
}
}
```
**Exemple**
```json
{ "gt": { "foo": "bar" } },
```
Voici la liste des opérateurs de filtrage:
- `eq` - Comparaison `==`
- `neq` - Comparaison `!=`
- `gt` - Comparaison `>`
- `gte` - Comparaison `>=`
- `lt` - Comparaison `<`
- `lte` - Comparaison `<=`
- `like` - Comparaison type `LIKE` MySQL/SQLite
- `in` - Comparaison type `IN` MySQL/SQLite
### QueryOptions
#### Usage
```js
var ctx = context.new();
var results = store.query(ctx, "myCollection", {
eq: {
"foo": "bar",
}
}, {
limit: 10,
offset: 5,
orderBy: "foo",
orderDirection: store.DIRECTION_ASC,
});
```