wip

Author: manuelpelloni

benzina/src/array.rs

@@ -1,7 +1,7 @@
 use std::fmt::Debug;
 
 use diesel::{
-    deserialize::{FromSql, FromSqlRow},
+    deserialize::FromSql,
     expression::{AppearsOnTable, Expression, SelectableExpression},
     pg::{Pg, PgValue},
     query_builder::{AstPass, QueryFragment, QueryId},
@@ -12,7 +12,67 @@ use diesel::{
 
 use crate::{U15, U31, U63, error::InvalidArray};
 
-#[derive(Debug, FromSqlRow)]
+/// Since postgres ignores the array dimension (if specified) diesel implements [`FromSql`] for `Vec<T>` and [`ToSql`] for `Vec<T>`/`&[T]`.
+/// In addition postgres also consider array items as always nullable.
+/// This makes hard to deal with real arrays, that have a predetermined length, and an omogeneous nullability.
+/// This type checks at runtime the array length and the NON nullability of its items, to be completely safe you should also add some `CHECK` constraints to your array fields.
+///
+/// This type is not intended to be used directly in the model but rather to be
+/// used with diesel [`serialize_as`] and [`deserialize_as`].
+///
+/// ```
+/// use benzina::{Array, U31};
+/// use diesel::{Insertable, Queryable};
+/// use serde::{Deserialize, Serialize};
+///
+/// #[derive(Debug, Queryable)]
+/// #[diesel(table_name = users, check_for_backend(diesel::pg::Pg))]
+/// struct User {
+///     id: U31,
+///     first_name: String,
+///     last_name: String,
+///     #[diesel(deserialize_as = Array<bool, 5>)]
+///     flags: UserFlags,
+/// }
+///
+/// #[derive(Debug, Insertable)]
+/// #[diesel(table_name = users)]
+/// struct NewUser {
+///     first_name: String,
+///     last_name: String,
+///     #[diesel(serialize_as = Array<bool, 5>)]
+///     flags: UserFlags,
+/// }
+///
+/// #[derive(Debug, Serialize, Deserialize)]
+/// struct UserFlags([5; bool]);
+///
+/// // needed by deserialize_as
+/// impl From<benzina::Array<bool, 5>> for UserFlags  {
+///    fn from(value: benzina::Array<bool, 5>) -> Self {
+///        Self::new(value.get())
+///    }
+/// }
+///
+/// // needed by serialize_as
+/// impl From<UserFlags> for benzina::Array<bool, 5> {
+///    fn from(value: UserFlags) -> Self {
+///        Self::new(value.0)
+///    }
+/// }
+///
+/// diesel::table! {
+///     users (id) {
+///         id -> Int4,
+///         first_name -> Text,
+///         last_name -> Text,
+///         flags -> Array<Nullable<Bool>>,
+///     }
+/// }
+///
+/// [`serialize_as`]: diesel::prelude::Insertable#optional-field-attributes
+/// [`deserialize_as`]: diesel::prelude::Queryable#deserialize_as-attribute
+#[derive(Debug)]
 pub struct Array<T, const N: usize>([T; N]);
 impl<T, const N: usize> Array<T, N> {
     pub fn new(values: [T; N]) -> Self {
@@ -24,7 +84,7 @@ impl<T, const N: usize> Array<T, N> {
     }
 }
 
-#[derive(Debug, FromSqlRow)]
+#[derive(Debug)]
 pub struct ArrayWithNullableItems<T, const N: usize>([Option<T>; N]);
 impl<T, const N: usize> ArrayWithNullableItems<T, N> {
     pub fn new(values: [Option<T>; N]) -> Self {