Auxiliary Data

Auxiliary data refers to data that is not considered part of the primary data of a collection. For example, it can represent data that is used in form calculations and workflow. Auxiliary data is transient and ephemeral and is not stored in the database.

Server Auxiliary Data

Auxiliary data can be specified in the main collection definition by specifying aux: true on collection or field definitions. For example, the following defines an auxiliary collection:

new Tyr.Collection({
  ...,
  aux: true,
  fields: {
    ...,
    someFieldOnATransientCollection: { is: 'string' },
    ...
  },
  ...,
});

while the following defines an auxiliary field on a non-auxiliary collection:

new Tyr.Collection({
  ...,
  fields: {
    ...,
    someTransientField: { is: 'string', aux: true },
    ...
  },
  ...,
});

Note that aux: true implies db: false but aux: false does not necessarily imply db: true -- computed fields are by default not stored in the database but are also not by default auxiliary.

Client Auxiliary Data

Auxiliary data specified on the server will be automatically available on the client as well (assuming client: false is not set).

Often though, it is useful to just define auxiliary data on the client to drive ephemeral UI elements and Tyranid and Tyreant provide a number of ways to do that.

Auxiliary Collections

You can define an entire auxiliary collection using Tyr.aux(), for example:

const myCollection = Tyr.aux({
  name: 'myFormData',
  fields: {
    re: { is: 'regexp', label: 'Regular Expression' },
    testRe: { is: 'string', label: 'Test regular expression' }
  }
});

It is not necessary to come up with a collection ID when defining a collection on the client (though you can, if you need to) -- Tyranid will automatically generate one. Automatically generated collection IDs start with a tilde (~).

Singleton Auxiliary Collections

Tyranid also supports singleton auxiliary collections. These are collections which only have a single, shared copy of data that can be useful for storing session data like application settings and other types of data that is "global" in the context of the client.

const myCollection = Tyr.aux({
  name: 'session',
  singleton: true,
  fields: {
    darkMode: { is: 'boolean', label: 'Enable Dark Mode?' },
    ...
  }
});

Singleton collections support a special path syntax to access them -- collection name:path name. For example:

<TyrForm>
  <TyrString path="session:darkMode" />
</TyrForm>

Auxiliary Fields

Auxiliary fields can be added to an existing collection on the client using collection.aux().

Work.aux({
  myStringOnWork: { is: 'string' }
});

Auxiliary fields can also be defined on tyreant components directly without needing a separate call:

<TyrForm
   aux={{
     myFormField: { is: 'string' }
   }}
>
  <TyrField path="myFormField" ... />
</TyrForm>

Further, you can define them on the fly on actual field controls. The following is the same as the previous:

<TyrForm>
  <TyrString aux="myFormField" ... />
</TyrForm>

In this case it infers the type of myFormField to be a string since it is being defined by a TyrString control.

If you try to add auxiliary fields on a Tyreant component and there is no local document/collection in the local context, Tyreant will automatically define a custom auxiliary collection and add the fields to that so that it will still work as expected in this case.

Overview