Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: add missing JSDoc for table API #1382

Merged
merged 3 commits into from
Jun 3, 2021
Merged

docs: add missing JSDoc for table API #1382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f088bda
docs: missing documentation for table api
May 28, 2021
ff89909
docs: missing documentation for commit options
May 31, 2021
baa16d6
docs: address review comments
Jun 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
200 changes: 155 additions & 45 deletions src/table.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,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.
olavloite marked this conversation as resolved.
Show resolved Hide resolved
* @param {CreateTableCallback} [callback] Callback function.
* @returns {Promise<CreateTableResponse>}
*
Expand Down Expand Up @@ -174,11 +176,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 @@ -259,6 +259,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 @@ -267,10 +280,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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @param {DropTableCallback} [callback] Callback function.
* @returns {Promise<DropTableResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -329,6 +342,25 @@ class Table {
options: DeleteRowsOptions | CallOptions,
callback: DeleteRowsCallback
): void;
/**
* @typedef {array} DeleteRowsResponse
* @property {CommitResponse} 0 The commit response.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
*/
/**
* @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}
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* for more details.
*/
/**
* Delete rows from this table.
*
Expand All @@ -337,9 +369,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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @param {DeleteRowsCallback} [callback] Callback function.
* @returns {Promise<DeleteRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -390,16 +423,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
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* details.
* @param {DropTableCallback} [callback] Callback function.
* @returns {Promise<DropTableResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -454,16 +501,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}
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* 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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @param {InsertRowsCallback} [callback] Callback function.
* @returns {Promise<InsertRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -532,27 +599,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 @@ -711,16 +761,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}
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* 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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @param {ReplaceRowsCallback} [callback] Callback function.
* @returns {Promise<ReplaceRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -773,16 +843,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}
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* 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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @param {UpdateRowsCallback} [callback] Callback function.
* @returns {Promise<UpdateRowsResponse>}
*
* @example
* const {Spanner} = require('@google-cloud/spanner');
Expand Down Expand Up @@ -839,6 +929,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}
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* for more details.
*/
/**
* Insert or update rows of data within this table.
*
Expand All @@ -847,9 +956,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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
* @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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -402,15 +402,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.
laljikanjareeya marked this conversation as resolved.
Show resolved Hide resolved
*/
/**
* Create a readable object stream to receive rows from the database using key
Expand Down