Repository navigation
AsyncRowIterator.Class.AsyncRowIterator
tedious-plus / AsyncRowIterator / AsyncRowIterator
Defined in: AsyncRowIterator.ts:68
An async iterator for the result rows of a Tedious Request.
The iterator must be created before the request is executed, so that it does not miss any events of
the request. The request can then be executed, e.g. with connection.execSql().
Usage:
const request = new Tedious.Request("select name from sys.databases", () => {});
const iterator = new AsyncRowIterator(request);
connection.execSql(request);
for await (const row of iterator) {
console.log(row);
}The type declarations of the current Tedious version require a completion callback for the
Request constructor. The dummy callback () => {} in the example above can be omitted once
Tedious makes it optional.
Behavior:
- Each row is delivered as an array of column values (see RowValues).
- Only the first result set of the request is processed. Additional result sets are ignored.
- The rows received from the server are buffered in an internal FIFO. When the FIFO is full, the request is paused until enough rows have been consumed (see AsyncRowIteratorOptions.fifoSize).
- When the request fails, e.g. because of an SQL error, the rows received before the error are delivered
first. Then the error is thrown within the
for awaitloop, i.e. the promise returned bynext()is rejected. - When the
for awaitloop is exited early (bybreak,returnor an exception), the request is canceled. The loop exit waits until the request has completed, so that the connection can be used for the next request immediately afterwards.
Requirements:
The connection options useColumnNames, rowCollectionOnDone and rowCollectionOnRequestCompletion
must not be set. Otherwise the iteration fails with an error.
new AsyncRowIterator(request, options?): AsyncRowIterator;Defined in: AsyncRowIterator.ts:82
Creates a row iterator for a Tedious request.
Request
The Tedious request whose result rows are to be iterated.
Partial<AsyncRowIteratorOptions>
Optional settings for the iterator.
AsyncRowIterator
get fifoRowCount(): number;Defined in: AsyncRowIterator.ts:97
Returns the number of rows that have been received from the server, but not yet delivered by the iterator. These rows are stored in the internal FIFO row buffer.
number
get metadata(): RowMetadata;Defined in: AsyncRowIterator.ts:108
Returns the column metadata of the first result set.
The metadata is guaranteed to be available when the first row is delivered.
Error If the metadata has not yet been received.
get rowCount(): number;Defined in: AsyncRowIterator.ts:90
Returns the number of rows that have been delivered by the iterator so far.
number
asyncDispose: Promise<void>;Defined in: AsyncRowIterator.ts:151
Terminates the iteration. This method is called implicitly at the end of the scope of an
await using declaration.
If the request is still active, it is canceled. The returned promise is resolved when the request
has completed, so that the connection can be used for the next request immediately afterwards.
This has the same effect as exiting a for await loop early.
A request that has not yet been executed is left untouched. If a canceled request does not complete within a safety timeout, the returned promise is resolved anyway. The connection then remains in a non-ready state and the next request on it fails.
Usage:
await using iterator = ConnectionPromises.execSqlIterator(connection, request);
const metadata = await iterator.getMetadata();
...Promise<void>
asyncIterator: AsyncIterator<RowValues>;Defined in: AsyncRowIterator.ts:129
Returns the AsyncIterator for the rows. This method is called implicitly by a for await loop.
The same iterator object is returned on each call.
AsyncIterator<RowValues>
getMetadata(): Promise<RowMetadata>;Defined in: AsyncRowIterator.ts:121
Returns a promise for the column metadata of the first result set.
The returned promise is resolved as soon as the metadata has been received, which is before the first row is delivered. It is rejected if the request completes without producing a result set, e.g. because of an error, because the SQL statement does not produce a result set, or because the iteration has been terminated early.
Promise<RowMetadata>