Skip to content

Commit

Permalink
docs: add missing JSDoc for table API (#1382)
Browse files Browse the repository at this point in the history
  • Loading branch information
@laljikanjareeya
laljikanjareeya committed Jun 3, 2021
1 parent cf4cd54 commit b18be4b
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 @@ -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.
* @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.
* @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.
*/
/**
* @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 @@ -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.
* @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
* 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}
* 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 @@ -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}
* 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 @@ -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}
* 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 @@ -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}
* 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.
* @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 @@ -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.
*/
/**
* Create a readable object stream to receive rows from the database using key
Expand Down

0 comments on commit b18be4b

Please sign in to comment.