{"id":15990,"library":"connection-string-parser","title":"Connection String Parser","description":"The `connection-string-parser` library provides a generic, cross-environment solution for converting URI-based connection strings into structured JSON objects and vice-versa. It supports both Node.js and browser environments, addressing a common problem where applications need to consume compact URI strings (e.g., `mongodb://user:pass@host/db?options`) but underlying connection tools require a JSON configuration object. The current stable version is 1.0.4. The library is written in TypeScript and ships with type definitions. It differentiates itself by offering a flexible, scheme-agnostic parsing mechanism, allowing developers to define custom URI patterns beyond standard database connection strings, making it suitable for various project-specific configurations. Its release cadence appears to be stable, focusing on robust utility.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/sindilevich/connection-string-parser","tags":["javascript","database","database-connection","connection-string","parser","typescript","nodejs","browser"],"install":[{"cmd":"npm install connection-string-parser","lang":"bash","label":"npm"},{"cmd":"yarn add connection-string-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add connection-string-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary class for creating parser instances. While CommonJS `require` might technically work in some setups, idiomatic usage for modern TypeScript/ESM projects is the named import.","wrong":"const ConnectionStringParser = require('connection-string-parser');","symbol":"ConnectionStringParser","correct":"import { ConnectionStringParser } from 'connection-string-parser';"},{"note":"Used for defining the configuration options when initializing a `ConnectionStringParser` instance. Imported using `import type` to denote it's a type-only import, which is tree-shakeable and prevents runtime issues.","wrong":"import { ConnectionStringParserOptions } from 'connection-string-parser';","symbol":"ConnectionStringParserOptions","correct":"import type { ConnectionStringParserOptions } from 'connection-string-parser';"},{"note":"Represents the structure of the object returned by the `parse` method, containing decoded connection components like scheme, hosts, and options. Use `import type` for type-only imports.","wrong":"import { IConnectionString } from 'connection-string-parser';","symbol":"IConnectionString","correct":"import type { IConnectionString } from 'connection-string-parser';"}],"quickstart":{"code":"import { ConnectionStringParser, IConnectionString } from \"connection-string-parser\";\n\nconst connectionStringParser = new ConnectionStringParser({\n\tscheme: \"mongodb\",\n\thosts: []\n});\n\nconst connectionString = \"mongodb://s%23perus%24r:unbr%23k%40bl%24@ho%24t:1234/%24my-db?replicaSet=%24super%40\";\nconst connectionObject: IConnectionString = connectionStringParser.parse(connectionString);\n\nconsole.log(\"Parsed Connection Object:\", connectionObject);\n// Expected output:\n// {\n//   scheme: 'mongodb',\n//   hosts: [ { host: 'ho$t', port: 1234 } ],\n//   username: 's#perus$r',\n//   password: 'unbr#k@bl$',\n//   database: '$my-db',\n//   options: { replicaSet: '$super@' }\n// }","lang":"typescript","description":"Demonstrates how to initialize the parser with a scheme and parse a URI-encoded connection string into a structured connection object, showing key components like scheme, hosts, credentials, and options."},"warnings":[{"fix":"Before constructing the full connection string, ensure all variable parts are passed through `encodeURIComponent()`. For example, `mongodb://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@...`","message":"All components of an input connection string (username, password, host, database, options values) *must be manually URI-encoded* before being passed to the `parse` method. The library automatically decodes them, but will not encode them on input, leading to incorrect parsing if not pre-encoded.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the `scheme` property provided during `ConnectionStringParser` instantiation exactly matches the scheme of the connection string you intend to parse. Validate the output object for completeness.","message":"The `ConnectionStringParser` instance is initialized with a specific `scheme` (e.g., `{ scheme: 'mongodb' }`). If the input connection string's scheme does not match this configured scheme, the parser may return an empty or incomplete connection object without throwing an error, leading to silent failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official GitHub repository or source code for examples and detailed usage of the `format` method, if you need to convert a connection object back into a connection string.","message":"While the library is described as both a parser and formatter, the provided documentation excerpt primarily focuses on parsing. Users attempting to convert a connection object back to a string might need to consult the full API documentation for the `format` method, which is not directly demonstrated in the quickstart.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Manually apply `encodeURIComponent()` to each non-literal component (username, password, database, options values) of your connection string before passing the complete string to the parser. Ensure the overall string follows the expected URI format.","cause":"The connection string or one of its components contains invalid URI sequences, likely due to improper or missing `encodeURIComponent` calls before parsing, or it's simply malformed.","error":"URIError: URI malformed"},{"fix":"Verify that the `ConnectionStringParser` instance was configured with the correct `scheme` matching the input string. Always check the returned object for existence and expected structure before accessing its properties.","cause":"Attempting to access properties of the parsed connection object when the parsing failed (e.g., due to a scheme mismatch) and the object is `null`, `undefined`, or incomplete.","error":"TypeError: Cannot read properties of undefined (reading 'property')"}],"ecosystem":"npm"}