Readme

Design.md

@@ -0,0 +1,46 @@
+# Readability
+
+## Turbofish and inference
+
+Consider the following method:
+```rust
+fn left_join<E>(self) -> Self
+where
+    E: EntityTrait,
+{
+    // ...
+}
+```
+which has to be invoked like:
+```rust
+.left_join::<fruit::Entity>()
+```
+
+If we instead do:
+```rust
+fn left_join<E>(self, _: E) -> Self
+where
+    E: EntityTrait,
+{
+    // ...
+}
+```
+then the Turbofish can be omitted:
+```rust
+.left_join(fruit::Entity)
+```
+provided that `fruit::Entity` is a unit struct.
+
+## Builder pattern
+
+Instead of:
+```rust
+fn has_many(entity: Entity, from: Column, to: Column);
+
+has_many(cake::Entity, cake::Column::Id, fruit::Column::CakeId)
+```
+
+we'd prefer having a builder and stating the params explicitly:
+```rust
+has_many(cake::Entity).from(cake::Column::Id).to(fruit::Column::CakeId)
+```

README.md

@@ -17,15 +17,17 @@
 Inspired by ActiveRecord, Eloquent and TypeORM, SeaORM aims to provide you an intuitive and ergonomic 
 API to make working with databases in Rust a first-class experience.
 
+> This is an early WIP of SeaORM, and is not yet published. See [example](examples/sqlx-mysql/src/main.rs) for demo.
+
 ## Features
 
 1. Async
 
 Relying on SQLx, SeaORM is a new library with async support from day 1.
 
-2. Progressive
+2. Dynamic
 
-Built upon SeaQuery (a dynamic query builder), SeaORM allows you to build complex queries without 'fighting the ORM'.
+Built upon SeaQuery, a dynamic query builder, SeaORM allows you to build complex queries without 'fighting the ORM'.
 
 3. Testable
 
@@ -33,4 +35,18 @@ Use mock connections to write unit tests for your logic.
 
 4. API oriented
 
-Quickly build search models that help you filter, sort and paginate data in APIs.
+Quickly build search models that help you filter, sort and paginate data in APIs.
+
+## Design goals
+
+1. Intuitive and ergonomic
+
+API should state the intention clearly. Provide syntax sugar for common things.
+
+2. Fast(er) compilation
+
+Balance between compile-time checking and compilation speed.
+
+3. Avoid 'symbol soup'
+
+Avoid procedural macro if possible, use derive macro where appropriate.