@securitydept/client 0.2.0 → 0.3.0-beta.10

package/dist/test/index.mjs

@@ -0,0 +1,270 @@
+import { H as ClientError, U as ClientErrorKind, j as SYMBOL_OBSERVABLE } from "../rx-DM6Ouv-m.mjs";
+import { $ as notMissingProvider, I as PopupAttachFailureReason, O as RouterNavigationMode, Q as getSecuritydeptProviderToken, R as throwValidationClientError, T as TIME_TRAIT_TOKEN, Z as createProviderIfTokenMissing, c as createInMemoryRecordStore, h as TRANSPORT_TRAIT_TOKEN, t as createFoundationEnvironment, z as validateTraitInput } from "../create-i5VyYgN6.mjs";
+import { n as UriReferenceString } from "../uri-string-BPNbIMgv.mjs";
+import { type } from "arktype";
+//#region src/test/time.ts
+const TimeForTestCreateOptionsSchema = type({ initialNow: "number" });
+function createTimeForTest(options = {}) {
+	const { validators, ...createOptions } = options;
+	const resolvedCreateOptions = { initialNow: createOptions.initialNow ?? 0 };
+	validateTraitInput({
+		value: resolvedCreateOptions,
+		bundledSchema: TimeForTestCreateOptionsSchema,
+		validator: validators?.time,
+		onInvalid: (failure) => throwValidationClientError({
+			code: "test.time.invalid_options",
+			source: "test",
+			messagePrefix: "createTimeForTest could not validate time",
+			failure
+		})
+	});
+	let now = resolvedCreateOptions.initialNow;
+	let nextId = 1;
+	const tasks = /* @__PURE__ */ new Map();
+	return {
+		now: () => now,
+		setTimeout(handler, delayMs) {
+			const id = nextId++;
+			tasks.set(id, {
+				at: now + Math.max(0, delayMs),
+				handler
+			});
+			return id;
+		},
+		clearTimeout(handle) {
+			if (typeof handle === "number") tasks.delete(handle);
+		},
+		advance(ms) {
+			now += ms;
+		},
+		flush() {
+			let progressed = true;
+			while (progressed) {
+				progressed = false;
+				const ready = [...tasks.entries()].filter(([, task]) => task.at <= now).sort((a, b) => a[1].at - b[1].at);
+				for (const [id, task] of ready) {
+					tasks.delete(id);
+					task.handler();
+					progressed = true;
+				}
+			}
+		},
+		advanceAndFlush(ms) {
+			this.advance(ms);
+			this.flush();
+		},
+		get pendingCount() {
+			return tasks.size;
+		}
+	};
+}
+//#endregion
+//#region src/test/environment.ts
+function createEnvironmentForTest(options = {}) {
+	const { createBaseEnvironment = createFoundationEnvironment, transport, providers = [], ...baseOptions } = options;
+	const externalProviderTokens = new Set(providers.map((provider) => getSecuritydeptProviderToken(provider)));
+	const testProviders = [createProviderIfTokenMissing(externalProviderTokens, TRANSPORT_TRAIT_TOKEN, () => ({
+		provide: TRANSPORT_TRAIT_TOKEN,
+		useValue: transport ?? createMissingTransportForTest()
+	})), createProviderIfTokenMissing(externalProviderTokens, TIME_TRAIT_TOKEN, () => ({
+		provide: TIME_TRAIT_TOKEN,
+		useValue: baseOptions.time ?? createTimeForTest({ initialNow: Date.now() })
+	}))].filter(notMissingProvider);
+	return createBaseEnvironment({
+		...baseOptions,
+		providers: [...testProviders, ...providers]
+	});
+}
+function createMissingTransportForTest() {
+	return { async execute() {
+		throw new Error("Test environment transport was not provided.");
+	} };
+}
+//#endregion
+//#region src/test/idle-callback.ts
+function createIdleCallbackForTest() {
+	let nextId = 1;
+	const callbacks = /* @__PURE__ */ new Map();
+	return {
+		requestIdleCallback(callback) {
+			const id = nextId++;
+			callbacks.set(id, callback);
+			return id;
+		},
+		cancelIdleCallback(handle) {
+			if (typeof handle === "number") callbacks.delete(handle);
+		},
+		flush() {
+			const ready = [...callbacks.entries()];
+			callbacks.clear();
+			for (const [, callback] of ready) callback();
+		},
+		get pendingCount() {
+			return callbacks.size;
+		}
+	};
+}
+//#endregion
+//#region src/test/page-lifecycle.ts
+function createPageLifecycleForTest() {
+	return { resume: createEventSubjectForTest() };
+}
+function createEventSubjectForTest() {
+	const observers = /* @__PURE__ */ new Set();
+	return {
+		subscribe(observer) {
+			observers.add(observer);
+			return { unsubscribe() {
+				observers.delete(observer);
+			} };
+		},
+		next(value) {
+			for (const observer of [...observers]) observer.next?.(value);
+		},
+		error(error) {
+			for (const observer of [...observers]) observer.error?.(error);
+		},
+		complete() {
+			for (const observer of [...observers]) observer.complete?.();
+			observers.clear();
+		},
+		get observerCount() {
+			return observers.size;
+		},
+		[SYMBOL_OBSERVABLE]() {
+			return this;
+		}
+	};
+}
+//#endregion
+//#region src/test/popup.ts
+function createPopupForTest(options = {}) {
+	const openCalls = [];
+	let attachResult = options.attachResult ?? createMissingOpenerAttachFailure();
+	return {
+		open(url, openOptions) {
+			openCalls.push({
+				url,
+				options: openOptions
+			});
+			throw new Error("Test popup open was not configured.");
+		},
+		attach() {
+			return attachResult;
+		},
+		get openCalls() {
+			return openCalls;
+		},
+		setAttachResult(result) {
+			attachResult = result;
+		}
+	};
+}
+function createMissingOpenerAttachFailure() {
+	return {
+		kind: "failure",
+		reason: PopupAttachFailureReason.MissingOpener,
+		error: new ClientError({
+			kind: ClientErrorKind.Configuration,
+			code: "test.popup.missing_opener",
+			source: "test",
+			message: "Test popup attach was not configured."
+		})
+	};
+}
+//#endregion
+//#region src/test/router.ts
+function createRouterForTest(options = {}) {
+	let currentUrl = options.currentUrl == null ? null : UriReferenceString.parse(options.currentUrl);
+	const navigations = [];
+	return {
+		currentUrl() {
+			return currentUrl;
+		},
+		setCurrentUrl(url) {
+			currentUrl = url == null ? null : UriReferenceString.parse(url);
+		},
+		get navigations() {
+			return navigations;
+		},
+		async navigate(request) {
+			navigations.push(request);
+			if (request.mode === RouterNavigationMode.Push || request.mode === RouterNavigationMode.Replace) currentUrl = request.url;
+			await options.onNavigate?.(request);
+		}
+	};
+}
+//#endregion
+//#region src/test/storage.ts
+const StorageForTestCreateOptionsSchema = type({
+	initialEntries: "object",
+	validatorKey: "'persistentStorage' | 'sessionStorage'"
+});
+function createStorageForTest(options = {}) {
+	const { validators, ...createOptions } = options;
+	const validatorKey = options.validatorKey ?? "persistentStorage";
+	const resolvedCreateOptions = {
+		initialEntries: createOptions.initialEntries ?? {},
+		validatorKey
+	};
+	validateTraitInput({
+		value: resolvedCreateOptions,
+		bundledSchema: StorageForTestCreateOptionsSchema,
+		validator: validators?.[validatorKey],
+		onInvalid: (failure) => throwValidationClientError({
+			code: "test.storage.invalid_options",
+			source: "test",
+			messagePrefix: `createStorageForTest could not validate ${validatorKey}`,
+			failure
+		})
+	});
+	const storage = createInMemoryRecordStore();
+	for (const [key, value] of Object.entries(resolvedCreateOptions.initialEntries)) storage.set(key, value);
+	return storage;
+}
+//#endregion
+//#region src/test/transport.ts
+function createTransportForTest(options = {}) {
+	const routes = [...options.routes ?? []];
+	const history = [];
+	let fallback = options.fallback ?? createNotFoundResponseForTest();
+	return {
+		on(predicate, handler) {
+			routes.push({
+				predicate,
+				handler
+			});
+			return this;
+		},
+		onRequest(method, urlPrefix, response) {
+			return this.on((request) => request.method.toUpperCase() === method.toUpperCase() && request.url.startsWith(urlPrefix), () => response);
+		},
+		setFallback(response) {
+			fallback = response;
+			return this;
+		},
+		reset() {
+			routes.length = 0;
+			history.length = 0;
+		},
+		get history() {
+			return history;
+		},
+		async execute(request) {
+			history.push(request);
+			for (const route of routes) if (route.predicate(request)) return route.handler(request);
+			return fallback;
+		}
+	};
+}
+function createNotFoundResponseForTest() {
+	return {
+		status: 404,
+		headers: {},
+		body: { error: "No matching test transport route" }
+	};
+}
+//#endregion
+export { createEnvironmentForTest, createEventSubjectForTest, createIdleCallbackForTest, createPageLifecycleForTest, createPopupForTest, createRouterForTest, createStorageForTest, createTimeForTest, createTransportForTest };
+
+//# sourceMappingURL=index.mjs.map

