@eliware/elera-lib 0.1.8 → 0.1.9

package/README.md

@@ -2,9 +2,9 @@
 
 The alternative SQL client for Eliware applications. It provides generic
 primary/balanced MySQL or MariaDB routing without embedding Elera, HAProxy,
-backup, or GitOps policy. It is a v0.1.8 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.9 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.8.
+0.1.9.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -61,8 +61,10 @@ automatically.
 `client.availability()` reports whether a primary route is usable. It returns
 `state: 'cluster-unavailable'` when every primary candidate is draining or
 unavailable; the `routes` fields report primary and balanced availability
-independently. New operations in that state fail with the exported
-`ClusterUnavailableError` using code `CLUSTER_UNAVAILABLE`.
+independently. A single-node route fails with the exported
+`ServerUnavailableError` using code `SERVER_UNAVAILABLE`; a multi-node route
+with no eligible candidates fails with `ClusterUnavailableError` using code
+`CLUSTER_UNAVAILABLE`.
 
 When an attached routing stream receives a `routing.shutdown` event, the
 client drains the identified node, performs a REST bundle resynchronization,
@@ -94,11 +96,12 @@ contents. The stream reports `websocket`, `rest`, or `disconnected` mode so
 callers can observe transport health without implementing transport policy.
 
 Applications may opt into generic in-memory telemetry with
-`createDb({ ..., telemetry: true })`. Query counts, failures, retries,
-in-flight work, and latency are exposed through `client.telemetry` and sent
-over an attached routing stream once per second. Telemetry is observational
-only; it does not carry SQL or credentials. Reconnect, failover, and cumulative
-reconnect-delay counters are included in the telemetry snapshot.
+`createDb({ ..., telemetry: true })`. Query, execute, and transaction counts,
+failures, retries, in-flight work, and latency are exposed through
+`client.telemetry` and sent over an attached routing stream once per second.
+Telemetry is observational only; it does not carry SQL or credentials.
+Reconnect, failover, and cumulative reconnect-delay counters are included in
+the telemetry snapshot.
 
 `createMaterializer` supports bounded plaintext use for a caller-provided
 operation. It creates a mode-restricted temporary file and removes its entire

package/RELEASE_NOTES.md

@@ -1,5 +1,18 @@
 # Release notes
 
+## 0.1.9 — Standalone outage classification and complete operation telemetry
+
+### Added
+
+- Exposes `ServerUnavailableError` with the stable `SERVER_UNAVAILABLE` code when a standalone SQL route has no eligible server.
+- Keeps multi-node route exhaustion classified as `CLUSTER_UNAVAILABLE`.
+- Records telemetry for `execute()` and transaction operations alongside query latency and failure metrics.
+
+### Validation
+
+- Adds regression coverage for standalone drain classification and operation telemetry.
+- Maintains 100% statements, branches, functions, and lines coverage with zero lint warnings.
+
 ## 0.1.8 — Explicit outage state and recovery observability
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.8",
+    "version": "0.1.9",
     "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",

package/src/client/create-db.mjs

