apache-iggy 0.10.0-edge.4 → 0.10.0-edge.6

package/NOTICE

@@ -1,4 +1,4 @@
-Apache Iggy (Incubating)
+Apache Iggy
 Copyright 2026 The Apache Software Foundation
 
 This product includes software developed at

package/README.md

@@ -10,12 +10,6 @@
 
 Apache Iggy Node.js client written in typescript, it currently only supports tcp & tls transports.
 
-> Apache Iggy (Incubating) is an effort undergoing incubation at the Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC.
->
-> Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.
->
-> While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.
-
 diclaimer: although all iggy commands & basic client/stream are implemented this is still a WIP, provided as is, and has still a long way to go to be considered "battle tested".
 
 note: This lib started as _iggy-bin_ ( [github](https://github.com/T1B0/iggy-bin) / [npm](https://www.npmjs.com/package/iggy-bin)) before migrating under iggy-rs org. package iggy-bin@v1.3.4 is equivalent to @iggy.rs/sdk@v1.0.3 and migrating again under apache iggy monorepo ( [github](https://github.com/apache/iggy/tree/master/foreign/node) and is now published on npmjs as apache-iggy
@@ -73,6 +67,8 @@ new session.
 
 The client pings every `heartbeatInterval` milliseconds, 5000 by default, which
 keeps an idle session alive when the server's `[heartbeat]` eviction is enabled.
+`heartbeatInterval` also accepts a duration expression such as `"10s"` or
+`"1h 30m"`, like the Rust SDK.
 The server evicts a connection silent for 36 s, which is 1.2 x its 30 s
 heartbeat interval. Raising the client interval past that window, or setting it
 to 0 to disable client heartbeats, exposes an idle consumer-group member to
@@ -111,6 +107,43 @@ const client = new Client({
 const stats = await client.system.getStats();
 ```
 
+### Connection strings
+
+Every client constructor (except `SimpleClient` see note) also accepts a
+connection string instead of a config object:
+
+```ts
+import { Client } from "apache-iggy";
+
+const client = new Client("iggy://iggy:iggy@127.0.0.1:8090");
+const stats = await client.system.getStats();
+```
+
+Supported schemes are `iggy://` (TCP, default) and `iggy+tcp://`. Credentials
+are `username:password` or a single personal access token. Options mirror the
+other SDKs: `tls`, `tls_domain`, `tls_ca_file`, `reconnection_retries`,
+`reconnection_interval`, `heartbeat_interval` and `nodelay`. `reestablish_after`
+is accepted for format compatibility but has no Node equivalent.
+
+note: `SimpleClient` does not accept a connection string: it wraps an existing
+`RawClient` instance rather than building one from configuration. Pass the
+connection string to `Client`, `SingleClient` or `getRawClient` and hand the
+resulting raw client to `SimpleClient` if needed.
+
+### option limits
+
+| option | limit |
+| --- | --- |
+| `reconnection_retries` | integer up to `4294967295` (u32 max); larger values are rejected like Rust's u32 overflow, and `unlimited` maps to this ceiling. Defaults to unlimited |
+| `heartbeat_interval` | duration up to `2147483647ms` (Node's largest timer delay); `0` disables heartbeats |
+| `reconnection_interval` | positive duration (`ms`, `s`, `m`, `h`) up to `2147483647ms` (Node's largest timer delay); zero spellings are rejected. Defaults to `1s` |
+| port in the authority | decimal up to `65535` |
+
+Durations accept the same expressions as the Rust SDK, for example `500ms`,
+`10s`, `1h 30m`, `5d`, `2w`, `1y`; matching is case-insensitive and
+`0`, `unlimited`, `disabled` and `none` map to zero. Unit-less numbers such as
+`5` are rejected.
+
 ## use sources
 
 ### Install
@@ -128,7 +161,7 @@ npm run build
 ### test
 
 note: use env var `IGGY_TCP_ADDRESS="host:port"` to set the server
-address for bdd and e2e tests.
+address for e2e tests. bdd tests need more variables, see below.
 
 #### unit tests
 
@@ -146,15 +179,27 @@ npm run test:e2e
 
 #### bdd tests
 
-bdd test expect an iggy-server at tcp://127.0.0.1:8090
+the bdd suite has no defaults and fails when `IGGY_TCP_ADDRESS`,
+`IGGY_ROOT_USERNAME` or `IGGY_ROOT_PASSWORD` is missing. from the repository
+root run
 
 ```bash
-npm run test:bdd
+./scripts/run-bdd-tests.sh node
 ```
 
+the script starts the server and sets every variable, so none of them have to be
+exported by hand. to iterate against a server you started yourself, see
+[src/bdd/README.md](./src/bdd/README.md).
+
 #### run all test
 
-`npm run test` runs unit, bdd and e2e tests suite (expect an iggy-server at tcp://127.0.0.1:8090)
+`npm run test` runs unit, bdd and e2e tests suite against an iggy-server at
+tcp://127.0.0.1:8090, started with the same root credentials
+
+```bash
+IGGY_TCP_ADDRESS=127.0.0.1:8090 IGGY_ROOT_USERNAME=iggy IGGY_ROOT_PASSWORD=iggy \
+  npm run test
+```
 
 ### lint
 

package/dist/client/client.config.d.ts

@@ -1,4 +1,4 @@
-import type { ClientConfig } from './client.type.js';
+import type { ClientConfig, ClientConfigOrString } from './client.type.js';
 export declare const DEFAULT_MAX_RESPONSE_FRAME_SIZE: number;
 /**
  * The server evicts a connection silent for 36 s (1.2 x its 30 s heartbeat
@@ -7,5 +7,5 @@ export declare const DEFAULT_MAX_RESPONSE_FRAME_SIZE: number;
 export declare const DEFAULT_HEARTBEAT_INTERVAL: number;
 /** Node's largest timer delay: setInterval clamps anything above it to 1 ms. */
 export declare const MAX_HEARTBEAT_INTERVAL = 2147483647;
-export declare const normalizeClientConfig: (config: ClientConfig) => ClientConfig;
+export declare const normalizeClientConfig: (config: ClientConfigOrString) => ClientConfig;
 //# sourceMappingURL=client.config.d.ts.map

package/dist/client/client.config.js

@@ -14,6 +14,8 @@
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
+import { MAX_U32 } from '../constant.js';
+import { parseConnectionString } from './client.connection-string.js';
 export const DEFAULT_MAX_RESPONSE_FRAME_SIZE = 64 * 1024 * 1024;
 /**
  * The server evicts a connection silent for 36 s (1.2 x its 30 s heartbeat
@@ -23,6 +25,8 @@ export const DEFAULT_HEARTBEAT_INTERVAL = 5 * 1000;
 /** Node's largest timer delay: setInterval clamps anything above it to 1 ms. */
 export const MAX_HEARTBEAT_INTERVAL = 2_147_483_647;
 export const normalizeClientConfig = (config) => {
+    if (typeof config === 'string')
+        config = parseConnectionString(config);
     const maxResponseFrameSize = config.maxResponseFrameSize ?? DEFAULT_MAX_RESPONSE_FRAME_SIZE;
     if (!Number.isSafeInteger(maxResponseFrameSize) ||
         maxResponseFrameSize < 256)
@@ -38,6 +42,25 @@ export const normalizeClientConfig = (config) => {
         heartbeatInterval < 0 ||
         heartbeatInterval > MAX_HEARTBEAT_INTERVAL)
         throw new TypeError(`heartbeatInterval must be a safe integer of milliseconds between 0 and ${MAX_HEARTBEAT_INTERVAL} (0 disables heartbeats)`);
+    // Unlike the heartbeat, 0 is not a disable here: an immediate retry delay
+    // turns reconnection into a hot loop. The ceiling guards the same
+    // setInterval clamp, which would turn a long backoff into a 1 ms spin.
+    // A disabled reconnect never schedules a retry, so the interval check
+    // applies only when enabled; callers commonly pass a zero interval with
+    // enabled: false. maxRetries stays bounded either way, matching the
+    // connection-string path.
+    if (config.reconnect !== undefined) {
+        const { enabled, interval, maxRetries } = config.reconnect;
+        if (!Number.isSafeInteger(maxRetries) ||
+            maxRetries < 0 ||
+            maxRetries > MAX_U32)
+            throw new TypeError(`reconnect.maxRetries must be a non-negative integer of at most ${MAX_U32}`);
+        if (enabled &&
+            (!Number.isSafeInteger(interval) ||
+                interval < 1 ||
+                interval > MAX_HEARTBEAT_INTERVAL))
+            throw new TypeError(`reconnect.interval must be a safe integer of milliseconds between 1 and ${MAX_HEARTBEAT_INTERVAL}`);
+    }
     return {
         ...config,
         options: { ...config.options },

package/dist/client/client.config.test.js

@@ -16,6 +16,7 @@
 // under the License.
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import { MAX_U32 } from '../constant.js';
 import { DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_MAX_RESPONSE_FRAME_SIZE, normalizeClientConfig } from './client.config.js';
 const config = () => ({
     transport: 'TCP',
@@ -44,6 +45,34 @@ describe('normalizeClientConfig', () => {
                 heartbeatInterval
             }), /heartbeatInterval/);
     });
+    it('accepts a usable reconnect interval', () => {
+        const reconnect = { enabled: true, interval: 1000, maxRetries: 3 };
+        assert.deepEqual(normalizeClientConfig({ ...config(), reconnect }).reconnect, reconnect);
+    });
+    it('rejects unusable reconnect intervals', () => {
+        for (const interval of [
+            0, -1000, Number.NaN, 1.5, 2_147_483_648, Number.MAX_VALUE
+        ])
+            assert.throws(() => normalizeClientConfig({
+                ...config(),
+                reconnect: { enabled: true, interval, maxRetries: 1 }
+            }), /reconnect\.interval/);
+    });
+    it('skips the interval check when reconnect is disabled', () => {
+        assert.doesNotThrow(() => normalizeClientConfig({
+            ...config(),
+            reconnect: { enabled: false, interval: 0, maxRetries: 0 }
+        }));
+    });
+    it('rejects unusable reconnect maxRetries', () => {
+        for (const maxRetries of [
+            -1, Number.NaN, 1.5, MAX_U32 + 1, Number.MAX_VALUE
+        ])
+            assert.throws(() => normalizeClientConfig({
+                ...config(),
+                reconnect: { enabled: true, interval: 1000, maxRetries }
+            }), /reconnect\.maxRetries/);
+    });
     it('restricts the client to one pooled connection', () => {
         const normalized = normalizeClientConfig(config());
         assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });

package/dist/client/client.connection-string.d.ts

@@ -0,0 +1,14 @@
+import type { ClientConfig } from './client.type.js';
+/** Parses a duration with the exact grammar of the Rust SDK's
+ * `IggyDuration::from_str`, returning whole milliseconds.
+ */
+export declare const parseDuration: (value: string) => number;
+/**
+ * Parses an Iggy connection string into a client configuration.
+ *
+ * Supports `iggy://` and `iggy+tcp://`; the Node SDK implements TCP/TLS only.
+ * Credentials are either `username:password` or a single personal access
+ * token before the `@`. TLS is enabled with `tls=true`.
+ */
+export declare const parseConnectionString: (connectionString: string) => ClientConfig;
+//# sourceMappingURL=client.connection-string.d.ts.map

package/dist/client/client.connection-string.js

@@ -0,0 +1,188 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+import { MAX_U32 } from '../constant.js';
+import { nanosecondsToMilliseconds, parseIggyDurationNanoseconds } from '../duration.utils.js';
+const DEFAULT_PROTOCOL = 'iggy';
+const SCHEME_PREFIX = 'iggy+';
+const SUPPORTED_PROTOCOLS = ['tcp'];
+/** Reconnection defaults carried by every connection string.
+ *
+ * Mirrors TcpConnectionStringOptions: retries default to unlimited and the
+ * interval to 1s. Deliberately not DefaultReconnectOption, whose 12/5s pair
+ * only applies to object configs.
+ */
+const CONNECTION_STRING_RECONNECT = {
+    enabled: true,
+    interval: 1000,
+    maxRetries: MAX_U32
+};
+/** Parses a duration with the exact grammar of the Rust SDK's
+ * `IggyDuration::from_str`, returning whole milliseconds.
+ */
+export const parseDuration = (value) => {
+    try {
+        return nanosecondsToMilliseconds(parseIggyDurationNanoseconds(value));
+    }
+    catch (error) {
+        throw new TypeError(`invalid duration "${value}"`, { cause: error });
+    }
+};
+/**
+ * Parses an Iggy connection string into a client configuration.
+ *
+ * Supports `iggy://` and `iggy+tcp://`; the Node SDK implements TCP/TLS only.
+ * Credentials are either `username:password` or a single personal access
+ * token before the `@`. TLS is enabled with `tls=true`.
+ */
+export const parseConnectionString = (connectionString) => {
+    if (typeof connectionString !== 'string' || connectionString.length === 0)
+        throw new TypeError('connection string must be a non-empty string');
+    const protocolParts = connectionString.split('://');
+    if (protocolParts.length !== 2)
+        throw new TypeError('invalid connection string');
+    const scheme = protocolParts[0];
+    const protocol = scheme === DEFAULT_PROTOCOL
+        ? 'tcp'
+        : scheme.startsWith(SCHEME_PREFIX)
+            ? scheme.slice(SCHEME_PREFIX.length)
+            : undefined;
+    if (protocol === undefined)
+        throw new TypeError('invalid connection string');
+    if (!SUPPORTED_PROTOCOLS.includes(protocol))
+        throw new TypeError(`unsupported transport "${protocol}", Node SDK supports tcp only`);
+    const parts = protocolParts[1].split('@');
+    if (parts.length !== 2)
+        throw new TypeError('invalid connection string');
+    const credentials = parts[0].split(':');
+    const tokenCredentials = credentials.length === 1;
+    if (!tokenCredentials && credentials.length !== 2)
+        throw new TypeError('invalid connection string');
+    const username = credentials[0];
+    const password = credentials[1] ?? '';
+    if (!tokenCredentials && (username.length === 0 || password.length === 0))
+        throw new TypeError('invalid connection string');
+    const serverAndOptions = parts[1].split('?');
+    if (serverAndOptions.length > 2)
+        throw new TypeError('invalid connection string');
+    const serverAddress = serverAndOptions[0];
+    // One match covers both `[ipv6]:port` and `host:port`, where the
+    // unbracketed host may not contain a colon. Multi-colon authorities such
+    // as `2001:db8::1:8090` or `host:8090:9090` are rejected
+    const addressMatch = /^(?:\[([^\]]+)\]|([^:\[\]]+)):(\d+)$/.exec(serverAddress);
+    if (!addressMatch)
+        throw new TypeError('invalid connection string');
+    const host = addressMatch[1] ?? addressMatch[2];
+    const port = Number(addressMatch[3]);
+    if (port > 65535)
+        throw new TypeError('invalid connection string');
+    const options = serverAndOptions.length === 2
+        ? parseConnectionOptions(serverAndOptions[1])
+        : {
+            tls: false,
+            reconnect: { ...CONNECTION_STRING_RECONNECT }
+        };
+    const { tls, reconnect, heartbeatInterval, ...transportOptions } = options;
+    const config = {
+        transport: tls ? 'TLS' : 'TCP',
+        options: {
+            host,
+            port: Number(port),
+            ...transportOptions
+        },
+        credentials: tokenCredentials
+            ? { token: username }
+            : { username, password },
+        // Always present on connection strings: Rust applies its unlimited/1s
+        // reconnection defaults even without query options.
+        reconnect
+    };
+    if (heartbeatInterval !== undefined)
+        config.heartbeatInterval = heartbeatInterval;
+    return config;
+};
+const parseConnectionOptions = (optionsString) => {
+    const parsed = {
+        tls: false,
+        reconnect: { ...CONNECTION_STRING_RECONNECT }
+    };
+    for (const option of optionsString.split('&')) {
+        const optionParts = option.split('=');
+        if (optionParts.length !== 2)
+            throw new TypeError('invalid connection string');
+        const [name, value] = optionParts;
+        switch (name) {
+            case 'tls':
+                parsed.tls = parseBoolean(name, value);
+                break;
+            case 'nodelay':
+                parsed.noDelay = parseBoolean(name, value);
+                break;
+            case 'tls_domain':
+                parsed.servername = value;
+                break;
+            case 'tls_ca_file':
+                // The path is stored unread; the certificate is loaded when the
+                // TLS socket is created, so plain-TCP configs never touch the
+                // filesystem (matches the Rust SDK).
+                parsed.caFile = value;
+                break;
+            case 'reconnection_retries': {
+                // Values above u32::MAX are rejected like the Rust SDK's u32
+                // overflow; otherwise they would act as a second, undocumented
+                // spelling of "unlimited".
+                const maxRetries = value === 'unlimited'
+                    ? MAX_U32
+                    : parseNumber(name, value);
+                if (maxRetries > MAX_U32)
+                    throw new TypeError(`option "${name}" must be at most ${MAX_U32}`);
+                parsed.reconnect.maxRetries = maxRetries;
+                break;
+            }
+            case 'reconnection_interval': {
+                const interval = parseDuration(value);
+                // With retries defaulting to unlimited, a zero interval would turn
+                // the reconnect loop into an unbounded hot loop.
+                if (interval <= 0)
+                    throw new TypeError(`option "${name}" must be positive`);
+                parsed.reconnect.interval = interval;
+                break;
+            }
+            case 'reestablish_after':
+                // No Node equivalent: validated as a duration like the Rust SDK
+                // does, then discarded.
+                parseDuration(value);
+                break;
+            case 'heartbeat_interval':
+                parsed.heartbeatInterval = parseDuration(value);
+                break;
+            default:
+                throw new TypeError(`unknown option "${name}"`);
+        }
+    }
+    return parsed;
+};
+const parseBoolean = (name, value) => {
+    if (value !== 'true' && value !== 'false')
+        throw new TypeError(`option "${name}" must be true or false`);
+    return value === 'true';
+};
+const parseNumber = (name, value) => {
+    if (!/^\d+$/.test(value))
+        throw new TypeError(`option "${name}" must be a non-negative integer`);
+    return Number(value);
+};
+//# sourceMappingURL=client.connection-string.js.map

package/dist/client/client.connection-string.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.connection-string.test.d.ts.map

package/dist/client/client.connection-string.test.js

@@ -0,0 +1,209 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { MAX_U32 } from '../constant.js';
+import { parseConnectionString, parseDuration } from './client.connection-string.js';
+import { DEFAULT_HEARTBEAT_INTERVAL, normalizeClientConfig } from './client.config.js';
+describe('parseConnectionString', () => {
+    it('parses the default scheme with password credentials', () => {
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@127.0.0.1:8090'), {
+            transport: 'TCP',
+            options: { host: '127.0.0.1', port: 8090 },
+            credentials: { username: 'iggy', password: 'secret' },
+            reconnect: { enabled: true, interval: 1000, maxRetries: MAX_U32 }
+        });
+    });
+    it('parses the explicit tcp scheme with a personal access token', () => {
+        assert.deepEqual(parseConnectionString('iggy+tcp://iggypat-1234567890abcdef@localhost:8090'), {
+            transport: 'TCP',
+            options: { host: 'localhost', port: 8090 },
+            credentials: { token: 'iggypat-1234567890abcdef' },
+            reconnect: { enabled: true, interval: 1000, maxRetries: MAX_U32 }
+        });
+    });
+    it('maps tls options to the TLS transport', () => {
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090?tls=true&tls_domain=iggy.apache.org'), {
+            transport: 'TLS',
+            options: {
+                host: 'localhost',
+                port: 8090,
+                servername: 'iggy.apache.org'
+            },
+            credentials: { username: 'iggy', password: 'secret' },
+            reconnect: { enabled: true, interval: 1000, maxRetries: MAX_U32 }
+        });
+    });
+    it('maps reconnection and heartbeat options', () => {
+        assert.deepEqual(parseConnectionString('iggy+tcp://iggy:secret@localhost:8090' +
+            '?reconnection_retries=3&reconnection_interval=5s&heartbeat_interval=10s'), {
+            transport: 'TCP',
+            options: { host: 'localhost', port: 8090 },
+            credentials: { username: 'iggy', password: 'secret' },
+            reconnect: {
+                enabled: true,
+                maxRetries: 3,
+                interval: 5000
+            },
+            heartbeatInterval: 10000
+        });
+    });
+    it('applies unlimited/1s reconnection defaults to partial options', () => {
+        // retries alone keep the 1s interval; interval alone keeps unlimited.
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090?reconnection_retries=3').reconnect, { enabled: true, interval: 1000, maxRetries: 3 });
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090?reconnection_interval=5s').reconnect, { enabled: true, interval: 5000, maxRetries: MAX_U32 });
+    });
+    it('maps nodelay to the socket option', () => {
+        assert.equal(parseConnectionString('iggy://iggy:secret@localhost:8090?nodelay=true')
+            .options.noDelay, true);
+    });
+    it('maps unlimited retries to the u32 ceiling', () => {
+        assert.equal(parseConnectionString('iggy://iggy:secret@localhost:8090?reconnection_retries=unlimited').reconnect?.maxRetries, MAX_U32);
+    });
+    it('accepts retry counts up to u32::MAX and rejects overflow', () => {
+        assert.equal(parseConnectionString(`iggy://iggy:secret@localhost:8090?reconnection_retries=${MAX_U32}`).reconnect?.maxRetries, MAX_U32);
+        for (const value of [
+            'iggy://iggy:secret@localhost:8090?reconnection_retries=4294967296',
+            'iggy://iggy:secret@localhost:8090?reconnection_retries=99999999999999'
+        ])
+            assert.throws(() => parseConnectionString(value), TypeError);
+    });
+    it('rejects a non-positive reconnection interval', () => {
+        // Zero spellings parse but are rejected by the positivity bound.
+        for (const value of ['0', '0ms', 'none'])
+            assert.throws(() => parseConnectionString(`iggy://iggy:secret@localhost:8090?reconnection_interval=${value}`), /must be positive/);
+        // Negative durations shall not parse
+        assert.throws(() => parseConnectionString('iggy://iggy:secret@localhost:8090?reconnection_interval=-1s'), TypeError);
+    });
+    it('ignores reestablish_after for format compatibility', () => {
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090?reestablish_after=10s'), {
+            transport: 'TCP',
+            options: { host: 'localhost', port: 8090 },
+            credentials: { username: 'iggy', password: 'secret' },
+            reconnect: { enabled: true, interval: 1000, maxRetries: MAX_U32 }
+        });
+    });
+    it('rejects unsupported transports', () => {
+        for (const value of [
+            'iggy+quic://iggy:secret@localhost:8090',
+            'iggy+ws://iggy:secret@localhost:8090'
+        ])
+            assert.throws(() => parseConnectionString(value), /unsupported transport/);
+    });
+    it('rejects malformed connection strings', () => {
+        for (const value of [
+            '',
+            'iggy',
+            'iggy://',
+            'iggy://:secret@localhost:8090',
+            'iggy://iggy:@localhost:8090',
+            'iggy://iggy:secret@localhost',
+            'iggy://iggy:secret@:8090',
+            'iggy://iggy:secret@localhost:port',
+            'iggy://iggy:secret@localhost:70000',
+            'iggy://iggy:secret@localhost:8090?unknown=value',
+            'iggy://iggy:secret@localhost:8090?tls=maybe',
+            'iggy://iggy:secret@localhost:8090?reconnection_retries=three',
+            'iggy://iggy:secret@[::1:8090',
+            'iggy://iggy:secret@[]:8090',
+            'iggy://iggy:secret@[::1]x:8090',
+            'iggy://iggy:secret@2001:db8::1:8090',
+            'iggy://iggy:secret@host:8090:9090',
+            'iggy://iggy:secret@localhost:8090?',
+            'iggy://iggy:secret@localhost:8090?&',
+            'iggy://iggy:secret@localhost:8090?reestablish_after=garbage'
+        ])
+            assert.throws(() => parseConnectionString(value), TypeError);
+    });
+    it('never includes the connection string in error messages', () => {
+        const secrets = ['hunter2', 'iggypat-1234567890abcdef'];
+        for (const value of [
+            'iggy://iggy:hunter2@localhost',
+            `iggy+tcp://iggypat-1234567890abcdef@localhost`,
+            'iggy://iggy:hunter2@localhost:8090?unknown=value',
+            'iggy://iggy:hunter2@localhost:8090?tls=maybe',
+            'iggy://iggy:hunter2@localhost:8090?reconnection_retries=three',
+            'iggy://iggy:hunter2@localhost:70000'
+        ]) {
+            try {
+                parseConnectionString(value);
+                assert.fail(`expected "${value}" to be rejected`);
+            }
+            catch (error) {
+                assert.ok(error instanceof TypeError);
+                for (const secret of secrets)
+                    assert.ok(!error.message.includes(secret), `error message leaked a secret: ${error.message}`);
+            }
+        }
+    });
+    it('parses IPv6 host addresses without their brackets', () => {
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@[::1]:8090').options, { host: '::1', port: 8090 });
+    });
+    it('stores tls_ca_file as a path without reading it at parse time', () => {
+        assert.deepEqual(parseConnectionString('iggy://iggy:secret@localhost:8090' +
+            '?tls=true&tls_ca_file=/does/not/exist.pem').options, {
+            host: 'localhost',
+            port: 8090,
+            caFile: '/does/not/exist.pem'
+        });
+    });
+});
+describe('parseDuration', () => {
+    it('converts supported units to milliseconds', () => {
+        assert.equal(parseDuration('500ms'), 500);
+        assert.equal(parseDuration('5s'), 5000);
+        assert.equal(parseDuration('2m'), 120000);
+        assert.equal(parseDuration('1h'), 3600000);
+        assert.equal(parseDuration('0.5s'), 500);
+        assert.equal(parseDuration('1h 1m 1s'), 3661000);
+        assert.equal(parseDuration('1h30m'), 5400000);
+        assert.equal(parseDuration('5d'), 432000000);
+        assert.equal(parseDuration('2w'), 1209600000);
+        assert.equal(parseDuration('1y'), 31557600000);
+        assert.equal(parseDuration('5sec'), 5000);
+        assert.equal(parseDuration('5msec'), 5);
+        // Fractional results are rounded to whole milliseconds.
+        assert.equal(parseDuration('1.005s'), 1005);
+        assert.equal(parseDuration('5usec'), 0);
+        assert.equal(parseDuration('500nsec'), 0);
+        for (const zero of ['0', 'unlimited', 'disabled', 'none', 'UNLIMITED'])
+            assert.equal(parseDuration(zero), 0);
+    });
+    it('rejects unsupported durations', () => {
+        for (const value of ['5', '-1s', 'ms', '', 'abc', 's'])
+            assert.throws(() => parseDuration(value), /invalid duration/);
+    });
+});
+describe('normalizeClientConfig with connection strings', () => {
+    it('applies client defaults to the parsed config', () => {
+        const normalized = normalizeClientConfig('iggy://iggy:secret@localhost:8090');
+        assert.equal(normalized.transport, 'TCP');
+        assert.equal(normalized.options.host, 'localhost');
+        assert.equal(normalized.options.port, 8090);
+        assert.deepEqual(normalized.credentials, {
+            username: 'iggy',
+            password: 'secret'
+        });
+        assert.equal(normalized.heartbeatInterval, DEFAULT_HEARTBEAT_INTERVAL);
+        assert.deepEqual(normalized.poolSize, { min: 1, max: 1 });
+    });
+    it('rejects reconnect intervals beyond the node timer ceiling', () => {
+        // Parses to 3_600_000_000 ms; setInterval would clamp it back to 1 ms.
+        assert.throws(() => normalizeClientConfig('iggy://iggy:secret@localhost:8090?reconnection_interval=1000h'), /reconnect\.interval/);
+    });
+});
+//# sourceMappingURL=client.connection-string.test.js.map