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'

export const updateUserSchema = {
	//request data schema
	req: z.object({
		name: z.string(),
		age: z.number(),
		address: z.string(),
	}),
	// response data schema
	res: z.undefined(),
	// function name
	name: 'updateUser',
}

export const getUserSchema = {
	res: z.string(), // userId
	res: 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'

export const app = initializeApp(yourConfig) // must initialize app before using firecaller

const funRef = getFunctions(app)

// now create the specific callable
export const updateUser = callable(updateUserSchema) // or callable(updateUserSchema, funRef)
export const getUser = 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 } = res
	if (code === 'ok') {
		const data = 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'

const app = initializeApp({ projectId: `### YOUR_PROJECT_ID` })
const functions = getFunctions(app)

connectFunctionsEmulator(functions, 'localhost', f.emulators.functions.port)

const schema = {
	req: z.string(),
	res: z.string(),
	name: 'hello',
}

const helloCallable = callable(schema, functions)

describe('test callable', () => {
	it('success', async () => {
		const result = await helloCallable('hello')

		expect(result.code).toBe('ok')
		expect(result.data).toEqual('hello')
	})

	it('invalid arguments', async () => {
		// @ts-expect-error
		const result = await helloCallable(123) // wrong input type

		expect(result.code).toBe('functions/invalid-argument')
		expect(result.message).toEqual('invalid-argument')
	})
})

Related Projects

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

tylim88/FireCaller