This package aims to assist the firebase function export. and allows a flexible mechanism to use different options for https service functions (API)
yarn add @dev-vortex/fireback
or
npm install @dev-vortex/fireback
The app neds an initializatiion moment. This can be achieved in isolation through the exported method initApp
or directly by using the exported method exportFunctions
.
Note - This process is a requirement from Firebase you can see it here: https://firebase.google.com/docs/reference/node/firebase#initializeapp
initApp
will accept as paremeter the configuration objec and will return the admin firebase application or a boolean value. If an error occurr it will throw an error.
exportFunctions
will provide all prepared functions and it will try to initialize the app with the proviided configuuratiion object.
There are to relevant moments where we need to use the provided API. These moments are the entry point (output/export of fuunctiions) and every type we need to create a function.
To allow a clear and simple way to organise and define functions and function groups, the service will use the file structure, together with file naming convention.
By default the system will look for and into a folder named api
that must exist right next to the index
entripoint.
Structure example
.
|
+ - functions
|
+ - index.ts
+ - api
|
+ - group_name_1
. |
. + - group-name|1.1
. |
. + - function_a_name.func.ts
. + - function-b-name.func.ts
.
+ - group.name.2
. |
. + - function.c.name.func.ts
. + - function_with-name.d|version.func.ts
...
The service will implement the following rules:
- ANY folder will be seen as a function group
- ANY file will be seen as a function
- Group and Function names will be normalized into
camelCase
- Group and Function names with dot (
.
) or pipe (|
) characters, will be converted to underscore (_
)
Given the srtucture above, we will end with the following functions:
groupName1-groupName_1_1-functionAName
groupName1-groupName_1_1-functionBName
groupName2-function_c_name
groupName2-functionWithName_d_version
In your function project we will need to export all the developed functions so firebase can expose them to your app(s).
Here we will make use of the exportFunctions
method. This will be responsible to export all the functions that were registered by your project.
import { initApp } from '@dev-vortex/fireback'
import { firebaseConfigObject } from './firebaseConfig' // your configuration
initApp(firebaseConfigObject)
or
import { exportFunctions } from '@dev-vortex/fireback'
exports = module.exports = exportFunctions({
...
firebaseServiceConfig: firebaseConfigObject,
})
Info - If needed, it is possible to change functions location as well as adding a top group to the function by specifying it in the parameter option object
base: string
- If provided, this will be used to set the working foolder. Otherwise, the service will assume the same location as the file that is calling the method (defaults to __dirname
).
folder: string
- If provided (relative path to the api file structure), the service will use it to fetch the function definition files. (default: ./api
)
extensions: string[]
- Function definition file extension list. (default: [.func.ts
, .func.js
]). Thisi will be used by the service to assume just the files that comply with the specified extensions
options
- Options object to define function export settings
functionGroupPath: string
- Main group name to add to the function (default: '' [empty])
firebaseServiceConfig
- Configuration to initialize firebase app same as in initApp
. (see Configuration note)
When defining a function we will need to pick what type of function and depending on that decision we may also need to provide a service to it.
At this point any of the functioon creation methods will register the function to be exported at the Entry/Export moment.
This is the most close function to Firebase API and it will create a function that can be used to any type of function that firebase may provide. It is responsible to localize the function in a specific location from any that is available by firebase locations
import { callableFunction } from '@dev-vortex/fireback'
export default callableFunction({
functionRegion: 'europe-west1',
})
This kind of function allows us to setup a function (piece of code) that will run at a specific location on a specific time (within a specific timezone).
import { cronFunction } from '@dev-vortex/fireback'
export default cronFunction(
'5 11 * * *',
(context) => {
...
},
{
functionRegion: 'europe-west1',
functionTimeZone: 'Europe/Stockholm',
}
)
This type of function will allow us to expose HTTPS services like REST APIs. Here you can use any service that respects the (request, response) service signature
import { httpsFunction } from '@dev-vortex/fireback'
// 1. Import your https service (eg: Express, Fastify, Koa, Hapi, TypeGraphQL, Moleculer)
// 2. Prepare all the necessary endpoints/routes, security and logic withing the httpsService
export default httpsFunction(
httpService,
{ functionRegion: 'europe-west1' }
)