package/dist/test/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["defineType","defineType"],"sources":["../../src/test/time.ts","../../src/test/environment.ts","../../src/test/idle-callback.ts","../../src/test/page-lifecycle.ts","../../src/test/popup.ts","../../src/test/router.ts","../../src/test/storage.ts","../../src/test/transport.ts"],"sourcesContent":["import { type as defineType } from \"arktype\";\nimport { type EnvironmentValidators } from \"../environment/types\";\nimport { type TimeTrait } from \"../scheduling/types\";\nimport {\n\tthrowValidationClientError,\n\tvalidateTraitInput,\n\ttype WithTraitInputValidator,\n} from \"../validation\";\n\nexport interface TestTimeTrait extends TimeTrait {\n\tadvance(ms: number): void;\n\tflush(): void;\n\tadvanceAndFlush(ms: number): void;\n\tget pendingCount(): number;\n}\n\nexport interface TimeForTestCreateOptions {\n\tinitialNow?: number;\n}\n\nconst TimeForTestCreateOptionsSchema = defineType({\n\tinitialNow: \"number\",\n});\n\nexport function createTimeForTest(\n\toptions: TimeForTestCreateOptions &\n\t\tWithTraitInputValidator<Pick<EnvironmentValidators, \"time\">> = {},\n): TestTimeTrait {\n\tconst { validators, ...createOptions } = options;\n\tconst resolvedCreateOptions = {\n\t\tinitialNow: createOptions.initialNow ?? 0,\n\t};\n\tvalidateTraitInput({\n\t\tvalue: resolvedCreateOptions,\n\t\tbundledSchema: TimeForTestCreateOptionsSchema,\n\t\tvalidator: validators?.time,\n\t\tonInvalid: (failure) =>\n\t\t\tthrowValidationClientError({\n\t\t\t\tcode: \"test.time.invalid_options\",\n\t\t\t\tsource: \"test\",\n\t\t\t\tmessagePrefix: \"createTimeForTest could not validate time\",\n\t\t\t\tfailure,\n\t\t\t}),\n\t});\n\tlet now = resolvedCreateOptions.initialNow;\n\tlet nextId = 1;\n\tconst tasks = new Map<number, { at: number; handler: () => void }>();\n\treturn {\n\t\tnow: () => now,\n\t\tsetTimeout(handler, delayMs) {\n\t\t\tconst id = nextId++;\n\t\t\ttasks.set(id, { at: now + Math.max(0, delayMs), handler });\n\t\t\treturn id;\n\t\t},\n\t\tclearTimeout(handle) {\n\t\t\tif (typeof handle === \"number\") {\n\t\t\t\ttasks.delete(handle);\n\t\t\t}\n\t\t},\n\t\tadvance(ms) {\n\t\t\tnow += ms;\n\t\t},\n\t\tflush() {\n\t\t\tlet progressed = true;\n\t\t\twhile (progressed) {\n\t\t\t\tprogressed = false;\n\t\t\t\tconst ready = [...tasks.entries()]\n\t\t\t\t\t.filter(([, task]) => task.at <= now)\n\t\t\t\t\t.sort((a, b) => a[1].at - b[1].at);\n\t\t\t\tfor (const [id, task] of ready) {\n\t\t\t\t\ttasks.delete(id);\n\t\t\t\t\ttask.handler();\n\t\t\t\t\tprogressed = true;\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t\tadvanceAndFlush(ms) {\n\t\t\tthis.advance(ms);\n\t\t\tthis.flush();\n\t\t},\n\t\tget pendingCount() {\n\t\t\treturn tasks.size;\n\t\t},\n\t};\n}\n","import {\n\ttype CreateFoundationEnvironmentOptions,\n\tcreateFoundationEnvironment,\n} from \"../environment/create\";\nimport { type FoundationEnvironment } from \"../environment/types\";\nimport {\n\tcreateProviderIfTokenMissing,\n\tgetSecuritydeptProviderToken,\n\tnotMissingProvider,\n\ttype SecuritydeptProvider,\n} from \"../injection\";\nimport { TIME_TRAIT_TOKEN, type TimeTrait } from \"../scheduling/types\";\nimport {\n\ttype BaseTransportTrait,\n\tTRANSPORT_TRAIT_TOKEN,\n} from \"../transport/types\";\nimport { createTimeForTest } from \"./time\";\n\nexport type EnvironmentCreatorOptions = {\n\tproviders?: readonly SecuritydeptProvider[];\n};\n\nexport type EnvironmentCreator<\n\tTOptions extends EnvironmentCreatorOptions,\n\tTEnvironment extends FoundationEnvironment,\n> = (options: TOptions) => TEnvironment;\n\nexport interface CreateEnvironmentForTestOptions\n\textends Omit<CreateFoundationEnvironmentOptions, \"transport\"> {\n\ttransport?: BaseTransportTrait;\n\ttime?: TimeTrait;\n}\n\nexport type CreateEnvironmentForTestWithBaseOptions<\n\tTBaseOptions extends EnvironmentCreatorOptions,\n\tTEnvironment extends FoundationEnvironment,\n> = Omit<TBaseOptions, \"providers\" | \"transport\" | \"createBaseEnvironment\"> & {\n\tcreateBaseEnvironment: EnvironmentCreator<TBaseOptions, TEnvironment>;\n\ttransport?: BaseTransportTrait;\n\tproviders?: readonly SecuritydeptProvider[];\n};\n\nexport function createEnvironmentForTest(): FoundationEnvironment;\nexport function createEnvironmentForTest(\n\toptions: CreateEnvironmentForTestOptions,\n): FoundationEnvironment;\nexport function createEnvironmentForTest<\n\tTBaseOptions extends EnvironmentCreatorOptions,\n\tTEnvironment extends FoundationEnvironment,\n>(\n\toptions: CreateEnvironmentForTestWithBaseOptions<TBaseOptions, TEnvironment>,\n): TEnvironment;\nexport function createEnvironmentForTest(\n\toptions:\n\t\t| CreateEnvironmentForTestOptions\n\t\t| CreateEnvironmentForTestWithBaseOptions<\n\t\t\t\tEnvironmentCreatorOptions,\n\t\t\t\tFoundationEnvironment\n\t\t  > = {},\n): FoundationEnvironment {\n\tconst {\n\t\tcreateBaseEnvironment = createFoundationEnvironment,\n\t\ttransport,\n\t\tproviders = [],\n\t\t...baseOptions\n\t} = options as CreateEnvironmentForTestWithBaseOptions<\n\t\tEnvironmentCreatorOptions,\n\t\tFoundationEnvironment\n\t> &\n\t\tCreateEnvironmentForTestOptions;\n\tconst externalProviderTokens = new Set(\n\t\tproviders.map((provider) => getSecuritydeptProviderToken(provider)),\n\t);\n\tconst testProviders: SecuritydeptProvider[] = [\n\t\tcreateProviderIfTokenMissing(\n\t\t\texternalProviderTokens,\n\t\t\tTRANSPORT_TRAIT_TOKEN,\n\t\t\t() => ({\n\t\t\t\tprovide: TRANSPORT_TRAIT_TOKEN,\n\t\t\t\tuseValue: transport ?? createMissingTransportForTest(),\n\t\t\t}),\n\t\t),\n\t\tcreateProviderIfTokenMissing(\n\t\t\texternalProviderTokens,\n\t\t\tTIME_TRAIT_TOKEN,\n\t\t\t() => ({\n\t\t\t\tprovide: TIME_TRAIT_TOKEN,\n\t\t\t\tuseValue:\n\t\t\t\t\tbaseOptions.time ?? createTimeForTest({ initialNow: Date.now() }),\n\t\t\t}),\n\t\t),\n\t].filter(notMissingProvider) as SecuritydeptProvider[];\n\n\treturn createBaseEnvironment({\n\t\t...(baseOptions as unknown as Omit<EnvironmentCreatorOptions, \"providers\">),\n\t\tproviders: [...testProviders, ...providers],\n\t});\n}\n\nfunction createMissingTransportForTest(): BaseTransportTrait {\n\treturn {\n\t\tasync execute() {\n\t\t\tthrow new Error(\"Test environment transport was not provided.\");\n\t\t},\n\t};\n}\n","import { type IdleCallbackTrait } from \"../scheduling/types\";\n\nexport interface TestIdleCallbackTrait extends IdleCallbackTrait {\n\tflush(): void;\n\tget pendingCount(): number;\n}\n\nexport function createIdleCallbackForTest(): TestIdleCallbackTrait {\n\tlet nextId = 1;\n\tconst callbacks = new Map<number, () => void>();\n\treturn {\n\t\trequestIdleCallback(callback) {\n\t\t\tconst id = nextId++;\n\t\t\tcallbacks.set(id, callback);\n\t\t\treturn id;\n\t\t},\n\t\tcancelIdleCallback(handle) {\n\t\t\tif (typeof handle === \"number\") {\n\t\t\t\tcallbacks.delete(handle);\n\t\t\t}\n\t\t},\n\t\tflush() {\n\t\t\tconst ready = [...callbacks.entries()];\n\t\t\tcallbacks.clear();\n\t\t\tfor (const [, callback] of ready) {\n\t\t\t\tcallback();\n\t\t\t}\n\t\t},\n\t\tget pendingCount() {\n\t\t\treturn callbacks.size;\n\t\t},\n\t};\n}\n","import { SYMBOL_OBSERVABLE } from \"../compat/observable\";\nimport {\n\ttype EventObserverTrait,\n\ttype EventSubjectTrait,\n\ttype EventSubscriptionTrait,\n} from \"../events/types\";\nimport { type PageLifecycleTrait } from \"../page\";\n\nexport interface TestEventSubjectTrait<T> extends EventSubjectTrait<T> {\n\tget observerCount(): number;\n}\n\nexport interface TestPageLifecycleTrait<TResumeEvent = unknown>\n\textends PageLifecycleTrait<TResumeEvent> {\n\treadonly resume: TestEventSubjectTrait<TResumeEvent>;\n}\n\nexport function createPageLifecycleForTest<\n\tTResumeEvent = unknown,\n>(): TestPageLifecycleTrait<TResumeEvent> {\n\treturn {\n\t\tresume: createEventSubjectForTest<TResumeEvent>(),\n\t};\n}\n\nexport function createEventSubjectForTest<T>(): TestEventSubjectTrait<T> {\n\tconst observers = new Set<Partial<EventObserverTrait<T>>>();\n\tconst stream = {\n\t\tsubscribe(observer) {\n\t\t\tobservers.add(observer);\n\t\t\treturn {\n\t\t\t\tunsubscribe() {\n\t\t\t\t\tobservers.delete(observer);\n\t\t\t\t},\n\t\t\t} satisfies EventSubscriptionTrait;\n\t\t},\n\t\tnext(value) {\n\t\t\tfor (const observer of [...observers]) {\n\t\t\t\tobserver.next?.(value);\n\t\t\t}\n\t\t},\n\t\terror(error) {\n\t\t\tfor (const observer of [...observers]) {\n\t\t\t\tobserver.error?.(error);\n\t\t\t}\n\t\t},\n\t\tcomplete() {\n\t\t\tfor (const observer of [...observers]) {\n\t\t\t\tobserver.complete?.();\n\t\t\t}\n\t\t\tobservers.clear();\n\t\t},\n\t\tget observerCount() {\n\t\t\treturn observers.size;\n\t\t},\n\t\t[SYMBOL_OBSERVABLE]() {\n\t\t\treturn this;\n\t\t},\n\t} satisfies TestEventSubjectTrait<T>;\n\treturn stream;\n}\n","import { ClientError, ClientErrorKind } from \"../errors\";\nimport {\n\tPopupAttachFailureReason,\n\ttype PopupAttachResult,\n\ttype PopupOpenOptions,\n\ttype PopupTrait,\n} from \"../popup\";\n\nexport interface PopupForTestOpenCall {\n\turl: string;\n\toptions?: PopupOpenOptions;\n}\n\nexport interface PopupForTestCreateOptions {\n\tattachResult?: PopupAttachResult;\n}\n\nexport interface TestPopupTrait extends PopupTrait {\n\treadonly openCalls: readonly PopupForTestOpenCall[];\n\tsetAttachResult(result: PopupAttachResult): void;\n}\n\nexport function createPopupForTest(\n\toptions: PopupForTestCreateOptions = {},\n): TestPopupTrait {\n\tconst openCalls: PopupForTestOpenCall[] = [];\n\tlet attachResult = options.attachResult ?? createMissingOpenerAttachFailure();\n\treturn {\n\t\topen(url, openOptions) {\n\t\t\topenCalls.push({ url, options: openOptions });\n\t\t\tthrow new Error(\"Test popup open was not configured.\");\n\t\t},\n\t\tattach() {\n\t\t\treturn attachResult;\n\t\t},\n\t\tget openCalls() {\n\t\t\treturn openCalls;\n\t\t},\n\t\tsetAttachResult(result) {\n\t\t\tattachResult = result;\n\t\t},\n\t};\n}\n\nfunction createMissingOpenerAttachFailure(): PopupAttachResult {\n\treturn {\n\t\tkind: \"failure\",\n\t\treason: PopupAttachFailureReason.MissingOpener,\n\t\terror: new ClientError({\n\t\t\tkind: ClientErrorKind.Configuration,\n\t\t\tcode: \"test.popup.missing_opener\",\n\t\t\tsource: \"test\",\n\t\t\tmessage: \"Test popup attach was not configured.\",\n\t\t}),\n\t};\n}\n","import {\n\tRouterNavigationMode,\n\ttype RouterNavigationRequest,\n\ttype RouterTrait,\n} from \"../router/router\";\nimport { UriReferenceString } from \"../struct/uri-string\";\n\nexport interface RouterForTestCreateOptions {\n\tcurrentUrl?: string | UriReferenceString | null;\n\tonNavigate?: (request: RouterNavigationRequest) => void | Promise<void>;\n}\n\nexport interface TestRouterTrait extends RouterTrait {\n\treadonly navigations: readonly RouterNavigationRequest[];\n\tsetCurrentUrl(url: string | UriReferenceString | null): void;\n}\n\nexport function createRouterForTest(\n\toptions: RouterForTestCreateOptions = {},\n): TestRouterTrait {\n\tlet currentUrl =\n\t\toptions.currentUrl == null\n\t\t\t? null\n\t\t\t: UriReferenceString.parse(options.currentUrl);\n\tconst navigations: RouterNavigationRequest[] = [];\n\treturn {\n\t\tcurrentUrl() {\n\t\t\treturn currentUrl;\n\t\t},\n\t\tsetCurrentUrl(url) {\n\t\t\tcurrentUrl = url == null ? null : UriReferenceString.parse(url);\n\t\t},\n\t\tget navigations() {\n\t\t\treturn navigations;\n\t\t},\n\t\tasync navigate(request) {\n\t\t\tnavigations.push(request);\n\t\t\tif (\n\t\t\t\trequest.mode === RouterNavigationMode.Push ||\n\t\t\t\trequest.mode === RouterNavigationMode.Replace\n\t\t\t) {\n\t\t\t\tcurrentUrl = request.url;\n\t\t\t}\n\t\t\tawait options.onNavigate?.(request);\n\t\t},\n\t};\n}\n","import { type as defineType } from \"arktype\";\nimport { type EnvironmentValidators } from \"../environment/types\";\nimport { createInMemoryRecordStore } from \"../storage/memory-store\";\nimport { type SyncStorageTrait } from \"../storage/types\";\nimport {\n\tthrowValidationClientError,\n\tvalidateTraitInput,\n\ttype WithTraitInputValidator,\n} from \"../validation\";\n\nexport interface StorageForTestCreateOptions {\n\tinitialEntries?: Record<string, string>;\n\tvalidatorKey?: \"persistentStorage\" | \"sessionStorage\";\n}\n\nconst StorageForTestCreateOptionsSchema = defineType({\n\tinitialEntries: \"object\",\n\tvalidatorKey: \"'persistentStorage' | 'sessionStorage'\",\n});\n\nexport function createStorageForTest(\n\toptions: StorageForTestCreateOptions &\n\t\tWithTraitInputValidator<\n\t\t\tPick<EnvironmentValidators, \"persistentStorage\" | \"sessionStorage\">\n\t\t> = {},\n): SyncStorageTrait {\n\tconst { validators, ...createOptions } = options;\n\tconst validatorKey = options.validatorKey ?? \"persistentStorage\";\n\tconst resolvedCreateOptions = {\n\t\tinitialEntries: createOptions.initialEntries ?? {},\n\t\tvalidatorKey,\n\t};\n\tvalidateTraitInput({\n\t\tvalue: resolvedCreateOptions,\n\t\tbundledSchema: StorageForTestCreateOptionsSchema,\n\t\tvalidator: validators?.[validatorKey],\n\t\tonInvalid: (failure) =>\n\t\t\tthrowValidationClientError({\n\t\t\t\tcode: \"test.storage.invalid_options\",\n\t\t\t\tsource: \"test\",\n\t\t\t\tmessagePrefix: `createStorageForTest could not validate ${validatorKey}`,\n\t\t\t\tfailure,\n\t\t\t}),\n\t});\n\tconst storage = createInMemoryRecordStore();\n\tfor (const [key, value] of Object.entries(\n\t\tresolvedCreateOptions.initialEntries,\n\t)) {\n\t\tstorage.set(key, value);\n\t}\n\treturn storage;\n}\n","import {\n\ttype BaseTransportTrait,\n\ttype HttpRequest,\n\ttype HttpResponse,\n} from \"../transport/types\";\n\nexport interface TransportForTestRoute {\n\tpredicate: (request: HttpRequest) => boolean;\n\thandler: (request: HttpRequest) => HttpResponse | Promise<HttpResponse>;\n}\n\nexport interface TransportForTestCreateOptions {\n\troutes?: readonly TransportForTestRoute[];\n\tfallback?: HttpResponse;\n}\n\nexport interface TestTransportTrait extends BaseTransportTrait {\n\ton(\n\t\tpredicate: (request: HttpRequest) => boolean,\n\t\thandler: (request: HttpRequest) => HttpResponse | Promise<HttpResponse>,\n\t): this;\n\tonRequest(method: string, urlPrefix: string, response: HttpResponse): this;\n\tsetFallback(response: HttpResponse): this;\n\treset(): void;\n\treadonly history: readonly HttpRequest[];\n}\n\nexport function createTransportForTest(\n\toptions: TransportForTestCreateOptions = {},\n): TestTransportTrait {\n\tconst routes = [...(options.routes ?? [])];\n\tconst history: HttpRequest[] = [];\n\tlet fallback = options.fallback ?? createNotFoundResponseForTest();\n\treturn {\n\t\ton(predicate, handler) {\n\t\t\troutes.push({ predicate, handler });\n\t\t\treturn this;\n\t\t},\n\t\tonRequest(method, urlPrefix, response) {\n\t\t\treturn this.on(\n\t\t\t\t(request) =>\n\t\t\t\t\trequest.method.toUpperCase() === method.toUpperCase() &&\n\t\t\t\t\trequest.url.startsWith(urlPrefix),\n\t\t\t\t() => response,\n\t\t\t);\n\t\t},\n\t\tsetFallback(response) {\n\t\t\tfallback = response;\n\t\t\treturn this;\n\t\t},\n\t\treset() {\n\t\t\troutes.length = 0;\n\t\t\thistory.length = 0;\n\t\t},\n\t\tget history() {\n\t\t\treturn history;\n\t\t},\n\t\tasync execute(request) {\n\t\t\thistory.push(request);\n\t\t\tfor (const route of routes) {\n\t\t\t\tif (route.predicate(request)) {\n\t\t\t\t\treturn route.handler(request);\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn fallback;\n\t\t},\n\t};\n}\n\nfunction createNotFoundResponseForTest(): HttpResponse {\n\treturn {\n\t\tstatus: 404,\n\t\theaders: {},\n\t\tbody: { error: \"No matching test transport route\" },\n\t};\n}\n"],"mappings":";;;;;AAoBA,MAAM,iCAAiCA,KAAW,EACjD,YAAY,SACb,CAAC;AAED,SAAgB,kBACf,UACgE,CAAC,GACjD;CAChB,MAAM,EAAE,YAAY,GAAG,kBAAkB;CACzC,MAAM,wBAAwB,EAC7B,YAAY,cAAc,cAAc,EACzC;CACA,mBAAmB;EAClB,OAAO;EACP,eAAe;EACf,WAAW,YAAY;EACvB,YAAY,YACX,2BAA2B;GAC1B,MAAM;GACN,QAAQ;GACR,eAAe;GACf;EACD,CAAC;CACH,CAAC;CACD,IAAI,MAAM,sBAAsB;CAChC,IAAI,SAAS;CACb,MAAM,wBAAQ,IAAI,IAAiD;CACnE,OAAO;EACN,WAAW;EACX,WAAW,SAAS,SAAS;GAC5B,MAAM,KAAK;GACX,MAAM,IAAI,IAAI;IAAE,IAAI,MAAM,KAAK,IAAI,GAAG,OAAO;IAAG;GAAQ,CAAC;GACzD,OAAO;EACR;EACA,aAAa,QAAQ;GACpB,IAAI,OAAO,WAAW,UACrB,MAAM,OAAO,MAAM;EAErB;EACA,QAAQ,IAAI;GACX,OAAO;EACR;EACA,QAAQ;GACP,IAAI,aAAa;GACjB,OAAO,YAAY;IAClB,aAAa;IACb,MAAM,QAAQ,CAAC,GAAG,MAAM,QAAQ,CAAC,CAAC,CAChC,QAAQ,GAAG,UAAU,KAAK,MAAM,GAAG,CAAC,CACpC,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE;IAClC,KAAK,MAAM,CAAC,IAAI,SAAS,OAAO;KAC/B,MAAM,OAAO,EAAE;KACf,KAAK,QAAQ;KACb,aAAa;IACd;GACD;EACD;EACA,gBAAgB,IAAI;GACnB,KAAK,QAAQ,EAAE;GACf,KAAK,MAAM;EACZ;EACA,IAAI,eAAe;GAClB,OAAO,MAAM;EACd;CACD;AACD;;;AChCA,SAAgB,yBACf,UAKO,CAAC,GACgB;CACxB,MAAM,EACL,wBAAwB,6BACxB,WACA,YAAY,CAAC,GACb,GAAG,gBACA;CAKJ,MAAM,yBAAyB,IAAI,IAClC,UAAU,KAAK,aAAa,6BAA6B,QAAQ,CAAC,CACnE;CACA,MAAM,gBAAwC,CAC7C,6BACC,wBACA,8BACO;EACN,SAAS;EACT,UAAU,aAAa,8BAA8B;CACtD,EACD,GACA,6BACC,wBACA,yBACO;EACN,SAAS;EACT,UACC,YAAY,QAAQ,kBAAkB,EAAE,YAAY,KAAK,IAAI,EAAE,CAAC;CAClE,EACD,CACD,CAAC,CAAC,OAAO,kBAAkB;CAE3B,OAAO,sBAAsB;EAC5B,GAAI;EACJ,WAAW,CAAC,GAAG,eAAe,GAAG,SAAS;CAC3C,CAAC;AACF;AAEA,SAAS,gCAAoD;CAC5D,OAAO,EACN,MAAM,UAAU;EACf,MAAM,IAAI,MAAM,8CAA8C;CAC/D,EACD;AACD;;;AClGA,SAAgB,4BAAmD;CAClE,IAAI,SAAS;CACb,MAAM,4BAAY,IAAI,IAAwB;CAC9C,OAAO;EACN,oBAAoB,UAAU;GAC7B,MAAM,KAAK;GACX,UAAU,IAAI,IAAI,QAAQ;GAC1B,OAAO;EACR;EACA,mBAAmB,QAAQ;GAC1B,IAAI,OAAO,WAAW,UACrB,UAAU,OAAO,MAAM;EAEzB;EACA,QAAQ;GACP,MAAM,QAAQ,CAAC,GAAG,UAAU,QAAQ,CAAC;GACrC,UAAU,MAAM;GAChB,KAAK,MAAM,GAAG,aAAa,OAC1B,SAAS;EAEX;EACA,IAAI,eAAe;GAClB,OAAO,UAAU;EAClB;CACD;AACD;;;ACfA,SAAgB,6BAE0B;CACzC,OAAO,EACN,QAAQ,0BAAwC,EACjD;AACD;AAEA,SAAgB,4BAAyD;CACxE,MAAM,4BAAY,IAAI,IAAoC;CAiC1D,OAAO;EA/BN,UAAU,UAAU;GACnB,UAAU,IAAI,QAAQ;GACtB,OAAO,EACN,cAAc;IACb,UAAU,OAAO,QAAQ;GAC1B,EACD;EACD;EACA,KAAK,OAAO;GACX,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GACnC,SAAS,OAAO,KAAK;EAEvB;EACA,MAAM,OAAO;GACZ,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GACnC,SAAS,QAAQ,KAAK;EAExB;EACA,WAAW;GACV,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GACnC,SAAS,WAAW;GAErB,UAAU,MAAM;EACjB;EACA,IAAI,gBAAgB;GACnB,OAAO,UAAU;EAClB;EACA,CAAC,qBAAqB;GACrB,OAAO;EACR;CAEW;AACb;;;ACtCA,SAAgB,mBACf,UAAqC,CAAC,GACrB;CACjB,MAAM,YAAoC,CAAC;CAC3C,IAAI,eAAe,QAAQ,gBAAgB,iCAAiC;CAC5E,OAAO;EACN,KAAK,KAAK,aAAa;GACtB,UAAU,KAAK;IAAE;IAAK,SAAS;GAAY,CAAC;GAC5C,MAAM,IAAI,MAAM,qCAAqC;EACtD;EACA,SAAS;GACR,OAAO;EACR;EACA,IAAI,YAAY;GACf,OAAO;EACR;EACA,gBAAgB,QAAQ;GACvB,eAAe;EAChB;CACD;AACD;AAEA,SAAS,mCAAsD;CAC9D,OAAO;EACN,MAAM;EACN,QAAQ,yBAAyB;EACjC,OAAO,IAAI,YAAY;GACtB,MAAM,gBAAgB;GACtB,MAAM;GACN,QAAQ;GACR,SAAS;EACV,CAAC;CACF;AACD;;;ACtCA,SAAgB,oBACf,UAAsC,CAAC,GACrB;CAClB,IAAI,aACH,QAAQ,cAAc,OACnB,OACA,mBAAmB,MAAM,QAAQ,UAAU;CAC/C,MAAM,cAAyC,CAAC;CAChD,OAAO;EACN,aAAa;GACZ,OAAO;EACR;EACA,cAAc,KAAK;GAClB,aAAa,OAAO,OAAO,OAAO,mBAAmB,MAAM,GAAG;EAC/D;EACA,IAAI,cAAc;GACjB,OAAO;EACR;EACA,MAAM,SAAS,SAAS;GACvB,YAAY,KAAK,OAAO;GACxB,IACC,QAAQ,SAAS,qBAAqB,QACtC,QAAQ,SAAS,qBAAqB,SAEtC,aAAa,QAAQ;GAEtB,MAAM,QAAQ,aAAa,OAAO;EACnC;CACD;AACD;;;AC/BA,MAAM,oCAAoCC,KAAW;CACpD,gBAAgB;CAChB,cAAc;AACf,CAAC;AAED,SAAgB,qBACf,UAGK,CAAC,GACa;CACnB,MAAM,EAAE,YAAY,GAAG,kBAAkB;CACzC,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,MAAM,wBAAwB;EAC7B,gBAAgB,cAAc,kBAAkB,CAAC;EACjD;CACD;CACA,mBAAmB;EAClB,OAAO;EACP,eAAe;EACf,WAAW,aAAa;EACxB,YAAY,YACX,2BAA2B;GAC1B,MAAM;GACN,QAAQ;GACR,eAAe,2CAA2C;GAC1D;EACD,CAAC;CACH,CAAC;CACD,MAAM,UAAU,0BAA0B;CAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QACjC,sBAAsB,cACvB,GACC,QAAQ,IAAI,KAAK,KAAK;CAEvB,OAAO;AACR;;;ACxBA,SAAgB,uBACf,UAAyC,CAAC,GACrB;CACrB,MAAM,SAAS,CAAC,GAAI,QAAQ,UAAU,CAAC,CAAE;CACzC,MAAM,UAAyB,CAAC;CAChC,IAAI,WAAW,QAAQ,YAAY,8BAA8B;CACjE,OAAO;EACN,GAAG,WAAW,SAAS;GACtB,OAAO,KAAK;IAAE;IAAW;GAAQ,CAAC;GAClC,OAAO;EACR;EACA,UAAU,QAAQ,WAAW,UAAU;GACtC,OAAO,KAAK,IACV,YACA,QAAQ,OAAO,YAAY,MAAM,OAAO,YAAY,KACpD,QAAQ,IAAI,WAAW,SAAS,SAC3B,QACP;EACD;EACA,YAAY,UAAU;GACrB,WAAW;GACX,OAAO;EACR;EACA,QAAQ;GACP,OAAO,SAAS;GAChB,QAAQ,SAAS;EAClB;EACA,IAAI,UAAU;GACb,OAAO;EACR;EACA,MAAM,QAAQ,SAAS;GACtB,QAAQ,KAAK,OAAO;GACpB,KAAK,MAAM,SAAS,QACnB,IAAI,MAAM,UAAU,OAAO,GAC1B,OAAO,MAAM,QAAQ,OAAO;GAG9B,OAAO;EACR;CACD;AACD;AAEA,SAAS,gCAA8C;CACtD,OAAO;EACN,QAAQ;EACR,SAAS,CAAC;EACV,MAAM,EAAE,OAAO,mCAAmC;CACnD;AACD"}

