f_orm_m8 0.8.0+3

  • Readme
  • Changelog
  • Example
  • Installing
  • 78

Dart Framework ORM M8 #

Gitter GitHub release pub package Build Status Codecov license

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

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:

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

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 {

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)

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});

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)

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;

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;

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;
}

Concrete implementation examples #

The following is a list of f-orm-m8 implementations by supported backend database.

package nameversiondatabasesource
f_orm_m8_sqlitepub packageSQLitef-orm-m8-sqliteGitHub release

[Unreleased]

[0.8.0+3] - 2019-05-21

Added #

  • Tests to cover 100% of the code
  • Integrate the codecov.io into CI pipeline

Changed #

  • The test folder was reviewed and reorganized
  • The README.md was reviewed with small fixes

[0.8.0+2] - 2019-05-03

Changed #

  • The README.md was reviewed with small fixes

[0.8.0+1] - 2019-05-03

Changed #

  • The CHANGELOG.md was reviewed with small fixes
  • The README.md was reviewed with small fixes

[0.8.0] - 2019-05-02

Changed #

  • The github project was renamed from flutter-orm-m8 to f-orm-m8
  • The dart package was renamed from flutter_orm_m8 to f_orm_m8
  • The dart package was published as f_orm_m8
  • See f_orm_m8 for new updated framework

Removed #

  • The former dart package flutter_orm_m8 is not longer maintained

[0.7.1] - 2019-04-29

Changed #

  • flutter_orm_m8.dart exports the composite_constraint
  • The README.md was refined

[0.7.0] - 2019-04-29

Added #

  • CompositeConstraintType - enum to signal constraints that are candidates to composition
  • CompositeConstraint - describe the constraints that require non default naming or aggregation with another constraint with same name and type

Changed #

  • The DataColumn constructor parameters. The current version requires a mandatory name. The parameter metadataLevel is now named and optional. A third optional named parameter compositeConstraints as a list of CompositeConstraint was added.
  • ColumnMetadata fields name to lowerCamelCase
  • TableMetadata fields name to lowerCamelCase

[0.6.0] - 2019-04-15

Changed #

  • The DbAccountEntity fields. It received a new bool field named isCurrent

[0.5.1] - 2019-04-08

Fixed #

  • The pubspec description length must be between 60 and 180 characters

[0.5.0] - 2019-04-08

Added #

  • DbOpenEntity - for free DataTables with unconstrained PK
  • Test for DbOpenEntity

Changed #

  • The README.md was extended
  • The CHANGELOG was aligned with keepachangelog

[0.4.0] - 2019-04-02

Added #

  • TableMetadata to enhance DataTable. Three options:

    • SoftDeletable
    • TrackCreate
    • TrackUpdate

Changed #

  • All the fields in DbEntity and descendants goes public
  • Removed all methods from DbEntity and descendants to keep the models as plain as possible

[0.3.0] - 2019-03-15

Changed #

  • DbEntity:
    • Adding abstract method getDbEntityFromMap(Map<String, dynamic> map);

[0.2.0] - 2019-03-08

Added #

  • Base classes for:
    • DbEntity
    • DbAccountEntity
    • DbAccountRelatedEntity

[0.1.0] - 2019-03-03

Changed #

  • Switching from flutter_test to test
  • Removing flutter dependencies

[0.0.3] - 2019-03-02

Changed #

  • Shifting column options values with one bit
  • Enhancing documentation
  • Reorganizing example

[0.0.2] - 2019-03-01

Added #

  • Adding some example usage

[0.0.1] - 2019-03-01

Added #

  • Basic annotations for ORM extensions
  • ColumnMetadata options:
    • Ignore
    • PrimaryKey
    • Unique
    • NotNull
    • AutoIncrement
    • Indexed
  • DataTable with name
  • DataColumn with name and a bit mask for required ColumnMetadata's

example/example.dart

import 'package:f_orm_m8/f_orm_m8.dart';

@DataTable(
    "health_issues",
    TableMetadata.softDeletable |
        TableMetadata.trackCreate |
        TableMetadata.trackUpdate)
class HealthIssue 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", compositeConstraints: [
    CompositeConstraint(
        name: "ix_record_date", constraintType: CompositeConstraintType.indexed)
  ])
  int recordDate;

  HealthIssue(this.accountId, this.description);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  f_orm_m8: ^0.8.0+3

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:f_orm_m8/f_orm_m8.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
57
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
78
Learn more about scoring.

We analyzed this package on Oct 16, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:f_orm_m8/f_orm_m8.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.68.0 <3.0.0
meta ^1.1.6 1.1.7
Dev dependencies
test ^1.3.3
test_coverage ^0.2.0