mecomp-storage 0.7.2

This library is responsible for storing and retrieving data about a user's music library to and from an embedded surrealdb database.
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

use surrealdb::opt::IntoQuery;
use surrealqlx::surrql;

/// Query to relate a playlist to its songs.
///
/// Compiles to:
/// ```sql, ignore
/// "RELATE $id->playlist_to_song->(array::complement(array::distinct($songs), $id->playlist_to_song.out))"
/// ```
///
/// Let's break this down:
/// - `RELATE $id->playlist_to_song->(...)` creates a relation between the playlist and a set of songs.
/// - `array::complement(array::distinct($songs), $id->playlist_to_song.out)` ensures that only songs
///   that are not already related to the playlist are added.
/// - `array::distinct($songs)` ensures that the input songs are unique.
/// - `$id->playlist_to_song.out` retrieves the current related songs.
#[must_use]
#[inline]
pub const fn add_songs() -> impl IntoQuery {
    // only songs that aren't already related to the playlist should be added
    surrql!(
        "RELATE $id->playlist_to_song->(array::complement(array::distinct($songs), $id->playlist_to_song.out))"
    )
}

/// Query to read the songs of a playlist
///
/// Compiles to:
/// ```sql, ignore
/// SELECT * FROM $id->playlist_to_song.out
/// ```
///
/// # Example
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use mecomp_storage::db::crud::queries::playlist::read_songs;
/// use surrealdb::opt::IntoQuery;
///
/// let statement = read_songs();
/// assert_eq!(
///     statement.into_query().unwrap(),
///     "SELECT * FROM $id->playlist_to_song.out".into_query().unwrap()
/// );
/// ```
#[must_use]
#[inline]
pub const fn read_songs() -> impl IntoQuery {
    surrql!("SELECT * FROM $id->playlist_to_song.out")
}

/// Query to remove songs from a playlist
///
/// Compiles to:    
/// ```sql, ignore
/// DELETE $id->playlist_to_song WHERE out IN $songs
/// ```
///
/// # Example
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use mecomp_storage::db::crud::queries::playlist::remove_songs;
/// use surrealdb::opt::IntoQuery;
///
/// let statement = remove_songs();
/// assert_eq!(
///     statement.into_query().unwrap(),
///     "DELETE $id->playlist_to_song WHERE out IN $songs".into_query().unwrap()
/// );
/// ```
#[must_use]
#[inline]
pub const fn remove_songs() -> impl IntoQuery {
    surrql!("DELETE $id->playlist_to_song WHERE out IN $songs")
}

/// Query to read a playlist by its name.
///
/// Compiles to:
/// ```sql, ignore
/// SELECT * FROM playlist WHERE name = $name LIMIT 1
/// ```
///
/// # Example
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use mecomp_storage::db::crud::queries::playlist::read_by_name;
/// use surrealdb::opt::IntoQuery;
///
/// let statement = read_by_name();
/// assert_eq!(
///     statement.into_query().unwrap(),
///     "SELECT * FROM playlist WHERE name = $name LIMIT 1".into_query().unwrap()
/// );
/// ```
#[must_use]
#[inline]
pub const fn read_by_name() -> impl IntoQuery {
    surrql!("SELECT * FROM playlist WHERE name = $name LIMIT 1")
}

#[cfg(test)]
mod query_validation_tests {
    use crate::db::queries::validate_query;
    use rstest::rstest;

    use super::*;

    #[rstest]
    #[case::add_songs(
        add_songs(),
        "RELATE $id->playlist_to_song->(array::complement(array::distinct($songs), $id->playlist_to_song.out))"
    )]
    #[case::read_songs(read_songs(), "SELECT * FROM $id->playlist_to_song.out")]
    #[case::remove_songs(remove_songs(), "DELETE $id->playlist_to_song WHERE out IN $songs")]
    #[case::read_by_name(read_by_name(), "SELECT * FROM playlist WHERE name = $name LIMIT 1")]
    fn test_queries(#[case] statement: impl IntoQuery, #[case] expected: &str) {
        validate_query(statement, expected);
    }
}