1 | /// <reference types="node" />
|
2 | import { Query, QueryProto, IntegerTypeCastOptions } from './query';
|
3 | import { PathType } from '.';
|
4 | import { protobuf as Protobuf } from 'google-gax';
|
5 | import { google } from '../protos/protos';
|
6 | export declare namespace entity {
|
7 | interface InvalidKeyErrorOptions {
|
8 | code: string;
|
9 | }
|
10 | class InvalidKeyError extends Error {
|
11 | constructor(opts: InvalidKeyErrorOptions);
|
12 | }
|
13 | /**
|
14 | * A symbol to access the Key object from an entity object.
|
15 | *
|
16 | * @type {symbol}
|
17 | *
|
18 | */
|
19 | const KEY_SYMBOL: unique symbol;
|
20 | /**
|
21 | * Build a Datastore Double object. For long doubles, a string can be
|
22 | * provided.
|
23 | *
|
24 | * @class
|
25 | * @param {number} value The double value.
|
26 | *
|
27 | * @example
|
28 | * const {Datastore} = require('@google-cloud/datastore');
|
29 | * const datastore = new Datastore();
|
30 | * const aDouble = datastore.double(7.3);
|
31 | */
|
32 | class Double {
|
33 | type: string;
|
34 | value: number;
|
35 | constructor(value: number);
|
36 | }
|
37 | /**
|
38 | * Check if something is a Datastore Double object.
|
39 | *
|
40 | * @private
|
41 | * @param {*} value
|
42 | * boolean}
{ |
43 | */
|
44 | function isDsDouble(value?: {}): value is entity.Double;
|
45 | /**
|
46 | * Check if a value is a Datastore Double object converted from JSON.
|
47 | *
|
48 | * @private
|
49 | * @param {*} value
|
50 | * @returns {boolean}
|
51 | */
|
52 | function isDsDoubleLike(value: unknown): boolean;
|
53 | /**
|
54 | * Build a Datastore Int object. For long integers, a string can be provided.
|
55 | *
|
56 | * @class
|
57 | * @param {number|string} value The integer value.
|
58 | * @param {object} [typeCastOptions] Configuration to convert
|
59 | * values of `integerValue` type to a custom value. Must provide an
|
60 | * `integerTypeCastFunction` to handle `integerValue` conversion.
|
61 | * @param {function} typeCastOptions.integerTypeCastFunction A custom user
|
62 | * provided function to convert `integerValue`.
|
63 | * @param {sting|string[]} [typeCastOptions.properties] `Entity` property
|
64 | * names to be converted using `integerTypeCastFunction`.
|
65 | *
|
66 | * @example
|
67 | * const {Datastore} = require('@google-cloud/datastore');
|
68 | * const datastore = new Datastore();
|
69 | * const anInt = datastore.int(7);
|
70 | */
|
71 | class Int extends Number {
|
72 | type: string;
|
73 | value: string;
|
74 | typeCastFunction?: Function;
|
75 | typeCastProperties?: string[];
|
76 | private _entityPropertyName;
|
77 | constructor(value: number | string | ValueProto, typeCastOptions?: IntegerTypeCastOptions);
|
78 | valueOf(): any;
|
79 | toJSON(): Json;
|
80 | }
|
81 | /**
|
82 | * Check if something is a Datastore Int object.
|
83 | *
|
84 | * @private
|
85 | * @param {*} value
|
86 | * boolean}
{ |
87 | */
|
88 | function isDsInt(value?: {}): value is entity.Int;
|
89 | /**
|
90 | * Check if a value is a Datastore Int object converted from JSON.
|
91 | *
|
92 | * @private
|
93 | * @param {*} value
|
94 | * @returns {boolean}
|
95 | */
|
96 | function isDsIntLike(value: unknown): boolean;
|
97 | interface Coordinates {
|
98 | latitude: number;
|
99 | longitude: number;
|
100 | }
|
101 | /**
|
102 | * Build a Datastore Geo Point object.
|
103 | *
|
104 | * @class
|
105 | * @param {object} coordinates Coordinate value.
|
106 | * @param {number} coordinates.latitude Latitudinal value.
|
107 | * @param {number} coordinates.longitude Longitudinal value.
|
108 | *
|
109 | * @example
|
110 | * const {Datastore} = require('@google-cloud/datastore');
|
111 | * const datastore = new Datastore();
|
112 | * const coordinates = {
|
113 | * latitude: 40.6894,
|
114 | * longitude: -74.0447
|
115 | * };
|
116 | *
|
117 | * const geoPoint = datastore.geoPoint(coordinates);
|
118 | */
|
119 | class GeoPoint {
|
120 | value: Coordinates;
|
121 | constructor(coordinates: Coordinates);
|
122 | }
|
123 | /**
|
124 | * Check if something is a Datastore Geo Point object.
|
125 | *
|
126 | * @private
|
127 | * @param {*} value
|
128 | * boolean}
{ |
129 | */
|
130 | function isDsGeoPoint(value?: {}): value is entity.GeoPoint;
|
131 | interface KeyOptions {
|
132 | namespace?: string;
|
133 | path: PathType[];
|
134 | }
|
135 | /**
|
136 | * Build a Datastore Key object.
|
137 | *
|
138 | * @class
|
139 | * @param {object} options Configuration object.
|
140 | * @param {array} options.path Key path.
|
141 | * @param {string} [options.namespace] Optional namespace.
|
142 | *
|
143 | * @example
|
144 | * //-
|
145 | * // Create an incomplete key with a kind value of `Company`.
|
146 | * //-
|
147 | * const {Datastore} = require('@google-cloud/datastore');
|
148 | * const datastore = new Datastore();
|
149 | * const key = datastore.key('Company');
|
150 | *
|
151 | * @example
|
152 | * //-
|
153 | * // Create a complete key with a kind value of `Company` and id`123`.
|
154 | * //-
|
155 | * const {Datastore} = require('@google-cloud/datastore');
|
156 | * const datastore = new Datastore();
|
157 | * const key = datastore.key(['Company', 123]);
|
158 | *
|
159 | * @example
|
160 | * //-
|
161 | * // If the ID integer is outside the bounds of a JavaScript Number
|
162 | * // object, create an Int.
|
163 | * //-
|
164 | * const {Datastore} = require('@google-cloud/datastore');
|
165 | * const datastore = new Datastore();
|
166 | * const key = datastore.key([
|
167 | * 'Company',
|
168 | * datastore.int('100000000000001234')
|
169 | * ]);
|
170 | *
|
171 | * @example
|
172 | * const {Datastore} = require('@google-cloud/datastore');
|
173 | * const datastore = new Datastore();
|
174 | * // Create a complete key with a kind value of `Company` and name `Google`.
|
175 | * // Note: `id` is used for numeric identifiers and `name` is used otherwise.
|
176 | * const key = datastore.key(['Company', 'Google']);
|
177 | *
|
178 | * @example
|
179 | * //-
|
180 | * // Create a complete key from a provided namespace and path.
|
181 | * //-
|
182 | * const {Datastore} = require('@google-cloud/datastore');
|
183 | * const datastore = new Datastore();
|
184 | * const key = datastore.key({
|
185 | * namespace: 'My-NS',
|
186 | * path: ['Company', 123]
|
187 | * });
|
188 | *
|
189 | * @example <caption>Serialize the key for later re-use.</caption>
|
190 | * const {Datastore} = require('@google-cloud/datastore');
|
191 | * const datastore = new Datastore();
|
192 | * const key = datastore.key({
|
193 | * namespace: 'My-NS',
|
194 | * path: ['Company', 123]
|
195 | * });
|
196 | * // Later...
|
197 | * const key = datastore.key(key.serialized);
|
198 | */
|
199 | class Key {
|
200 | namespace?: string;
|
201 | id?: string;
|
202 | name?: string;
|
203 | kind: string;
|
204 | parent?: Key;
|
205 | path: Array<string | number>;
|
206 | constructor(options: KeyOptions);
|
207 | /**
|
208 | * Access the `serialized` property for a library-compatible way to re-use a
|
209 | * key.
|
210 | *
|
211 | * @returns {object}
|
212 | *
|
213 | *
|
214 | * const key = datastore.key({
|
215 | * namespace: 'My-NS',
|
216 | * path: ['Company', 123]
|
217 | * });
|
218 | *
|
219 | * // Later...
|
220 | * const key = datastore.key(key.serialized);
|
221 | */
|
222 | get serialized(): {
|
223 | namespace: string | undefined;
|
224 | path: (string | Int)[];
|
225 | };
|
226 | }
|
227 | /**
|
228 | * Check if something is a Datastore Key object.
|
229 | *
|
230 | * @private
|
231 | * @param {*} value
|
232 | * @returns {boolean}
|
233 | */
|
234 | function isDsKey(value?: {}): value is entity.Key;
|
235 | /**
|
236 | * @typedef {object} IntegerTypeCastOptions Configuration to convert
|
237 | * values of `integerValue` type to a custom value. Must provide an
|
238 | * `integerTypeCastFunction` to handle `integerValue` conversion.
|
239 | * @property {function} integerTypeCastFunction A custom user
|
240 | * provided function to convert `integerValue`.
|
241 | * @property {string | string[]} [properties] `Entity` property
|
242 | * names to be converted using `integerTypeCastFunction`.
|
243 | */
|
244 | /**
|
245 | * Convert a protobuf Value message to its native value.
|
246 | *
|
247 | * @private
|
248 | * @param {object} valueProto The protobuf Value message to convert.
|
249 | * @param {boolean | IntegerTypeCastOptions} [wrapNumbers=false] Wrap values of integerValue type in
|
250 | * {@link Datastore#Int} objects.
|
251 | * If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
|
252 | * If an `object`, this will return a value returned by
|
253 | * `wrapNumbers.integerTypeCastFunction`.
|
254 | * Please see {@link IntegerTypeCastOptions} for options descriptions.
|
255 | * @returns {*}
|
256 | *
|
257 | * @example
|
258 | * decodeValueProto({
|
259 | * booleanValue: false
|
260 | * });
|
261 | * // false
|
262 | *
|
263 | * decodeValueProto({
|
264 | * stringValue: 'Hi'
|
265 | * });
|
266 | * // 'Hi'
|
267 | *
|
268 | * decodeValueProto({
|
269 | * blobValue: Buffer.from('68656c6c6f')
|
270 | * });
|
271 | * // <Buffer 68 65 6c 6c 6f>
|
272 | */
|
273 | function decodeValueProto(valueProto: ValueProto, wrapNumbers?: boolean | IntegerTypeCastOptions): any;
|
274 | /**
|
275 | * Convert any native value to a protobuf Value message object.
|
276 | *
|
277 | * @private
|
278 | * @param {*} value Native value.
|
279 | * @returns {object}
|
280 | *
|
281 | * @example
|
282 | * encodeValue('Hi');
|
283 | * // {
|
284 | * // stringValue: 'Hi'
|
285 | * // }
|
286 | */
|
287 | function encodeValue(value: any, property: string): ValueProto;
|
288 | /**
|
289 | * Convert any entity protocol to a plain object.
|
290 | *
|
291 | * @todo Use registered metadata if provided.
|
292 | *
|
293 | * @private
|
294 | * @param {object} entityProto The protocol entity object to convert.
|
295 | * @param {boolean | IntegerTypeCastOptions} [wrapNumbers=false] Wrap values of integerValue type in
|
296 | * {@link Datastore#Int} objects.
|
297 | * If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
|
298 | * If an `object`, this will return a value returned by
|
299 | * `wrapNumbers.integerTypeCastFunction`.
|
300 | * Please see {@link IntegerTypeCastOptions} for options descriptions.
|
301 | * @returns {object}
|
302 | *
|
303 | * @example
|
304 | * entityFromEntityProto({
|
305 | * properties: {
|
306 | * map: {
|
307 | * name: {
|
308 | * value: {
|
309 | * valueType: 'stringValue',
|
310 | * stringValue: 'Stephen'
|
311 | * }
|
312 | * }
|
313 | * }
|
314 | * }
|
315 | * });
|
316 | * // {
|
317 | * // name: 'Stephen'
|
318 | * // }
|
319 | */
|
320 | function entityFromEntityProto(entityProto: EntityProto, wrapNumbers?: boolean | IntegerTypeCastOptions): any;
|
321 | /**
|
322 | * Convert an entity object to an entity protocol object.
|
323 | *
|
324 | * @private
|
325 | * @param {object} entityObject The entity object to convert.
|
326 | * @returns {object}
|
327 | *
|
328 | * @example
|
329 | * entityToEntityProto({
|
330 | * excludeFromIndexes: [
|
331 | * 'name'
|
332 | * ],
|
333 | * data: {
|
334 | * name: 'Burcu',
|
335 | * legit: true
|
336 | * }
|
337 | * });
|
338 | * // {
|
339 | * // key: null,
|
340 | * // properties: {
|
341 | * // name: {
|
342 | * // stringValue: 'Burcu'
|
343 | * // excludeFromIndexes: true
|
344 | * // },
|
345 | * // legit: {
|
346 | * // booleanValue: true
|
347 | * // }
|
348 | * // }
|
349 | * // }
|
350 | */
|
351 | function entityToEntityProto(entityObject: EntityObject): EntityProto;
|
352 | /**
|
353 | * Convert an API response array to a qualified Key and data object.
|
354 | *
|
355 | * @private
|
356 | * @param {object[]} results The response array.
|
357 | * @param {object} results.entity An entity object.
|
358 | * @param {object} results.entity.key The entity's key.
|
359 | * @param {boolean | IntegerTypeCastOptions} [wrapNumbers=false] Wrap values of integerValue type in
|
360 | * {@link Datastore#Int} objects.
|
361 | * If a `boolean`, this will wrap values in {@link Datastore#Int} objects.
|
362 | * If an `object`, this will return a value returned by
|
363 | * `wrapNumbers.integerTypeCastFunction`.
|
364 | * Please see {@link IntegerTypeCastOptions} for options descriptions.
|
365 | *
|
366 | * @example
|
367 | * request_('runQuery', {}, (err, response) => {
|
368 | * const entityObjects = formatArray(response.batch.entityResults);
|
369 | * // {
|
370 | * // key: {},
|
371 | * // data: {
|
372 | * // fieldName: 'value'
|
373 | * // }
|
374 | * // }
|
375 | * //
|
376 | * });
|
377 | */
|
378 | function formatArray(results: ResponseResult[], wrapNumbers?: boolean | IntegerTypeCastOptions): any[];
|
379 | /**
|
380 | * Find the properties which value size is large than 1500 bytes,
|
381 | * with excludeLargeProperties enabled, automatically exclude properties from indexing.
|
382 | * This will allow storing string values larger than 1500 bytes
|
383 | *
|
384 | * @param entities Datastore key object(s).
|
385 | * @param path namespace of provided entity properties
|
386 | * @param properties properties which value size is large than 1500 bytes
|
387 | */
|
388 | function findLargeProperties_(entities: Entities, path: string, properties?: string[]): string[];
|
389 | /**
|
390 | * Check if a key is complete.
|
391 | *
|
392 | * @private
|
393 | * @param {Key} key The Key object.
|
394 | * @returns {boolean}
|
395 | *
|
396 | * @example
|
397 | * isKeyComplete(new Key(['Company', 'Google'])); // true
|
398 | * isKeyComplete(new Key('Company')); // false
|
399 | */
|
400 | function isKeyComplete(key: Key): boolean;
|
401 | /**
|
402 | * Convert a key protocol object to a Key object.
|
403 | *
|
404 | * @private
|
405 | * @param {object} keyProto The key protocol object to convert.
|
406 | * @returns {Key}
|
407 | *
|
408 | * @example
|
409 | * const key = keyFromKeyProto({
|
410 | * partitionId: {
|
411 | * projectId: 'project-id',
|
412 | * namespaceId: ''
|
413 | * },
|
414 | * path: [
|
415 | * {
|
416 | * kind: 'Kind',
|
417 | * id: '4790047639339008'
|
418 | * }
|
419 | * ]
|
420 | * });
|
421 | */
|
422 | function keyFromKeyProto(keyProto: KeyProto): Key;
|
423 | /**
|
424 | * Convert a Key object to a key protocol object.
|
425 | *
|
426 | * @private
|
427 | * @param {Key} key The Key object to convert.
|
428 | * @returns {object}
|
429 | *
|
430 | * @example
|
431 | * const keyProto = keyToKeyProto(new Key(['Company', 1]));
|
432 | * // {
|
433 | * // path: [
|
434 | * // {
|
435 | * // kind: 'Company',
|
436 | * // id: 1
|
437 | * // }
|
438 | * // ]
|
439 | * // }
|
440 | */
|
441 | function keyToKeyProto(key: Key): KeyProto;
|
442 | /**
|
443 | * Convert a query object to a query protocol object.
|
444 | *
|
445 | * @private
|
446 | * @param {object} q The query object to convert.
|
447 | * @returns {object}
|
448 | *
|
449 | * @example
|
450 | * queryToQueryProto({
|
451 | * namespace: '',
|
452 | * kinds: [
|
453 | * 'Kind'
|
454 | * ],
|
455 | * filters: [],
|
456 | * orders: [],
|
457 | * groupByVal: [],
|
458 | * selectVal: [],
|
459 | * startVal: null,
|
460 | * endVal: null,
|
461 | * limitVal: -1,
|
462 | * offsetVal: -1
|
463 | * });
|
464 | * // {
|
465 | * // projection: [],
|
466 | * // kinds: [
|
467 | * // {
|
468 | * // name: 'Kind'
|
469 | * // }
|
470 | * // ],
|
471 | * // order: [],
|
472 | * // groupBy: []
|
473 | * // }
|
474 | */
|
475 | function queryToQueryProto(query: Query): QueryProto;
|
476 | /**
|
477 | * URL safe key encoding and decoding helper utility.
|
478 | *
|
479 | * This is intended to work with the "legacy" representation of a
|
480 | * datastore "Key" used within Google App Engine (a so-called "Reference").
|
481 | *
|
482 | * @private
|
483 | * @class
|
484 | */
|
485 | class URLSafeKey {
|
486 | protos: any;
|
487 | constructor();
|
488 | /**
|
489 | * Load AppEngine protobuf file.
|
490 | *
|
491 | * @private
|
492 | */
|
493 | loadProtos_(): {
|
494 | [k: string]: Protobuf.ReflectionObject;
|
495 | } | undefined;
|
496 | /**
|
497 | * Convert key to url safe base64 encoded string.
|
498 | *
|
499 | * @private
|
500 | * @param {string} projectId Project Id.
|
501 | * @param {entity.Key} key Entity key object.
|
502 | * @param {string} locationPrefix Optional .
|
503 | * The location prefix of an App Engine project ID.
|
504 | * Often this value is 's~', but may also be 'e~', or other location prefixes
|
505 | * currently unknown.
|
506 | * @returns {string} base64 endocded urlsafe key.
|
507 | */
|
508 | legacyEncode(projectId: string, key: entity.Key, locationPrefix?: string): string;
|
509 | /**
|
510 | * Helper to convert URL safe key string to entity key object
|
511 | *
|
512 | * This is intended to work with the "legacy" representation of a
|
513 | * datastore "Key" used within Google App Engine (a so-called "Reference").
|
514 | *
|
515 | * @private
|
516 | * @param {entity.Key} key Entity key object.
|
517 | * @param {string} locationPrefix Optional .
|
518 | * The location prefix of an App Engine project ID.
|
519 | * Often this value is 's~', but may also be 'e~', or other location prefixes
|
520 | * currently unknown.
|
521 | * @returns {string} Created urlsafe key.
|
522 | */
|
523 | legacyDecode(key: string): entity.Key;
|
524 | /**
|
525 | * Convert buffer to base64 encoding.
|
526 | *
|
527 | * @private
|
528 | * @param {Buffer} buffer
|
529 | * @returns {string} Base64 encoded string.
|
530 | */
|
531 | convertToBase64_(buffer: Buffer): string;
|
532 | /**
|
533 | * Rebuild base64 from encoded url safe string and convert to buffer.
|
534 | *
|
535 | * @private
|
536 | * @param {string} val Encoded url safe string.
|
537 | * @returns {string} Base64 encoded string.
|
538 | */
|
539 | convertToBuffer_(val: string): Buffer;
|
540 | }
|
541 | }
|
542 | export interface ValueProto {
|
543 | [index: string]: any;
|
544 | valueType?: string;
|
545 | values?: ValueProto[];
|
546 | value?: any;
|
547 | propertyName?: string;
|
548 | }
|
549 | export interface EntityProto {
|
550 | key?: KeyProto | null;
|
551 | properties?: {
|
552 | [k: string]: ValueProto;
|
553 | };
|
554 | excludeFromIndexes?: boolean;
|
555 | }
|
556 | export declare type Entity = any;
|
557 | export declare type Entities = Entity | Entity[];
|
558 | interface KeyProtoPathElement extends google.datastore.v1.Key.IPathElement {
|
559 | [index: string]: any;
|
560 | idType?: string;
|
561 | }
|
562 | export interface KeyProto {
|
563 | partitionId?: google.datastore.v1.IPartitionId | null;
|
564 | path?: KeyProtoPathElement[] | null;
|
565 | }
|
566 | export interface ResponseResult {
|
567 | entity: EntityProto;
|
568 | }
|
569 | export interface EntityObject {
|
570 | data: {
|
571 | [k: string]: Entity;
|
572 | };
|
573 | excludeFromIndexes: string[];
|
574 | }
|
575 | export interface Json {
|
576 | [field: string]: string;
|
577 | }
|
578 | export {};
|