@venizia/ignis-docs 0.0.8 → 0.2.0

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

@@ -6,11 +6,11 @@ Models define your data structure using Drizzle ORM schemas. A model is a single
 
 ```typescript
 // src/models/entities/user.model.ts
-import { BaseEntity, generateIdColumnDefs, generateTzColumnDefs, model } from '@venizia/ignis';
+import { BasePostgresEntity, generateIdColumnDefs, generateTzColumnDefs, model } from '@venizia/ignis';
 import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   // Define schema as static property
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
@@ -28,7 +28,7 @@ export class User extends BaseEntity<typeof User.schema> {
 
 - Schema is defined inline as `static override schema`
 - Relations are defined as `static override relations`
-- No constructor needed - BaseEntity auto-discovers from static properties
+- No constructor needed - BasePostgresEntity auto-discovers from static properties
 - Type parameter uses `typeof User.schema` (self-referencing)
 
 ## Creating a Model with Relations
@@ -36,7 +36,7 @@ export class User extends BaseEntity<typeof User.schema> {
 ```typescript
 // src/models/entities/configuration.model.ts
 import {
-  BaseEntity,
+  BasePostgresEntity,
   generateDataTypeColumnDefs,
   generateIdColumnDefs,
   generateTzColumnDefs,
@@ -49,7 +49,7 @@ import { foreignKey, index, pgTable, text, unique } from 'drizzle-orm/pg-core';
 import { User } from './user.model';
 
 @model({ type: 'entity' })
-export class Configuration extends BaseEntity<typeof Configuration.schema> {
+export class Configuration extends BasePostgresEntity<typeof Configuration.schema> {
   static override schema = pgTable(
     'Configuration',
     {
@@ -114,11 +114,10 @@ Enrichers are helper functions that generate common database columns automatical
 ```typescript
 static override schema = pgTable('User', {
   id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
-  status: text('status').notNull().default('ACTIVE'),
-  createdBy: text('created_by'),
-  modifiedBy: text('modified_by'),
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   modifiedAt: timestamp('modified_at', { withTimezone: true }).notNull().defaultNow(),
+  createdBy: text('created_by'),
+  modifiedBy: text('modified_by'),
   // ... your fields
 });
 ```
@@ -127,9 +126,12 @@ static override schema = pgTable('User', {
 
 ```typescript
 static override schema = pgTable('User', {
-  ...generateIdColumnDefs({ id: { dataType: 'string' } }),  // id (text with UUID default)
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),   // id (text with UUID default)
   ...generateTzColumnDefs(),                                 // createdAt, modifiedAt
-  ...generateUserAuditColumnDefs(),                          // createdBy, modifiedBy
+  ...generateUserAuditColumnDefs({
+    created: { dataType: 'string', columnName: 'created_by' },
+    modified: { dataType: 'string', columnName: 'modified_by' },
+  }),                                                        // createdBy, modifiedBy
   // ... your fields
 });
 ```
@@ -144,7 +146,7 @@ static override schema = pgTable('User', {
 | `generateDataTypeColumnDefs()` | `dataType`, `tValue`, `nValue`, etc. | Configuration tables |
 
 :::note User Audit Options
-The `generateUserAuditColumnDefs` enricher supports an `allowAnonymous` option (default: `true`). Set to `false` to require authenticated user context and throw errors for anonymous operations:
+The `generateUserAuditColumnDefs` enricher defaults both columns to `dataType: 'number'` (integer user ids) - pass `dataType: 'string'` for text ids. It also supports an `allowAnonymous` option (default: `true`). Set to `false` to require authenticated user context and throw errors for anonymous operations:
 ```typescript
 ...generateUserAuditColumnDefs({
   created: { dataType: 'string', columnName: 'created_by', allowAnonymous: false },
@@ -162,7 +164,7 @@ For a complete list of enrichers and options, see the [Schema Enrichers Referenc
 Protect sensitive data by configuring properties that are **never returned** through repository queries. Hidden properties are excluded at the SQL level for maximum security and performance.
 
 ```typescript
-import { BaseEntity, generateIdColumnDefs, model } from '@venizia/ignis';
+import { BasePostgresEntity, generateIdColumnDefs, model } from '@venizia/ignis';
 import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({
@@ -171,7 +173,7 @@ import { pgTable, text } from 'drizzle-orm/pg-core';
     hiddenProperties: ['password', 'secret'],  // Never returned via repository
   },
 })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),
@@ -222,7 +224,7 @@ Apply automatic filters to all repository queries. This is commonly used for sof
     hiddenProperties: ['deletedAt'],
   },
 })
-export class Article extends BaseEntity<typeof Article.schema> {
+export class Article extends BasePostgresEntity<typeof Article.schema> {
   // ...
 }
 ```
@@ -231,10 +233,11 @@ The default filter is applied automatically to all read operations. Bypass it wi
 
 ```typescript
 // Normal query - auto-filters out soft-deleted records
-const articles = await articleRepo.find({});
+const articles = await articleRepo.find({ filter: {} });
 
 // Include deleted records
 const allArticles = await articleRepo.find({
+  filter: {},
   options: { shouldSkipDefaultFilter: true },
 });
 ```
@@ -244,7 +247,7 @@ const allArticles = await articleRepo.find({
 Declare your model's authorization principal directly in `@model` settings. The decorator auto-populates `AUTHORIZATION_SUBJECT` for type-safe references in route configs:
 
 ```typescript
-import { BaseEntity, generateIdColumnDefs, model, AuthorizationActions } from '@venizia/ignis';
+import { BasePostgresEntity, generateIdColumnDefs, model, AuthorizationActions } from '@venizia/ignis';
 import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({
@@ -253,14 +256,14 @@ import { pgTable, text } from 'drizzle-orm/pg-core';
     authorize: { principal: 'article' },
   },
 })
-export class Article extends BaseEntity<typeof Article.schema> {
+export class Article extends BasePostgresEntity<typeof Article.schema> {
   static override schema = pgTable('Article', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     title: text('title').notNull(),
   });
 }
 
-// Use in route configs — no hardcoded strings
+// Use in route configs - no hardcoded strings
 authorize: {
   action: AuthorizationActions.READ,
   resource: Article.AUTHORIZATION_SUBJECT, // 'article'
@@ -282,16 +285,17 @@ The `@model` decorator accepts the following metadata:
 | `skipMigrate` | `boolean` | Skip this model during migrations |
 | `settings.hiddenProperties` | `string[]` | Properties excluded from all query results |
 | `settings.defaultFilter` | `TFilter` | Default filter auto-applied to all queries |
+| `settings.defaultLimit` | `number` | Default row limit when a query omits `limit` (must be a positive integer; falls back to `10`) |
 | `settings.authorize.principal` | `string` | Authorization subject name for this model |
 
 ## Model Template
 
 ```typescript
-import { BaseEntity, generateIdColumnDefs, model, TRelationConfig } from '@venizia/ignis';
+import { BasePostgresEntity, generateIdColumnDefs, model, TRelationConfig } from '@venizia/ignis';
 import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({ type: 'entity' })
-export class MyModel extends BaseEntity<typeof MyModel.schema> {
+export class MyModel extends BasePostgresEntity<typeof MyModel.schema> {
   static override schema = pgTable('MyModel', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     name: text('name').notNull(),

package/content/guides/core-concepts/persistent/postgres-drivers.md

@@ -0,0 +1,201 @@
+# Postgres Drivers & Supabase
+
+IGNIS talks to PostgreSQL through a **driver seam**: `IRelationalDriver` owns connection acquisition and the raw transaction control statements, and everything above it - repositories, transactions, the Casbin adapters - is driver-agnostic. Two drivers ship today:
+
+- **node-postgres** (`pg`) - the default IGNIS has always used
+- **postgres-js** (`postgres`) - required for Supabase's transaction pooler, and a faster option anywhere else
+
+Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies the **driver**, not the SQL dialect. The `@venizia/ignis/postgres/supabase` submodule adds the two things Supabase deployments actually need - pooler presets and an RLS auth-context helper.
+
+> [!IMPORTANT] Every database client is optional
+> `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - only the driver class you import and name in `@datasource({ driver })` reaches your bundle. Install the one your app uses:
+>
+> ```bash
+> bun add pg          # node-postgres
+> bun add postgres    # postgres-js (>= 3.4.0)
+> ```
+
+## Import Paths
+
+| Import | Contents | Loads |
+| :--- | :--- | :--- |
+| `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, repository hierarchy | no client library |
+| `@venizia/ignis/postgres/node-postgres` | `NodePostgresDriver` | `pg` |
+| `@venizia/ignis/postgres/postgres-js` | `PostgresJsDriver` | `postgres` |
+| `@venizia/ignis/postgres/supabase` | `PoolerModes`, `buildPostgresJsOptions`, `withAuthContext`, Supabase role re-exports | `drizzle-orm/supabase` |
+
+## Naming the Driver Class
+
+`@datasource({ driver })` takes the driver **class**, not a driver-name string:
+
+```typescript
+import { datasource, ValueOrPromise } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
+import { Pool } from 'pg';
+
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure(): ValueOrPromise<void> {
+    this.client = new Pool({ connectionString: this.getConnectionString() }); // that is all
+  }
+}
+```
+
+`configure()` only builds `this.client` - the raw `pg.Pool` (or postgres-js `Sql`) your app's connection settings produce. The base class wires the driver **and** the connector lazily, on first call to `getConnector()` or `beginTransaction()`: it reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds the pooled Drizzle connector from that. `getClient()` hands `this.client` back as the raw-client escape hatch. A datasource that sets neither `this.client` nor a driver (via `useDriver()`, below) throws `No driver and no client` on first use.
+
+> [!IMPORTANT] Why a class, not a name
+> A driver-name string cannot carry `pg` or `postgres` into your bundle - it is just text. A dynamic `import('./node-postgres.js')` keyed off that string would defer *execution*, not *packaging*: every bundler statically resolves a literal specifier and packages whatever it points to, so a build that only used node-postgres would still fail with `Could not resolve: "postgres"` the moment postgres-js's import appeared anywhere in the module graph reachable at build time. Naming the class instead makes the driver module a real value reference - the one thing a bundler is forced to keep - which is what lets `pg` and `postgres` stay genuinely optional peers. A bare side-effect import (`import '@venizia/ignis/postgres/node-postgres'`) would not work either: `@venizia/ignis` declares `sideEffects: false`, so a bundler is free to drop an import whose exports go unused.
+>
+> Two tests pin this from different angles: `packages/core/src/__tests__/connectors/postgres/no-eager-driver-import.test.ts` proves no barrel **loads** a driver package in a fresh process (the runtime module graph), and `packages/core/src/__tests__/connectors/postgres/bundle/optional-peers.test.ts` proves no barrel gets a driver package **packaged** by a real bundler.
+
+## Using postgres-js
+
+Same shape, different class:
+
+```typescript
+import { datasource, ValueOrPromise } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
+import postgres from 'postgres';
+import type { Sql } from 'postgres';
+
+@datasource({ driver: PostgresJsDriver })
+export class PostgresDataSource extends BasePostgresDataSource<
+  IDataSourceConfigs,
+  typeof schema,
+  {},
+  Sql // getClient() is now honestly typed as postgres-js's Sql, not pg.Pool
+> {
+  override configure(): ValueOrPromise<void> {
+    this.client = postgres(this.getConnectionString());
+  }
+}
+```
+
+The fourth type parameter (`Client`) defaults to `pg.Pool`; declare it when the raw client escape hatch (`getClient()`) should carry the real type.
+
+## Driver Constructors Validate Their Client
+
+Both shipped drivers throw immediately if constructed with the wrong shape of client, instead of failing later inside a query:
+
+```typescript
+new NodePostgresDriver({ client: pool }); // client must expose connect() AND totalCount (pool accounting)
+new PostgresJsDriver({ client: sql });    // client must expose reserve() AND unsafe()
+```
+
+`NodePostgresDriver` rejects a bare `pg.Client` - it exposes `connect()` too, but has no pool accounting and cannot hand out a dedicated connection per transaction. `PostgresJsDriver` rejects a `pg.Pool` the same way. You will not normally construct these yourself: `wireDriverFromMetadata()` does it for you from `this.client`, so this validation fires the first time a datasource wired the wrong client behind the wrong `@datasource({ driver })` class.
+
+## Custom or Third-Party Drivers: `useDriver()`
+
+For a driver IGNIS does not ship, wire it explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+
+```typescript
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure(): ValueOrPromise<void> {
+    this.useDriver({
+      driver: new MyCustomDriver({ client: myClient }),
+      schema: this.getSchema(),
+    });
+  }
+}
+```
+
+`useDriver()` bypasses `@datasource({ driver })` entirely - you never need to name a class in the decorator when you wire the driver yourself in `configure()`.
+
+> [!WARNING] postgres-js cannot destroy a poisoned connection
+> After a failed `COMMIT` or `ROLLBACK`, node-postgres **destroys** the connection instead of pooling it - the session may still hold an open transaction that the next borrower would inherit. postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so the connection is returned to the pool anyway. This asymmetry is real and IGNIS does not paper over it; it is pinned by the driver's own tests.
+
+## The Driver Contract
+
+Every driver satisfies the same neutral interface, proven by a shared conformance suite - a seam only one driver can satisfy is not a seam:
+
+```typescript
+interface IRelationalDriver<Schema, Client> {
+  createConnector(opts: { schema: Schema }): TRelationalConnector<Schema>; // pooled Drizzle
+  acquire(opts: { schema: Schema }): Promise<IRelationalConnection<Schema>>; // one dedicated connection
+  getClient(): Client; // raw client escape: pg.Pool or Sql
+  end(): Promise<void>;
+}
+
+interface IRelationalConnection<Schema> {
+  connector: TRelationalConnector<Schema>; // Drizzle bound to THIS connection, not the pool
+  execute(opts: { statement: string }): Promise<IStatementResult>; // { count } - control statements
+  release(opts?: { destroy?: boolean }): void;
+}
+```
+
+`acquire()` matters for transactions: `BEGIN` and `COMMIT` must land on the same backend, so each explicit transaction gets a dedicated connection (`pool.connect()` for pg, `sql.reserve()` for postgres-js - the reason for the `>= 3.4.0` floor).
+
+The connection is checked out of the pool before Drizzle is constructed on top of it. If that constructor throws - a malformed discovered schema, a drizzle mismatch - both drivers catch the error, release the connection back to the pool first, and rethrow. Without this, every failed `acquire()` would strand a connection, and the pool would exhaust after enough of them.
+
+`execute()` resolves to the neutral `IStatementResult` (`{ count }` - the same `count` the repository verbs speak). Each driver maps its native result shape at its own boundary; nothing above the seam ever inspects a driver-specific type.
+
+## Supabase
+
+### Choosing a connection mode
+
+Supabase exposes three ways in, and one of them silently breaks prepared statements:
+
+| Mode | Port | Prepared statements | When |
+| :--- | :--- | :--- | :--- |
+| `PoolerModes.DIRECT` | 5432 | yes | long-lived servers connecting straight to the database |
+| `PoolerModes.SESSION` | 5432 (pooler) | yes | pooled, one backend per client session |
+| `PoolerModes.TRANSACTION` | 6543 | **no** | serverless / many short-lived connections |
+
+The transaction pooler (Supavisor) rebinds the backend per transaction, so a server-side prepared statement created on one backend simply is not there next time. `buildPostgresJsOptions` encodes this so you cannot forget it:
+
+```typescript
+import { datasource } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
+import { buildPostgresJsOptions, PoolerModes } from '@venizia/ignis/postgres/supabase';
+import postgres from 'postgres';
+
+@datasource({ driver: PostgresJsDriver })
+export class SupabaseDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure() {
+    this.client = postgres(connectionString, {
+      ...buildPostgresJsOptions({ mode: PoolerModes.TRANSACTION, max: 10 }),
+    });
+  }
+}
+```
+
+`prepare: false` is emitted only for `TRANSACTION` mode; `max` is forwarded only when you pass it, so postgres-js's own default survives. Naming `PostgresJsDriver` in `@datasource` is what wires it - `configure()` only needs to build the client, same as node-postgres.
+
+### Row Level Security
+
+`withAuthContext` sets the Supabase auth context for the remainder of **one transaction**, so `auth.uid()` resolves inside RLS policies:
+
+```typescript
+import { withAuthContext } from '@venizia/ignis/postgres/supabase';
+
+const transaction = await this.dataSource.beginTransaction();
+try {
+  // role defaults to claims.role (PostgREST semantics); pass it explicitly to override
+  await withAuthContext({ transaction, claims: jwtPayload });
+
+  await this.orderRepository.create({ data, options: { transaction } });
+  await transaction.commit();
+} catch (error) {
+  try {
+    await transaction.rollback();
+  } catch (rollbackError) {
+    logger.error('Rollback failed | %s', rollbackError);
+  }
+  throw error;
+}
+```
+
+Three properties make this safe under a transaction-mode pooler:
+
+- `claims` is **bound as a query parameter**, never interpolated into SQL text.
+- `role` must be a bare identifier (`/^[a-z_][a-z0-9_]*$/`) because `set local role $1` is not valid SQL - a role taken from a JWT and interpolated unvalidated would be a privilege-escalation vector. Validation runs **before** any statement, so a rejected call leaves the session untouched.
+- Everything is `SET LOCAL` / `set_config(..., true)` - transaction-scoped. A plain `SET` would leak the caller's identity to the next borrower of the pooled connection, and is deliberately not offered.
+
+The submodule also re-exports Drizzle's Supabase helpers (`anonRole`, `authenticatedRole`, `serviceRole`, `authUid`, `authUsers`, ...) so RLS-aware schema files need one import.
+
+## Adding a Driver
+
+One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, buildDriverProbe })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.

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

@@ -48,15 +48,15 @@ export class UserRepository extends ReadableRepository<typeof User.schema> {
     dataSource: PostgresDataSource, // Must be concrete type, not 'any'
 
     // After first arg, you can inject any additional dependencies
-    @inject({ key: 'some.cache' })
-    private cache: SomeCache,
+    @inject({ key: 'services.CacheService' })
+    private cacheService: CacheService,
   ) {
     super(dataSource);
   }
 
   async findByRealm(opts: { realm: string }) {
     // Use injected dependencies
-    const cached = await this.cache.get(`user:realm:${opts.realm}`);
+    const cached = await this.cacheService.get(`user:realm:${opts.realm}`);
     if (cached) {
       return cached;
     }
@@ -74,13 +74,17 @@ export class UserRepository extends ReadableRepository<typeof User.schema> {
 ## Repository Hierarchy
 
 ```
-AbstractRepository (base + mixins: FieldsVisibilityMixin + DefaultFilterMixin)
+AbstractRepository (engine-neutral base in src/base - lazy dataSource/entity resolution,
+                    @model settings getters: hiddenProperties, defaultFilter, defaultLimit)
+  ↓
+PostgresBaseRepository (postgres connector - filter building, hidden-column exclusion,
+                        default-filter merging, transaction-aware connector resolution)
   ↓
 ReadableRepository (read-only: find, findOne, findById, count, existsWith)
   ↓
-PersistableRepository (+ create, updateById, updateAll)
+PersistableRepository (+ create, createAll, updateById, updateAll, deleteById, deleteAll)
   ↓
-DefaultCRUDRepository (+ deleteById, deleteAll) — recommended default
+DefaultCRUDRepository (no additional methods - recommended default)
   ↓
 SoftDeletableRepository (overrides delete to set deletedAt timestamp)
 ```
@@ -88,14 +92,16 @@ SoftDeletableRepository (overrides delete to set deletedAt timestamp)
 | Type | Description |
 |------|-------------|
 | `ReadableRepository` | Read-only operations. Write operations throw errors. |
-| `PersistableRepository` | Read + write operations (create, update). Extends ReadableRepository. |
-| `DefaultCRUDRepository` | Full CRUD including delete. Extends PersistableRepository. **Recommended for most use cases.** |
+| `PersistableRepository` | Read + write operations (create, update, delete). Extends ReadableRepository. |
+| `DefaultCRUDRepository` | Extends PersistableRepository with no additional logic. **Recommended for most use cases.** |
 | `SoftDeletableRepository` | Extends DefaultCRUDRepository. Overrides delete to set `deletedAt` timestamp instead of physically removing records. |
 
 ## Querying Data
 
 For advanced filtering with operators like `gt`, `lt`, `like`, `in`, `between`, and more, see [Filter System](../../../references/base/filter-system/).
 
+Return shapes: read methods return values directly (`find` returns an array, `findOne`/`findById` return a record or `null`, `count` returns `{ count }`), while write methods (`create`, `updateById`, `deleteById`, ...) return a `{ count, data }` envelope.
+
 ```typescript
 const repo = this.get<ConfigurationRepository>({ key: 'repositories.ConfigurationRepository' });
 
@@ -128,8 +134,8 @@ const sorted = await repo.find({
   }
 });
 
-// Create a record
-const newConfig = await repo.create({
+// Create a record - write operations return a { count, data } envelope
+const { data: newConfig } = await repo.create({
   data: {
     code: 'NEW_SETTING',
     group: 'SYSTEM',
@@ -137,13 +143,13 @@ const newConfig = await repo.create({
   }
 });
 
-// Update by ID
-await repo.updateById({
+// Update by ID - also returns { count, data }
+const { data: updatedConfig } = await repo.updateById({
   id: 'uuid-here',
   data: { description: 'Updated description' }
 });
 
-// Delete by ID
+// Delete by ID - also returns { count, data }
 await repo.deleteById({ id: 'uuid-here' });
 ```
 
@@ -153,10 +159,13 @@ All repository operations accept an `options` parameter with these fields:
 
 | Option | Type | Description |
 | :--- | :--- | :--- |
-| `transaction` | `ITransaction` | Transaction context for atomic operations |
-| `shouldReturn` | `boolean` | Whether to return created/updated data (default: `true`) |
-| `shouldQueryRange` | `boolean` | Return `{ data, range: { total, skip, limit } }` for pagination |
+| `transaction` | `IDatabaseTransaction` | Transaction context for atomic operations |
+| `shouldReturn` | `boolean` | Write methods only - whether to return created/updated data (default: `true`) |
+| `shouldQueryRange` | `boolean` | `find` only - return `{ data, range: { start, end, total } }` for pagination |
 | `shouldSkipDefaultFilter` | `boolean` | Bypass the model's default filter (e.g., soft delete) |
+| `force` | `boolean` | `updateAll`/`deleteAll` only - allow an empty `where` (table-wide operation) |
+| `lock` | `TLockOptions` | Row-level locking for reads (`{ strength: 'update' }`, ...). Requires a transaction; incompatible with `include`/`fields` |
+| `log` | `TRepositoryLogOptions` | Per-operation logging (`{ use: true, level?: 'info' }`) |
 
 ```typescript
 // Create without returning data (faster)
@@ -178,7 +187,7 @@ const result = await repo.find({
   filter: { limit: 20, skip: 0 },
   options: { shouldQueryRange: true }
 });
-// result = { data: [...], range: { total: 150, skip: 0, limit: 20 } }
+// result = { data: [...], range: { start: 0, end: 19, total: 150 } }
 ```
 
 ## Querying with Relations
@@ -193,7 +202,7 @@ const configWithCreator = await repo.findOne({
   },
 });
 
-console.log('Created by:', configWithCreator.creator.name);
+console.log('Created by:', configWithCreator?.creator.name);
 ```
 
 ## Registering Repositories
@@ -214,8 +223,15 @@ export class Application extends BaseApplication {
 For soft-delete patterns, use `SoftDeletableRepository` which overrides delete operations to set a `deletedAt` timestamp instead of physically removing records:
 
 ```typescript
-import { SoftDeletableRepository, repository, model, BaseEntity } from '@venizia/ignis';
-import { pgTable, timestamp } from 'drizzle-orm/pg-core';
+import {
+  BasePostgresEntity,
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+  model,
+  repository,
+  SoftDeletableRepository,
+} from '@venizia/ignis';
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 
 @model({
   type: 'entity',
@@ -224,7 +240,7 @@ import { pgTable, timestamp } from 'drizzle-orm/pg-core';
     defaultFilter: { where: { deletedAt: null } },
   },
 })
-export class Category extends BaseEntity<typeof Category.schema> {
+export class Category extends BasePostgresEntity<typeof Category.schema> {
   static override schema = pgTable('Category', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     ...generateTzColumnDefs(),
@@ -237,6 +253,8 @@ export class Category extends BaseEntity<typeof Category.schema> {
 export class CategoryRepository extends SoftDeletableRepository<typeof Category.schema> {}
 ```
 
+Delete operations accept `shouldHardDelete: true` in options to physically remove a row, and soft-deleted records can be restored via `restoreById`/`restoreAll`.
+
 ## Repository Template
 
 ```typescript
@@ -252,7 +270,7 @@ export class MyModelRepository extends DefaultCRUDRepository<typeof MyModel.sche
 
 ### Performance: Core API Optimization
 
-Ignis automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads. The `canUseCoreAPI()` method on `ReadableRepository` determines when this optimization applies.
+IGNIS automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads. The `canUseCoreAPI()` method on `ReadableRepository` determines when this optimization applies.
 
 ### Modular Persistence with Components
 
@@ -283,7 +301,6 @@ export class UserManagementComponent extends BaseComponent {
   - [Filter System](/references/base/filter-system/) - Query operators and filtering
   - [Relations & Includes](/references/base/repositories/relations) - Loading related data
   - [Advanced Features](/references/base/repositories/advanced) - JSON queries, performance tuning
-  - [Repository Mixins](/references/base/repositories/mixins) - Soft delete and auditing
 
 - **Best Practices:**
   - [Data Modeling](/best-practices/data-modeling) - Repository design patterns