Class: Uri

Defined in: packages/core/src/http/Uri.ts:150

Fluent, immutable URI value object. Parse an absolute or relative URL, read its parts, and rewrite scheme/host/path/query/fragment — every mutator returns a NEW Uri, so instances are safe to share and reuse.

Construct via the uri helper or the static factories (Uri.of, Uri.to, Uri.current, Uri.route). For app-aware URL generation and signing, see the higher-level Url / url service.

Example

Uri.of("https://example.com/users?page=1")
  .withQuery({ page: 2, sort: "name" })
  .withFragment("top")
  .value(); // "https://example.com/users?page=2&sort=name#top"

Throws

from Uri.url (and, transitively, Uri.current) when called on a relative URI that has no host.

Components

scheme()

scheme(): string | undefined

Defined in: packages/core/src/http/Uri.ts:205

The scheme (e.g. "https"), or undefined for a relative URI.

Returns

string | undefined

user()

user(): string | undefined

Defined in: packages/core/src/http/Uri.ts:212

The decoded userinfo username, or undefined.

Returns

string | undefined

password()

password(): string | undefined

Defined in: packages/core/src/http/Uri.ts:219

The decoded userinfo password, or undefined.

Returns

string | undefined

host()

host(): string | undefined

Defined in: packages/core/src/http/Uri.ts:226

The host (without port), or undefined for a relative URI.

Returns

string | undefined

port()

port(): number | undefined

Defined in: packages/core/src/http/Uri.ts:233

The port number, or undefined when none is set.

Returns

number | undefined

path()

path(): string

Defined in: packages/core/src/http/Uri.ts:240

The path component (may be empty).

Returns

string

fragment()

fragment(): string | undefined

Defined in: packages/core/src/http/Uri.ts:247

The fragment (without the leading #), or undefined.

Returns

string | undefined

withScheme()

withScheme(scheme): Uri

Defined in: packages/core/src/http/Uri.ts:300

Return a copy with the scheme replaced (trailing :// is stripped).

Parameters

scheme

string

Returns

Uri

withUser()

withUser(user, password?): Uri

Defined in: packages/core/src/http/Uri.ts:307

Return a copy with the userinfo username (and optional password) set.

Parameters

user

string | undefined

password?

string

Returns

Uri

withPassword()

withPassword(password): Uri

Defined in: packages/core/src/http/Uri.ts:314

Return a copy with the userinfo password set.

Parameters

password

string | undefined

Returns

Uri

withHost()

withHost(host): Uri

Defined in: packages/core/src/http/Uri.ts:321

Return a copy with the host replaced.

Parameters

host

string

Returns

Uri

withPort()

withPort(port): Uri

Defined in: packages/core/src/http/Uri.ts:328

Return a copy with the port set (pass undefined to remove it).

Parameters

port

number | undefined

Returns

Uri

withPath()

withPath(path): Uri

Defined in: packages/core/src/http/Uri.ts:335

Return a copy with the path replaced; a non-empty path is given a leading slash.

Parameters

path

string

Returns

Uri

withFragment()

withFragment(fragment): Uri

Defined in: packages/core/src/http/Uri.ts:342

Return a copy with the fragment set (pass undefined to remove it).

Parameters

fragment

string | undefined

Returns

Uri

Construction

of()

static of(value): Uri

Defined in: packages/core/src/http/Uri.ts:163

Build a Uri from a string (or clone another Uri).

Parameters

value

string | Uri

Returns

Uri

to()

static to(path): Uri

Defined in: packages/core/src/http/Uri.ts:172

Build an absolute Uri for path, relative to the app URL (config('app.url')).

Parameters

path

string

Returns

Uri

current()

static current(): Uri

Defined in: packages/core/src/http/Uri.ts:183

The current request's full URL.

Returns

Uri

Throws

when called outside an active HTTP request.

route()

static route(name, params?): Uri

Defined in: packages/core/src/http/Uri.ts:191

Build a Uri from a named route + params.

Parameters

name

string

params?

Record<string, string | number> = {}

Returns

Uri

intended()

intended(fallback?): Uri

Defined in: packages/core/src/http/Uri.ts:411

Resolve the URL the user was heading to before authentication (the session's intended_url, set by RequireAuth), falling back to fallback. Cross-origin stored URLs are rejected (open-redirect guard). Returns a fresh Uri pointing at the resolved target.

Parameters

fallback?

string = "/"

Returns

Uri

Example

return uri().intended("/dashboard").redirect();

Output

url()

url(): string

Defined in: packages/core/src/http/Uri.ts:255

The assembled absolute URL string.

Returns

string

Throws

when the URI is relative (has no host).

redirect()

redirect(status?): ResponseBuilder

Defined in: packages/core/src/http/Uri.ts:427

Issue a redirect to this URI, returning a ResponseBuilder for flash chaining.

Parameters

status?

301 | 302 | 303 | 307 | 308

Returns

ResponseBuilder

Throws

when called outside an active HTTP request.

value()

value(): string

Defined in: packages/core/src/http/Uri.ts:440

The assembled URI string. Unlike Uri.url, this works for both absolute and relative URIs.

Returns

string

toString()

toString(): string

Defined in: packages/core/src/http/Uri.ts:466

Alias for Uri.value — enables string coercion and template literals.

Returns

string

toJSON()

toJSON(): string

Defined in: packages/core/src/http/Uri.ts:474

Serialize to the URI string when passed to JSON.stringify.

Returns

string

Query

query()

query(): UriQueryString

Defined in: packages/core/src/http/Uri.ts:277

A read-only view over the query string.

Returns

UriQueryString

withQuery()

withQuery(query): Uri

Defined in: packages/core/src/http/Uri.ts:350

Merge the given parameters into the query string (overwriting existing keys).

Parameters

query

QueryInput

Returns

Uri

withQueryIfMissing()

withQueryIfMissing(query): Uri

Defined in: packages/core/src/http/Uri.ts:358

Add parameters only when their key is not already present.

Parameters

query

QueryInput

Returns

Uri

replaceQuery()

replaceQuery(query): Uri

Defined in: packages/core/src/http/Uri.ts:370

Replace the entire query string with the given parameters.

Parameters

query

QueryInput

Returns

Uri

pushOntoQuery()

pushOntoQuery(key, value): Uri

Defined in: packages/core/src/http/Uri.ts:378

Append a value to a key, turning it into a multi-value parameter.

Parameters

key

string

value

string | number

Returns

Uri

withoutQuery()

withoutQuery(keys): Uri

Defined in: packages/core/src/http/Uri.ts:393

Remove one or more keys from the query string.

Parameters

keys

string[]

Returns

Uri