connection-string

library5.0.0jsnpmunverified

connection-string is an advanced JavaScript library for parsing and generating URL connection strings, offering features beyond standard URL parsers. It supports a fully optional syntax for every component, multiple hosts, unification of Unix socket support with URL standards, automatic defaults configuration for missing parameters, and the ability to reconstruct a connection string from an object. The current stable version is 5.0.0, released in late 2025/early 2026. Releases are active but not on a fixed cadence, focusing on maintenance, compatibility, and feature enhancements. Key differentiators include its flexible parsing for partial or complex connection strings (e.g., with multiple hosts or specific Unix socket patterns) and its ability to apply defaults, making it highly versatile for database and service connection configurations. The library ships with TypeScript types.

database serialization

npm install connection-string

github ↗package ↗

INSTALL

IMPORT

SIG · CONNECTION-STRING

connection-string

databasejavascriptv5.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConnectionString

✓ import { ConnectionString } from 'connection-string';

✗ import ConnectionString from 'connection-string';

The `ConnectionString` class is a named export. The package targets ES2020 and is optimized for ES Modules (ESM) since v5.0.0.

ConnectionString (CommonJS)

✓ const { ConnectionString } = require('connection-string');

✗ const ConnectionString = require('connection-string');

This pattern is for CommonJS (CJS) environments. For modern Node.js and browser applications, the ESM `import` is the recommended standard.

Host Type

✓ import type { Host } from 'connection-string';

The library ships with TypeScript types. While specific type names like `Host` (which describes elements in the `hosts` array) are not explicitly detailed in the README, they are typically exported for type safety. Developers can explore the generated `.d.ts` files for comprehensive type definitions.

Demonstrates parsing a complex connection string, accessing parsed properties, applying default values, and generating a connection string from an object.

import { ConnectionString } from 'connection-string'; // Parse a complex connection string with multiple hosts and parameters const cs = new ConnectionString('protocol://user:password@host1:123,[abcd::]:456/one/two?p1=val1&msg=hello+world!'); console.log('Parsed Connection String:', JSON.stringify(cs, null, 2)); // Access virtual properties for the first host console.log(`First Host: ${cs.host} Port: ${cs.port}`); // Create a new connection string object and apply defaults const defaultDbCs = new ConnectionString('my-db-server', { protocol: 'postgres', port: 5432, user: 'admin' }); console.log('Connection String with Defaults:', JSON.stringify(defaultDbCs, null, 2)); // Generate a connection string from an object const generatedString = defaultDbCs.toString(); console.log('Generated String:', generatedString);

Debug

Known issues

breakingVersion 5.0.0 removed all Node.js-specific code (e.g., color output support) and migrated the distribution target to ES2020. This means the package now works identically in Node.js and web browsers, but older Node.js-specific functionalities are no longer present.

fix

Ensure your environment supports ES2020. No direct code fix is required if your code didn't rely on the removed Node.js specifics or color output features.

affects: >=5.0.0

breakingThe minimum required Node.js version for `connection-string` v5.0.0 and above is Node.js `>=20.0.0`. Older Node.js versions (e.g., v12, v14, v16, v18) are no longer officially supported.

fix

Upgrade your Node.js runtime to version 20 or newer. For older Node.js environments, use `connection-string` v4.x.

affects: >=5.0.0

gotchaPrior to version 4.3.0, parsing of comma-separated parameters in query strings (e.g., `p=a,b`) or correctly handling URL-encoded commas (`%2C`) for array-like values was inconsistent. This could lead to incorrect parsing of array values.

fix

Upgrade to `connection-string` version 4.3.1 or newer to ensure correct handling of repeated and comma-separated parameters and URL-encoded commas (`%2C`) in query strings.

affects: <4.3.0

gotchaFor browser usage with older tooling or non-ESM setups, you might need to manually browserify the `dist/index.js` file. While v5.0.0 improves browser compatibility by removing Node.js-specifics, direct import without a bundler might still face issues depending on the browser's module support.

fix

Use a bundler like Webpack or Rollup for browser applications, or ensure your environment supports ES Modules for direct import. Refer to the 'Browsers' page in the package's documentation for details.

affects: all

Errors

Common errors & fixes

TypeError: ConnectionString is not a constructor

Attempting to instantiate `ConnectionString` without the `new` keyword, or importing it incorrectly as a default export instead of a named export.

fix

Ensure you are using `new ConnectionString(...)` to create an instance. If using ESM, verify your import is `import { ConnectionString } from 'connection-string';` (named import).

ERR_REQUIRE_ESM or Cannot find module 'connection-string'

Trying to use `require('connection-string')` in an ES Module (`.mjs` or `"type": "module"` in package.json) environment without proper transpilation, or trying to `import` in a CommonJS context.

fix

For ESM, use `import { ConnectionString } from 'connection-string';`. For CommonJS, use `const { ConnectionString } = require('connection-string');`. Ensure your `tsconfig.json` (if applicable) and `package.json` `type` field are configured correctly for your module system.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vitaly-t/connection-string ↗

packagehttps://www.npmjs.com/package/connection-string ↗