Merge pull request #99 from monarch-orm/docs-improvements

Improve documentation

Author: princecodes247

docs/.vitepress/config.mts

@@ -8,7 +8,6 @@ export default defineConfig({
     nav: [
       { text: "Home", link: "/" },
       { text: "Guide", link: "/guide/getting-started" },
-      { text: "API", link: "/api/" },
     ],
 
     sidebar: [
@@ -17,16 +16,13 @@ export default defineConfig({
         items: [
           { text: "Getting Started", link: "/guide/getting-started" },
           { text: "Schemas", link: "/guide/schemas" },
+          { text: "Queries & Mutations", link: "/guide/queries-and-mutations" },
+          { text: "Query Builders", link: "/guide/query-builders" },
           { text: "Types", link: "/guide/types" },
-          { text: "Queries", link: "/guide/queries" },
+          { text: "Relations", link: "/guide/relations" },
           { text: "Operators", link: "/guide/operators" },
-          { text: "Aggregations & Relations", link: "/guide/aggregation-and-relations" },
         ],
       },
-      {
-        text: "API Reference",
-        items: [{ text: "Collection Methods", link: "/api/" }],
-      },
     ],
 
     socialLinks: [{ icon: "github", link: "https://github.com/monarch-orm/monarch" }],

docs/guide/getting-started.md

@@ -4,50 +4,55 @@
 
 ## Installation
 
-NPM:
-```bash
+::: code-group
+
+```bash [npm]
 npm install monarch-orm
 ```
 
-Or Yarn:
-```bash
+```bash [pnpm]
+pnpm add monarch-orm
+```
+
+```bash [yarn]
 yarn add monarch-orm
 ```
 
-Or PNPM:
-```bash
-pnpm add monarch-orm
+```bash [bun]
+bun add monarch-orm
 ```
 
+:::
+
 ## Basic Usage
 
 ```typescript
 import { createClient, createDatabase, createSchema, defineSchemas } from "monarch-orm";
 import { boolean, number, string } from "monarch-orm/types";
 
 const UserSchema = createSchema("users", {
-  name: string().nullable(),
-  email: string().lowercase().optional(),
-  age: number().optional().default(10),
+  name: string(),
+  email: string(),
+  age: number().default(10),
   isVerified: boolean(),
 });
 
-const client = createClient(/** db uri **/)
 const schemas = defineSchemas({
   UserSchema,
 });
 
-const { collections } = createDatabase(client.db(), schemas);
+const client = createClient("mongodb://localhost:27017/monarch-example");
+const db = createDatabase(client.db(), schemas);
 
-const newUser = await collections.users
+const newUser = await db.collections.users
   .insertOne({
     name: "anon",
     email: "anon@gmail.com",
     age: 0,
     isVerified: true,
   });
 
-const users = await collections.users.find({});
+const users = await db.collections.users.find({});
 ```
 
 ## Quick Start
@@ -72,7 +77,7 @@ const schemas = defineSchemas({
   UserSchema,
 });
 
-const { collections } = createDatabase(client.db(), schemas);
+const db = createDatabase(client.db(), schemas);
 ```
 
 ### Inserting Documents

docs/api/index.md docs/guide/queries-and-mutations.mddocs/api/index.md renamed to docs/guide/queries-and-mutations.md

@@ -1,10 +1,24 @@
-# API Documentation
+# Queries & Mutations
 
-This page provides a comprehensive list of all collection methods available in Monarch ORM.
+Once your database is initialized, every collection becomes available under `db.collections`. This object provides a fully type-safe gateway to interact with your MongoDB database.
 
-## Queries
+This page serves as an API reference for the core methods you can call directly on a collection instance to insert, update, delete, or retrieve data.
+
+## Accessing Collections
+
+You don't need to manually instantiate or wrap collections. Just access them directly off the `db.collections` object. Because of your schemas, Monarch knows exactly what data shapes are valid.
+
+```typescript
+// Access your "users" collection
+// The collection is strictly typed!
+await db.collections.users.insertOne({ name: "Alice" });
+```
+
+---
 
-Collections expose typed query methods.
+## Mutations
+
+Mutations allow you to add, modify, or delete documents. All mutations immediately execute against the database.
 
 ### `insertOne(data)`
 
@@ -28,6 +42,12 @@ await db.collections.users.insertMany([
 ]);
 ```
 
+---
+
+## Queries
+
+Queries retrieve data from the database. Unlike mutations, queries like `.find()` return a lazy builder that isn't executed until you `await` it.
+
 ### `find(filter?)`
 
 Returns a query for multiple documents. It supports `select()`, `omit()`, `sort()`, `limit()`, `skip()`, `options()`, `cursor()`, and `populate()`.