startupjs racer-orm
ORM system for Racer.js and ShareDB
What it does
Lets you automatically override your scope models
(created with .at()
and .scope()
) with the additional methods.
Usage
StartupJS project has the ORM plugin enabled by default,
so you don't need to do any initialization and can just start adding new ORM entities.
If you are using this package standalone, you'll need to add the orm plugin manually:
import Racer from 'racer'
import racerOrm from '@startupjs/orm'
Racer.use(racerOrm)
Then start adding the ORM entities to your model.
Each ORM Entity must be inherited from either:
Model.ChildModel
from racer
package.- or recommended
BaseModel
from startupjs/orm
package. This one has additional helper methods like .getId
and .getCollection
and can also use ActionRecord-like associations.
import { Model } from 'racer'
class PlayerModel extends Model.ChildModel {
alert (message) {
this.set('alert', this.get('name') + ', ' + message)
this.setDiff('showAlert', true)
}
}
class GamesModel extends Model.ChildModel {
async addNew (userId = 'system', params = {}) {
let gameId = this.id()
await this.add('games', {
name: 'Dummy Game',
...params,
id: gameId,
userId,
playerIds: [],
createdAt: Date.now()
})
return gameId
}
}
class GameModel extends Model.ChildModel {
async alertPlayers (message) {
let playerIds = this.get('playerIds')
let playersQuery = this.root.query('players', { _id: { $in: playerIds } })
await this.subscribe(playersQuery)
for (let playerId of playersQuery.getIds()) {
this.scope('players.' + playerId).alert(message)
}
}
async addPlayer (userId, params = {}) {
if (!userId) throw new Error('userId required')
var playerId = this.id()
await this.root.add('players', {
...params,
id: playerId,
userId,
createdAt: Date.now()
})
await this.push('playerIds', playerId)
return playerId
}
}
racer.orm('games', GamesModel)
racer.orm('games.*', GameModel)
racer.orm('players.*', PlayerModel)
async function main ($root) {
let $games = $root.scope('games')
let gameId = await $games.addNew('userId1', { name: 'Cool game' })
let $game = $games.at(gameId)
for (let userIds of ['userId1', 'userId2', 'userId3']) {
await $game.addPlayer(userIds)
}
$game.alertPlayers('please join the game!')
}
Factory
Sometimes you want to dynamically decide which ORM to use
based on the document's data. Factory let you do that.
Example:
class BasePlayerModel extends Model.ChildModel {
getColor () {
throw new Error('Player color is unknown')
}
}
class AlliedPlayerModel extends BasePlayerModel {
getColor () {
return 'blue'
}
}
class RivalPlayerModel extends BasePlayerModel {
getColor () {
return 'red'
}
}
function PlayerFactory ($player, $parent) {
let playerTeamId = $player.get('teamId')
let $root = $player.root
let myTeamId = $root.get('_session.myTeamId')
if (!playerTeamId || !myTeamId) return new BasePlayerModel($parent)
if (playerTeamId === myTeamId) {
return new AlliedPlayerModel($parent)
} else {
return new RivalPlayerModel($parent)
}
}
PlayerFactory.factory = true
racer.orm('players.*', PlayerFactory)
Alias
You can optionally specify an alias for the ORM Entity:
racer.orm('players.*', PlayerModel, 'Player')
This will allow you to explicitly specify in .at()
and .scope()
which ORM Entity to use even for the unknown path patters:
let playerId = 'playerId1'
model.scope('players.' + playerId).alert('please join the game!')
model.scope('_session.myPlayer', 'Player').alert('please join the game!')
IMPORTANT: Note, that this is a bad practice and must only be used in the edge cases.
It's always better to list all your path patterns explicitly and don't use aliases at all:
racer.orm('players.*', PlayerModel)
racer.orm('_session.myPlayer', PlayerModel)
racer.orm('_session.rivalPlayer', PlayerModel)
JSON Schema validation of documents.
Associations decorators
Association allow you to describe relationships between ORM entities for reuse in your code.
belongsTo(AssociatedOrmEntity, options)
Specifies a one-to-one association with another ORM entity. This decorator should only be used if this ORM entity contains the foreign key.
AssociatedOrmEntity (OrmEntityClass)
: associated orm entity
options (Object)
:
key
: foreign key name (default: collection + 'Id'
)- any other custom properties
hasOne(AssociatedOrmEntity, options)
Specifies a one-to-one association with another ORM entity. This decorator should only be used if the other ORM entity contains the foreign key.
AssociatedOrmEntity (OrmEntityClass)
: associated orm entity
options (Object)
:
key
: foreign key name (default: collection + 'Id'
)- any other custom properties
hasMany(AssociatedOrmEntity, options)
Is similar to hasOne
, but indicates a one-to-many association with another ORM entity.
AssociatedOrmEntity (OrmEntityClass)
: associated orm entity
options (Object)
:
key
: foreign key name (default: collection + 'Ids'
)- any other custom properties
import { BaseModel, hasMany } from 'startupjs/orm'
import GamesModel from './GamesModel'
import GameModel from './GameModel'
import PlayerModel from './PlayerModel'
racer.orm('games', GamesModel)
racer.orm('games.*', hasMany(PlayerModel)(GameModel))
racer.orm('players.*', PlayerModel)
Installation
- in
server/index.js
add validateSchema: true
to startupjsServer()
options - Go to one of your ORM document entities (for example,
UserModel
, which targets users.*
) and add a static method schema
:
import { BaseModel } from 'startupjs/orm'
export default class UserModel extends BaseModel {
static schema = {
firstName: { type: 'string' },
lastName: { type: 'string' },
age: {
type: 'number',
multipleOf: 1,
minimum: 0,
maximum: 130
}
}
}
Notes
- Schema is checked on both client-side and server-side.
- Schema validation only works in development. So there won't be any performance overheads when
NODE_ENV
is production
- Only ORMs targeting documents path
<collection>.*
are gonna be parsed for schema
definitions.
Helpers to work with forms
createdAt
, updatedAt
, id
, _id
fields are automatically excluded.- Support specifying
required
flag inside json-schema object properties -- it will automatically bubble up to the required
array and it will also be passed to the Form
to show the red asterics.
pickFormFields
Helper function to pick fields from schema to be consumed by Form(fields)
.
export function pickFormFields (schema, options) {}
Example
import { BaseModel, pickFormFields } from 'startupjs/orm'
export default class PersonsModel extends BaseModel {
static schema = {
name: { type: 'string', required: true },
number: { type: 'number' },
gender: { type: 'string', enum: ['man', 'woman'] },
phone: { type: 'string' },
likes: { type: 'object', input: 'likes' },
createdAt: { type: 'number', required: true }
}
}
export const PERSON_FORM = pickFormFields(PersonsModel.schema)
import { PERSON_FORM } from '@/model/persons'
import { observer, useValue$ } from 'startupjs'
import { Form, Button } from '@startupjs/ui'
export default observer(() => {
const $new = useValue$({})
return (
<>
<Form fields={PERSON_FORM} $value={$new} customInputs={{ likes: LikesInput }} />
<Button onPress={() => console.log('Submit form', $new.get())}>Submit</Button>
</>
)
})
function LikesInput () { return null }
License
MIT
(c) Decision Mapper - http://decisionmapper.com