entity

Entity Skill

This skill helps you create or modify domain entities following the hexagonal architecture conventions using the @efesto-cloud/entity package. Scope: entity class + DTO interface only — persistence (repository, mapper, MongoDB document) is a separate concern handled elsewhere.

Installation: If not already installed, add the package with pnpm add @efesto-cloud/entity (peer dependency: luxon).

Before You Write Anything

Read the existing codebase before generating code:

1. Locate the entity directory (typically packages/core/src/entity/) and read a similar existing entity as a reference
2. Locate the DTO directory (typically packages/core/src/dto/) and read a similar DTO
3. Check for a CLAUDE.md inside the entity directory — it may have project-specific conventions

If the project is new or the entity/dto directories are empty, use the reference files in this skill's references/ directory as your canonical examples instead:

• references/entity-example.ts — fully annotated entity covering every pattern
• references/dto-example.ts — fully annotated DTO covering every pattern
• references/entity-union.ts — entity union pattern: abstract base + multiple concrete subtypes discriminated by a type literal
• references/dto-union.ts — DTO union pattern: base interface + concrete sub-interfaces each carrying a type literal discriminant

These reference files cover all the patterns described below. Read them before generating code on a fresh project — they contain inline comments explaining the why behind each convention.

---

File Structure

For a new entity you'll create two files:

• src/dto/IEntityName.ts — the public data contract (DTO interface)
• src/entity/EntityName.ts — the domain entity class

Then export both from their respective index files.

For modifying an existing entity, read the files first, then apply changes consistently across both.

---

DTO Interface

The DTO is the public serialization contract. It has no methods — pure native data types.

// src/dto/IEntityName.ts
export default interface IEntityName {
    _id: string;            // always string (serialized from ObjectId or UUID)
    name: string;
    description: string;
    slug?: string;
    deleted_at: string | null;  // DateTime serialized as ISO string
    // foreign keys end with _id: string
    parent_id: string | null;
}

Rules:

• All properties snake_case
• Primary key: _id: string
• Foreign keys: parent_id, elemento_id, etc.
• DateTime → string (ISO); nullable → string | null
• No methods, no business logic
• Only native types (string, number, boolean, arrays, nested DTOs) — no domain types or value objects here (use their DTO representation instead if needed)
• 1 entity = 1 DTO interface;

---

Entity Class

// src/entity/EntityName.ts
import { Entity, IEntity } from "@efesto-cloud/entity";
import Maybe from "@efesto-cloud/maybe";
import Result from "@efesto-cloud/result";
import { DateTime } from "luxon";
import { ObjectId } from "mongodb";  // or UUID — check what the project uses
import IEntityName from "~/dto/IEntityName.js";

type EntityNameProps = {
    name: string;
    description: string;
    deleted_at: DateTime<true> | null;
    // Use domain types, not primitives for complex concepts
    // e.g. email: EmailAddress  (not string)
};

export default class EntityName extends Entity<EntityNameProps, ObjectId> implements IEntity<ObjectId> {
    constructor(props: EntityNameProps, id?: ObjectId) {
        super(props, new ObjectId(id));  // always wrap in ID constructor
    }

    // Getters — one per prop, no setters unless business-justified
    get name(): string { return this.props.name; }
    get description(): string { return this.props.description; }

    // Business methods — describe intent, not data access
    // Return Result<T, Error> for fallible operations
    // Return void for infallible mutations
    someOperation(input: string): Result<void, Error> {
        if (!input) return Result.err(new Error("Invalid input"));
        this.props.name = input;
        return Result.ok(undefined);
    }

    toDTO(): IEntityName {
        return {
            _id: this._id.toHexString(),      // ObjectId → string
            // _id: this._id.toString(),       // UUID → string
            name: this.props.name,
            description: this.props.description,
            deleted_at: this.deleted_at?.toISO() ?? null,
            // nested entity: this.props.nested?.toDTO() ?? null
            // array: this.props.items.map(i => i.toDTO())
        };
    }

    static create(props: {
        name?: string;
        description?: string;
        deleted_at?: DateTime<true> | null;
        // all props optional — use ?? to apply defaults
    }, id?: ObjectId) {
        return new EntityName({
            name: props.name ?? "",
            description: props.description ?? "",
            deleted_at: props.deleted_at ?? null,
        }, id);
    }
}

Key rules:

• Constructor: super(props, new ObjectId(id)) — wraps id even if already the right type
• Never instantiate directly from outside — always go through static create()
• The majority of create() props are optional with ?? defaults, required fields are the ones strictly necessary (usually dictated by business rules, not technical ones)
• Getters for everything; only add setters when the operation has business meaning
• deleted_at pattern: DateTime<true> | null for soft deletes

Inherited members from Entity base

All entities inherit these from the Entity base class — do not redefine them:

Member	Type	Description
v	number | null	Version number — 0 for new (unsaved) entities, > 0 after first persist
isNew()	() => boolean	Returns true when v === 0
isUpdated()	() => boolean	Returns true when v !== 0
delete()	() => void	Soft-deletes: sets deleted_at to now
restore()	() => void	Undoes a soft-delete: sets deleted_at to null
isDeleted()	() => boolean	Returns true when deleted_at !== null

Inheritance

When extending a base entity class:

type EntityNameProps = BaseProps & { extraField: string; };

class EntityName extends BaseClass<EntityNameProps, ObjectId> {
    override toDTO(): IEntityName {
        return { ...super.toDTO(), extraField: this.props.extraField };
    }
}

For the union + abstract base pattern (multiple concrete subtypes distinguished by a type literal), read references/entity-union.ts (entities) and references/dto-union.ts (DTOs). Both files use matching type names and discriminants so you can see the entity↔DTO correspondence directly.

---

Audit trail pattern

For entities that track who changed what:

// In props:
created_at: DateTime;
updated_at: DateTime;
updated_by: Operator | null;  // import the Operator entity

// In business methods that mutate state:
this.props.updated_at = DateTime.now();
this.props.updated_by = operator;

Value objects

Prefer value objects for complex domain concepts rather than raw primitives. Check the project's src/value_object/ directory for what's available before defaulting to string. Common ones:

• Email → EmailAddress
• Password → Password
• If the concept doesn't have an existing value object, use a plain type for now and note that it could become one.

---

Exports

Add to src/entity/index.ts:

export { default as EntityName } from "./EntityName.js";

Add to src/dto/index.ts:

export type { default as IEntityName } from "./IEntityName.js";

---

Checklist — New Entity

• Read a comparable existing entity first
• DTO created in src/dto/IEntityName.ts with _id: string
• Entity class in src/entity/EntityName.ts with create() factory
• All props have getters; create() has optional props with ?? defaults
• toDTO() maps every DTO field; ID converted to string
• Both exported from their index files
• Run typecheck

Checklist — Modifying Existing Entity

• Read the entity file and DTO file first
• New prop added to EntityNameProps type
• Getter added
• create() updated with optional prop + default
• toDTO() updated to include new field
• DTO interface updated
• Run typecheck