CONTRIBUTING.md

Contribute to Cotton

There are still a lot of room for improvements. Here are some features that are not available yet:

Query Buider

Here are some query expressions that haven't implemented yet.

• MIN, MAX, SUM, AVG
• RAW SQL
• INCREMENT & DECREMENT

We also want to add some features like:

• Add custom SQL query string.
• Nested queries (combining AND & OR hierarchically).

Adapter

• Connect via URL

Migrations

• Add index in TableBuilder
• Drop table column for SQLite in TableBuilder
• Seeder
• Factory

Manager

• Hooks
• JSON field
• Array field

Roadmap to v1.0

• Database Adapters
  • ✅ SQLite3 (via sqlite)
  • ✅ MySQL (via deno_mysql)
  • 🚧 MariaDB (wait for deno_mysql to fully support it)
  • ✅ PostgresQL (via postgres)
• 🚧 Query Builder
• ✅ Object-Relational Mapper
  • ✅ Model Manager
  • ✅ Base Model
  • ✅ Model query
  • ✅ Bulk insert
  • ✅ Bulk remove
  • 🚧 Relationships (only one-to-many)
  • ❌ Hooks
  • ❌ Timestamps
• ✅ Command-line tool
  • ✅ Migrations
  • 🚧 Seeder
• 🚧 Model serializer (only in serializer branch)
  • ✅ Serializing "dumping"
  • ✅ Deserializing "loading"
  • ❌ Validating
  • ❌ Sanitizing

Testing

Please make sure that you are implementing tests for the features that you're working on.

To run the tests, you need to have Docker and Docker Compose installed on your machine.

Then, execute the following command.

./test.sh

This will fire up Docker Compose and initialize 3 services. MySQL and Postgres database, and the test container itself that runs all the test code.

To clean up everything, run:

docker-compose down --volumes

Writing tests

There are two types of tests that we should care about, unit test and integration test. You don't have to use both of them all the time because it really depends on the feature that you're working on. If you're working on a utility function that doesn't have to access the database, unit test is the way to go. If the feature is accesing the database through high-level abstraction such as Model Manager and Query Builder, you can still use unit test and them using mock library which served from the testdeps.ts file.

To make a unit test, you can simply use the Deno.test function.

Deno.test("Manager.save() -> should save a model", () => {
  // ...
});

However, there are some features that need to test end-to-end, such as model manager and migrations. That's why we've written a utility function to make an integration test called testDB. It works exactly like Deno.test but you'll get an Adapter instance within the parameter and it'll create three tests for PostgreSQL, MySQL, and SQLite.

Deno.test("Manager.save() -> should save a model", (client) => {
  // ...
});