@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/core-concepts/persistent/transactions.md

@@ -1,6 +1,9 @@
 # Transactions
 
-Ignis supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
+IGNIS supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
+
+> [!NOTE] PostgreSQL-only capability
+> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default: calling `beginTransaction()` on it throws a `501 Not Implemented` (`messageCode: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
 
 ## Using Transactions
 
@@ -14,8 +17,8 @@ const tx = await userRepo.beginTransaction({
 
 try {
   // 2. Pass transaction to operations
-  // Create user
-  const user = await userRepo.create({
+  // Create user (write methods return a { count, data } envelope)
+  const { data: user } = await userRepo.create({
     data: userData,
     options: { transaction: tx }
   });
@@ -32,29 +35,54 @@ try {
   // 3. Commit the transaction
   await tx.commit();
 } catch (err) {
-  // 4. Rollback on error
-  await tx.rollback();
-  throw err;
+  // 4. Rollback on error. Nest it: rollback() throws if ROLLBACK itself fails, and a bare
+  //    `await tx.rollback()` here would replace `err` with the rollback error.
+  try {
+    await tx.rollback();
+  } catch (rollbackError) {
+    logger.error('Rollback failed | %s', rollbackError);
+  }
+
+  throw err; // the original cause survives
 }
 ```
 
+> [!WARNING] `commit()` and `rollback()` throw on failure
+> `COMMIT` can genuinely fail - a deadlock, a serialization failure under `SERIALIZABLE`, a dropped
+> connection, a deferred constraint firing at commit time. When it does, `commit()` throws rather
+> than resolving, so you never report success on a write that was never persisted. The connection is
+> then destroyed instead of being returned to the pool, because it may still hold an open
+> transaction that the next borrower would inherit.
+>
+> `rollback()` behaves the same way when it is the FIRST verb to fail. One deliberate exception
+> keeps the everyday `catch { await tx.rollback(); throw error; }` pattern safe: calling
+> `rollback()` on a transaction that already ended BY FAILURE (a failed `COMMIT` or a failed prior
+> `ROLLBACK`) is a silent no-op - nothing was committed and the connection is already destroyed, so
+> the rollback's goal is achieved and your original error survives. The nested-try form above is
+> still the safest general pattern, because a FIRST rollback that itself fails does throw.
+>
+> The destroy half is **driver-specific**: node-postgres (`pg`) discards the poisoned connection,
+> but postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so under the
+> postgres-js driver the connection returns to the pool anyway. See
+> [Postgres Drivers & Supabase](./postgres-drivers) for the full asymmetry.
+
 ## Transaction Object
 
-The transaction object returned by `beginTransaction()` has the following properties:
+`beginTransaction()` returns an `IDatabaseTransaction` with the following properties:
 
 | Property/Method | Type | Description |
 | :--- | :--- | :--- |
-| `connector` | `TNodePostgresConnector` | A Drizzle connector bound to the transaction's database client |
+| `connector` | `TRelationalConnector<Schema>` | A Drizzle connector bound to the transaction's dedicated connection |
 | `isolationLevel` | `TIsolationLevel` | The isolation level of this transaction |
 | `isActive` | `boolean` | Whether the transaction is still active (not yet committed/rolled back) |
-| `commit()` | `Promise<void>` | Commit the transaction and release the connection |
-| `rollback()` | `Promise<void>` | Rollback the transaction and release the connection |
+| `commit()` | `Promise<void>` | Commit and release the connection. **Throws** if `COMMIT` fails, and destroys the connection rather than pooling it |
+| `rollback()` | `Promise<void>` | Rollback and release the connection. **Throws** if `ROLLBACK` fails, and destroys the connection rather than pooling it |
 
-Calling `commit()` or `rollback()` on an already-ended transaction throws an error.
+Calling `commit()` or `rollback()` on an already-ended transaction throws an error, with one exception: `rollback()` after the transaction ended BY FAILURE is a silent no-op (see the warning above).
 
 ## Isolation Levels
 
-Ignis supports standard PostgreSQL isolation levels:
+IGNIS supports standard PostgreSQL isolation levels:
 
 | Level | Description | Use Case |
 |-------|-------------|----------|
@@ -63,17 +91,17 @@ Ignis supports standard PostgreSQL isolation levels:
 | `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
 
 > [!NOTE]
-> Ignis only supports these three levels. `READ UNCOMMITTED` is **not** accepted — PostgreSQL treats it as `READ COMMITTED` anyway, so Ignis omits it to avoid confusion.
+> IGNIS only supports these three levels. The fourth SQL-standard level (uncommitted reads) is **not** accepted - PostgreSQL treats it as `READ COMMITTED` anyway, so IGNIS omits it to avoid confusion.
 
 ## Best Practices
 
-1.  **Always use `try...catch`**: Ensure `rollback()` is called on error to release the connection back to the pool.
+1.  **Always use `try...catch`, and nest the rollback**: `rollback()` throws when `ROLLBACK` fails, so a bare `await tx.rollback()` inside a `catch` would discard the error that sent you there. Wrap it in its own `try...catch`, log the rollback failure, and rethrow the original cause.
 2.  **Keep it short**: Long-running transactions hold database connections from the pool and can cause connection exhaustion.
 3.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
 
 ```typescript
 // Service method supporting transactions
-async createInitialOrder(opts: { userId: string; transaction?: ITransaction }) {
+async createInitialOrder(opts: { userId: string; transaction?: IDatabaseTransaction }) {
   return this.orderRepository.create({
     data: { userId: opts.userId, status: 'PENDING' },
     options: { transaction: opts.transaction } // Forward the transaction
@@ -99,12 +127,12 @@ export class OrderService extends BaseService {
   async createOrderWithItems(opts: {
     orderData: TOrderCreate;
     items: TOrderItemCreate[];
-    transaction?: ITransaction;
+    transaction?: IDatabaseTransaction;
   }) {
     const { orderData, items, transaction } = opts;
 
     // Create order
-    const order = await this._orderRepository.create({
+    const { data: order } = await this._orderRepository.create({
       data: orderData,
       options: { transaction },
     });
@@ -138,7 +166,7 @@ export class OrderController extends BaseRestController {
 
   @post({ configs: OrderRoutes.CREATE })
   async createOrder(c: TRouteContext) {
-    const body = c.req.valid<{ order: any; items: any[] }>('json');
+    const body = await c.req.json<{ order: TOrderCreate; items: TOrderItemCreate[] }>();
 
     const tx = await this._orderRepository.beginTransaction({
       isolationLevel: 'SERIALIZABLE',
@@ -154,7 +182,12 @@ export class OrderController extends BaseRestController {
       await tx.commit();
       return c.json(order, HTTP.ResultCodes.RS_2.Created);
     } catch (err) {
-      await tx.rollback();
+      try {
+        await tx.rollback();
+      } catch (rollbackError) {
+        this.logger.error('Rollback failed | %s', rollbackError);
+      }
+
       throw err;
     }
   }
@@ -163,15 +196,18 @@ export class OrderController extends BaseRestController {
 
 ## How Transactions Work Internally
 
-When you pass a `transaction` option to a repository method, the repository uses the transaction's `connector` (a Drizzle instance bound to the transaction's `PoolClient`) instead of the default datasource connector. This ensures all operations within the transaction use the same database connection and see a consistent view of the data.
+When you pass a `transaction` option to a repository method, the repository uses the transaction's `connector` (a Drizzle instance bound to the transaction's dedicated connection) instead of the default datasource connector. This ensures all operations within the transaction use the same database connection and see a consistent view of the data.
 
 ```typescript
-// Inside AbstractRepository (simplified)
-protected resolveConnector(opts?: { transaction?: ITransaction }) {
-  if (opts?.transaction) {
-    return opts.transaction.connector;
+// Inside PostgresBaseRepository (simplified)
+protected resolveConnector(opts?: { transaction?: IDatabaseTransaction }) {
+  if (!opts?.transaction) {
+    return this.dataSource.connector;
   }
-  return this.dataSource.connector;
+
+  // Throws if the transaction has already been committed/rolled back,
+  // or if it is not a postgres transaction.
+  return opts.transaction.connector;
 }
 ```
 

package/content/guides/core-concepts/rest-controllers.md

@@ -1,6 +1,6 @@
 # REST Controllers
 
-REST controllers handle incoming HTTP requests and return JSON responses -- they are your API endpoints. This is the default transport in Ignis and covers the majority of use cases.
+REST controllers handle incoming HTTP requests and return JSON responses -- they are your API endpoints. This is the default transport in IGNIS and covers the majority of use cases.
 
 > **Deep Dive:** See [REST Controllers Reference](../../references/base/controllers.md) for the complete API.
 
@@ -9,8 +9,9 @@ REST controllers handle incoming HTTP requests and return JSON responses -- they
 Extend `BaseRestController` and use decorators to define routes:
 
 ```typescript
-import { BaseRestController, controller, get, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { BaseRestController, controller, get, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 @controller({ path: '/users' })
 export class UserController extends BaseRestController {
@@ -55,7 +56,7 @@ For decorator-based routes, you do not need to explicitly annotate the return ty
 
 ### HTTP Method Decorators
 
-`Ignis` provides a decorator for each common HTTP method:
+`IGNIS` provides a decorator for each common HTTP method:
 
 -   `@get(opts)`
 -   `@post(opts)`
@@ -132,7 +133,7 @@ export class MyItemsController extends BaseRestController {
 
 ## Manual Route Definition: An Alternative Approach
 
-While decorators are the recommended approach for most use cases, `Ignis` also provides a manual way to define routes within the controller's `binding()` method.
+While decorators are the recommended approach for most use cases, `IGNIS` also provides a manual way to define routes within the controller's `binding()` method.
 
 ### Decorator vs Manual: Quick Comparison
 
@@ -161,8 +162,9 @@ When using this method, you will override the `binding()` method in your control
 Use this method for defining a single API endpoint with all its configurations and handler. It also benefits from type inference when used with `TRouteContext`.
 
 ```typescript
-import { Authentication, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { Authentication, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 // ... inside the binding() method
 
@@ -189,8 +191,9 @@ this.defineRoute({
 This method offers a fluent API for defining routes, similar to `defineRoute`, but structured for chaining. It also benefits from `TRouteContext` for type safety.
 
 ```typescript
-import { jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 // ... inside the binding() method
 
@@ -215,7 +218,7 @@ this.bindRoute({
 
 ## `ControllerFactory` for CRUD Operations
 
-For standard CRUD (Create, Read, Update, Delete) operations, `Ignis` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
+For standard CRUD (Create, Read, Update, Delete) operations, `IGNIS` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
 
 ```typescript
 // src/controllers/configuration/configuration.controller.ts (Example from @examples/vert)
@@ -363,7 +366,7 @@ export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, chil
 };
 ```
 
-> **Note:** JSX support in `Ignis` uses Hono's built-in JSX runtime. Make sure your `tsconfig.json` includes the JSX configuration (this is already set up in the framework's base configuration).
+> **Note:** JSX support in `IGNIS` uses Hono's built-in JSX runtime. Make sure your `tsconfig.json` includes the JSX configuration (this is already set up in the framework's base configuration).
 
 ## Accessing Validated Request Data
 
@@ -454,7 +457,7 @@ Using `TRouteContext` provides a typed context object. By using `c.req.valid<T>(
 - **References:**
   - [BaseRestController API](/references/base/controllers) - Complete REST controller API reference
   - [Middlewares](/references/base/middlewares) - Request interceptors
-  - [Swagger Component](/extensions/components/swagger) - Auto-generate API docs
+  - [Swagger Component](/extensions/components/api-reference) - Auto-generate API docs
   - [Schema Utilities](/references/utilities/schema) - Request/response helpers
 
 - **Tutorials:**