platform/README.md

# orm
[![Pub](https://img.shields.io/pub/v/angel_orm.svg)](https://pub.dartlang.org/packages/angel_orm)
[![build status](https://travis-ci.org/angel-dart/orm.svg)](https://travis-ci.org/angel-dart/orm)

**This project is currently in the early stages, and may change at any given
time without warning.**

Source-generated ORM for use with the Angel framework. Documentation is coming soon.
This ORM can work with virtually any database, thanks to the functionality exposed by
`package:query_builder`.

Currently supported:
* PostgreSQL
* MongoDB (planned)
* RethinkDB (planned)
* In-Memory (planned)

Your model, courtesy of `package:angel_serialize`:

```dart
library angel_orm.test.models.car;

import 'package:angel_framework/common.dart';
import 'package:angel_orm/angel_orm.dart';
import 'package:angel_serialize/angel_serialize.dart';
part 'car.g.dart';

@serializable
@orm
class _Car extends Model {
  String make;
  String description;
  bool familyFriendly;
  DateTime recalledAt;
}
```

Models can still use the `@Alias()` annotation. `package:angel_orm` obeys it.

After building, you'll have access to a `Query` class with strongly-typed methods that
allow to run asynchronous queries without a headache.
You can run complex queries like:

```dart
import 'package:angel_framework/angel_framework.dart';
import 'package:postgres/postgres.dart';
import 'car.dart';
import 'car.orm.g.dart';

/// Returns an Angel plug-in that connects to a PostgreSQL database, and sets up a controller connected to it...
AngelConfigurer connectToCarsTable(PostgreSQLConnection connection) {
  return (Angel app) async {
    // Register the connection with Angel's dependency injection system.
    // 
    // This means that we can use it as a parameter in routes and controllers.
    app.container.singleton(connection);
    
    // Attach the controller we create below
    await app.configure(new CarService(connection));
  };
}

@Expose('/cars')
class CarService extends Controller {
  // The `connection` will be injected.
  @Expose('/recalled_since_2008')
  carsRecalledSince2008(PostgreSQLConnection connection) {
    // Instantiate a Car query, which is auto-generated. This class helps us build fluent queries easily.
    var cars = new CarQuery(connection);
    cars.where
      ..familyFriendly.equals(false)
      ..recalledAt.year.greaterThanOrEqualTo(2008);
    
    // Shorter syntax we could use instead...
    cars.where.recalledAt.year <= 2008;
    
    // `get()` returns a Stream.
    // `get().toList()` returns a Future.
    return cars.get().toList();
  }
  
  @Expose('/create', method: 'POST')
  createCar(PostgreSQLConnection connection) async {
    // `package:angel_orm` generates a strongly-typed `insert` function on the query class.
    // Say goodbye to typos!!!
    var car = await CarQuery.insert(connection, familyFriendly: true, make: 'Honda');
    
    // Auto-serialized using code generated by `package:angel_serialize`
    return car;
  }
}
```

# Relations
**NOTE**: This is not yet implemented.

* `@HasOne()`
* `@HasMany()`
* `@BelongsTo()`

```dart
@serializable
@orm
abstract class _Author extends Model {
  @hasMany // Use the defaults, and auto-compute `foreignKey`
  List<Book> books;
  
  // Also supports parameters...
  @HasMany(localKey: 'id', foreignKey: 'author_id', cascadeOnDelete: true)
  List<Book> books;
  
  @Alias('writing_utensil')
  @hasOne
  Pen pen;
}
```