Crate mongodb_cursor_pagination

source ·
Expand description

MongoDB Cursor Pagination

Crate Docs Build Status MIT licensed

Documentation
Examples

This package provides a cursor based pagination using the mongodb driver. Essentially instead of page based pagination you receive cursors to both the start and end of the result set so that you can ensure you get the next item, even if the data changes in between requests. That said, it also provides regular ole’ page based pagination as well. If your options include skip and limit parameters then you’ll do the page based. If you leave skip off or send a cursor, then it will use that instead (and ignore the skip parameter.)

It’s based on the node.js module but written in Rust. You can read more about the concept on their blog post.

So far it only supports count and find. Search and aggregation will come when needed.

Usage:

The usage is a bit different than the node version. See the examples for more details and a working example.

use mongodb::{options::FindOptions, Client};
use mongodb_cursor_pagination::{CursorDirections, FindResult, PaginatedCursor};
use bson::doc;
use serde::Deserialize;

// Note that your data structure must derive Deserialize
#[derive(Debug, Deserialize, PartialEq, Clone)]
pub struct MyFruit {
    name: String,
    how_many: i32,
}

#[tokio::main]
async fn main() {
    let client = Client::with_uri_str("mongodb://localhost:27017/")
        .await
        .expect("Failed to initialize client.");
    let db = client.database("mongodb_cursor_pagination");

    let docs = vec![
        doc! { "name": "Apple", "how_many": 5 },
        doc! { "name": "Orange", "how_many": 3 },
        doc! { "name": "Blueberry", "how_many": 25 },
        doc! { "name": "Bananas", "how_many": 8 },
        doc! { "name": "Grapes", "how_many": 12 },
    ];

    db.collection("myfruits")
        .insert_many(docs, None)
        .await
        .expect("Unable to insert data");

    // query page 1, 2 at a time
    let options = FindOptions::builder()
            .limit(2)
            .sort(doc! { "name": 1 })
            .build();

    let mut find_results: FindResult<MyFruit> = PaginatedCursor::new(Some(options.clone()), None, None)
        .find(&db.collection("myfruits"), None)
        .await
        .expect("Unable to find data");
    println!("First page: {:?}", find_results);

    // get the second page
    let mut cursor = find_results.page_info.next_cursor;
    find_results = PaginatedCursor::new(Some(options), cursor, Some(CursorDirections::Next))
        .find(&db.collection("myfruits"), None)
        .await
        .expect("Unable to find data");
    println!("Second page: {:?}", find_results);
}

Response

The response FindResult<T> contains page info, cursors and edges (cursors for all of the items in the response).

pub struct PageInfo {
    pub has_next_page: bool,
    pub has_previous_page: bool,
    pub start_cursor: Option<String>,
    pub next_cursor: Option<String>,
}

pub struct Edge {
    pub cursor: String,
}

pub struct FindResult<T> {
    pub page_info: PageInfo,
    pub edges: Vec<Edge>,
    pub total_count: i64,
    pub items: Vec<T>,
}

Features

It has support for graphql (using juniper) if you enable the graphql flag. You can use it by just including the PageInfo into your code.

ⓘ
use mongodb_cursor_pagination::{PageInfo, Edge};

#[derive(Serialize, Deserialize)]
struct MyDataConnection {
    page_info: PageInfo,
    edges: Vec<Edge>,
    data: Vec<MyData>,
    total_count: i64,
}

[juniper::object]
impl MyDataConnection {
    fn page_info(&self) -> &PageInfo {
        self.page_info
    }

    fn edges(&self) -> &Vec<Edge> {
        &self.edges
    }
}

Modules

Structs

  • Edge
    Edges are the cursors on all of the items in the return
  • FindResult
    The result of a find method with the items, edges, pagination info, and total count of objects
  • PageInfo
    Provides details about if there are more pages and the cursor to the start of the list and end
  • PaginatedCursor
    The main entry point for finding documents

Enums

  • CursorDirections
    The direction of the list, ie. you are sending a cursor for the next or previous items. Defaults to Next

Functions