@httpx/dsn-parser

DSN & JDBC string parser with query params support in a light (~750B) and modern package.


Install

``bash
$ npm install @httpx/dsn-parser
$ yarn add @httpx/dsn-parser
$ pnpm add @httpx/dsn-parser
`

Features

- 👉  Parse individual fields (ie: driver, user, password, host...)
- 🖖  Handle query string parameters and converts to boolean and numeric values.
- 🦄  Handle special characters like /, :... in the password (some libs won't).
- 🚀  Error with indicative message / reasons (discriminated union or throwable).
- 🛡️  Don't leak passwords in the error message.
- 🙏  Assertion and typeguard helpers
- 🤗  Ecosystem friendly (ie: zod integration).
- ♾️️  Tested on node 20-25, browser, bun, cloudflare workers and runtime/edge.

Documentation

👉 Official website or Github Readme

Usage

$3

Usage with exceptions

`typescript
import { parseDsnOrThrow } from "@httpx/dsn-parser";

const dsn = "redis://user:p@/ssword@localhost:6379/0?ssl=true";

try {
const parsedDsn = parseDsnOrThrow(dsn);
assert.deepEqual(parsedDsn, {
driver: "redis",
pass: "p@/ssword",
host: "localhost",
user: "user",
port: 6379,
db: "0",
params: {
ssl: true,
},
});
} catch (e) {
// example:
// e -> Error("Can't parse dsn: Invalid port: 12345678 (INVALID_PORT)")
}
`

$3

Usage with discriminated union.

`typescript
import { parseDsn } from "@httpx/dsn-parser";

const dsn = "redis://user:p@/ssword@localhost:6379/0?ssl=true";

const parsed = parseDsn(dsn);

if (parsed.success) {
assert.deepEqual(parsed.value, {
driver: "redis",
pass: "p@/ssword",
host: "localhost",
user: "user",
port: 6379,
db: "0",
params: {
ssl: true,
},
});
} else {
assert.deepEqual(parsed, {
success: false,
// Reasons might vary
reason: "INVALID_PORT",
message: "Invalid http port: 12345678",
});
}
`

$3

`typescript
import { parseDsn, type ParseDsnOptions } from "@httpx/dsn-parser";

const dsn = "mySql://localhost:6379/db";
const parsed = parseDsn(dsn, {
lowercaseDriver: true,
// Overrides, allows to force some values (ParseDsnOptions)
overrides: {
db: "db3",
port: undefined,
},
});

assert.deepEqual(parsed.value, {
driver: "mysql",
host: "localhost",
db: "db3",
});
`

| Params | Type | Description |
| ----------------- | ---------------------- | ----------------------------------------- |
| lowercaseDriver | boolean | Driver name in lowercase, default false |
| overrides | ParseDsnOptions | Overrides allows to force specific values |

Utilities

$3

`typescript
import { isParsableDsn, type ParsableDsn } from "@httpx/dsn-parser";

const dsn = "postgresql://localhost:6379/db";

if (isParsableDsn(dsn)) {
// known to be ParsableDsn
}
`

$3

`typescript
import { assertParsableDsn, ParsableDsn } from "@httpx/dsn-parser";

try {
assertParsableDsn("redis:/");
// Type is narrowed to string (ParsableDsn) if it
// didn't throw.
} catch (e) {
assert.equal(e.message, "Cannot parse DSN (PARSE_ERROR)");
}
`

$3

ParsableDsn is a weak opaque type.

`typescript
declare const tag: unique symbol;
export type WeakOpaqueContainer = {
readonly [tag]: Token;
};
export type ParsableDsn = string & WeakOpaqueContainer<'ParsableDsn'>;
`

It can be used to enforce that the isParsableDsn or assertParsableDsn have been
used before usage.

`typescript
import type { ParsableDsn } from "./dsn-parser.type";
import { assertParsableDsn } from "./assert-parsable-dsn";

// to opt-in, just change the dsn param type to ParsableDsn instead of string
const fnWithWeakOpaqueType = (dsn: ParsableDsn) => {
// by explictly requiring a ParsableDsn, we can rely on typescript
// to be sure that a validation has occured before (isParsableDsn or assertParsableDsn)
}

fnWithWeakOpaqueType('redis://localhost'); // ❌ typescript will complain

const dsn = 'redis://localhost';
assertParsableDsn(dsn);
fnWithWeakOpaqueType(dsn); // ✅ working cause it was checked before

`

> PS: WeakOpaque usage is totally optional, a nice to have if applicable

$3

Utility to convert jdbc dsn.
Useful for prisma using sqlserver.

`typescript
import { convertJdbcToDsn } from "@httpx/dsn-parser";

