Merge pull request #36 from fastapi-startkit/docs/fix-misc-issues

docs: fix database examples, models gaps, remove queue stub, minor fixes

Author: bedus-creation

.vitepress/config.mts

@@ -155,6 +155,7 @@ export default defineConfig({
                 items: [
                     { text: 'Getting Started', link: '/docs/getting-started' },
                     { text: 'Configuration', link: '/docs/configuration' },
+                    { text: 'Config Component', link: '/docs/config' },
                     { text: 'FastAPI', link: '/docs/fastapi' },
                     { text: 'Exception Handling', link: '/docs/exception-handling' },
                     { text: 'Logging', link: '/docs/logging' },

docs/ai/agent.md

@@ -142,7 +142,7 @@ Apply decorators directly to the class to configure it declaratively:
 
 | Decorator | Default | Description |
 |---|---|---|
-| `@provider(name)` | `"anthropic"` | LLM provider: `"anthropic"`, `"openai"`, or `"google"` |
+| `@provider(name)` | `AI_PROVIDER` env var (default: `google`) | LLM provider: `"anthropic"`, `"openai"`, or `"google"` |
 | `@model(name)` | provider default | Model identifier (e.g. `"claude-sonnet-4-6"`, `"gpt-4o"`) |
 | `@max_tokens(n)` | `4096` | Maximum output tokens per response |
 | `@max_steps(n)` | `10` | Maximum agentic loop iterations before stopping |

docs/database/casts.md

@@ -20,7 +20,7 @@ Casts automatically transform model attribute values when reading from or writin
 | `dict` | JSON | `'{"key":"val"}'` → `{"key": "val"}`          |
 | `list` | JSON | `'["a","b"]'` → `["a", "b"]`                  |
 | `datetime` | DateTime | `"2024-01-01 08:00:00"` → `datetime.datetime` |
-| `date` | DateTime | `"2024-01-01"` → `datetiem.date`              |
+| `date` | DateTime | `"2024-01-01"` → `datetime.date`              |
 | `Carbon` | DateTime | `"2024-01-01 00:00:00"` → `Carbon`            |
 | `time` | Time | `"09:00:00"` → `datetime.time`                |
 | `timedelta` | TimeDelta | `3600.0` → `datetime.timedelta(seconds=3600)` |

docs/database/index.md

@@ -78,8 +78,7 @@ This will create a `config/database.py` file in your project. Alternatively, you
 
 ```python
 # config/database.py
-from dataclasses import field
-from pydantic.dataclasses import dataclass
+from dataclasses import dataclass, field
 from fastapi_startkit.environment import env
 from fastapi_startkit.masoniteorm import MySQLConfig, SQLiteConfig
 
@@ -88,20 +87,17 @@ class DatabaseConfig:
     default: str = field(default_factory=lambda: env("DB_CONNECTION", "sqlite"))
 
     connections: dict = field(default_factory=lambda: {
-        "sqlite": DatabaseConnection(
+        "sqlite": SQLiteConfig(
             driver="sqlite",
             database=env("DB_DATABASE", "database.sqlite"),
         ),
-        "mysql": DatabaseConnection(
+        "mysql": MySQLConfig(
             driver="mysql",
             host=env("DB_HOST", "127.0.0.1"),
             database=env("DB_DATABASE", "app"),
             username=env("DB_USERNAME", "root"),
             password=env("DB_PASSWORD", ""),
             port=env("DB_PORT", "3306"),
-            options={
-                "charset": "utf8mb4"
-            }
         ),
     })
 

docs/database/models.md

@@ -77,6 +77,66 @@ user = await User.where("email", "admin@example.com").first()
 posts = await Post.where("user_id", 1).get()
 ```
 
+### `find_or_fail(id)` — find or raise
+
+Fetch a record by primary key, raising `ModelNotFoundException` if nothing is found:
+
+```python
+user = await User.find_or_fail(1)
+```
+
+### `first_or_fail()` — first or raise
+
+Execute the current query and raise `ModelNotFoundException` if no record matches:
+
+```python
+user = await User.where("email", "admin@example.com").first_or_fail()
+```
+
+### `exists()` — check existence
+
+Return `True` if any record matches the current query, `False` otherwise:
+
+```python
+active = await User.where("is_active", True).exists()
+```
+
+### `count()` — row count
+
+Return the number of rows matching the current query:
+
+```python
+total = await User.count()
+active_count = await User.where("is_active", True).count()
+```
+
+### `paginate(per_page, page)` — paginate results
+
+Return a `LengthAwarePaginator` containing the requested slice of records plus total-count metadata:
+
+```python
+page = await User.paginate(per_page=15, page=1)
+# page.items      → list of User instances
+# page.total      → total number of matching rows
+# page.last_page  → last available page number
+```
+
+### `or_where` / `where_raw` / `or_where_raw` / `or_where_null` — raw & OR variants
+
+```python
+# OR condition
+users = await User.where("role", "admin").or_where("role", "moderator").get()
+
+# Raw SQL predicate
+users = await User.where_raw("created_at > NOW() - INTERVAL '7 days'").get()
+
+# Raw SQL with OR
+users = await User.where("is_active", True).or_where_raw("role = 'superadmin'").get()
+
+# OR IS NULL
+users = await User.where("name", "Alice").or_where_null("deleted_at").get()
+```
+
 ## Creating Records
 
 ### `create`

docs/exception-handling.md

@@ -4,6 +4,7 @@ title: Exception Handling
 description: Robust exception handling and custom error responses in Fastapi Startkit.
 keywords: error handling, exceptions, fastapi, debugging
 ---
+
 # Exception Handling
 
 The framework provides a centralized `ExceptionHandler` that handles reporting (logging) and rendering (HTTP responses) for exceptions across both web and CLI contexts.

docs/frontend/inertia.md

@@ -4,6 +4,7 @@ title: Inertia
 description: Build modern single-page applications without the complexity of a separate API using Inertia.js and Fastapi Startkit.
 keywords: inertia, spa, frontend, fastapi, monolithic
 ---
+
 # Inertia
 
 [Inertia.js](https://inertiajs.com) is a protocol that bridges your server and frontend, letting you build full-stack single-page applications without building a separate API. Instead of writing REST endpoints and consuming them with `fetch()`, you write controllers that return component names and props — Inertia takes care of the rest.

docs/jsonapi.md

@@ -1,4 +1,5 @@
 ---
+outline: deep
 title: JSON:API Resources
 description: Build JSON:API-compliant responses with JsonResource — automatic serialization, hidden fields, pagination meta, fluent chain API for fields and includes.
 ---