@1amageek/ballcap-admin v1.3.0

ballcap for TypeScript

Ballcap is a database schema design framework for Cloud Firestore. This repository supports the WEB and Admin.

Why Ballcap

Cloud Firestore is a great schema-less and flexible database that can handle data. However, its flexibility can create many bugs in development. Ballcap can assign schemas to Cloud Firestore to visualize data structures. This plays a very important role when developing as a team.

export class User extends Doc {
	@Field name?: string
	@Field thumbnailImage?: File
	@SubCollection items: Collection<Item> = new Collection()
}

Installation

Web

npm add @1amageek/ballcap

Admin(node.js)

npm add @1amageek/ballcap-admin

Get Started

• Expo
• React

Expo

Create your first project

expo init new-project
cd my-new-project
npm add firebase @1amageek/ballcap

Edit tsconfig.json

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "commonjs",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "lib": ["dom", "esnext"],
    "jsx": "react-native",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true
  }
}

Firebase and Ballcap initialize

import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import * as firebase from 'firebase'
import '@firebase/firestore'
import * as Ballcap from '@1amageek/ballcap'

const config = { ... }  // apiKey, authDomain, etc. (see above)
const app = firebase.initializeApp(config)
Ballcap.initialize(app.firestore())

React

Create your first project

npx create-react-app my-new-project
cd my-new-project
npm add firebase @1amageek/ballcap ts-loader
react-scripts eject

Edit webpack.config.js

    
    // Replace module
    module: {
      strictExportPresence: true,
      rules: [
        { parser: { requireEnsure: false } },
        {
          oneOf: [
            {
              test: /\.(js|mjs|jsx|ts|tsx)$/,
              include: paths.appSrc,
              loader: require.resolve('ts-loader')
            }
          ],
        },
      ],
    },

Edit tsconfig.json

{
  "compilerOptions": {
    "target": "es2015",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "experimentalDecorators": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react"
  },
  "include": [
    "src"
  ]
}

Usage

Initialize

To use Ballcap, you need to initialize it.

Ballcap.initialize(app.firestore())

RootReference

Considering the extensibility of DB, it is recommended to provide a method of version control.

Ballcap.initialize(app.firestore(), app.firestore().collection("version").doc("1"))

CRUD

Document

// autoID
const user: User = new User()

// with ID
const user: User = new User("ID")

// with DocumentReference
const user: User = new User(firestore.doc("a/a"))

// save
await user.save()

// update
await user.upate()

// delete
await user.delete()

Batch

const user: User = new User()
const batch: Batch = new Batch()

batch.save(user)
await batch.commit()

Retrive document

// with id
const user?: User = await User.get("id")

// with DocumentReference
const user?: User = await User.get(firestore.doc("a/a"))

Convert from DocumentSnapshot

const user: User = User.fromSnapshot(documentSnapshot)

Field

Use Field to represent a field in a document. A Field can have another Document. In that case, use the @Codable decorator.

export class Address extends Model {
	@Field postCode?: string
	@Field country?: string
}

export class User extends Doc {
	@Field name?: string
	@Field thumbnailImage?: File
	@Codable(Address)
	@Field address: Address[] = []
}

SubCollecion

Use SubCollection and Collection to represent SubCollection.

class Charge extends Doc {
    @Field amount: number = 0
    @Field userID!: string
}
class User extends Doc {
    @SubCollection charges: Collection<Charge> = new Collection()
}