npm package: @michinded/odbc-orm-js
Description: A lightweight ORM for ODBC databases
Author: michinded
Latest version: 0.1.0-beta.0

# @michinded/odbc-orm-js

A lightweight ORM for ODBC databases written in JavaScript. Manage multiple database connections with a simple, Laravel-inspired configuration system.

## Features

- ✅ **Multiple Database Connections** - Manage multiple ODBC connections with unique aliases
- ✅ **Simple Configuration** - Laravel-style config files with environment variable support
- ✅ **Auto Setup** - Automatically creates configuration files on installation
- ✅ **Singleton Pattern** - Efficient connection management across your application
- ✅ **Well Documented** - Comprehensive JSDoc documentation for all classes and methods

## Installation

```bash
npm install @michinded/odbc-orm-js
```

or with pnpm:

```bash
pnpm add @michinded/odbc-orm-js
```

After installation, the package automatically creates:
- `config/connections.js` - Database connections configuration
- `.env.example` - Environment variables template

## Configuration

### 1. Setup Environment Variables

Copy `.env.example` to `.env` and update with your database credentials:

```env
# .env
DB_PRIMARY_CONNECTION_STRING=DRIVER={ODBC Driver 17 for SQL Server};SERVER=localhost;DATABASE=mydb;UID=user;PWD=password
DB_SECONDARY_CONNECTION_STRING=DRIVER={ODBC Driver 17 for SQL Server};SERVER=localhost;DATABASE=otherdb;UID=user;PWD=password
```

### 2. Configure Connections

Edit `config/connections.js` to define your database connections:

```javascript
require('dotenv').config();

module.exports = {
    // Default connection alias
    default: 'primary',

    // Array of database connections
    connections: [
        {
            alias: 'primary',
            connectionString: process.env.DB_PRIMARY_CONNECTION_STRING,
            options: {}
        },
        {
            alias: 'secondary',
            connectionString: process.env.DB_SECONDARY_CONNECTION_STRING,
            options: {}
        }
    ]
};
```

## Usage

### Basic Usage

```javascript
const { DB } = require('@michinded/odbc-orm-js');

async function example() {
    // Use default connection
    const conn = await DB.connection();
    const result = await conn.query('SELECT * FROM users');
    console.log(result);

    // Close connection when done
    await DB.closeConnection();
}
```

### Using Multiple Connections

```javascript
const { DB } = require('@michinded/odbc-orm-js');

async function multipleConnections() {
    // Connect to primary database
    const primary = await DB.connection('primary');
    const users = await primary.query('SELECT * FROM users');

    // Connect to secondary database
    const secondary = await DB.connection('secondary');
    const products = await secondary.query('SELECT * FROM products');

    // Close specific connection
    await DB.closeConnection('primary');

    // Or close all connections
    await DB.closeConnection();
}
```

### Get Available Connections

```javascript
const { DB } = require('@michinded/odbc-orm-js');

// List all configured connection aliases
const aliases = DB.getAliases();
console.log('Available connections:', aliases);

// Get default connection alias
const defaultAlias = DB.getDefaultAlias();
console.log('Default connection:', defaultAlias);
```

## API Reference

### DB.connection(alias)

Gets a database connection by alias.

- **Parameters:**
  - `alias` (string, optional) - Connection alias. Uses default if not provided.
- **Returns:** Promise<object> - ODBC connection object
- **Throws:** Error if connection alias not found

### DB.closeConnection(alias)

Closes a specific connection or all connections.

- **Parameters:**
  - `alias` (string, optional) - Connection alias. Closes all if not provided.
- **Returns:** Promise<void>

### DB.getAliases()

Gets list of all configured connection aliases.

- **Returns:** Array<string> - Array of connection aliases

### DB.getDefaultAlias()

Gets the default connection alias.

- **Returns:** string|null - Default connection alias

## Examples

Check the `examples/` directory for more usage examples:

```bash
node examples/basic-usage.js
```

## Requirements

- Node.js >= 14.0.0
- ODBC Driver installed on your system

## Project Structure

```
@michinded/odbc-orm-js/
├── src/
│   ├── core/
│   │   ├── Connection.js         # Connection wrapper class
│   │   └── ConnectionManager.js  # Manages multiple connections
│   └── index.js                  # Main entry point
├── stubs/
│   ├── .env.example             # Environment variables template
│   └── connections.js.stub      # Connections config template
├── scripts/
│   └── postinstall.js           # Auto-setup script
└── examples/
    └── basic-usage.js           # Usage examples
```

## License

MIT

## Author

Michinded

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.