Migration guide

Upgrading to v6

Configuration changes

The format for specifying attribute metadata has changed. This will probably not affect most users but if you have custom element metadata (e.g. elements.json) and specify attribute restrictions you should migrate to the new format.

If you do not use custom element metadata you can safely upgrade to this version without any changes.

If you need to maintain backwards compatibility with older versions of html-validate you can safely hold of the migration (e.g. you publish a component framework with bundled element metadata and don't want to force an update for end users). The old format is deprecated but will continue to be supported for now.

Previously the attributes was specified as an array of possible values (strings or regular expressions). Boolean attributes was specified as [] and when value could be omitted it used the magic value [""].

{
  "my-custom-input": {
    "attributes": {
      /* enumeration: must have one of the specified values */
      "type": ["text", "email", "tel"],

      /* boolean: should not have a value */
      "disabled": [],

      /* allow omitting value, e.g. it can be set as a boolean or it should be "true" or "false" */
      "multiline": ["", "true", "false"]
    }
  }
}

To migrate the array is changed to an object with the properties enum, boolean and omit:

 {
   "my-custom-input": {
     "attributes": {
       /* enumeration: must have one of the specified values */
-      "type": ["text", "email", "tel"],
+      "type": {
+        "enum": ["text", "email", "tel"]
+      },

       /* boolean: should not have a value */
-      "disabled": [],
+      "disabled": {
+        "boolean": true
+      },

       /* allow omitting value, e.g. it can be set as a boolean or it should be "true" or "false" */
-      "multiline": ["", "true", "false"]
+      "multiline": {
+        "omit": true,
+        "enum": ["true", "false"] // the value "" is no longer specified in the enumeration
+      }
     }
   }
 }

The properties requiredAttributes and deprecatedAttributes have been integrated into the same object:

 {
   "my-custom-input": {
-    "requiredAttributes": ["type"],
-    "deprecatedAttributes": ["autocorrect"]
+    "attributes": {
+      "type": {
+        "required": true
+      },
+      "autocorrect": {
+        "deprecated": true
+      }
+    }
   }
 }

It is perfectly valid to specify attributes as an empty object which is used to signal that an attribute is exists. When #68 (validate know attributes) is implemented it will be required to list all known attributes but for now no validation will happen without any properties set.

{
  "my-custom-input": {
    "attributes": {
      /* signal that the "foobar" attribute exists but no validation will occur */
      "foobar": {}
    }
  }
}

API changes

If you use MetaElement to query attribute metadata you must use the new object. Typically this should only be if you have a custom rule dealing with attributes. While the old format is supported in userland internally it is converted to the new format.

For instance, given a rule such as:

function myCustomRule(node: DOMNode, attr: Attribute, rule: string[]): void {
  /* ... */
}

const meta = node.meta.attributes;
for (const attr of node.attributes) {
  if (meta[attr.key]) {
    myCustomRule(node, attr, meta[attr.key]);
  }
}

The signature of the function must be changed to:

-function myCustomRule(node: DOMNode, attr: Attribute, rule: string[]): void {
+function myCustomRule(node: DOMNode, attr: Attribute, rule: MetaAttribute): void {
   /* ... */
}

If you want backwards compatibility you must handle both string[] and MetaAttribute, Array.isArray can be used to distinguish between the two:

function myCustomRule(node: DOMNode, attr: Attribute, rule: string[] | MetaAttribute): void {
  if (Array.isArray(rule)) {
    /* legacy code path */
  } else {
    /* modern code path */
  }
}

If the rule used logic to determine if the attribute is boolean it must be changed to use the boolean property:

-const isBoolean = rule.length === 0;
+const isBoolean = rule.boolean;

If the rule used logic to determine if the attribute value can be omitted it must be changed to use the omitted property:

-const canOmit = rule.includes("");
+const canOmit = rule.omit;

The list of allowed values are must be read from the enum property but rules must take care to ensure they work even if enum is not set (undefined):

-const valid = rule.includes(attr.value);
+const valid = !rule.enum || rule.enum.includes(attr.value);

If you used requiredAttributes or deprecatedAttributes these have now been integrated into the same object:

-const isDeprecated = meta.deprecatedAttributes.includes(attr.key);
+const isDeprecated = meta.attribute[attr.key]?.deprecated;

ConfigReadyEvent

Only affects API users.

If you have a rule or plugin listening to the ConfigReadyEvent event the datatype of the config property has changed from ConfigData to ResolvedConfig. For most part it contains the same information but is normalized, for instance rules are now always passed as Record<RuleID, [Severity, Options]>. Configured transformers, plugins etc are resolved instances and fields suchs as root and extends will never be present.

StaticConfigLoader

Only affects API users.

The default configuration loader has changed from FileSystemConfigLoader to StaticConfigLoader, i.e. the directory traversal looking for .htmlvalidate.json configuration files must now be explicitly enabled.

This will reduce the dependency on the NodeJS fs module and make it easier to use the library in browsers.

To restore the previous behaviour you must now enable FileSystemConfigLoader:

 import { HtmlValidate, FileSystemConfigLoader } from "html-validate";

-const htmlvalidate = new HtmlValidate();
+const loader = new FileSystemConfigLoader();
+const htmlvalidate = new HtmlValidate(loader);

If you pass configuration to the constructor you now pass it to the loader instead:

 import { HtmlValidate, FileSystemConfigLoader } from "html-validate";

-const htmlvalidate = new HtmlValidate({ ... });
+const loader = new FileSystemConfigLoader({ ... });
+const htmlvalidate = new HtmlValidate(loader);

If you use the root property as a workaround for the directory traversal you can now drop the workaround and rely on StaticConfigLoader:

 import { HtmlValidate } from "html-validate";

-const htmlvalidate = new HtmlValidate({
-  root: true,
-});
+const htmlvalidate = new HtmlValidate();

The CLI class is not affected as it will enable FileSystemConfigLoader automatically, so the following code will continue to work as expected:

const cli = new CLI();
const htmlvalidate = cli.getValidator();