location-context-resolver

Getting started

Install#

npm i @dmytromykhailiuk/location-context-resolver

Quick start#

Create the resolver once at module scope. Call it wherever the current location is needed — every call reads the location afresh.

import { createLocationContextResolver } from "@dmytromykhailiuk/location-context-resolver";

const resolveLocationContext = createLocationContextResolver({
  remoteOrigin: "https://remote.example.com",
  applicationBasePath: "/my-app",
});

// current URL: https://host.example.com/my-app/users/42?tab=posts
const context = resolveLocationContext();

context.origin;                  // "https://host.example.com"
context.remoteOrigin;            // "https://remote.example.com"
context.applicationOrigin;       // "https://host.example.com/my-app"
context.remoteApplicationOrigin; // "https://remote.example.com/my-app"
context.pathname;                // "/users/42" — relative to the base path
context.queryParams.get("tab");  // "posts"

The context is frozen and fully typed — see The context object for every field, and Base path for exactly how pathname is derived.

One topology, two origins#

The library's one opinion: where the application lives — its remote origin, its base path — is configuration, declared once; where the user is right now is state, read at call time. The resolver is the border between the two.

import { createLocationContextResolver } from "@dmytromykhailiuk/location-context-resolver";

export const resolveLocationContext = createLocationContextResolver({
  remoteOrigin: import.meta.env.VITE_REMOTE_ORIGIN,
  applicationBasePath: import.meta.env.BASE_URL,
});

// anywhere else in the app
import { resolveLocationContext } from "./location";
const { remoteApplicationOrigin, pathname } = resolveLocationContext();
fetch(`${remoteApplicationOrigin}/api${pathname}`);

Creating the resolver never reads the location — module scope is safe in any environment, SSR included. Only the call does; see SSR & custom locations. The one thing validated at creation is the configuration itself:

createLocationContextResolver({ remoteOrigin: "" });
// Error: "remoteOrigin" must be a non-empty string

A resolver that can't name its remote is a configuration bug — an env variable that didn't load — worth failing loudly on, at startup, not at the first navigation.

Reference

createLocationContextResolver#

function createLocationContextResolver(options: {
  remoteOrigin: string;
  applicationBasePath?: string;
  location?: LocationLike | (() => LocationLike);
  onBasePathMismatch?: (pathname: string, applicationBasePath: string) => void;
}): LocationContextResolver;

type LocationContextResolver = () => LocationContext;

Options#

The context object#

Every call returns a fresh, frozen LocationContext — a snapshot of the location at that moment. All fields are readonly.

Base path#

When an application is mounted under a prefix, two views of the pathname coexist: the document's — /my-app/users/42 — and the application's — /users/42. Routers, analytics and links inside the app think in the second one; window.location only offers the first. applicationBasePath is the bridge: declare the prefix once and pathname comes back relative.

Normalization#

Slashes on either end are optional — all four spellings configure the same base path, so it can come straight from an env variable or a bundler constant without ceremony:

// all equivalent:
applicationBasePath: "/my-app"
applicationBasePath: "my-app"
applicationBasePath: "my-app/"
applicationBasePath: "/my-app/"

// multi-segment prefixes work the same way:
applicationBasePath: "/org/my-app"

Matching & mismatches#

Stripping happens only at a segment boundary — a pathname that merely starts with the base path as a string belongs to a different app and is left alone:

A pathname outside the base path is never mangled — the naive pathname.split(basePath)[1] would hand you undefined or a fragment cut in the middle of a word. Instead the full pathname is returned unchanged, and the mismatch is reported through onBasePathMismatch:

const resolveLocationContext = createLocationContextResolver({
  remoteOrigin: "https://remote.example.com",
  applicationBasePath: "/my-app",
  onBasePathMismatch: (pathname, basePath) => report({ pathname, basePath }),
});

// at /other/users:
resolveLocationContext().pathname; // "/other/users" — unchanged, mismatch reported

The default handler is a console.warn naming the library, the pathname and the base path — a misconfigured mount is visible in development even when you configure nothing, and navigation keeps working either way.

Query params#

queryParams is a standard URLSearchParams built from the current query string — decoding, repeated keys and iteration all behave exactly as the platform defines them:

// at /my-app/search?q=hello%20world&tag=a&tag=b
const { queryParams } = resolveLocationContext();

queryParams.get("q");       // "hello world"
queryParams.getAll("tag");  // ["a", "b"]
queryParams.has("missing"); // false
[...queryParams.entries()]; // [["q", "hello world"], ["tag", "a"], ["tag", "b"]]

Each resolve builds a fresh instance. URLSearchParams is mutable by design — the freeze on the context can't reach inside it — so the fresh copy is what keeps snapshots independent: mutate one to build a link, and the next resolve still reflects the URL, not your edits.

const a = resolveLocationContext();
a.queryParams.set("page", "2");          // building the "next page" link
const href = `?${a.queryParams}`;        // "?q=hello+world&tag=a&tag=b&page=2"

resolveLocationContext().queryParams.get("page"); // null — the URL didn't change

SSR & custom locations#

By default the resolver reads globalThis.location — the browser's. The split matters for everywhere else: creating a resolver never touches the location, so a module that calls createLocationContextResolver at top level imports cleanly in Node, workers and tests. Only calling the resolver needs a location — and where there is none, it throws a clear error naming the fix rather than resolving to something made up.

To run outside the browser, pass the location in — an object for a fixed snapshot, or a function read on every resolve:

const url = new URL(request.url);

const resolveLocationContext = createLocationContextResolver({
  remoteOrigin: "https://remote.example.com",
  applicationBasePath: "/my-app",
  location: { origin: url.origin, pathname: url.pathname, search: url.search },
});

resolveLocationContext().pathname; // relative to /my-app — same as in the browser

const resolveLocationContext = createLocationContextResolver({
  remoteOrigin: "https://remote.example.com",
  location: () => currentRequest.location, // whatever is current at call time
});

TypeScript#

Everything is typed end to end: the options object requires remoteOrigin — forgetting it is a compile error, not a runtime surprise — and every context field is readonly, so the type system enforces the same immutability the runtime freeze does.

import type {
  LocationContext,
  LocationContextResolver,
  LocationContextResolverOptions,
  LocationLike,
} from "@dmytromykhailiuk/location-context-resolver";

const resolve: LocationContextResolver = createLocationContextResolver({
  remoteOrigin: "https://remote.example.com",
});

const context: LocationContext = resolve();
context.pathname;              // string
context.queryParams;           // URLSearchParams
// @ts-expect-error — readonly
context.pathname = "/other";

LocationLike is deliberately the smallest usable shape — origin, pathname, search. Structural typing does the rest: the DOM's Location is assignable to it, and in tests a plain object literal is all a fake needs.

Exports#

Values

createLocationContextResolver

Types

LocationContext · LocationContextResolver · LocationContextResolverOptions · LocationLike