@endevops/effect-codec-xml 0.0.1

package/dist/namespaces.js

@@ -0,0 +1,663 @@
+import { TEXT_KEY, isAttributeKey } from "./conventions.js";
+import { Predicate, SchemaAST } from "effect";
+//#region src/namespaces.ts
+/**
+* @description The annotation key holding an element's namespace URI.
+*/
+const NAMESPACE_KEY = "xmlNamespace";
+/**
+* @description The annotation key holding the wire prefix for an element's namespace.
+*/
+const PREFIX_KEY = "xmlPrefix";
+/**
+* @description The annotation key holding the wire local name for an element or attribute.
+*/
+const NAME_KEY = "xmlName";
+/**
+* @description The annotation key marking a field as an XML attribute.
+*/
+const ATTRIBUTE_KEY = "xmlAttribute";
+/**
+* @description The annotation key marking a field as the element's character data.
+*/
+const VALUE_KEY = "xmlValue";
+/**
+* @description The namespace an AST's own annotations declare, or `undefined`. `Schema.optional` and `Schema.suspend` wrap a node without moving its annotation,
+* so both are unwrapped to find the namespace the field actually carries.
+*
+* @param ast - The AST to read.
+*
+* @returns The namespace, or `undefined`.
+*/
+const annotationAt = (ast, key) => {
+	const seen = /* @__PURE__ */ new Set();
+	const find = (node) => {
+		if (seen.has(node)) return void 0;
+		seen.add(node);
+		const value = SchemaAST.resolve(node)?.[key];
+		if (value !== void 0) return value;
+		if (node._tag === "Union") {
+			for (const member of node.types) {
+				const found = find(member);
+				if (found !== void 0) return found;
+			}
+			return;
+		}
+		return node._tag === "Suspend" ? find(node.thunk()) : void 0;
+	};
+	return find(ast);
+};
+/**
+* @description The namespace an AST's own annotations declare, or `undefined`. `Schema.optional` and `Schema.suspend` wrap a node without moving its annotation,
+* so both are unwrapped to find the namespace the field carries.
+*
+* @param ast - The AST to read.
+*
+* @returns The namespace, or `undefined`.
+*/
+const namespaceOf = (ast) => {
+	const uri = annotationAt(ast, NAMESPACE_KEY);
+	if (!Predicate.isString(uri)) return void 0;
+	const prefix = annotationAt(ast, PREFIX_KEY);
+	return {
+		uri,
+		prefix: Predicate.isString(prefix) ? prefix : ""
+	};
+};
+/**
+* @description The wire local name an AST's own annotations declare, or `undefined`.
+*
+* @param ast - The AST to read.
+*
+* @returns The local name, or `undefined`.
+*/
+const nameOf = (ast) => {
+	const name = annotationAt(ast, NAME_KEY);
+	return Predicate.isString(name) ? name : void 0;
+};
+/**
+* @description The namespace a property carries when its annotation was attached with `Schema.annotateKey` rather than to the field's schema.
+*
+* @param ast - The property's value AST, whose context holds the key annotations.
+*
+* @returns The namespace, or `undefined`.
+*/
+const keyNamespaceOf = (ast) => {
+	const annotations = ast.context?.annotations;
+	const uri = annotations?.[NAMESPACE_KEY];
+	if (!Predicate.isString(uri)) return void 0;
+	const prefix = annotations?.[PREFIX_KEY];
+	return {
+		uri,
+		prefix: Predicate.isString(prefix) ? prefix : ""
+	};
+};
+/**
+* @description The wire local name a property's key annotations declare, or `undefined`.
+*
+* @param ast - The property's value AST, whose context holds the key annotations.
+*
+* @returns The local name, or `undefined`.
+*/
+const keyNameOf = (ast) => {
+	const name = ast.context?.annotations?.[NAME_KEY];
+	return Predicate.isString(name) ? name : void 0;
+};
+/**
+* @description Whether an AST's own annotations mark the field as an XML attribute.
+*
+* @param ast - The AST to read.
+*
+* @returns Whether the annotation is set.
+*/
+const attributeOf = (ast) => annotationAt(ast, ATTRIBUTE_KEY) === true;
+/**
+* @description Whether a property's key annotations mark the field as an XML attribute.
+*
+* @param ast - The property's value AST, whose context holds the key annotations.
+*
+* @returns Whether the annotation is set.
+*/
+const keyAttributeOf = (ast) => ast.context?.annotations?.[ATTRIBUTE_KEY] === true;
+/**
+* @description Whether an AST's own annotations mark the field as the element's character data.
+*
+* @param ast - The AST to read.
+*
+* @returns Whether the annotation is set.
+*/
+const valueOf = (ast) => annotationAt(ast, VALUE_KEY) === true;
+/**
+* @description Whether a property's key annotations mark the field as the element's character data.
+*
+* @param ast - The property's value AST, whose context holds the key annotations.
+*
+* @returns Whether the annotation is set.
+*/
+const keyValueOf = (ast) => ast.context?.annotations?.[VALUE_KEY] === true;
+/**
+* @description Whether a struct property holds the element's character data, marked with `xmlValue` on its schema or its key.
+*
+* @param ast - The property's value AST.
+*
+* @returns Whether the property is the value.
+*/
+const isValueProperty = (ast) => keyValueOf(ast) || valueOf(ast);
+/**
+* @description The local name a schema key names, with the attribute prefix removed. This is what a declaration resolves to.
+*
+* @param key - The schema key.
+*
+* @returns The local name.
+*/
+const localName = (key) => isAttributeKey(key) ? key.slice(1) : key;
+/**
+* @description The separator between the schema keys in an element path. A NUL is not a legal XML name character, so it cannot collide with a key.
+*/
+const PATH_SEPARATOR = "\0";
+/**
+* @description The path of a child element, appended to its parent's path.
+*
+* @param parent - The parent element's path.
+* @param key - The child's schema key.
+*
+* @returns The child's path.
+*/
+const childPath = (parent, key) => parent === "" ? key : `${parent}${PATH_SEPARATOR}${key}`;
+/**
+* @description The schema key at the end of an element path.
+*
+* @param path - The element path.
+*
+* @returns The schema key of the element itself.
+*/
+const pathKey = (path) => {
+	const at = path.lastIndexOf(PATH_SEPARATOR);
+	return at === -1 ? path : path.slice(at + 1);
+};
+/**
+* @description Whether a field is an attribute: the key at the end of its path carries the `@` prefix, or `xmlAttribute` marks the field.
+*
+* @param plan - The namespace plan.
+* @param path - The field's element path.
+*
+* @returns Whether the field is an attribute.
+*/
+const isAttributeOf = (plan, path) => isAttributeKey(pathKey(path)) || plan.attributeKeys.has(path);
+/**
+* @description The wire local name of a field: its `xmlName` override, or the key at the end of its path with the attribute prefix removed.
+*
+* @param plan - The namespace plan.
+* @param path - The field's element path.
+*
+* @returns The local name.
+*/
+const localOf = (plan, path) => plan.nameByKey.get(path) ?? localName(pathKey(path));
+/**
+* @description The reverse-lookup key for a resolved wire name. The attribute flag is part of it, so an element and an attribute of the same local name in the
+* same namespace stay distinct.
+*
+* @param isAttribute - Whether the name is an attribute.
+* @param uri - The resolved namespace URI, or `undefined`.
+* @param local - The resolved local name.
+*
+* @returns The lookup key.
+*/
+const resolvedKey = (isAttribute, uri, local) => `${isAttribute ? "@" : ""}${uri ?? ""}|${local}`;
+/**
+* @description The path of the parent element, one segment shorter than the field's own path.
+*
+* @param path - The field's element path.
+*
+* @returns The parent element's path, or the root sentinel.
+*/
+const parentPath = (path) => {
+	const at = path.lastIndexOf(PATH_SEPARATOR);
+	return at === -1 ? "" : path.slice(0, at);
+};
+/**
+* @description The reverse-lookup key for a wire name under one parent element. The parent's path is part of it, so the same wire name under two parents resolves
+* to each parent's own field.
+*
+* @param parent - The parent element's path.
+* @param resolved - A name from {@link resolvedKey}.
+*
+* @returns The lookup key.
+*/
+const lookupKey = (parent, resolved) => `${parent}\u0001${resolved}`;
+/**
+* @description Records a field's namespace, reporting a local name that would belong to two namespaces at once.
+*
+* @param scan - The scan state.
+* @param path - The field's element path.
+* @param namespace - The namespace, or `undefined` when the field has none.
+*/
+const record = (scan, path, namespace) => {
+	if (Predicate.isUndefined(namespace)) return;
+	const previous = scan.byKey.get(path);
+	if (Predicate.isNotUndefined(previous) && (previous.uri !== namespace.uri || previous.prefix !== namespace.prefix)) scan.problems.push(`the local name "${pathKey(path)}" belongs to more than one namespace (${previous.uri}:${previous.prefix} vs ${namespace.uri}:${namespace.prefix})`);
+	else scan.byKey.set(path, namespace);
+};
+/**
+* @description Records a field's `xmlName` override, refusing one that carries a prefix because the prefix comes from `xmlPrefix`.
+*
+* @param scan - The scan state.
+* @param path - The field's element path.
+* @param name - The annotated local name, or `undefined`.
+*/
+const recordName = (scan, path, name) => {
+	if (Predicate.isUndefined(name)) return;
+	if (name.includes(":")) scan.problems.push(`xmlName "${name}" on "${pathKey(path)}" must be a local name; use xmlPrefix for the prefix`);
+	else scan.nameByKey.set(path, name);
+};
+/**
+* @description Records a field's namespace, refusing the two annotations that cannot be honored: a namespaced field whose name already carries a prefix, and a
+* namespaced attribute without a prefix, because a default namespace does not apply to attributes.
+*
+* @param scan - The scan state.
+* @param path - The field's element path.
+* @param isAttribute - Whether the field is an attribute.
+* @param field - The field's own namespace, or `undefined`.
+* @param inherited - The namespace the enclosing element passes down.
+*/
+const recordFieldNamespace = (scan, path, isAttribute, field, inherited) => {
+	const key = pathKey(path);
+	if (Predicate.isNotUndefined(field) && key.includes(":")) scan.problems.push(`"${key}" already carries a prefix, so it cannot also carry a namespace annotation`);
+	else if (isAttribute && Predicate.isNotUndefined(field) && field.prefix === "") scan.problems.push(`the attribute "${key}" needs xmlPrefix, because a default namespace does not apply to attributes`);
+	else record(scan, path, isAttribute ? field : field ?? inherited);
+};
+/**
+* @description Whether a struct property is an attribute: its key carries the `@` prefix, or its own or key annotation marks it.
+*
+* @param key - The schema key.
+* @param ast - The property's value AST.
+*
+* @returns Whether the property is an attribute.
+*/
+const isAttributeProperty = (key, ast) => isAttributeKey(key) || keyAttributeOf(ast) || attributeOf(ast);
+/**
+* @description Notes a field that `xmlAttribute` marks as an attribute but whose name does not carry the `@` prefix.
+*
+* @param scan - The scan state.
+* @param path - The field's element path.
+* @param isAttribute - Whether the field is an attribute.
+*/
+const noteAttribute = (scan, path, isAttribute) => {
+	if (isAttribute && !isAttributeKey(pathKey(path))) scan.attributeKeys.add(path);
+};
+/**
+* @description Records a field marked `xmlValue` against the element that owns it, refusing the annotations a value cannot combine with: character data has no
+* name and no namespace, and an element has room for only one value.
+*
+* @param scan - The scan state.
+* @param elementPath - The path of the element the field belongs to, or the root sentinel.
+* @param valueKey - The schema key of the value field.
+* @param isAttribute - Whether the field is an attribute.
+* @param name - The field's `xmlName` override, or `undefined`.
+* @param field - The field's own namespace, or `undefined`.
+*/
+const recordValue = (scan, elementPath, valueKey, isAttribute, name, field) => {
+	if (isAttribute) scan.problems.push(`the field "${valueKey}" is marked as both an attribute and the element's value`);
+	else if (Predicate.isNotUndefined(name)) scan.problems.push(`the value field "${valueKey}" cannot have an xmlName, because character data has no name`);
+	else if (Predicate.isNotUndefined(field)) scan.problems.push(`the value field "${valueKey}" cannot have a namespace, because character data has none`);
+	else {
+		const previous = scan.valueByElement.get(elementPath);
+		if (Predicate.isNotUndefined(previous) && previous !== valueKey) scan.problems.push(`the element "${elementPath === "" ? "root" : elementPath}" has more than one value field, "${previous}" and "${valueKey}"`);
+		else scan.valueByElement.set(elementPath, valueKey);
+	}
+};
+/**
+* @description Records one struct property: its `xmlName`, its namespace, and the namespace its descendants inherit. An attribute carries a namespace only when
+* annotated; an element field falls back to the namespace it inherits. A value field is character data, so it is recorded against its element
+* instead.
+*
+* @param scan - The scan state.
+* @param property - The property signature.
+* @param inherited - The namespace the enclosing element passes down.
+* @param elementPath - The path of the element the property belongs to, or the root sentinel.
+*/
+const scanProperty = (scan, property, inherited, elementPath) => {
+	const key = Predicate.isString(property.name) ? property.name : String(property.name);
+	const path = childPath(elementPath, key);
+	const isAttribute = isAttributeProperty(key, property.type);
+	const isValue = isValueProperty(property.type);
+	const name = keyNameOf(property.type) ?? nameOf(property.type);
+	const field = keyNamespaceOf(property.type) ?? namespaceOf(property.type);
+	if (isValue) recordValue(scan, elementPath, key, isAttribute, name, field);
+	else {
+		noteAttribute(scan, path, isAttribute);
+		recordName(scan, path, name);
+		recordFieldNamespace(scan, path, isAttribute, field, inherited);
+	}
+	scanNode(scan, property.type, isAttribute ? inherited : field ?? inherited, path);
+};
+/**
+* @description Walks a list of child ASTs under one inherited namespace.
+*
+* @param scan - The scan state.
+* @param nodes - The child ASTs.
+* @param inherited - The namespace they inherit.
+* @param elementPath - The path of the element they belong to, or the root sentinel.
+*/
+const scanAll = (scan, nodes, inherited, elementPath) => {
+	for (const node of nodes) scanNode(scan, node, inherited, elementPath);
+};
+/**
+* @description Records the names in one object node: its properties and its index signatures, each under the namespace the object passes down.
+*
+* @param scan - The scan state.
+* @param ast - The object AST.
+* @param namespace - The namespace the object passes to its members.
+* @param elementPath - The path of the element the object describes, or the root sentinel.
+*/
+const scanObject = (scan, ast, namespace, elementPath) => {
+	for (const property of ast.propertySignatures) scanProperty(scan, property, namespace, elementPath);
+	for (const index of ast.indexSignatures) scanNode(scan, index.type, namespace, elementPath);
+};
+/**
+* @description Notes an array field that names its element with `xmlName`, so the decoder reads a single occurrence as a one-member array. An unnamed array keeps
+* the ambiguity and does not wrap.
+*
+* @param scan - The scan state.
+* @param ast - The AST being scanned.
+* @param elementPath - The path of the field the AST describes.
+*/
+const noteArray = (scan, ast, elementPath) => {
+	if (ast._tag === "Arrays" && scan.nameByKey.has(elementPath)) scan.arrayKeys.add(elementPath);
+};
+/**
+* @description Records every name in one schema AST, carrying the namespace an element passes to its descendants and the element the names belong to.
+*
+* @param scan - The scan state.
+* @param ast - The AST to walk.
+* @param inherited - The namespace the enclosing element passes down.
+* @param elementPath - The path of the element this AST describes, or the root sentinel.
+*/
+const scanNode = (scan, ast, inherited, elementPath) => {
+	if (scan.seen.has(ast)) return;
+	scan.seen.add(ast);
+	try {
+		noteArray(scan, ast, elementPath);
+		const namespace = namespaceOf(ast) ?? inherited;
+		switch (ast._tag) {
+			case "Objects":
+				scanObject(scan, ast, namespace, elementPath);
+				return;
+			case "Arrays":
+				scanAll(scan, [...ast.elements, ...ast.rest], namespace, elementPath);
+				return;
+			case "Union":
+				scanAll(scan, ast.types, namespace, elementPath);
+				return;
+			case "Suspend":
+				scanNode(scan, ast.thunk(), namespace, elementPath);
+				return;
+			case "Declaration":
+				scanAll(scan, ast.typeParameters, namespace, elementPath);
+				return;
+			default: return;
+		}
+	} finally {
+		scan.seen.delete(ast);
+	}
+};
+/**
+* @description Collects the namespace and name of every field in a schema. A namespace is inherited by descendant elements, the way a default namespace is, and an
+* element field records its own namespace, so encode and decode can find it by the local name alone.
+*
+* @param schema - The schema to walk.
+*
+* @returns The plan, or the annotations that cannot be honored.
+*/
+const namespacePlan = (schema) => {
+	const scan = {
+		byKey: /* @__PURE__ */ new Map(),
+		nameByKey: /* @__PURE__ */ new Map(),
+		attributeKeys: /* @__PURE__ */ new Set(),
+		valueByElement: /* @__PURE__ */ new Map(),
+		arrayKeys: /* @__PURE__ */ new Set(),
+		problems: [],
+		seen: /* @__PURE__ */ new Set()
+	};
+	scanNode(scan, schema.ast, void 0, "");
+	const byResolved = /* @__PURE__ */ new Map();
+	for (const path of /* @__PURE__ */ new Set([
+		...scan.byKey.keys(),
+		...scan.nameByKey.keys(),
+		...scan.attributeKeys
+	])) {
+		const key = pathKey(path);
+		const namespace = scan.byKey.get(path);
+		const isAttribute = isAttributeKey(key) || scan.attributeKeys.has(path);
+		const local = scan.nameByKey.get(path) ?? localName(key);
+		const resolved = lookupKey(parentPath(path), resolvedKey(isAttribute, namespace?.uri, local));
+		const previous = byResolved.get(resolved);
+		if (previous !== void 0 && previous !== key) scan.problems.push(`"${previous}" and "${key}" both resolve to "${local}" under the same element`);
+		else byResolved.set(resolved, key);
+	}
+	if (scan.problems.length > 0) return { error: [...new Set(scan.problems)].join(";\n	- ") };
+	return { plan: {
+		byKey: scan.byKey,
+		nameByKey: scan.nameByKey,
+		attributeKeys: scan.attributeKeys,
+		valueByElement: scan.valueByElement,
+		arrayKeys: scan.arrayKeys,
+		root: namespaceOf(schema.ast),
+		rootName: nameOf(schema.ast),
+		byResolved
+	} };
+};
+/**
+* @description Whether a key is a namespace declaration the codec manages: `@xmlns` or `@xmlns:prefix`.
+*
+* @param key - The record key.
+*
+* @returns Whether the key is a declaration.
+*/
+const isDeclarationKey = (key) => key === `@xmlns` || key.startsWith(`@xmlns:`);
+/**
+* @description The prefix a declaration key carries, or `''` for the default namespace.
+*
+* @param key - A key {@link isDeclarationKey} accepted.
+*
+* @returns The prefix.
+*/
+const declarationPrefix = (key) => key === `@xmlns` ? "" : key.slice(`@xmlns:`.length);
+/**
+* @description Writes the declaration for a namespace into an element's record, when the scope does not already bind it. A prefixed namespace is declared as
+* `xmlns:prefix`; the default namespace as `xmlns`; and an element that leaves a default namespace in scope for no namespace of its own clears it
+* with `xmlns=""`.
+*
+* @param out - The element's record, written in place.
+* @param scope - The in-scope prefix bindings, updated in place.
+* @param namespace - The element's namespace, or `undefined`.
+*/
+const declare = (out, scope, namespace) => {
+	if (Predicate.isNotUndefined(namespace) && namespace.prefix !== "") {
+		if (scope[namespace.prefix] === namespace.uri) return;
+		out[`@xmlns:${namespace.prefix}`] = namespace.uri;
+		scope[namespace.prefix] = namespace.uri;
+		return;
+	}
+	if (!Predicate.isUndefined(namespace)) {
+		if (scope[""] === namespace.uri) return;
+		out[`@xmlns`] = namespace.uri;
+		scope[""] = namespace.uri;
+		return;
+	}
+	if (Predicate.isUndefined(scope[""])) return;
+	out[`@xmlns`] = "";
+	scope[""] = void 0;
+};
+/**
+* @description The wire key for one field: the local name with the prefix its namespace declares, or the local name unchanged when there is no prefix.
+*
+* @param plan - The namespace plan.
+* @param path - The field's element path.
+* @param namespace - The field's namespace, or `undefined`.
+*
+* @returns The key to write.
+*/
+const wireKey = (plan, path, namespace) => {
+	const isAttribute = isAttributeOf(plan, path);
+	const local = localOf(plan, path);
+	if (Predicate.isUndefined(namespace) || namespace.prefix === "") return isAttribute ? `@${local}` : local;
+	return `${isAttribute ? "@" : ""}${namespace.prefix}:${local}`;
+};
+/**
+* @description Writes one record's fields under the element's scope: an attribute is a leaf and declares its prefix on this element, the value field becomes the
+* element's character data, and a child element recurses with its own namespace.
+*
+* @param value - The element's record, keyed by the schema's local names.
+* @param plan - The namespace plan.
+* @param out - The wire record, written in place.
+* @param scope - The prefix bindings in scope for this element.
+* @param elementPath - The path of this element, or the root sentinel.
+*/
+const encodeFields = (value, plan, out, scope, elementPath) => {
+	const valueKey = plan.valueByElement.get(elementPath);
+	for (const [key, child] of Object.entries(value)) {
+		if (isDeclarationKey(key)) continue;
+		if (key === valueKey) {
+			out[TEXT_KEY] = child;
+			continue;
+		}
+		const path = childPath(elementPath, key);
+		const childNamespace = plan.byKey.get(path);
+		if (isAttributeOf(plan, path)) {
+			if (Predicate.isNotUndefined(childNamespace)) declare(out, scope, childNamespace);
+			out[wireKey(plan, path, childNamespace)] = child;
+			continue;
+		}
+		out[wireKey(plan, path, childNamespace)] = encodeNames(child, plan, childNamespace, scope, path);
+	}
+};
+/**
+* @description Rewrites a value tree into its namespaced wire form: every field with a plan entry gets its prefix, and every element declares the namespace its
+* subtree uses. A leaf that has to carry a declaration is wrapped as a `#text` record so the attribute has somewhere to live.
+*
+* @param value - The value tree, keyed by the schema's local names.
+* @param plan - The namespace plan.
+* @param namespace - This element's namespace.
+* @param scope - The prefix bindings in scope above this element.
+* @param elementPath - The path of this element, or the root sentinel.
+*
+* @returns The wire tree.
+*/
+const encodeNames = (value, plan, namespace, scope, elementPath) => {
+	if (Array.isArray(value)) return value.map((member) => encodeNames(member, plan, namespace, scope, elementPath));
+	const out = {};
+	const inner = { ...scope };
+	declare(out, inner, namespace);
+	if (Predicate.isUndefined(value)) return;
+	if (Predicate.isString(value)) return Object.keys(out).length > 0 ? {
+		...out,
+		[TEXT_KEY]: value
+	} : value;
+	if (!Predicate.isObject(value)) return value;
+	encodeFields(value, plan, out, inner, elementPath);
+	return out;
+};
+/**
+* @description Resolves a wire name to its URI and local name against the in-scope bindings. An unprefixed element takes the default namespace; an unprefixed
+* attribute has no namespace, because a default namespace does not apply to attributes.
+*
+* @param name - The name as written, without the attribute prefix.
+* @param isAttribute - Whether the name belongs to an attribute.
+* @param scope - The in-scope prefix bindings.
+*
+* @returns The resolved URI (possibly `undefined`) and local name.
+*/
+const resolveName = (name, isAttribute, scope) => {
+	const colon = name.indexOf(":");
+	if (colon === -1) return {
+		uri: isAttribute ? void 0 : scope[""],
+		local: name
+	};
+	return {
+		uri: scope[name.slice(0, colon)],
+		local: name.slice(colon + 1)
+	};
+};
+/**
+* @description Reads an element's declarations into a fresh scope that falls back to the enclosing one.
+*
+* @param value - The element's record.
+* @param scope - The bindings in scope above the element.
+*
+* @returns The element's own scope.
+*/
+const scopeOf = (value, scope) => {
+	const inner = { ...scope };
+	for (const [key, declaration] of Object.entries(value)) if (isDeclarationKey(key) && Predicate.isString(declaration)) inner[declarationPrefix(key)] = declaration;
+	return inner;
+};
+/**
+* @description The schema key a wire key resolves to under one parent element: the plan's key for its URI and local name, or the local name when the schema left
+* it unannotated.
+*
+* @param plan - The namespace plan.
+* @param parent - The parent element's path.
+* @param key - The wire key.
+* @param scope - The in-scope prefix bindings.
+*
+* @returns The schema key.
+*/
+const schemaKey = (plan, parent, key, scope) => {
+	const isAttribute = isAttributeKey(key);
+	const { uri, local } = resolveName(localName(key), isAttribute, scope);
+	return plan.byResolved.get(lookupKey(parent, resolvedKey(isAttribute, uri, local))) ?? (isAttribute ? `@${local}` : local);
+};
+/**
+* @description The scope a child element resolves its own name against: the declarations it carries on itself, layered over the parent scope. An element may
+* declare the prefix it uses on the element itself, so its own name is read with those bindings in scope. A repeated element arrives as an array, so
+* the first member stands in for the run — every member describes the same element and carries the same declaration.
+*
+* @param child - The child value.
+* @param scope - The bindings in scope above the child.
+*
+* @returns The scope to resolve the child's own name with.
+*/
+const childScopeOf = (child, scope) => {
+	if (Array.isArray(child)) return child.length > 0 ? childScopeOf(child[0], scope) : scope;
+	return Predicate.isObject(child) ? scopeOf(child, scope) : scope;
+};
+/**
+* @description Rewrites a wire value tree back to the schema's local names, resolving every name against the declarations the document carries and dropping those
+* declarations. Character data maps to the value field of the element it belongs to. A record left holding only character data collapses back to that
+* string, which is how a namespaced leaf stays a `Schema.String`.
+*
+* @param value - The parsed wire tree.
+* @param plan - The namespace plan.
+* @param scope - The prefix bindings in scope above this element.
+* @param elementPath - The path of this element, or the root sentinel.
+*
+* @returns The value tree, keyed by the schema's names.
+*/
+const decodeNames = (value, plan, scope, elementPath) => {
+	if (Array.isArray(value)) return value.map((member) => decodeNames(member, plan, scope, elementPath));
+	if (Predicate.isString(value) || Predicate.isUndefined(value)) return value;
+	if (!Predicate.isObject(value)) return value;
+	const record = value;
+	const inner = scopeOf(record, scope);
+	const valueKey = plan.valueByElement.get(elementPath);
+	const out = {};
+	for (const [key, child] of Object.entries(record)) {
+		if (isDeclarationKey(key)) continue;
+		if (key === "#text") {
+			out[valueKey ?? "#text"] = decodeNames(child, plan, inner, elementPath);
+			continue;
+		}
+		const childKey = schemaKey(plan, elementPath, key, childScopeOf(child, inner));
+		const path = childPath(elementPath, childKey);
+		const decoded = decodeNames(child, plan, inner, path);
+		out[childKey] = plan.arrayKeys.has(path) && !Array.isArray(decoded) ? [decoded] : decoded;
+	}
+	const keys = Object.keys(out);
+	if (keys.length === 1 && keys[0] === "#text") return out[TEXT_KEY];
+	return out;
+};
+//#endregion
+export { ATTRIBUTE_KEY, NAMESPACE_KEY, NAME_KEY, PREFIX_KEY, VALUE_KEY, decodeNames, encodeNames, namespacePlan };
+
+//# sourceMappingURL=namespaces.js.map