1 | // Copyright IBM Corp. 2018. All Rights Reserved.
|
2 | // Node module: loopback-datasource-juggler
|
3 | // This file is licensed under the MIT License.
|
4 | // License text available at https://opensource.org/licenses/MIT
|
5 |
|
6 | import {Callback, Options, PromiseOrVoid} from './common';
|
7 | import {ModelBase, ModelData} from './model';
|
8 |
|
9 | /**
|
10 | * Data object for KV models
|
11 | */
|
12 | export type KVData<T extends ModelBase = ModelBase> = ModelData<T>;
|
13 |
|
14 | /**
|
15 | * Key/Value model. Strictly speaking, KeyValueModel is not a class
|
16 | * but a mixin into existing model classes
|
17 | */
|
18 | export declare class KeyValueModel extends ModelBase {
|
19 | /**
|
20 | * Return the value associated with a given key.
|
21 | *
|
22 | * @param {string} key Key to use when searching the database.
|
23 | * @options {Object} options
|
24 | * @callback {Function} callback
|
25 | * @param {Error} err Error object.
|
26 | * @param {any} result Value associated with the given key.
|
27 | * @promise
|
28 | *
|
29 | * @header KeyValueModel.get(key, cb)
|
30 | */
|
31 | static get(
|
32 | key: string,
|
33 | options?: Options,
|
34 | callback?: Callback<KVData>,
|
35 | ): PromiseOrVoid<KVData>;
|
36 |
|
37 | /**
|
38 | * Persist a value and associate it with the given key.
|
39 | *
|
40 | * @param {string} key Key to associate with the given value.
|
41 | * @param {any} value Value to persist.
|
42 | * @options {Number|Object} options Optional settings for the key-value
|
43 | * pair. If a Number is provided, it is set as the TTL (time to live) in ms
|
44 | * (milliseconds) for the key-value pair.
|
45 | * @property {Number} ttl TTL for the key-value pair in ms.
|
46 | * @callback {Function} callback
|
47 | * @param {Error} err Error object.
|
48 | * @promise
|
49 | *
|
50 | * @header KeyValueModel.set(key, value, cb)
|
51 | */
|
52 | static set(
|
53 | key: string,
|
54 | value: KVData,
|
55 | options?: Options,
|
56 | callback?: Callback<void>,
|
57 | ): PromiseOrVoid<void>;
|
58 |
|
59 | /**
|
60 | * Delete the key-value pair associated to the given key.
|
61 | *
|
62 | * @param {string} key Key to use when searching the database.
|
63 | * @options {Object} options
|
64 | * @callback {Function} callback
|
65 | * @param {Error} err Error object.
|
66 | * @param {*} result Value associated with the given key.
|
67 | * @promise
|
68 | */
|
69 | static delete(
|
70 | key: string,
|
71 | options?: Options,
|
72 | callback?: Callback<void>,
|
73 | ): PromiseOrVoid<void>;
|
74 |
|
75 | /**
|
76 | * Delete all keys (and values) associated to the current model.
|
77 | *
|
78 | * @options {Object} options Unused ATM, placeholder for future options.
|
79 | * @callback {Function} callback
|
80 | * @param {Error} err Error object.
|
81 | * @promise
|
82 | */
|
83 | static deleteAll(
|
84 | options?: Options,
|
85 | callback?: Callback<void>,
|
86 | ): PromiseOrVoid<void>;
|
87 |
|
88 | /**
|
89 | * Set the TTL (time to live) in ms (milliseconds) for a given key. TTL is the
|
90 | * remaining time before a key-value pair is discarded from the database.
|
91 | *
|
92 | * @param {string} key Key to use when searching the database.
|
93 | * @param {Number} ttl TTL in ms to set for the key.
|
94 | * @options {Object} options
|
95 | * @callback {Function} callback
|
96 | * @param {Error} err Error object.
|
97 | * @promise
|
98 | *
|
99 | * @header KeyValueModel.expire(key, ttl, cb)
|
100 | */
|
101 | static expire(
|
102 | key: string,
|
103 | ttl: number,
|
104 | options?: Options,
|
105 | callback?: Callback<void>,
|
106 | ): PromiseOrVoid<void>;
|
107 |
|
108 | /**
|
109 | * Return the TTL (time to live) for a given key. TTL is the remaining time
|
110 | * before a key-value pair is discarded from the database.
|
111 | *
|
112 | * @param {string} key Key to use when searching the database.
|
113 | * @options {Object} options
|
114 | * @callback {Function} callback
|
115 | * @param {Error} error
|
116 | * @param {Number} ttl Expiration time for the key-value pair. `undefined` if
|
117 | * TTL was not initially set.
|
118 | * @promise
|
119 | *
|
120 | * @header KeyValueModel.ttl(key, cb)
|
121 | */
|
122 | static ttl(
|
123 | key: string,
|
124 | options?: Options,
|
125 | callback?: Callback<number>,
|
126 | ): PromiseOrVoid<number>;
|
127 |
|
128 | /**
|
129 | * Return all keys in the database.
|
130 | *
|
131 | * **WARNING**: This method is not suitable for large data sets as all
|
132 | * key-values pairs are loaded into memory at once. For large data sets,
|
133 | * use `iterateKeys()` instead.
|
134 | *
|
135 | * @param {Object} filter An optional filter object with the following
|
136 | * @param {string} filter.match Glob string used to filter returned
|
137 | * keys (i.e. `userid.*`). All connectors are required to support `*` and
|
138 | * `?`, but may also support additional special characters specific to the
|
139 | * database.
|
140 | * @param {Object} options
|
141 | * @callback {Function} callback
|
142 | * @promise
|
143 | *
|
144 | * @header KeyValueModel.keys(filter, cb)
|
145 | */
|
146 | static keys(
|
147 | filter?: KVFilter,
|
148 | options?: Options,
|
149 | callback?: Callback<string[]>,
|
150 | ): PromiseOrVoid<string[]>;
|
151 |
|
152 | /**
|
153 | * Asynchronously iterate all keys in the database. Similar to `.keys()` but
|
154 | * instead allows for iteration over large data sets without having to load
|
155 | * everything into memory at once.
|
156 | *
|
157 | * Callback example:
|
158 | * ```js
|
159 | * // Given a model named `Color` with two keys `red` and `blue`
|
160 | * var iterator = Color.iterateKeys();
|
161 | * it.next(function(err, key) {
|
162 | * // key contains `red`
|
163 | * it.next(function(err, key) {
|
164 | * // key contains `blue`
|
165 | * });
|
166 | * });
|
167 | * ```
|
168 | *
|
169 | * Promise example:
|
170 | * ```js
|
171 | * // Given a model named `Color` with two keys `red` and `blue`
|
172 | * var iterator = Color.iterateKeys();
|
173 | * Promise.resolve().then(function() {
|
174 | * return it.next();
|
175 | * })
|
176 | * .then(function(key) {
|
177 | * // key contains `red`
|
178 | * return it.next();
|
179 | * });
|
180 | * .then(function(key) {
|
181 | * // key contains `blue`
|
182 | * });
|
183 | * ```
|
184 | *
|
185 | * @param {Object} filter An optional filter object with the following
|
186 | * @param {string} filter.match
|
187 | * @param {Object} options
|
188 | * @returns {AsyncKeyIterator} An Object implementing `next(cb) -> Promise`
|
189 | * function that can be used to iterate all keys.
|
190 | *
|
191 | * @header KeyValueModel.iterateKeys(filter)
|
192 | */
|
193 | static iterateKeys(filter?: KVFilter, options?: Options): AsyncKeyIterator;
|
194 | }
|
195 |
|
196 | export type KVFilter = {
|
197 | /**
|
198 | * Glob string to use to filter returned keys (i.e. `userid.*`). All connectors
|
199 | * are required to support `*` and `?`. They may also support additional special
|
200 | * characters that are specific to the backing database.
|
201 | */
|
202 | match: string;
|
203 | };
|
204 |
|
205 | /**
|
206 | * Async iterator to return keys one by one. The value will be undefined if there is
|
207 | * no more keys
|
208 | */
|
209 | export interface AsyncKeyIterator {
|
210 | /**
|
211 | * Try to fetch the next key
|
212 | * @param callback Callback function. If not provided, the return value will be
|
213 | * a promise
|
214 | */
|
215 | next(
|
216 | callback?: Callback<string | undefined>,
|
217 | ): PromiseOrVoid<string | undefined>;
|
218 | }
|