@getodk/xforms-engine 0.4.0 → 0.6.0

package/src/lib/codecs/getSharedValueCodec.ts

@@ -0,0 +1,79 @@
+import type { ValueType } from '../../client/ValueType.ts';
+import {
+	DecimalValueCodec,
+	type DecimalInputValue,
+	type DecimalRuntimeValue,
+} from './DecimalValueCodec.ts';
+import type { GeopointInputValue, GeopointRuntimeValue } from './Geopoint/Geopoint.ts';
+import { GeopointValueCodec } from './Geopoint/GeopointValueCodec.ts';
+import { IntValueCodec, type IntInputValue, type IntRuntimeValue } from './IntValueCodec.ts';
+import { StringValueCodec } from './StringValueCodec.ts';
+import type { ValueCodec } from './ValueCodec.ts';
+import { ValueTypePlaceholderCodec } from './ValueTypePlaceholderCodec.ts';
+
+interface RuntimeValuesByType {
+	readonly string: string;
+	readonly int: IntRuntimeValue;
+	readonly decimal: DecimalRuntimeValue;
+	readonly boolean: string;
+	readonly date: string;
+	readonly time: string;
+	readonly dateTime: string;
+	readonly geopoint: GeopointRuntimeValue;
+	readonly geotrace: string;
+	readonly geoshape: string;
+	readonly binary: string;
+	readonly barcode: string;
+	readonly intent: string;
+}
+
+export type RuntimeValue<V extends ValueType> = RuntimeValuesByType[V];
+
+interface RuntimeInputValuesByType {
+	readonly string: string;
+	readonly int: IntInputValue;
+	readonly decimal: DecimalInputValue;
+	readonly boolean: string;
+	readonly date: string;
+	readonly time: string;
+	readonly dateTime: string;
+	readonly geopoint: GeopointInputValue;
+	readonly geotrace: string;
+	readonly geoshape: string;
+	readonly binary: string;
+	readonly barcode: string;
+	readonly intent: string;
+}
+
+export type RuntimeInputValue<V extends ValueType> = RuntimeInputValuesByType[V];
+
+type SharedValueCodecs = {
+	readonly [V in ValueType]: ValueCodec<V, RuntimeValue<V>, RuntimeInputValue<V>>;
+};
+
+export type SharedValueCodec<V extends ValueType> = SharedValueCodecs[V];
+
+/**
+ * Provides codecs for each {@link ValueType | value type}, for nodes with a
+ * common representation of those value types.
+ */
+export const sharedValueCodecs: SharedValueCodecs = {
+	string: new StringValueCodec(),
+
+	int: new IntValueCodec(),
+	decimal: new DecimalValueCodec(),
+	boolean: new ValueTypePlaceholderCodec('boolean'),
+	date: new ValueTypePlaceholderCodec('date'),
+	time: new ValueTypePlaceholderCodec('time'),
+	dateTime: new ValueTypePlaceholderCodec('dateTime'),
+	geopoint: new GeopointValueCodec(),
+	geotrace: new ValueTypePlaceholderCodec('geotrace'),
+	geoshape: new ValueTypePlaceholderCodec('geoshape'),
+	binary: new ValueTypePlaceholderCodec('binary'),
+	barcode: new ValueTypePlaceholderCodec('barcode'),
+	intent: new ValueTypePlaceholderCodec('intent'),
+};
+
+export const getSharedValueCodec = <V extends ValueType>(valueType: V): SharedValueCodec<V> => {
+	return sharedValueCodecs[valueType];
+};

package/src/lib/codecs/items/BaseItemCodec.ts

