// use it
const austin = new Address({
street: '123 South Congress',
suite: null,
city: 'Austin',
state: 'Texas',
postal: '78704',
});
`

$3

In Domain Driven Design, an Entity is a type of Domain Object for which:

- properties change over time
- e.g., it has a lifecycle
- identity matters
- i.e., it represents a distinct existence
- e.g., two entities could have the same properties, differing only by id, and are still considered different entities
- e.g., you can update properties on an entity and it is still considered the same entity

`ts
// define it
interface RocketShip {
uuid?: string;
serialNumber: string;
fuelQuantity: number;
passengers: number;
homeAddress: Address;
}
class RocketShip extends DomainEntity implements RocketShip {
/**
* an entity is uniquely identifiable by some subset of their properties
*
* in order to use the getUniqueIdentifier and serialize methods on domain entities,
* we must define the properties that the entity is uniquely identifiable by.
*/
public static unique = ['serialNumber'];
}

// use it
const ship = new RocketShip({
serialNumber: 'SN5,
fuelQuantity: 9001,
passengers: 21,
homeAddress: new Address({ ... }),
});
`

References (Ref, RefByUnique, RefByPrimary)

In work with entities and events, you often need to refer to them by their primary key (e.g., uuid) or by their unique keys (e.g., a compound unique such as { source, exid }). domain-objects provides utility types to make this type-safe.

$3

RefByPrimary extracts the shape of the primary key for a given domain object.

`ts
import { DomainEntity, RefByPrimary } from 'domain-objects';

interface SeaTurtle {
uuid?: string;
seawaterSecurityNumber: string;
name: string;
}
class SeaTurtle extends DomainEntity implements SeaTurtle {
public static primary = ['uuid'] as const;
public static unique = ['seawaterSecurityNumber'] as const;
}

// ✅ valid
const primaryRef: RefByPrimary = { uuid: 'beefbeef...' };

// ❌ invalid - must be a string
const wrongType: RefByPrimary = { uuid: 8335 };

// ❌ invalid - wrong key
const wrongKey: RefByPrimary = { guid: 'beefbeef...' };

// ❌ invalid - missing primary key
const missing: RefByPrimary = {};
`

$3

RefByUnique extracts the shape of the unique key(s) for a given domain object.

`ts
import { DomainEntity, RefByUnique } from 'domain-objects';

interface SeaTurtle {
uuid?: string;
seawaterSecurityNumber: string;
name: string;
}
class SeaTurtle extends DomainEntity implements SeaTurtle {
public static primary = ['uuid'] as const;
public static unique = ['seawaterSecurityNumber'] as const;
}

// ✅ valid
const uniqueRef: RefByUnique = { seawaterSecurityNumber: 'ABC-999' };

// ❌ invalid - wrong type
const wrongType: RefByUnique = { seawaterSecurityNumber: 999 };

// ❌ invalid - wrong key
const wrongKey: RefByUnique = { saltwaterSecurityNumber: 'ABC-999' };

// ❌ invalid - empty object
const empty: RefByUnique = {};
`

$3

Ref is a union type that allows referring to a domain object by either primary key or unique keys.

`ts
import { DomainEntity, Ref } from 'domain-objects';

interface EarthWorm {
uuid?: string;
soilSecurityNumber: string;
wormSegmentNumber: string;
name: string;
}
class EarthWorm extends DomainEntity implements EarthWorm {
public static primary = ['uuid'] as const;
public static unique = ['soilSecurityNumber', 'wormSegmentNumber'] as const;
}

// ✅ primary
const byPrimary: Ref = { uuid: 'beefbeef...' };

// ✅ unique
const byUnique: Ref = {
soilSecurityNumber: 'SOIL-001',
wormSegmentNumber: 'SEG-42',
};

// ❌ invalid - missed part of unique key
const incompleteUnique: Ref = { soilSecurityNumber: 'SOIL-001' };

// ❌ invalid - not related to either key
const wrongKey: Ref = { guid: 'beefbeef...' };

// ❌ invalid - empty object
const empty: Ref = {};
`

👉 Use RefByPrimary for primary-only references,
👉 RefByUnique for unique-only references,
👉 Ref when you want to allow either.

$3

You can instantiate reference objects directly using the RefByUnique or RefByPrimary constructors:

`ts
import { RefByUnique, RefByPrimary } from 'domain-objects';

// Using RefByUnique
const turtleRef = RefByUnique.build({
seawaterSecurityNumber: '821',
});

// Using RefByPrimary
const turtleRefById = RefByPrimary.build({
uuid: 'beefbeef-cafe-babe-0000-000000000001',
});
`

$3

Just like other nested domain objects, references can be automatically hydrated when used as nested properties:

`ts
import { DomainEntity, RefByUnique, RefByPrimary } from 'domain-objects';

