# Datastore Interface

Enum EventType {
    Create,
    Update,
    Delete,
    Restore,
}

Exception ModelDoesNotExist(model: Fqid);
Exception ModelExist(model: Fqid);
Exception ModelNotDeleted(model: Fqid);
Exception ModelLocked(key: Fqid | Fqfield | CollectionField);
Exception InvalidFormat(msg: string);
Exception InvalidRequest(msg: string);

# Note: Error returns via HTTP 400:
Interface ErrorResponse {
    error: InvalidFormatData |
        InvalidRequestData |
        ModelDoesNotExistData |
        ModelExistData |
        ModelMotDeletedData |
        ModelLockedData;
}
Interface InvalidFormatData {
    type: 1;
    msg: string;
}
Interface InvalidRequestData {
    type: 2;
    msg: string;
}
Interface ModelDoesNotExistData {
    type: 3;
    fqid: string;
}
Interface ModelExistData {
    type: 4;
    fqid: string;
}
Interface ModelNotDeletedData {
    type: 5;
    fqid: string;
}
Interface ModelLockedData {
    type: 6;
    key: string;
}

## Writer
# Note: Different host and port than the reader!

/**
 * Writes Events into the datastore.
 * Url: POST to /datastore/writer/write
 *
 * @throws ModelDoesNotExist
 * @throws ModelExists
 * @throws ModelLocked
 * @throws InvalidFormat
 * @throws ModelNotDeleted
 */
write(request: WriteRequest): void publishes ModifiedFieldsEvent

Interface WriteRequest {
    events: (CreateEvent | RestoreEvent | UpdateEvent | DeleteEvent)[];
    information: {
        <fqid>: Object
    };
    user_id: number;
    locked_fields: {
        <fqid>: Position;
        <fqfield>: Position;
        <CollectionField>: Position;
    }
}

Interface CreateEvent {
    type: 'create';
    fqid: Fqid;
    fields: {
        <field>: Value;
    }
}

// Note: For deleting keys, they must be set to `None`. These keys
// will be removed from the model.
Interface UpdateEvent {
    type: 'update';
    fqid: Fqid;
    fields: {
        <field>: Value;
    }
}

Interface RestoreEvent {
    type: 'restore';
    fqid: Fqid;
}

Interface DeleteEvent {
    type: 'delete';
    fqid: Fqid;
}

// Note: The modified fqfields include:
// - all updated fqfields
// - all deleted fqfields
// - all fqfields of all deleted models
// - all fqfields of all created models
// - all fqfields of all restored models (logically the same as created)
Event ModifiedFieldsEvent on topic ModifiedFields {
    modified: Fqfield[];
}

/**
 * Gibt n sequentielle Ids für die gegebene Collection zurück.
 * Url: POST to /datastore/writer/get_ids
 */
getIds(collection: Collection, n: number): Id[]


## Reader
# Note: Different host and port than the writer!

/** Common notes:
 * - parameter `position`: Optional, if given reads the data to this position.
 * - parameter `mapped_fields`: List of fields that should only be present in the response.
 * - parameter `get_deleted_models`: Optional, defines which models to return
 *    - DeletedModelsBehaviour.NO_DELETED:   (Default) only non-deleted models are returned.
 *                                           get throws a ModelDoesNotExist error if the given
 *                                           model is deleted.
 *    - DeletedModelsBehaviour.ONLY_DELETED: only deleted models are returned. get throws
 *                                           a ModelNotDeleted if the given model is not deleted.
 *    - DeletedModelsBehaviour.ALL_MODELS:   all models are returned
 * - All operations adds the fields `meta_position` and `meta_deleted` to the models.
 * - The InvalidFormat exception can always be thrown, if the requested formats are
 *   wrong, including something like empty collections, ...
 */

Enum DeletedModelsBehaviour {
    NO_DELETED = 1,
    ONLY_DELETED = 2,
    ALL_MODELS = 3
}

/**
 * Returns a model by fqid.
 *
 * @throws ModelDoesNotExist
 * @throws InvalidFormat
 */
get(fqid: Fqid, mapped_fields?: Field[], position?: Position, get_deleted_models?: DeletedModelsBehaviour): Partial<Model>;

/**
 * Returns multiple models.
 * Can either be called with a list of fqids (if all fields are needed/wanted or if the
 * same fields of all objects are needed) or with a list of specific request objects
 * that map a collection to the needed ids and fields. If both the lower and the higher
 * level mapped_fields are given, the higher level one is merged into all lower level
 * ones.
 * If an id is not found, it is not included in the response instead of throwing a
 * ModelDoesNotExist.
 *
 * @throws InvalidFormat
 */
getMany(requests: GetManyRequest[], mapped_fields?: Field[], position?: Position, get_deleted_models?: DeletedModelsBehaviour): Map<Fqid, Partial<Model>>;

Interface GetManyRequest {
    collection: Collection;
    ids: Id[];
    mapped_fields?: Field[];
}

/**
 * Returns all models of one collection. It is not possible to specify a position, so
 * this method cannot be used if the user browses the history. It should be noted that
 * it is highly disencouraged to use this method because it might return a huge amount
 * of data.
 */
getAll(collection: Collection, mapped_fields?: Field[], get_deleted_models?: DeletedModelsBehaviour): Partial<Model>[];

/**
 * Returns all models of one collection that satisfy the filter condition. This method
 * does not take a position and can not be used when browsing the history.
 *
 * @throws InvalidFormat
 */
filter(collection: Collection, filter: Filter, mapped_fields?: Field[]): Partial<Model>[]

/**
 * See `filter`, returns true, if at least one model was found. The returned position is
 * the highest position in the complete datastore.
 *
 * @throws InvalidFormat
 */
exists(collection: Collection, filter: Filter): {exists: boolean; position: Position;}

/**
 * See `filter`, returns the amount of found models. The returned position is
 * the highest position in the complete datastore.
 *
 * @throws InvalidFormat
 */
count(collection: Collection, filter: Filter): {count: number; position: Position;}

/**
 * Executes a min aggregation on all models of one collection on
 * the given field that satisfy the filter condition.
 * The field is cast to int by default. If aggregation of another field type is needed,
 * a valid type can be passed via the type parameter.
 *
 * @throws InvalidFormat
 */
min(collection: Collection, filter: Filter, field: Field, type?: string): {min: Value; position: Position;}

/**
 * Analogous to min.
 *
 * @throws InvalidFormat
 */
max(collection: Collection, filter: Filter, field: Field, type?: string): {max: Value; position: Position;}

Type Filter = And | Or | Not | FilterOperator

/**
 * The filter predicate. M[field] states the value of the field of a model M.
 * For all operations the predicate if true, if `M[field] <op> value` is true.
 */
Interface FilterOperator {
    field: Field;
    value: Value | null;
    operator: '=' | '!=' | '<' | '>' | '>=' | '<=';
}

Interface Not {
    not_filter: Filter;
}

Interface And {
    and_filter: Filter[];
}

Interface Or {
    or_filter: Filter[];
}