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