forked from jupyterlab/jupyterlab
-
Notifications
You must be signed in to change notification settings - Fork 0
/
interfaces.ts
100 lines (93 loc) · 3.16 KB
/
interfaces.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
// Copyright (c) Jupyter Development Team.
// Distributed under the terms of the Modified BSD License.
/**
* A generic interface for change emitter payloads.
*/
export interface IChangedArgs<T> {
/**
* The name of the changed attribute.
*/
name: string;
/**
* The old value of the changed attribute.
*/
oldValue: T;
/**
* The new value of the changed attribute.
*/
newValue: T;
}
/**
* The description of a general purpose data connector.
*
* #### Notes
* The generic type arguments <T, U = T, V = string> semantics are:
*
* T - is the basic entity response type a particular service's connector.
*
* U = T - is the basic entity request type, which is conventionally the same as
* the response type but may be different if a service's implementation requires
* input data to be different from output responses.
*
* V = string - is the basic token applied to a request, conventionally a string
* ID or filter, but may be set to a different type when an implementation
* requires it.
*/
export interface IDataConnector<T, U = T, V = string> {
/**
* Retrieve an item from the data connector.
*
* @param id - The identifier used to retrieve an item.
*
* @returns A promise that bears a data payload if available.
*
* #### Notes
* The promise returned by this method may be rejected if an error occurs in
* retrieving the data. Nonexistence of an `id` resolves with `undefined`.
*/
fetch(id: V): Promise<T | undefined>;
/**
* Retrieve the list of items available from the data connector.
*
* @param query - The optional query filter to apply to the connector request.
*
* @returns A promise that bears a list of `values` and an associated list of
* fetch `ids`.
*
* #### Notes
* The promise returned by this method may be rejected if an error occurs in
* retrieving the data. The two lists will always be the same size. If there
* is no data, this method will succeed with empty `ids` and `values`.
*/
list(query?: any): Promise<{ ids: V[]; values: T[] }>;
/**
* Remove a value using the data connector.
*
* @param id - The identifier for the data being removed.
*
* @returns A promise that is rejected if remove fails and succeeds otherwise.
*
* #### Notes
* This promise may resolve with a back-end response or `undefined`.
* Existence of resolved content in the promise is not prescribed and must be
* tested for. For example, some back-ends may return a copy of the item of
* type `T` being removed while others may return no content.
*/
remove(id: V): Promise<any>;
/**
* Save a value using the data connector.
*
* @param id - The identifier for the data being saved.
*
* @param value - The data being saved.
*
* @returns A promise that is rejected if saving fails and succeeds otherwise.
*
* #### Notes
* This promise may resolve with a back-end response or `undefined`.
* Existence of resolved content in the promise is not prescribed and must be
* tested for. For example, some back-ends may return a copy of the item of
* type `T` being saved while others may return no content.
*/
save(id: V, value: U): Promise<any>;
}