{"id":13552646,"url":"https://github.com/matei-tm/f-orm-m8","last_synced_at":"2025-04-03T03:32:27.211Z","repository":{"id":56828654,"uuid":"173208287","full_name":"matei-tm/f-orm-m8","owner":"matei-tm","description":"The core of M8, a Dart tiny ORM framework with a simple set of annotations","archived":true,"fork":false,"pushed_at":"2020-07-19T13:03:53.000Z","size":80,"stargazers_count":30,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T16:45:05.635Z","etag":null,"topics":["dart","framework","orm","orm-m8"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matei-tm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-01T00:27:43.000Z","updated_at":"2024-01-09T03:17:01.000Z","dependencies_parsed_at":"2022-08-26T14:11:23.144Z","dependency_job_id":null,"html_url":"https://github.com/matei-tm/f-orm-m8","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matei-tm%2Ff-orm-m8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matei-tm%2Ff-orm-m8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matei-tm%2Ff-orm-m8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matei-tm%2Ff-orm-m8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matei-tm","download_url":"https://codeload.github.com/matei-tm/f-orm-m8/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246933421,"owners_count":20857049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","framework","orm","orm-m8"],"created_at":"2024-08-01T12:02:07.191Z","updated_at":"2025-04-03T03:32:22.149Z","avatar_url":"https://github.com/matei-tm.png","language":"Dart","funding_links":[],"categories":["Dart"],"sub_categories":[],"readme":"# Dart Framework ORM M8 \r\n\r\n[![Gitter](https://img.shields.io/gitter/room/flutter-orm-m8/community.svg?style=flat-square)](https://gitter.im/flutter-orm-m8/community) \r\n[![GitHub release](https://img.shields.io/github/release/matei-tm/f-orm-m8.svg)](https://github.com/matei-tm/f-orm-m8) \r\n[![pub package](https://img.shields.io/pub/v/f_orm_m8.svg)](https://pub.dartlang.org/packages/f_orm_m8) \r\n[![Build Status](https://travis-ci.org/matei-tm/f-orm-m8.svg?branch=master)](https://travis-ci.org/matei-tm/f-orm-m8) \r\n[![Codecov](https://img.shields.io/codecov/c/github/matei-tm/f-orm-m8.svg)](https://codecov.io/gh/matei-tm/f-orm-m8) \r\n[![license](https://img.shields.io/github/license/matei-tm/f-orm-m8.svg)](https://github.com/matei-tm/f-orm-m8/blob/master/LICENSE)\r\n\r\n\u003e f_orm_m8 - \\fɔːrm meɪt\\ It defines the core of **M8**, a tiny ORM framework with a simple set of annotations.\r\n\r\n- [Dart Framework ORM M8](#dart-framework-orm-m8)\r\n  - [Description](#description)\r\n  - [Introduction](#introduction)\r\n  - [Annotation](#annotation)\r\n    - [DataTable](#datatable)\r\n      - [TableMetadata](#tablemetadata)\r\n    - [DataColumn](#datacolumn)\r\n      - [ColumnMetadata](#columnmetadata)\r\n      - [CompositeConstraint](#compositeconstraint)\r\n      - [A simple approach](#a-simple-approach)\r\n      - [A fine tuned approach](#a-fine-tuned-approach)\r\n  - [Interfaces](#interfaces)\r\n    - [DbOpenEntity](#dbopenentity)\r\n    - [DbEntity](#dbentity)\r\n    - [DbAccountEntity](#dbaccountentity)\r\n    - [DbAccountRelatedEntity implements DbEntity](#dbaccountrelatedentity-implements-dbentity)\r\n  - [Usage convention](#usage-convention)\r\n  - [Concrete implementation examples](#concrete-implementation-examples)\r\n\r\n## Description\r\n\r\nThe 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.  \r\nIf you are looking for a ready to use implementation, check [Concrete implementation examples](#concrete-implementation-examples)!\r\n\r\nPromoted implementations:\r\n\r\n[f_orm_m8_sqlite](https://pub.dartlang.org/packages/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](https://github.com/matei-tm/f-orm-m8-sqlite)\r\n\r\nPromoted toolset:\r\n\r\n[Flutter ORM M8 Generator](https://marketplace.visualstudio.com/items?itemName=matei-tm.f-orm-m8-generator) - VS Code extension to generate models and database adapter based on [f_orm_m8_sqlite](https://pub.dartlang.org/packages/f_orm_m8_sqlite) framework for Flutter application\r\n\r\n## Introduction\r\n\r\nThe package adds definitions for a set of types that could be combined to expand ORM capabilities in the annotated code.\r\nThe current version defines two main annotation types and some helpers associated with each definition:\r\n\r\n- [DataTable](#datatable)\r\n  - [TableMetadata](#tablemetadata): trackCreate, trackUpdate, softDeletable\r\n- [DataColumn](#datacolumn)\r\n  - [ColumnMetadata](#columnmetadata): ignore, primaryKey, unique, notNull, autoIncrement, indexed\r\n  - [CompositeConstraint](#compositeconstraint): unique, primaryKey, foreignKey, indexed\r\n\r\nIn order to ease the code emitting, four abstract classes are defined:\r\n\r\n  - [DbOpenEntity](#dbopenentity): non constrained entity\r\n  - [DbEntity](#dbentity): an entity with Id as primary key\r\n  - [DbAccountEntity](#dbaccountentity): a user account template with Id as primary key\r\n  - [DbAccountRelatedEntity](#dbaccountrelatedentity-implements-dbentity): user related data entities\r\n\r\n## Annotation\r\n\r\nThe annotation conventions are splitted in two:\r\n\r\n- DataTable\r\n- DataColumn\r\n\r\n### DataTable\r\n\r\nDataTable describes the required name for the table in conjuction with a bit mask for optional [TableMetadata](#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.  \r\n\r\n```dart\r\n@DataTable(\r\n  \"a01_tests\",\r\n  metadataLevel: TableMetadata.softDeletable | TableMetadata.trackCreate | TableMetadata.trackUpdate)\r\nclass A01Test implements DbAccountRelatedEntity {\r\n```\r\n\r\n#### TableMetadata\r\n\r\nThe TableMetadata describes the basic options for the table:\r\n\r\n- softDeletable\r\n- trackCreate\r\n- trackUpdate\r\n\r\nThe options may be combined in various ways using | operator\r\n\r\n```dart\r\n@DataTable(\r\n    \"health_issues\",\r\n    metadataLevel: \r\n      TableMetadata.softDeletable | \r\n      TableMetadata.trackCreate | \r\n      TableMetadata.trackUpdate)\r\n```\r\n\r\n### DataColumn\r\n\r\nThe DataColumn describes how the fields will be transformed into entity attributes. \r\nThe DataColumn constructor has three parameters:\r\n- name\r\n  - purpose: to specify the entity name\r\n  - type: String\r\n  - positional\r\n  - mandatory\r\n- metadataLevel \r\n  - purpose: syntactic sugar to specify common use cases\r\n  - type: int as combination of [ColumnMetadata](#ColumnMetadata)\r\n  - named\r\n  - optional\r\n- compositeConstraints\r\n  - purpose: a fine grain mode to specify composite constraints\r\n  - type: List\u003c[CompositeConstraint](#CompositeConstraint)\u003e\r\n  - named\r\n  - optional\r\n\r\n```dart\r\n const DataColumn(this.name, {this.metadataLevel, this.compositeConstraints});\r\n```\r\n\r\n#### ColumnMetadata\r\n\r\nColumn metadata is specified with the parameter `metadataLevel`. Is a syntactic sugar to generate a quick fixture, offering basic options for the following use cases:\r\n\r\n- ignore\r\n- primaryKey\r\n- unique\r\n- notNull\r\n- autoIncrement\r\n- indexed\r\n\r\nThe options can be combined in various ways using | operator\r\n\r\n```dart\r\n@DataColumn(\r\n  \"id\", \r\n  metadataLevel: ColumnMetadata.primaryKey | ColumnMetadata.unique | ColumnMetadata.autoIncrement)\r\n```\r\n\r\nThe `primaryKey`, `unique`, `indexed` constraints can be generated in a targetted way using [CompositeConstraint](CompositeConstraint)\r\n\r\n#### CompositeConstraint\r\n\r\nThe 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.\r\nThe CompositeConstraint is instantiated with named, required parameters:\r\n\r\n- name - the name of the constraint\r\n- constraintType - the type of the constraint as enum with the following values:\r\n  -  unique, \r\n  -  primaryKey, \r\n  -  foreignKey, \r\n  -  indexed\r\n\r\n#### A simple approach\r\n\r\nDataColumn describes the required name for the column in conjunction  with a bit mask for required column metadata.\r\n\r\n```dart\r\n  @DataColumn(\r\n    \"id\", \r\n    metadataLevel: \r\n      ColumnMetadata.primaryKey | \r\n      ColumnMetadata.unique | \r\n      ColumnMetadata.autoIncrement)\r\n  int id;\r\n```\r\n\r\n#### A fine tuned approach\r\n\r\nDataColumn 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:\r\n\r\n```dart\r\n  @DataColumn(\"account_id\", compositeConstraints: [\r\n    CompositeConstraint(\r\n        name: \"uq_account_entry\",\r\n        constraintType: CompositeConstraintType.unique)\r\n  ])\r\n  int accountId;\r\n\r\n  @DataColumn(\"description\", compositeConstraints: [\r\n    CompositeConstraint(\r\n        name: \"uq_account_entry\",\r\n        constraintType: CompositeConstraintType.unique)\r\n  ])\r\n  String description;\r\n```\r\n\r\n## Interfaces\r\n\r\n### DbOpenEntity\r\n\r\nDbOpenEntity is, as it's name suggests, a template for non restrictive models with composite primary keys.\r\nIt can also be used for non integer primary key implementation.  \r\nIt defines a single method getPrimaryKey\r\n\r\n### DbEntity\r\n\r\nCan be used for a general purpose model template with integer primary key named `id`\r\n\r\n### DbAccountEntity\r\n\r\nIt implements DbEntity.\r\nCan be used for a model template in a generic user account with the following fields:\r\n\r\n- userName\r\n- email\r\n- abbreviation\r\n- isCurrent\r\n\r\n### DbAccountRelatedEntity implements DbEntity\r\n\r\nIt implements DbEntity.\r\nCan be used for a model template in a generic, account dependent, entity with the following fields:\r\n\r\n- accountId\r\n\r\n## Usage convention\r\n\r\nThe 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:\r\n\r\n\r\n```dart\r\n@DataTable(\"a01_tests\", TableMetadata.softDeletable)\r\nclass A01Test implements DbAccountRelatedEntity {\r\n  @DataColumn(\r\n    \"id\", \r\n    metadataLevel: ColumnMetadata.primaryKey | ColumnMetadata.unique | ColumnMetadata.autoIncrement)\r\n  int id;\r\n\r\n  @DataColumn(\"account_id\", compositeConstraints: [\r\n    CompositeConstraint(\r\n        name: \"uq_account_entry\",\r\n        constraintType: CompositeConstraintType.unique)\r\n  ])\r\n  int accountId;\r\n\r\n  @DataColumn(\"description\", compositeConstraints: [\r\n    CompositeConstraint(\r\n        name: \"uq_account_entry\",\r\n        constraintType: CompositeConstraintType.unique)\r\n  ])\r\n  String description;\r\n\r\n  @DataColumn(\"record_date\")\r\n  int recordDate;\r\n}\r\n```\r\n\r\n## Concrete implementation examples\r\n\r\nThe following is a list of `f-orm-m8` implementations by supported backend database.\r\n\r\n| package name                                                           | version                                                                                                               | database | source                                                         |                                                                                           |\r\n| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\r\n| [f_orm_m8_sqlite](https://pub.dartlang.org/packages/f_orm_m8_sqlite) | [![pub package](https://img.shields.io/pub/v/f_orm_m8_sqlite.svg)](https://pub.dartlang.org/packages/f_orm_m8_sqlite) | SQLite   | [f-orm-m8-sqlite](https://github.com/matei-tm/f-orm-m8-sqlite) | ![GitHub release](https://img.shields.io/github/release-pre/matei-tm/f-orm-m8-sqlite.svg) |\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatei-tm%2Ff-orm-m8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatei-tm%2Ff-orm-m8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatei-tm%2Ff-orm-m8/lists"}