@mimersql/node-mimer 1.0.0

package/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * node-mimer - Node.js bindings for Mimer SQL
+ */
+
+export interface ConnectOptions {
+  /** Database name */
+  dsn: string;
+  /** Username */
+  user: string;
+  /** Password */
+  password: string;
+}
+
+export interface PoolOptions extends ConnectOptions {
+  /** Maximum number of connections (default 10) */
+  max?: number;
+  /** Milliseconds before an idle connection is closed (default 30000) */
+  idleTimeout?: number;
+  /** Milliseconds to wait for a connection when pool is full (default 5000) */
+  acquireTimeout?: number;
+}
+
+export interface FieldInfo {
+  /** Column name */
+  name: string;
+  /** Numeric Mimer type code */
+  dataTypeCode: number;
+  /** Human-readable SQL type name (e.g. "INTEGER", "NVARCHAR") */
+  dataTypeName: string;
+  /** Whether the column allows NULL values */
+  nullable: boolean;
+}
+
+export interface QueryResult {
+  /** Array of row objects (SELECT only) */
+  rows?: Record<string, any>[];
+  /** Number of rows returned or affected */
+  rowCount: number;
+  /** Column metadata (SELECT only) */
+  fields?: FieldInfo[];
+}
+
+export class MimerClient {
+  /** Whether the client is currently connected */
+  connected: boolean;
+
+  /** Connect to a Mimer SQL database */
+  connect(options: ConnectOptions): Promise<void>;
+
+  /** Execute a SQL statement with optional parameter binding */
+  query(sql: string, params?: any[]): Promise<QueryResult>;
+
+  /** Prepare a SQL statement for repeated execution */
+  prepare(sql: string): Promise<PreparedStatement>;
+
+  /** Execute a SELECT and return a cursor for row-at-a-time streaming */
+  queryCursor(sql: string, params?: any[]): Promise<ResultSet>;
+
+  /** Begin a new transaction */
+  beginTransaction(): Promise<void>;
+
+  /** Commit the current transaction */
+  commit(): Promise<void>;
+
+  /** Rollback the current transaction */
+  rollback(): Promise<void>;
+
+  /** Close the database connection */
+  close(): Promise<void>;
+
+  /** Check if connected to database */
+  isConnected(): boolean;
+}
+
+export class PreparedStatement {
+  /** Execute the prepared statement with parameter values */
+  execute(params?: any[]): Promise<QueryResult>;
+
+  /** Close the prepared statement and release resources */
+  close(): Promise<void>;
+}
+
+export class ResultSet {
+  /** Column metadata array */
+  readonly fields: FieldInfo[];
+
+  /** Fetch the next row, or null when exhausted */
+  next(): Promise<Record<string, any> | null>;
+
+  /** Close the cursor and release resources */
+  close(): Promise<void>;
+
+  /** Async iterator for for-await-of */
+  [Symbol.asyncIterator](): AsyncIterableIterator<Record<string, any>>;
+}
+
+export class Pool {
+  /** Total number of connections (idle + active) */
+  readonly totalCount: number;
+
+  /** Number of idle connections */
+  readonly idleCount: number;
+
+  /** Number of checked-out connections */
+  readonly activeCount: number;
+
+  /** Number of callers waiting for a connection */
+  readonly waitingCount: number;
+
+  /** Acquire a connection, execute the query, and release */
+  query(sql: string, params?: any[]): Promise<QueryResult>;
+
+  /** Acquire a connection and open a cursor (auto-released on close) */
+  queryCursor(sql: string, params?: any[]): Promise<ResultSet>;
+
+  /** Check out a connection for multiple operations */
+  connect(): Promise<PoolClient>;
+
+  /** Close all connections and shut down the pool */
+  end(): Promise<void>;
+}
+
+export class PoolClient {
+  /** Execute a SQL statement */
+  query(sql: string, params?: any[]): Promise<QueryResult>;
+
+  /** Open a cursor for row-at-a-time streaming */
+  queryCursor(sql: string, params?: any[]): Promise<ResultSet>;
+
+  /** Prepare a SQL statement */
+  prepare(sql: string): Promise<PreparedStatement>;
+
+  /** Begin a new transaction */
+  beginTransaction(): Promise<void>;
+
+  /** Commit the current transaction */
+  commit(): Promise<void>;
+
+  /** Rollback the current transaction */
+  rollback(): Promise<void>;
+
+  /** Return the connection to the pool */
+  release(): void;
+}
+
+/** Create and connect a new MimerClient */
+export function connect(options: ConnectOptions): Promise<MimerClient>;
+
+/** Create a new connection pool */
+export function createPool(options: PoolOptions): Pool;
+
+/** Native addon version string */
+export const version: string;

