nicot 1.2.13 → 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)