Source: recipes.ts

  1. /**
  2.  * @author Michael Hasenstein <hasenstein@yahoo.com>
  3.  * @copyright REFINIO GmbH 2018
  4.  * @license CC-BY-NC-SA-2.5; portions MIT License
  5.  * @version 0.0.1
  6.  */
  8. /**
  9.  * This module defines the core ONE object types. It has the type definitions as well as the
  10.  * recipes.
  11.  *
  12.  * **The module deliberately does not import any other module.** This ensures that there are no
  13.  * cyclic imports (type imports don't count, they don't exist at runtime).
  14.  * @module
  15.  */
  17. /**
  18.  * A meta-type defined in `one.core/[src|lib]/@OneObjectInterfaces.d.ts` in module namespace
  19.  * `"@OneObjectInterfaces"` that can be extended through TypeScript's
  20.  * {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html|*declaration merging*} feature to include ONE object definitions defined through recipes of the application.
  21.  *
  22.  * In order to add your own project's unversioned ONE object types create similar .d.ts
  23.  * file, declare a module namespace `@OneObjectInterfaces` and export an interface declaration for
  24.  * `OneUnversionedObjectInterfaces` just as in the one.core file. If you tell `tsc`
  25.  * (TypeScript server) via your `tsconfig.json` to include both one.core's and your own
  26.  * definition files it will merge the declarations into one.
  27.  *
  28.  * To extend this structure have a look at file `one.core/@OneObjectInterfaces.d.ts` and do what
  29.  * was one there to add ONE object types defined for the one.core tests for your own application
  30.  * types.
  31.  *
  32.  * This interface contains the names (as keys) and TypeScript interface types (as values) of
  33.  * all unversioned objects.
  34.  *
  35.  * **Important:** The string keys for each entry must be exactly the ONE object type name as
  36.  * used in the "`name`" property of the recipe for that type.
  37.  * @global
  38.  * @typedef {object} OneUnversionedObjectInterfaces
  39.  * @property {ONE-object-interface-type} type-name - Use the same string literal as used for
  40.  * the "type" property in your ONE object(s) as key and the TypeScript interface definition
  41.  * name as the value
  42.  */
  43. declare module '@OneObjectInterfaces' {
  44.     export interface OneUnversionedObjectInterfaces extends OneCrdtMetaObjectInterfaces {
  45.         Keys: Keys;
  46.     }
  47. }
  49. /**
  50.  * ONE microdata object properties can store one of these types:
  51.  *
  52.  * - NumberValue
  53.  * - BooleanValue
  54.  * - StringifiableValue
  55.  * - ReferenceToObjValue
  56.  * - ReferenceToIdValue
  57.  * - ReferenceToClobValue
  58.  * - ReferenceToBlobValue
  59.  * - MapValue
  60.  * - BagValue
  61.  * - ArrayValue
  62.  * - SetValue
  63.  * - ObjectValue;
  64.  *
  65.  * Conversion from and to the types is performed upon writing and reading ONE microdata objects:
  66.  *
  67.  * When reading microdata and creating a Javascript object representation of the ONE object
  68.  * the strings will be converted to these types if the respective rule for the item has type
  69.  * information. By default, everything remains a string.
  70.  *
  71.  * @global
  72.  * @typedef {(
  73.  *   StringValue | IntegerValue | NumberValue | BooleanValue | StringifiableValue |
  74.  *   ReferenceToObjValue | ReferenceToIdValue | ReferenceToClobValue | ReferenceToBlobValue |
  75.  *   MapValue | BagValue | ArrayValue | SetValue | ObjectValue
  76.  * )} ValueType
  77.  */
  78. export type ValueType =
  79.     | StringValue
  80.     | IntegerValue
  81.     | NumberValue
  82.     | BooleanValue
  83.     | StringifiableValue
  84.     | ReferenceToObjValue
  85.     | ReferenceToIdValue
  86.     | ReferenceToClobValue
  87.     | ReferenceToBlobValue
  88.     | MapValue
  89.     | BagValue
  90.     | ArrayValue
  91.     | SetValue
  92.     | ObjectValue;
  94. /**
  95.  * This object is part of {@link ValueType} and describes the value-type of a String.
  96.  * @global
  97.  * @typedef {object} StringValue
  98.  * @property {'string'} type
  99.  * @property {RegExp} [regexp]
  100.  */
  101. export interface StringValue {
  102.     type: 'string';
  103.     regexp?: RegExp;
  104. }
  106. /**
  107.  * This object is part of {@link ValueType} and describes the value-type of an Integer.
  108.  * @global
  109.  * @typedef {object} IntegerValue
  110.  * @property {'integer'} type
  111.  * @property {number} [max]
  112.  * @property {number} [min]
  113.  */
  114. export interface IntegerValue {
  115.     type: 'integer';
  116.     max?: number;
  117.     min?: number;
  118. }
  120. /**
  121.  * This object is part of {@link ValueType} and describes the value-type of a Number.
  122.  * @global
  123.  * @typedef {object} NumberValue
  124.  * @property {'number'} type
  125.  * @property {number} [max]
  126.  * @property {number} [min]
  127.  */
  128. export interface NumberValue {
  129.     type: 'number';
  130.     max?: number;
  131.     min?: number;
  132. }
  134. /**
  135.  * This object is part of {@link ValueType} and describes the value-type of a Boolean.
  136.  * @global
  137.  * @typedef {object} BooleanValue
  138.  * @property {'boolean'} type
  139.  */
  140. export interface BooleanValue {
  141.     type: 'boolean';
  142. }
  144. /**
  145.  * This object is part of {@link ValueType} and describes the value-type of a {@link SHA256Hash} of
  146.  * an object.
  147.  * @global
  148.  * @typedef {object} ReferenceToObjValue
  149.  * @property {'referenceToObj'} type
  150.  * @property {Set<OneObjectTypeNames | '*'>} allowedTypes - Includes another recipe as a
  151.  * sub-item. Create microdata span tag for complex data with attributes `itemscope` and
  152.  * `itemtype="//refin.io/{THIS TYPE}"`. The actual values are placed in inner span tags
  153.  * with an itemprop attributeSHA256IdHash. This is a list of acceptable types to include. The
  154.  * itemprop` either is a hash link, or in imploded microdata those objects themselves are
  155.  * included. If the list includes the type string '*' the meaning is "any type".
  156.  */
  157. export interface ReferenceToObjValue {
  158.     type: 'referenceToObj';
  159.     allowedTypes: Set<OneObjectTypeNames | '*'>;
  160. }
  162. /**
  163.  * This object is part of {@link ValueType} and describes the value-type of a {@link
  164.  * SHA256IdHash} of an object.
  165.  * @global
  166.  * @typedef {object} ReferenceToIdValue
  167.  * @property {'referenceToId'} type
  168.  * @property {Set<OneVersionedObjectTypeNames | '*'>} allowedTypes - Same as `referenceToObj`
  169.  * but the hash link points to an ID hash.
  170.  */
  171. export interface ReferenceToIdValue {
  172.     type: 'referenceToId';
  173.     allowedTypes: Set<OneVersionedObjectTypeNames | '*'>;
  174. }
  176. /**
  177.  * This object is part of {@link ValueType} and describes the value-type of a {@link SHA256Hash} of
  178.  * a {@link CLOB}.
  179.  * @global
  180.  * @typedef {object} ReferenceToClobValue
  181.  * @property {'referenceToClob'} type - Same as `referenceToObj` but the hash link points to a
  182.  * CLOB (UTF-8) hash. It also is just a boolean value.
  183.  */
  184. export interface ReferenceToClobValue {
  185.     type: 'referenceToClob';
  186. }
  188. /**
  189.  * This object is part of {@link ValueType} and describes the value-type of a {@link SHA256Hash} of
  190.  * a {@link BLOB}.
  191.  * @global
  192.  * @typedef {object} ReferenceToBlobValue
  193.  * @property {'referenceToBlob'} type - Same as `referenceToObj` but the hash link points to a
  194.  * BLOB hash. It also is just a boolean value.
  195.  */
  196. export interface ReferenceToBlobValue {
  197.     type: 'referenceToBlob';
  198. }
  200. /**
  201.  * This object is part of {@link ValueType} and describes the value-type of a Map Object.
  202.  * @global
  203.  * @typedef {object} MapValue
  204.  * @property {'map'} type
  205.  * @property {PrimitiveValueTypes|ReferenceValueTypes} key
  206.  * @property {ValueType} value
  207.  */
  208. export interface MapValue {
  209.     type: 'map';
  210.     key: PrimitiveValueTypes | ReferenceValueTypes;
  211.     value: ValueType;
  212. }
  214. /**
  215.  * This object is part of {@link ValueType} and describes the value-type of a Bag Object.
  216.  * A "bag" is a data-structure that implements a multiset, which is a set
  217.  * that allows multiple (duplicates). In the microdata the sequence of items is ordered by ONE.
  218.  * @global
  219.  * @typedef {object} BagValue
  220.  * @property {'bag'} type
  221.  * @property {ValueType} item
  222.  */
  223. export interface BagValue {
  224.     type: 'bag';
  225.     item: ValueType;
  226. }
  228. /**
  229.  * This object is part of {@link ValueType} and describes the value-type of an Array Object.
  230.  * @global
  231.  * @typedef {object} ArrayValue
  232.  * @property {'array'} type
  233.  * @property {ValueType} item
  234.  */
  235. export interface ArrayValue {
  236.     type: 'array';
  237.     item: ValueType;
  238. }
  240. /**
  241.  * This object is part of {@link ValueType} and describes the value-type of a Set Object.
  242.  * @global
  243.  * @typedef {object} SetValue
  244.  * @property {'set'} type
  245.  * @property {ValueType} item
  246.  */
  247. export interface SetValue {
  248.     type: 'set';
  249.     item: ValueType;
  250. }
  252. /**
  253.  * This object is part of {@link ValueType} and describes the value-type of an ONE Object.
  254.  * @global
  255.  * @typedef {object} ObjectValue
  256.  * @property {'object'} type
  257.  * @property {RecipeRule[]} rules
  258.  */
  259. export interface ObjectValue {
  260.     type: 'object';
  261.     rules: RecipeRule[];
  262. }
  264. /**
  265.  * @global
  266.  * @typedef {object} StringifiableValue
  267.  * @property {'stringifiable'} type
  268.  */
  269. export interface StringifiableValue {
  270.     type: 'stringifiable';
  271. }
  273. /**
  274.  * @global
  275.  * @typedef {(
  276.  *   StringValue | IntegerValue | NumberValue | BooleanValue | StringifiableValue
  277.  * )} PrimitiveValueTypes
  278.  */
  279. export type PrimitiveValueTypes =
  280.     | StringValue
  281.     | IntegerValue
  282.     | NumberValue
  283.     | BooleanValue
  284.     | StringifiableValue;
  286. /**
  287.  * @global
  288.  * @typedef {(
  289.  *   ReferenceToObjValue | ReferenceToIdValue | ReferenceToClobValue | ReferenceToBlobValue
  290.  * )} PrimitiveValueTypes
  291.  */
  292. export type ReferenceValueTypes =
  293.     | ReferenceToObjValue
  294.     | ReferenceToIdValue
  295.     | ReferenceToClobValue
  296.     | ReferenceToBlobValue;
  298. /**
  299.  * A meta-type defined in `one.core/@OneObjectInterfaces.d.ts` in module namespace
  300.  * `"@OneObjectInterfaces"` that can be extended through TypeScript's
  301.  * {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html|*declaration merging*} feature to include ONE object definitions defined through recipes of the application.
  302.  *
  303.  * In order to add your own project's ID ONE object types create similar .d.ts file,
  304.  * declare a module namespace `@OneObjectInterfaces` and export an interface declaration for
  305.  * `OneIdObjectInterfaces` just as in the one.core file. If you tell `tsc` (TypeScript
  306.  * server) via your `tsconfig.json` to include both one.core's and your own definition files
  307.  * it will merge the declarations into one.
  308.  *
  309.  * This interface contains the names (as keys) and TypeScript interface types (as values) of
  310.  * all ID objects. Unless you need to refer to the ID object types by name it probably is
  311.  * best to use TypeScript's built-in `Pick<T, K>` helper to pick the ID object properties
  312.  * from the full versioned object types. Usually only the latter will have named interfaces.
  313.  * If necessary, in .ts code files you can always refer to ID object interfaces using
  314.  * `OneIdObjectInterfaces[TypeId]`, where `TypeId` is the appropriate string key. For key
  315.  * names one.core follows the rule to take the name of the versioned object type and append, for
  316.  * example, 'Id'.
  317.  *
  318.  * **Note** that ID object interfaces are special and must be used explicitly, they are not
  319.  * part in any of the unions or merged definitions of ONE object types.
  320.  * Except for in rare places ID object types are not to be permitted even when the
  321.  * respective versioned object types are, because the ID object types may miss properties
  322.  * that are not ID properties but still non-optional. ID objects are only used to calculate
  323.  * ID hashes and never written, nor should they be used for processing.
  324.  *
  325.  * That is why the name (key) you choose for the ID object type may be arbitrary, it is not
  326.  * used as type name. Only the values are used, i.e. the ID object declarations.
  327.  *
  328.  * This key/value interface still is necessary, the declarations cannot just be written
  329.  * directly to `OneIdObjectTypes`: Declaration merging of ID object types declared for the
  330.  * application requires this key/value structure.
  331.  * @global
  332.  * @typedef {object} OneIdObjectInterfaces
  333.  * @property {ONE-object-interface-type} type-name - Use the same string literal as used for
  334.  * the "$type$" property in your ONE object(s) as key and the TypeScript interface definition
  335.  * name as the value
  336.  */
  337. declare module '@OneObjectInterfaces' {
  338.     // eslint-disable-next-line no-undef -- OneCrdtIdObjectInterfaces *is* defined
  339.     export interface OneIdObjectInterfaces extends OneCrdtIdObjectInterfaces {
  340.         Access: Pick<Access, '$type$' | 'object'>;
  341.         Chum: Pick<Chum, '$type$' | 'name' | 'instance' | 'person'>;
  342.         Group: Pick<Group, '$type$' | 'name'>;
  343.         IdAccess: Pick<IdAccess, '$type$' | 'id'>;
  344.         Instance: Pick<Instance, '$type$' | 'name' | 'owner'>;
  345.         Module: Pick<Module, '$type$' | 'name'>;
  346.         Person: PersonId;
  347.         Recipe: Pick<Recipe, '$type$' | 'name'>;
  348.         MetaObjectList: Pick<MetaObjectList, 'object' | '$type$'>;
  349.     }
  350. }
  352. /**
  353.  * A meta-type defined in `one.core/@OneObjectInterfaces.d.ts` in module namespace
  354.  * `"@OneObjectInterfaces"` that can be extended through TypeScript's
  355.  * {@link https://www.typescriptlang.org/docs/handbook/declaration-merging.html|*declaration merging*} feature to include ONE object definitions defined through recipes of the application.
  356.  *
  357.  * In order to add your own project's versioned ONE object types create similar .d.ts
  358.  * file, declare a module namespace `@OneObjectInterfaces` and export an interface declaration for
  359.  * `OneVersionedObjectInterfaces` just as in the one.core file. If you tell `tsc`
  360.  * (TypeScript server) via your `tsconfig.json` to include both one.core's and your own
  361.  * definition files it will merge the declarations into one.
  362.  *
  363.  * This interface contains the names (as keys) and TypeScript interface types (as values) of
  364.  * all versioned objects.
  365.  *
  366.  * **Important:** The string keys for each entry must be exactly the ONE object type name as
  367.  * used in the "`name`" property of the recipe for that type.
  368.  * @global
  369.  * @typedef {object} OneVersionedObjectInterfaces
  370.  * @property {ONE-object-interface-type} type-name - Use the same string literal as used for
  371.  * the "$type$" property in your ONE object(s) as key and the TypeScript interface definition
  372.  * name as the value
  373.  */
  374. declare module '@OneObjectInterfaces' {
  375.     export interface OneVersionedObjectInterfaces extends OneCrdtObjectInterfaces {
  376.         Access: Access;
  377.         Chum: Chum;
  378.         Group: Group;
  379.         IdAccess: IdAccess;
  380.         Instance: Instance;
  381.         Module: Module;
  382.         Person: Person;
  383.         Recipe: Recipe;
  384.         MetaObjectList: MetaObjectList;
  385.     }
  386. }
  388. /**
  389.  * Defined in one.core's `@OneObjectInterfaces.d.ts` file, this is the result of merging the
  390.  * declarations of {@link OneUnversionedObjectInterfaces}, {@link OneVersionedObjectInterfaces}.
  391.  *
  392.  * This is a key/value map object where the keys are *all* valid ONE object type names, and the
  393.  * values are the interface type (i.e. ONE object) definitions.
  394.  *
  395.  * ID object interface definitions are not included in this map because except for in rare
  396.  * places ID object types are not to be permitted even when the respective versioned object
  397.  * types are, because the ID object types may miss properties that are not ID properties but
  398.  * still non-optional. ID objects are only used to calculate ID hashes and never written,
  399.  * nor should they be used for processing.
  400.  * @global
  401.  * @typedef {object} OneObjectInterfaces
  402.  */
  403. export type OneObjectInterfaces = OneUnversionedObjectInterfaces & OneVersionedObjectInterfaces;
  405. /**
  406.  * This union is obtained by extracting all keys from {@link OneUnversionedObjectInterfaces}.
  407.  * @global
  408.  * @typedef {"Keys" | AllYourUnversionedTypeNames} OneUnversionedObjectTypeNames
  409.  */
  410. export type OneUnversionedObjectTypeNames = keyof OneUnversionedObjectInterfaces;
  412. /**
  413.  * This union is obtained by extracting all values from {@link OneUnversionedObjectInterfaces}.
  414.  * @global
  415.  * @typedef {Keys | AllYourUnversionedTypes} OneUnversionedObjectTypes
  416.  */
  417. export type OneUnversionedObjectTypes =
  418.     OneUnversionedObjectInterfaces[keyof OneUnversionedObjectInterfaces];
  420. /**
  421.  * This union is obtained by extracting all keys from {@link OneVersionedObjectInterfaces}.
  422.  * @global
  423.  * @typedef {
  424.  *     "Access" | "Chum" | "Group" | "Instance" | "Module" | "Person" | "Recipe" |
  425.  *     AllYourVersionedTypeNames
  426.  * } OneVersionedObjectTypeNames
  427.  */
  428. export type OneVersionedObjectTypeNames = keyof OneVersionedObjectInterfaces;
  430. /**
  431.  * This union is obtained by extracting all values from {@link OneVersionedObjectInterfaces}.
  432.  * @global
  433.  * @typedef {
  434.  *     Access | Chum | Group | IdAccess | Instance | Module | Person | Recipe |
  435.  *     AllYourVersionedTypes
  436.  * } OneVersionedObjectTypes
  437.  */
  438. export type OneVersionedObjectTypes =
  439.     OneVersionedObjectInterfaces[keyof OneVersionedObjectInterfaces];
  441. /**
  442.  * This union is obtained by extracting all values from {@link OneIdObjectInterfaces}.
  443.  * @global
  444.  * @typedef {
  445.  *   AccessId | ChumId | GroupId | InstanceId | ModuleId | PersonId | RecipeId |
  446.  *   AllYourIdObjectTypes
  447.  * } OneIdObjectTypes
  448.  */
  449. export type OneIdObjectTypes = OneIdObjectInterfaces[keyof OneIdObjectInterfaces];
  451. /**
  452.  * The union of all "`name`" property values of all {@link Recipe}s used by one.core and the
  453.  * application. The type is created as union of {@link OneUnversionedObjectTypeNames} and
  454.  * {@link OneVersionedObjectTypeNames}.
  455.  * @global
  456.  * @typedef {OneUnversionedObjectTypeNames|OneVersionedObjectTypeNames} OneObjectTypeNames
  457.  */
  458. export type OneObjectTypeNames = OneUnversionedObjectTypeNames | OneVersionedObjectTypeNames;
  460. /**
  461.  * The union of all interfaces of ONE object types used by one.core and the application. The
  462.  * type is created as union of {@link OneUnversionedObjectTypes} and
  463.  * {@link OneVersionedObjectTypes}.
  464.  * @global
  465.  * @typedef {OneUnversionedObjectTypes | OneVersionedObjectTypes} OneObjectTypes
  466.  */
  467. export type OneObjectTypes = OneUnversionedObjectTypes | OneVersionedObjectTypes;
  469. /**
  470.  * The ID object of a Person with only "email" as the sole ID property of {@link Person}
  471.  * objects.
  472.  * @typedef {object} PersonId
  473.  * @property {'Person'} $type$
  474.  * @property {string} email
  475.  */
  476. export type PersonId = Pick<Person, '$type$' | 'email'>;
  478. /**
  479.  * This is a *virtual type* representing BLOB files. It is used as a generic parameter type
  480.  * for {@link SHA256Hash} and {@link SHA256IdHash}.
  481.  * @global
  482.  * @typedef {object} BLOB
  483.  */
  484. export interface BLOB {
  485.     _: 'BLOB';
  486. }
  488. /**
  489.  * This is a *virtual type* representing CLOB (UTF-8 text) files. It is used as a generic
  490.  * parameter type for {@link SHA256Hash} and {@link SHA256IdHash}.
  491.  * @global
  492.  * @typedef {object} CLOB
  493.  */
  494. export interface CLOB {
  495.     _: 'CLOB';
  496. }
  498. /**
  499.  * The union of all "`name`" property values of all {@link Recipe}s used by one.core and the
  500.  * application plus 'BLOB' for binary objects and 'CLOB' for UTF-8 objects.
  501.  * @global
  502.  * @typedef {OneObjectTypeNames|BLOB|CLOB} HashTypes
  503.  */
  504. export type HashTypes = OneObjectTypes | BLOB | CLOB;
  506. /**
  507.  * There are two Access objects that are identical in structure and purpose except for in name:
  508.  * 'Access' points to immutable graphs.
  509.  *
  510.  * ### Example
  511.  *
  512.  * Javascript representation:
  513.  *
  514.  * ```javascript
  515.  * const obj = {
  516.  *     $type$: 'Access',
  517.  *     object: hash,
  518.  *     person: [personIdHash]
  519.  * };
  520.  * ```
  521.  *
  522.  * HTML microdata representation:
  523.  *
  524.  * ```html
  525.  * <div itemscope itemtype="//refin.io/Access">
  526.  *   <a itemprop="object" href="${hash}">${hash}</a>
  527.  *   <a itemprop="person" href="${personIdHash}">${personIdHash}</a>
  528.  * </span>
  529.  * ```
  530.  * @global
  531.  * @typedef {object} Access
  532.  * @property {'Access'} type Fixed string 'Access'
  533.  * @property {SHA256Hash} object A versioned or unversioned object link to a concrete
  534.  * versioned or unversioned object that the access rights are being set for.
  535.  * @property {SHA256IdHash[]} [person] An array of ID references to Person objects.
  536.  * @property {SHA256IdHash[]} [group] An array of ID references to Group objects. *Only
  537.  * the latest version* of a group is granted access!
  538.  */
  539. export interface Access {
  540.     $type$: 'Access';
  541.     object: SHA256Hash;
  542.     person: Array<SHA256IdHash<Person>>;
  543.     group: Array<SHA256IdHash<Group>>;
  544. }
  546. /**
  547.  * Same as {@link Access|Access object} but instead of a reference to a concrete object it
  548.  * has a reference to an ID object of a versioned object and grants access to all current *and
  549.  * future* versions of the object.
  550.  * @global
  551.  * @typedef {object} IdAccess
  552.  * @property {'IdAccess'} $type$ Fixed string 'IdAccess' (which is mutable, since the ID
  553.  * reference also points to any future versions of the object) depending on if the directed
  554.  * graph of ONE objects it points to an ID object.
  555.  * @property {SHA256IdHash} id A reference to all versions of an ID object that the access
  556.  * rights are being set for.
  557.  * @property {SHA256IdHash[]} [person] An array of ID references to Person objects.
  558.  * @property {SHA256IdHash[]} [group] An array of ID references to Group objects. *Only
  559.  * the latest version* of a group is granted access!
  560.  */
  561. export interface IdAccess {
  562.     $type$: 'IdAccess';
  563.     id: SHA256IdHash;
  564.     person: Array<SHA256IdHash<Person>>;
  565.     group: Array<SHA256IdHash<Group>>;
  566. }
  568. /**
  569.  * This type is included in {@link Chum} objects as well as used internally.
  570.  * The numbers are without network overhead. The number of sent requests always includes the
  571.  * connect request, so after communication finished both parties will have sent one more request
  572.  * than they themselves received, since the connect request is to the communication server!
  573.  * @global
  574.  * @typedef {object} WebsocketStatistics
  575.  * @property {number} requestsSentTotal Total number of requests made thus far
  576.  * @property {number} requestsReceivedTotal Total number of requests received thus far
  577.  * @property {number} requestsReceivedInvalid Total number of requests received that had to be
  578.  * ignored because they were either unparsable (invalid JSON) or otherwise unusable
  579.  */
  580. export interface WebsocketStatistics {
  581.     requestsSentTotal: number;
  582.     requestsReceivedTotal: number;
  583.     requestsReceivedInvalid: number;
  584. }
  586. /**
  587.  * A Chum object defines a filter for exchanging data with other instances.
  588.  * Initially it only filters by persons.
  589.  *
  590.  * ### Example
  591.  *
  592.  * ```html
  593.  * <div itemscope itemtype="//refin.io/Chum">
  594.  *   <span itemprop="name">ThisChumsName</span>
  595.  *   <span itemprop="instance">${name1}</span>
  596.  *   <span itemprop="instance">${name2}</span>
  597.  *   <span itemprop="person">${hash1}</span>
  598.  *   <span itemprop="person">${hash2}</span>
  599.  *   <span itemprop="highestRemoteTimestamp">${timestamp1}</span>
  600.  *   ...
  601.  * </span>
  602.  * ```
  603.  * @global
  604.  * @typedef {object} Chum
  605.  * @property {'Chum'} $type$ - Fixed string 'Chum'
  606.  * @property {string} name
  607.  * @property {string[]} instance - A pair of instance names
  608.  * @property {SHA256IdHash[]} person - A pair of Person ID hashes. The first one is the one the
  609.  * local instance (owner of the Chum object) used for authentication to the remote instance,
  610.  * the second one is the one the remote instance used to do the same for the local instance.
  611.  * @property {number} highestRemoteTimestamp - A numeric timestamp specifying a date-time on
  612.  * the remote system. We can be sure to have all objects accessible to us created or made
  613.  * accessible to us before that time. NOTE: If older objects are made accessible it
  614.  * will be through an object created at a later time. Since this cutoff date-time specifies
  615.  * the root node of an accessible directed graph, which by necessity (hash links!) has to be
  616.  * created after all others, we get older objects linked from such a root node in any case.
  617.  * This timestamp is only used to filter root nodes.
  618.  * @property {Array<SHA256Hash>} AtoBObjects - Record of all transfers from A to B
  619.  * @property {Array<SHA256IdHash>} AtoBIdObjects - Record of all ID transfers from A to B
  620.  * @property {Array<SHA256Hash>} AtoBBlob - Record of all BLOB transfers from A to B
  621.  * @property {Array<SHA256Hash>} AtoBClob - Record of all CLOB transfers from A to B
  622.  * @property {Array<SHA256Hash>} BtoAObjects - Record of all transfers from B to A
  623.  * @property {Array<SHA256IdHash>} BtoAIdObjects - Record of all ID transfers from B to A
  624.  * @property {Array<SHA256Hash>} BtoABlob - Record of all BLOB transfers from B to A
  625.  * @property {Array<SHA256Hash>} BtoAClob - Record of all CLOB transfers from B to A
  626.  * @property {number} BtoAExists - How many hashes we already had and did not need to import
  627.  * @property {Error[]} errors - Record of exceptions encountered while running
  628.  * @property {Set<SHA256Hash>} [unacknowledged] - List of hashes of files sent for which we did
  629.  * not receive an acknowledgement that it was successfully stored by the importer.
  630.  * **NOTE:** These hashes don't cause any reverse map entries to be created - this field is
  631.  * somewhat optional and "FYI". The main fields are the other transfers-recording fields.
  632.  * @property {WebsocketStatistics} [statistics] - Data about the exchange such as bytes
  633.  * sent/received
  634.  */
  635. export interface Chum {
  636.     $type$: 'Chum';
  637.     name: string;
  638.     instance: [string, string];
  639.     person: [SHA256IdHash<Person>, undefined | SHA256IdHash<Person>];
  640.     highestRemoteTimestamp: number;
  641.     AtoBObjects: SHA256Hash[];
  642.     AtoBIdObjects: SHA256IdHash[];
  643.     AtoBBlob: Array<SHA256Hash<BLOB>>;
  644.     AtoBClob: Array<SHA256Hash<CLOB>>;
  645.     BtoAObjects: SHA256Hash[];
  646.     BtoAIdObjects: SHA256IdHash[];
  647.     BtoABlob: Array<SHA256Hash<BLOB>>;
  648.     BtoAClob: Array<SHA256Hash<CLOB>>;
  649.     BtoAExists: number;
  650.     errors: Error[];
  651.     unacknowledged?: Set<SHA256Hash<HashTypes> | SHA256IdHash>;
  652.     statistics?: WebsocketStatistics;
  653. }
  655. /**
  656.  * {@link Access|Access} objects link to `Group` objects to grant access rights.
  657.  *
  658.  * ### Example
  659.  *
  660.  * Javascript representation:
  661.  *
  662.  * ```javascript
  663.  * const obj = {
  664.  *     $type$: 'Group',
  665.  *     name: name,
  666.  *     person: [Person1-idHash, Person2-idHash]
  667.  * };
  668.  * ```
  669.  *
  670.  * HTML microdata representation:
  671.  *
  672.  * ```html
  673.  * <span itemprop="item" itemscope itemtype="//refin.io/Group">
  674.  *   <span itemprop="name">${name}</span>
  675.  *   <span itemprop="person">${Person1-ID-hash}</span>
  676.  *   <span itemprop="person">${Person2-ID-hash}</span>
  677.  * </span>
  678.  * ```
  679.  * @global
  680.  * @typedef {object} Group
  681.  * @property {'Group'} $type$ - Fixed string 'Group'
  682.  * @property {string} name
  683.  * @property {SHA256IdHash[]} person
  684.  *
  685.  */
  686. export interface Group {
  687.     $type$: 'Group';
  688.     name: string;
  689.     person: Array<SHA256IdHash<Person>>;
  690. }
  692. /**
  693.  * An Instance object describes one instance of the app. Multiple instances can co-exist on
  694.  * one, and even in the same disk space. Both instances would share the same directory and
  695.  * much of their respective data.
  696.  *
  697.  * The encryption key pair is generated by TweetNaCl.js and is stored in two Base 64 encoded
  698.  * strings:
  699.  *  - Base 64 character set: {@link https://tools.ietf.org/html/rfc4648#section-4}
  700.  *  - Base 64 length: {@link https://stackoverflow.com/q/13378815/544779}
  701.  *  - TweetNaCl length is n=32 bytes
  702.  *  - Base 64 encoded length: Math.ceil(4 * n/3) => 43, plus trailing "=" padding character
  703.  *  for a total length of 44 characters.
  704.  *
  705.  * ### Example
  706.  *
  707.  * Javascript representation:
  708.  *
  709.  * ```javascript
  710.  * const obj = {
  711.  *     $type$: 'Instance',
  712.  *     name: 'InstanceName',
  713.  *     owner: personIdHash,
  714.  *     publicKey: blobHash,
  715.  *     secretKey: blobHash,
  716.  *     module: [moduleHash]
  717.  * };
  718.  * ```
  719.  *
  720.  * HTML microdata representation:
  721.  *
  722.  * ```html
  723.  * <div itemscope itemtype="//refin.io/Instance">
  724.  *   <div itemscope="name">InstanceName</span>
  725.  *   <span itemprop="owner">${personIdHash}</span>
  726.  *   <span itemprop="publicKey">${publicKey}</span>
  727.  *   <a itemprop="module" href="${moduleHash}">${module1-hash}</a>
  728.  * </span>
  729.  * ```
  730.  * @global
  731.  * @typedef {object} Instance
  732.  * @property {'Instance'} $type$
  733.  * @property {string} name - The name of the instance chosen by the user
  734.  * @property {SHA256IdHash} owner - A reference to a Person ID object
  735.  * @property {SHA256Hash[]} recipe - A list of ONE object recipes
  736.  * @property {SHA256Hash[]} module - A list of code modules
  737.  * @property {Map<OneObjectTypeNames,null|Set<string>>} enabledReverseMapTypes - A Map
  738.  * object with ONE object type names as keys and an array of "itemprop" properties from the
  739.  * recipe for that particular ONE object type for which  reverse maps should be written. For
  740.  * all other types and/or properties not mentioned in this Map reverse map entries are not
  741.  * created.
  742.  * @property {Map<OneObjectTypeNamesForIdObjects,null|Set<string>>}
  743.  *     enabledReverseMapTypesForIdObjects - A Map object with ONE object type names as keys and an
  744.  *     array of "itemprop" properties from the recipe for that particular ONE object type for which
  745.  *     ID object reverse maps should be written. For all other types and/or properties not
  746.  *     mentioned in this Map reverse map entries are not created.
  747.  */
  748. export interface Instance {
  749.     $type$: 'Instance';
  750.     name: string;
  751.     owner: SHA256IdHash<Person>;
  752.     recipe: Array<SHA256Hash<Recipe>>;
  753.     module: Array<SHA256Hash<Module>>;
  754.     enabledReverseMapTypes: Map<OneObjectTypeNames, Set<string>>;
  755.     enabledReverseMapTypesForIdObjects: Map<OneVersionedObjectTypeNames, Set<string>>;
  756. }
  758. /**
  759.  * This object stores the *public* encryption and sign keys for a given {@link Instance} or
  760.  * {@link Person} ID. The secret keys are stored in a special non-shared private storage area.
  761.  * @global
  762.  * @typedef {object} Keys
  763.  * @property {'Keys'} $type$
  764.  * @property {SHA256IdHash} owner
  765.  * @property {HexString} publicKey
  766.  * @property {HexString} publicSignKey
  767.  */
  768. export interface Keys {
  769.     $type$: 'Keys';
  770.     owner: SHA256IdHash<Instance | Person>;
  771.     publicKey: HexString;
  772.     publicSignKey: HexString;
  773. }
  775. /**
  776.  * ### Example
  777.  *
  778.  * Javascript representation:
  779.  *
  780.  * ```javascript
  781.  * const obj = {
  782.  *     $type$: 'Module',
  783.  *     name: '@module/imap-mailbox-handler',
  784.  *     version: '1.0',
  785.  *     requires: [
  786.  *         '@module/imap-promisifier.js',
  787.  *         '@one/message-bus.js',
  788.  *         '@one/storage.js'
  789.  *     ],
  790.  *     code: clobHash
  791.  * };
  792.  * ```
  793.  *
  794.  * HTML microdata representation:
  795.  *
  796.  * ```html
  797.  * <div itemscope itemtype="//refin.io/Module">
  798.  *   <span itemprop="name">@module/imap-mailbox-handler</span>
  799.  *   <span itemprop="version">1.0</span>
  800.  *   <span itemprop="requires">@module/imap-promisifier.js</span>
  801.  *   <span itemprop="requires">lib/message-bus.js</span>
  802.  *   <span itemprop="requires">lib/storage.js</span>
  803.  *   <span itemprop="code">${CLOB-hash}</span>
  804.  * </span>
  805.  * ```
  806.  * @global
  807.  * @typedef {object} Module
  808.  * @property {'Module'} $type$
  809.  * @property {string} name The name that will be used by other modules to request this module
  810.  * @property {string[]} [provides]
  811.  * @property {string[]} [requires] The modules called from this module, extracted from
  812.  * require() or import calls from its code
  813.  * @property {string} [version] An optional version string
  814.  * @property {SHA256Hash} [code] Link to a UTF-8 CLOB with the Javascript code for this module
  815.  */
  816. export interface Module {
  817.     $type$: 'Module';
  818.     name: string;
  819.     provides?: string[];
  820.     requires?: string[];
  821.     version?: string;
  822.     code?: SHA256Hash<CLOB>;
  823. }
  825. /**
  826.  * ### Example
  827.  *
  828.  * Javascript representation:
  829.  *
  830.  * ```javascript
  831.  * const obj = {
  832.  *     $type$: 'Person',
  833.  *     email: 'members@gmx.net',
  834.  *     name: 'Foo Test'
  835.  * };
  836.  * ```
  837.  *
  838.  * HTML microdata representation:
  839.  *
  840.  * ```html
  841.  * <div itemscope itemtype="//refin.io/Person">
  842.  *   <span itemprop="email">members@gmx.net</span>
  843.  * </span>
  844.  * ```
  845.  * @global
  846.  * @typedef {object} Person
  847.  * @property {'Person'} $type$
  848.  * @property {string} email - A person-identifying unique email address
  849.  * @property {string} [name]
  850.  */
  851. export interface Person {
  852.     $type$: 'Person';
  853.     email: string;
  854.     name?: string;
  855. }
  857. /**
  858.  * The array of rules determines the properties of the ONE object and their order (in the
  859.  * written microdata representation).
  860.  *
  861.  * ### Example
  862.  *
  863.  * Javascript representation:
  864.  *
  865.  * ```javascript
  866.  * const obj = {
  867.  *     $type$: 'Recipe',
  868.  *     name: ONE-object-type-name,
  869.  *     version: 1,
  870.  *     rule: [
  871.  *         {
  872.  *             itemprop: property1-name
  873.  *             isId: true
  874.  *             valueType: 'number'
  875.  *         },
  876.  *         {
  877.  *             itemprop: property2-name,
  878.  *             regexp: /^[\w]*+$/
  879.  *         },
  880.  *         {
  881.  *             itemprop: property3-name
  882.  *             valueType: 'map'
  883.  *         },
  884.  *         {
  885.  *             itemprop: property4-name
  886.  *             referenceToObj: new Set(['*'])
  887.  *         }
  888.  *     ]
  889.  * };
  890.  * ```
  891.  *
  892.  * HTML microdata representation:
  893.  *
  894.  * ```html
  895.  * <div itemscope itemtype="//refin.io/Recipe">
  896.  *   <span itemprop="name">${ONE-object-type-name}</span>
  897.  *   <span itemprop="rule">
  898.  *     <span itemprop="itemprop">${property1-name}</span>
  899.  *     <span itemprop="isId">true</span>
  900.  *     <span itemprop="valueType">number</span>
  901.  *   </span>
  902.  *   <span itemprop="rule">
  903.  *     <span itemprop="itemprop">${property2-name}</span>
  904.  *   </span>
  905.  *   <span itemprop="rule">
  906.  *     <span itemprop="itemprop">${property3-name}</span>
  907.  *     <span itemprop="valueType">Map</span>
  908.  *   </span>
  909.  *   <span itemprop="rule">
  910.  *     <span itemprop="itemprop">${property4-name}</span>
  911.  *     <span itemprop="referenceToObj">['*']</span>
  912.  *   </span>
  913.  * </span>
  914.  * ```
  915.  * @global
  916.  * @typedef {object} Recipe
  917.  * @property {'Recipe'} $type$
  918.  * easily load a specific version of this versioned Recipe object.
  919.  * @property {string} name The type-string constant identifying this ONE object type
  920.  * @property {RecipeRule[]} rule Array of rules
  921.  */
  922. export interface Recipe {
  923.     $type$: 'Recipe';
  924.     name: OneObjectTypeNames;
  925.     rule: RecipeRule[];
  926.     crdtConfig?: Map<string, CRDTImplementationNames>;
  927. }
  929. /**
  930.  * Important note (from @sebastian). I decided to keep exclude 'list' even if we don't have
  931.  * the list field anymore in {@link RecipeRule}. It will remove 'array','bag' or 'set' field in
  932.  * the {@link RecipeRule.itemtype} and keep only the item type.
  933.  *
  934.  *
  935.  * The recipe-rule property "inheritFrom" can be either a string (common inheritance) or an
  936.  * object (inheritance with additional options). This is the type of the object in the latter case.
  937.  * @global
  938.  * @typedef {object} RuleInheritanceWithOptions
  939.  * @property {string} rule - The rule to inherit from as "." separated path Recipe.itemprop
  940.  * @property {'CollectionItemType' | 'MapItemType'} extract - Extracts the item type inside a
  941.  * collection or map.
  942.  */
  943. export interface RuleInheritanceWithOptions {
  944.     rule: string;
  945.     extract: 'CollectionItemType' | 'MapItemType';
  946. }
  948. /**
  949.  * This object is part of {@link Recipe} but has an extra type because the rule objects  appear
  950.  * on their own in parts of the code, where those rules are given to functions to process parts
  951.  * of ONE objects.
  952.  *
  953.  * NOTE: If this type is updated don't forget to also update function `ensureRecipeRule()` in
  954.  * <PROJECT_HOME>/src/util/recipe-checks.js
  955.  * @global
  956.  * @typedef {object} RecipeRule
  957.  * @property {string} itemprop - Create a microdata span tag with attribute "itemprop".
  958.  * Equivalent to the "key" in a Javascript object literal. The equivalent of the "value"
  959.  * is, again similar to a JS object, either another object (recursion: see "referenceToObj"
  960.  * below) or an actual value (string).
  961.  * @property {boolean} [isId=false] - Whether this is an ID field for this type. If not present
  962.  * "false" is assumed.
  963.  * @property {ValueType} [type] - The Javascript type of this property: After
  964.  * reading microdata everything is a "string". Setting this to {@link ValueType}
  965.  * lets the Microdata => (JS) Object converter know that it has to convert the strings to these
  966.  * types. The default is "string", because everything already is a string anyway when stored as
  967.  * HTML microdata.
  968.  * @property {RecipeRule[]} [object] - An array of {@link RecipeRule} rules for a nested data
  969.  * property. It works just like including a full ONE object on a `referenceToObj` enabled
  970.  * property but without using an actual ONE object, only the data.
  971.  * @property {(string|RuleInheritanceWithOptions)} [inheritFrom] - Inherit properties from the
  972.  * given rule. The current rule inherits all properties of the linked rule and can override them
  973.  * or add to them with its own properties. In the simple case it is a string of the for
  974.  * Recipe[.itemprop].itemprop pointing to an itemprop in any known recipe. Recipe resolution
  975.  * happens at runtime, when "inheritFrom" is encountered for the first time in a recipe rule.
  976.  * The second case with options requires an object of the form {@link RuleInheritanceWithOptions}.
  977.  *
  978.  * ### Example
  979.  *
  980.  * Javascript representation:
  981.  *
  982.  * ```javascript
  983.  * const obj = {
  984.  *     itemprop: propertyValue,
  985.  *     isId: true,
  986.  *     list: 'array',
  987.  *     valueType: {number: {max: 1000}}
  988.  * };
  989.  * ```
  990.  *
  991.  * HTML microdata representation:
  992.  *
  993.  * ```html
  994.  * // Part of a "Recipe" object: Array of RecipeRule in property "rule"
  995.  * ...
  996.  *   <span itemprop="rule">
  997.  *     <span itemprop="itemprop">${propertyValue}</span>
  998.  *     <span itemprop="isId">true</span>
  999.  *     <span itemprop="valueType">"{\"number\":{\"max\":1000}}"</span>
  1000.  *   </span>
  1001.  * ...
  1002.  * ```
  1003.  */
  1004. export interface RecipeRule {
  1005.     itemprop: string;
  1006.     itemtype?: ValueType;
  1007.     optional?: boolean;
  1008.     isId?: boolean;
  1009.     inheritFrom?: string | RuleInheritanceWithOptions;
  1010. }
  1012. /**
  1013.  * This type stores a collection of metadata objects for a specific object (version).
  1014.  *
  1015.  * Example:
  1016.  * If you have an object with hash AB34... and you want to get meta-object (e.g. creation
  1017.  * time or crdt metadata objects) you can get the corresponding meta-object list that holds
  1018.  * all metadata objects pointing to object AB34...
  1019.  *
  1020.  * ```
  1021.  * const metaObjectList = await getObjectByIdObj({
  1022.  *     $type$: 'MetaObjectList',
  1023.  *     object: 'AB34...'
  1024.  * });
  1025.  *
  1026.  * // The meta-objects are available via
  1027.  * const objs = metaObjectList.obj.metaobject;
  1028.  * ```
  1029.  *
  1030.  * We should add convenience functions to get meta-objects of a specific type for a specific
  1031.  * object.
  1032.  */
  1033. export interface MetaObjectList {
  1034.     $type$: 'MetaObjectList';
  1035.     object: SHA256Hash<OneObjectTypes>;
  1036.     metaobject: Array<SHA256Hash<OneUnversionedObjectTypes>>;
  1037. }
  1039. // ######## CRDT Types ########
  1041. /**
  1042.  * Interface that lists all crdt capable versioned one objects.
  1043.  *
  1044.  * This interface is very similar to OneVersionedObjectInterfaces. The only difference is,
  1045.  * that this interface collects the one types that use CRDTs for synchronization. All types
  1046.  * that appear here are automatically inherited by OneVersionedObjectInterfaces.
  1047.  */
  1048. declare module '@OneObjectInterfaces' {
  1049.     export interface OneCrdtObjectInterfaces {
  1050.         CrdtDummy: CrdtDummy;
  1051.         CrdtDummy2: CrdtDummy2;
  1052.     }
  1053. }
  1055. /**
  1056.  * The id types for the OneCrdtObjectInterfaces.
  1057.  */
  1058. declare module '@OneObjectInterfaces' {
  1059.     export interface OneCrdtIdObjectInterfaces {
  1060.         CrdtDummy: Pick<CrdtDummy, 'id' | '$type$'>;
  1061.         CrdtDummy2: Pick<CrdtDummy2, 'id' | '$type$'>;
  1062.     }
  1063. }
  1065. /**
  1066.  * The types of all crdt capable versioned objects.
  1067.  */
  1068. export type OneCrdtObjectTypes = OneCrdtObjectInterfaces[keyof OneCrdtObjectInterfaces];
  1070. /**
  1071.  * The type names of all crdt capable versioned objects.
  1072.  */
  1073. export type OneCrdtObjectTypeNames = keyof OneCrdtObjectInterfaces;
  1075. /**
  1076.  * This type only exists, so that the OneCrdtObjectInterfaces is initially not empty.
  1077.  *
  1078.  * The empty interface poses sometimes a problem. If you have a useful crdt capable object
  1079.  * in one.core, you can remove this. We don't register the recipe of this object, so that
  1080.  * nobody attempts to use it.
  1081.  */
  1082. export interface CrdtDummy {
  1083.     $type$: 'CrdtDummy';
  1084.     id: string;
  1085. }
  1087. export interface CrdtDummy2 {
  1088.     $type$: 'CrdtDummy2';
  1089.     id: string;
  1090. }
  1092. // ######## CRDT Metadata Types ########
  1094. /**
  1095.  * The typescript interface for crdt metadata objects.
  1096.  */
  1097. export interface CRDTMetaData<T extends OneCrdtObjectTypes> {
  1098.     $type$: `${T['$type$']}CrdtMeta`;
  1099.     data: SHA256Hash<T>; // Pointer to the data
  1100.     crdt: Record<string, any>; // The crdt metadata.
  1101.     source?: 'local' | 'remote'; // A source string that lets us distinguish between remote and
  1102.     // local merges. It is mostly for debugging purposes.
  1103. }
  1105. /**
  1106.  * This interface defines the metadata types for the crdt types.
  1107.  *
  1108.  * These types are the types that store the crdt metadata for the object that are specified
  1109.  * in OneCrdtObjectInterfaces. So there is a 1:1 relationship between them.
  1110.  */
  1111. declare module '@OneObjectInterfaces' {
  1112.     export type OneCrdtMetaObjectInterfaces = {
  1113.         [k in keyof OneCrdtObjectInterfaces as `${k}CrdtMeta`]: CRDTMetaData<
  1114.             OneCrdtObjectInterfaces[k]
  1115.         >;
  1116.     };
  1118.     export type OneCrdtToMetaObjectInterfaces = {
  1119.         [k in keyof OneCrdtObjectInterfaces]: CRDTMetaData<OneCrdtObjectInterfaces[k]>;
  1120.     };
  1121. }
  1123. /**
  1124.  * The types of all crdt metadata objects.
  1125.  */
  1126. export type OneCrdtMetaObjectTypes = OneCrdtMetaObjectInterfaces[keyof OneCrdtMetaObjectInterfaces];
  1128. /**
  1129.  * The type names of all crdt metadata objects.
  1130.  */
  1131. export type OneCrdtMetaObjectTypeNames = keyof OneCrdtMetaObjectInterfaces;
  1133. import type {
  1134.     OneCrdtMetaObjectInterfaces,
  1135.     OneCrdtObjectInterfaces,
  1136.     OneIdObjectInterfaces,
  1137.     OneUnversionedObjectInterfaces,
  1138.     OneVersionedObjectInterfaces
  1139. } from '@OneObjectInterfaces';
  1140. import type {CRDTImplementationNames} from './crdt/CRDTRegistry';
  1141. import type {HexString} from './util/arraybuffer-to-and-from-hex-string';
  1142. import type {SHA256Hash, SHA256IdHash} from './util/type-checks';
  1144. /**
  1145.  * The allowed values for {@link RecipeRule}'s property `list` for list properties (i.e. more
  1146.  * than one value for the given `itemprop`). Leave the property undefined if the value is not a
  1147.  * list but a single value.
  1148.  *
  1149.  * Background/reason: The same elements but a different order will produce a different SHA-256
  1150.  * hash of the content! Here is when you tell one that this is what is intended or not.
  1151.  *
  1152.  * - `ORDERED_BY.ONE`: When converting an array of values to microdata the result will be
  1153.  * alphabetically ordered to impose a reproducible order, in order to guarantee that the same
  1154.  * unordered "bag" of data produces the exact same microdata and the exact same SHA-256 hash.
  1155.  * This means that an array of the exact same elements in different order is going to lead to a
  1156.  * microdata representation that is always the same. IT also means that when reading the ONE
  1157.  * object back from storage the order will be whatever the alphabetical sorting of the microdata
  1158.  * elements produced, which may be different from the original order when the data was saved.
  1159.  *
  1160.  * - `ORDERED_BY.APP`: When converting the array of values the order is left as-is. This means
  1161.  * that an array of the exact same elements in different order is going to lead to a microdata
  1162.  * representation that is different, which leads to a different SHA-256 hash.
  1163.  * @static
  1164.  * @type {object}
  1165.  * @property {'orderedByONE'} ONE
  1166.  * @property {'orderedByApp'} APP
  1167.  */
  1168. export const ORDERED_BY = {
  1169.     ONE: 'orderedByONE',
  1170.     APP: 'orderedByApp'
  1171. } as const;
  1173. /**
  1174.  * Declare the private ONE storage for RECIPES. They describe how objects are built and are used
  1175.  * to create the Javascript, JSON and the microdata representations of ONE objects.
  1176.  *
  1177.  * Note: The examples for each ONE object type recipe are **with newlines and indentation** for
  1178.  * readability. The actual output will not have spaces or newlines!
  1179.  * @static
  1180.  * @type {Recipe[]}
  1181.  */
  1182. export const CORE_RECIPES: readonly Recipe[] = [
  1183.     {
  1184.         $type$: 'Recipe',
  1185.         name: 'Access',
  1186.         rule: [
  1187.             {
  1188.                 itemprop: 'object',
  1189.                 itemtype: {type: 'referenceToObj', allowedTypes: new Set(['*'])},
  1190.                 isId: true
  1191.             },
  1192.             {
  1193.                 // Reference to ID hashes of persons
  1194.                 itemprop: 'person',
  1195.                 itemtype: {
  1196.                     type: 'bag',
  1197.                     item: {
  1198.                         type: 'referenceToId',
  1199.                         allowedTypes: new Set(['Person'])
  1200.                     }
  1201.                 }
  1202.             },
  1203.             {
  1204.                 // References to ID hashes of groups
  1205.                 itemprop: 'group',
  1206.                 itemtype: {
  1207.                     type: 'bag',
  1208.                     item: {
  1209.                         type: 'referenceToId',
  1210.                         allowedTypes: new Set(['Group'])
  1211.                     }
  1212.                 }
  1213.             }
  1214.         ]
  1215.     },
  1217.     {
  1218.         $type$: 'Recipe',
  1219.         name: 'IdAccess',
  1220.         rule: [
  1221.             {
  1222.                 itemprop: 'id',
  1223.                 itemtype: {
  1224.                     type: 'referenceToId',
  1225.                     allowedTypes: new Set(['*'])
  1226.                 },
  1227.                 isId: true
  1228.             },
  1229.             {
  1230.                 itemprop: 'person',
  1231.                 itemtype: {
  1232.                     type: 'bag',
  1233.                     item: {
  1234.                         type: 'referenceToId',
  1235.                         allowedTypes: new Set(['Person'])
  1236.                     }
  1237.                 }
  1238.             },
  1239.             {
  1240.                 itemprop: 'group',
  1241.                 itemtype: {
  1242.                     type: 'bag',
  1243.                     item: {
  1244.                         type: 'referenceToId',
  1245.                         allowedTypes: new Set(['Group'])
  1246.                     }
  1247.                 }
  1248.             }
  1249.         ]
  1250.     },
  1252.     {
  1253.         $type$: 'Recipe',
  1254.         name: 'Chum',
  1255.         rule: [
  1256.             {
  1257.                 // Every chum is identified by a name.
  1258.                 // <span itemprop="name">some-name</span>
  1259.                 itemprop: 'name',
  1260.                 isId: true
  1261.             },
  1262.             {
  1263.                 // Names of the two instances that can exchange data via this chum.
  1264.                 // <span itemprop="instance">instance name</span>
  1265.                 itemprop: 'instance',
  1266.                 isId: true,
  1267.                 itemtype: {
  1268.                     type: 'array',
  1269.                     item: {
  1270.                         type: 'string'
  1271.                     }
  1272.                 } // always 2
  1273.             },
  1274.             {
  1275.                 // Person hash of the two persons who can exchange data via this Chum.
  1276.                 // Also used to authenticate the remote user.
  1277.                 // TODO Make it a referenceToIdObj
  1278.                 // <span itemprop="person">personHash</span>
  1279.                 itemprop: 'person',
  1280.                 isId: true,
  1281.                 itemtype: {
  1282.                     type: 'array',
  1283.                     item: {
  1284.                         type: 'string',
  1285.                         regexp: /^(undefined|[0-9a-f]{64})$/
  1286.                     }
  1287.                 } // Our type "SHA256Hash"
  1288.             },
  1289.             {
  1290.                 // Milliseconds-since 1/1/1970 timestamp
  1291.                 // <span itemprop="highestRemoteTimestamp">timestamp</span>
  1292.                 itemprop: 'highestRemoteTimestamp',
  1293.                 itemtype: {
  1294.                     type: 'integer'
  1295.                 }
  1296.             },
  1297.             // The transfer lists cannot be saved as "array of two" (pairs) because they already
  1298.             // are arrays (list:'orderedByONE'), and saving them as JSON-encoded strings is not
  1299.             // possible since that would prevent the reverse-map updates for the reference links
  1300.             // as well as any other hash-link based functionality.
  1301.             {
  1302.                 itemprop: 'AtoBObjects',
  1303.                 itemtype: {
  1304.                     type: 'bag',
  1305.                     item: {
  1306.                         type: 'referenceToObj',
  1307.                         allowedTypes: new Set(['*'])
  1308.                     }
  1309.                 }
  1310.             },
  1311.             {
  1312.                 itemprop: 'AtoBIdObjects',
  1313.                 itemtype: {
  1314.                     type: 'bag',
  1315.                     item: {
  1316.                         type: 'referenceToId',
  1317.                         allowedTypes: new Set(['*'])
  1318.                     }
  1319.                 }
  1320.             },
  1321.             {
  1322.                 itemprop: 'AtoBBlob',
  1323.                 itemtype: {
  1324.                     type: 'bag',
  1325.                     item: {
  1326.                         type: 'referenceToBlob'
  1327.                     }
  1328.                 }
  1329.             },
  1330.             {
  1331.                 itemprop: 'AtoBClob',
  1332.                 itemtype: {
  1333.                     type: 'bag',
  1334.                     item: {
  1335.                         type: 'referenceToClob'
  1336.                     }
  1337.                 }
  1338.             },
  1339.             {
  1340.                 itemprop: 'BtoAObjects',
  1341.                 itemtype: {
  1342.                     type: 'bag',
  1343.                     item: {
  1344.                         type: 'referenceToObj',
  1345.                         allowedTypes: new Set(['*'])
  1346.                     }
  1347.                 }
  1348.             },
  1349.             {
  1350.                 itemprop: 'BtoAIdObjects',
  1351.                 itemtype: {
  1352.                     type: 'bag',
  1353.                     item: {
  1354.                         type: 'referenceToId',
  1355.                         allowedTypes: new Set(['*'])
  1356.                     }
  1357.                 }
  1358.             },
  1359.             {
  1360.                 itemprop: 'BtoABlob',
  1361.                 itemtype: {
  1362.                     type: 'bag',
  1363.                     item: {
  1364.                         type: 'referenceToBlob'
  1365.                     }
  1366.                 }
  1367.             },
  1368.             {
  1369.                 itemprop: 'BtoAClob',
  1370.                 itemtype: {
  1371.                     type: 'bag',
  1372.                     item: {
  1373.                         type: 'referenceToClob'
  1374.                     }
  1375.                 }
  1376.             },
  1377.             {
  1378.                 itemprop: 'BtoAExists',
  1379.                 itemtype: {
  1380.                     type: 'integer'
  1381.                 }
  1382.             },
  1383.             {
  1384.                 // For logging purposes: List of hashes of files sent for which we did not
  1385.                 // receive an acknowledgement
  1386.                 // This is saved as string and not as reference because it is not meant to be a
  1387.                 // graph-creating reference.
  1388.                 // <span itemprop="unacknowledged">["hash1","hash2"]</span>
  1389.                 itemprop: 'unacknowledged',
  1390.                 optional: true,
  1391.                 itemtype: {
  1392.                     type: 'set',
  1393.                     item: {
  1394.                         type: 'string'
  1395.                     }
  1396.                 }
  1397.             },
  1398.             {
  1399.                 // For logging purposes: statistical data
  1400.                 // <span itemprop="statistics">{sent:...,received:...}</span>
  1401.                 itemprop: 'statistics',
  1402.                 itemtype: {type: 'stringifiable'},
  1403.                 optional: true
  1404.             },
  1405.             {
  1406.                 // For logging purposes: List of errors raised by the importer or exporter
  1407.                 // <span itemprop="errors">["..."]</span>
  1408.                 itemprop: 'errors',
  1409.                 itemtype: {type: 'stringifiable'},
  1410.                 optional: true
  1411.             }
  1412.         ]
  1413.     },
  1415.     {
  1416.         $type$: 'Recipe',
  1417.         name: 'Group',
  1418.         rule: [
  1419.             {
  1420.                 // <span itemprop="name">${name}</a>
  1421.                 itemprop: 'name',
  1422.                 isId: true
  1423.             },
  1424.             {
  1425.                 itemprop: 'person',
  1426.                 itemtype: {
  1427.                     type: 'bag',
  1428.                     item: {
  1429.                         type: 'referenceToId',
  1430.                         allowedTypes: new Set(['Person'])
  1431.                     }
  1432.                 }
  1433.             }
  1434.         ]
  1435.     },
  1437.     {
  1438.         $type$: 'Recipe',
  1439.         name: 'Instance',
  1440.         rule: [
  1441.             {
  1442.                 // Every instance is identified by name, which should be unique per user.
  1443.                 itemprop: 'name',
  1444.                 isId: true
  1445.             },
  1446.             {
  1447.                 // The owner of the app represented by its person ID.
  1448.                 itemprop: 'owner',
  1449.                 itemtype: {
  1450.                     type: 'referenceToId',
  1451.                     allowedTypes: new Set(['Person'])
  1452.                 },
  1453.                 isId: true
  1454.             },
  1455.             {
  1456.                 // Reference to Recipe objects.
  1457.                 itemprop: 'recipe',
  1458.                 itemtype: {
  1459.                     type: 'bag',
  1460.                     item: {
  1461.                         type: 'referenceToObj',
  1462.                         allowedTypes: new Set(['Recipe'])
  1463.                     }
  1464.                 }
  1465.             },
  1466.             {
  1467.                 // Reference to Module objects.
  1468.                 itemprop: 'module',
  1469.                 itemtype: {
  1470.                     type: 'bag',
  1471.                     item: {
  1472.                         type: 'referenceToObj',
  1473.                         allowedTypes: new Set(['Module'])
  1474.                     }
  1475.                 }
  1476.             },
  1477.             {
  1478.                 itemprop: 'enabledReverseMapTypes',
  1479.                 itemtype: {
  1480.                     type: 'map',
  1481.                     key: {
  1482.                         type: 'string'
  1483.                     },
  1484.                     value: {
  1485.                         type: 'set',
  1486.                         item: {
  1487.                             type: 'string'
  1488.                         }
  1489.                     }
  1490.                 }
  1491.             },
  1492.             {
  1493.                 itemprop: 'enabledReverseMapTypesForIdObjects',
  1494.                 itemtype: {
  1495.                     type: 'map',
  1496.                     key: {
  1497.                         type: 'string'
  1498.                     },
  1499.                     value: {
  1500.                         type: 'set',
  1501.                         item: {
  1502.                             type: 'string'
  1503.                         }
  1504.                     }
  1505.                 }
  1506.             }
  1507.         ]
  1508.     },
  1510.     {
  1511.         $type$: 'Recipe',
  1512.         name: 'Keys',
  1513.         rule: [
  1514.             {
  1515.                 itemprop: 'owner',
  1516.                 itemtype: {
  1517.                     type: 'referenceToId',
  1518.                     allowedTypes: new Set(['Instance', 'Person'])
  1519.                 }
  1520.             },
  1521.             {
  1522.                 // ENCRYPTION KEY: Hex encoded public key (64 characters)
  1523.                 itemprop: 'publicKey',
  1524.                 // TweetNaCl length is n=32 bytes
  1525.                 itemtype: {
  1526.                     type: 'string',
  1527.                     regexp: /^[A-Za-z0-9+/]{64}$/
  1528.                 }
  1529.             },
  1530.             {
  1531.                 // SIGN KEY: Hex encoded public key (64 characters)
  1532.                 itemprop: 'publicSignKey',
  1533.                 // TweetNaCl length is n=32 bytes
  1534.                 itemtype: {
  1535.                     type: 'string',
  1536.                     regexp: /^[A-Za-z0-9+/]{64}$/
  1537.                 }
  1538.             }
  1539.         ]
  1540.     },
  1542.     {
  1543.         $type$: 'Recipe',
  1544.         name: 'Module',
  1545.         rule: [
  1546.             {
  1547.                 // The name should include namespace-components. The name is what other scripts use
  1548.                 // to call (import) this module's code.
  1549.                 // <span itemprop="name">some-name</span>
  1550.                 itemprop: 'name',
  1551.                 isId: true
  1552.             },
  1553.             {
  1554.                 // <span itemprop="version">0.1</span>
  1555.                 itemprop: 'version',
  1556.                 optional: true
  1557.             },
  1558.             {
  1559.                 // <span itemprop="provides">types provided by the Module</span>
  1560.                 // list of type recipes (from this file or future alternatives)
  1561.                 itemprop: 'provides',
  1562.                 itemtype: {
  1563.                     type: 'bag',
  1564.                     item: {
  1565.                         type: 'string'
  1566.                     }
  1567.                 },
  1568.                 optional: true
  1569.             },
  1570.             {
  1571.                 // <span itemprop="requires">types required by the Module</span>
  1572.                 // list of type recipes (from this file or future alternatives)
  1573.                 itemprop: 'requires',
  1574.                 itemtype: {
  1575.                     type: 'bag',
  1576.                     item: {
  1577.                         type: 'string'
  1578.                     }
  1579.                 },
  1580.                 optional: true
  1581.             },
  1582.             {
  1583.                 // Pointer to a Javascript file stored as CLOB and named for its crypto-hash
  1584.                 // <span itemprop="code">${hash}</span>
  1585.                 itemprop: 'code',
  1586.                 itemtype: {
  1587.                     type: 'referenceToClob'
  1588.                 }
  1589.             }
  1590.         ]
  1591.     },
  1592.     {
  1593.         $type$: 'Recipe',
  1594.         name: 'Person',
  1595.         rule: [
  1596.             {
  1597.                 itemprop: 'email',
  1598.                 isId: true
  1599.             },
  1600.             {
  1601.                 itemprop: 'name',
  1602.                 optional: true
  1603.             }
  1604.         ]
  1605.     },
  1607.     {
  1608.         $type$: 'Recipe',
  1609.         name: 'Recipe', // This recipe describes _itself_ :-)
  1610.         rule: [
  1611.             {
  1612.                 // <span itemprop="name">${name}</span>
  1613.                 itemprop: 'name',
  1614.                 isId: true
  1615.             },
  1616.             {
  1617.                 itemprop: 'crdtConfig',
  1618.                 optional: true,
  1619.                 itemtype: {
  1620.                     type: 'map',
  1621.                     key: {type: 'string'},
  1622.                     value: {type: 'string'}
  1623.                 }
  1624.             },
  1625.             {
  1626.                 itemprop: 'rule',
  1627.                 itemtype: {
  1628.                     type: 'array',
  1629.                     item: {
  1630.                         type: 'object',
  1631.                         rules: [
  1632.                             {
  1633.                                 // <span itemprop="itemprop">${itemprop}</span>
  1634.                                 itemprop: 'itemprop'
  1635.                             },
  1636.                             {
  1637.                                 itemprop: 'optional',
  1638.                                 itemtype: {
  1639.                                     type: 'boolean'
  1640.                                 },
  1641.                                 optional: true
  1642.                             },
  1643.                             {
  1644.                                 // <span itemprop="isId">${true}</span>
  1645.                                 itemprop: 'isId',
  1646.                                 itemtype: {
  1647.                                     type: 'boolean'
  1648.                                 },
  1649.                                 optional: true
  1650.                             },
  1651.                             {
  1652.                                 itemprop: 'itemtype',
  1653.                                 itemtype: {type: 'stringifiable'},
  1654.                                 optional: true
  1655.                             },
  1656.                             {
  1657.                                 itemprop: 'inheritFrom',
  1658.                                 itemtype: {
  1659.                                     type: 'stringifiable'
  1660.                                 },
  1661.                                 optional: true
  1662.                             }
  1663.                         ]
  1664.                     }
  1665.                 }
  1666.             }
  1667.         ]
  1668.     },
  1669.     {
  1670.         $type$: 'Recipe',
  1671.         name: 'MetaObjectList',
  1672.         rule: [
  1673.             {
  1674.                 itemprop: 'object',
  1675.                 isId: true,
  1676.                 itemtype: {
  1677.                     type: 'referenceToObj',
  1678.                     allowedTypes: new Set(['*'])
  1679.                 }
  1680.             },
  1681.             {
  1682.                 itemprop: 'metaobject',
  1683.                 // TODO: This should be a map from type to object
  1684.                 itemtype: {
  1685.                     type: 'bag',
  1686.                     item: {
  1687.                         type: 'referenceToObj',
  1688.                         allowedTypes: new Set(['*'])
  1689.                     }
  1690.                 }
  1691.             }
  1692.         ]
  1693.     }
  1694. ];