package/index.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Mimer Information Technology
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// See license for more details.
+
+/**
+ * node-mimer - Node.js bindings for Mimer SQL
+ *
+ * This module provides a JavaScript interface to the native Mimer API bindings.
+ */
+
+const mimer = require('./lib/native');
+const { MimerClient, connect } = require('./lib/client');
+const { PreparedStatement } = require('./lib/prepared');
+const { ResultSet } = require('./lib/resultset');
+const { Pool, PoolClient } = require('./lib/pool');
+
+function createPool(options) {
+  return new Pool(options);
+}
+
+module.exports = {
+  MimerClient,
+  PreparedStatement,
+  ResultSet,
+  Pool,
+  PoolClient,
+  connect,
+  createPool,
+  version: mimer.version,
+};

package/lib/client.js

@@ -0,0 +1,225 @@
+// Copyright (c) 2026 Mimer Information Technology
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// See license for more details.
+
+const mimer = require('./native');
+const { PreparedStatement } = require('./prepared');
+const { ResultSet } = require('./resultset');
+
+/**
+ * MimerClient provides a Promise-based interface to Mimer SQL
+ */
+class MimerClient {
+  constructor() {
+    this.connection = new mimer.Connection();
+    this.connected = false;
+  }
+
+  /**
+   * Connect to a Mimer SQL database
+   * @param {Object} options - Connection options
+   * @param {string} options.dsn - Database name
+   * @param {string} options.user - Username
+   * @param {string} options.password - Password
+   * @returns {Promise<void>}
+   */
+  async connect(options) {
+    const { dsn, user, password } = options;
+
+    if (!dsn || !user || !password) {
+      throw new Error('dsn, user, and password are required');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const result = this.connection.connect(dsn, user, password);
+        if (result) {
+          this.connected = true;
+          resolve();
+        } else {
+          reject(new Error('Connection failed'));
+        }
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Execute a SQL query
+   * @param {string} sql - SQL statement to execute
+   * @param {Array} params - Optional parameters (for future prepared statement support)
+   * @returns {Promise<Object>} Result object with rows and metadata
+   */
+  async query(sql, params = []) {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const result = this.connection.execute(sql, params);
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Begin a transaction
+   * @returns {Promise<void>}
+   */
+  async beginTransaction() {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.connection.beginTransaction();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Commit the current transaction
+   * @returns {Promise<void>}
+   */
+  async commit() {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.connection.commit();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Rollback the current transaction
+   * @returns {Promise<void>}
+   */
+  async rollback() {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.connection.rollback();
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Close the database connection
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (!this.connected) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.connection.close();
+        this.connected = false;
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Prepare a SQL statement for repeated execution
+   * @param {string} sql - SQL statement with ? placeholders
+   * @returns {Promise<PreparedStatement>}
+   */
+  async prepare(sql) {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const stmt = this.connection.prepare(sql);
+        resolve(new PreparedStatement(stmt));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Execute a SELECT query and return a cursor for row-at-a-time iteration.
+   * @param {string} sql - SELECT statement (with optional ? placeholders)
+   * @param {Array} params - Optional parameter values
+   * @returns {Promise<ResultSet>}
+   */
+  async queryCursor(sql, params = []) {
+    if (!this.connected) {
+      throw new Error('Not connected to database');
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const nativeRs = this.connection.executeQuery(sql, params);
+        resolve(new ResultSet(nativeRs));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Check if connected to database
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this.connection.isConnected();
+  }
+}
+
+/**
+ * Helper function to create a connection with options
+ * @param {Object} options - Connection options
+ * @returns {Promise<MimerClient>} Connected client instance
+ */
+async function connect(options) {
+  const client = new MimerClient();
+  await client.connect(options);
+  return client;
+}
+
+module.exports = { MimerClient, connect };

package/lib/find-mimer-library.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2026 Mimer Information Technology
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+// See license for more details.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find the Mimer SQL shared library path for the current platform.
+ * Returns the path (or library name for ld search) to load with koffi.load().
+ */
+function findMimerLibrary() {
+  switch (process.platform) {
+    case 'linux':
+      return 'libmimerapi.so';
+
+    case 'darwin':
+      return '/usr/local/lib/libmimerapi.dylib';
+
+    case 'win32':
+      return findMimerWindows();
+
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+
+/**
+ * Find mimapi64.dll on Windows.
+ * Search order: MIMER_HOME → Registry → Program Files scan → defaults.
+ */
+function findMimerWindows() {
+  // Helper to check if a directory contains the Mimer DLL
+  function hasDll(dir) {
+    if (!dir) return false;
+    const dllPath = path.join(dir, 'lib', 'mimapi64.dll');
+    return fs.existsSync(dllPath) ? dllPath : null;
+  }
+
+  // Try 1: MIMER_HOME environment variable
+  if (process.env.MIMER_HOME) {
+    const dll = hasDll(process.env.MIMER_HOME);
+    if (dll) return dll;
+  }
+
+  // Try 2: Windows Registry
+  try {
+    const { execSync } = require('child_process');
+    const regEnum = 'reg query "HKLM\\SOFTWARE\\Mimer\\Mimer SQL" 2>nul';
+    const output = execSync(regEnum, { encoding: 'utf8' });
+
+    const registryVersions = [];
+    for (const line of output.split('\n')) {
+      const versionMatch = line.match(/Mimer SQL\\(\d+\.\d+)\s*$/);
+      if (versionMatch) {
+        const version = versionMatch[1];
+        try {
+          const pathQuery = `reg query "HKLM\\SOFTWARE\\Mimer\\Mimer SQL\\${version}" /v PathName 2>nul`;
+          const pathOutput = execSync(pathQuery, { encoding: 'utf8' });
+          const pathMatch = pathOutput.match(/PathName\s+REG_SZ\s+(.+)/);
+          if (pathMatch && pathMatch[1]) {
+            const mimerPath = pathMatch[1].trim();
+            const dll = hasDll(mimerPath);
+            if (dll) {
+              registryVersions.push({ version, path: dll });
+            }
+          }
+        } catch (_) { /* skip */ }
+      }
+    }
+
+    if (registryVersions.length > 0) {
+      registryVersions.sort((a, b) => {
+        const va = a.version.split('.').map(Number);
+        const vb = b.version.split('.').map(Number);
+        if (va[0] !== vb[0]) return vb[0] - va[0];
+        return vb[1] - va[1];
+      });
+      return registryVersions[0].path;
+    }
+  } catch (_) { /* registry not available */ }
+
+  // Try 3: Program Files scan
+  const programFiles = [
+    process.env.ProgramFiles,
+    process.env['ProgramFiles(x86)'],
+  ].filter(Boolean);
+
+  const foundPaths = [];
+  for (const pf of programFiles) {
+    if (!fs.existsSync(pf)) continue;
+    try {
+      const entries = fs.readdirSync(pf, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name.startsWith('Mimer SQL Experience')) {
+          const fullPath = path.join(pf, entry.name);
+          const dll = hasDll(fullPath);
+          if (dll) {
+            foundPaths.push({
+              path: dll,
+              version: entry.name.match(/(\d+\.\d+)/)?.[1] || '0.0',
+            });
+          }
+        }
+      }
+    } catch (_) { /* permission error */ }
+  }
+
+  if (foundPaths.length > 0) {
+    foundPaths.sort((a, b) => {
+      const va = a.version.split('.').map(Number);
+      const vb = b.version.split('.').map(Number);
+      if (va[0] !== vb[0]) return vb[0] - va[0];
+      return vb[1] - va[1];
+    });
+    return foundPaths[0].path;
+  }
+
+  // Try 4: Default locations
+  const defaultPaths = [
+    'C:\\Program Files\\Mimer SQL Experience 12.0',
+    'C:\\Program Files\\Mimer SQL Experience 11.0',
+  ];
+  for (const dp of defaultPaths) {
+    const dll = hasDll(dp);
+    if (dll) return dll;
+  }
+
+  throw new Error(
+    'Mimer SQL library not found. Please install Mimer SQL or set MIMER_HOME.'
+  );
+}
+
+module.exports = findMimerLibrary;