AeroGear JS paging API strawman

strawman-paging.md

Below is a pipe configuration showing the different paging options. Defaults are just suggestions and are up for discussion as much as the rest of it

var pagedPipe = AeroGear.Pipeline({
    name: "pager",
    settings: {
        paged: {String}, // Default is undefined, can also be "headers" or "content" to describe where to find the paging metadata, or undefined/false for no paging
        pageConfig: { // Only required if paged is not undefined
            // which page, header default is "AG-Paging-Offset", content default is "paging.offset"
            offset: {String},
            offsetVal: {Number}, // Default 0 for first page
            
            // items per page, header default is "AG-Paging-Limit", content default is "paging.limit"
            limit: {String},
            limitVal: {Number}, // Default 5 items per page
            
            // total number of items, header default is "AG-Paging-Total", content default is "paging.total"
            total: {String},
            
            // link to next page, default in both cases is undefined
            next: {String},
            
            // link to previous page, default in both cases is undefined
            prev: {String}
        }
    }   
}).pipes.pager;

Getter/Setter methods should be provided for getting and updating the offsetVal and limitVal defaults

var defaultOffset = pagedPipe.getOffsetVal();
pagedPipe.setOffsetVal( defaultOffset + 1 ); // by default the second page would be returned

var defaultLimit = pagedPipe.getLimitVal();
pagedPipe.setLimitVal( defaultLimit + 5 ); // by default, 10 items would be returned per page

read()

By default, a read() against a paged pipe will return the first page based on the default offsetVal and limitVal. We could possible add an option that doesn't effect unpaged pipes but on a paged pipe, it can be used to turn off paging for that read() and get all data

// Get first page
pagedPipe.read({success callback handles data});

// Get all data from paged pipe
pagedPipe.read({
    page: false,
    success: handle the data
});

To avoid code duplication, next, prev, first and last pages can be retrieved by passing an option to the read method of a paged pipe since other than some paging housekeeping, the code would be the same. We can also use that same option as above that was used to get all data from a paged pipe. One question, when requesting prev from first page or next from last page, should it throw an error that needs to be handled or just return and empty data set? I see advantages and disadvantages of both.

// Get next page
pagedPipe.read({
    page: "next",
    success: handle the data
});

// Get previous page
pagedPipe.read({
    page: "prev",
    success: handle the data
});

// Get first page
pagedPipe.read({
    page: "first",
    success: handle the data
});

// Get last page
pagedPipe.read({
    page: "last",
    success: handle the data
});