fontoxpath - npm Package Compare versions

Comparing version 3.13.6 to 3.14.0

dist/fontoxpath.d.ts

@@ -0,1 +1,2 @@
+/// <reference lib="dom" />
 
@@ -5,3 +6,3 @@ /**
  */
-export declare type Attr = Node & {
+declare type Attr_2 = Node_2 & {
     localName: string;
@@ -14,2 +15,3 @@ name: string;
 };
+export { Attr_2 as Attr }
 
@@ -19,3 +21,4 @@ /**
  */
-export declare type CDATASection = CharacterData;
+declare type CDATASection_2 = CharacterData_2;
+export { CDATASection_2 as CDATASection }
 
@@ -25,5 +28,6 @@ /**
  */
-export declare type CharacterData = Node & {
+declare type CharacterData_2 = Node_2 & {
     data: string;
 };
+export { CharacterData_2 as CharacterData }
 
@@ -33,3 +37,4 @@ /**
  */
-export declare type Comment = CharacterData;
+declare type Comment_2 = CharacterData_2;
+export { Comment_2 as Comment }
 
@@ -57,13 +62,14 @@ /**
  */
-export declare type Document = Node & {
+declare type Document_2 = Node_2 & {
     implementation: {
-        createDocument(namespaceURI: null, qualifiedNameStr: null, documentType: null): Document;
+        createDocument(namespaceURI: null, qualifiedNameStr: null, documentType: null): Document_2;
     };
-    createAttributeNS(namespaceURI: string, name: string): Attr;
-    createCDATASection(contents: string): CDATASection;
-    createComment(data: string): Comment;
-    createElementNS(namespaceURI: string, qualifiedName: string): Element;
-    createProcessingInstruction(target: string, data: string): ProcessingInstruction;
-    createTextNode(data: string): Text;
+    createAttributeNS(namespaceURI: string, name: string): Attr_2;
+    createCDATASection(contents: string): CDATASection_2;
+    createComment(data: string): Comment_2;
+    createElementNS(namespaceURI: string, qualifiedName: string): Element_2;
+    createProcessingInstruction(target: string, data: string): ProcessingInstruction_2;
+    createTextNode(data: string): Text_2;
 };
+export { Document_2 as Document }
 
@@ -78,3 +84,3 @@ /**
  */
-export declare type Element = Node & {
+declare type Element_2 = Node_2 & {
     localName: string;
@@ -85,2 +91,3 @@ namespaceURI: string | null;
 };
+export { Element_2 as Element }
 
@@ -121,3 +128,3 @@ /**
  */
-export declare function evaluateUpdatingExpressionSync<TNode extends Node, TReturnType extends keyof IReturnTypes<TNode>>(updateScript: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
+export declare function evaluateUpdatingExpressionSync<TNode extends Node_2, TReturnType extends keyof IReturnTypes<TNode>>(updateScript: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
     [s: string]: any;
@@ -154,3 +161,3 @@ } | null, options?: UpdatingOptions | null): {
      */
-    <TNode extends Node, TReturnType extends keyof IReturnTypes<TNode>>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
+    <TNode extends Node_2, TReturnType extends keyof IReturnTypes<TNode>>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
         [s: string]: any;
@@ -193,3 +200,2 @@ } | null, returnType?: TReturnType, options?: Options | null): IReturnTypes<TNode>[TReturnType];
     /**
-
      * Resolve to an array of numbers
@@ -290,3 +296,3 @@ */
  */
-export declare function evaluateXPathToFirstNode<T extends Node>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
+export declare function evaluateXPathToFirstNode<T extends Node_2>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
     [s: string]: any;
@@ -333,3 +339,3 @@ } | null, options?: Options | null): T | null;
  */
-export declare function evaluateXPathToNodes<T extends Node>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
+export declare function evaluateXPathToNodes<T extends Node_2>(selector: string, contextItem?: any | null, domFacade?: IDomFacade | null, variables?: {
     [s: string]: any;
@@ -433,3 +439,3 @@ } | null, options?: Options | null): T[];
  */
-export declare function getBucketsForNode(node: Node): string[];
+export declare function getBucketsForNode(node: Node_2): string[];
 
@@ -440,7 +446,7 @@ /**
 export declare interface IDocumentWriter {
-    insertBefore(parent: Element | Document, newNode: Node, referenceNode: Node | null): void;
-    removeAttributeNS(node: Element, namespace: string, name: string): void;
-    removeChild(parent: Element | Document, child: Node): void;
-    setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
-    setData(node: Node, data: string): void;
+    insertBefore(parent: Element_2 | Document_2, newNode: Node_2, referenceNode: Node_2 | null): void;
+    removeAttributeNS(node: Element_2, namespace: string, name: string): void;
+    removeChild(parent: Element_2 | Document_2, child: Node_2): void;
+    setAttributeNS(node: Element_2, namespace: string, name: string, value: string): void;
+    setData(node: Node_2, data: string): void;
 }
@@ -461,3 +467,3 @@
      */
-    getAllAttributes(node: Element, bucket?: string | null): Attr[];
+    getAllAttributes(node: Element_2, bucket?: string | null): Attr_2[];
     /**
@@ -469,3 +475,3 @@ * Get the value of specified attribute of this element.
      */
-    getAttribute(node: Element, attributeName: string): string | null;
+    getAttribute(node: Element_2, attributeName: string): string | null;
     /**
@@ -478,3 +484,3 @@ * Get all child nodes of this element.
      */
-    getChildNodes(node: Node, bucket?: string | null): Node[];
+    getChildNodes(node: Node_2, bucket?: string | null): Node_2[];
     /**
@@ -485,3 +491,3 @@ * Get the data of this element.
      */
-    getData(node: Attr | CharacterData): string;
+    getData(node: Attr_2 | CharacterData_2): string;
     /**
@@ -494,3 +500,3 @@ * Get the first child of this element.
      */
-    getFirstChild(node: Node, bucket?: string | null): Node | null;
+    getFirstChild(node: Node_2, bucket?: string | null): Node_2 | null;
     /**
@@ -503,3 +509,3 @@ * Get the last child of this element.
      */
-    getLastChild(node: Node, bucket?: string | null): Node | null;
+    getLastChild(node: Node_2, bucket?: string | null): Node_2 | null;
     /**
@@ -512,3 +518,3 @@ * Get the next sibling of this node
      */
-    getNextSibling(node: Node, bucket?: string | null): Node | null;
+    getNextSibling(node: Node_2, bucket?: string | null): Node_2 | null;
     /**
@@ -521,3 +527,3 @@ * Get the parent of this element.
      */
-    getParentNode(node: Node, bucket?: string | null): Node | null;
+    getParentNode(node: Node_2, bucket?: string | null): Node_2 | null;
     /**
@@ -530,3 +536,3 @@ * Get the previous sibling of this element.
      */
-    getPreviousSibling(node: Node, bucket?: string | null): Node | null;
+    getPreviousSibling(node: Node_2, bucket?: string | null): Node_2 | null;
 }
