import { name, ncName, qName, nmToken, nmTokens } from 'xml-naming';// Name — colon allowed anywhere, used for DOCTYPE entity namesname('foo') // truename('a:b:c') // true ← multiple colons fine for Namename('1foo') // false ← digit start invalid// NCName — no colon, used for SVG id attributes, namespace prefixesncName('my-id') // truencName('xlink:href') // false ← colon not allowed// QName — exactly one colon as prefix separator, used for element/attribute namesqName('svg:circle') // trueqName('foo') // true ← unprefixed QName is validqName('a:b:c') // false ← only one colon allowedqName(':foo') // false ← cannot start with colon// NMToken — any NameChar at start, used for DTD NMTOKEN attributesnmToken('123') // true ← digit start is finenmToken('-bar') // truenmToken('foo bar') // false ← space not allowed// NMTokens — whitespace-separated NMToken listnmTokens('tok1 tok2 -foo 123') // true
XML version option
All validators accept an optional { xmlVersion } option:
import { name } from 'xml-naming';name('\u0085', { xmlVersion: '1.0' }) // false — NEL (Next Line), not in 1.0 rangesname('\u0085', { xmlVersion: '1.1' }) // true — explicitly allowed in 1.1name('\uD800\uDC00', { xmlVersion: '1.0' }) // falsename('\uD800\uDC00', { xmlVersion: '1.1' }) // true
ASCII-only fast path
All validators, validate, validateAll, and sanitize also accept { asciiOnly: true }.
When set, matching is restricted to the ASCII subset of the NameStartChar/NameChar
productions and skips unicode-aware regex matching entirely — no \u00C0-\uFFFD-style
ranges, and (for XML 1.1) no /u regex flag. Unicode-aware regexes are measurably slower
than plain ASCII matching in JS engines, so this is a real performance win when you know
your input is ASCII-only, which is the common case for HTML/SVG ids and most XML tags.
This is opt-in and defaults to false for backward compatibility: turning it on
changes behavior, since it rejects legitimate non-ASCII XML names that would otherwise be
valid. Only enable it when you control the input and know it's ASCII (e.g. internal
identifiers, machine-generated names), not for validating arbitrary user- or
externally-supplied XML/SVG content.
import { name, sanitize } from 'xml-naming';name('café', { asciiOnly: true }) // false — 'é' is not ASCII, even though it'sname('café') // true a valid XML 1.0/1.1 NameCharsanitize('café', 'name', { asciiOnly: true }) // 'caf_' — non-ASCII replaced toosanitize('café', 'name') // 'café' — left untouched by default
Memoized validator (createValidator)
Real documents tend to reuse a small vocabulary of tag/attribute names across many
siblings (id, class, href, ... repeated across hundreds of elements). Calling the
plain boolean validators re-runs the regex on every call, even for names seen before.
createValidator(production, opts) returns a memoized validator function: xmlVersion
and asciiOnly are fixed at creation time (so the regex is resolved once, not per call),
and repeated inputs after the first are served from an internal cache instead of
re-matching the regex.
import { createValidator } from 'xml-naming';const isQName = createValidator('qName', { xmlVersion: '1.0' });isQName('sku'); // false → regex test (cache miss), result cachedisQName('sku'); // false → cache hit, no regex run
Use one instance per document/parse (or reuse across a session — your choice), rather
than creating one per call:
// e.g. inside a parser, once per parse call:const isValidTag = createValidator('qName', { asciiOnly: true });for (const tagName of tagNames) { if (!isValidTag(tagName)) throw new Error(`Invalid tag name: ${tagName}`);}
Because the validator is a plain function, this loop already gets short-circuit
behaviour (via break/throw on first failure) and zero extra allocation on the happy
path — no separate "bulk" API is needed for that.
Cache bound: the internal cache is capped by maxCacheSize (default 2048). Once
the cap is reached, new distinct strings are still validated correctly, they're just no
longer cached — existing cached entries keep being served. This keeps memory bounded
even against high-cardinality or adversarial input (e.g. externally-supplied names that
never repeat), without the cost of a full LRU or the perf cliff of reset-and-refill.
Call .reset() on the returned function to clear the cache manually, e.g. between
unrelated parse calls if you're reusing one validator instance across a long-running
process:
isQName.reset();
The cache is private to each createValidator() instance — there's no shared/global
cache, so unrelated callers never interfere with each other.
Diagnostic validation
import { validate } from 'xml-naming';validate('svg:circle', 'qName')// { valid: true, production: 'qName', input: 'svg:circle' }validate('1foo', 'ncName')// {// valid: false,// production: 'ncName',// input: '1foo',// reason: 'First character "1" is not a valid NameStartChar',// position: 0// }validate('foo:bar', 'ncName')// {// valid: false,// production: 'ncName',// input: 'foo:bar',// reason: 'Colon is not allowed in NCName',// position: 3// }validate('a:b:c', 'qName')// {// valid: false,// production: 'qName',// input: 'a:b:c',// reason: 'QName can have at most one colon',// position: 3// }