Defining Entities

Entities are TypeScript classes annotated with the @Entity() decorator. Each entity gets a fully typed CRUD service generated automatically.

Basic Entity

Every entity needs at least the @Entity() decorator on the class and an ID field.

import { Entity, AutoGeneratedId, NotNull, MultiTenancyType } from '@kinotic-ai/persistence'

@Entity(MultiTenancyType.NONE)
export class Person {
    @AutoGeneratedId
    id: string | null = null

    @NotNull
    firstName: string = ''

    @NotNull
    lastName: string = ''

    age: number = 0
}

Properties Should Have Default Values

All properties on an entity class should have default values assigned. This ensures proper serialization and deserialization when data moves between your application and the server.

The @Entity Decorator

The @Entity() decorator accepts two parameters:

@Entity(multiTenancyType, entityType)

Multi-Tenancy Type

• MultiTenancyType.NONE - No multi-tenancy. All data lives in a single index.
• MultiTenancyType.SHARED - Shared index with automatic tenant isolation. Requires a @TenantId field on the entity.

Entity Type

• EntityType.TABLE (default) - Standard entity for general-purpose data storage.
• EntityType.STREAM - Time-series data optimized for append-heavy workloads. Requires a @TimeReference field.

ID Fields

Every entity must have exactly one ID field. You choose between two strategies:

@AutoGeneratedId

Use @AutoGeneratedId when you want the server to assign IDs automatically. The field type must be string | null, initialized to null.

@AutoGeneratedId
id: string | null = null

When you save a new entity, the server generates a unique ID and returns it on the saved object.

@Id

Use @Id when you want to control the ID value yourself.

import { Entity, Id, MultiTenancyType } from '@kinotic-ai/persistence'

@Entity(MultiTenancyType.NONE)
export class Device {
    @Id
    serialNumber: string = ''

    name: string = ''
}

With @Id, you are responsible for providing a unique value before saving.