Added doc blocks and updated readme

Author: justinwilaby

.github/workflows/ci.yaml

@@ -43,7 +43,7 @@ jobs:
         run: npm install
 
       - name: Build and test
-        run: npm run build && npm run test
+        run: npm run build && npm run coverage
 
       - name: Cache Node.js modules
         uses: actions/cache@v2

ENCODING_SPEC.md

@@ -0,0 +1,46 @@
+# Custom Encoding Specification for FFI Boundary Crossing
+## Overview
+This document describes the custom encoding format used for serializing the Tag struct in Rust to a `Vec<u8>` for crossing FFI (Foreign Function Interface) boundaries. This encoding format ensures that the data can be efficiently transferred and reconstructed on the other side of the FFI boundary.
+
+## Tag Struct
+The Tag struct contains the following fields:
+
+- open_start: `[u32; 2]`
+- open_end: `[u32; 2]`
+- close_start: `[u32; 2]`
+- close_end: `[u32; 2]`
+- self_closing: `bool`
+- name: `Vec<u8>`
+- attributes: `Vec<Attribute>`
+- text_nodes: `Vec<Text>`
+### Encoding Format
+The encoding format is a binary representation of the Tag struct, with the following layout:
+
+1. ### Header (8 bytes):
+  - attributes_start: u32 (4 bytes) - The starting byte offset of the attributes section.
+  - text_nodes_start: u32 (4 bytes) - The starting byte offset of the text nodes section.
+
+2. ### Tag Data:
+  - open_start: `[u32; 2]` (8 bytes)
+  - open_end: `[u32; 2]` (8 bytes)
+  - close_start: `[u32; 2]` (8 bytes)
+  - close_end: `[u32; 2]` (8 bytes)
+  - self_closing: `u8` (1 byte)
+  - name_length: `u32` (4 bytes) - The length of the name field.
+  - name: `Vec<u8>` (variable length) - The UTF-8 encoded bytes of the tag name.
+
+3. ### Attributes Section:
+  - attributes_count: `u32` (4 bytes) - The number of attributes.
+  - For each attribute:
+      - attribute_length: `u32` (4 bytes) - The length of the encoded attribute.
+      - attribute_data: `Vec<u8>`(variable length) - The encoded attribute data.
+
+
+Text Nodes Section:
+
+text_nodes_count: u32 (4 bytes) - The number of text nodes.
+For each text node:
+text_length: u32 (4 bytes) - The length of the encoded text node.
+text_data: Vec<u8> (variable length) - The encoded text node data.
+Encoding Process
+The encoding process involves serializing each field of the Tag struct into a Vec<u8> in the specified order. The following Rust code demonstrates the encoding process:

lib/cjs/saxWasm.d.ts

