Module: object-recipes

In addition to ONE object type names declared in recipes we have one type with the meaning of "everything binary". For example, it is used during Chum synchronization to inform a remote instance about the type behind a hash to select the right method (binary websocket stream transfer) to obtain the file. We define it as a string constant in one place to be sure there is only one such string in the code and only one place to change it.

In addition to ONE object type names declared in recipes we have one type with the meaning of "everything UTF-8 but not a ONE object". For example, it is used during Chum synchronization to inform a remote instance about the type behind a hash to select the right method (utf-8 based websocket stream transfer) to obtain the file. We define it as a string constant in one place to be sure there is only one such string in the code and only one place to change it.

Check if we have a recipe in memory for the given type string. The recipe must have been registered with the instance and loaded into memory, the function does not check for Recipe objects in storage.

Convenience function for the static type checker: Turns a generic "string" into a "OneObjectTypeNames". Check if we have a recipe in memory for the given type string. The recipe must have been registered with the instance and loaded into memory, the function does not check for Recipe objects in storage. If we have the recipe the function returns the string, but now tagged as "OneObjectTypeNames" instead of as generic "string".

Returns the Recipe object describing how a ONE object of the given type looks like.

Example

See addRecipeToRuntime for an example of a definition of a versioned ONE object. Using that example of a Mailbox object the following code

console.log(
    ObjectRecipes.getRecipe('Mailbox')
);

might produce output that looks like this:

{
    $type$: 'Recipe',
    name: 'Mailbox',
    rule: [
        {
           itemprop: 'account',
           isId: true
        },
        {
            itemprop: 'name',
            isId: true
        },
        {
            itemprop: 'uidEmailBlobMap',
            valueType: 'object'
        }
    ]
}

Add a recipe to working memory. The "Recipe" object may or may not exist in storage.

A recipe consists of an array of objects of type RecipeRule for the given type ("name") string. The recipe's rules are checked for the property names and the corresponding types but no further: For example, if you forget "itemprop" (mandatory, a string) in a rule, or if you have the wrong type of item on a rule property an Error is thrown. However, for "type" and a rule's "itemprop" string property we only guard against HTML-breaking "<" and ">" and against whitespace, and we don't check if any other recipes you refer to exist and a wide range of conceivable problems.

A recipe for a ONE object type consists of arrays of objects describing the data properties. Allowed rule properties are explained in RecipeRule:

Example

The following code adds a recipe for a ONE object type "Mailbox":

import * as ObjectRecipes from 'one.core/lib/object-recipes';

if (!ObjectRecipes.hasRecipe('Mailbox')) {
    ObjectRecipes.addRecipeToRuntime({
        $type$: 'Recipe',
        name: 'Mailbox',
        rule: [
            // SHA-256 hash pointing to OneTest$ImapAccount object that mailbox belongs to.
            // Both the account and the name are the ID attributes of this VERSIONED object,
            // meaning any Mailbox object with the same account and name will be a version of
            // the same object, varying only in the data properties not marked as "isID:true".
            { itemprop: 'account', isId: true, referenceToObj: new Set(['Account']) },
            { itemprop: 'name', isId: true },
            // This is an IMAP protocol feature to check if the IMAP-UIDs from last time are
            // still valid. This 32-bit integer can be fully represented by a Javascript number.
            { itemprop: 'uidValidity', valueType: 'number' },
            // A JSON-stringified UID => OneTest$Email-BLOB-hash map
            { itemprop: 'uidEmailBlobMap', valueType: 'object' },
        ]
    });
}

A ONE object created using this recipe would look like this (indentation and newlines added fore readability, not present in the actual microdata):

<div itemscope itemtype="//refin.io/Mailbox">
  <span itemprop="account">8296cf598c1af767b5287....2bd96eae03448da3066aa</span>
  <span itemprop="name">INBOX</span>
  <span itemprop="uidValidity">1455785767</span>
  <span itemprop="uidEmailBlobMap">...[JSON]....</span>
</span>

When then instance is closed is called all runtime recipes need to be removed

Adds the core recipes to the Runtime needed for basic functionality.

Any ONE object with a recipe where there is a property isId: true is a versioned object with an idHash common to all versions, a version map (stored using the idHash) pointing to all versions.

Example

See addRecipeToRuntime for an example of a definition of a versioned ONE object. Using that example of a Mailbox object the following call would return true and the output would be "Mailbox" is a versioned type:

if (ObjectRecipes.isVersionedObjectType('Mailbox')) {
    console.log('"Mailbox" is a versioned type');
}

This function checks the "type" property of the given ONE object against a Set of type names of versioned object types currently registered in the running instance.

A dynamic type check to turn a string into a OneVersionedObjectTypeNames.

Get an array with all types known to the currently running instance. This checks memory, not persistent storage, so only types actually loaded are found. Since all types registered with an instance are automatically loaded this should match the registered types.

RecipeRule objects in Recipes can link to other RecipeRule objects in the same recipe by name. They inherit all properties of the linked rule.

RecipeRule objects in Recipes can link to other RecipeRule objects in the same recipe type by name. They inherit all properties of the linked rule.