From 9b026f1a514ce531f7799da5dce6cc1fa0686320 Mon Sep 17 00:00:00 2001
From: Acellam Guy <acellam.guy@gmail.com>
Date: Sun, 11 Aug 2024 16:59:08 +0300
Subject: [PATCH] docs(pkg): add basic developer guide

---
 .env.example |  5 ++++
 README.md    | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 84 insertions(+), 3 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..2dfe1ca
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,5 @@
+#PRODUCTION
+RDBMS_DATABASE_URI="mysql://DATBASE_USER:DATABASE_PASSWORD@DATABASE_HOST:DATABASE_PORT/DATABASE_DB"
+NOSQL_DATABASE_URI="mongodb://DATABASE_HOST:DATABASE_PORT/DATABASE_DB"
+NOSQL_DATABASE_ADAPTER="mongodb"
+API_BASE='/v1/'
diff --git a/README.md b/README.md
index edd0f7f..aafee89 100644
--- a/README.md
+++ b/README.md
@@ -21,11 +21,87 @@ A library responsible for representing business data.
 
 This library follows the `Active Record Pattern` by building a wrapper on top of popular orm such as [Mongoose](https://www.npmjs.com/package/mongoose) and [Sequelize](https://www.npmjs.com/package/sequelize) to support all kinds of databases
 
+## ⚙️ How to use the package in project
+1. You should create the following environment variables in your node project.
+```env
+RDBMS_DATABASE_URI="mysql://DATBASE_USER:DATABASE_PASSWORD@DATABASE_HOST:DATABASE_PORT/DATABASE_DB"
+NOSQL_DATABASE_URI="mongodb://DATABASE_HOST:DATABASE_PORT/DATABASE_DB"
+NOSQL_DATABASE_ADAPTER="mongodb"
+```
+2. Once the variables have been set. You should create a model base on the active record `SchemaProperty`. See example below
+
+```typescript
+import { ActiveRecord } from "@fractalerp/active-record-js"
+
+export interface ITaskModelDocument {
+  name: string;
+  description: string;
+}
+
+const TaskModelSchema = {
+  name: {
+    type: String,
+    required: true,
+    unique: true
+  },
+  description: {
+    type: String,
+    default: null
+  }
+};
+
+export const TaskModel = new ActiveRecord<ITaskModelDocument>("Task", TaskModelSchema);
+
+```
+3. Then use its methods to perform data management. The following methods are supported;
+
+|Method|Description|
+|------------------|-----------|
+|`find`|returns list of data objects|
+|`findOne`|returns one data item|
+|`create`|save item to the data store|
+|`update`|updates the record in the store|
+|`delete`|delete item from the data store|
 
-## 🪲 Issues, suggestions and feature requests
-👩‍🚒 We are failing to get the published NPM package working. Someone can fix it and send a pull request.
+Since we support all kinds of databases. The following are the respective methods of the two kinds of databases.
+
+This only applies to `NOSQL databases`
+
+|Method|Description|
+|------------------|-----------|
+|`aggregate`|peform aggregate action based on a pipeline|
+|`index`|create an index in the document store|
+
+This only applies to `Relational databases`
+
+|Method|Description|
+|------------------|-----------|
+|`query`|create a raw `SQL` to send to database|
+|`beginTransaction`|start a transaction|
+|`commitTransaction`|persist a transaction|
+|`rollbackTransaction`|rollback a transaction|
+
+Other than that, all the other ORM respective methods for `Sequelize` and `Mongoose` are supported by default.
+
+4. Finally you can use the model to peform data action. See example.
+
+```typescript
+// create task
+const task = await TaskModel.create({
+    name: 'Use fractalerp active record js',
+    description: 'Change all models'
+});
 
-In the mean time, you can just include the module as part of the project and use it 🚀
+// Find one task
+const task = await TaskModel.findOne({ id: 'cbdabs-29232323-msasd'});
+```
+
+## 🫶 Projects using this package
+See the projects using this package in action.
+- [Fractal Js](https://github.com/fractalerp/fractal-js)
+- [Fractalerp core](https://github.com/fractalerp/fractal-core)
+
+## 🪲 Issues, suggestions and feature requests
 
 We are actively maintaining this boilerplate, please report any issues or suggestion for improvement at https://github.com/fractalerp/active-record-js/issues