nicot 1.2.12 → 1.3.0

package/README.md

@@ -808,6 +808,236 @@ You can think of Binding as **“automatic ownership filters”** configured dec
 
 ---
 
+## Upsert: Idempotent Write by Conflict Keys (PUT /resource)
+
+Upsert is NICOT’s idempotent write primitive. Given a set of conflict keys, NICOT will insert a new row if no existing row matches, or update the matched row if it already exists.
+
+Unlike create or update, upsert is a first-class operation with its own semantics:
+- It does not reuse create/update DTO rules by default.
+- It does not rely on create/update lifecycle hooks.
+- It uses explicitly declared upsert keys.
+- It integrates with Binding to remain multi-tenant safe.
+
+---
+
+### 1) Declaring conflict keys with `@UpsertColumn`
+
+`@UpsertColumn()` marks entity fields that participate in the upsert conflict key (often called a “natural key”).
+
+Example: upserting an article by `slug`.
+
+```ts
+import { Entity } from 'typeorm';
+import { IdBase, StringColumn } from 'nicot';
+import { UpsertColumn, UpsertableEntity } from 'nicot';
+
+@Entity()
+@UpsertableEntity()
+export class Article extends IdBase() {
+  @UpsertColumn()
+  @StringColumn(64, { required: true, description: 'Unique slug per tenant' })
+  slug: string;
+
+  @StringColumn(255, { required: true })
+  title: string;
+
+  isValidInUpsert() {
+    return !this.slug ? 'slug is required' : undefined;
+  }
+
+  async beforeUpsert() {}
+  async afterUpsert() {}
+}
+```
+
+Notes:
+- Upsert is whitelist-based: only fields decorated with `@UpsertColumn()` can be used as conflict keys.
+- Validation is upsert-specific via `isValidInUpsert()`, parallel to `isValidInCreate()` and `isValidInUpdate()`.
+
+---
+
+### 2) Enabling upsert with `@UpsertableEntity`
+
+`@UpsertableEntity()` marks an entity as upsert-capable and enforces structural correctness.
+
+It guarantees that:
+- the entity defines at least one `UpsertColumn` or `BindingColumn` (or has an upsert-capable base id)
+- the effective conflict key is backed by a database-level UNIQUE constraint
+
+This aligns with PostgreSQL’s requirement for:
+
+`INSERT ... ON CONFLICT (...) DO UPDATE`
+
+where the conflict target must match a unique index or unique constraint (the primary key also qualifies).
+
+In practice, NICOT builds uniqueness from:
+
+- all `@UpsertColumn()` fields
+- all `@BindingColumn()` fields
+
+unless the conflict key degenerates to the primary key alone.
+
+---
+
+### 3) `StringIdBase()` and upsert keys (UUID vs manual)
+
+NICOT provides `StringIdBase()` as the string-primary-key base.
+
+- `StringIdBase({ uuid: true })`
+  - id is generated by the DB
+  - id is not client-writable
+  - upsert keys should usually be explicit natural keys via `@UpsertColumn()` (and possibly binding columns)
+
+- `StringIdBase({ uuid: false })` (or omitted)
+  - id is client-provided and required
+  - id is effectively the natural key
+  - upsert can conflict on `id` alone, meaning this mode behaves as if `id` is an upsert key out of the box
+
+This is important when you combine `id` with additional `@UpsertColumn()` fields:
+- If your conflict key includes both `id` and another field (e.g. `slug`), then `id` differs but `slug` matches should be treated as a different row (because the conflict key is the full tuple).
+- If you instead want “slug decides identity” independent of `id`, do not include `id` in the conflict key.
+
+(Which key set is used is determined by your upsert columns + binding columns + base id behavior.)
+
+---
+
+### 4) Upsert and Binding (multi-tenant safety)
+
+When Binding is used, binding columns automatically participate in the upsert conflict key.
+
+```ts
+import { Entity } from 'typeorm';
+import { IdBase, IntColumn, StringColumn } from 'nicot';
+import { BindingColumn, BindingValue } from 'nicot';
+import { UpsertColumn, UpsertableEntity } from 'nicot';
+import { Injectable } from '@nestjs/common';
+import { CrudService } from 'nicot';
+import { InjectRepository } from '@nestjs/typeorm';
+
+@Entity()
+@UpsertableEntity()
+export class TenantArticle extends IdBase() {
+  @BindingColumn('app')
+  @IntColumn('int', { unsigned: true })
+  appId: number;
+
+  @UpsertColumn()
+  @StringColumn(64)
+  slug: string;
+
+  @StringColumn(255)
+  title: string;
+}
+
+@Injectable()
+export class TenantArticleService extends CrudService(TenantArticle) {
+  constructor(@InjectRepository(TenantArticle) repo) {
+    super(repo);
+  }
+
+  @BindingValue('app')
+  get currentAppId() {
+    return 44;
+  }
+}
+```
+
+Effective conflict key:
+- appId (binding)
+- slug (upsert column)
+
+This ensures:
+- upsert never matches or overwrites rows belonging to another tenant
+- tenant isolation is enforced declaratively at the entity level
+
+---
+
+### 5) Exposing upsert in controllers (PUT /resource)
+
+Upsert is exposed as a PUT request on the resource root path.
+
+Factory definition:
+
+```ts
+import { RestfulFactory } from 'nicot';
+
+export const ArticleFactory = new RestfulFactory(TenantArticle, {
+  relations: ['author'],
+  upsertIncludeRelations: true,
+  skipNonQueryableFields: true,
+});
+```
+
+Service:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+
+@Injectable()
+export class ArticleService extends ArticleFactory.crudService() {
+  constructor(@InjectRepository(TenantArticle) repo) {
+    super(repo);
+  }
+}
+```
+
+Controller:
+
+```ts
+import { Controller } from '@nestjs/common';
+
+export class UpsertArticleDto extends ArticleFactory.upsertDto {}
+
+@Controller('articles')
+export class ArticleController {
+  constructor(private readonly service: ArticleService) {}
+
+  // PUT /articles
+  @ArticleFactory.upsert()
+  upsert(@ArticleFactory.upsertParam() dto: UpsertArticleDto) {
+    return this.service.upsert(dto);
+  }
+}
+```
+
+---
+
+### 6) Response shape and relations
+
+Upsert returns NICOT’s standard response envelope.
+
+When `upsertIncludeRelations` is enabled, NICOT will:
+- refetch the saved entity using a query builder
+- apply relation joins based on the factory’s `relations` whitelist
+- return a fully hydrated entity in the response
+
+When disabled, upsert returns only the entity’s own columns, which is usually faster and avoids unnecessary joins.
+
+---
+
+### 7) Soft delete behavior
+
+All NICOT base entities include a soft-delete column (`deleteTime`).
+
+If an upsert matches a row that is currently soft-deleted:
+- NICOT sets `deleteTime` to `null` during upsert
+- refetches the row using `withDeleted()`
+- performs an explicit restore if necessary
+
+This makes upsert fully idempotent even across delete–recreate cycles.
+
+---
+
+### 8) Recommended usage patterns
+
+- Use stable natural keys (`slug`, `code`, `externalId`) as upsert columns.
+- Combine upsert columns with binding columns for multi-tenant uniqueness.
+- Keep upsert validation logic inside `isValidInUpsert()`.
+- For `StringIdBase({ uuid: false })`, treat `id` as the natural key by default; add extra upsert columns only when you explicitly want a composite identity.
+
+---
+
 ## Pagination
 
 ### Offset pagination (default)
@@ -1169,6 +1399,414 @@ You can still build custom endpoints and return these wrappers manually if neede
 
 ---
 
+## Transactional TypeORM (request-scoped transactions)
+
+NICOT’s CRUD flows are TypeORM-based, but by default each repository call is not automatically wrapped in a single database transaction.
+
+If you want **“one HTTP request = one DB transaction”**, NICOT provides a small TypeORM wrapper:
+
+- `TransactionalTypeOrmInterceptor()` — starts a TypeORM transaction at the beginning of a request and commits or rolls it back when request processing finishes or fails.
+- `TransactionalTypeOrmModule.forFeature(...)` — provides **request-scoped** transaction-aware `EntityManager` / `Repository` injection tokens, and also includes the TypeORM `forFeature()` import/export.
+
+### When to use
+
+Use transactional mode when you want:
+
+- multiple writes across different repositories to **commit/rollback together**
+- service methods that mix `create/update/delete` and custom repo operations
+- deterministic rollback when you throw `BlankReturnMessageDto(...).toException()`
+
+Avoid it for:
+
+- streaming responses (SSE / long-lived streams) — the transaction would stay open until the stream completes
+- very heavy read-only endpoints where a transaction adds overhead
+
+### 1) Import TransactionalTypeOrmModule
+
+In the module that owns your resource:
+
+```ts
+import { Module } from '@nestjs/common';
+import { User } from './user.entity';
+import { UserController } from './user.controller';
+import { UserService } from './user.service';
+
+import { TransactionalTypeOrmModule } from 'nicot'; // or your local path
+
+@Module({
+  imports: [
+    // ⭐ includes TypeOrmModule.forFeature([User]) internally and re-exports it
+    TransactionalTypeOrmModule.forFeature([User]),
+  ],
+  controllers: [UserController],
+  providers: [UserService],
+})
+export class UserModule {}
+```
+
+Notes:
+
+- The providers created by `TransactionalTypeOrmModule.forFeature(...)` are `Scope.REQUEST`.
+- You still need a `TypeOrmModule.forRoot(...)` (or equivalent) at app root to configure the DataSource.
+
+### 2) Enable TransactionalTypeOrmInterceptor() for the controller
+
+Apply the interceptor to ensure a transaction is created for each HTTP request:
+
+```
+import { Controller, UseInterceptors } from '@nestjs/common';
+import { RestfulFactory } from 'nicot';
+import { User } from './user.entity';
+import { TransactionalTypeOrmInterceptor } from 'nicot';
+
+export const UserFactory = new RestfulFactory(User);
+
+@Controller('users')
+@UseInterceptors(TransactionalTypeOrmInterceptor())
+export class UserController extends UserFactory.baseController() {
+  constructor(service: UserService) {
+    super(service);
+  }
+}
+```
+
+Behavior:
+
+- Transaction begins before controller handler runs.
+- Transaction commits when the returned Observable completes.
+- Transaction rolls back when the Observable errors (including thrown HTTP exceptions).
+
+### 3) Inject Transactional Repository / EntityManager in services
+
+To actually use the transaction context, inject the transactional repo/em instead of the default TypeORM ones.
+
+#### Transactional repository (recommended)
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Repository } from 'typeorm';
+import { RestfulFactory } from 'nicot';
+import { InjectTransactionalRepository } from 'nicot';
+import { User } from './user.entity';
+
+export const UserFactory = new RestfulFactory(User);
+
+@Injectable()
+export class UserService extends UserFactory.crudService() {
+  constructor(
+    @InjectTransactionalRepository(User)
+    repo: Repository<User>,
+  ) {
+    super(repo);
+  }
+}
+```
+
+Now all NICOT CRUD operations (`create/findAll/update/delete/import`) will run using the transaction-bound repository when the interceptor is active.
+
+#### Transactional entity manager (advanced)
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { EntityManager } from 'typeorm';
+import { InjectTransactionalEntityManager } from 'nicot';
+
+@Injectable()
+export class UserTxService {
+  constructor(
+    @InjectTransactionalEntityManager()
+    private readonly em: EntityManager,
+  ) {}
+
+  async doSomethingComplex() {
+    // this.em is transaction-bound when interceptor is active
+  }
+}
+```
+
+### Rollback example (404)
+
+If you throw a NICOT exception after writing, the transaction will roll back:
+
+```ts
+@Post('fail')
+async fail() {
+  await this.service.repo.save({ name: 'ROLL' } as any);
+  throw new BlankReturnMessageDto(404, 'message').toException();
+}
+```
+
+Expected:
+
+- HTTP response is `404`
+- database changes are not committed (rollback)
+
+---
+
+## Operation: Atomic business logic on a single entity
+
+NICOT provides an **`operation` abstraction** for implementing
+**atomic, row-level business logic** on top of a `CrudService`.
+
+This abstraction exists on **two different layers**:
+
+1. **Service layer**: `CrudService.operation()`
+2. **Controller layer**: `RestfulFactory.operation()`
+
+They are designed to be **orthogonal**:
+- the service operation **executes domain logic**
+- the factory operation **exposes it as an HTTP endpoint**
+
+You may use either one independently, or combine them.
+
+---
+
+### Service-level operation (`CrudService.operation()`)
+
+#### What it does
+
+`CrudService.operation()` executes a callback with:
+
+- a **row-level write lock** on the target entity
+- a transactional repository (unless one is explicitly provided)
+- automatic **change tracking and flushing**
+- full compatibility with NICOT binding (`@BindingColumn`, `@BindingValue`)
+
+Internally, it follows this lifecycle:
+
+1. Resolve binding values (tenant / owner isolation)
+2. Check entity existence
+3. Open a transaction (unless `options.repo` is provided)
+4. Load the entity with `pessimistic_write` lock
+5. Snapshot column values
+6. Run user callback
+7. Flush only changed columns
+8. Commit or rollback
+
+---
+
+#### Basic usage (inside a service)
+
+```ts
+@Injectable()
+class UserService extends UserFactory.crudService() {
+  async disableUser(id: number) {
+    return this.operation(id, async (user) => {
+      user.isActive = false;
+    });
+  }
+}
+```
+
+Return behavior:
+
+- callback returns `void | undefined | null`  
+  → `BlankReturnMessageDto(200, 'success')`
+- callback returns a value  
+  → `GenericReturnMessageDto(200, 'success', value)`
+
+---
+
+#### Returning business data
+
+```ts
+async disableAndReport(id: number) {
+  return this.operation(id, async (user) => {
+    user.isActive = false;
+    return { disabled: true };
+  });
+}
+```
+
+---
+
+#### Error handling & rollback
+
+Any exception thrown inside the callback causes a rollback.
+
+```ts
+async dangerousOperation(id: number) {
+  return this.operation(id, async () => {
+    throw new BlankReturnMessageDto(403, 'Forbidden').toException();
+  });
+}
+```
+
+---
+
+#### Binding-aware by default
+
+`operation()` never bypasses NICOT binding rules.
+
+If your entity has:
+
+```ts
+@BindingColumn()
+userId: number;
+```
+
+and your service defines:
+
+```ts
+@BindingValue()
+get currentUserId() {
+  return this.ctx.userId;
+}
+```
+
+then `operation()` will automatically:
+
+- restrict existence checks
+- restrict row locking
+- restrict updates
+
+to the current binding scope.
+
+---
+
+#### Using `options.repo` (integration with transactional interceptors)
+
+By default, `operation()` opens its own transaction.
+
+If you pass a repository via `options.repo`,
+**no new transaction will be created**.
+
+This is intended for integration with
+`TransactionalTypeOrmModule` and `TransactionalTypeOrmInterceptor`.
+
+```ts
+@Injectable()
+class UserService extends UserFactory.crudService() {
+  constructor(
+    @InjectTransactionalRepository(User)
+    private readonly repo: Repository<User>,
+  ) {
+    super(repo);
+  }
+
+  async updateInsideRequestTransaction(id: number) {
+    return this.operation(
+      id,
+      async (user) => {
+        user.name = 'Updated in request transaction';
+      },
+      {
+        repo: this.repo,
+      },
+    );
+  }
+}
+```
+
+This allows:
+
+- request-wide transactions
+- consistent behavior across multiple service calls
+- zero coupling between business logic and infrastructure
+
+---
+
+### Controller-level operation (`RestfulFactory.operation()`)
+
+#### What it does (and what it does NOT)
+
+`RestfulFactory.operation()` **does not implement any business logic**.
+
+It only:
+
+- declares an HTTP endpoint
+- wires Swagger metadata
+- standardizes request / response shape
+- delegates execution to your service method
+
+Think of it as **a declarative endpoint generator**, not an executor.
+
+---
+
+#### Declaring an operation endpoint
+
+```ts
+@Controller('users')
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @UserFactory.operation('disable')
+  async disable(@UserFactory.idParam() id: number) {
+    return this.userService.disableUser(id);
+  }
+}
+```
+
+This generates:
+
+- `POST /users/:id/disable`
+- Swagger operation summary
+- standardized NICOT response envelope
+
+---
+
+#### Returning custom data
+
+```ts
+@UserFactory.operation('reset-password', {
+  returnType: ResetPasswordResultDto,
+})
+async resetPassword(@UserFactory.idParam() id: number) {
+  return this.userService.resetPassword(id);
+}
+```
+
+---
+
+### Combining both layers (recommended pattern)
+
+The **recommended pattern** is:
+
+- put **all business logic** in `CrudService.operation()`
+- expose it via `RestfulFactory.operation()`
+
+This gives you:
+
+- reusable domain logic
+- testable service methods
+- thin, declarative controllers
+
+```ts
+@Injectable()
+class UserService extends UserFactory.crudService() {
+  async disableUser(id: number) {
+    return this.operation(id, async (user) => {
+      user.isActive = false;
+    });
+  }
+}
+
+@Controller('users')
+class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @UserFactory.operation('disable')
+  disable(@UserFactory.idParam() id: number) {
+    return this.userService.disableUser(id);
+  }
+}
+```
+
+---
+
+### Design philosophy
+
+- `operation()` is **not** a CRUD replacement
+- it is **not** a generic transaction wrapper
+- it is a **domain-oriented mutation primitive**
+
+In NICOT:
+
+> **CRUD is declarative**  
+> **Operations express intent**
+
+---
+
 ## Best practices
 
 - **One factory per entity**, in its own `*.factory.ts` file.