Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tylim88/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.
https://github.com/tylim88/firecaller
firebase firebase-functions typescript
Last synced: 21 days ago
JSON representation
🔥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.
- Host: GitHub
- URL: https://github.com/tylim88/firecaller
- Owner: tylim88
- License: mit
- Created: 2022-05-03T02:16:35.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-11-08T08:23:28.000Z (about 2 years ago)
- Last Synced: 2024-05-21T12:08:43.577Z (6 months ago)
- Topics: firebase, firebase-functions, typescript
- Language: TypeScript
- Homepage:
- Size: 664 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://github.com/tylim88/FireCall).
It wraps around Firebase callable functions to provide type safety for you request data and response data with [zod](https://www.npmjs.com/package/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](#usage-with-emulator)
## Why Do You Need This? What Is The Problem FireCall Trying To Solve?
Read [Here](https://github.com/tylim88/FireCall#why-do-you-need-this-what-is-the-problem-firecall-trying-to-solve)
## Installation
```bash
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](https://github.com/colinhacks/zod)!
```ts
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
```ts
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`. |
```ts
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
```ts
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
1. [FirelordJS](https://github.com/tylim88/Firelordjs) - Typescript wrapper for Firestore Web V9
2. [Firelord](https://github.com/tylim88/Firelord) - Typescript wrapper for Firestore Admin
3. [Firelordrn](https://github.com/tylim88/firelordrn) - Typescript wrapper for Firestore React Native
4. [FireLaw](https://github.com/tylim88/firelaw) - Write Firestore security rule with Typescript, utilizing Firelord type engine.