Connection String Parser

Common errors

• URIError: URI malformed

  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.
  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.

• TypeError: Cannot read properties of undefined (reading 'property')

  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.
  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.

Warnings

• gotcha 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.
  Fix: Before constructing the full connection string, ensure all variable parts are passed through `encodeURIComponent()`. For example, `mongodb://${encodeURIComponent(user)}:${encodeURIComponent(pass)}@...`
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install connection-string-parser npm
• yarn add connection-string-parser yarn
• pnpm add connection-string-parser pnpm

Imports

• ConnectionStringParser
  wrong:

  const ConnectionStringParser = require('connection-string-parser');

  correct:

  import { ConnectionStringParser } from 'connection-string-parser';

  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.
• ConnectionStringParserOptions
  wrong:

  import { ConnectionStringParserOptions } from 'connection-string-parser';

  correct:

  import type { ConnectionStringParserOptions } from 'connection-string-parser';

  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.
• IConnectionString
  wrong:

  import { IConnectionString } from 'connection-string-parser';

  correct:

  import type { IConnectionString } from 'connection-string-parser';

  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.

Quickstart

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.

import { ConnectionStringParser, IConnectionString } from "connection-string-parser";

const connectionStringParser = new ConnectionStringParser({
	scheme: "mongodb",
	hosts: []
});

const connectionString = "mongodb://s%23perus%24r:unbr%23k%40bl%24@ho%24t:1234/%24my-db?replicaSet=%24super%40";
const connectionObject: IConnectionString = connectionStringParser.parse(connectionString);

console.log("Parsed Connection Object:", connectionObject);
// Expected output:
// {
//   scheme: 'mongodb',
//   hosts: [ { host: 'ho$t', port: 1234 } ],
//   username: 's#perus$r',
//   password: 'unbr#k@bl$',
//   database: '$my-db',
//   options: { replicaSet: '$super@' }
// }