Skip to content

Commit

Permalink
docs: add missing JSDoc for table API (googleapis#1382)
Browse files Browse the repository at this point in the history
  • Loading branch information
@laljikanjareeya @AVaksman
laljikanjareeya authored and AVaksman committed Jun 29, 2021
1 parent e63a306 commit 7dc6c0f
Show file tree
Hide file tree
Showing 2 changed files with 176 additions and 49 deletions.
200 changes: 155 additions & 45 deletions src/table.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ class Table {
* Create a table.
*
* @param {string} schema See {@link Database#createTable}.
* @param {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {CreateTableCallback} [callback] Callback function.
* @returns {Promise<CreateTableResponse>}
*
Expand Down Expand Up @@ -180,11 +182,9 @@ class Table {
* @see [StreamingRead API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.StreamingRead)
* @see [ReadRequest API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.ReadRequest)
*
* @param {ReadRequest} query Configuration object. See official
* [`ReadRequest`](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.ReadRequest).
* API documentation.
* @param {ReadRequest} query Configuration object, describing what to read from the table..
* @param {TimestampBounds} [options] [Transaction options](https://cloud.google.com/spanner/docs/timestamp-bounds).
* @returns {ReadableStream}
* @returns {PartialResultStream} A readable stream that emits rows.
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -265,6 +265,19 @@ class Table {
delete(gaxOptions?: CallOptions): Promise<DropTableResponse>;
delete(callback: DropTableCallback): void;
delete(gaxOptions: CallOptions, callback: DropTableCallback): void;
/**
* @typedef {array} DropTableResponse
* @property {Operation} 0 An {@link Operation} object that can be used to check
* the status of the request.
* @property {object} 1 The full API response.
*/
/**
* @callback DropTableCallback
* @param {?Error} err Request error, if any.
* @param {Operation} operation An {@link Operation} object that can be used to
* check the status of the request.
* @param {object} apiResponse The full API response.
*/
/**
* Delete the table. Not to be confused with {@link Table#deleteRows}.
*
Expand All @@ -273,10 +286,10 @@ class Table {
* @see {@link Database#updateSchema}
*
* @throws {TypeError} If any arguments are passed in.
* @param {object} [gaxOptions] Request configuration options, outlined here:
* https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
* @param {LongRunningOperationCallback} [callback] Callback function.
* @returns {Promise<LongRunningOperationResponse>}
* @param {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {DropTableCallback} [callback] Callback function.
* @returns {Promise<DropTableResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -335,6 +348,25 @@ class Table {
options: DeleteRowsOptions | CallOptions,
callback: DeleteRowsCallback
): void;
/**
* @typedef {array} DeleteRowsResponse
* @property {CommitResponse} 0 The commit response.
*/
/**
* @callback DeleteRowsCallback
* @param {?Error} error Request error, if any.
* @param {CommitResponse} apiResponse The full API response.
*/
/**
* @typedef {object} DeleteRowsOptions
* @property {google.spanner.v1.IRequestOptions} requestOptions The request options to include
* with the commit request.
* @property {boolean} returnCommitStats Include statistics related to the
* transaction in the {@link CommitResponse}.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* Delete rows from this table.
*
Expand All @@ -343,9 +375,10 @@ class Table {
* @param {array} keys The keys for the rows to delete. If using a
* composite key, provide an array within this array. See the example
* below.
* @param {DeleteRowsOptions} [options] Options for configuring the request.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
* @param {DeleteRowsOptions|CallOptions} [options] Options for configuring the request.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {DeleteRowsCallback} [callback] Callback function.
* @returns {Promise<DeleteRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -396,16 +429,30 @@ class Table {
drop(gaxOptions?: CallOptions): Promise<DropTableResponse>;
drop(callback: DropTableCallback): void;
drop(gaxOptions: CallOptions, callback: DropTableCallback): void;
/**
* @typedef {array} DropTableResponse
* @property {Operation} 0 An {@link Operation} object that can be used to check
* the status of the request.
* @property {object} 1 The full API response.
*/
/**
* @callback DropTableCallback
* @param {?Error} err Request error, if any.
* @param {Operation} operation An {@link Operation} object that can be used to
* check the status of the request.
* @param {object} apiResponse The full API response.
*/
/**
* Drop the table.
*
* @see {@link Table#delete}
* @see {@link Database#updateSchema}
*
* @param {object} [gaxOptions] Request configuration options, outlined here:
* https://googleapis.github.io/gax-nodejs/classes/CallSettings.html.
* @param {LongRunningOperationCallback} [callback] Callback function.
* @returns {Promise<LongRunningOperationResponse>}
* @param {object} [gaxOptions] Request configuration options.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more
* details.
* @param {DropTableCallback} [callback] Callback function.
* @returns {Promise<DropTableResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -460,16 +507,36 @@ class Table {
options: InsertRowsOptions | CallOptions,
callback: InsertRowsCallback
): void;
/**
* @typedef {array} InsertRowsResponse
* @property {CommitResponse} 0 The commit response.
*/
/**
* @callback InsertRowsCallback
* @param {?Error} error Request error, if any.
* @param {CommitResponse} apiResponse The full API response.
*/
/**
* @typedef {object} InsertRowsOptions
* @property {google.spanner.v1.IRequestOptions} requestOptions The request options to include
* with the commit request.
* @property {boolean} returnCommitStats Include statistics related to the
* transaction in the {@link CommitResponse}.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* Insert rows of data into this table.
*
* @see [Commit API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.Commit)
*
* @param {object|object[]} rows A map of names to values of data to insert
* into this table.
* @param {InsertRowsOptions} [options] Options for configuring the request.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
* @param {InsertRowsOptions|CallOptions} [options] Options for configuring the request.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {InsertRowsCallback} [callback] Callback function.
* @returns {Promise<InsertRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -538,27 +605,10 @@ class Table {
): void;
/**
* Configuration object, describing what to read from the table.
*
* @typedef {object} TableReadRequestOptions
* @property {string[]} columns The columns of the table to be returned for each
* row matching this query.
* @property {string[]|string[][]} keys The primary keys of the rows in this table to be
* yielded. If using a composite key, provide an array within this array.
* See the example below.
* @property {string} [index] The name of an index on the table.
* @property {boolean} [json=false] Receive the rows as serialized objects. This
* is the equivalent of calling `toJSON()` on each row.
* @property {object} [jsonOptions] Configuration options for the serialized
* objects.
* @property {boolean} [jsonOptions.wrapNumbers=false] Protect large integer
* values outside of the range of JavaScript Number.
* @property {object} [keySet] Defines a collection of keys and/or key ranges to
* read.
* @property {number} [limit] The number of rows to yield.
*/
/**
* @typedef {array} TableReadResponse
* @property {array[]} 1 Rows are returned as an array of object arrays. Each
* @property {array[]} 0 Rows are returned as an array of object arrays. Each
* object has a `name` and `value` property. To get a serialized object,
* call `toJSON()`. Optionally, provide an options object to `toJSON()`
* specifying `wrapNumbers: true` to protect large integer values outside
Expand Down Expand Up @@ -717,16 +767,36 @@ class Table {
options: ReplaceRowsOptions | CallOptions,
callback: ReplaceRowsCallback
): void;
/**
* @typedef {array} ReplaceRowsResponse
* @property {CommitResponse} 0 The commit response.
*/
/**
* @callback ReplaceRowsCallback
* @param {?Error} error Request error, if any.
* @param {CommitResponse} apiResponse The full API response.
*/
/**
* @typedef {object} ReplaceRowsOptions
* @property {google.spanner.v1.IRequestOptions} requestOptions The request options to include
* with the commit request.
* @property {boolean} returnCommitStats Include statistics related to the
* transaction in the {@link CommitResponse}.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* Replace rows of data within this table.
*
* @see [Commit API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.Commit)
*
* @param {object|object[]} rows A map of names to values of data to insert
* into this table.
* @param {ReplaceRowsOptions} [options] Options for configuring the request.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
* @param {ReplaceRowsOptions|CallOptions} [options] Options for configuring the request.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {ReplaceRowsCallback} [callback] Callback function.
* @returns {Promise<ReplaceRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -779,16 +849,36 @@ class Table {
options: UpdateRowsOptions | CallOptions,
callback: UpdateRowsCallback
): void;
/**
* @typedef {array} UpdateRowsResponse
* @property {CommitResponse} 0 The commit response.
*/
/**
* @callback UpdateRowsCallback
* @param {?Error} error Request error, if any.
* @param {CommitResponse} apiResponse The full API response.
*/
/**
* @typedef {object} UpdateRowsOptions
* @property {google.spanner.v1.IRequestOptions} requestOptions The request options to include
* with the commit request.
* @property {boolean} returnCommitStats Include statistics related to the
* transaction in the {@link CommitResponse}.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* Update rows of data within this table.
*
* @see [Commit API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.Commit)
*
* @param {object|object[]} rows A map of names to values of data to insert
* into this table.
* @param {UpdateRowsOptions} [options] Options for configuring the request.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
* @param {UpdateRowsOptions|CallOptions} [options] Options for configuring the request.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {UpdateRowsCallback} [callback] Callback function.
* @returns {Promise<UpdateRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -845,6 +935,25 @@ class Table {
options: UpsertRowsOptions | CallOptions,
callback: UpsertRowsCallback
): void;
/**
* @typedef {array} UpsertRowsResponse
* @property {CommitResponse} 0 The commit response.
*/
/**
* @callback UpsertRowsCallback
* @param {?Error} error Request error, if any.
* @param {CommitResponse} apiResponse The full API response.
*/
/**
* @typedef {object} UpsertRowsOptions
* @property {google.spanner.v1.IRequestOptions} requestOptions The request options to include
* with the commit request.
* @property {boolean} returnCommitStats Include statistics related to the
* transaction in the {@link CommitResponse}.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* Insert or update rows of data within this table.
*
Expand All @@ -853,9 +962,10 @@ class Table {
* @param {object|object[]} rows A map of names to values of data to insert
* into this table.
*
* @param {UpsertRowsOptions} [options] Options for configuring the request.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
* @param {UpsertRowsOptions|CallOptions} [options] Options for configuring the request.
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
* @param {UpsertRowsCallback} [callback] Callback function.
* @returns {Promise<UpsertRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down
25 changes: 21 additions & 4 deletions src/transaction.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -412,15 +412,32 @@ export class Snapshot extends EventEmitter {
* @see [ReadRequest API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.ReadRequest)
*
* @typedef {object} ReadRequest
* @property {string[]|string[][]} [keys] The primary keys of the rows in this table to be
* @property {string} table The name of the table in the database to be read.
* @property {string[]} columns The columns of the table to be returned for each
* row matching this query.
* @property {string[]|string[][]} keys The primary or index keys of the rows in this table to be
* yielded. If using a composite key, provide an array within this array.
* See the example below.
* @property {KeyRange[]} [ranges] An alternative to the keys property; this can
* be used to define a range of keys to be yielded.
* be used to define a range of keys to be yielded.
* @property {string} [index] The name of an index on the table if a
* different index than the primary key should be used to determine which rows to return.
* @property {boolean} [json=false] Receive the rows as serialized objects. This
* is the equivalent of calling `toJSON()` on each row.
* @property {JSONOptions} [jsonOptions] Configuration options for the
* serialized objects.
* @property {JSONOptions} [jsonOptions] Configuration options for the serialized
* objects.
* @property {object} [keySet] Defines a collection of keys and/or key ranges to
* read.
* @property {number} [limit] The number of rows to yield.
* @property {Buffer} [partitionToken]
* If present, results will be restricted to the specified partition
* previously created using PartitionRead(). There must be an exact
* match for the values of fields common to this message and the
* PartitionReadRequest message used to create this partition_token.
* @property {google.spanner.v1.RequestOptions} [requestOptions]
* Common options for this request.
* @property {object} [gaxOptions]
* Call options. See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions} for more details.
*/
/**
* Create a readable object stream to receive rows from the database using key
Expand Down

0 comments on commit 7dc6c0f

Please sign in to comment.