basant307/AI_Governance_Project

1// const { Expression } = require('path-expression-matcher');2 3//type Matcher = unknown;4type Expression = unknown;5 6/**7 * A lightweight, live read-only view of a Matcher instance.8 *9 * Returned by `Matcher.readOnly()`. The same instance is reused across every10 * callback invocation — no allocation overhead per call. Reads directly from11 * the parent Matcher's internal state so it always reflects the current parser12 * position with no copying or freezing.13 */14class MatcherView {15  readonly separator: string;16 17  /** Check if current path matches an Expression. */18  matches(expression: Expression): boolean;19 20  /** Get current tag name, or `undefined` if path is empty. */21  getCurrentTag(): string | undefined;22 23  /** Get current namespace, or `undefined` if not present. */24  getCurrentNamespace(): string | undefined;25 26  /** Get attribute value of the current node. */27  getAttrValue(attrName: string): any;28 29  /** Check if the current node has a given attribute. */30  hasAttr(attrName: string): boolean;31 32  /** Sibling position of the current node (child index in parent). */33  getPosition(): number;34 35  /** Occurrence counter of the current tag name at this level. */36  getCounter(): number;37 38  /** Number of nodes in the current path. */39  getDepth(): number;40 41  /** Current path as a string (e.g. `"root.users.user"`). */42  toString(separator?: string, includeNamespace?: boolean): string;43 44  /** Current path as an array of tag names. */45  toArray(): string[];46}47 48 49type XmlBuilderOptions = {50  /**51   * Give a prefix to the attribute name in the resulting JS object52   * 53   * Defaults to '@_'54   */55  attributeNamePrefix?: string;56 57  /**58   * A name to group all attributes of a tag under, or `false` to disable59   * 60   * Defaults to `false`61   */62  attributesGroupName?: false | string;63 64  /**65   * The name of the next node in the resulting JS66   * 67   * Defaults to `#text`68   */69  textNodeName?: string;70 71  /**72   * Whether to ignore attributes when building73   * 74   * When `true` - ignores all the attributes75   * 76   * When `false` - builds all the attributes77   * 78   * When `Array<string | RegExp>` - filters out attributes that match provided patterns79   * 80   * When `Function` - calls the function for each attribute and filters out those for which the function returned `true`81   * 82   * Defaults to `true`83   */84  ignoreAttributes?: boolean | (string | RegExp)[] | ((attrName: string, jPath: string) => boolean);85 86  /**87   * Give a property name to set CDATA values to instead of merging to tag's text value88   * 89   * Defaults to `false`90   */91  cdataPropName?: false | string;92 93  /**94   * If set, parse comments and set as this property95   * 96   * Defaults to `false`97   */98  commentPropName?: false | string;99 100  /**101   * Whether to make output pretty instead of single line102   * 103   * Defaults to `false`104   */105  format?: boolean;106 107 108  /**109   * If `format` is set to `true`, sets the indent string110   * 111   * Defaults to `  `112   */113  indentBy?: string;114 115  /**116   * Give a name to a top-level array117   * 118   * Defaults to `undefined`119   */120  arrayNodeName?: string;121 122  /**123   * Create empty tags for tags with no text value124   * 125   * Defaults to `false`126   */127  suppressEmptyNode?: boolean;128 129  /**130   * Suppress an unpaired tag131   * 132   * Defaults to `true`133   */134  suppressUnpairedNode?: boolean;135 136  /**137   * Don't put a value for boolean attributes138   * 139   * Defaults to `true`140   */141  suppressBooleanAttributes?: boolean;142 143  /**144   * Preserve the order of tags in resulting JS object145   * 146   * Defaults to `false`147   */148  preserveOrder?: boolean;149 150  /**151   * List of tags without closing tags152   * 153   * Defaults to `[]`154   */155  unpairedTags?: string[];156 157  /**158   * Nodes to stop parsing at159   * 160   * Accepts string patterns or Expression objects from path-expression-matcher161   * 162   * String patterns starting with "*." are automatically converted to ".." for backward compatibility163   * 164   * Defaults to `[]`165   */166  stopNodes?: (string | Expression)[];167 168  /**169   * Control how tag value should be parsed. Called only if tag value is not empty170   * 171   * @returns {undefined|null} `undefined` or `null` to set original value.172   * @returns {unknown} 173   * 174   * 1. Different value or value with different data type to set new value.175   * 2. Same value to set parsed value if `parseTagValue: true`.176   * 177   * Defaults to `(tagName, val, jPath, hasAttributes, isLeafNode) => val`178   */179  tagValueProcessor?: (name: string, value: unknown) => unknown;180 181  /**182   * Control how attribute value should be parsed183   * 184   * @param attrName 185   * @param attrValue 186   * @param jPath 187   * @returns {undefined|null} `undefined` or `null` to set original value188   * @returns {unknown}189   * 190   * Defaults to `(attrName, val, jPath) => val`191   */192  attributeValueProcessor?: (name: string, value: unknown) => unknown;193 194  /**195   * Whether to process default and DOCTYPE entities196   * 197   * Defaults to `true`198   */199  processEntities?: boolean;200 201 202  oneListGroup?: boolean;203 204  /**205   * Maximum number of nested tags206   * 207   * Defaults to `100`208   */209  maxNestedTags?: number;210 211  /**212   * Validate or sanitize tag and attribute names before they are written to XML output.213   *214   * The context object provides:215   * - `isAttribute` — `true` when the name being resolved is an attribute name,216   *   `false` when it is a tag name.217   * - `matcher` — the current path matcher (readonly). Can be used to inspect the218   *   current element path, e.g. via `.toString()` or `.getDepth()`.219   *220   * Return the (possibly transformed) name to use in the output.221   * Throw an error inside the function to reject an invalid name entirely.222   *223   * When set to `false` (default) all names are written as-is, preserving224   * backward-compatible behaviour.225   *226   * @example227   * // Auto-fix invalid names using xml-naming228   * import { sanitize } from 'xml-naming';229   * { sanitizeName: (name) => sanitize(name, 'qName') }230   *231   * @example232   * // Reject invalid names233   * import { qName } from 'xml-naming';234   * { sanitizeName: (name) => { if (!qName(name)) throw new Error(`Invalid XML name: "${name}"`); return name; } }235   *236   * Defaults to `false`237   */238  sanitizeName?: false | ((name: string, context: SanitizeNameContext) => string);239};240 241/**242 * Context object passed as the second argument to {@link XmlBuilderOptions.sanitizeName}.243 */244type SanitizeNameContext = {245  /**246   * `true` when the name being resolved is an XML attribute name;247   * `false` when it is an XML element (tag) name.248   */249  isAttribute: boolean;250 251  /**252   * The current path matcher at the point where the name is being resolved.253   * Readonly from the callback's perspective — do not call mutating methods.254   * Use `.toString()` to get the current jPath string, `.getDepth()` for nesting depth.255   */256  matcher: MatcherView;257};258 259interface XMLBuilder {260  build(jObj: any): string;261}262 263interface XMLBuilderConstructor {264  new(options?: XmlBuilderOptions): XMLBuilder;265  (options?: XmlBuilderOptions): XMLBuilder;266}267 268declare const Builder: XMLBuilderConstructor;269 270export = Builder;