How to access a newly created entity?

[purefun]

booster/packages/framework-types/src/concepts/command.ts

Line 10 in cfea264

handle(command: TCommand, register: Register): Promise<void>

There is a common scenario:
a user creates a chat room, then the user can enter the chat room immediately and subscribe it. But the command handler doesn't return anything useful, how Booster achieve the UX? IMHO, the frontend doesn't need to know to generate the entity id. Thank you.

[purefun]

Then I found TODO code 😂 :

booster/packages/framework-core/src/services/graphql/graphql-mutation-generator.ts

Lines 23 to 38 in cfea264

	private generateMutations(): GraphQLFieldConfigMap<any, any> {
	const mutations: GraphQLFieldConfigMap<any, any> = {}
	for (const name in this.targetTypes) {
	const type = this.targetTypes[name]
	mutations[name] = {
	type: GraphQLBoolean, // TODO: Return the request ID an useful information
	args: {
	input: {
	type: new GraphQLNonNull(this.typeInformer.getGraphQLInputTypeFor(type.class)),
	},
	},
	resolve: this.mutationResolver(type.class),
	}
	}
	return mutations
	}

[NickSeagull]

Hey, thanks for reporting, discussing these things are super important for us to figure out the best UX 😄

Still, you should not rely on the entity itself as the source of truth, but rather on the events. You cannot access entities (well, you can with the Booster.entity function, but generally you don't want that) and rather you would access read models if you wanted to access the state of your system.

In fact, even if that TODO returned something, an entity ID wouldn't be in that response 😅

The reason is that entities are in some middle ground between the write (commands) and the read (read models) parts of the framework and are mainly used for snapshotting and relative ordering of events.

Events are a way of defining that stuff has happened in your app (facts), entities then use them to generate the state they hold.

Let's see how we can integrate this knowledge into your example. I'm gonna be separating by use cases.

Creating a room and joining

If your chat app lets users join the rooms instantly after creation, you can either create a RoomWithParticipantCreated event to model that, or register two events:

public handle(command: TCommand, register: Register): Promise<void> {
  // some logic
  const roomId = UUID.generate()
  register.events(new RoomWithParticipantCreated(roomId, command.userId, /* more parameters */))
 
  // or
  register.events(new RoomCreated(roomId), new RoomJoined(roomId, command.userId))
}

With this, we could write an entity for the room that has the participant inside already:

@Entity
export class Room {
  public constructor(public id: UUID, readonly participants: Array<UUID>) {}

  @Reduces(RoomCreated)
  public static reduceRoomCreated(event: RoomCreated): Room {
    return new Room(event.roomId, [])
  }

  @Reduces(RoomJoined)
  public static reduceRoomJoined(event: RoomCreated, entity?: Room): Room {
    if (!entity) throw new Error(`Room with event ${event.roomId} not found`)
    return new Room(entity.id, [...entity.participants, event.userId])
  }
}

Letting the user know which room they participate in

Given that this is a different piece of data, we'd have to create a new entity called MyRooms which will be updated each time that a user joins some room. In order to do so, we'd have to create a MyRoomsUpdated event representing an update in this entity and an event handler to transform the RoomJoined event into MyRoomsUpdated:

@EventHandler(RoomJoined)
export class MyRoomsUpdater {
  public static async handle(
    event: RoomJoined,
    register: Register
  ): Promise<void> {
    register.events(new MyRoomsUpdated(event.roomId, event.userId))
  }
}

And then the entity:

@Entity
export class MyRooms {
  public constructor(public id: UUID, readonly rooms: Array<UUID>) {}

  @Reduces(MyRoomsUpdated)
  public static reduceMyRoomsUpdated(event: MyRoomsUpdated, entity?: MyRooms): MyRooms {
    const rooms = entity?.rooms ?? []
    return new MyRooms(event.userId, [rooms, event.roomId])
  }
}

This way you could then access it from a MyRoomsReadModel read model or whatever :)

Why so much hassle

One of the Booster goals is to provide an efficient way to create apps that support high throughput situations without making the developer have to think in these restrictions. In order to achieve this, some constraints have to be set, and we are constantly working to figure out how to ease these constraints and make the UX much better.

So, again, thanks for reporting, I hope that this has been useful in some way 😄

PS: Moving this to a discussion, as it is much more appropriate there

[purefun]

I never thought you would answer the question with so many details. Thank you. MyRooms entity is a good way for better ux.

[NickSeagull]

You're very welcome, feel free to ask as many questions as you want either here or on Discord. Thanks a lot for bringing this up! 😄