docs: populate usage and some minor adjustments

Author: Akalanka47000

docs/auditing/the-audit-model.md

@@ -9,18 +9,18 @@ The Audit model is a special model that is used to log changes to other models.
 ```go
 var AuditModel = NewModel[Audit]("Audit", NewSchema(map[string]Field{
 	"Entity": {
-		Type:     reflect.String,
+		Type:     elemental.String,
 		Required: true,
 	},
 	"Type": {
-		Type: reflect.String,
+		Type: elemental.String,
 	},
 	"Document": {
-		Type:     reflect.Map,
+		Type:     elemental.Map,
 		Required: true,
 	},
 	"User": {
-		Type: reflect.String,
+		Type: elemental.String,
 	},
 }, SchemaOptions{
 	Collection: "audits",

docs/getting-started/create-a-schema.md

@@ -16,26 +16,26 @@ A schema is a blueprint for your data model. It defines the structure of your da
 unique := true
 schema := elemental.NewSchema(map[string]elemental.Field{
 	"Name": {
-		Type:     reflect.String,
+		Type:     elemental.String,
 		Required: true,
-		Index: options.Index().SetUnique(true),
+		Index:    options.Index().SetUnique(true),
 	},
 	"Age": {
-		Type:    reflect.Int,
+		Type:    elemental.Int,
 		Default: DefaultAge,
 	},
 	"Occupation": {
-		Type: reflect.String,
+		Type: elemental.String,
 	},
 	"School": {
-		Type: reflect.String,
+		Type: elemental.String,
 	},
 	"Weapons": {
-		Type:    reflect.Slice,
+		Type:    elemental.Slice,
 		Default: []string{},
 	},
 	"Retired": {
-		Type:    reflect.Bool,
+		Type:    elemental.Bool,
 		Default: false,
 	},
 }, elemental.SchemaOptions{
@@ -47,7 +47,7 @@ schema := elemental.NewSchema(map[string]elemental.Field{
 
 Each field in a schema is defined by a `Field` struct. The `Field` struct has the following properties:
 
-- **Type**: The data type of the field. This can be any of the types supported by the `reflect` package.
+- **Type**:  The data type of the field. Can be of reflect.Kind, reflect.Type, an Elemental alias such as elemental.String or a custom reflection
 
 - **Required**: A boolean value that indicates whether the field is required or not.
 
@@ -59,9 +59,9 @@ Each field in a schema is defined by a `Field` struct. The `Field` struct has th
 
 - **Length**: The length of the field.
 
-- **Regex**: A regular expression pattern that the field must match.
+- **Regex**: A regular expression (*regexp.Regexp) that the field must match.
 
-- **Index**: An `IndexOptions` struct that defines the indexing options for the field.
+- **Index**: A pointer to an `IndexOptions` struct that defines the indexing options for the field.
 
 - **IndexOrder**: The order in which the field should be indexed.
 

docs/getting-started/type-inference.md

@@ -20,4 +20,6 @@ That being said, manual type assertion is still a pain and we want to make it as
 
 - `ExecInt()` - Executes the query and returns the result as an `int`. This method is useful for queries that return a single integer value, such as count queries or schedule queries which return a cron entry ID.
 
-- `ExecSS()` - Executes the query and returns the result as a slice of strings. This method is useful for queries that return an array of strings, such as distinct queries.
+- `ExecSS()` - Executes the query and returns the result as a slice of strings. This method is useful for queries that return an array of strings, such as distinct queries.
+
+- `ExecInto()` - Executes the query and unmarshals the result into the provided result variable. It is useful when you want to extract results into a custom struct other than the model type such as when you populate certain fields.

docs/indexing/creating-indexes.md

@@ -9,7 +9,7 @@ Indexes can be defined within a Schema under the `Index` field. This field accep
 ```go
 schema := elemental.NewSchema(map[string]elemental.Field{
 	"Vitality": {
-		Type:     reflect.Int,
+		Type:     elemental.Int,
 		Required: true,
 		Index: options.Index().SetUnique(true),
 	},

docs/middleware/lifecycle-hooks.md

@@ -4,13 +4,15 @@ sidebar_position: 1
 
 # Lifecycle Hooks
 
-Elemental provides a way to inject custom logic into the lifecycle of a model. This is done by defining middleware functions that are executed at specific points in the lifecycle of a model.
+Elemental provides a way to inject custom logic into the lifecycle of a model. This is done by defining middleware functions that are executed at specific points in its lifecycle.
 
 ## Middleware Functions
 
-Middleware functions are functions that are executed at specific points in the lifecycle of a model. They are defined as methods on a model and are executed in the order they are defined.
+Middleware functions are model methods which you can invoke to register custom callbacks/handlers to be executed before or after certain operations. They are executed in the order they are defined.
 
-You can define any number of middleware functions on a model. Each middleware function is passed in necessary arguments related to the current operation such as the document being operated on.
+You can define any number of middleware functions on a single model. Each middleware function is passed in necessary arguments as pointers related to the current operation such as the document being operated on or the filters being used. **Since these arguments are pointers, you can modify them within the middleware function in any way you want.**
+
+Each middleware function returns a boolean value indicating whether the operation should continue or not. If the middleware function returns `false`, the operation will be aborted and no further middleware functions will be executed.
 
 There are 2 categories of middleware functions in Elemental:
 
@@ -20,8 +22,8 @@ There are 2 categories of middleware functions in Elemental:
 ## Example Usage
 
 ```go
-WitcherModel.PreSave(func(witcher Witcher) bool {
-	fmt.Println("PreSave middleware executed", witcher.Name)
+WitcherModel.PreSave(func(witcher *bson.M) bool {
+	fmt.Println("PreSave middleware executed", *witcher)
 	return true
 })
 ```
@@ -38,6 +40,7 @@ In the example above, we define a `PreSave` middleware function on the `WitcherM
 - **PreDeleteMany**: Executed before multiple documents are deleted from the database.
 - **PreFindOneAndUpdate**: Executed before a single document is updated in the database.
 - **PreFindOneAndDelete**: Executed before a single document is deleted from the database.
+- **PreFindOneAndReplace**: Executed before a single document is replaced in the database.
 
 ### Post Middleware Functions
 

docs/querybuilder/or-fail.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 26
+sidebar_position: 27
 ---
 
 # Or Fail

docs/querybuilder/populate.md

@@ -0,0 +1,149 @@
+---
+sidebar_position: 26
+---
+
+# Populate
+
+Populate is a method that allows you to retrieve related documents from other collections based on references defined in your schema. The retrieved documents are automatically embedded into the results of your query.
+
+This is particularly useful for fetching associated data without having to perform multiple queries manually as well as for reducing the number of queries made to the database. This uses `$lookup` under the hood, which is a MongoDB aggregation stage that allows you to join documents from different collections.
+
+## Usage
+
+### Type definitions
+
+Population is a bit tricky to work with in Go due to its type system. Here we utilize the power of generics to define a flexible population structure that can work with any type of documents.
+
+
+```go
+type Kingdom struct {
+	ID        primitive.ObjectID `json:"_id" bson:"_id"`
+	Name      string             `json:"name" bson:"name"`
+	CreatedAt time.Time          `json:"created_at" bson:"created_at"`
+	UpdatedAt time.Time          `json:"updated_at" bson:"updated_at"`
+}
+
+type Monster struct {
+	ID         primitive.ObjectID `json:"_id" bson:"_id"`
+	Name       string             `json:"name" bson:"name"`
+	Category   string             `json:"category,omitempty" bson:"category,omitempty"`
+	CreatedAt  time.Time          `json:"created_at" bson:"created_at"`
+	UpdatedAt  time.Time          `json:"updated_at" bson:"updated_at"`
+}
+
+type GenericBestiary[T any, Y any] struct {
+	ID      primitive.ObjectID `json:"_id" bson:"_id"`
+	Monster T                  `json:"monster" bson:"monster"`
+	Kingdom Y                  `json:"kingdom" bson:"kingdom"`
+}
+
+type Bestiary = GenericBestiary[any, any]
+
+type DetailedBestiary = GenericBestiary[Monster, Kingdom]
+
+type PartiallyDetailedBestiary = GenericBestiary[Monster, primitive.ObjectID]
+
+```
+
+### Model definition
+
+```go
+BestiaryModel := elemental.NewModel[Bestiary]("Bestiary", elemental.NewSchema(map[string]elemental.Field{
+	"Monster": {
+		Type: elemental.ObjectID,
+		Ref:  "Monster",
+	},
+	"Kingdom": {
+		Type: elemental.ObjectID,
+		Ref:  "Kingdom",
+	},
+}))
+```
+
+In the example above, we define a `Bestiary` model with two fields, `Monster` and `Kingdom`, which are references to other Elemental models. You can also directly provide a `Collection` attribute into a field instead of using the `Ref` attribute, which is a bit faster to work with and also allows to use a different collection name than the one registered in the referenced model.
+
+
+### Querying with Populate
+
+To use the `Populate` method, you can chain it to your query. The `Populate` method accepts a list of fields to populate and you can use it in a variety of ways depending on your preference. 
+
+There is no limitation on the number of fields you can populate, and it can be chained alongside other Elemental query methods.
+
+Note that with `Populate` we use the `ExecInto` method to retrieve the results into a custom type since the base type of the model is not sufficient to hold the populated data and may even fail to unmarshal the results correctly.
+
+```go
+var bestiaries []DetailedBestiary
+
+BestiaryModel.Find().Populate("Monster", "Kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate("monster", "kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate("Monster").Populate("Kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate("monster").Populate("kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate("monster kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate([]string{"Monster", "Kingdom"}).ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate(primitive.M{
+    "path": "monster",
+    "pipeline": []primitive.M{
+        {"$addFields": primitive.M{
+            "category": primitive.M{"$toLower": "$category"},
+        }},
+    },
+}, "Kingdom").ExecInto(&bestiaries)
+
+// or
+
+BestiaryModel.Find().Populate(primitive.M{
+    "path": "monster",
+    "select": primitive.M{
+        "name": 1,
+        "category": 1,
+    },
+}).Populate("Kingdom").ExecInto(&bestiaries)
+```
+
+#### You can even just populate one field if you want to:
+
+```go
+var bestiaries []PartiallyDetailedBestiary
+
+BestiaryModel.Find().Populate("Monster").ExecInto(&bestiaries)
+```
+
+### Creating a new document with a referenced document
+
+When creating a new document with a reference to another document, you can directly pass the document as the value of the field. Elemental will automatically handle the reference and store the ObjectID of the referenced document.
+
+```go
+monster := MonsterModel.Create(Monster{
+    Name: "Griffin",
+    Category: "Beast",
+}).Exec()
+
+kingdom := KingdomModel.Create(Kingdom{
+    Name: "Temeria",
+}).Exec()
+
+bestiary := BestiaryModel.Create(Bestiary{
+    Monster: monster,
+    Kingdom: kingdom,
+}).ExecT()
+
+fmt.Println("Bestiary created with ID:", bestiary.ID.Hex())
+```