const jdbcDsn =
"sqlserver://localhost:1433;database=my-db;authentication=default;user=sa;password=pass03$;encrypt=true;trustServerCertificate=true";

const dsn = convertJdbcToDsn(jdbc);

// -> 'sqlserver://localhost:1433?database=my-db&authentication=default&user=sa&password=pass03$&encrypt=true&trustServerCertificate=true'
`




DSN parsing

$3

The minimum requirement for dsn parsing is to have a host and
a driver _(/[a-z0-9]+/i)_ defined. All other options are optional.

`typescript
export type ParsedDsn = {
driver: string;
host: string;
user?: string;
pass?: string;
port?: number;
db?: string;
/* Query params /
params?: Record;
};
`

$3

Things like:

`typescript
const validExamples = [
"postgresql://postgres:@localhost:5432/prisma-db",
"redis://us_er-name:P@ass-_:?/ssw/rd@www.example.com:6379/0?cache=true",
//...
];
`

should work.

$3

Simple query parameters are supported (no arrays, no nested). For convenience
it will cast 'true' and 'false' to booleans,
parse numeric string to numbers if possible. When a query
parameter does not contain a value, it will be returned as true.

`typescript
const dsn = "redis://host?index=1&compress=false&ssl";
const parsed = parseDsn(dsn);
assert.deepEqual(parsed.value.params, {
index: 1,
compress: false,
ssl: true,
});
`

$3

parseDsn won't make any assumptions on default values _(i.e: default port for mysql...)_.

$3

parseDsn wraps its result in a discriminated union
to allow the retrieval of validation errors. No try... catchneeded and full typescript support.

Reason codes are guaranteed in semantic versions and messages does not
leak credentials

`typescript
const parsed = parseDsn("redis://localhost:65636");
assert.deepEqual(parsed, {
success: false,
reason: "INVALID_PORT",
message: "Invalid port: 65636",
});
if (!parsed.success) {
// success: false narrows the type to
// {
// reason: 'PARSE_ERROR'|'INVALID_ARGUMENT'|...
// message: string
// }
log(parsed.reason);
}
`

| Reason | Message | Comment |
| -------------------- | ----------------------- | --------------- |
| 'PARSE_ERROR' | Cannot parse DSN | _Regexp failed_ |
| 'INVALID_ARGUMENT' | DSN must be a string | |
| 'EMPTY_DSN' | DSN cannot be empty | |
| 'INVALID_PORT' | Invalid port: ${port} | [1-65535] |

Ecosystem

$3

The isParsableDsn can be easily plugged into zod custom validation. Example:

`typescript
import { z } from "zod";
import { isParsableDsn, type ParsableDsn } from "@httpx/dsn-parser";

export const serverEnvSchema = z.object({
PRISMA_DATABASE_URL: z.custom(
(dsn) => isParsableDsn(dsn),
"Invalid DSN format."
),
});

serverEnvSchema.parse(process.env);
`

Faq

$3

Some libs (ioredis...) still might fail parsing a password containing '/',
unfortunately they're pretty convenient, i.e:

`bash
openssl rand 60 | openssl base64 -A

YFUXIG9INIK7dFyE9aXtxLmjmnYL0zv6YluBJJbC6alKIBema/MwEGy3VUpx0oLAvWHUFGFMagAdLxrB


`

Bundle size

Bundle size is tracked by a size-limit configuration

| Scenario (esm) | Size (compressed) |
|----------------------------------------------------------|------------------:|
| import { parseDsn } from '@httpx/dsn-parser` | ~ 750B |

Compatibility

| Level | CI | Description |
|--------------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Node | ✅ | CI for 20.x, 22.x, 24.x & 25.x. |
| Browser | ✅ | Tested with latest chrome (vitest/playwright) |
| Browserslist | ✅ | > 95% on 01/2025. defaults, chrome >= 96, firefox >= 105, edge >= 113, safari >= 15, ios >= 15, opera >= 103, not dead |
| Bun | ✅ | Tested with latest (at time of writing >= 1.3.3) |
| Edge | ✅ | Ensured on CI with @vercel/edge-runtime. |
| Cloudflare | ✅ | Ensured with @cloudflare/vitest-pool-workers (see wrangler.toml |
| Typescript | ✅ | TS 5.0 + / are-the-type-wrong checks on CI. |
| ES2022 | ✅ | Dist files checked with es-check |

> For _older_ browsers: most frontend frameworks can transpile the library (ie: nextjs...)

Contributors

Contributions are warmly appreciated. Have a look to the CONTRIBUTING document.

Sponsors

If my OSS work brightens your day, let's take it to new heights together!
Sponsor>), coffee>),
or star – any gesture of support fuels my passion to improve. Thanks for being awesome! 🙏❤️

$3

JetBrains	Embie.be

License

MIT © belgattitude and contributors.