NOS-SQL

A SQL module for IBI Data's Node Starter

Features

• ✅ TypeScript support - Full type definitions included
• ✅ Dual module support - Works with both ES Modules (import) and CommonJS (require)
• ✅ Node.js 20+ - Optimized for modern Node.js with native Promises
• ✅ Automatic data trimming - All returned data has whitespace trimmed
• ✅ Connection pooling - Efficient database connection management
• ✅ Parameter type detection - Automatic SQL parameter type mapping

Requirements

• Node.js 20 or higher

Installation

npm install nos-sql

Usage

This package supports both CommonJS (require) and ES Modules (import) syntax.

ES Modules (import)

import NosSql from 'nos-sql';

const sql = new NosSql({
    database: 'YOUR_DB',
    user: 'YOUR_USER',
    password: 'YOUR_PASSWORD',
    server: 'YOUR_SERVER',
    port: 1203, // must be a number
});

try {
    const results = await sql.storedProcedure('YOUR_PROC', {
        param: 'YOUR_PARAM',
    });
    console.log('DO STUFF', results);
} catch (err) {
    console.log('HANDLE ERRORS', err);
}

CommonJS (require)

const NosSql = require('nos-sql');

const sql = new NosSql({
    database: 'YOUR_DB',
    user: 'YOUR_USER',
    password: 'YOUR_PASSWORD',
    server: 'YOUR_SERVER',
    port: 1203, // must be a number
});

try {
    const results = await sql.storedProcedure('YOUR_PROC', {
        param: 'YOUR_PARAM',
    });
    console.log('DO STUFF', results);
} catch (err) {
    console.log('HANDLE ERRORS', err);
}

TypeScript

import NosSql, { DatabaseConfig } from 'nos-sql';

const config: DatabaseConfig = {
    database: 'YOUR_DB',
    user: 'YOUR_USER',
    password: 'YOUR_PASSWORD',
    server: 'YOUR_SERVER',
    port: 1203, // must be a number
};

const sql = new NosSql(config);

try {
    const results = await sql.storedProcedure('YOUR_PROC', {
        param: 'YOUR_PARAM',
    });
    console.log('Results:', results);
} catch (err) {
    console.error('Error:', err);
}

Methods

storedProcedure(spName [, params, configOverride ])

• Will always return a promise.

• If configOverride object is present, that sql config will take precedence. If not supplied, the default config sql object will be used. It's OK to pass in the new db connection object as the 2nd or 3rd parameter, as long as it's the last one. Feel free to chain together different procedures using different database connections.

Examples

// Basic usage
try {
    const data = await sql.storedProcedure('proc_name', myParameters);
    // Do stuff with data
    console.log(data);
} catch (err) {
    console.error('Error:', err);
}

// With parameters
try {
    const results = await sql.storedProcedure('getUserById', {
        userId: 123
    });
    console.log('User data:', results);
} catch (err) {
    console.error('Failed to get user:', err);
}

query(query, [, params, configOverride])

• Simple query method. Same rules apply as storedProcedure method.

// Simple query
try {
    const results = await sql.query('SELECT * FROM table');
    console.log(results);
} catch (err) {
    console.error('Query failed:', err);
}

// Query with parameters
try {
    const results = await sql.query('SELECT * FROM users WHERE userid = @userid', {
        userid: 'guest',
    });
    console.log('User results:', results);
} catch (err) {
    console.error('User query failed:', err);
}

Extra Methods

close()

• Closes active sql connection. Note that this not necessary in web apps, but can be useful to gracefully exit a script.

try {
    await sql.storedProcedure('some_proc');
    await sql.close();
    console.log('Connection closed successfully');
} catch (err) {
    console.error('Error during operation:', err);
}

NosSql.deepTrim(obj)

• Deep trim an object

const trimmedObj = NosSql.deepTrim(obj);

Development

Prerequisites

• Node.js 20 or higher

Setup

1. Clone the repository
2. Install dependencies: npm install && npm prepare
3. Run tests: npm test
4. Build the project: npm run build

The 'prepare' script initializes Husky git hooks to run tests on each commit.

Available Scripts

• npm test - Run Jest tests with coverage
• npm run build - Build both CommonJS and ES Module versions
• npm run lint - Run ESLint code quality checks
• npm run build:check - TypeScript compilation check without output