Improvement: change structure of domain data

[Plazide]

To make the interaction with domain data more intuitive, I would like to change it to something that is more similar to FaunaDB documents.

The current structure

The current way to write domain data looks like the following:

import { DataResource } from "fauna-gql-upload";

const initialUser: DataResource = {
  collection: "User",
  index: "user-by-email",
  key: "email",
  data: [
    { name: "Admin", email: "[email protected]" },
    { name: "Editor", email: "[email protected]", ref: q.Ref(q.Collection("User"), "00000000000000") }
  ],
  credentials: [
    {
      key: "[email protected]",
      password: "SuperStrongPassword"
    }
  ]
}

export default initialUser;

Where each item in the data array is a separate document in the User collection, as specified by the collection property. Each document is identified by the property name specified in the key property. The value of the key property must correspond to the term used in the index specified by the index property. This index needs to be created by the consumer of the package, which might not be entirely clear.

You can also specify a ref property on each of the document items to give them specific ref values. When doing this, you need to specify the collection which they belong to, and this collection could be completely different from the one specified in the collection property.

To add credentials to data, you need to create a separate credentials property and link each credential to the related document using the key property. This

As you might understand, this can be quite confusing and unintuitive.

My proposed structure

I propose this new structure to better conform with how a document looks in FaunaDB and to make handling of domain data less straining on the package consumer:

{
  name: "Users",
  collection: q.Collection("User"),
  data: [
    { name: "Admin", email: "[email protected]" },
    {
      ref: q.Ref(q.Collection("User"), "00000000000000"),
      credentials: { password: "SuperStrongPassword" },
      data: {
        name: "Editor", email: "[email protected]"
      },
    }
  ]
}

Here, we specify a name for the subset of data that this resource controls. This name will be used to automatically create an index together with the collection property. Each document will be assigned a fgu_id field upon upload. This field will be used in the index to identify each document, thus transferring this responsibility from the consumer to the package.

The fgu_id field could be based on the index of the document in the data array. There is at least one potential issue with this approach, though. If an item is removed from the array or an item is moved to another position in the array, all the items will keep their refs but will contain data that belongs to another document.

Another approach would be to require the user to specify the fgu_id field manually. Ideally, we would like to avoid this approach to let the developer focus on the actual data rather than how it is handled by the package.

It is also possible that we might need to have a field similar to the existing key field.

The actual data can be written in two ways. The first is similar to the previous way of writing data and will most likely be the most common way. The second is a more advanced use case where you are able to specify the ref, ts, and credentials of the document while still matching the structure of a FaunaDB document.

Open to suggestions

If you have suggestions or other solutions to the problems above, please leave a comment below.