@@ -1,52 +1,142 @@
-export declare class SaxEventType {
-    static Text: number;
-    static ProcessingInstruction: number;
-    static SGMLDeclaration: number;
-    static Doctype: number;
-    static Comment: number;
-    static OpenTagStart: number;
-    static Attribute: number;
-    static OpenTag: number;
-    static CloseTag: number;
-    static Cdata: number;
+/**
+ * An enum representing the events that can be
+ * subscribed to on the parser. Multiple events
+ * are subscribed to by using the bitwise or operator.
+ *
+ * @example
+ * ```ts
+ *  // Subscribe to both the Text and OpenTag events.
+ *  const parser = new SaxParser(SaxEventType.Text | SaxEventType.OpenTag);
+ * ```
+ * Event subscriptions can be updated between write operations.
+ *
+ * Note that minimizing the numnber of events will have a
+ * slight performance improvement which becomes more noticable
+ * on very large documents.
+ */
+export declare enum SaxEventType {
+    Text = 1,
+    ProcessingInstruction = 2,
+    SGMLDeclaration = 4,
+    Doctype = 8,
+    Comment = 16,
+    OpenTagStart = 32,
+    Attribute = 64,
+    OpenTag = 128,
+    CloseTag = 256,
+    Cdata = 512
 }
+/**
+ * Represents the detail of a SAX event.
+ */
 export type Detail = Position | Attribute | Text | Tag | ProcInst;
+/**
+ * Abstract class for reading SAX event data.
+ *
+ * @template T - The type of detail to be read.
+ */
 export declare abstract class Reader<T = Detail> {
     protected data: Uint8Array;
     protected cache: {
         [prop: string]: T;
     };
     protected ptr: number;
+    /**
+     * Creates a new Reader instance.
+     *
+     * @param data - The data to be read.
+     * @param ptr - The initial pointer position.
+     */
     constructor(data: Uint8Array, ptr?: number);
+    /**
+     * Converts the reader data to a JSON object.
+     *
+     * @returns A JSON object representing the reader data.
+     */
     abstract toJSON(): {
         [prop: string]: T;
     };
 }
+/**
+ * Class representing the line and character
+ * integers for entities that are encountered
+ * in the document.
+ */
 export declare class Position {
     line: number;
     character: number;
+    /**
+     * Creates a new Position instance.
+     *
+     * @param line - The line number.
+     * @param character - The character position.
+     */
     constructor(line: number, character: number);
 }
+/**
+ * Represents the different types of attributes.
+ */
 export declare enum AttributeType {
     Normal = 0,
     JSX = 1
 }
+/**
+ * Represents an attribute in the XML data.
+ */
 export declare class Attribute extends Reader<Text | AttributeType> {
     type: AttributeType;
     name: Text;
     value: Text;
+    /**
+     * Creates a new Attribute instance.
+     *
+     * @param buffer - The buffer containing the attribute data.
+     * @param ptr - The initial pointer position.
+     */
     constructor(buffer: Uint8Array, ptr?: number);
+    /**
+     * @inheritDoc
+     */
     toJSON(): {
         [prop: string]: Text | AttributeType;
     };
+    /**
+     * Converts the attribute to a string representation.
+     *
+     * @returns A string representing the attribute.
+     */
     toString(): string;
 }
+/**
+ * Represents a processing instruction in the XML data.
+ */
 export declare class ProcInst extends Reader<Position | Text> {
     target: Text;
     content: Text;
+    /**
+     * Creates a new ProcInst instance.
+     *
+     * @param buffer - The buffer containing the processing instruction data.
+     * @param ptr - The initial pointer position.
+     */
     constructor(buffer: Uint8Array, ptr?: number);
+    /**
+     * Gets the start position of the processing instruction.
+     *
+     * @returns The start position of the processing instruction.
+     */
     get start(): Position;
+    /**
+     * Gets the start position of the processing instruction.
+     *
+     * @returns The start position of the processing instruction.
+     */
     get end(): Position;
+    /**
+     * Converts the processing instruction to a JSON object.
+     *
+     * @returns A JSON object representing the processing instruction.
+     */
     toJSON(): {
         [p: string]: Position | Text;
     };
@@ -93,11 +183,155 @@ export declare class SAXParser {
     eventHandler?: (type: SaxEventType, detail: Detail) => void;
     private writeBuffer?;
     constructor(events?: number);
+    /**
+     * Parses the XML data from a readable stream.
+     *
+     * This function takes a readable stream of `Uint8Array` chunks and processes them using the SAX parser.
+     * It yields events and their details as they are parsed.
+     *
+     * # Arguments
+     *
+     * * `reader` - A readable stream reader for `Uint8Array` chunks.
+     *
+     * # Returns
+     *
+     * * An async generator yielding tuples of `SaxEventType` and `Detail`.
+     *
+     * # Examples
+     *
+     * ```ts
+     * // Node.js example
+     * import { createReadStream } from 'fs';
+     * import { resolve as pathResolve } from 'path';
+     * import { Readable } from 'stream';
+     * import { SAXParser, SaxEventType, Detail } from 'sax-wasm';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   const options = { encoding: 'utf8' };
+     *   const readable = createReadStream(pathResolve('path/to/your.xml'), options);
+     *   const webReadable = Readable.toWeb(readable);
+     *
+     *   for await (const [event, detail] of parser.parse(webReadable.getReader())) {
+     *     // Do something with these
+     *   }
+     * })();
+     *
+     * // Browser example
+     * import { SAXParser, SaxEventType, Detail } from 'sax-wasm';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   const response = await fetch('path/to/your.xml');
+     *   const reader = response.body.getReader();
+     *
+     *   for await (const [event, detail] of parser.parse(reader)) {
+     *     // Do something with these
+     *   }
+     * })();
+     * ```
+     */
     parse(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<[SaxEventType, Detail]>;
+    /**
+     * Writes a chunk of data to the parser.
+     *
+     * This function takes a `Uint8Array` chunk and processes it using the SAX parser.
+     *
+     * # Arguments
+     *
+     * * `chunk` - A `Uint8Array` chunk representing the data to be parsed.
+     *
+     * # Examples
+     *
+     * ```ts
+     * // Node.js example
+     * import { createReadStream } from 'node:fs';
+     * import { resolve as pathResolve } from 'node:path';
+     * import { Readable } from 'stream';
+     * import { SAXParser, SaxEventType } from 'sax-wasm';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   await parser.prepareWasm(fetch('path/to/your.wasm'));
+     *   const options = { encoding: 'utf8' };
+     *   const readable = createReadStream(pathResolve(__dirname + '/xml.xml'), options);
+     *   const webReadable = Readable.toWeb(readable);
+     *
+     *   for await (const chunk of webReadable.getReader()) {
+     *     parser.write(chunk);
+     *   }
+     *   parser.end();
+     * })();
+     *
+     * // Browser example
+     * import { SAXParser, SaxEventType } from 'sax-wasm';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   await parser.prepareWasm(fetch('path/to/your.wasm'));
+     *   const response = await fetch('path/to/your.xml');
+     *   const reader = response.body.getReader();
+     *
+     *   while (true) {
+     *     const { done, value } = await reader.read();
+     *     if (done) break;
+     *     parser.write(value);
+     *   }
+     *   parser.end();
+     * })();
+     * ```
+     */
     write(chunk: Uint8Array): void;
+    /**
+     * Ends the parsing process.
+     *
+     * This function signals the end of the parsing process and performs any necessary cleanup.
+     */
     end(): void;
+    /**
+     * Prepares the WebAssembly module for the SAX parser.
+     *
+     * This function takes a WebAssembly module source (either a `Response` or `Uint8Array`)
+     * and instantiates it for use with the SAX parser.
+     *
+     * # Arguments
+     *
+     * * `source` - A `Response`, `Promise<Response>`, or `Uint8Array` representing the WebAssembly module source.
+     *
+     * # Returns
+     *
+     * * A `Promise<boolean>` that resolves to `true` if the WebAssembly module was successfully instantiated.
+     *
+     * # Examples
+     *
+     * ```ts
+     * // Node.js example
+     * import { SAXParser, SaxEventType } from 'sax-wasm';
+     * import { readFileSync } from 'fs';
+     * import { resolve as pathResolve } from 'path';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   const wasmBuffer = readFileSync(pathResolve(__dirname + '/sax-wasm.wasm'));
+     *   const success = await parser.prepareWasm(wasmBuffer);
+     *   console.log('WASM prepared:', success);
+     * })();
+     *
+     * // Browser example
+     * import { SAXParser, SaxEventType } from 'sax-wasm';
+     *
+     * (async () => {
+     *   const parser = new SAXParser(SaxEventType.Text | SaxEventType.OpenTag);
+     *   const success = await parser.prepareWasm(fetch('path/to/your.wasm'));
+     *   console.log('WASM prepared:', success);
+     * })();
+     * ```
+     */
     prepareWasm(source: Response | Promise<Response>): Promise<boolean>;
     prepareWasm(saxWasm: Uint8Array): Promise<boolean>;
     eventTrap: (event: number, ptr: number, len: number) => void;
 }
+export declare const readString: (data: Uint8Array, offset: number, length: number) => string;
+export declare const readU32: (uint8Array: Uint8Array, ptr: number) => number;
+export declare const readPosition: (uint8Array: Uint8Array, ptr?: number) => Position;
 export {};