YDbClient

YDbClient is a robust and intuitive database client for managing and executing SQL queries efficiently. It provides streamlined methods to perform operations while maintaining flexibility and error handling capabilities.

Features

• Execute complex SQL queries with ease.
• Built-in error handling for database operations.
• Supports query parameterization to prevent SQL injection.
• Dedicated methods for executing single-row and limited-result queries.
• Optimized for both CommonJS (CJS) and ECMAScript Modules (ESM).

Installation

To install the package, use the following commands:

# Using npm
npm install ydb-client

# Using yarn
yarn add ydb-client

Usage

Importing the Module

CommonJS

const { connect } = require("ydb-client");

ES Modules

import { connect } from "ydb-client";

Quick Start

Creating a Connection

const accessToken = "your-access-token";
const db = connect(accessToken);

Executing Queries

Execute a SQL Query

(async () => {
  try {
    const result = await db.execute("SELECT * FROM users");
    console.log(result.rows);
  } catch (error) {
    console.error(error.message);
  }
})();

Execute a Parameterized Query

(async () => {
  try {
    const result = await db.execute("SELECT * FROM users WHERE id = ?", [1]);
    console.log(result.rows);
  } catch (error) {
    console.error(error.message);
  }
})();

Get a Single Row

(async () => {
  try {
    const result = await db.getSingle("SELECT * FROM users WHERE id = ?", [1]);
    console.log(result.row);
  } catch (error) {
    console.error(error.message);
  }
})();

Get Results with a Limit

(async () => {
  try {
    const result = await db.getWithLimit("SELECT * FROM users", 10);
    console.log(result.rows);
  } catch (error) {
    console.error(error.message);
  }
})();

API Reference

connect(accessToken: string): connection

Establishes a connection to the database client.

Parameters

• accessToken (string): Your authentication token for accessing the database.

Returns

• connection: An instance of the database client.

Class: YDbClient

Properties

• execute: Executes a SQL query.
• getSingle: Executes a SQL query and returns a single row.
• getWithLimit: Executes a SQL query with a specified row limit.

Methods

execute<T>(sql: string, values?: any[]): Promise<queryResponse<T>>

Executes a SQL query with optional parameterized values.

Parameters

• sql (string): The SQL query string.
• values (array, optional): An array of values to parameterize the query.

Returns

• Promise<queryResponse<T>>: The result of the query execution.

getSingle<T>(sql: string, values?: any[]): Promise<dataResponse<T>>

Executes a SELECT query and ensures the result contains a single row.

Parameters

• sql (string): The SQL query string. Only SELECT statements are allowed.
• values (array, optional): An array of values to parameterize the query.

Throws

• YdbError if the query is not a SELECT statement.

Returns

• Promise<dataResponse<T>>: The result containing a single row.

getWithLimit<T>(sql: string, values?: any[], limit?: number): Promise<queryResponse<T>>

Executes a SELECT query with a limit on the number of rows returned.

Parameters

• sql (string): The SQL query string. Only SELECT statements are allowed.
• values (array, optional): An array of values to parameterize the query.
• limit (number, optional): The maximum number of rows to retrieve (default is 1000).

Throws

• YdbError if the query is not a SELECT statement.
• YdbError if the limit exceeds 100,000 rows.

Returns

• Promise<queryResponse<T>>: The result containing limited rows.

Interfaces

connection

An alias for the YDbClient instance.

queryResponse<T>

Represents the response of a successful database query.

Properties

• rows (array): The result rows.
• fields (array): Metadata about the result fields.
• rowCount (number): The total number of rows returned.
• affectedRows (number): The number of rows affected by the query.
• insertId (number): The ID of the last inserted row (for INSERT queries).

errorResponse

Represents the structure of an error response from the database.

Properties

• success (boolean): Indicates if the operation was successful.
• message (string): A descriptive error message.
• code (string): The error code.
• errno (string): The error number.
• sql (string): The SQL query that caused the error.
• sqlMessage (string): The database's error message.

Error Handling

The YdbError class extends the built-in Error class and provides additional information about database-related errors.

License

YDbClient is licensed under the MIT License. See the LICENSE file for details.