The main ZooDb object

import { ZooDb } from '@phfaist/zoodb';
class ZooDb()

The main database class.

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

  • processors — list of DB processor instances to install. Each processor must extend ZooDbProcessorBase(). See Database processors.

  • schema_validator — An object with a validate(object, schema) method (e.g. a Validator instance from the jsonschema npm package). When a validator is provided, every object added to the database is validated against its schema. Omitting this option (or passing null/undefined) throws an error at construction time. Pass false to explicitly disable validation without triggering this error; this is appropriate when YamlDbDataLoader() is used, since that loader already validates objects as it loads them.

  • normalize_id_for_uniqueness_check — A function (id: string) => string used to normalise object IDs before comparing them for uniqueness. Defaults to (x) => x.toLowerCase().

  • silent — If set to true, schema validation failures are not printed to the console (the error is still thrown). Defaults to false.

ZooDb.object_types

A list of object types that are stored in this database (read-only property).

ZooDb.objects

Read-only properties to access the dictionary of objects. Access objects as stored_object = zoodb.objects[object_type][object_id].

ZooDb.schemas

Read-only properties to access the dictionary of schemas.

ZooDb.data_dump(options)

Produce a serializable data dump of the contents of the database.

Warning

Depending on the options provided and any installed database processors, this method may return references to the raw objects stored inside the database. For example, when flm_fragments_keep_instances is used with ZooFLMProcessor(), the returned objects contain live FLMFragment instances from the database. Any mutations will affect the original database content.

Options accepted in the options argument:

  • use_raw_db_data — when true, return the raw (pre-processor) data and skip all processor process_data_dump() calls. Defaults to false.

  • skip_db_processors — when true, skip calling each installed processor’s process_data_dump() method but still return the live processed object data (not the raw data). Defaults to false.

  • remove_zoodb_id — when true, delete the id field from every object’s _zoodb metadata property in the returned dump. Defaults to false.

  • remove_zoodb_info — when true, delete the entire _zoodb metadata property from every returned object. Defaults to false.

Additional options recognised by individual database processors (e.g. flm_fragments_to_flm_text, relations_keep_object_property_pointers, etc.) may be passed here and are forwarded to each processor’s process_data_dump() method.

Arguments:

  • options (Object) – Dump options, see above.

Returns:

Object – An object { db: { objects, schemas }, … } suitable for serialisation.

ZooDb.install_zoo_loader_handler(zoo_loader_handler)

Install a zoo loader handler.

The loader handler’s task is to invoke a dbdataloader (e.g. YamlDbDataLoader()) to obtain the database data from some source (e.g. YAML files) and then to properly initialize and validate the zoo with that data.

The zoo_loader_handler is pretty much expected to be a ZooDbDataLoaderHandler() instance. If you specify null here, any existing loader handler will be removed.

The reason for splitting off the logic of the loader handler is to avoid bloating the ZooDb class definition, especially in case a user would like to create a barebones ZooDb, e.g. with hard-coded JSON data, without reloading features, in which case neither a loader nor a loader handler is necessary.

ZooDb.load(options)

Load or reload the zoo, using the loader handler that was installed via install_zoo_loader_handler().

The options parameter is forwarded to the loader handler’s load() method. The default ZooDbDataLoaderHandler() does not use it, but a custom loader handler subclass may define its own options.

ZooDb.load_data(db)

Initialize the database processors and then directly load objects whose data is given in the argument dictionary db. We ensure that the objects are copies of the provided data, by serializing them & deserializing them again from JSON.

Note that this method is meant to load raw data that needs to be processed. You are not likely to be able to load data dumped using data_dump(), unless you dumped that data by using raw data dump options and skipping the db processors’ fiddling. See data_dump() for details.

Arguments:

  • db (Object) – an object with keys ‘schemas’ and ‘objects’.

ZooDb.load_schemas(options)

Load schema definitions into the database. The provided schemas are deep-cloned before being stored.

Normally you do not call this method directly — it is invoked automatically by load_data() when the data includes a schemas property.

Arguments:

  • options (Object)

  • options.schemas (Object) – An object mapping each schema name (which doubles as the object type name) to its JSON Schema object.

ZooDb.schema(object_type)

Get the schema associated with a given object_type. Returns the schema object.

ZooDb.update_objects(db_objects)

Update a subset of objects in the database, running the processor pipeline’s update hooks (prepare_zoo_update_objects() and process_zoo_update_objects()).

This method is called by ZooDbDataLoaderHandler() during a reload operation. You can also call it directly to inject updated raw object data without triggering a full re-load.

Arguments:

  • db_objects (Object) – An object of the form { object_type: { object_id: object, ... }, ... } containing only the objects that should be updated. Each object must already carry a _zoodb metadata field (as set by YamlDbDataLoader()).

ZooDb.validate()

Can be overridden to proceed to validation of the zoo. E.g., you can enforce any constraints, sanity checks, etc.

The base class applies checks that all IDs are unique modulo the normalizer set as constructor argument.

(Schema validation doesn’t happen here, it happens instead directly when loading the data in load_data() because the check can be performed earlier. The ID uniqueness check happens here because it must act globally on the database.)