@@ -32,8 +32,8 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
   const timed = createTimedOperation({ metrics, now });
   const client = {
     async query(sql, values, options) { return timed(async () => { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { const requestedRoute = options?.route ?? routing; if (error.retryable && balancedPool && routeFor(sql, requestedRoute) === 'balanced' && classifyQuery(sql) === 'balanced') { metrics?.record?.({ retry: true }); return balancedPool.query(sql, values); } throw error; } }); },
-    async execute(sql, values, options) { return choose(sql, options).execute(sql, values); },
-    async transaction(callback) { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } },
+    async execute(sql, values, options) { return timed(async () => choose(sql, options).execute(sql, values)); },
+    async transaction(callback) { return timed(async () => { const node = primaryPool.choose(); const connection = await node.getConnection(); try { await connection.beginTransaction(); const tx = { query: (sql, values) => connection.query(sql, values), execute: (sql, values) => connection.execute(sql, values) }; const result = await callback(tx); await connection.commit(); return result; } catch (error) { await connection.rollback().catch(() => {}); throw asSqlError(error); } finally { connection.release(); } }); },
     async health(route = 'primary') { const started = now(); const selected = route === 'balanced' && balancedPool ? balancedPool : primaryPool; const nodes = await selected.health(); return { ok: nodes.some((node) => node.ok), route: selected === balancedPool ? 'balanced' : 'primary', nodes, latencyMs: now() - started }; },
     async refresh(nextBundle) { const candidate = validateBundle(nextBundle); if (bundleExpired(candidate, now())) throw new Error('routing bundle is expired'); if (olderVersion(candidate.bundleVersion, activeBundle?.bundleVersion)) return { bundleVersion: activeBundle?.bundleVersion, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; const previous = [primaryPool, balancedPool]; const credentials = candidate.credentials ?? { username: primaryConfig.user, password: primaryConfig.password }; const writer = candidate.writer ?? candidate.routes.primary?.[0]; const reader = candidate.readers?.[0] ?? candidate.routes.balanced?.[0]; primaryConfig = validateProfile({ ...primaryConfig, host: writer.host, port: writer.port, user: credentials.username, password: credentials.password, database: candidate.database }, 'primary'); balancedConfig = reader ? validateProfile({ ...primaryConfig, host: reader.host, port: reader.port }, 'balanced') : undefined; activeBundle = candidate; primaryPool = makeRoute('primary', primaryConfig); balancedPool = balancedConfig ? makeRoute('balanced', balancedConfig) : null; await Promise.all(previous.filter(Boolean).map((pool) => pool.close())); return { bundleVersion: activeBundle.bundleVersion ?? null, refreshRequired: bundleNeedsRefresh(activeBundle, now()) }; },
     async attachRoutingStream(stream) { if (!stream?.connect) throw new TypeError('routing stream is required'); metrics?.start?.(stream); stream.setTelemetry?.(metrics); stream.setOnUpdate?.(async (event) => { const update = event.type === 'routing.update' ? event : event.type === 'routing.resync' ? event.bundle : undefined; if (update && (update.writer || update.routes?.primary?.length)) await client.refresh({ ...activeBundle, ...update, database: update.database ?? activeBundle?.database ?? primaryConfig.database, credentials: update.credentials ?? activeBundle?.credentials, routes: update.routes ?? activeBundle?.routes, bundleVersion: update.bundleVersion ?? update.version ?? activeBundle?.bundleVersion, expiresAt: update.expiresAt ?? activeBundle?.expiresAt ?? new Date(now() + 60000).toISOString() }); if (event.type === 'routing.drain' || event.type === 'routing.shutdown') for (const pool of [primaryPool, balancedPool].filter(Boolean)) (event.type === 'routing.drain' ? pool.drain : pool.drain)(event.node, drainTimeoutMs); if (event.type === 'routing.recovery') for (const pool of [primaryPool, balancedPool].filter(Boolean)) pool.recover(event.node, drainTimeoutMs); }); await stream.connect(); return () => stream.close?.(); },

package/src/errors.mjs

@@ -11,6 +11,13 @@ export class ClusterUnavailableError extends SqlClientError {
   }
 }
 
+export class ServerUnavailableError extends SqlClientError {
+  constructor(message = 'The SQL server is unavailable', options = {}) {
+    super(message, { code: 'SERVER_UNAVAILABLE', retryable: false, ...options });
+    this.name = 'ServerUnavailableError';
+  }
+}
+
 export function classifyError(error) {
   const code = error?.code;
   if (['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'PROTOCOL_CONNECTION_LOST', 'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR'].includes(code)) return { code: 'CONNECTION_ERROR', retryable: true };

package/src/index.d.ts

@@ -69,6 +69,7 @@ export function validateProfile(profile: ConnectionProfile, name?: string): Conn
 export function redactedProfile(profile: ConnectionProfile): ConnectionProfile;
 export class SqlClientError extends Error { code?: string; retryable?: boolean; cause?: unknown; }
 export class ClusterUnavailableError extends SqlClientError {}
+export class ServerUnavailableError extends SqlClientError {}
 export function classifyError(error: unknown): { retryable: boolean; code?: string };
 export function asSqlError(error: unknown): SqlClientError;
 export function validateBundle(bundle: RoutingBundle): RoutingBundle;

package/src/index.mjs

@@ -3,7 +3,7 @@ export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs
 export { createDbFromEnvironment } from './client/environment.mjs';
 export { classifyQuery, routeFor } from './routing.mjs';
 export { validateProfile, redactedProfile } from './config.mjs';
-export { SqlClientError, ClusterUnavailableError, classifyError, asSqlError } from './errors.mjs';
+export { SqlClientError, ClusterUnavailableError, ServerUnavailableError, classifyError, asSqlError } from './errors.mjs';
 export { validateBundle, bundleExpired, bundleNeedsRefresh } from './bundle.mjs';
 export { createAdminSql } from './admin/sql.mjs';
 export { createMigrationRunner } from './admin/migrations.mjs';

package/src/pools/route-pool.mjs

@@ -1,11 +1,11 @@
-import { ClusterUnavailableError } from '../errors.mjs';
+import { ClusterUnavailableError, ServerUnavailableError } from '../errors.mjs';
 
-export function createRoutePool(nodes, { preferred = false } = {}) {
+export function createRoutePool(nodes, { preferred = false, unavailableError = nodes.length === 1 ? ServerUnavailableError : ClusterUnavailableError } = {}) {
   let cursor = 0;
   const candidates = () => nodes.filter((node) => node.available);
   const choose = () => {
     const available = candidates();
-    if (!available.length) throw new ClusterUnavailableError('no eligible SQL nodes available');
+    if (!available.length) throw new unavailableError('no eligible SQL nodes available');
     if (preferred) return available[0];
     const total = available.reduce((sum, node) => sum + Math.max(0, node.weight), 0);
     if (!total) return available[cursor++ % available.length];