{"id":12992,"library":"connection-string","title":"Connection String Parser & Generator","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/vitaly-t/connection-string","tags":["javascript","connection","string","parser","generator","typescript"],"install":[{"cmd":"npm install connection-string","lang":"bash","label":"npm"},{"cmd":"yarn add connection-string","lang":"bash","label":"yarn"},{"cmd":"pnpm add connection-string","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `ConnectionString` class is a named export. The package targets ES2020 and is optimized for ES Modules (ESM) since v5.0.0.","wrong":"import ConnectionString from 'connection-string';","symbol":"ConnectionString","correct":"import { ConnectionString } from 'connection-string';"},{"note":"This pattern is for CommonJS (CJS) environments. For modern Node.js and browser applications, the ESM `import` is the recommended standard.","wrong":"const ConnectionString = require('connection-string');","symbol":"ConnectionString (CommonJS)","correct":"const { ConnectionString } = require('connection-string');"},{"note":"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.","symbol":"Host Type","correct":"import type { Host } from 'connection-string';"}],"quickstart":{"code":"import { ConnectionString } from 'connection-string';\n\n// Parse a complex connection string with multiple hosts and parameters\nconst cs = new ConnectionString('protocol://user:password@host1:123,[abcd::]:456/one/two?p1=val1&msg=hello+world!');\n\nconsole.log('Parsed Connection String:', JSON.stringify(cs, null, 2));\n\n// Access virtual properties for the first host\nconsole.log(`First Host: ${cs.host} Port: ${cs.port}`);\n\n// Create a new connection string object and apply defaults\nconst defaultDbCs = new ConnectionString('my-db-server', {\n  protocol: 'postgres',\n  port: 5432,\n  user: 'admin'\n});\n\nconsole.log('Connection String with Defaults:', JSON.stringify(defaultDbCs, null, 2));\n\n// Generate a connection string from an object\nconst generatedString = defaultDbCs.toString();\nconsole.log('Generated String:', generatedString);","lang":"typescript","description":"Demonstrates parsing a complex connection string, accessing parsed properties, applying default values, and generating a connection string from an object."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js runtime to version 20 or newer. For older Node.js environments, use `connection-string` v4.x.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<4.3.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to instantiate `ConnectionString` without the `new` keyword, or importing it incorrectly as a default export instead of a named export.","error":"TypeError: ConnectionString is not a constructor"},{"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.","cause":"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.","error":"ERR_REQUIRE_ESM or Cannot find module 'connection-string'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}