package/dist/uri-string-BPNbIMgv.mjs

@@ -0,0 +1,300 @@
+//#region src/struct/uri-string.ts
+const RELATIVE_URI_SENTINEL_BASE = "http://localhost";
+/**
+* Thrown when a string cannot be parsed into the requested URI variant.
+*/
+var UriParseError = class extends Error {
+	input;
+	kind;
+	constructor(input, kind, options) {
+		super(`Failed to parse "${input}" as ${kind}`, options);
+		this.name = "UriParseError";
+		this.input = input;
+		this.kind = kind;
+	}
+};
+/**
+* Immutable wrapper around a URI-reference string.
+*
+* A URI-reference (RFC 3986 §4.1) is either an absolute URI or a relative
+* reference.  Concrete subclasses {@link UriString} and
+* {@link UriRelativeString} carry the additional type-level guarantee of
+* which variant they hold.
+*
+* Instances created via `UriReferenceString.parse` / `.tryParse` are always
+* one of the two subclasses, so {@link isAbsolute} and {@link isRelative}
+* narrow correctly.
+*/
+var UriReferenceString = class UriReferenceString {
+	/** The original, unmodified input string. */
+	_raw;
+	/**
+	* Eagerly parsed URL helper.
+	*
+	* - Absolute URIs: `new URL(raw)`.
+	* - Relative URIs: `new URL(raw, RELATIVE_URI_SENTINEL_BASE)`.
+	*
+	* For relative URIs the scheme and host originate from the sentinel and
+	* MUST NOT be used for origin-sensitive operations.
+	*/
+	_parsed;
+	_isAbsolute;
+	constructor(raw, parsed, isAbsolute) {
+		this._raw = raw;
+		this._parsed = parsed;
+		this._isAbsolute = isAbsolute;
+	}
+	/**
+	* Parse any valid URI reference (absolute or relative).
+	*
+	* The returned instance is always a {@link UriString} or
+	* {@link UriRelativeString}.
+	*
+	* @throws {UriParseError} when the input is not a valid URI reference.
+	*/
+	static parse(input) {
+		const result = UriReferenceString.tryParse(input);
+		if (!result) throw new UriParseError(typeof input === "string" ? input : input.toString(), "URI reference");
+		return result;
+	}
+	/**
+	* Try to parse a URI reference, returning `null` on failure.
+	*
+	* The returned instance is always a {@link UriString} or
+	* {@link UriRelativeString}.
+	*/
+	static tryParse(input) {
+		if (input instanceof UriReferenceString) return input;
+		const source = typeof input === "string" ? input : input.toString();
+		return UriString.tryParse(source) ?? UriRelativeString.tryParse(source);
+	}
+	/** Create from a native `URL`. Always produces a {@link UriString}. */
+	static fromURL(url) {
+		return UriString.fromURL(url);
+	}
+	/**
+	* Create from the relative components of a URL.
+	* Always produces a {@link UriRelativeString}.
+	*/
+	static fromURLRelative(parts) {
+		return UriRelativeString.fromURLRelative(parts);
+	}
+	/** The original input string. */
+	get raw() {
+		return this._raw;
+	}
+	get pathname() {
+		return this._parsed.pathname;
+	}
+	get hash() {
+		return this._parsed.hash;
+	}
+	get search() {
+		return this._parsed.search;
+	}
+	get searchParams() {
+		return this._parsed.searchParams;
+	}
+	/** Type-guard: narrows to {@link UriString} when the reference is absolute. */
+	isAbsolute() {
+		return this._isAbsolute;
+	}
+	/** Type-guard: narrows to {@link UriRelativeString} when the reference is relative. */
+	isRelative() {
+		return !this._isAbsolute;
+	}
+	/** Narrow to {@link UriString} or return `null`. */
+	asAbsolute() {
+		return this.isAbsolute() ? this : null;
+	}
+	/** Narrow to {@link UriRelativeString} or return `null`. */
+	asRelative() {
+		return this.isRelative() ? this : null;
+	}
+	/**
+	* Returns a new instance with `hash` replaced.
+	*
+	* @param value URL-style hash, including a leading `#` when non-empty.
+	*/
+	setHash(value) {
+		const hashIndex = this._raw.indexOf("#");
+		const base = hashIndex >= 0 ? this._raw.slice(0, hashIndex) : this._raw;
+		return UriReferenceString.parse(`${base}${value}`);
+	}
+	/** Returns a new instance with the complete query parameter set replaced. */
+	setSearchParams(init) {
+		const hashIndex = this._raw.indexOf("#");
+		const hash = hashIndex >= 0 ? this._raw.slice(hashIndex) : "";
+		const withoutHash = hashIndex >= 0 ? this._raw.slice(0, hashIndex) : this._raw;
+		const searchIndex = withoutHash.indexOf("?");
+		const base = searchIndex >= 0 ? withoutHash.slice(0, searchIndex) : withoutHash;
+		const search = new URLSearchParams(init).toString();
+		return UriReferenceString.parse(`${base}${search.length > 0 ? `?${search}` : ""}${hash}`);
+	}
+	/**
+	* Convert to a native `URL`.
+	*
+	* A `base` is required when the reference is relative; it is ignored
+	* for absolute references.
+	*
+	* @throws {TypeError} when the reference is relative and no base is provided.
+	*/
+	toURL(base) {
+		if (this._isAbsolute) return new URL(this._parsed.href);
+		if (base == null) throw new TypeError("A base URL is required to convert a relative URI reference to a URL");
+		return new URL(this._raw, base);
+	}
+	toString() {
+		return this._raw;
+	}
+	valueOf() {
+		return this._raw;
+	}
+	toJSON() {
+		return this._raw;
+	}
+};
+/**
+* Immutable wrapper around an absolute URI string.
+*
+* An absolute URI (RFC 3986 §4.3) always starts with a scheme component
+* (e.g. `https://example.com/path`).
+*/
+var UriString = class UriString extends UriReferenceString {
+	constructor(raw, parsed) {
+		super(raw, parsed, true);
+	}
+	/**
+	* Parse an absolute URI string.
+	*
+	* @throws {UriParseError} when the input is not a valid absolute URI.
+	*/
+	static parse(input) {
+		const result = UriString.tryParse(input);
+		if (!result) throw new UriParseError(input, "absolute URI");
+		return result;
+	}
+	/**
+	* Try to parse an absolute URI, returning `null` if the input is not
+	* a valid absolute URI.
+	*/
+	static tryParse(input) {
+		if (input instanceof UriString) return input;
+		try {
+			const parsed = new URL(input);
+			return new UriString(input, parsed);
+		} catch {
+			return null;
+		}
+	}
+	/** Create from a native `URL`, using its `href` as the raw string. */
+	static fromURL(url) {
+		return new UriString(url.href, new URL(url.href));
+	}
+	/**
+	* Not supported — relative parts cannot produce an absolute URI.
+	*
+	* @throws {TypeError} unconditionally.
+	*/
+	static fromURLRelative(_parts) {
+		throw new TypeError("Cannot create a UriString from relative URL parts. Use UriRelativeString.fromURLRelative() or UriReferenceString.fromURLRelative() instead.");
+	}
+	get host() {
+		return this._parsed.host;
+	}
+	get hostname() {
+		return this._parsed.hostname;
+	}
+	get origin() {
+		return this._parsed.origin;
+	}
+	get password() {
+		return this._parsed.password;
+	}
+	get port() {
+		return this._parsed.port;
+	}
+	get protocol() {
+		return this._parsed.protocol;
+	}
+	get username() {
+		return this._parsed.username;
+	}
+	/** Convert to a native `URL`. No base is required for absolute URIs. */
+	toURL() {
+		return new URL(this.raw);
+	}
+};
+/**
+* Immutable wrapper around a relative URI reference string.
+*
+* A relative reference (RFC 3986 §4.2) has no scheme and must be resolved
+* against a base URI to obtain an absolute URI.
+*
+* Internally, the raw string is parsed against a sentinel base
+* (`http://localhost`) to enable eager validation and URL-component
+* extraction.  The sentinel origin is never leaked through the public API.
+*/
+var UriRelativeString = class UriRelativeString extends UriReferenceString {
+	constructor(raw, parsed) {
+		super(raw, parsed, false);
+	}
+	/**
+	* Parse a relative URI reference.
+	*
+	* @throws {UriParseError} when the input is absolute or not a valid
+	*   relative URI reference.
+	*/
+	static parse(input) {
+		const result = UriRelativeString.tryParse(input);
+		if (!result) throw new UriParseError(input, "relative URI reference");
+		return result;
+	}
+	/**
+	* Try to parse a relative URI reference, returning `null` if the input
+	* is an absolute URI or otherwise invalid.
+	*/
+	static tryParse(input) {
+		if (input instanceof UriRelativeString) return input;
+		try {
+			new URL(input);
+			return null;
+		} catch {}
+		try {
+			const parsed = new URL(input, RELATIVE_URI_SENTINEL_BASE);
+			return new UriRelativeString(input, parsed);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Not supported — a native `URL` is always absolute and cannot be
+	* represented as a relative URI reference.
+	*
+	* @throws {TypeError} unconditionally.
+	*/
+	static fromURL(_url) {
+		throw new TypeError("Cannot create a UriRelativeString from a URL; URLs are always absolute. Use UriString.fromURL() or UriReferenceString.fromURL() instead.");
+	}
+	/**
+	* Create from the relative components of a URL.
+	*
+	* Concatenates `pathname + search + hash` into a relative URI string.
+	*/
+	static fromURLRelative(parts) {
+		const raw = `${parts.pathname}${parts.search}${parts.hash}`;
+		return UriRelativeString.parse(raw);
+	}
+	/**
+	* Convert to a native `URL` by resolving against the given base.
+	*
+	* @param base - The base URL to resolve against (required).
+	*/
+	toURL(base) {
+		return new URL(this.raw, base);
+	}
+};
+//#endregion
+export { UriString as i, UriReferenceString as n, UriRelativeString as r, UriParseError as t };
+
+//# sourceMappingURL=uri-string-BPNbIMgv.mjs.map

package/dist/uri-string-BPNbIMgv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-string-BPNbIMgv.mjs","names":[],"sources":["../src/struct/uri-string.ts"],"sourcesContent":["// Sentinel base used internally to parse relative URIs via the URL constructor.\n// The specific value is never exposed; it only serves as a structural anchor\n// so that `new URL(relativeInput, SENTINEL_BASE)` succeeds.\nconst RELATIVE_URI_SENTINEL_BASE = \"http://localhost\";\n\n/**\n * Thrown when a string cannot be parsed into the requested URI variant.\n */\nexport class UriParseError extends Error {\n\treadonly input: string;\n\treadonly kind: string;\n\n\tconstructor(input: string, kind: string, options?: ErrorOptions) {\n\t\tsuper(`Failed to parse \"${input}\" as ${kind}`, options);\n\t\tthis.name = \"UriParseError\";\n\t\tthis.input = input;\n\t\tthis.kind = kind;\n\t}\n}\n\n/**\n * The relative components of a URL — pathname, search, and hash.\n *\n * All fields use the same format as the native `URL` accessors:\n * - `pathname` starts with `/` (e.g. `\"/path\"`).\n * - `search` includes the leading `?` when present (e.g. `\"?q=1\"`).\n * - `hash` includes the leading `#` when present (e.g. `\"#section\"`).\n */\nexport interface UriRelativeParts {\n\treadonly pathname: string;\n\treadonly search: string;\n\treadonly hash: string;\n}\n\n/**\n * Minimal structural type for URI fragment parsing.\n *\n * Matches any value that exposes a URL-style `hash` accessor — for example\n * `URL`, `Location`, or {@link UriReferenceString}.\n */\nexport interface UriFragmentPart {\n\treadonly hash: string;\n}\n\n/**\n * Minimal structural type for URI reference parsing.\n *\n * Matches any value that can be serialized via `toString()` — for example\n * native `URL`, `Location`, or {@link UriReferenceString}.\n */\nexport interface UriReferenceStringLike {\n\ttoString(): string;\n}\n\nexport type UriReferenceStringInput = string | UriReferenceStringLike;\n\nexport type UriSearchParamsInit = NonNullable<\n\tConstructorParameters<typeof URLSearchParams>[0]\n>;\n\n// ---------------------------------------------------------------------------\n// UriReferenceString — the URI-reference supertype (absolute | relative)\n// ---------------------------------------------------------------------------\n\n/**\n * Immutable wrapper around a URI-reference string.\n *\n * A URI-reference (RFC 3986 §4.1) is either an absolute URI or a relative\n * reference.  Concrete subclasses {@link UriString} and\n * {@link UriRelativeString} carry the additional type-level guarantee of\n * which variant they hold.\n *\n * Instances created via `UriReferenceString.parse` / `.tryParse` are always\n * one of the two subclasses, so {@link isAbsolute} and {@link isRelative}\n * narrow correctly.\n */\nexport class UriReferenceString {\n\t/** The original, unmodified input string. */\n\tprotected readonly _raw: string;\n\n\t/**\n\t * Eagerly parsed URL helper.\n\t *\n\t * - Absolute URIs: `new URL(raw)`.\n\t * - Relative URIs: `new URL(raw, RELATIVE_URI_SENTINEL_BASE)`.\n\t *\n\t * For relative URIs the scheme and host originate from the sentinel and\n\t * MUST NOT be used for origin-sensitive operations.\n\t */\n\tprotected readonly _parsed: URL;\n\n\tprotected readonly _isAbsolute: boolean;\n\n\tprotected constructor(raw: string, parsed: URL, isAbsolute: boolean) {\n\t\tthis._raw = raw;\n\t\tthis._parsed = parsed;\n\t\tthis._isAbsolute = isAbsolute;\n\t}\n\n\t// ---- Static factories ------------------------------------------------\n\n\t/**\n\t * Parse any valid URI reference (absolute or relative).\n\t *\n\t * The returned instance is always a {@link UriString} or\n\t * {@link UriRelativeString}.\n\t *\n\t * @throws {UriParseError} when the input is not a valid URI reference.\n\t */\n\tstatic parse(input: UriReferenceStringInput): UriReferenceString {\n\t\tconst result = UriReferenceString.tryParse(input);\n\t\tif (!result) {\n\t\t\tthrow new UriParseError(\n\t\t\t\ttypeof input === \"string\" ? input : input.toString(),\n\t\t\t\t\"URI reference\",\n\t\t\t);\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Try to parse a URI reference, returning `null` on failure.\n\t *\n\t * The returned instance is always a {@link UriString} or\n\t * {@link UriRelativeString}.\n\t */\n\tstatic tryParse(input: UriReferenceStringInput): UriReferenceString | null {\n\t\tif (input instanceof UriReferenceString) {\n\t\t\treturn input;\n\t\t}\n\t\tconst source = typeof input === \"string\" ? input : input.toString();\n\t\treturn UriString.tryParse(source) ?? UriRelativeString.tryParse(source);\n\t}\n\n\t/** Create from a native `URL`. Always produces a {@link UriString}. */\n\tstatic fromURL(url: URL): UriString {\n\t\treturn UriString.fromURL(url);\n\t}\n\n\t/**\n\t * Create from the relative components of a URL.\n\t * Always produces a {@link UriRelativeString}.\n\t */\n\tstatic fromURLRelative(parts: UriRelativeParts): UriRelativeString {\n\t\treturn UriRelativeString.fromURLRelative(parts);\n\t}\n\n\t// ---- Accessors -------------------------------------------------------\n\n\t/** The original input string. */\n\tget raw(): string {\n\t\treturn this._raw;\n\t}\n\n\tget pathname(): string {\n\t\treturn this._parsed.pathname;\n\t}\n\n\tget hash(): string {\n\t\treturn this._parsed.hash;\n\t}\n\n\tget search(): string {\n\t\treturn this._parsed.search;\n\t}\n\n\tget searchParams(): URLSearchParams {\n\t\treturn this._parsed.searchParams;\n\t}\n\n\t// ---- Type narrowing --------------------------------------------------\n\n\t/** Type-guard: narrows to {@link UriString} when the reference is absolute. */\n\tisAbsolute(): this is UriString {\n\t\treturn this._isAbsolute;\n\t}\n\n\t/** Type-guard: narrows to {@link UriRelativeString} when the reference is relative. */\n\tisRelative(): this is UriRelativeString {\n\t\treturn !this._isAbsolute;\n\t}\n\n\t/** Narrow to {@link UriString} or return `null`. */\n\tasAbsolute(): UriString | null {\n\t\treturn this.isAbsolute() ? this : null;\n\t}\n\n\t/** Narrow to {@link UriRelativeString} or return `null`. */\n\tasRelative(): UriRelativeString | null {\n\t\treturn this.isRelative() ? this : null;\n\t}\n\n\t// ---- Mutation (immutable) --------------------------------------------\n\n\t/**\n\t * Returns a new instance with `hash` replaced.\n\t *\n\t * @param value URL-style hash, including a leading `#` when non-empty.\n\t */\n\tsetHash(value: string): this {\n\t\tconst hashIndex = this._raw.indexOf(\"#\");\n\t\tconst base = hashIndex >= 0 ? this._raw.slice(0, hashIndex) : this._raw;\n\t\treturn UriReferenceString.parse(`${base}${value}`) as this;\n\t}\n\n\t/** Returns a new instance with the complete query parameter set replaced. */\n\tsetSearchParams(init?: UriSearchParamsInit): this {\n\t\tconst hashIndex = this._raw.indexOf(\"#\");\n\t\tconst hash = hashIndex >= 0 ? this._raw.slice(hashIndex) : \"\";\n\t\tconst withoutHash =\n\t\t\thashIndex >= 0 ? this._raw.slice(0, hashIndex) : this._raw;\n\t\tconst searchIndex = withoutHash.indexOf(\"?\");\n\t\tconst base =\n\t\t\tsearchIndex >= 0 ? withoutHash.slice(0, searchIndex) : withoutHash;\n\t\tconst search = new URLSearchParams(init).toString();\n\t\treturn UriReferenceString.parse(\n\t\t\t`${base}${search.length > 0 ? `?${search}` : \"\"}${hash}`,\n\t\t) as this;\n\t}\n\n\t// ---- Conversion ------------------------------------------------------\n\n\t/**\n\t * Convert to a native `URL`.\n\t *\n\t * A `base` is required when the reference is relative; it is ignored\n\t * for absolute references.\n\t *\n\t * @throws {TypeError} when the reference is relative and no base is provided.\n\t */\n\ttoURL(base?: string | URL): URL {\n\t\tif (this._isAbsolute) {\n\t\t\treturn new URL(this._parsed.href);\n\t\t}\n\t\tif (base == null) {\n\t\t\tthrow new TypeError(\n\t\t\t\t\"A base URL is required to convert a relative URI reference to a URL\",\n\t\t\t);\n\t\t}\n\t\treturn new URL(this._raw, base);\n\t}\n\n\ttoString(): string {\n\t\treturn this._raw;\n\t}\n\n\tvalueOf(): string {\n\t\treturn this._raw;\n\t}\n\n\ttoJSON(): string {\n\t\treturn this._raw;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// UriString — absolute URI (must include a scheme)\n// ---------------------------------------------------------------------------\n\n/**\n * Immutable wrapper around an absolute URI string.\n *\n * An absolute URI (RFC 3986 §4.3) always starts with a scheme component\n * (e.g. `https://example.com/path`).\n */\nexport class UriString extends UriReferenceString {\n\tprotected constructor(raw: string, parsed: URL) {\n\t\tsuper(raw, parsed, true);\n\t}\n\n\t// ---- Static factories ------------------------------------------------\n\n\t/**\n\t * Parse an absolute URI string.\n\t *\n\t * @throws {UriParseError} when the input is not a valid absolute URI.\n\t */\n\tstatic override parse(input: string): UriString {\n\t\tconst result = UriString.tryParse(input);\n\t\tif (!result) {\n\t\t\tthrow new UriParseError(input, \"absolute URI\");\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Try to parse an absolute URI, returning `null` if the input is not\n\t * a valid absolute URI.\n\t */\n\tstatic override tryParse(input: string | UriString): UriString | null {\n\t\tif (input instanceof UriString) {\n\t\t\treturn input;\n\t\t}\n\t\ttry {\n\t\t\tconst parsed = new URL(input);\n\t\t\treturn new UriString(input, parsed);\n\t\t} catch {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t/** Create from a native `URL`, using its `href` as the raw string. */\n\tstatic override fromURL(url: URL): UriString {\n\t\treturn new UriString(url.href, new URL(url.href));\n\t}\n\n\t/**\n\t * Not supported — relative parts cannot produce an absolute URI.\n\t *\n\t * @throws {TypeError} unconditionally.\n\t */\n\tstatic override fromURLRelative(_parts: UriRelativeParts): never {\n\t\tthrow new TypeError(\n\t\t\t\"Cannot create a UriString from relative URL parts. \" +\n\t\t\t\t\"Use UriRelativeString.fromURLRelative() or UriReferenceString.fromURLRelative() instead.\",\n\t\t);\n\t}\n\n\t// ---- Accessors -------------------------------------------------------\n\n\tget host(): string {\n\t\treturn this._parsed.host;\n\t}\n\n\tget hostname(): string {\n\t\treturn this._parsed.hostname;\n\t}\n\n\tget origin(): string {\n\t\treturn this._parsed.origin;\n\t}\n\n\tget password(): string {\n\t\treturn this._parsed.password;\n\t}\n\n\tget port(): string {\n\t\treturn this._parsed.port;\n\t}\n\n\tget protocol(): string {\n\t\treturn this._parsed.protocol;\n\t}\n\n\tget username(): string {\n\t\treturn this._parsed.username;\n\t}\n\n\t// ---- Conversion ------------------------------------------------------\n\n\t/** Convert to a native `URL`. No base is required for absolute URIs. */\n\toverride toURL(): URL {\n\t\treturn new URL(this.raw);\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// UriRelativeString — relative URI reference (no scheme)\n// ---------------------------------------------------------------------------\n\n/**\n * Immutable wrapper around a relative URI reference string.\n *\n * A relative reference (RFC 3986 §4.2) has no scheme and must be resolved\n * against a base URI to obtain an absolute URI.\n *\n * Internally, the raw string is parsed against a sentinel base\n * (`http://localhost`) to enable eager validation and URL-component\n * extraction.  The sentinel origin is never leaked through the public API.\n */\nexport class UriRelativeString extends UriReferenceString {\n\tprotected constructor(raw: string, parsed: URL) {\n\t\tsuper(raw, parsed, false);\n\t}\n\n\t// ---- Static factories ------------------------------------------------\n\n\t/**\n\t * Parse a relative URI reference.\n\t *\n\t * @throws {UriParseError} when the input is absolute or not a valid\n\t *   relative URI reference.\n\t */\n\tstatic override parse(input: string): UriRelativeString {\n\t\tconst result = UriRelativeString.tryParse(input);\n\t\tif (!result) {\n\t\t\tthrow new UriParseError(input, \"relative URI reference\");\n\t\t}\n\t\treturn result;\n\t}\n\n\t/**\n\t * Try to parse a relative URI reference, returning `null` if the input\n\t * is an absolute URI or otherwise invalid.\n\t */\n\tstatic override tryParse(\n\t\tinput: string | UriRelativeString,\n\t): UriRelativeString | null {\n\t\tif (input instanceof UriRelativeString) {\n\t\t\treturn input;\n\t\t}\n\t\t// Reject absolute URIs — they belong in UriString.\n\t\ttry {\n\t\t\tnew URL(input);\n\t\t\treturn null;\n\t\t} catch {\n\t\t\t// Not absolute — fall through to relative parsing.\n\t\t}\n\t\ttry {\n\t\t\tconst parsed = new URL(input, RELATIVE_URI_SENTINEL_BASE);\n\t\t\treturn new UriRelativeString(input, parsed);\n\t\t} catch {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t/**\n\t * Not supported — a native `URL` is always absolute and cannot be\n\t * represented as a relative URI reference.\n\t *\n\t * @throws {TypeError} unconditionally.\n\t */\n\tstatic override fromURL(_url: URL): never {\n\t\tthrow new TypeError(\n\t\t\t\"Cannot create a UriRelativeString from a URL; URLs are always absolute. \" +\n\t\t\t\t\"Use UriString.fromURL() or UriReferenceString.fromURL() instead.\",\n\t\t);\n\t}\n\n\t/**\n\t * Create from the relative components of a URL.\n\t *\n\t * Concatenates `pathname + search + hash` into a relative URI string.\n\t */\n\tstatic override fromURLRelative(parts: UriRelativeParts): UriRelativeString {\n\t\tconst raw = `${parts.pathname}${parts.search}${parts.hash}`;\n\t\treturn UriRelativeString.parse(raw);\n\t}\n\n\t// ---- Conversion ------------------------------------------------------\n\n\t/**\n\t * Convert to a native `URL` by resolving against the given base.\n\t *\n\t * @param base - The base URL to resolve against (required).\n\t */\n\toverride toURL(base: string | URL): URL {\n\t\treturn new URL(this.raw, base);\n\t}\n}\n"],"mappings":"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"}