> For the complete documentation index, see [llms.txt](https://docs.soapjs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soapjs.com/components/entity.md).

# Entity

## Entity

An **entity** is a plain TypeScript class representing a domain object — your business model, free of any framework or database concerns. It lives in a feature's `domain/` folder. You write it by hand (SoapJS has no scaffolding CLI):

```typescript
export type CharacterUniverse = 'marvel' | 'dc';
export type CharacterAlignment = 'hero' | 'villain' | 'anti-hero';

export class Character {
  constructor(
    public readonly id: string,
    public readonly name: string,
    public readonly universe: CharacterUniverse,
    public readonly alignment: CharacterAlignment,
    public readonly createdAt: Date,
    public readonly updatedAt: Date,
  ) {}
}
```

### Validated factories

Keep invariants in the domain: expose a `static create()` that validates untrusted input and returns a `Result`, reserving the constructor for trusted rehydration (the mapper, seeds):

```typescript
import { Result, Failure } from '@soapjs/soap';

static create(props: CharacterProps): Result<Character> {
  if (!props.name?.trim()) {
    return Result.withFailure(Failure.fromError(new ValidationError('name is required')));
  }
  return Result.withSuccess(new Character(/* ...validated fields */));
}
```

Entities are pure — no decorators, no DB types. The database shape lives in a Model; a Mapper converts between the two. See the [demo](https://github.com/soapjs/soap-node-demo) for full examples.