docs: Unwrapping Nested Objects using Embeddables or Custom Types

[vinialbano]

Context

In a domain-driven design project utilizing MikroORM, I use value objects like Period that encapsulate properties within a _value structure. My goal is to persist the start and end properties as separate columns (period_start and period_end) in the database, instead of storing them as a JSON object. However, I face challenges with hydrating and persisting these properties as individual columns.

Value Object Definition

The Period value object is defined as follows, encapsulating its properties and exposing them through getters:

import { ValueObject } from './value-object';

export type PeriodProps = {
  start: Date;
  end?: Date;
};

export class Period extends ValueObject<PeriodProps> {
  constructor(props: PeriodProps) {
    super(props);
  }

  get start(): Date {
    return this.value.start;
  }

  get end(): Date | undefined {
    return this.value.end;
  }
}

The base ValueObject class is as follows:

export abstract class ValueObject<Value = any> {
  protected readonly _value: Value;

  constructor(value: Value) {
    this._value = deepFreeze(value);
  }

  get value(): Value {
    return this._value;
  }
}

Embeddable Schema Configuration

Setting up the entity schema presented challenges, particularly because the properties are not directly accessible due to their encapsulation within a _value object. Attempting to configure hydration settings did not resolve these issues:

import { EntitySchema } from '@mikro-orm/core';
import { Period } from '../../../common/domain/value-objects/period.vo';

export const PeriodSchema = new EntitySchema<Omit<Period, 'value'>>({
  class: Period,
  embeddable: true,
  properties: {
    start: {
      type: Date,
      hydrate: false,
    },
    end: {
      type: Date,
      nullable: true,
      hydrate: false,
    },
  },
  forceConstructor: true,
});

An error occurs stating, Cannot set property start of #<Period> which has only a getter, even when hydration is disabled.

Desired Database Format Conversion

I aim to convert entities with a structure like this:

Lecture {
  id: { _value: "123" },
  period: { 
    _value: { 
      start: Date(), 
      end: Date()
    }
  }
}

Into a format like this in the database:

Lecture {
  id: "123",
  period_start: Date(),
  period_end: Date(),
}

And then be able to restore the original entity, when reading from the database.
While I successfully converted the id using a custom type, the period, being an object, posed difficulties.

I tried to make it work through the following schema:

export const LectureSchema = new EntitySchema<Lecture>({
  class: Lecture,
  properties: {
    id: {
      type: new LectureIdSchemaType(),
      primary: true,
    },
    period: {
      kind: 'embedded',
      entity: 'Period',
      nullable: true,
      prefix: 'period_',
    },
  },
})

And the LectureIdSchemaType is:

export class LectureIdSchemaType extends Type<LectureId, string> {
  convertToDatabaseValue(
    valueObject: LectureId | undefined | null,
    platform: Platform,
  ): string {
    return valueObject instanceof LectureId
      ? valueObject.value
      : (valueObject as unknown as string);
  }

  convertToJSValue(value: string, platform: Platform): LectureId {
    return new LectureId(value);
  }

  getColumnType(prop: EntityProperty, platform: Platform) {
    return `varchar(24)`;
  }
}

Questions and Requests for Guidance

• Hydration and Persistence: How can MikroORM be configured to effectively manage value objects like Period, which encapsulate their properties within a _value object, especially when these properties need to be stored in separate database columns?
• Custom Types and Multi-Column Support: Are there recommended practices or workarounds to facilitate the use of custom types for multi-column serialization and deserialization?
• Embeddable Handling: What are the best practices or additional configuration options for managing embeddables that encapsulate complex structures similar to my Period object?

I would greatly appreciate any guidance or recommendations on how to resolve these issues.

[B4nan]

I will get back to this later, for now just a few quick comments.

Hydration and Persistence: How can MikroORM be configured to effectively manage value objects like Period, which encapsulate their properties within a _value object, especially when these properties need to be stored in separate database columns?

Instead of asking "show me how to do this", please provide a complete but minimal reproduction so I can actually start experimenting right ahead with the problems you see - that's the fastest way to find an actual resolution.

You should use embeddables for this. I would stay away from rather internal options like hydrate, at least not as part of "let's try this and that without understanding what it does".

Custom Types and Multi-Column Support: Are there recommended practices or workarounds to facilitate the use of custom types for multi-column serialization and deserialization?

This is a non-goal to me, custom types abstract a single-column transform only and I don't plan to change this in the foreseeable future.

Embeddable Handling: What are the best practices or additional configuration options for managing embeddables that encapsulate complex structures similar to my Period object?

The only best practice I can offer is this: keep things simple, what you are up to sounds like a lot of abstraction already, but I guess that's not what you wanted to hear :]

[vinialbano]

Hello @B4nan, I appreciate your prompt response. I have provided as many details as possible regarding my query, but to make things easier, I have created a repository at the following URL: https://github.com/vinialbano/mikro-orm-with-ddd.

All you have to do is to install and run the tests. Once you do, you'll notice that my objective is to unwrap the Period value object to save the information in the database, and then recover the original structure when retrieving the record from the database.

In the schema definition (src/lectures/infra/db/schemas.ts), you'll see that I have commented out the embeddable definition to enable the tests to run. If you change it back, you'll receive the error I mentioned earlier, which is that there is no setter.

If there's a way to make everything work, it will be amazing!

Thanks again for your support.

[vinialbano]

Hi @B4nan did you have a chance to look at this?
Thanks