@@ -0,0 +1,20 @@
+import type { ValueType } from '../../../client/ValueType.ts';
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { ValueArrayCodec } from '../ValueArrayCodec.ts';
+import type { CodecDecoder, CodecEncoder } from '../ValueCodec.ts';
+
+export type BaseItemValueType = 'string';
+
+export type UnsupportedBaseItemValueType = Exclude<ValueType, BaseItemValueType>;
+
+export abstract class BaseItemCodec<
+	Values extends readonly string[] = readonly string[],
+> extends ValueArrayCodec<BaseItemValueType, Values> {
+	constructor(
+		baseCodec: SharedValueCodec<'string'>,
+		encodeValue: CodecEncoder<Values>,
+		decodeValue: CodecDecoder<Values>
+	) {
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/items/MultipleValueItemCodec.ts

@@ -0,0 +1,28 @@
+import { xmlXPathWhitespaceSeparatedList } from '@getodk/common/lib/string/whitespace.ts';
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import type { CodecDecoder, CodecEncoder } from '../ValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+
+/**
+ * Value codec implementation for `<select>` and `<odk:rank>` controls.
+ *
+ * This generalizes the application of a {@link SharedValueCodec} implementation
+ * over individual select and rank values, where those values are serialized as a
+ * whitespace-separated list. All other encoding and decoding logic is deferred
+ * to the provided {@link baseCodec}, ensuring that select and rank value types are
+ * treated consistently with the same underlying data types for other controls.
+ */
+export class MultipleValueItemCodec extends BaseItemCodec<readonly string[]> {
+	constructor(baseCodec: SharedValueCodec<'string'>) {
+		const encodeValue: CodecEncoder<readonly string[]> = (value) => {
+			return value.join(' ');
+		};
+		const decodeValue: CodecDecoder<readonly string[]> = (value) => {
+			return xmlXPathWhitespaceSeparatedList(value, {
+				ignoreEmpty: true,
+			});
+		};
+
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/codecs/items/SingleValueItemCodec.ts

@@ -0,0 +1,67 @@
+import type { SharedValueCodec } from '../getSharedValueCodec.ts';
+import { type CodecDecoder, type CodecEncoder } from '../ValueCodec.ts';
+import { BaseItemCodec } from './BaseItemCodec.ts';
+import type { MultipleValueItemCodec } from './MultipleValueItemCodec.ts';
+
+// prettier-ignore
+export type SingleValueSelectRuntimeValues =
+	| readonly []
+	| readonly [string];
+
+/**
+ * @see {@link encodeValueFactory}
+ */
+// prettier-ignore
+type SingleValueSelectCodecValues =
+	| SingleValueSelectRuntimeValues
+	| readonly string[];
+
+/**
+ * @todo This is more permissive than it should be, allowing an array of any
+ * length.  It's not clear whether a runtime check **MUST** happen here, but
+ * if we identify bugs where `<select1>` controls are somehow allowing more
+ * than one value to be set, this is where we'd start looking. The check is
+ * skipped for now, to reduce performance overhead.
+ */
+const encodeValueFactory = (
+	baseCodec: SharedValueCodec<'string'>
+): CodecEncoder<SingleValueSelectCodecValues> => {
+	return (values) => {
+		const [value] = values;
+
+		if (value == null) {
+			return '';
+		}
+
+		return baseCodec.encodeValue(value);
+	};
+};
+
+/**
+ * Value codec implementation for `<select1>` controls.
+ *
+ * Note: this implementation is a specialization of the same principles
+ * underlying {@link MultipleValueItemCodec}. It is implemented separately:
+ *
+ * 1. to address a semantic difference between `<select>` and `<select1>`
+ *    values: the former are serialized as a space-separated list, but that does
+ *    not apply to the latter;
+ *
+ * 2. as an optimization, as the more general implementation performs poorly on
+ *    forms which we monitor for performance.
+ */
+export class SingleValueItemCodec extends BaseItemCodec<SingleValueSelectCodecValues> {
+	constructor(baseCodec: SharedValueCodec<'string'>) {
+		const encodeValue = encodeValueFactory(baseCodec);
+
+		const decodeValue: CodecDecoder<SingleValueSelectRuntimeValues> = (value) => {
+			if (value == null) {
+				return [];
+			}
+
+			return [value];
+		};
+
+		super(baseCodec, encodeValue, decodeValue);
+	}
+}

package/src/lib/dom/query.ts

@@ -3,7 +3,6 @@ import type {
 	KnownAttributeLocalNamedElement,
 	LocalNamedElement,
 } from '@getodk/common/types/dom.ts';
-import type { SelectElement } from '../../parse/body/control/select/SelectDefinition';
 
 const hintLookup = new ScopedElementLookup(':scope > hint', 'hint');
 const itemLookup = new ScopedElementLookup(':scope > item', 'item');
@@ -15,6 +14,7 @@ const repeatGroupLabelLookup = new ScopedElementLookup(
 );
 const repeatLookup = new ScopedElementLookup(':scope > repeat[nodeset]', 'repeat[nodeset]');
 const valueLookup = new ScopedElementLookup(':scope > value', 'value');
+const submissionLookup = new ScopedElementLookup(':scope > submission', 'submission');
 
 export interface HintElement extends LocalNamedElement<'hint'> {}
 
@@ -37,7 +37,7 @@ export const getHintElement = (parent: Element): HintElement | null => {
 	return hintLookup.getElement<HintElement>(parent);
 };
 
-export const getItemElements = (parent: SelectElement): readonly ItemElement[] => {
+export const getItemElements = (parent: Element): readonly ItemElement[] => {
 	return Array.from(itemLookup.getElements<ItemElement>(parent));
 };
 
@@ -60,3 +60,9 @@ export const getRepeatElement = (parent: Element): RepeatElement | null => {
 export const getValueElement = (parent: ItemElement | ItemsetElement): ValueElement | null => {
 	return valueLookup.getElement<ValueElement>(parent);
 };
+
+export interface SubmissionElement extends LocalNamedElement<'submission'> {}
+
+export const getSubmissionElement = (parent: Element): SubmissionElement | null => {
+	return submissionLookup.getElement<SubmissionElement>(parent);
+};

package/src/lib/names/NamespaceDeclaration.ts

@@ -0,0 +1,106 @@
+import { XMLNS_NAMESPACE_URI, XMLNS_PREFIX } from '@getodk/common/constants/xmlns.ts';
+import { escapeXMLText } from '../xml-serialization.ts';
+import type { NamespaceDeclarationMap } from './NamespaceDeclarationMap.ts';
+import type { NamespaceURI } from './QualifiedName.ts';
+import { QualifiedName } from './QualifiedName.ts';
+
+interface NamespaceDeclarationXMLSerializationOptions {
+	readonly omitDefaultNamespace?: boolean;
+}
+
+export interface NamespaceDeclarationOptions {
+	readonly declaredPrefix: string | null;
+	readonly declaredURI: NamespaceURI;
+}
+
+/**
+ * Provides a generalized representation of an XML namespace declaration, which
+ * can be used for:
+ *
+ * - Resolution of a declared namespace URI, by its declared prefix
+ * - Resolution of a declared namespace prefix associated with its namespace URI
+ * - Scoped resolution of same in an arbitrary DOM-like tree of nodes (or
+ *   representations thereof)
+ * - Serialization of the namespace declaration as an XML representation, as
+ *   part of broader XML serialization logic from an arbitrary DOM-like tree of
+ *   nodes (or representations thereof)
+ *
+ * @see {@link NamespaceDeclarationMap} for details on scoped usage
+ */
+export class NamespaceDeclaration {
+	private readonly serializedXML: string;
+
+	/**
+	 * A namespace is declared as either:
+	 *
+	 * - a "default" namespace (for which no prefix is declared, in which case
+	 *   this value will be `null`)
+	 *
+	 * - a namespace prefix (for which the prefix can be used to reference the
+	 *   declared namespace, in which case this value will be a `string`)
+	 */
+	readonly declaredPrefix: string | null;
+
+	/**
+	 * A namespace is declared for a {@link NamespaceURI}, i.e. either a
+	 * {@link URL} or `null`, where `null` corresponds to the "null namespace"
+	 * (i.e. `xmlns=""` or `xmlns:prefix=""`, in serialized XML).
+	 */
+	readonly declaredURI: NamespaceURI;
+
+	constructor(options: NamespaceDeclarationOptions) {
+		const { declaredPrefix, declaredURI } = options;
+
+		/**
+		 * Represents the {@link QualifiedName} **of the {@link NamespaceDeclaration} itself, used only for consistent XML serialization logic.
+		 */
+		let qualifiedName: QualifiedName;
+
+		switch (declaredPrefix) {
+			// Declaring a "null prefix" is equivalent to the following XML syntax:
+			// `xmlns="..."`
+			case null:
+				qualifiedName = new QualifiedName({
+					namespaceURI: XMLNS_NAMESPACE_URI,
+					prefix: null,
+					localName: XMLNS_PREFIX,
+				});
+
+				break;
+
+			// Declaring a non-null prefix is equivalent to the following XML syntax:
+			// `xmlns:$declaredPrefix="..."
+			default:
+				qualifiedName = new QualifiedName({
+					namespaceURI: XMLNS_NAMESPACE_URI,
+					prefix: XMLNS_PREFIX,
+					localName: declaredPrefix,
+				});
+				break;
+		}
+
+		this.declaredPrefix = declaredPrefix;
+		this.declaredURI = declaredURI;
+
+		const serializedName = qualifiedName.getPrefixedName();
+		const serializedValue = escapeXMLText(declaredURI?.href ?? '');
+
+		this.serializedXML = ` ${serializedName}="${serializedValue}"`;
+	}
+
+	declaresNamespaceURI(namespaceURI: NamespaceURI) {
+		if (namespaceURI == null) {
+			return this.declaredURI === null;
+		}
+
+		return this.declaredURI?.href === namespaceURI.href;
+	}
+
+	serializeNamespaceDeclarationXML(options?: NamespaceDeclarationXMLSerializationOptions): string {
+		if (options?.omitDefaultNamespace && this.declaredPrefix == null) {
+			return '';
+		}
+
+		return this.serializedXML;
+	}
+}

package/src/lib/names/NamespaceDeclarationMap.ts

@@ -0,0 +1,228 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { NamespaceDeclaration } from './NamespaceDeclaration.ts';
+import type { NamespaceURI, QualifiedName } from './QualifiedName.ts';
+
+export interface NamedNodeDefinition {
+	readonly qualifiedName: QualifiedName;
+}
+
+type NamedNodeDefinitionMap = ReadonlyMap<QualifiedName, NamedNodeDefinition>;
+
+export interface NamedSubtreeDefinition extends NamedNodeDefinition {
+	readonly namespaceDeclarations: NamespaceDeclarationMap;
+	readonly parent: NamedSubtreeDefinition | null;
+	readonly attributes?: NamedNodeDefinitionMap;
+}
+
+/**
+ * @todo This is a bit of a code style experiment! Responsive to
+ * {@link https://github.com/getodk/web-forms/issues/296 | How should we represent enumerated types?}.
+ * Observations to be considered for that issue...
+ *
+ * This more or less works as one would expect, with one really irritating
+ * downside: unlike a **TypeScript `enum`**, code completions (in VSCode, but
+ * I'd expect the same for any TypeScript language server/LSP implementation)
+ * automatically suggest the bare string values rather than the equivalent
+ * syntax referencing the enumerations as defined here. Without care, it would
+ * be fairly trivial to lose consistency between the source "enum" and consuming
+ * code which we presume to be an exhaustive check (such as the `switch`
+ * statement operating on it below). This is somewhat mitigated for now by
+ * habitual use of {@link UnreachableError} (and would be better mitigated by a
+ * lint rule to enforce exhaustiveness checks over similar enumerations). But
+ * there is an obvious _stylistic mismatch_ between how an editor treats "thing
+ * shaped like `enum` but not semantically an `enum`", whereas there's no such
+ * mismatch in how it treats a plain "union of strings". If nothing else, that
+ * mismatch would tend to exacerbate exhaustiveness drift as an enumeration
+ * evolves.
+ */
+const DECLARE_NAMESPACE_RESULTS = {
+	SUCCESS: 'SUCCESS',
+	HOISTED: 'HOISTED',
+	DEFERRED: 'DEFERRED',
+	REDUNDANT: 'REDUNDANT',
+	CONFLICT: 'CONFLICT',
+} as const;
+
+type DeclareNamespaceResultEnum = typeof DECLARE_NAMESPACE_RESULTS;
+
+type DeclareNamespaceResult = DeclareNamespaceResultEnum[keyof DeclareNamespaceResultEnum];
+
+export class NamespaceDeclarationMap extends Map<string | null, NamespaceDeclaration> {
+	constructor(readonly subtree: NamedSubtreeDefinition) {
+		super();
+
+		this.declareNamespace(subtree);
+
+		const { attributes } = subtree;
+
+		if (attributes != null) {
+			for (const attribute of attributes.values()) {
+				this.declareNamespace(attribute);
+			}
+		}
+	}
+
+	/**
+	 * For any {@link definition | named node definition}, we can _infer_ a
+	 * namespace declaration (rather than parsing it directly, which is error
+	 * prone depending on parsing context) from that definition's
+	 * {@link QualifiedName.namespaceURI} and {@link QualifiedName.prefix} (if the
+	 * latter is defined).
+	 *
+	 * If a namespace declaration can be inferred, we "declare" (set, in
+	 * {@link Map} semantics) it in **EITHER**:
+	 *
+	 * - An ancestor {@link NamedSubtreeDefinition | named subtree definition}'s
+	 *   {@link NamespaceDeclarationMap}: if such an ancestor exists and has no
+	 *   conflicting declaration for the same prefix; **OR**
+	 * - This {@link NamespaceDeclarationMap}, if no suitable ancestor exists
+	 *
+	 * This can be described as "hoisting" the declaration to the uppermost node
+	 * (or definitional representation of same) where it would be valid to declare
+	 * the namespace for its prefix.
+	 *
+	 * In the following example, note that this logic applies for arbitrary tree
+	 * structures satisfying the {@link NamedNodeDefinition} and
+	 * {@link NamedSubtreeDefinition} interfaces. XML syntax is used to provide a
+	 * concise explanation, but it should not be inferred that this is operating
+	 * directly on an XML value (or any platform-native DOM structure of the
+	 * same).
+	 *
+	 * @example Given an input tree like:
+	 *
+	 * ```xml
+	 * <foo xmlns="https://example.com/DEFAULT_ONE">
+	 *   <bar:bat xmlns:bar="https://example.com/bar"/>
+	 *   <baz xmlns="https://example.com/DEFAULT_TWO"/>
+	 * </foo>
+	 * ```
+	 *
+	 * The namespace declarations will be assigned as if they'd been declared
+	 * like:
+	 *
+	 * ```xml
+	 * <foo
+	 *   xmlns="https://example.com/DEFAULT_ONE"
+	 *   xmlns:bar="https://example.com/bar"
+	 * >
+	 *   <!-- bar declaration has no conflict in foo, hoisted to parent -->
+	 *   <bar:bat/>
+	 *   <!-- default declaration conflicts with foo's default, not hoisted -->
+	 *   <baz xmlns="https://example.com/DEFAULT_TWO"/>
+	 * </foo>
+	 * ```
+	 *
+	 * **IMPORTANT:** this behavior may seem overly complicated! It should be
+	 * noted that the behavior:
+	 *
+	 * 1. ... is conceptually similar to behavior observable in a web standard
+	 *    WHAT Working Group DOM (as in browser DOM, XML DOM) implementation.
+	 *    There, serializing any subtree element will produce namespace
+	 *    declarations on the root element for any namespaces _referenced within
+	 *    its subtree but declared on an ancestor_. Note that in this case, the
+	 *    hierarchical behavior is inverted, but it demonstrates the same
+	 *    effective namespace scoping semantics.
+	 *
+	 * 2. ... vastly simplifies our ability to produce a compact XML
+	 *    representation from any arbitrary tree representation of its nodes.
+	 *    Hoisting namespace declarations to their uppermost scope, and
+	 *    deduplicating recursively up the ancestor tree, ensures that we only
+	 *    declare a given namespace once as it is referenced.
+	 *
+	 * @todo While this design is intended to help with producing compact
+	 * serialized XML, at time of writing there is still an aspect which is
+	 * unaddressed in the serialization logic: we assume namespace declarations
+	 * are referenced if they've been parsed. This logic doesn't hold for nodes
+	 * which are ultimately omitted from serialization, which would occur for
+	 * non-relevant nodes, and repeat ranges with zero repeat instances (or any of
+	 * their descendants). A future iteration of this same behavior could produce
+	 * XML which is theoretically more compact, by performing the same declaration
+	 * hoisting logic _dynamically at call time_ rather than at parse time.
+	 */
+	declareNamespace(definition: NamedNodeDefinition): DeclareNamespaceResult {
+		const { prefix, namespaceURI } = definition.qualifiedName;
+
+		if (typeof prefix === 'symbol') {
+			return DECLARE_NAMESPACE_RESULTS.DEFERRED;
+		}
+
+		const parentNamespaceDeclarations = this.subtree.parent?.namespaceDeclarations;
+
+		if (parentNamespaceDeclarations != null) {
+			const ancestorResult = parentNamespaceDeclarations.declareNamespace(definition);
+
+			switch (ancestorResult) {
+				case DECLARE_NAMESPACE_RESULTS.CONFLICT:
+					break;
+
+				case DECLARE_NAMESPACE_RESULTS.DEFERRED:
+					return ancestorResult;
+
+				case DECLARE_NAMESPACE_RESULTS.HOISTED:
+					return ancestorResult;
+
+				case DECLARE_NAMESPACE_RESULTS.SUCCESS:
+				case DECLARE_NAMESPACE_RESULTS.REDUNDANT:
+					return DECLARE_NAMESPACE_RESULTS.HOISTED;
+
+				default:
+					throw new UnreachableError(ancestorResult);
+			}
+		}
+
+		const currentDeclaration = this.get(prefix);
+
+		if (currentDeclaration == null) {
+			this.set(
+				prefix,
+				new NamespaceDeclaration({
+					declaredPrefix: prefix,
+					declaredURI: namespaceURI,
+				})
+			);
+
+			return DECLARE_NAMESPACE_RESULTS.SUCCESS;
+		}
+
+		if (currentDeclaration.declaresNamespaceURI(namespaceURI)) {
+			return DECLARE_NAMESPACE_RESULTS.REDUNDANT;
+		}
+
+		return DECLARE_NAMESPACE_RESULTS.CONFLICT;
+	}
+
+	/**
+	 * Given a {@link namespaceURI}, resolves a declared prefix (which may be
+	 * `null`) for the {@link subtree} context **or any of its ancestors**. This
+	 * is an important semantic detail:
+	 *
+	 * - Namespace declarations on a given subtree are effective for all of its
+	 *   descendants _until another declaration for the same prefix or namespace
+	 *   URI is encountered_
+	 * - We "hoist" namespace declarations up to the uppermost {@link subtree}'s
+	 *   {@link NamespaceDeclarationMap} during parsing (as described in more
+	 *   detail on {@link declareNamespace}).
+	 */
+	lookupPrefix(namespaceURI: NamespaceURI): string | null {
+		const namespace = String(namespaceURI);
+
+		// Note: this is a dynamic lookup on the _very unlikely_ chance that a
+		// lookup occurs while parsing is still in progress. It's expected that we
+		// collect all namespace declarations by the time parsing is complete, at
+		// which point we could theoretically collect a companion map where the
+		// namespace URI is used as a key. This has been deferred for now, because
+		// we'd need:
+		//
+		// 1. To know _in this class_ when parsing is complete (which seems like a
+		//    huge excess of mixed responsibilities!)
+		// 2. To resolve the "object-as-value-as-map-key" problem, which has also
+		//    been deferred.
+		for (const namespaceDeclaration of this.values()) {
+			if (String(namespaceDeclaration.declaredURI) === namespace) {
+				return namespaceDeclaration.declaredPrefix;
+			}
+		}
+
+		return this.subtree.parent?.namespaceDeclarations.lookupPrefix(namespaceURI) ?? null;
+	}
+}

package/src/lib/names/NamespaceURL.ts

@@ -0,0 +1,44 @@
+import type { NamespaceDeclaration } from './NamespaceDeclaration.ts';
+
+/**
+ * Convenience wrapper to represent an XML namespace URI as a {@link URL}. This
+ * representation is used/responsible for:
+ *
+ * - normalized logic for XML semantics around special namespace URI values, in
+ *   particular for consistent handling of the "null namespace" (input for such
+ *   is accepted as either an empty string or `null`)
+ * - validation of input: a non-"null namespace" value will be rejected if it is
+ *   not a valid URI string
+ * - type-level distinction between a namespace URI and a
+ *   {@link NamespaceDeclaration.declaredPrefix | namespace declaration's prefix},
+ *   as an aide to avoid using one in place of the other as e.g. a positional
+ *   argument
+ *
+ * @todo Test the finer distinctions between "URL" and "URI"!
+ *
+ * @todo Probably not a huge deal in the scheme of things, but this is almost
+ * entirely pure overhead at runtime! The "validation" use case is kind of a
+ * stretch, and may well be wrong. The type-level distinction from a namespace
+ * prefix, however, has proved useful **quite a few times** during iteration of
+ * this change. If we can actually measure an impact, it might be worth instead
+ * considering "branded types" for the type-level distinct (in which case we
+ * could use a factory function to handle both the branding and special XML
+ * semantics).
+ */
+export class NamespaceURL extends URL {
+	static from(namespaceURI: NamespaceURL | string | null): NamespaceURL | null {
+		if (namespaceURI == null || namespaceURI === '') {
+			return null;
+		}
+
+		return new this(String(namespaceURI));
+	}
+
+	override readonly href: string;
+
+	private constructor(href: string) {
+		super(href);
+
+		this.href = href;
+	}
+}