f_orm_m8

Description:

f orm m8

Dart Framework ORM M8 #







f_orm_m8 - \fɔːrm meɪt\ It defines the core of M8, a tiny ORM framework with a simple set of annotations.


Dart Framework ORM M8

Description
Introduction
Annotation

DataTable

TableMetadata


DataColumn

ColumnMetadata
CompositeConstraint
A simple approach
A fine tuned approach




Interfaces

DbOpenEntity
DbEntity
DbAccountEntity
DbAccountRelatedEntity implements DbEntity


Usage convention
Concrete implementation examples



Description #
The package is for developers of code generators. The goal is to have a framework that, besides relational mapping, offers the possibility to generate scaffolds for basic usage cases: user account, user data, data tracking (create, update, delete), soft delete.
If you are looking for a ready to use implementation, check Concrete implementation examples!
Promoted implementations:
f_orm_m8_sqlite - a Sqlite fixture generator with mapping capability out of the box. It is stuffed with a Flutter example project as a showcase for the common use cases covered by M8. See sources on github
Promoted toolset:
Flutter ORM M8 Generator - VS Code extension to generate models and database adapter based on f_orm_m8_sqlite framework for Flutter application
Introduction #
The package adds definitions for a set of types that could be combined to expand ORM capabilities in the annotated code.
The current version defines two main annotation types and some helpers associated with each definition:

DataTable

TableMetadata: trackCreate, trackUpdate, softDeletable


DataColumn

ColumnMetadata: ignore, primaryKey, unique, notNull, autoIncrement, indexed
CompositeConstraint: unique, primaryKey, foreignKey, indexed



In order to ease the code emitting, four abstract classes are defined:

DbOpenEntity: non constrained entity
DbEntity: an entity with Id as primary key
DbAccountEntity: a user account template with Id as primary key
DbAccountRelatedEntity: user related data entities

Annotation #
The annotation conventions are splitted in two:

DataTable
DataColumn

DataTable #
DataTable describes the required name for the table in conjuction with a bit mask for optional TableMetadata. Table metadata is specified with the parameter metadataLevel, and is a syntactic sugar to generate the proper fixture without explicitly adding the required fields.
@DataTable(
"a01_tests",
metadataLevel: TableMetadata.softDeletable | TableMetadata.trackCreate | TableMetadata.trackUpdate)
class A01Test implements DbAccountRelatedEntity {
copied to clipboard
TableMetadata
The TableMetadata describes the basic options for the table:

softDeletable
trackCreate
trackUpdate

The options may be combined in various ways using | operator
@DataTable(
"health_issues",
metadataLevel:
TableMetadata.softDeletable |
TableMetadata.trackCreate |
TableMetadata.trackUpdate)
copied to clipboard
DataColumn #
The DataColumn describes how the fields will be transformed into entity attributes.
The DataColumn constructor has three parameters:

name

purpose: to specify the entity name
type: String
positional
mandatory


metadataLevel

purpose: syntactic sugar to specify common use cases
type: int as combination of ColumnMetadata
named
optional


compositeConstraints

purpose: a fine grain mode to specify composite constraints
type: List<CompositeConstraint>
named
optional



const DataColumn(this.name, {this.metadataLevel, this.compositeConstraints});
copied to clipboard
ColumnMetadata
Column metadata is specified with the parameter metadataLevel. Is a syntactic sugar to generate a quick fixture, offering basic options for the following use cases:

ignore
primaryKey
unique
notNull
autoIncrement
indexed

The options can be combined in various ways using | operator
@DataColumn(
"id",
metadataLevel: ColumnMetadata.primaryKey | ColumnMetadata.unique | ColumnMetadata.autoIncrement)
copied to clipboard
The primaryKey, unique, indexed constraints can be generated in a targetted way using CompositeConstraint
CompositeConstraint
The composite constraint is able to specify the name and the type of the constraint. If the same name is used on multiple DataColumns, it will signal a composite constraint that will cover all the involved fields.
The CompositeConstraint is instantiated with named, required parameters:

name - the name of the constraint
constraintType - the type of the constraint as enum with the following values:

unique,
primaryKey,
foreignKey,
indexed



A simple approach
DataColumn describes the required name for the column in conjunction with a bit mask for required column metadata.
@DataColumn(
"id",
metadataLevel:
ColumnMetadata.primaryKey |
ColumnMetadata.unique |
ColumnMetadata.autoIncrement)
int id;
copied to clipboard
A fine tuned approach
DataColumn describes the required name for the column in conjunction with a list of composite constraints. For example, if we need a composite, unique constraint defined on the combination of two fields, we define the composite with the same name:
@DataColumn("account_id", compositeConstraints: [
CompositeConstraint(
name: "uq_account_entry",
constraintType: CompositeConstraintType.unique)
])
int accountId;

@DataColumn("description", compositeConstraints: [
CompositeConstraint(
name: "uq_account_entry",
constraintType: CompositeConstraintType.unique)
])
String description;
copied to clipboard
Interfaces #
DbOpenEntity #
DbOpenEntity is, as it's name suggests, a template for non restrictive models with composite primary keys.
It can also be used for non integer primary key implementation.
It defines a single method getPrimaryKey
DbEntity #
Can be used for a general purpose model template with integer primary key named id
DbAccountEntity #
It implements DbEntity.
Can be used for a model template in a generic user account with the following fields:

userName
email
abbreviation
isCurrent

DbAccountRelatedEntity implements DbEntity #
It implements DbEntity.
Can be used for a model template in a generic, account dependent, entity with the following fields:

accountId

Usage convention #
The package can be a start for other projects that aim to develop an ORM scaffolding infrastructure. It is up to developers how they implement the gems of this package. We recommend the annotations to be placed as in the following example:
@DataTable("a01_tests", TableMetadata.softDeletable)
class A01Test implements DbAccountRelatedEntity {
@DataColumn(
"id",
metadataLevel: ColumnMetadata.primaryKey | ColumnMetadata.unique | ColumnMetadata.autoIncrement)
int id;

@DataColumn("account_id", compositeConstraints: [
CompositeConstraint(
name: "uq_account_entry",
constraintType: CompositeConstraintType.unique)
])
int accountId;

@DataColumn("description", compositeConstraints: [
CompositeConstraint(
name: "uq_account_entry",
constraintType: CompositeConstraintType.unique)
])
String description;

@DataColumn("record_date")
int recordDate;
}
copied to clipboard
Concrete implementation examples #
The following is a list of f-orm-m8 implementations by supported backend database.



package name
version
database
source





f_orm_m8_sqlite

SQLite
f-orm-m8-sqlite