Skip to content

Latest commit

 

History

History
302 lines (196 loc) · 7.32 KB

README.md

File metadata and controls

302 lines (196 loc) · 7.32 KB
Raw

Firestore Service

FEArmy

Create firestore queries as if you were using a REST api.

Installation

npm install firestore-service

Prerequisites

1 - Create a firestore data base, you can do it here

2 - Get your database credentials. You can find those in Project Overview -> Add firebase to your web app

Note: We strongly recommend you to save the credentials on a .env file and don't upload them to any repository.

Getting Started

Once you have your credentials and the package install you can start using firestore service.

You will need to initialize the service as soon as you can, the code should look something like this:

import firestoreService from 'firestore-service';

const firebaseConfig = {
  apiKey: xxxxxxxxxxxx,
  authDomain: xxxxxxxxxxxx,
  databaseURL: xxxxxxxxxxxx,
  projectId: xxxxxxxxxxxx,
  storageBucket: xxxxxxxxxxxx,
  messagingSenderId: xxxxxxxxxxxx
};

firestoreService.initialize(firebaseConfig);

Response format

Every HTTP method will return a response with the following body.

{
  ok: a boolean -> true: Success, false: Failure
  data: The data you requested,
  status: An HTTP status code, see the code table below,
  statusText: 'OK' or 'Failure',
  request: the actual request (GET, POST, etc.)
}

Supported methods

GET

You can get all the elements from a collection or a specific element if the element's id is specified.

Note: The path will always be collection/id/collection2/id2/.... The "url" will finish with a collection if you want an array of elements or with an id if you want a single one.

E.g.:

const response = await firestoreService.get('regions');

The response will have all the "regions"

const response = await firestoreService.get('regions/32');

The response will have the information about the region with id 32.

Extra query parameters

Firestore service allows you to use certain tools to manipulate your data in the query. For this you should add extra parameters into the function get.

  • Limit

The response will only have 20 "regions"

const response = await firestoreService.get('regions/32', { limit: 20 });
  • Filter

The response will only have users who are older than 22 years old and younger than 35

const response = await firestoreService.get('regions/32', {
  filters: [
    { field: 'age', condition: '<', value: 35 },
    { field: 'age', condition: '>', value: 22 }
  ]
});

Supported condition operators:

  • <
  • <=
  • >
  • >=
  • ==
  • array-contains

Note: If you want to combine == with any of the others you will have to create an index in your db. More info about this here

  • Order By

Allows for ordering the query result by database field and ascending/descending direction. The default orderDirection is ascending

The following query will get regions ordered by age ascending

const response = await firestoreService.get('regions', { orderBy: 'age' });

The following query will get regions ordered by age descending

const response = await firestoreService.get('regions', {
  orderBy: 'age',
  descending: true
});

The following query will get regions ordered by age and name ascending

const response = await firestoreService.get('regions', {
  orderBy: ['age', 'name']
});

Note: If you want to order your query by several fields you will have to create an index in your db,More info about this here

POST

You can create an element by calling POST with the collection's path and the body with the element's data.

E.g.:

const body = {
  firstName: 'New name'
  lastName: 'New last name'
};

firestoreService.post('regions/32/users', body)

The previous request will create a new user under the region with id 32 using the information sent in the body. It will return the created user with its id.

DELETE

You can delete a certain element from a collection by using DELETE with a path to the element.

E.g.:

firestoreService.delete('regions/32/users/1');

The user from the region with id 32 that has id 1 will be deleted. The response will be empty

PATCH

You can update an element by calling PATCH and providing only the fields desired to be updated from an element.

E.g.:

const body = {
  firstName: 'New name2'
};

firestoreService.patch('regions/32/users/1', body);

The user with id 1 that belongs to the region with id 32 will have his name altered but will keep the previous values. The response will contain the updated user

PUT

You can update an element by calling PUT and providing all the fields in an element, providing less fields will make the rest of the values null (except for the id). Providing a different id in the body will result in an error.

E.g.:

const body = {
  id: 1,
  firstName: 'New name3',
  lastName: 'New last name3'
};

firestoreService.put('regions/32/users/1', body);

The user with id 1 that belongs to the region with id 32 will be altered.The response will contain the edited user.

const body = {
  firstName: 'New name3'
};

firestoreService.put('regions/32/users/1', body);

The user with id 1 that belongs to the region with id 32 will be altered and the lastName field will be set to null. The response will contain the edited user.

const body = {
  id: 2,
  firstName: 'New name3',
  lastName: 'New last name3'
};

firestoreService.patch('regions/32/users/1', body);

An error will be thrown because of id mismatch.

Authentications

Firestore service also supports methods to authenticate users. These are not http methods, are functions to be used with the same package.

LOGIN

You can login with an already created user (You can create them in the firebase console)

const email = '[email protected]'
const password = 'xxxxxx'


const response = await firestoreService.login(email, password);

The response will have all the user info.

SIGN UP

You can sign up a new user with the sign up method.

const email = '[email protected]'
const password = 'xxxxxx'


const response = await firestoreService.signUp(email, password);

If the response is succesful, the user will be created and all it's information will be in the response.

UPDATE PROFILE

You can update a user's profile with the following method.

const body = { name: 'example name', phone: 'example phone'}


const response = await firestoreService.updateProfile(body);

If the response is succesful, the user will be updated.

Note: The user should be logged in to perform the update

Supported status codes

OK: 200
CREATED: 201
NO_CONTENT: 204
BAD_REQUEST: 400
UNAUTHORIZED: 401
FORBIDDEN: 403
NOT_FOUND: 404
CONFLICT: 409

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Contributing

Learn how to contribute in the CONTRIBUTING.md file.

About

This project is maintained by Lucas Zibell and it was written by Wolox.

Wolox