@pipobscure/xml 0.1.0

package/dist/chars.js

@@ -0,0 +1,74 @@
+/**
+ * @pipobscure/xml — XML character classification
+ *
+ * All functions operate on numeric Unicode code points (from `charCodeAt`)
+ * for maximum performance on the ASCII-heavy content typical of
+ * CalDAV / CardDAV payloads.
+ *
+ * The ranges follow XML 1.0 (fifth edition) §2.2 and the XML Namespaces 1.0
+ * specification. The parser itself is tolerant and will not reject documents
+ * solely on character-class grounds, but these helpers are used to drive the
+ * tokeniser for correct name recognition.
+ */
+/** XML whitespace: space, tab, carriage-return, newline. */
+export function isXmlWhitespace(code) {
+	return code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d;
+}
+/**
+ * Valid XML NameStartChar (includes `:` so that QNames can be lexed as a
+ * single token and split on `:` afterwards).
+ *
+ * XML 1.0 §2.3 production [4]
+ */
+export function isNameStartChar(code) {
+	if (code < 0x41) return code === 0x3a || code === 0x5f; // : or _
+	if (code <= 0x5a) return true; // A-Z
+	if (code < 0x61) return false;
+	if (code <= 0x7a) return true; // a-z
+	if (code < 0xc0) return false;
+	if (code <= 0xd6) return true;
+	if (code < 0xd8) return false;
+	if (code <= 0xf6) return true;
+	if (code < 0xf8) return false;
+	if (code <= 0x2ff) return true;
+	if (code < 0x370) return false;
+	if (code <= 0x37d) return true;
+	if (code < 0x37f) return false;
+	if (code <= 0x1fff) return true;
+	if (code === 0x200c || code === 0x200d) return true;
+	if (code < 0x2070) return false;
+	if (code <= 0x218f) return true;
+	if (code < 0x2c00) return false;
+	if (code <= 0x2fef) return true;
+	if (code < 0x3001) return false;
+	if (code <= 0xd7ff) return true;
+	if (code < 0xf900) return false;
+	if (code <= 0xfdcf) return true;
+	if (code < 0xfdf0) return false;
+	if (code <= 0xfffd) return true;
+	if (code < 0x10000) return false;
+	return code <= 0xeffff;
+}
+/**
+ * Valid XML NameChar (superset of NameStartChar).
+ *
+ * XML 1.0 §2.3 production [4a]
+ */
+export function isNameChar(code) {
+	if (isNameStartChar(code)) return true;
+	if (code === 0x2d || code === 0x2e) return true; // - or .
+	if (code >= 0x30 && code <= 0x39) return true; // 0-9
+	if (code === 0xb7) return true;
+	if (code >= 0x0300 && code <= 0x036f) return true;
+	if (code >= 0x203f && code <= 0x2040) return true;
+	return false;
+}
+/** ASCII hex digit [0-9A-Fa-f]. */
+export function isHexDigit(code) {
+	return (code >= 0x30 && code <= 0x39) || (code >= 0x41 && code <= 0x46) || (code >= 0x61 && code <= 0x66);
+}
+/** ASCII decimal digit [0-9]. */
+export function isDecimalDigit(code) {
+	return code >= 0x30 && code <= 0x39;
+}
+//# sourceMappingURL=chars.js.map