interface SeaTurtleShell {
turtle: RefByUnique;
algea: 'ALOT' | 'ALIL';
}
class SeaTurtleShell extends DomainEntity implements SeaTurtleShell {
public static unique = ['turtle'] as const;
public static nested = {
turtle: RefByUnique,
};
}

// now you can pass a plain object and it will be hydrated as a RefByUnique
const shell = new SeaTurtleShell({
turtle: { seawaterSecurityNumber: '821' }, // plain object
algea: 'ALOT',
});

expect(shell.turtle).toBeInstanceOf(RefByUnique); // ✅ automatically hydrated!
expect(shell.turtle.seawaterSecurityNumber).toEqual('821');
`

Run Time Validation

Runtime validation is a great way to fail fast and prevent unexpected errors.

domain-objects supports an easy way to add runtime validation, by defining a Zod, Yup, or Joi schema.

When you provide a schema in your type definition, your domain objects will now be run time validated at instantiation.

example:

`ts
// with this declaration of a "RocketShip", the schema specifies that there can be a max of 42 passengers
interface RocketShip {
serialNumber: string;
fuelQuantity: number;
passengers: number;
}
const schema = Joi.object().keys({
serialNumber: Joi.string().uuid().required(),
fuelQuantity: Joi.number().required(),
passengers: Joi.number().max(42).required(),
});
class RocketShip extends DomainObject implements RocketShip {
public static schema = schema;
}

// so if we try the following, we will get an error
new RocketShip({
serialNumber: uuid(),
fuelQuantity: 9001,
passengers: 50,
});

// throws JoiValidationError
`

We made sure that the errors are as descriptive as possible to help with debugging. For example, the error that would have been shown above has the following message:

`
Errors on 1 properties were found while validating properties for domain object RocketShip.:
[
{
"message": "\"passengers\" must be less than or equal to 42",
"path": "passengers",
"type": "number.max"
}
]

Props Provided:
{
"serialNumber": "eeb6988c-d877-4268-b841-bde2f40b377e",
"fuelQuantity": 9001,
"passengers": 50
}
`

Nested Hydration

> _TL:DR;_ Without DomainObject.nested, you will need to manually instantiate nested domain objects every time. If you forget, getUniqueIdentifier and serialize will throw errors.

Nested hydration is useful when instantiating DomainObjects that are composed of other DomainObjects. For example, in the RocketShip example above, RocketShip has Address as a nested property (i.e., typeof Spaceship.address === Address).

When attempting to manipulate DomainObjects with nested DomainObjects, like the Spaceship.address example, it is important that all nested domain objects are instantiated with their class. Otherwise, if RocketShip.address is not an instanceof Address, then we will not be able to utilize the domain information baked into the static properties of Address (e.g., that it is a DomainLiteral).

domain-objects makes it easy to instantiate nested DomainObjects, by exposing the DomainObject.nested static property.

For example:

`ts
// define the domain objects that you'll be nesting
interface PlantPot {
diameterInInches: number;
}
class PlantPot extends DomainLiteral implements PlantPot {}
interface PlantOwner {
name: string;
}
class PlantOwner extends DomainEntity implements PlantOwner {}

// define the plant
interface Plant {
pot: PlantPot;
owners: PlantOwner[];
lastWatered: string;
}
class Plant extends DomainEntity implements Plant {
/**
* define that pot and owners are nested domain objects, and specify which domain objects they are, so that they can be hydrated during instantiation if needed.
*/
public static nested = { pot: PlantPot, owners: PlantOwner };
}

// instantiate your domain object
const plant = new Plant({
pot: { diameterInInches: 7 }, // note, not an instance of PlantPot
owners: [{ name: 'bob' }], // note, not an instance of PlantOwner
lastWatered: 'monday',
});

// and find that, because .nested.pot was defined, pot was instantiated as a PlantPot
expect(plant.pot).toBeInstanceOf(PlantPot);

