From c2d97254a71972835eb6ee83aca851d471ef842c Mon Sep 17 00:00:00 2001 From: Dmitry Volyntsev Date: Wed, 1 Feb 2023 19:04:39 -0800 Subject: [PATCH] Types: added ts types for the xml API. --- test/ts/package.json | 2 +- test/ts/test.ts | 20 +++++ ts/index.d.ts | 1 + ts/njs_modules/xml.d.ts | 162 ++++++++++++++++++++++++++++++++++++++++ ts/package.json | 2 +- 5 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 ts/njs_modules/xml.d.ts diff --git a/test/ts/package.json b/test/ts/package.json index 3daeea81..f2093017 100644 --- a/test/ts/package.json +++ b/test/ts/package.json @@ -10,6 +10,6 @@ "license": "BSD-2-Clause", "devDependencies": { "njs-types": "file:../../ts", - "typescript": "~4.0.3" + "typescript": "~4.9.5" } } diff --git a/test/ts/test.ts b/test/ts/test.ts index 1780a218..cc339293 100644 --- a/test/ts/test.ts +++ b/test/ts/test.ts @@ -1,6 +1,7 @@ import fs from 'fs'; import qs from 'querystring'; import cr from 'crypto'; +import xml from 'xml'; async function http_module(r: NginxHTTPRequest) { var bs: NjsByteString; @@ -147,6 +148,25 @@ function qs_module(str: NjsByteString) { s = qs.stringify(o); } +function xml_module(str: NjsByteString) { + let doc; + let node; + let children, selectedChildren; + + doc = xml.parse(str); + node = doc.$root; + + node.$ns; + children = node.$tags; + selectedChildren = node.$tags$xxx; + + node?.xxx?.yyy?.$attr$zzz; + + let buf:Buffer = xml.exclusiveC14n(node); + buf = xml.exclusiveC14n(doc, node.xxx, false); + buf = xml.exclusiveC14n(node, null, true, "aa bb"); +} + function crypto_module(str: NjsByteString) { var h; var b:Buffer; diff --git a/ts/index.d.ts b/ts/index.d.ts index eec5c342..bacac1ea 100644 --- a/ts/index.d.ts +++ b/ts/index.d.ts @@ -2,4 +2,5 @@ /// /// /// +/// /// diff --git a/ts/njs_modules/xml.d.ts b/ts/njs_modules/xml.d.ts new file mode 100644 index 00000000..61c707ac --- /dev/null +++ b/ts/njs_modules/xml.d.ts @@ -0,0 +1,162 @@ +/// + +declare module "xml" { + + type XMLTagName = + | `_${string}` + | `a${string}` + | `b${string}` + | `c${string}` + | `d${string}` + | `e${string}` + | `f${string}` + | `g${string}` + | `h${string}` + | `i${string}` + | `j${string}` + | `k${string}` + | `l${string}` + | `m${string}` + | `n${string}` + | `o${string}` + | `p${string}` + | `q${string}` + | `r${string}` + | `s${string}` + | `t${string}` + | `u${string}` + | `v${string}` + | `w${string}` + | `x${string}` + | `y${string}` + | `z${string}` + | `A${string}` + | `B${string}` + | `C${string}` + | `D${string}` + | `E${string}` + | `F${string}` + | `G${string}` + | `H${string}` + | `I${string}` + | `J${string}` + | `K${string}` + | `L${string}` + | `M${string}` + | `N${string}` + | `O${string}` + | `P${string}` + | `Q${string}` + | `R${string}` + | `S${string}` + | `T${string}` + | `U${string}` + | `V${string}` + | `W${string}` + | `X${string}` + | `Y${string}` + | `Z${string}`; + + export interface XMLDoc { + /** + * The doc's root node. + */ + readonly $root: XMLNode; + + /** + * The doc's root by its name or undefined. + */ + readonly [rootTagName: XMLTagName]: XMLNode | undefined; + } + + export interface XMLNode { + /** + * node.$attr$xxx - the node's attribute value of "xxx". + */ + readonly [key: `$attr$${string}`]: string | undefined; + + /** + * node.$attrs - an XMLAttr wrapper object for all the attributes + * of the node. + */ + readonly $attrs: XMLAttr; + + /** + * node.$tag$xxx - the node's first child tag named "xxx". + */ + readonly [key: `$tag$${string}`]: XMLNode | undefined; + + /** + * node.$tags$xxx - all children tags named "xxx" of the node. + */ + readonly [key: `$tags$${string}`]: XMLNode[] | undefined; + + /** + * node.$name - the name of the node. + */ + readonly $name: string; + + /** + * node.$ns - the namespace of the node. + */ + readonly $ns: string; + + /** + * node.$parent - the parent node of the current node. + */ + readonly $parent: string; + + /** + * node.$text - the content of the node. + */ + readonly $text: string; + + /** + * node.$tags - all the node's children tags. + */ + readonly $tags: XMLNode[] | undefined; + + /** + * node.xxx is the same as node.$tag$xxx. + */ + readonly [key: XMLTagName]: XMLNode | undefined; + } + + export interface XMLAttr { + /** + * attr.xxx is the attribute value of "xxx". + */ + readonly [key: string]: string | undefined; + } + + interface Xml { + /** + * Parses src buffer for an XML document and returns a wrapper object. + * + * @param src a string or a buffer with an XML document. + * @return A XMLDoc wrapper object representing the parsed XML document. + */ + parse(src: NjsStringLike): XMLDoc; + + /** + * Canonicalizes root_node and its children according to + * https://www.w3.org/TR/xml-exc-c14n/. + * + * @param root - XMLDoc or XMLNode. + * @param excluding_node - allows to omit from the output a part of the + * document corresponding to the excluding_node and its children. + * @param withComments - a boolean (false by default). When withComments + * is true canonicalization corresponds to + * http://www.w3.org/2001/10/xml-exc-c14n#WithComments. + * @param prefix_list - an optional string with a space separated namespace + * prefixes for namespaces that should also be included into the output. + * @return Buffer object containing canonicalized output. + */ + exclusiveC14n(root: XMLDoc | XMLNode, excluding_node?: XMLNode | null | undefined, + withComments?: boolean, prefix_list?: string): Buffer; + } + + const xml: Xml; + + export default xml; +} diff --git a/ts/package.json b/ts/package.json index 2c8a8162..cafe0637 100644 --- a/ts/package.json +++ b/ts/package.json @@ -26,6 +26,6 @@ }, "homepage": "https://nginx.org/en/docs/njs/", "devDependencies": { - "typescript": "^4.0.3" + "typescript": "^4.9.5" } } -- 2.47.3