package/dist/chars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chars.js","sourceRoot":"","sources":["../src/chars.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @pipobscure/xml
+ *
+ * A fully capable, forgiving XML parser that produces plain JS objects
+ * suitable for JSON serialisation and TypeScript consumption.
+ *
+ * Quick start
+ * ───────────
+ * ```ts
+ * import { parse } from '@pipobscure/xml';
+ *
+ * const doc = parse(`<?xml version="1.0"?>
+ *   <cal:calendar xmlns:cal="urn:ietf:params:xml:ns:caldav">
+ *     <cal:displayname>My Calendar</cal:displayname>
+ *   </cal:calendar>`);
+ *
+ * // doc.type === 'document'
+ * // doc.children[0].type === 'xml-declaration'
+ * // doc.children[1].type === 'element'
+ * ```
+ */
+export { parse, ParseError } from './parser.ts';
+export type { NodeType, Node, Attribute, XmlDeclaration, DocumentType, ProcessingInstruction, Comment, CData, Text, Element, Document, ChildNode, DocumentChild, AnyNode } from './types.ts';
+export { isDocument, isElement, isText, isCData, isComment, isProcessingInstruction, isDocumentType, isXmlDeclaration } from './types.ts';
+export { textContent, rootElement, child, requireChild, children, childElements, childElementCount, descendant, descendants, attr } from './query.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGhD,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,qBAAqB,EACrB,OAAO,EACP,KAAK,EACL,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,aAAa,EACb,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,WAAW,EACX,WAAW,EACX,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,IAAI,GACL,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * @pipobscure/xml
+ *
+ * A fully capable, forgiving XML parser that produces plain JS objects
+ * suitable for JSON serialisation and TypeScript consumption.
+ *
+ * Quick start
+ * ───────────
+ * ```ts
+ * import { parse } from '@pipobscure/xml';
+ *
+ * const doc = parse(`<?xml version="1.0"?>
+ *   <cal:calendar xmlns:cal="urn:ietf:params:xml:ns:caldav">
+ *     <cal:displayname>My Calendar</cal:displayname>
+ *   </cal:calendar>`);
+ *
+ * // doc.type === 'document'
+ * // doc.children[0].type === 'xml-declaration'
+ * // doc.children[1].type === 'element'
+ * ```
+ */
+// Parser function and error class
+export { parse, ParseError } from './parser.js';
+export { isDocument, isElement, isText, isCData, isComment, isProcessingInstruction, isDocumentType, isXmlDeclaration } from './types.js';
+// Tree-query helpers
+export { textContent, rootElement, child, requireChild, children, childElements, childElementCount, descendant, descendants, attr } from './query.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,kCAAkC;AAClC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAoBhD,OAAO,EACL,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,qBAAqB;AACrB,OAAO,EACL,WAAW,EACX,WAAW,EACX,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,IAAI,GACL,MAAM,YAAY,CAAC"}

package/dist/parser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @pipobscure/xml — Recursive-descent XML parser
+ *
+ * Design goals
+ * ─────────────
+ * • Correctness for well-formed XML (CalDAV, CardDAV, Atom, WebDAV …)
+ * • Tolerant / forgiving: recovers from many real-world XML quirks instead
+ *   of aborting with an error. The aim is to parse what servers actually send,
+ *   not only what the spec mandates.
+ * • Optimised for small documents (< ~1 MB) — no streaming, no SAX.
+ * • Pure TypeScript, zero dependencies, plain-object output (JSON-safe).
+ *
+ * Tolerance specifics
+ * ────────────────────
+ * • Unknown named entity references (e.g. `&nbsp;`) are left verbatim
+ *   (`&nbsp;`) rather than causing an error.
+ * • Undefined namespace prefixes resolve to `null` rather than throwing.
+ * • `--` inside comments is allowed (browsers are lenient here too).
+ * • Missing XML declaration is fine.
+ * • Attribute values may use either quote style.
+ * • DOCTYPE internal subsets are captured verbatim, not validated.
+ * • The BOM (U+FEFF) at the start of the stream is silently skipped.
+ */
+import type { Document } from './types.ts';
+/**
+ * Thrown when the input is so malformed that the parser cannot produce a
+ * meaningful tree. In practice the parser tries hard to recover, so only
+ * truly unrecoverable situations (e.g. no root element found) reach here.
+ */
+export declare class ParseError extends Error {
+	/** Byte offset in the source string where the problem was detected. */
+	readonly position: number;
+	/** 1-based line number. */
+	readonly line: number;
+	/** 1-based column number. */
+	readonly column: number;
+	constructor(message: string, position: number, line: number, column: number);
+}
+/**
+ * Parses an XML string into a `Document` tree of plain JS objects.
+ *
+ * The parser is deliberately forgiving:
+ * - Unknown entity references are preserved verbatim.
+ * - Undeclared namespace prefixes resolve to `null`.
+ * - Minor structural quirks (missing closing quotes, stray characters in
+ *   element tags, unterminated comments) are recovered from where possible.
+ *
+ * @throws {ParseError} Only for unrecoverable structural failures such as a
+ *   completely absent root element.
+ */
+export declare function parse(xml: string): Document;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,QAAQ,EAWT,MAAM,YAAY,CAAC;AA6BpB;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAO5E;AAytBD;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAE3C"}