// and find that, because .nested.owners was defined, each element of owners was instantiated as a PlantOwner
plant.owners.forEach((owner) => expect(owner).toBeInstance(PlantOwner));
`

You may be thinking to yourself, "Didn't i just define what the nested DomainObjects were in the type definition, when defining the interface? Why do i have to define it again?". Agreed! Unfortunately, typescript removes all type information at runtime. Therefore, we have no choice but to repeat this information in another way if we want to use this information at runtime. (See #8 for progress on automating this).

fn getUniqueIdentifier(obj: DomainEntity | DomainLiteral)

Domain models inform us of what properties uniquely identify a domain object.

i.e.,:
- literals are uniquely identified by all of their non-metadata properties
- entities are uniquely identified by an explicitly subset of their properties, declared via the .unique static property

this getUniqueIdentifier function leverages this knowledge to return a normal object containing only the properties that uniquely identify the domain object you give it.

fn serialize(value: any)

Domain modeling gives additional information that we can use for change detection and identity comparisons.

domain-objects allows us to use that information conveniently with the functions serialize.

serialize deterministically converts any object you give it into a string representation:

- deterministically sort all array items
- deterministically sort all object keys
- remove non-unique properties from nested domain objects

due to this deterministic serialization, we are able to use this fn for change detection and identity comparisons. See the examples section above for an example of each.

Readonly vs Metadata Properties

Domain objects support two categories of readonly properties. Both are set by the persistence layer, but they differ in what they describe. Metadata is a special subset of readonly - all metadata is readonly, but not all readonly is metadata.

$3

Metadata are attributes set by the persistence layer that describe the persistence of the object - not intrinsic attributes of the domain object itself. This is the most common type of readonly property and applies to all domain objects (entities, events, and literals).

- Default metadata keys: id, uuid, createdAt, updatedAt, effectiveAt
- Customize via static metadata = ['...'] as const;
- Omit with omitMetadata(obj)

`ts
class User extends DomainEntity implements User {
public static primary = ['id'] as const;
public static unique = ['email'] as const;
public static metadata = ['id', 'createdAt', 'updatedAt'] as const;
}
`

$3

Readonly (non-metadata) are intrinsic attributes of the object that the persistence layer sets. Unlike metadata (which describes the persistence), these describe real attributes of the domain object.

- Only applicable to DomainEntity (not DomainEvent or DomainLiteral)
- No default readonly keys (domain-specific, must be explicitly declared)
- Declare via static readonly = ['...'] as const;
- Omit with omitReadonly(obj) - this omits both metadata AND explicit readonly keys

Why only DomainEntity?
- DomainEvent: Immutable by nature. All properties are known before persistence - there's no concept of persistence-layer-set intrinsic attributes.
- DomainLiteral: Immutable by nature and fully defined by intrinsic properties. If a property changes, it's a different literal.

`ts
class AwsRdsCluster extends DomainEntity implements AwsRdsCluster {
public static primary = ['arn'] as const;
public static unique = ['name'] as const;
public static metadata = ['arn'] as const; // AWS-assigned identity (describes persistence)
public static readonly = ['host', 'port', 'status'] as const; // AWS-resolved intrinsic attributes (describes the object)
}
`

$3

| Aspect | Metadata | Readonly (broader) |
|--------|----------|----------|
| Relationship | A special subset of readonly | The superset containing metadata + more |
| Applies to | All domain objects | DomainEntity only |
| What it describes | Persistence of the object | Intrinsic attributes of the object |
| Set by | Persistence layer | Persistence layer |
| Default keys | Yes (id, uuid, etc.) | No (explicit only) |
| Omit function | omitMetadata() | omitReadonly() (includes metadata) |

DomainObject.build

Add getters to your domain object instances, easily.

By default, .build will wrap your dobj instances withImmute, to give you immute operations such as .clone(andSet?: Partial)

For example,
`ts
const ship = RocketShip.build({
serialNumber: 'SN1',
fuelQuantity: 9001,
passengers: 3,
});
const shipTwin = ship.clone()
const shipUsed = ship.clone({ fuelQuantity: 821 })
`

Note, you can override your DomainObject's .build procedure to add your own getters

For example,
`ts

`

This gives you a simple way to enrich your objects with domain-specific logic, while still preserving immutability and ergonomics.

withImmute


Wraps any domain object to make it safer to use via immutable operations.

Immutability helps avoid bugs caused by shared object references - where multiple procedures unintentionally share the same instance of data in memory. This is especially common concern in systems which leverage parallelism.

withImmute adds immute operators to your dobj, such as
- .clone(update?: Partial)

Added by default via .build(). Available for adhoc usage too:

`ts
const plant = withImmute(new Plant({ ... }));
const twin = plant.clone()
`

withImmute.clone(update?: Partial)

Creates a new instance of the domain object with updated values — without modifying the original.

This is helpful when working in a system that depends on immutability, such as functional logic, undo/redo flows, or parallel processing, where unintended mutations can introduce bugs.

The .clone() method uses deep cloning and deep merging:
- Every nested value is safely copied.
- Only the fields you provide in the update are changed.
- Original object remains untouched.

Example:

`ts
const plant = Plant.build({
plantedIn: new PlantPot({ diameterInInches: 5 }),
lastWatered: 'Monday',
});

const updated = plant.clone({ lastWatered: 'Tuesday' });

expect(updated.lastWatered).toEqual('Tuesday');
expect(plant.lastWatered).toEqual('Monday'); // original is unchanged
``