saxes

  • Version 5.0.1
  • Published
  • 164 kB
  • 1 dependency
  • ISC license

Install

npm i saxes
yarn add saxes
pnpm add saxes

Overview

An evented streaming XML parser in JavaScript

Index

Variables

variable EVENTS

const EVENTS: readonly [
'xmldecl',
'text',
'processinginstruction',
'doctype',
'comment',
'opentagstart',
'attribute',
'opentag',
'closetag',
'cdata',
'error',
'end',
'ready'
];
  • The list of supported events.

Classes

class SaxesParser

class SaxesParser<O extends SaxesOptions = {}> {}

    constructor

    constructor(opt?: SaxesOptions);
    • Parameter opt

      The parser options.

    property closed

    readonly closed: boolean;
    • Indicates whether or not the parser is closed. If ``true``, wait for the ``ready`` event to write again.

    property column

    column: number;
    • The column number of the next character to be read by the parser. * This field is zero-based. (The first column is 0.)

      This field counts columns by *Unicode character*. Note that this *can* be different from the index of the character in a JavaScript string due to how JavaScript handles astral plane characters.

      See [[columnIndex]] for a number that corresponds to the JavaScript index.

    property columnIndex

    readonly columnIndex: number;
    • The column number of the next character to be read by the parser. * This field is zero-based. (The first column in a line is 0.)

      This field reports the index at which the next character would be in the line if the line were represented as a JavaScript string. Note that this *can* be different to a count based on the number of *Unicode characters* due to how JavaScript handles astral plane characters.

      See [[column]] for a number that corresponds to a count of Unicode characters.

    property ENTITIES

    ENTITIES: Record<string, string>;
    • A map of entity name to expansion.

    property line

    line: number;
    • The line number of the next character to be read by the parser. This field is one-based. (The first line is numbered 1.)

    property opt

    readonly opt: SaxesOptions;

      property position

      readonly position: number;
      • The stream position the parser is currently looking at. This field is zero-based.

        This field is not based on counting Unicode characters but is to be interpreted as a plain index into a JavaScript string.

      property xmlDecl

      xmlDecl: XMLDecl;
      • The XML declaration for this document.

      method close

      close: () => this;
      • Close the current stream. Perform final well-formedness checks and reset the parser tstate.

        Returns

        this

      method fail

      fail: (message: string) => this;
      • Report a parsing error. This method is made public so that client code may check for issues that are outside the scope of this project and can report errors.

        Parameter message

        The error to report.

        Returns

        this

      method makeError

      makeError: (message: string) => Error;
      • Make an error object. The error object will have a message that contains the ``fileName`` option passed at the creation of the parser. If position tracking was turned on, it will also have line and column number information.

        Parameter message

        The message describing the error to report.

        Returns

        An error object with a properly formatted message.

      method off

      off: (name: EventName) => void;
      • Unset an event handler.

        name The event to stop listening to.

      method on

      on: <
      N extends
      | 'xmldecl'
      | 'text'
      | 'processinginstruction'
      | 'doctype'
      | 'comment'
      | 'opentagstart'
      | 'attribute'
      | 'opentag'
      | 'closetag'
      | 'cdata'
      | 'error'
      | 'end'
      | 'ready'
      >(
      name: N,
      handler: EventNameToHandler<O, N>
      ) => void;
      • Set an event listener on an event. The parser supports one handler per event type. If you try to set an event handler over an existing handler, the old handler is silently overwritten.

        Parameter name

        The event to listen to.

        Parameter handler

        The handler to set.

      method resolve

      resolve: (prefix: string) => string | undefined;
      • Resolve a namespace prefix.

        Parameter prefix

        The prefix to resolve.

        Returns

        The namespace URI or ``undefined`` if the prefix is not defined.

      method write

      write: (chunk: string | {} | null) => this;
      • Write a XML data to the parser.

        Parameter chunk

        The XML data to write.

        Returns

        this

      Interfaces

      interface CommonOptions

      interface CommonOptions {}

        property fileName

        fileName?: string;
        • A file name to use for error reporting. "File name" is a loose concept. You could use a URL to some resource, or any descriptive name you like.

        property fragment

        fragment?: boolean;
        • Whether to accept XML fragments. Unset means ``false``.

        property position

        position?: boolean;
        • Whether to track positions. Unset means ``true``.

        interface ForcedXMLVersion

        interface ForcedXMLVersion extends XMLVersionOptions {}

          property defaultXMLVersion

          defaultXMLVersion: Exclude<XMLVersionOptions['defaultXMLVersion'], undefined>;

            property forceXMLVersion

            forceXMLVersion: true;

              interface NoForcedXMLVersion

              interface NoForcedXMLVersion extends XMLVersionOptions {}

                property forceXMLVersion

                forceXMLVersion?: false;

                  interface NSOptions

                  interface NSOptions {}

                    property additionalNamespaces

                    additionalNamespaces?: Record<string, string>;
                    • A plain object whose key, value pairs define namespaces known before parsing the XML file. It is not legal to pass bindings for the namespaces ``"xml"`` or ``"xmlns"``.

                    property resolvePrefix

                    resolvePrefix?: ResolvePrefix;
                    • A function that will be used if the parser cannot resolve a namespace prefix on its own.

                    property xmlns

                    xmlns?: boolean;
                    • Whether to track namespaces. Unset means ``false``.

                    interface NSOptionsWithNamespaces

                    interface NSOptionsWithNamespaces extends NSOptions {}

                      property xmlns

                      xmlns: true;

                        interface NSOptionsWithoutNamespaces

                        interface NSOptionsWithoutNamespaces extends NSOptions {}

                          property additionalNamespaces

                          additionalNamespaces?: undefined;

                            property resolvePrefix

                            resolvePrefix?: undefined;

                              property xmlns

                              xmlns?: false;

                                interface SaxesAttributeNS

                                interface SaxesAttributeNS {}
                                • This interface defines the structure of attributes when the parser is processing namespaces (created with ``xmlns: true``).

                                property local

                                local: string;
                                • The attribute's local name. For instance ``a:b="c"`` would have ``"b"`` for ``local``.

                                property name

                                name: string;
                                • The attribute's name. This is the combination of prefix and local name. For instance ``a:b="c"`` would have ``a:b`` for name.

                                property prefix

                                prefix: string;
                                • The attribute's prefix. For instance ``a:b="c"`` would have ``"a"`` for ``prefix``.

                                property uri

                                uri: string;
                                • The namespace URI of this attribute.

                                property value

                                value: string;
                                • The attribute's value.

                                interface SaxesAttributePlain

                                interface SaxesAttributePlain {}
                                • This interface defines the structure of attributes when the parser is NOT processing namespaces (created with ``xmlns: false``).

                                property name

                                name: string;
                                • The attribute's name.

                                property value

                                value: string;
                                • The attribute's value.

                                interface SaxesTag

                                interface SaxesTag {}
                                • This are the fields that MAY be present on a complete tag.

                                property attributes

                                attributes: Record<string, SaxesAttributeNS> | Record<string, string>;
                                • A map of attribute name to attributes. If namespaces are tracked, the values in the map are attribute objects. Otherwise, they are strings.

                                property isSelfClosing

                                isSelfClosing: boolean;
                                • Whether the tag is self-closing (e.g. ````).

                                property local

                                local?: string;
                                • The tag's local name. For instance ``<a:b>`` would have ``"b"`` for ``local``. Undefined if we do not track namespaces.

                                property name

                                name: string;
                                • The tag's name. This is the combination of prefix and global name. For instance ``<a:b>`` would have ``"a:b"`` for ``name``.

                                property ns

                                ns?: Record<string, string>;
                                • The namespace bindings in effect.

                                property prefix

                                prefix?: string;
                                • The tag's prefix. For instance ``<a:b>`` would have ``"a"`` for ``prefix``. Undefined if we do not track namespaces.

                                property uri

                                uri?: string;
                                • The namespace URI of this tag. Undefined if we do not track namespaces.

                                interface XMLDecl

                                interface XMLDecl {}
                                • An XML declaration.

                                property encoding

                                encoding?: string;
                                • The encoding specified by the XML declaration.

                                property standalone

                                standalone?: string;
                                • The value of the standalone parameter

                                property version

                                version?: string;
                                • The version specified by the XML declaration.

                                interface XMLVersionOptions

                                interface XMLVersionOptions {}

                                  property defaultXMLVersion

                                  defaultXMLVersion?: '1.0' | '1.1';
                                  • The default XML version to use. If unspecified, and there is no XML encoding declaration, the default version is "1.0".

                                  property forceXMLVersion

                                  forceXMLVersion?: boolean;
                                  • A flag indicating whether to force the XML version used for parsing to the value of ``defaultXMLVersion``. When this flag is ``true``, ``defaultXMLVersion`` must be specified. If unspecified, the default value of this flag is ``false``.

                                  Type Aliases

                                  type AttributeEventForOptions

                                  type AttributeEventForOptions<O extends SaxesOptions> = O extends {
                                  xmlns: true;
                                  }
                                  ? SaxesAttributeNSIncomplete
                                  : O extends {
                                  xmlns?: false | undefined;
                                  }
                                  ? SaxesAttributePlain
                                  : SaxesAttribute;

                                    type AttributeHandler

                                    type AttributeHandler<O> = (attribute: AttributeEventForOptions<O>) => void;
                                    • Event handler for attributes.

                                    type CDataHandler

                                    type CDataHandler = (cdata: string) => void;
                                    • Event handler for a CDATA section. This is called when ending the CDATA section.

                                      Parameter cdata

                                      The contents of the CDATA section.

                                    type CloseTagHandler

                                    type CloseTagHandler<O> = (tag: TagForOptions<O>) => void;
                                    • Event handler for a close tag. Note that for self-closing tags, this is called right after ``opentag``.

                                      Parameter tag

                                      The tag.

                                    type CommentHandler

                                    type CommentHandler = (comment: string) => void;
                                    • Event handler for comments.

                                      Parameter comment

                                      The comment contents.

                                    type DoctypeHandler

                                    type DoctypeHandler = (doctype: string) => void;
                                    • Event handler for doctype.

                                      Parameter doctype

                                      The doctype contents.

                                    type EndHandler

                                    type EndHandler = () => void;
                                    • Event handler for the stream end. This is called when the stream has been closed with ``close`` or by passing ``null`` to ``write``.

                                    type ErrorHandler

                                    type ErrorHandler = (err: Error) => void;
                                    • Event handler indicating an error.

                                      Parameter err

                                      The error that occurred.

                                    type EventName

                                    type EventName = typeof EVENTS[number];

                                      type EventNameToHandler

                                      type EventNameToHandler<O, N extends EventName> = {
                                      xmldecl: XMLDeclHandler;
                                      text: TextHandler;
                                      processinginstruction: PIHandler;
                                      doctype: DoctypeHandler;
                                      comment: CommentHandler;
                                      opentagstart: OpenTagStartHandler<O>;
                                      attribute: AttributeHandler<O>;
                                      opentag: OpenTagHandler<O>;
                                      closetag: CloseTagHandler<O>;
                                      cdata: CDataHandler;
                                      error: ErrorHandler;
                                      end: EndHandler;
                                      ready: ReadyHandler;
                                      }[N];

                                        type OpenTagHandler

                                        type OpenTagHandler<O> = (tag: TagForOptions<O>) => void;
                                        • Event handler for an open tag. This is called when the open tag is complete. (We've encountered the ">" that ends the open tag.)

                                          Parameter tag

                                          The tag.

                                        type OpenTagStartHandler

                                        type OpenTagStartHandler<O> = (tag: StartTagForOptions<O>) => void;
                                        • Event handler for the start of an open tag. This is called as soon as we have a tag name.

                                          Parameter tag

                                          The tag.

                                        type PIHandler

                                        type PIHandler = (data: { target: string; body: string }) => void;
                                        • Event handler for processing instructions.

                                          Parameter data

                                          The target and body of the processing instruction.

                                        type ReadyHandler

                                        type ReadyHandler = () => void;
                                        • Event handler indicating parser readiness . This is called when the parser is ready to parse a new document.

                                        type ResolvePrefix

                                        type ResolvePrefix = (prefix: string) => string | undefined;
                                        • A callback for resolving name prefixes.

                                          Parameter prefix

                                          The prefix to check.

                                          Returns

                                          The URI corresponding to the prefix, if any.

                                        type SaxesAttribute

                                        type SaxesAttribute = SaxesAttributeNS | SaxesAttributePlain;
                                        • A saxes attribute, with or without namespace information.

                                        type SaxesAttributeNSIncomplete

                                        type SaxesAttributeNSIncomplete = Exclude<SaxesAttributeNS, 'uri'>;
                                        • This is an attribute, as recorded by a parser which parses namespaces but prior to the URI being resolvable. This is what is passed to the attribute event handler.

                                        type SaxesOptions

                                        type SaxesOptions = CommonOptions & NSOptions & XMLVersionOptions;
                                        • The entire set of options supported by saxes.

                                        type SaxesStartTag

                                        type SaxesStartTag = Pick<SaxesTag, 'name' | 'attributes' | 'ns'>;
                                        • This type defines the fields that are present on a tag object when ``onopentagstart`` is called. This interface is namespace-agnostic.

                                        type SaxesStartTagNS

                                        type SaxesStartTagNS = Required<SaxesStartTag>;
                                        • This type defines the fields that are present on a tag object when ``onopentagstart`` is called on a parser that does process namespaces.

                                        type SaxesStartTagPlain

                                        type SaxesStartTagPlain = Pick<SaxesStartTag, 'name' | 'attributes'>;
                                        • This type defines the fields that are present on a tag object when ``onopentagstart`` is called on a parser that does not processes namespaces.

                                        type SaxesTagNS

                                        type SaxesTagNS = Required<SaxesTag> & {
                                        attributes: Record<string, SaxesAttributeNS>;
                                        };
                                        • This are the fields that are present on a complete tag produced by a parser that does process namespaces.

                                        type SaxesTagPlain

                                        type SaxesTagPlain = Pick<SaxesTag, 'name' | 'attributes' | 'isSelfClosing'> & {
                                        attributes: Record<string, string>;
                                        };
                                        • This are the fields that are present on a complete tag produced by a parser that does not process namespaces.

                                        type StartTagForOptions

                                        type StartTagForOptions<O extends SaxesOptions> = O extends {
                                        xmlns: true;
                                        }
                                        ? SaxesStartTagNS
                                        : O extends {
                                        xmlns?: false | undefined;
                                        }
                                        ? SaxesStartTagPlain
                                        : SaxesStartTag;

                                          type TagForOptions

                                          type TagForOptions<O extends SaxesOptions> = O extends {
                                          xmlns: true;
                                          }
                                          ? SaxesTagNS
                                          : O extends {
                                          xmlns?: false | undefined;
                                          }
                                          ? SaxesTagPlain
                                          : SaxesTag;

                                            type TextHandler

                                            type TextHandler = (text: string) => void;
                                            • Event handler for text data.

                                              Parameter text

                                              The text data encountered by the parser.

                                            type XMLDeclHandler

                                            type XMLDeclHandler = (decl: XMLDecl) => void;
                                            • Event handler for the

                                              Parameter text

                                              The text data encountered by the parser.

                                            Package Files (1)

                                            Dependencies (1)

                                            Dev Dependencies (31)

                                            Peer Dependencies (0)

                                            No peer dependencies.

                                            Badge

                                            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/saxes.

                                            • Markdown
                                              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/saxes)
                                            • HTML
                                              <a href="https://www.jsdocs.io/package/saxes"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>