Database relations

import { RelationsPopulator } from '@phfaist/zoodb/dbprocessor/relations';

Relation specification objects are usually attached to an object schema and specify information about a relationship about that object to another object. Relation specification objects may have the following fields:

  • object_field: the fully qualified field name where this relation is specified. For instance, a person object might contain a field relations.parents listing relationships to other parent person objects. In this case, set object_field: ‘relations.parents’.

  • to_object_type: the type of the target object which is being referenced. For instance, a person object might contain relationships to other parent person objects; in this case, set to_object_type: ‘person’.

  • allow_null: a boolean value specifying whether or not the field value can be null. The value might signify that there exists no target object that fulfills this relationship. By default, allow_null is false.

  • relation_primary_key_field: the name of the field within each relation object that holds the ID (primary key) of the target object. For example, if each element of the relations.parents array has a person_id field, set relation_primary_key_field: ‘person_id’. The special value true means the relation object is itself the target ID (a shorthand form where no wrapper object is used).

  • relation_add_object_field: if set, the resolved target object will be stored back into the relation object under this field name. For example, setting relation_add_object_field: ‘person’ causes the full person object to be inserted as relation_object.person. This field is computed automatically; mark it as _auto_populated: true in the schema.

  • backreference: if set, a back-reference entry is added to the target object for each forward relation. The value is an object with:

    • field: (required) the field on the target object type that will receive the list of back-reference entries. Mark this field as _auto_populated: true in the target object’s schema.

    • relation_primary_key_field: the field name used inside each back-reference entry to store the referring object’s ID. Defaults to <source_object_type>_id.

    • relation_object_field: the field name used inside each back-reference entry to store the actual referring object. Defaults to <source_object_type>.

class ZooRelation(options)

An instance of a relation in the database.

The constructor accepts a single destructured options object with the following properties:

Arguments:

  • options (Object)

  • options.object_type (string) – The type of the object from which the relation originates.

  • options.relation_spec (Object) – The relation specification object containing information about how this relation works (target object type, primary key field, backreferences, etc.). This is one of the items from the _zoo_relations array in the object schema (see Object schemas).

  • options.zoodb (ZooDb) – The ZooDb instance used to look up referenced objects.

ZooRelation.ZooRelation
ZooRelation.get_computed_fields()

Return information about which fields of which object will be set as a consequence of processing this relation object.

Return a dictionary where keys are object types, and values are a dictionary { fieldname, msg, }, where fieldname is the name of a field of that object type that will be set automatically by this relation instance and msg is an error message that you can display if the user accidentally set that field instead of letting it be set automatically.

ZooRelation.get_object_relation_objects(obj)

Return all relation-data objects for obj that are relevant to this relation. For a single-valued field this returns a one-element array (or an empty array if allow_null is true and the field is absent). For an array-typed field it returns all array elements.

Arguments:

  • obj (Object) – A database object instance whose field described by this.object_field will be read.

Throws:

Error – If the field is absent and allow_null is false.

Returns:

Array –

ZooRelation.process_object_relation(obj, options)

Process this relation for all relation-data objects of obj. Resolves target object references, populates the relation_add_object_field property if configured, and adds back-references to the target object if backreference is configured in the relation spec.

Arguments:

  • obj (Object) – A database object of type this.object_type.

  • options (Object) – Must include process_object_types (array of object types being processed), used to guard back-reference writes.

Throws:

Error – If a referenced object ID does not exist in the database.

class RelationsPopulator()

A database processor that turns relevant object fields into references to other objects, and possibly adds back-references, according to relations specified in the object type’s schema.

RelationsPopulator.RelationsPopulator
RelationsPopulator.check_all_clean_fields(options)

Iterate over all auto-populated relation fields in the database and invoke action for each field whose value is set. When action is omitted, the default action throws an error, which is used during initialize_zoo() to detect objects that manually set auto-populated fields. Pass a custom action to implement a different behaviour (e.g. deletion, as done by clear_all_relation_fields()).

Arguments:

  • options (Object)

  • options.action (function) – Called as action({ object_type, object, computed_relation_fieldinfo, fieldnameidx, value }). Defaults to throwing an error on the first non-empty auto-populated field.

  • options.dbobjects (Object) – Object dictionary to inspect; defaults to this.zoodb.objects.

RelationsPopulator.clear_all_relation_fields(options)

Delete every auto-populated relation field (object pointers and back-reference lists) from all objects in the database, leaving only the original source data. Called before process_zoo() rebuilds relations from scratch, and also before a data dump to avoid serialising circular references.

Arguments:

  • options (Object)

  • options.dbobjects (Object) – Alternative object dictionary to clear; defaults to this.zoodb.objects.