@@ -541,3 +547,3 @@
 export declare interface INodesFactory extends ISimpleNodesFactory {
-    createDocument(): Document;
+    createDocument(): Document_2;
 }
@@ -548,3 +554,3 @@
  */
-export declare interface IReturnTypes<T extends Node> {
+export declare interface IReturnTypes<T extends Node_2> {
     [ReturnType_2.ANY]: any;
@@ -572,11 +578,13 @@ [ReturnType_2.NUMBER]: number;
 export declare interface ISimpleNodesFactory {
-    createAttributeNS(namespaceURI: string, name: string): Attr;
-    createCDATASection(contents: string): CDATASection;
-    createComment(contents: string): Comment;
-    createElementNS(namespaceURI: string, name: string): Element;
-    createProcessingInstruction(target: string, data: string): ProcessingInstruction;
-    createTextNode(contents: string): Text;
+    createAttributeNS(namespaceURI: string, name: string): Attr_2;
+    createCDATASection(contents: string): CDATASection_2;
+    createComment(contents: string): Comment_2;
+    createElementNS(namespaceURI: string, name: string): Element_2;
+    createProcessingInstruction(target: string, data: string): ProcessingInstruction_2;
+    createTextNode(contents: string): Text_2;
 }
 
 /**
+ * Specifies which language to use.
+ *
  * @public
@@ -600,5 +608,6 @@ */
  */
-export declare type Node = {
+declare type Node_2 = {
     nodeType: number;
 };
+export { Node_2 as Node }
 
@@ -660,3 +669,3 @@ /**
  */
-export declare function parseScript<TElement extends Element>(script: string, options: Options, simpleNodesFactory: ISimpleNodesFactory, documentWriter?: IDocumentWriter): TElement;
+export declare function parseScript<TElement extends Element_2>(script: string, options: Options, simpleNodesFactory: ISimpleNodesFactory, documentWriter?: IDocumentWriter): TElement;
 
@@ -679,8 +688,82 @@ /**
  */
-export declare type ProcessingInstruction = CharacterData & {
+declare type ProcessingInstruction_2 = CharacterData_2 & {
     nodeName: string;
     target: string;
 };
+export { ProcessingInstruction_2 as ProcessingInstruction }
 
 /**
+ * Offers tooling to profile how much time is being spent running XPaths.
+ *
+ * Note that Javascript custom functions are also included in the profile. If they call new XPaths
+ * themselves, they may overlap in measurement.
+ *
+ * For example, the xpath `app:custom-function("a", "b")` calls a new XPath, the total time taken for
+ * that outer XPath will include the time taken for the inner one as well.
+ *
+ * @example
+ * import \{ evaluateXPathToNodes, profiler \} from 'fontoxpath';
+ * // For browsers:
+ * profiler.setPerformanceImplementation(window.performance)
+ * // For NodeJS:
+ * profiler.setPerformanceImplementation(global.performance)
+ *
+ * profiler.startProfiling();
+ * // Do loads of XPaths
+ * profiler.stopProfiling();
+ *
+ * const performanceSummary = profiler.getPerformanceSummary();
+ *
+ * // Do whatever with this profiler result
+ * console.log(`The most expensive XPath was ${performanceSummary[0].xpath}`);
+ *
+ * @public
+ */
+export declare type Profiler = {
+    /**
+     * Get the performance metrics of executed XPaths between the {@link Profiler.startProfiling}
+     * and {@link Profiler.stopProfiling} calls.
+     *
+     * @returns Returns an array of {@link XPathPerformanceMeasurement} items which can be
+     * coverted into a csv to paste in your favorite spreadsheet editor. Results are ordered by their total duration.
+     *
+     * @example
+     * const summary = profiler.getPerformanceSummary();
+     * const csv = summary.map(item =\>
+     *     `${item.xpath},${item.times},${item.average},${item.totalDuration}`);
+     * await navigator.clipboard.writeText(csv);
+     *
+     * @public
+     *
+     */
+    getPerformanceSummary(): XPathPerformanceMeasurement[];
+    /**
+     * Set the impormentation of the Performance API object. this should implement the Performance interface.
+     *
+     * This is usually either window.performance (in the Browser) or global.performance (for NodeJS)
+     *
+     * @public
+     */
+    setPerformanceImplementation(performance: Performance): void;
+    /**
+     * Start profiling XPaths. All marks are cleared. Use {@link Profiler.stopProfiling} to stop it again.
+     *
+     * @public
+     */
+    startProfiling(): void;
+    /**
+     * Stop profiling XPaths, use the {@link Profiler.getPerformanceSummary} function to get hold of the
+     * summarized results.
+     *
+     * @public
+     */
+    stopProfiling(): void;
+};
+
+/**
+ * @public
+ */
+export declare const profiler: Profiler;
+
+/**
  * Add a custom test for use in xpath-serialized expressions.
@@ -735,3 +818,4 @@ *
  */
-export declare type Text = CharacterData;
+declare type Text_2 = CharacterData_2;
+export { Text_2 as Text }
 
@@ -754,2 +838,15 @@ /**
 
+/**
+ * Describes the performance of a single XPath across multiple evaluations.
+ *
+ * See {@link profiler}.
+ * @public
+ */
+export declare type XPathPerformanceMeasurement = {
+    average: number;
+    times: number;
+    totalDuration: number;
+    xpath: string;
+};
+
 export { }

package.json

 {
 	"name": "fontoxpath",
-	"version": "3.13.6",
+	"version": "3.14.0",
 	"description": "A minimalistic XPath 3.1 engine in JavaScript",
@@ -64,3 +64,3 @@ "main": "dist/fontoxpath.js",
 	"devDependencies": {
-		"@fontoxml/fonto-benchmark-runner": "0.0.4",
+		"@fontoxml/fonto-benchmark-runner": "0.1.0",
 		"@microsoft/api-extractor": "^7.8.0",
@@ -67,0 +67,0 @@ "@tscc/tscc": "^0.4.8",

README.md

@@ -1,2 +0,2 @@
-# fontoxpath [![Build Status](https://travis-ci.org/FontoXML/fontoxpath.svg?branch=master)](https://travis-ci.org/FontoXML/fontoxpath) [![devDependency Status](https://david-dm.org/FontoXML/fontoxpath/dev-status.svg)](https://david-dm.org/FontoXML/fontoxpath#info=devDependencies) [![NPM version](https://badge.fury.io/js/fontoxpath.svg)](http://badge.fury.io/js/fontoxpath) [![install size](https://packagephobia.now.sh/badge?p=fontoxpath)](https://packagephobia.now.sh/result?p=fontoxpath) [![Coverage Status](https://coveralls.io/repos/github/FontoXML/fontoxpath/badge.svg?branch=master)](https://coveralls.io/github/FontoXML/fontoxpath?branch=master) [![Known Vulnerabilities](https://snyk.io/test/github/FontoXML/fontoxpath/badge.svg?targetFile=package.json)](https://snyk.io/test/github/FontoXML/fontoxpath?targetFile=package.json) [![CodeFactor](https://www.codefactor.io/repository/github/fontoxml/fontoxpath/badge)](https://www.codefactor.io/repository/github/fontoxml/fontoxpath)
+# fontoxpath [![Build Status](https://travis-ci.org/FontoXML/fontoxpath.svg?branch=master)](https://travis-ci.org/FontoXML/fontoxpath) [![devDependency Status](https://david-dm.org/FontoXML/fontoxpath/dev-status.svg)](https://david-dm.org/FontoXML/fontoxpath#info=devDependencies) [![NPM version](https://badge.fury.io/js/fontoxpath.svg)](http://badge.fury.io/js/fontoxpath) [![bundle size](https://badgen.net/bundlephobia/minzip/fontoxpath)](https://bundlephobia.com/result?p=fontoxpath) [![Coverage Status](https://coveralls.io/repos/github/FontoXML/fontoxpath/badge.svg?branch=master)](https://coveralls.io/github/FontoXML/fontoxpath?branch=master) [![Known Vulnerabilities](https://snyk.io/test/github/FontoXML/fontoxpath/badge.svg?targetFile=package.json)](https://snyk.io/test/github/FontoXML/fontoxpath?targetFile=package.json) [![CodeFactor](https://www.codefactor.io/repository/github/fontoxml/fontoxpath/badge)](https://www.codefactor.io/repository/github/fontoxml/fontoxpath)
 
@@ -137,2 +137,28 @@ A minimalistic [XPath 3.1](https://www.w3.org/TR/xpath-31/) and [XQuery
 
+### Performance
+
+FontoXPath can use the Performance API to provide some insight in the speed of XPaths. To use it,
+first give FontoXPath an implementation of the Performance interface:
+
+```js
+import {profiler} from "fontoxpath";
+
+profiler.setPerformanceImplementation(window.performance); // or global.performance or self.performance, depending on you surroundings
+
+// And start profiling all XPath / XQuery usage
+
+profiler.startProfiling();
+```
+
+At some point, you may want to get a summary of all evaluated XPaths:
+
+```js
+const summary = profiler.getPerformanceSummary();
+```
+
+This summary contains an array of XPaths, their execution times, their total runtime and their
+average runtime. Starting a performance profile will also output measurements on the timeline of the
+performance profiler of the browser.
+
+
 ### Modifying XML
@@ -187,2 +213,30 @@
 
+An example of using XQUF with XQuery modules:
+
+```js
+registerXQueryModule(`
+module namespace my-custom-namespace = "my-custom-uri";
+(:~
+	Insert attribute somewhere
+	~:)
+declare %public %updating function my-custom-namespace:do-something ($ele as element()) as xs:boolean {
+	if ($ele/@done) then false() else
+	(insert node
+	attribute done {"true"}
+	into $ele, true())
+};
+`)
+// At some point:
+const contextNode = null;
+const pendingUpdatesAndXdmValue = evaluateUpdatingExpressionSync('ns:do-something(.)', contextNode, null, null, {moduleImports: {'ns': 'my-custom-uri'}})
+
+console.log(pendingUpdatesAndXdmValue.xdmValue); // this is true or false, see function
+
+executePendingUpdateList(pendingUpdatesAndXdmValue.pendingUpdateList, null, null, null);
+
+// At this point the context node will have its attribute set
+
+```
+
+
 ### Global functions
@@ -189,0 +243,0 @@

New alerts

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

825222

increased by1.7%

Lines of code

4116

increased by3.57%

Number of lines in readme file

366

increased by17.31%

No dependency changes