Meta fields support

[DellanX]

Is your feature request related to a problem? Please describe.

Nope, just preparing for some optimizations

Describe the solution you'd like

I have some attributes that I send with every model, that I don't really need to, so I plan on moving them into the meta object.

For example, createdAt and updatedAt will be on the resource's meta object. These fields are read-only from the client perspective, as they are handled entirely by the server. This I could keep in the attributes, so this Feature Request isn't a hard requirement. That said, where I do need it, is for relationship counts. Basically, consider querying notification count. I can configure my jsonapi server to send this via the related link's meta object.

Describe alternatives you've considered

I can keep the createdAt and updatedAt in the attributes without issue. As for querying notificationCount, I'd probably need to use json-rpc to query those values. Not impossible, but inconvinient.

Additional context

The best solution, which may not be possible as there isn't a standard of how count is added to meta (or meta objects really), would be for this library to read the link related meta object's count field and create a PaginateEntityCollection for that relationship with the provided count as the totalCount. We don't need any data at this point, but can easily fetch said data.

As always, I am willing to help

Here is an example payload with count, that said, since count isn't really a standard, developers might have it as a different name. Most instances won't even have it.

{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": {
      "content": "...",
      "title": "Hello World"
    },
    "relationships": {
      "comments": {
        "links": {
          "self": "http://localhost/api/v1/posts/1/relationships/comments",
          "related": "http://localhost/api/v1/posts/1/comments"
        },
        "meta": {
          "count": 17
        }
      },
      "tags": {
        "links": {
          "self": "http://localhost/api/v1/posts/1/relationships/tags",
          "related": "http://localhost/api/v1/posts/1/tags"
        },
        "meta": {
          "count": 4
        }
      }
    },
    "links": {
      "self": "http://localhost/api/v1/posts/1"
    }
  }
}

[dpimonov]

Hi DellanX, thanks as always for the interesting issues. ;)

There is already a class responsible for extracting pagination-related information called JsonApiMetadataExtractor. It can be overridden and provided with the rest of configuration to extract the total count of entities in a collection. Right now, it is used for root document objects when working with collections.

There is also a class that already covers a use case similar to yours, but from a slightly different angle: JsonApiToManyRelationship. It allows you to work with relationships in the same way as with root collections. You can check the readme page for more info but API is basically the same as with regular entity sets.

const userMessages = jsonApiEntityProvider.createJsonApiToManyRelationship(userSet, user, u => u.messages);

const firstPageData = await userMessages.paginate(x => x.pageSize(1, 10)).findAll();
const secondPageData = await userMessages.paginate(x => x.pageSize(2, 10)).findAll();
const lastPageData = await userMessages.paginate(x => x.pageSize(4, 10)).findAll();

This reflects what is currently available and how you can already make use of your meta object. At the moment, it is possible to read custom pagination metadata (like total counts) for paginated entity collections both from root resources and from relationships.

If you specifically want to have an entity that contains a paginated entity collection as a property, that would require some additional work. In that case, we would need to:

1. Create a custom serializer that uses entity store information together with the related provider to properly serialize and deserialize such collections. The type manager always starts from the root object and drills down. When it encounters a relationship property, it needs explicit instructions on how that property should be serialized and deserialized.

2. Merge meta information with related entity data. Currently, meta fields like $id, $type, and custom meta objects are stripped out by the adapter, which prepares a raw serialized object. For this use case, these fields would need to be preserved so the serializer can read them. This likely requires an additional wrapper, because collections are currently transferred as plain arrays. I can not say yet what the best implementation approach would be, but this step is essential.

3. Include navigation links such as prev, next, first, and last, not just total counts, to make pagination work properly.

4. After that, your entity could look something like this:

@Type()
@JsonApiResource({
    type: 'post',
    route: 'posts'
})
export class Post
{
    @Property(String) public id?: string;
    @Property(JsonApiPaginatedEntityCollection, [Comment]) public comments!: JsonApiPaginatedEntityCollection<Comment>;
}

Before going down this path, I'd like to clarify one thing: are you already aware that you can work with relationships using the existing relationship classes? They already extract and expose exactly the data you're asking for.

The key difference is that relationships are not requested together with the user itself. Instead, you work with them via links as standalone, self-sufficient collections. In practice, this usually covers the real need, because embedding paginated collections directly inside entities tends to break pagination metadata very quickly once entities are modified.

Let me know your thoughts - happy to discuss the best approach further.

[DellanX]

So, I'm now about ready to dive in again.

I do already use the relationship classes such as:

const userMessages = jsonApiEntityProvider.createJsonApiToManyRelationship(userSet, user, u => u.messages);

const firstPageData = await userMessages.paginate(x => x.pageSize(1, 10)).findAll();
const secondPageData = await userMessages.paginate(x => x.pageSize(2, 10)).findAll();
const lastPageData = await userMessages.paginate(x => x.pageSize(4, 10)).findAll();

The issue here now is about trying to append some of this data with a single query without using an include clause. Think like if I am rendering a home page, and I want to see badges for unread notifications/messages.

Right now, I am just fetching the relationship with a pageSize of 1, and seeing the totalCount. That said, it's still a separate query, which I am hoping to optimize out.

The real big one I keep forgetting about though, is LID. If I do an optimistic update, I would like to be able to associate a local ID until the server can respond with the proper id. I'd like to pass this LUID with meta, so that I can remove the appropriate optimisticly inserted element from my EntityCollection (I use a custom wrapper class that allows inserts/removes as a post-processing step).

How would I go about the custom serializer in this context? Basically I'd like to keep serializing/deserializing my data the same way, except I'd like to append the meta fields such as LID, createdAt, updatedAt to my model. I'd also like to pull the unreadMessagesCount unreadNotificationsCount from the relationship object's meta fields.

I've written a custom serializer for luxon's DateTime object. Would it be a similar process here?

[dpimonov]

The idea is fairly straightforward. Resource objects and relationship links are already read by the adapter class. As a post-processing step, these are mapped to a serialized JSON object used by the type manager. That is basically a step where the transformation from JSON:API to a regular JSON format takes place.

At this stage, we can also attach the associated JSON:API objects as properties of the serialized JSON - for example, $resourceObject and $relationshipLinkObject. This effectively enriches the serialization context with additional data.

These extra properties can be configured via JsonApiResourceOptions, in the same way type and id are configured today. They are exposed as constant keys that a custom serializer can use to access related data. Since the original response is still available at the serializer or factory stage of the type manager, the serializer can rely on constants exported by the library to read the original raw well typed JSON:API data.

From there, you are free to handle metadata in any way you need.

The implementation can be summarized as follows:

1. Define constants similar to jsonApiResourceId.
2. Add them to the resource options so they are configurable, just like type and id.
3. In the adapter methods, pass the associated objects instead of only the data used to create the serialized JSON.
4. Use the resource configuration to write these fields into the serialized JSON object.

(Maybe exposing these options for configuration is not required. Static constants are simpler to implement and can be used to write the data directly. I am not fully sure about that, but simple constants plus direct writes to plain JSON already seem sufficient.)

Finally, consume these fields using the constants or the JSON:API resource configuration to perform your custom serialization logic on your side. I believe that should cover all the cases you mentioned. ;)