npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mobidonia-firebase-paginator

v1.1.1

Published

Pagination for Firebase

Downloads

5

Readme

FirebasePaginator

FirebasePaginator is a JavaScript utility for Node.js and the browser that enables simple, declarative pagination for your Firebase collections. It's been developed for Firebase 3.0, but it should work for Firebase 2.0 projects as well.

Dependencies

FirebasePaginator relies on the Promise object. Promise support is great for modern versions of Chrome, Firefox, Edge, Opera and Safari. Internet Explorer gets left out. Sorry IE, but even Microsoft is sick of you. You're dying. And attempting to support you would only prolong the misery.

FirebasePaginator uses the Axios library for Node.js and XMLHttpRequest in the browser.

In summary: Node.js requires Promise and Axios; the browser requires Promise and XMLHttpRequest.

Install

  • NPM: npm install --save firebase-paginator
  • Bower: bower install --save firebase-paginator

Test

  • npm install
  • npm test

Usage

If you're in Node.js, you'll need to do something like var FirebasePaginator = require('firebase-paginator').

If you're in the browser, you'll have access to FirebasePaginator on the window object like so: var FirebasePaginator = window.FirebasePaginator;

Once you have your FirebasePaginator object, the rest is isomorphic JavaScript. Just pass in a Firebase ref and some options:

pageSize: any integer greater than zero, defaults to 10

finite: defaults to false

auth: optional auth token for secure collections

retainLastPage: applies to infinite pagination only; prevents a short last page from resetting the list; see Finite vs Infinite Pagination

var options = {
  pageSize: 15,
  finite: true,
  auth: 'MyAuthTokenForSecurityPurposes',
  retainLastPage: false
};
var paginator = new FirebasePaginator(ref, options);

Functions

FirebasePaginator.prototype.listen(callback)

Listens to all events

Useful for proxying events or just debugging

var paginator = new FirebasePaginator(ref);
var itemsList = [];

paginator.listen(function (eventName, eventPayload) {
  console(`Fired ${eventName} with the following payload: `, eventPayload);
});

FirebasePaginator.prototype.on(event, callback)

Attaches a callback to an event

var paginator = new FirebasePaginator(ref);
var itemsList = [];
var handler = function() {
  collection = paginator.collection;
};

paginator.on('value', handler);

FirebasePaginator.prototype.off(event, callback)

Detaches a callback from an event

var paginator = new FirebasePaginator(ref);
var itemsList = [];
var handler = function() {
  collection = paginator.collection;
};

paginator.off('value', handler);

FirebasePaginator.prototype.once(event, callback) -> returns promise

Calls a callback exactly once for an event

var paginator = new FirebasePaginator(ref);
var itemsList = [];
var handler = function() {
  collection = paginator.collection;
};

// Callback pattern
paginator.once('value', handler);

// Promise pattern
paginator.once('value').then(handler);

FirebasePaginator.prototype.reset() -> returns promise

Resets pagination

Infinite: jumps to end of collection

Finite: Refreshes keys list and jumps to page 1

var paginator = new FirebasePaginator(ref);
paginator.reset()
  .then(function() {
    console.log('list has been reset');
  });

FirebasePaginator.prototype.previous() -> returns promise

Pages backward

var paginator = new FirebasePaginator(ref);
paginator.previous()
  .then(function() {
    console.log('paginated backward');
  });

FirebasePaginator.prototype.next() -> returns promise

Pages forward

var paginator = new FirebasePaginator(ref);
paginator.next()
  .then(function() {
    console.log('paginated forward');
  });

FirebasePaginator.prototype.goToPage() -> returns promise

Jumps to any page

Accepts page numbers from 1 to the pageCount

Available for finite pagination only

var paginator = new FirebasePaginator(ref);
paginator.goToPage(3)
  .then(function() {
    console.log('paginated to page 3');
  });

Events

value

The value event fires after every change in data. FirebasePaginator listens to the Firebase value event, manipulates the data a bit and then fires its own value event.

isLastPage

isLastPage fires just after the value event if FirebasePaginator has reached the top of the list.

ready

FirebasePaginator fires its ready event once the first page is loaded.

reset, next, previous

The reset, next and previous events fire after each of the corresponding functions is complete and the new data is loaded.

Finite vs Infinite Pagination

There are two ways to paginate Firebase data: finite and infinite paginations.

Let's assume that pageSize is 10 and we have records 1 through 100. Also note that all Firebase pagination occurs from the bottom of the collection.

Infinite Pagination

Infinite pagination pulls the last 11 records of the collection, saves the 90th record's key as a cursor and adds records 91 through 100 to the collection.

Infinite pagination steps backward by pulling another 11 records ending at the cursor (a.k.a. the 90th record's key). So paging back once will display records 81 to 90 with record 80's key as the new cursor. Page back again and you're at records 71 to 80 and so forth.

By default, inifinite pagination resets its last page if you overrun the beginning of a list. For example, if you had 100 items and a pageSize of 30, paging backwards would return records 71-100, 41-70, 11-40 and 1-30. Notice that the last page is still 30 records. The default behavior is to reset the collection to the beginning of the list and return a full page if possible. The set retainLastPage: true in your options to return records 1-10 instead.

Pros:

  • Scales forever
  • Users can page forward to discover new records as they're added to the collection
  • If a user is on the first page, new records will simply appear as they are added

Cons:

  • Must page forward and backward sequentially. Can't skip pages.
  • No context for how many pages exist and where the user is in the list
  • If a user is on the first page, new records will simply appear as they are added

Finite Pagination

Finite pagination makes a single "shallow" REST query to pull all of the collection's keys. See the docs on how this is done.

Once FirebasePaginator has all of the keys, it sorts them and finds the page endpoints. So if we have 100 records with a pageSize of 10, the page endpoints will be the keys for records 10, 20, 30, 40, 50... 100.

Pros:

  • Users have context for where they are in the collection.
  • Users can skip pages.

Cons:

  • Beware of scaling issues. Consider archiving records to Google Cloud Datastore if the collection grows too large.
  • Must call paginator.reset() to capture new records the may be added