API
DataProvider
Methods
registerConnection(name: string): void
- Register connection in your data storagename
- name of connection
dump(): SerializedStorage
- Get all data from your data providerrestore(data: SerializedStorage): void
- Set data to data providerdata
- - data to set
registerModule(path: ModulePath, initialState?: State): void
- Register module in your connectionpath
- tuple like [connection, <moduleName>]initialState
- optional initial module state
getModuleState(module: ModulePath): State
- Get state of specific modulemodule
- tuple like [connection, <moduleName>]
hasModule(module: ModulePath): boolean
- Does specific module existmodule
- tuple like [connection, <moduleName>]
save(module: ModulePath, records: Elements): void
- Save datamodule
- tuple like [connection, <moduleName>]records
- record like { [id: string]: Entity }
insert(module: ModulePath, records: Elements): void
- Insert datamodule
- tuple like [connection, <moduleName>]records
- record like { [id: string]: Entity }
replace(module: ModulePath, records: Elements): void
- Replace part of data with new datamodule
- tuple like [connection, <moduleName>]records
- record like { [id: string]: Entity }
update(module: ModulePath, records: Elements): void
- Update part of datamodule
- tuple like [connection, <moduleName>]records
- record like { [id: string]: Entity }
delete(module: ModulePath, ids: string[]): void
- Delete datamodule
- tuple like [connection, <moduleName>]ids
- primaryKey array of elements which will be deleted
flush(module: ModulePath): void
- Remove all data from modulemodule
- tuple like [connection, <moduleName>]
Database
Methods
isStarted()
- Whether the database has already been installed or not. The model registration procedure depends on this flag.getRepository<R extends Repository<InstanceType<M>>, M extends typeof Model = typeof Model>(model: M): R
- Get repository for modelmodel
- model for which a repository is needed
registerCustomRepository<R extends Repository>(repo: Constructor<R>): this
- Add custom repository constructorrepo
- constructor of your repository
setDataProvider(dataProvider: DataProvider): this
- Set data providerdataProvider
- instance of chosen DataProvider
getDataProvider()
- Get current database DataProvider. Returns initial DataProvider, not wrapped with EventsDataProviderWrapper.getWrappedDataProvider()
- Get current DataProvider wrapped in EventsDataProviderWrapersetConnection(connection: string): this
- Set the connection.connection
- connection name
getConnection(): string
- Get current database connectionstart(): this
- Initialize the database before a user can start using it.register<M extends Model>(model: M): void
- Register the given model.model
- model to register
getModel<M extends Model>(name: string): M
- Get a model by the specified entity name.name
- model name (from static entity field)
getSchema(name: string): EntitySchema
- Get schema by the specified entity name.name
- model name (from static entity field)
on(event: Extract<RattusEvent, 'save' | 'insert' | 'update' | 'replace'>, callback: DataEventCallback<Elements, Elements>): CancelSubscriptionCallback
- Listen to RattusEvent which can modify data it operates with. Should return an updated data.event
- event to listen tocallback
- callback, accepts Elements, returns Elements
on(event: typeof RattusEvents.DELETE, callback: DataEventCallback<string[], string[]>): CancelSubscriptionCallback
- Listen to RattusEvent on delete data. Should return an array of primary keys that will be deletedevent
- event to listen tocallback
- callback, accepts Array<string | number>, returns Array<string | number>
on(event: typeof RattusEvents.MODULE_REGISTER, callback: DataEventCallback<ModuleRegisterEventPayload, ModuleRegisterEventPayload>): CancelSubscriptionCallback
- Listen to RattusEvent on register new module. Should return special metadata payload: { path: ModulePath, initialState?: State }event
- event to listen tocallback
- callback, accepts ModuleRegisterEventPayload, returns ModuleRegisterEventPayload
on(event: typeof RattusEvents.FLUSH, callback: DataEventCallback<undefined>): CancelSubscriptionCallback
- Listen to RattusEvent on flush data. Can't modify data.event
- event to listen tocallback
- void callback
on(event: typeof RattusEvents.CONNECTION_REGISTER, callback: DataEventCallback<string>): CancelSubscriptionCallback
- Listen to RattusEvent on connection register. Can't modify data.event
- event to listen tocallback
- void callback, accepts connection name.
on(event: typeof RattusEvents.DATA_CHANGED, callback: DataEventCallback<DataChangedEventPayload>): CancelSubscriptionCallback
- Listen to RattusEvent on any data changed. Can't modify data.event
- event to listen tocallback
- void callback, accepts { path: ModulePath, state: State }
resetListeners(event?: RattusEvent)
- Reset listeners for specific eventevent
- reset for this event
use(plugin: DatabasePlugin): this
- Use pluginplugin
- database plugin function
dump(): SerializedStorage
- Export all data from current connection as JavaScript objectrestore(data: SerializedStorage)
- Import data into databasedata
- data to import
Model
Properties
static entity: string
- The name of the model.static dataTypeCasting: boolean = true
- Should or should not cast data typesstatic primaryKey: string | string[] = 'id'
- The primary key for the model.
Methods
static fields(): ModelFields
- Create a new model fields definition.static setRegistry<M extends typeof Model>(key: string, attribute: () => Attribute<unknown>): M
- Set the attribute to the registry.key
- model field nameattribute
- attribute factory
static clearBootedModels(): void
- Clear the list of booted models, so they can be re-booted.static clearRegistries(): void
- Clear registries.static newRawInstance<M extends Model>(): M
- Create a new model instance without field values being populated. This method is mainly for the internal use when registering models to the database. Since all pre-registered models are for referencing its model setting during the various process, but the fields are not required. Use this method when you want create a new model instance for: - Registering model to a component (eg. Repository, Query, etc.) - Registering model to attributes (String, Has Many, etc.)static attrField(value: any): Attr
- Create a new Attr attribute instance.value
- initial attribute value
static stringField(value: string | null): Str
- Create a new String attribute instance.value
- initial value, null if nullable
static numberField(value: number | null): Num
- Create a new Number attribute instance.value
- initial value, null if nullable
static booleanField(value: boolean | null): Bool
- Create a new Boolean attribute instance.value
- initial value, null if nullable
static uidField(): Uid
- Create a new Uid attribute instance.static dateField(value: Date | string | number | null): DateField
- Create a new Date attribute instance.value
- initial value, null if nullable.
static hasOne(related: ModelConstructor<any>, foreignKey: string, localKey?: string): HasOne
- Create a new HasOne relation instance.related
- related modelforeignKey
- related model keylocalKey
- this model key
static belongsTo(related: ModelConstructor<any>, foreignKey: string, ownerKey?: string): BelongsTo
- Create a new BelongsTo relation instance.related
- related modelforeignKey
- model keyownerKey
- related primary key
static hasMany(related: ModelConstructor<any>, foreignKey: string, localKey?: string): HasMany
- Create a new HasMany relation instance.related
- related modelforeignKey
- related model keylocalKey
- this model key
static hasManyBy(related: ModelConstructor<Model>, foreignKey: string, ownerKey?: string): HasManyBy
- Create a new HasManyBy relation instance.related
- related modelforeignKey
- model keyownerKey
- related model key
static morphOne(related: ModelConstructor<Model>, id: string, type: string, localKey?: string): MorphOne
- Create a new MorphOne relation instance.related
- related modelid
- related model keytype
- morph typelocalKey
- local key
static morphTo(related: ModelConstructor<any>[], id: string, type: string, ownerKey: string = ''): MorphTo
- Create a new MorphTo relation instance.related
- related modelsid
- related model keytype
- morph typeownerKey
- owner key
$self(): typeof Model
- Get the constructor for this model.$entity(): string
- Get the entity for this model.$primaryKey(): string | string[]
- Get the primary key for this model.$fields(): ModelFields
- Get the model fields for this model.$newInstance(attributes?: Element, options?: ModelOptions): this
- Create a new instance of this model. This method provides a convenient way to re-generate a fresh instance of this model. It's particularly useful during hydration through Query operations.attributes
- data to fill new instance withoptions
- options (should fill, include relations)
$fill(attributes: Element = {}, options: ModelOptions = {}): this
- Fill this model by the given attributes. Missing fields will be populated by the attributes default value.attributes
- data to fill new instance withoptions
- options (should fill, include relations)
$getKeyName(): string | string[]
- Get the primary key field name.$getKey(record: Element = this): string | number | (string | number)[] | null
- Get primary key value for the model. If the model has the composite key, it will return an array of ids.record
- optional data of element to get key
$getIndexId(record: Element = this): string
- Get the index id of this model or for a given record.record
- optional data of element to index id
$getLocalKey(): string
- Get the local key name for the model.$getRelation(name: string): Relation
- Get the relation instance for the given relation name.name
- name of relation to get instance
$setRelation(relation: string, model: Model | Model[] | null): this
- Set the given relationship on the model.relation
- relation namemodel
- model to set relation
$getAttributes(): Element
- Get the serialized model attributes.$toJson(options: ModelOptions = { relations: true }): RawModel<this>
- Serialize this model, or the given model, as POJO.options
- optional options to apply
$sanitize(record: Element): Element
- Sanitize the given record. This method is similar to `$toJson` method, but the difference is that it doesn't instantiate the full model. The method is used to sanitize the record before persisting to the store. It removes fields that don't exist in the model field schema or if the field is relationship fields. Note that this method only sanitizes existing fields in the given record. It will not generate missing model fields. If you need to generate all model fields, use `$sanitizeAndFill` method instead.record
- data to sanitize
$sanitizeAndFill(record: Element): Element
- Same as `$sanitize` method, but it produces missing model fields with its default value.record
- data to sanitize
getThisNonStrict()
-
Query
Methods
constructor(protected readonly database: Database, model: M, eagerLoad: EagerLoad = {}, skip: number = 0, take: number | null = null, orders: Order[] = [], wheres: Where[] = [])
- Create a new query instance.database
- database to work withmodel
- model to work witheagerLoad
- the relationships that should be eager loaded, default {}skip
- the number of records to skip, default 0take
- the maximum number of records to return, default nullorders
- the orderings for the query, default []wheres
- the where constraints for the query, default []
newQuery(model: string): Query<Model>
- Create a new query instance for the given model.model
- model entity to work with
newQueryWithConstraints(model: string): Query<Model>
- Create a new query instance with constraints for the given model.model
- model entity to work with
newQueryForRelation(relation: Relation): Query<Model>
- Create a new query instance from the given relation.relation
- relation to get model from
where(field: WherePrimaryClosure | string, value?: WhereSecondaryClosure | any): this
- Add a basic where clause to the query.field
- field name to work withvalue
- optional value to match
whereIn(field: string, values: any[]): this
- Add a "where in" clause to the query.field
- field name to work withvalues
- values to match
whereId(ids: string | number | (string | number)[]): this
- Add a where clause on the primary key to the query.ids
- primary keys to match
orWhere(field: WherePrimaryClosure | string, value?: WhereSecondaryClosure | any): this
- Add an "or where" clause to the query.field
- field name to work withvalue
- optional value to match
orderBy(field: OrderBy, direction: OrderDirection = 'asc'): this
- Add an "order by" clause to the query.field
- field name to work withdirection
- direction of order (asc | desc)
limit(value: number): this
- Set the "limit" value of the query.value
- limit records to count
offset(value: number): this
- Set the "offset" value of the query.value
- offset for records
with(name: string, callback: EagerLoadConstraint = () => {}): this
- Set the relationships that should be eager loaded.name
- relation namecallback
- callback to load
withAll(callback: EagerLoadConstraint = () => {}): this
- Set to eager load all top-level relationships. Constraint is set for all relationships.callback
- callback to load
withAllRecursive(depth: number = 3): this
- Set to eager load all relationships recursively.depth
- relations depth to load
all(): Collection<M>
- Get all models from the store. The difference with the `get` is that this method will not process any query chain. It'll always retrieve all models.get(): Collection<M>
- Retrieve models by processing whole query chain.first(): Item<M>
- Execute the query and get the first result.find(id: string | number): Item<M>
- Find a model by its primary key.id
- primary key value of needed item
find(ids: (string | number)[]): Collection<M>
- Find multiple models by their primary keys.ids
- primary keys array of needed items
findIn(ids: (string | number)[]): Collection<M>
- Find multiple models by their primary keys.ids
- primary keys array of needed items
select(): Collection<M>
- Retrieve models by processing all filters set to the query chain.load(models: Collection<M>): Collection<M>
- Eager load relations on the model.models
- models array for relations load
revive(schema: Element[]): Collection<M>
- Retrieves the models from the store by following the given normalized schema.schema
- elements to revive
revive(schema: Element): Item<M>
- Retrieves the model from the store by following the given normalized schema.schema
- element to revive
reviveOne(schema: Element): Item<M>
- Revive single model from the given schema.schema
- element to revive
reviveMany(schema: Element[]): Collection<M>
- Revive multiple models from the given schema.schema
- elements to revive
new(): M
- Create and persist model with default values.save(records: Element[]): M[]
- Save the given records to the store with data normalization.records
- elements to save
save(record: Element): M
- Save the given records to the store with data normalization.record
- element to save
saveElements(elements: Elements): void
- Save the given elements to the store.elements
- elements map to save
insert(records: Element[]): Collection<M>
- Insert the given record to the store.records
- elements to insert
insert(record: Element): M
- Insert the given record to the store.record
- element to insert
fresh(records: Element[]): Collection<M>
- Insert the given records to the store by replacing any existing records.records
- new elements
fresh(record: Element): M
- Insert the given record to the store by replacing any existing records.record
- new element
update(record: Element): Collection<M>
- Update the record matching the query chain.record
- element update payload
destroy(ids: (string | number)[]): Collection<M>
- Destroy the models for the given ids.ids
- primary keys to destroy
destroy(id: string | number): Item<M>
- Destroy the models for the given id.id
- primary key to destroy
delete(): M[]
- Delete records resolved by the query chain.flush(): Collection<M>
- Delete all records in the store.
RattusContext
Properties
$database: Database
- instance of first (main) database$databases: Record<string, Database> = {}
- all databases storage
Methods
constructor(dataProvider: DataProvider)
- Create context with DataProvider passeddataProvider
- chosen DataProvider
constructor(mainDatabase: Database)
- Create context with Database passed. DataProvider will be inferred from database.mainDatabase
- main database in context
createDatabase(connection: string = 'entities', isPrimary = false): Database
- Create database, save it in context and return.connection
- connection name for new databaseisPrimary
- should new database become "main" database
$repo<R extends Repository<InstanceType<M>>, M extends typeof Model = typeof Model>(model: M, connection?: string): R
- Get repository for model from database from specific connectionmodel
- model for which a repository is neededconnection
- database connection name
Repository
Properties
static _isRepository: boolean = true
- A special flag to indicate if this is the repository class or not. It's used when retrieving repository instance from `store.$repo()` method to determine whether the passed in class is either a repository or a model.use: typeof Model
- The model object to be used for the custom repository.
Methods
constructor(public database: Database)
- Create a new Repository instance.database
- database to work with
initialize(model?: ModelConstructor<M>): this
- Initialize the repository by setting the model instance.model
- model to initialize repository
getModel(): M
- Get the model instance. If the model is not registered to the repository, it will throw an error. It happens when users use a custom repository without setting `use` property.repo<M extends typeof Model>(model: M): Repository<InstanceType<M>>
- Create a new repository with the given model.model
- model to create new repository for
query(): Query<M>
- Create a new Query instance.where(field: WherePrimaryClosure | string, value?: WhereSecondaryClosure | any): Query<M>
- Add a basic where clause to the query.field
- field name to work withvalue
- optional value to match
orWhere(field: WherePrimaryClosure | string, value?: WhereSecondaryClosure | any): Query<M>
- Add an "or where" clause to the query.field
- field name to work withvalue
- optional value to match
orderBy(field: OrderBy, direction?: OrderDirection): Query<M>
- Add an "order by" clause to the query.field
- field name to work withdirection
- direction of order (asc | desc)
limit(value: number): Query<M>
- Set the "limit" value of the query.value
- limit records to count
offset(value: number): Query<M>
- Set the "offset" value of the query.value
- offset for records
with(name: string, callback?: EagerLoadConstraint): Query<M>
- Set the relationships that should be eager loaded.name
- relation namecallback
- callback to load
withAll(callback?: EagerLoadConstraint): Query<M>
- Set to eager load all top-level relationships. Constraint is set for all relationships.callback
- callback to load
withAllRecursive(depth?: number): Query<M>
- Set to eager load all top-level relationships. Constraint is set for all relationships.depth
- relations depth to load
all(): Collection<M>
- Get all models from the store.find(id: string | number): Item<M>
- Find a model by its primary key.id
- primary key value of needed item
find(ids: (string | number)[]): Collection<M>
- Find multiple models by their primary keys.ids
- primary keys array of needed items
revive(schema: Element[]): Collection<M>
- Retrieves the models from the store by following the given normalized schema.schema
- elements to revive
revive(schema: Element): Item<M>
- Retrieves the model from the store by following the given normalized schema.schema
- element to revive
make(attributes?: Element): M
- Create a new model instance. This method will not save the model to the store. It's pretty much the alternative to `new Model()`, but it injects the store instance to support model instance methods in SSR environment.attributes
- values for new model instance
save(records: Element[]): M[]
- Save the given records to the store with data normalization.records
- elements to save
save(record: Element): M
- Save the given records to the store with data normalization.record
- element to save
new(): M
- Create and persist model with default values.insert(records: Element[]): Collection<M>
- Insert the given record to the store.records
- elements to insert
insert(record: Element): M
- Insert the given record to the store.record
- element to insert
fresh(records: Element[]): Collection<M>
- Insert the given records to the store by replacing any existing records.records
- new elements
fresh(record: Element): M
- Insert the given record to the store by replacing any existing records.record
- new element
destroy(ids: (string | number)[]): Collection<M>
- Destroy the models for the given ids.ids
- primary keys to destroy
destroy(id: string | number): Item<M>
- Destroy the models for the given id.id
- primary key to destroy
flush(): M[]
- Delete all records in the store.