Registry / serialization / connection-string-parser

connection-string-parser

library1.0.4jsnpmunverified

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.

serialization database

npm install connection-string-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CONNECTION-STRING-

connection-string-parser

serializationjavascriptv1.0.4

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.

ConnectionStringParser

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

✗ const ConnectionStringParser = require('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

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

✗ import { 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

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

✗ import { 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.

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@' } // }

Debug

Known issues

gotchaAll 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)}@...`

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

URIError: URI malformed

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')

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.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sindilevich/connection-string-parser ↗

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