Skip to content

About

Promises, AsyncIterator, data export and conveniences for Tedious.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

tedious-plus

This package provides promises, an AsyncIterator, data export and conveniences for Tedious, the SQL Server driver for Node.js.

This is an unofficial add-on package. It is not affiliated with the Tedious project.

NPM package: tedious-plus
Status: Early version. The API is incomplete and may change.
Requirements: Node.js 26.8 or later.

Features

Implemented so far:

  • ConnectionPlus: A wrapper class for a Tedious connection with promise-based methods:
    • execSql() for SQL code that does not return a result set.
    • query(), queryRows() and queryScalar() for queries whose result is buffered in memory.
    • queryIterator() for processing large result sets row by row with a for await loop.
    • exportQuery() for exporting a query result into a JSON Lines (JSONL) file or into an entry of a ZIP archive.
  • SQL parameters: Parameters can be passed as an object (e.g. {params: {id: 123}}) or as an array of values. The SQL data types are derived from the values. Alternatively, full parameter definitions with explicit data types can be passed.
  • Row formats: Result rows can be returned as objects, arrays, Maps or in the original Tedious format.
  • ConnectionPromises: Promisified versions of the Tedious Connection methods connect(), close(), execSql() and execSqlBatch().
  • Support for await using declarations, to close connections and terminate iterations automatically.

Planned:

  • Promisified versions of the remaining database operations that a typical application needs.
  • Import of exported data.
  • More utility and convenience functions.
  • A connection pool.

Usage

import {type ConnectionConfiguration} from "tedious";
import {ConnectionPlus} from "tedious-plus";

const connectionConfig: ConnectionConfiguration = {
   server: "localhost",
   authentication: {
      type: "default",
      options: {userName: "myUser", password: "myPassword"}
   },
   options: {database: "myDatabase"}
};

await using conn = new ConnectionPlus(connectionConfig);
await conn.open();
const iterator = conn.queryIterator("select name from sys.databases");
for await (const row of iterator) {
   console.log(row);
}

SQL parameters and a single result value:

await conn.execSql("insert into t1 (id, name) values (@id, @name)",
   {params: {id: 123, name: "abc"}});
const name = await conn.queryScalar("select name from t1 where id = @id",
   {params: {id: 123}, dataType: "string"});

Export of a query result into a JSONL file:

const rowCount = await conn.exportQuery("select * from t1",
   {output: {type: "file", path: "t1.jsonl"}});

More examples can be found in the examples directory.

Modules

Module Description
AsyncRowIterator This module provides an AsyncIterator for reading the result rows of a Tedious Request.
ConnectionPlus This module provides an enhanced Connection for communicating with the database server.
ConnectionPromises Promisified wrappers for the methods of the Tedious Connection class.
export/ExportMain Main module for database data export. It provides the export options and the main export function.
Index Main package exports.
utils/TediousUtils Types and utility functions for result set rows, metadata, value data types and SQL parameters.
utils/Utils General utilities for this package.

Implementation notes

  • AsyncRowIterator: Reads the result rows of a Tedious Request with a for await loop. The request is paused when the rows are processed more slowly than they arrive, and canceled when the loop is exited early.
  • A fatal connection error does not crash the process, even when the application has not registered an error listener.

API layers:

The API of this package is organized in layers. Each layer builds on the layer below it. The layers can be combined, and the Tedious API can still be used directly where needed.

  • ConnectionPlus (highest layer): A class that wraps a Tedious connection and provides convenient methods. Most applications will only need this layer.
  • ConnectionPromises: Promisified functions for a Tedious Connection, e.g. connect(), execSql() and execSqlIterator(). They take Tedious Connection and Request objects as parameters.
  • AsyncRowIterator (lowest layer): An AsyncIterator for the result rows of a Tedious Request.

About

Promises, AsyncIterator, data export and conveniences for Tedious.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages