FireCaller 烈火呼

🔥 Write callable functions systematically like a Firelord. No more chaotic error handling, no more unsafe endpoint data type, no more messy validation. Be the Master of Fire you always wanted to be.

FireCaller validate response and handle error from FireCall.

It wraps around Firebase callable functions to provide type safety for you request data and response data with zod.

Do not use this library if you are not using FireCall.

FireCaller is a library for Web, FireCall is for Nodejs.

Usable with Emulator

Why Do You Need This? What Is The Problem FireCall Trying To Solve?

Read Here

Installation

npm i firecaller firebase zod

and of course you need typescript.

Create Schema With Zod

Normally this file is created on backend and share to frontend.

Tips: You can also use these schemas to validate your form, learn more at zod!

import{z}from'zod'exportconstupdateUserSchema={//request data schemareq: z.object({name: z.string(),age: z.number(),address: z.string(),}),// response data schemares: z.undefined(),// function namename: 'updateUser',}exportconstgetUserSchema={res: z.string(),// userIdres: z.object({name: z.string(),age: z.number(),}),name: 'getUser',}

Create Callable Functions

import{initializeApp}from'firebase/app'import{callable}from'firecaller'import{updateUserSchema,getUserSchema}from'./someFile'exportconstapp=initializeApp(yourConfig)// must initialize app before using firecallerconstfunRef=getFunctions(app)// now create the specific callableexportconstupdateUser=callable(updateUserSchema)// or callable(updateUserSchema, funRef)exportconstgetUser=callable(getUserSchema)// or callable(getUserSchema, funRef)

Calling

FireCaller never throw, all errors are caught and returned as object. We choose this pattern because it is impossible to type-safe rejected promise.

By checking the value of the code, you know how to deal with them:

code	meaning
ok	success, you can access the data value
schema-out-of-sync	Incorrect response data shape, your schema is out of sync, you can access the message
'functions/cancelled', 'functions/unknown', 'functions/invalid-argument', 'functions/deadline-exceeded', 'functions/not-found', 'functions/already-exists', 'functions/permission-denied', 'functions/resource-exhausted', 'functions/failed-precondition', 'functions/aborted', 'functions/out-of-range', 'functions/unimplemented', 'functions/internal', 'functions/unavailable', 'functions/data-loss', 'functions/unauthenticated'	the error source is FireCall in NodeJS, you can access the message.

import{updateUser,getUser}from'./someOtherFile'const{ name, age, address }=someFormData()updateUser(// input type depends on schema.req{ name, age, address }// { name: string, age: number, address: string }).then(res=>{const{ code }=resif(code==='ok'){constdata=res.data// data type depends on what you define in schema.res}else{const{ code, message }=res// message is string}})

Usage With Emulator

import{initializeApp}from'firebase/app'import{getFunctions,connectFunctionsEmulator}from'firebase/functions'import{callable}from'firecaller'import{z}from'zod'constapp=initializeApp({projectId: `### YOUR_PROJECT_ID`})constfunctions=getFunctions(app)connectFunctionsEmulator(functions,'localhost',f.emulators.functions.port)constschema={req: z.string(),res: z.string(),name: 'hello',}consthelloCallable=callable(schema,functions)describe('test callable',()=>{it('success',async()=>{constresult=awaithelloCallable('hello')expect(result.code).toBe('ok')expect(result.data).toEqual('hello')})it('invalid arguments',async()=>{// @ts-expect-errorconstresult=awaithelloCallable(123)// wrong input typeexpect(result.code).toBe('functions/invalid-argument')expect(result.message).toEqual('invalid-argument')})})

Related Projects

1. FirelordJS - Typescript wrapper for Firestore Web V9
2. Firelord - Typescript wrapper for Firestore Admin
3. Firelordrn - Typescript wrapper for Firestore React Native
4. FireLaw - Write Firestore security rule with Typescript, utilizing Firelord type engine.