# @mqschwanda/firebase-containers
> a collection of higher-order components that do firebase data fetching before rendering their corresponding sub-component.
Latest version **0.0.22** (published 2018-09-12) · MIT license · 0 weekly downloads
## Install
```sh
npm install @mqschwanda/firebase-containers
pnpm add @mqschwanda/firebase-containers
yarn add @mqschwanda/firebase-containers
bun add @mqschwanda/firebase-containers
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.0.22 |
| Published | 2018-09-12 |
| First published | 2018-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 47.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Maintainers | mqschwanda |
| Keywords | firebase, firestore, database, react, container, higher-order component, hoc |
## Links
- npm: https://www.npmjs.com/package/@mqschwanda/firebase-containers
- Repository: https://github.com/mqschwanda/node-monorepo
- Homepage: https://github.com/mqschwanda/node-monorepo/tree/master/packages/firebase-containers/README.md
- Issues: https://github.com/mqschwanda/node-monorepo/issues
- npm.io page: https://npm.io/package/@mqschwanda/firebase-containers
## Dependencies (1)
- [@mqschwanda/compose](https://npm.io/package/@mqschwanda/compose.md) ^0.0.1
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 0.0.22 (latest) — 2018-09-12
- 0.0.21 — 2018-09-10
- 0.0.20 — 2018-09-10
- 0.0.19 — 2018-09-10
- 0.0.18 — 2018-09-10
- 0.0.17 — 2018-08-22
- 0.0.16 — 2018-08-21
- 0.0.15 — 2018-08-21
- 0.0.14 — 2018-08-17
- 0.0.13 — 2018-08-17
- 0.0.12 — 2018-08-17
- 0.0.11 — 2018-08-17
- 0.0.10 — 2018-08-16
- 0.0.9 — 2018-08-15
- 0.0.8 — 2018-08-09
- … 6 more at https://npm.io/package/@mqschwanda/firebase-containers/versions
## README
# firebase-containers
[](https://travis-ci.org/mqschwanda/node-monorepo)
[](https://www.npmjs.com/package/@mqschwanda/firebase-containers)
[](https://github.com/mqschwanda/node-monorepo/tree/master/packages/firebase-containers)
[](https://github.com/mqschwanda/node-monorepo/tree/master/packages/firebase-containers)
Firebase containers are a collection of [higher-order components](https://reactjs.org/docs/higher-order-components.html) that do firebase data fetching before rendering their corresponding sub-component.
## Table of contents
- [Todo](#todo)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [API](#api)
- [firestoreContainer](#firestorecontainer)
- [databaseContainer](#databasecontainer)
- [userContainer](#usercontainer)
## Todo
- [ ] add userContainer docs & examples
- [ ] finish writing tests
## Getting Started
### Installation
**Important: Make sure you have `react` and `firebase` packages already installed or you will also need to install these alongside `@mqschwanda/firebase-containers`.**
Using yarn, our preferred method:
```bash
$ yarn add @mqschwanda/firebase-containers
```
Using npm:
```bash
$ npm install @mqschwanda/firebase-containers
```
Using cdn:
```html
```
## API
### firestoreContainer
The `firestoreContainer` hooks into the `onSnapshot` listener to get realtime updates with Cloud Firestore. The initial call creates a document snapshot immediately with the current data of the single document. Then, each time the contents change, another call updates the document snapshot. The listener triggers a React.Component's `this.setState` and re-renders passing the updated snapshot through to the sub-component.
Example of the firebase `onSnapshot` listener we are wrapping:
```jsx
import firebase from 'firebase';
const SF = firebase.database().collection('cities').doc('SF');
SF.onSnapshot((snapshot) => {
console.log(snapshot.data());
});
```
You can read more about the `onSnapshot` Firebase API we are wrapping here.
`firestoreContainer` has the following signature:
```jsx
/**
* @name firestoreContainer
* @type {Function}
* @description This container takes a firestore query and injects the snapshot
* into the sub-component.
* @since 0.0.15
* @param {firebase.firestore.Query} query firestore Query which we can read or listen to
* @param {Object} options options object
* @return {Function} composable function that accepts react components as params
* @returns container(Component, Loading)
*/
const container = firestoreContainer(query[, options]);
// we are currying the arguments so the above container is the same as...
// const container = (Component[, Loading]) =>
// firestoreContainer(query[, options])(Component[, Loading])
```
#### arguments
- `query` (required)
```jsx
/**
* @description A firestore Query which you can read or listen to
* @type {firebase.firestore.Query}
* @see {@link https://firebase.google.com/docs/reference/js/firebase.firestore.Query}
*/
const query = firebase.database().collection('cities').doc('SF');
```
- `options` (optional)
```jsx
const options = {
/**
* @name mapData
* @type {Function}
* @description access the snapshot to map the prop injected into the sub-component
* @since 0.0.1
* @param {[firebase.firestore.QuerySnapshot, firebase.firestore.QueryDocumentSnapshot]} firebase snapshot
* @see {@link https://firebase.google.com/docs/reference/js/firebase.firestore.QuerySnapshot}
* @see {@link https://firebase.google.com/docs/reference/js/firebase.firestore.QueryDocumentSnapshotshot}
* @return {Object} prop that is merged into sub-component's props
* @default (snapshot) => ({ snapshot })
*/
mapData: (snapshot) => ({ snapshot }),
// or, lets say you want to map the data to a different name...
// mapData: (labledSnapshot) => ({ labledSnapshot }),
/**
* @name once
* @type {Boolean}
* @description if you only want the first value and dont want reactive updates
* @since 0.0.11
* @default false
*/
once: false,
};
```
- Component (required)
```jsx
/**
* @name Component
* @description sub-component we are injecting the snapshot into
* @type {[React.Component, function]}
* @since 0.0.1
* @param {Object} props react props
* @returns {React.Element}
*/
const Component = (props) => (
{JSON.stringify(props.snapshot.data())}
);
```
- Loading (optional)
```jsx
/**
* @name Loading
* @description component displayed while loading the query snapshot
* @type {[React.Component, function]}
* @since 0.0.1
* @param {Object} props react props
* @returns {React.Element}
* @default (props) => loading...
*/
const Loading = (props) => loading...
```
#### Examples
- query single document
```jsx
// ./examples/firestoreContaier/query-single-document.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { firestoreContainer } from '@mqschwanda/firebase-containers';
const query = firebase.firestore().collection('cities').doc('SF');
const container = firestoreContainer(query);
const ComponentWithData = container((props) =>
{JSON.stringify(props.snapshot.data())}
);
```
- query multiple documents
```jsx
// ./examples/firestoreContaier/query-multiple-documents.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { firestoreContainer } from '@mqschwanda/firebase-containers';
const query = firebase.firestore().collection('cities').where('state == CA');
const container = firestoreContainer(query);
const ComponentWithData = container((props) => props.snapshot.docs.map(doc =>
doc.exists &&
{JSON.stringify(doc.data())}
);
```
- query composition
```jsx
// ./examples/firestoreContaier/query-composition.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { firestoreContainer, compose } from '@mqschwanda/firebase-containers';
const Cities = firebase.firestore().collection('cities');
const SF = Cities.doc('SF');
const LA = Cities.doc('LA');
// use compose to apply multiple higher order components
const container = compose(
firestoreContainer(SF, { mapData: (sfSnapshot) => ({ sfSnapshot }) }),
firestoreContainer(LA, { mapData: (laSnapshot) => ({ laSnapshot }) }),
);
const ComponentWithData = container((props) =>
{JSON.stringify(props.sfSnapshot.data())}
{JSON.stringify(props.laSnapshot.data())}
);
```
### databaseContainer
The `databaseContainer` hooks into the `.on('value')` listener to get realtime updates with Firebase's database. Firebase data is retrieved by attaching an asynchronous listener to a firebase.database.Reference. The listener triggers a React.Component's `this.setState` and re-renders passing the updated snapshot through to the sub-component.
**Important:** The value event is called every time data is changed at the specified database reference, including changes to children. To limit the size of your snapshots, attach only at the lowest level needed for watching changes. For example, attaching a listener to the root of your database is not recommended.
Example of the firebase `.on('value')` listener we are wrapping:
```jsx
import firebase from 'firebase';
const SF = firebase.database().ref('cities/SF');
SF.on('value', (snapshot) => {
console.log(snapshot.val());
});
```
You can read more about the `.on('value')` Firebase API we are wrapping here.
`databaseContainer` has the following signature:
```jsx
/**
* @name databaseContainer
* @type {Function}
* @description This container listens to a database reference and injects the
* snapshot into the sub-component.
* @since 0.0.15
* @param {firebase.database.Reference} reference database reference which we can read or listen to
* @see {@link https://firebase.google.com/docs/reference/js/firebase.database.Reference}
* @param {Object} options options object
* @return {Function} composable function that accepts react components as params
* @returns container(Component, Loading)
*/
const container = databaseContainer(query[, options]);
// we are currying the arguments so the above container is the same as...
// const container = (Component[, Loading]) =>
// databaseContainer(query[, options])(Component[, Loading])
```
#### arguments
- `reference` (required)
```jsx
/**
* @description database reference which we can read or listen to
* @param {firebase.database.Reference}
* @see {@link https://firebase.google.com/docs/reference/js/firebase.database.Reference}
*/
const reference = firebase.database().ref('cities/SF');
```
- `options` (optional)
```jsx
const options = {
/**
* @name mapData
* @type {Function}
* @description access the snapshot to map the prop injected into the sub-component
* @since 0.0.1
* @param {firebase.database.DataSnapshot} snapshot database snapshot
* @see {@link https://firebase.google.com/docs/reference/js/firebase.database.DataSnapshot}
* @return {Object} prop that is merged into sub-component's props
* @default (snapshot) => ({ snapshot })
*/
mapData: (snapshot) => ({ snapshot }),
// or, lets say you want to map the data to a different name...
// mapData: (labledSnapshot) => ({ labledSnapshot }),
/**
* @name once
* @type {Boolean}
* @description if you only want the first value and dont want reactive updates
* @since 0.0.11
* @default false
*/
once: false,
};
```
- `Component` (required)
```jsx
/**
* @name Component
* @description sub-component we are injecting the snapshot into
* @type {[React.Component, function]}
* @since 0.0.1
* @param {Object} props react props
* @returns {React.Element}
*/
const Component = (props) => (
{JSON.stringify(props.snapshot.data())}
);
```
- `Loading` (optional)
```jsx
/**
* @name Loading
* @description component displayed while loading the query snapshot
* @type {[React.Component, function]}
* @since 0.0.1
* @param {Object} props react props
* @returns {React.Element}
* @default (props) => loading...
*/
const Loading = (props) => loading...
```
#### Examples
- reference single document
```jsx
// ./examples/databaseContainer/reference-single-document.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { databaseContainer } from '@mqschwanda/firebase-containers';
const reference = firebase.database().ref('cities/SF');
const container = databaseContainer(reference);
const ComponentWithData = container((props) =>
{JSON.stringify(props.snapshot.val())}
);
```
- reference multiple documents
```jsx
// ./examples/databaseContainer/reference-multiple-documents.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { databaseContainer } from '@mqschwanda/firebase-containers';
const reference = firebase.database().ref('cities');
/**
* Firebase refs do not return a mappable array of documents that we can easily
* use with react. Instead we need to map the data ourselves by iterating
* through each document.
*/
const mapData = (snapshot) => {
const docs = [];
snapshot.forEach(docs.push);
// inject docs array alongside the original snapshot
return { docs, snapshot };
}
const container = databaseContainer(reference, { mapData });
const ComponentWithData = container((props) => props.docs.map(doc =>
doc.exists &&
{JSON.stringify(doc.val())}
);
```
- reference composition
```jsx
// ./examples/databaseContainer/reference-composition.js
import React from 'react'; // peer dependency
import firebase from 'firebase'; // peer dependency
import { databaseContainer, compose } from '@mqschwanda/firebase-containers';
const db = firebase.database();
const SF = db.ref('cities/SF');
const LA = db.ref('cities/LA');
// use compose to apply multiple higher order components
const container = compose(
databaseContainer(SF, { mapData: (sfSnapshot) => ({ sfSnapshot }) }),
databaseContainer(LA, { mapData: (laSnapshot) => ({ laSnapshot }) }),
);
const ComponentWithData = container((props) =>
{JSON.stringify(props.sfSnapshot.val())}
{JSON.stringify(props.laSnapshot.val())}
);
```
### userContainer
docs coming soon...
---
_Source: https://npm.io/package/@mqschwanda/firebase-containers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._