From 5d3d080ea7fcf7f64ecc0a77281c6300c84c5a90 Mon Sep 17 00:00:00 2001
From: Chris Tsang <tyt2y7@gmail.com>
Date: Mon, 17 May 2021 02:01:16 +0800
Subject: [PATCH] Readme

---
 Design.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 22 +++++++++++++++++++---
 2 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 Design.md

diff --git a/Design.md b/Design.md
new file mode 100644
index 00000000..a57e560a
--- /dev/null
+++ b/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)
+```
\ No newline at end of file
diff --git a/README.md b/README.md
index b8288adf..8ddfa54a 100644
--- a/README.md
+++ b/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.
\ No newline at end of file
+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.
\ No newline at end of file