@venizia/ignis-docs 0.0.7 → 0.0.8-0

package/wiki/references/base/repositories/index.md

@@ -25,14 +25,51 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 
 | Class | Capabilities | Use Case |
 |-------|--------------|----------|
-| **AbstractRepository** | Base class with properties | Extend for custom repositories |
-| **ReadableRepository** | Read-only operations | Views, external tables |
-| **PersistableRepository** | Read + Write operations | Rarely used directly |
-| **DefaultCRUDRepository** | Full CRUD operations | Standard data tables |
+| **AbstractRepository** | Base class with properties, mixins, lazy resolution | Extend for custom repositories |
+| **ReadableRepository** | Read-only operations (write methods throw errors) | Views, external tables, read-only access |
+| **PersistableRepository** | Read + Write operations | Full CRUD access |
+| **DefaultCRUDRepository** | Extends PersistableRepository (no additions) | Standard data tables (recommended) |
 | **SoftDeletableRepository** | CRUD + soft delete + restore | Tables with `deletedAt` column |
 
 **Most common:** Extend `DefaultCRUDRepository` for standard tables, or `SoftDeletableRepository` for soft-delete patterns.
 
+### Hierarchy
+
+```
+BaseHelper
+  + FieldsVisibilityMixin
+  + DefaultFilterMixin
+    = AbstractRepository (abstract base, declares all CRUD signatures)
+        |
+        +-- ReadableRepository (implements read ops; write ops throw errors)
+              |
+              +-- PersistableRepository (implements write + delete ops, READ_WRITE scope)
+                    |
+                    +-- DefaultCRUDRepository (empty subclass, recommended entry point)
+                          |
+                          +-- SoftDeletableRepository (overrides delete with soft-delete)
+```
+
+### Type Parameters
+
+All repository classes share the same four type parameters:
+
+```typescript
+class DefaultCRUDRepository<
+  EntitySchema extends TTableSchemaWithId = TTableSchemaWithId,
+  DataObject extends TTableObject<EntitySchema> = TTableObject<EntitySchema>,
+  PersistObject extends TTableInsert<EntitySchema> = TTableInsert<EntitySchema>,
+  ExtraOptions extends IExtraOptions = IExtraOptions,
+>
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `EntitySchema` | The Drizzle `pgTable` schema type (e.g., `typeof User.schema`) |
+| `DataObject` | The inferred SELECT type from the schema |
+| `PersistObject` | The inferred INSERT type from the schema |
+| `ExtraOptions` | Extra options for operations (defaults to `IExtraOptions`) |
+
 
 ## Available Methods
 
@@ -52,10 +89,357 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 | `create(opts)` | Create single record | `repo.create({ data: { title: 'New' } })` |
 | `createAll(opts)` | Create multiple records | `repo.createAll({ data: [{ title: 'A' }, { title: 'B' }] })` |
 | `updateById(opts)` | Update by primary key | `repo.updateById({ id: '123', data: { title: 'Updated' } })` |
-| `updateAll(opts)` | Update matching records | `repo.updateAll({ where: { status: 'draft' }, data: { status: 'published' } })` |
+| `updateAll(opts)` | Update matching records | `repo.updateAll({ data: { status: 'published' }, where: { status: 'draft' } })` |
+| `updateBy(opts)` | Alias for `updateAll` | `repo.updateBy({ data: { status: 'published' }, where: { status: 'draft' } })` |
 | `deleteById(opts)` | Delete by primary key | `repo.deleteById({ id: '123' })` |
 | `deleteAll(opts)` | Delete matching records | `repo.deleteAll({ where: { status: 'archived' } })` |
-| `deleteBy(opts)` | Delete by where condition | `repo.deleteBy({ where: { status: 'archived' } })` |
+| `deleteBy(opts)` | Alias for `deleteAll` | `repo.deleteBy({ where: { status: 'archived' } })` |
+
+
+## Method Signatures
+
+### Read Operations
+
+```typescript
+// Count matching records
+count(opts: {
+  where: TWhere<DataObject>;
+  options?: IExtraOptions;
+}): Promise<{ count: number }>;
+
+// Check if any record matches
+existsWith(opts: {
+  where: TWhere<DataObject>;
+  options?: IExtraOptions;
+}): Promise<boolean>;
+
+// Find multiple records (returns array)
+find<R = DataObject>(opts: {
+  filter: TFilter<DataObject>;
+  options?: IExtraOptions & { shouldQueryRange?: false };
+}): Promise<R[]>;
+
+// Find multiple records with range info (returns data + range)
+find<R = DataObject>(opts: {
+  filter: TFilter<DataObject>;
+  options: IExtraOptions & { shouldQueryRange: true };
+}): Promise<{ data: Array<R>; range: TDataRange }>;
+
+// Find single record
+findOne<R = DataObject>(opts: {
+  filter: TFilter<DataObject>;
+  options?: IExtraOptions;
+}): Promise<R | null>;
+
+// Find by primary key
+findById<R = DataObject>(opts: {
+  id: IdType;
+  filter?: Omit<TFilter<DataObject>, 'where'>;
+  options?: IExtraOptions;
+}): Promise<R | null>;
+```
+
+### Write Operations
+
+```typescript
+// Create single record (returns created data by default)
+create<R = DataObject>(opts: {
+  data: PersistObject;
+  options?: IExtraOptions & { shouldReturn?: true };
+}): Promise<{ count: number; data: R }>;
+
+// Create single record (skip returning data)
+create(opts: {
+  data: PersistObject;
+  options: IExtraOptions & { shouldReturn: false };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// Create multiple records (returns created data by default)
+createAll<R = DataObject>(opts: {
+  data: Array<PersistObject>;
+  options?: IExtraOptions & { shouldReturn?: true };
+}): Promise<{ count: number; data: Array<R> }>;
+
+// Create multiple records (skip returning data)
+createAll(opts: {
+  data: Array<PersistObject>;
+  options: IExtraOptions & { shouldReturn: false };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// Update by primary key (returns updated data by default)
+updateById<R = DataObject>(opts: {
+  id: IdType;
+  data: Partial<PersistObject>;
+  options?: IExtraOptions & { shouldReturn?: true };
+}): Promise<{ count: number; data: R }>;
+
+// Update by primary key (skip returning data)
+updateById(opts: {
+  id: IdType;
+  data: Partial<PersistObject>;
+  options: IExtraOptions & { shouldReturn: false };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// Update matching records (returns updated data by default)
+updateAll<R = DataObject>(opts: {
+  data: Partial<PersistObject>;
+  where: TWhere<DataObject>;
+  options?: IExtraOptions & { shouldReturn?: true; force?: boolean };
+}): Promise<{ count: number; data: Array<R> }>;
+
+// Update matching records (skip returning data)
+updateAll(opts: {
+  data: Partial<PersistObject>;
+  where: TWhere<DataObject>;
+  options: IExtraOptions & { shouldReturn: false; force?: boolean };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// updateBy is an alias for updateAll (same signatures)
+
+// Delete by primary key (returns deleted data by default)
+deleteById<R = DataObject>(opts: {
+  id: IdType;
+  options?: IExtraOptions & { shouldReturn?: true };
+}): Promise<{ count: number; data: R }>;
+
+// Delete by primary key (skip returning data)
+deleteById(opts: {
+  id: IdType;
+  options: IExtraOptions & { shouldReturn: false };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// Delete matching records (returns deleted data by default)
+deleteAll<R = DataObject>(opts: {
+  where: TWhere<DataObject>;
+  options?: IExtraOptions & { shouldReturn?: true; force?: boolean };
+}): Promise<{ count: number; data: Array<R> }>;
+
+// Delete matching records (skip returning data)
+deleteAll(opts: {
+  where: TWhere<DataObject>;
+  options: IExtraOptions & { shouldReturn: false; force?: boolean };
+}): Promise<{ count: number; data: undefined | null }>;
+
+// deleteBy is an alias for deleteAll (same signatures)
+```
+
+
+## IExtraOptions
+
+All repository operations accept an `options` parameter with these fields:
+
+```typescript
+interface IExtraOptions {
+  /** Transaction context — switches the underlying Drizzle connector. */
+  transaction?: ITransaction;
+
+  /** Operation logging configuration. */
+  log?: { use: boolean; level?: TLogLevel };
+
+  /** If true, bypass the default filter configured in model settings (e.g., soft delete). */
+  shouldSkipDefaultFilter?: boolean;
+}
+```
+
+Additional fields are available as intersections on specific methods:
+
+| Field | Type | Methods | Description |
+|-------|------|---------|-------------|
+| `shouldReturn` | `boolean` | `create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll` | If `false`, skip returning the data (only return count). Defaults to `true`. |
+| `shouldQueryRange` | `boolean` | `find` | If `true`, returns `{ data, range: { start, end, total } }` instead of a plain array. |
+| `force` | `boolean` | `updateAll`, `deleteAll`, `updateBy`, `deleteBy` | Required to allow empty `where` conditions. |
+
+
+## TDataRange
+
+When `shouldQueryRange: true` is used, the range follows the HTTP Content-Range standard:
+
+```typescript
+type TDataRange = {
+  start: number;  // Inclusive start index (based on skip/offset)
+  end: number;    // Inclusive end index
+  total: number;  // Total matching records (ignoring limit)
+};
+```
+
+
+## AbstractRepository Properties
+
+### dataSource
+
+Getter/setter for the repository's datasource. Throws if accessed before being set (either via constructor or `@repository` auto-injection).
+
+```typescript
+get dataSource(): IDataSource;
+set dataSource(value: IDataSource);
+setDataSource(opts: { dataSource: IDataSource }): void;
+```
+
+### entity
+
+Lazy-resolved from `@repository` metadata on first access. Can also be set explicitly via constructor `entityClass` option.
+
+```typescript
+get entity(): BaseEntity<EntitySchema>;
+set entity(value: BaseEntity<EntitySchema>);
+getEntity(): BaseEntity<EntitySchema>;
+getEntitySchema(): EntitySchema;
+```
+
+### operationScope
+
+Returns the repository's operation scope: `'READ_ONLY'`, `'WRITE_ONLY'`, or `'READ_WRITE'`.
+
+```typescript
+get operationScope(): TRepositoryOperationScope;
+```
+
+- `ReadableRepository` defaults to `READ_ONLY`
+- `PersistableRepository` and `DefaultCRUDRepository` default to `READ_WRITE`
+
+### filterBuilder
+
+Access to the `FilterBuilder` instance used for converting filter objects to Drizzle SQL.
+
+```typescript
+get filterBuilder(): FilterBuilder;
+```
+
+### connector
+
+Shortcut for `this.dataSource.connector`.
+
+```typescript
+get connector(): IDataSource['connector'];
+getConnector(): IDataSource['connector'];
+```
+
+### updateBuilder (PersistableRepository+)
+
+Access to the `UpdateBuilder` instance used for transforming update data (including JSON path updates).
+
+```typescript
+get updateBuilder(): UpdateBuilder;
+```
+
+
+## Key Methods
+
+### beginTransaction
+
+Start a new database transaction through the repository's datasource:
+
+```typescript
+await repo.beginTransaction(opts?: ITransactionOptions): Promise<ITransaction>;
+```
+
+Usage:
+
+```typescript
+const tx = await repo.beginTransaction();
+try {
+  await repo.create({ data: { name: 'John' }, options: { transaction: tx } });
+  await repo.updateById({ id: '456', data: { count: 1 }, options: { transaction: tx } });
+  await tx.commit();
+} catch (e) {
+  await tx.rollback();
+}
+```
+
+### buildQuery
+
+Converts a `TFilter` into Drizzle query options, automatically excluding hidden properties from `@model` settings:
+
+```typescript
+buildQuery(opts: { filter: TFilter<DataObject> }): TDrizzleQueryOptions;
+```
+
+The returned `TDrizzleQueryOptions` contains:
+
+```typescript
+type TDrizzleQueryOptions = Partial<{
+  limit: number;
+  offset: number;
+  orderBy: SQL[];
+  where: SQL;
+  with: Record<string, true | TDrizzleQueryOptions>;
+  columns: Record<string, boolean>;
+}>;
+```
+
+
+## Dual Query API
+
+`ReadableRepository` automatically selects the optimal query strategy:
+
+- **Core API** (Drizzle `select().from()`): ~15-20% faster for flat queries without relations or field selection
+- **Query API** (Drizzle `connector.query[entity].findMany()`): Supports `include` for relations and `fields` for column selection
+
+The selection is automatic based on filter complexity:
+
+```typescript
+// Uses Core API (no include, no fields)
+await repo.find({ filter: { where: { status: 'active' }, limit: 10 } });
+
+// Uses Query API (has include)
+await repo.find({
+  filter: {
+    where: { status: 'active' },
+    include: [{ relation: 'posts' }],
+  },
+});
+
+// Uses Query API (has fields)
+await repo.find({
+  filter: {
+    fields: { id: true, name: true },
+    where: { status: 'active' },
+  },
+});
+```
+
+
+## Constructor
+
+### AbstractRepository
+
+```typescript
+constructor(
+  ds?: IDataSource,
+  opts?: {
+    scope?: string;
+    entityClass?: TClass<BaseEntity<EntitySchema>>;
+    operationScope?: TRepositoryOperationScope;
+  },
+)
+```
+
+- `ds` -- DataSource instance (optional; auto-injected by `@repository` decorator)
+- `opts.scope` -- Logger scope name (defaults to class name)
+- `opts.entityClass` -- Entity class to instantiate (optional; lazy-resolved from `@repository` metadata)
+- `opts.operationScope` -- Defaults to `READ_ONLY`
+
+### ReadableRepository
+
+```typescript
+constructor(
+  ds?: IDataSource,
+  opts?: { entityClass?: TClass<BaseEntity<EntitySchema>> },
+)
+```
+
+Forces `operationScope` to `READ_ONLY`.
+
+### PersistableRepository
+
+```typescript
+constructor(
+  ds?: IDataSource,
+  opts?: { entityClass?: TClass<BaseEntity<EntitySchema>> },
+)
+```
+
+Forces `operationScope` to `READ_WRITE`. Also creates an `UpdateBuilder` instance.
 
 
 ## Documentation Sections
@@ -135,15 +519,29 @@ Composable mixins for repository features - `DefaultFilterMixin` and `FieldsVisi
 **Both `model` AND `dataSource` are required** for schema auto-discovery:
 
 ```typescript
-// ❌ WRONG - Missing dataSource
+@repository({ model: Model, dataSource: DataSourceClass })
+```
+
+The decorator accepts `IRepositoryMetadata`:
+
+```typescript
+interface IRepositoryMetadata<Schema, Model, DataSource> {
+  model: TValueOrResolver<TClass<Model>>;
+  dataSource: string | TValueOrResolver<TClass<DataSource>>;
+  operationScope?: TRepositoryOperationScope; // 'READ_ONLY' | 'WRITE_ONLY' | 'READ_WRITE'
+}
+```
+
+```typescript
+// WRONG - Missing dataSource
 @repository({ model: User })
 export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
 
-// ❌ WRONG - Missing model
+// WRONG - Missing model
 @repository({ dataSource: PostgresDataSource })
 export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
 
-// ✅ CORRECT
+// CORRECT
 @repository({ model: User, dataSource: PostgresDataSource })
 export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
 ```
@@ -179,19 +577,28 @@ export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
 }
 ```
 
+### Lazy Resolution
+
+The `@repository` decorator enables two lazy resolution mechanisms:
+
+1. **Entity resolution**: The `entity` getter auto-resolves the model class from `@repository` metadata on first access, so you never need to pass `entityClass` manually.
+2. **DataSource resolution**: The DataSource is auto-injected at constructor param[0] unless an explicit `@inject` is present.
+
 
 ## Safety Features
 
 ### Empty Where Protection
 
-Prevents accidental mass updates/deletes:
+Prevents accidental mass updates/deletes (in `PersistableRepository` and above):
 
 ```typescript
-// ❌ Throws error - empty where without force flag
+// Throws error - empty where without force flag
 await repo.deleteAll({ where: {} });
+await repo.updateAll({ data: { status: 'archived' }, where: {} });
 
-// ✅ Explicitly allow with force flag (logs warning)
+// Explicitly allow with force flag (logs warning)
 await repo.deleteAll({ where: {}, options: { force: true } });
+await repo.updateAll({ data: { status: 'archived' }, where: {}, options: { force: true } });
 ```
 
 | Scenario | `force: false` (default) | `force: true` |
@@ -199,6 +606,29 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 | Empty `where` | Throws error | Logs warning, proceeds |
 | Valid `where` | Executes normally | Executes normally |
 
+### ReadableRepository Write Protection
+
+All write methods (`create`, `createAll`, `updateById`, `updateAll`, `deleteById`, `deleteAll`) throw errors on `ReadableRepository`, enforcing the read-only scope at runtime.
+
+
+## TFilter Reference
+
+```typescript
+type TFilter<T = any> = {
+  where?: TWhere<T>;
+  fields?: Partial<{ [K in keyof T]: boolean }> | Array<keyof T>;
+  include?: Array<{
+    relation: string;
+    scope?: TFilter;
+    shouldSkipDefaultFilter?: boolean;
+  }>;
+  order?: string[];       // e.g., ['createdAt DESC', 'name ASC']
+  limit?: number;         // Defaults to 10
+  offset?: number;
+  skip?: number;          // Alias for offset
+};
+```
+
 
 ## Quick Reference
 
@@ -209,7 +639,10 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 | Find by ID | `repo.findById({ id: '123' })` |
 | Find with relations | `repo.find({ filter: { include: [{ relation: 'posts' }] } })` |
 | Create one | `repo.create({ data: { name: 'John' } })` |
+| Create without returning data | `repo.create({ data: { name: 'John' }, options: { shouldReturn: false } })` |
+| Create many | `repo.createAll({ data: [{ name: 'A' }, { name: 'B' }] })` |
 | Update by ID | `repo.updateById({ id: '123', data: { name: 'Jane' } })` |
+| Update by condition | `repo.updateAll({ data: { status: 'published' }, where: { status: 'draft' } })` |
 | Delete by ID | `repo.deleteById({ id: '123' })` |
 | Delete by condition | `repo.deleteBy({ where: { status: 'archived' } })` |
 | Soft delete | `repo.deleteById({ id: '123' })` (with `SoftDeletableRepository`) |
@@ -217,6 +650,8 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 | Hard delete (bypass soft) | `repo.deleteById({ id: '123', options: { shouldHardDelete: true } })` |
 | Count matching | `repo.count({ where: { status: 'active' } })` |
 | Check exists | `repo.existsWith({ where: { email: 'test@example.com' } })` |
+| Skip default filter | `repo.find({ filter, options: { shouldSkipDefaultFilter: true } })` |
+| Use transaction | `repo.create({ data, options: { transaction: tx } })` |
 
 
 ## Next Steps