Merge pull request #145 from posthtml/3.1.0

.github/FUNDING.yml

@@ -9,4 +9,4 @@ community_bridge: # Replace with a single Community Bridge project-name e.g., cl
 liberapay: # Replace with a single Liberapay username
 issuehunt: # Replace with a single IssueHunt username
 otechie: # Replace with a single Otechie username
-custom: ['https://mailviews.com']
+custom: mailviews.com

.github/workflows/nodejs.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18, 20]
+        node-version: [18, 20, 22]
 
     steps:
       - uses: actions/checkout@v4

biome.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	}
+}

build.config.ts

@@ -0,0 +1,11 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  rollup: {
+    emitCJS: true,
+  },
+  rootDir: './lib',
+  outDir: '../dist',
+  entries: ['index.js'],
+  declaration: true,
+})

dist/index.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+const qs = require('query-string');
+const isUrl = require('is-url-superb');
+const matchHelper = require('posthtml-match-helper');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const qs__default = /*#__PURE__*/_interopDefaultCompat(qs);
+const isUrl__default = /*#__PURE__*/_interopDefaultCompat(isUrl);
+const matchHelper__default = /*#__PURE__*/_interopDefaultCompat(matchHelper);
+
+const plugin = (config = {}) => (tree) => {
+  config.strict = typeof config.strict === "boolean" ? config.strict : true;
+  const process = (node) => {
+    if (!config || !config.parameters) {
+      return node;
+    }
+    const tags = Array.isArray(config.tags) ? config.tags : ["a"];
+    const knownAttributes = new Set(config.attributes || ["href", "src", "poster", "srcset", "background"]);
+    tree.match(matchHelper__default(tags.join(",")), (node2) => {
+      if (!node2.attrs) {
+        return node2;
+      }
+      const matchingAttribute = Object.keys(node2.attrs).find((key) => knownAttributes.has(key));
+      if (!matchingAttribute) {
+        return node2;
+      }
+      const url = node2.attrs[matchingAttribute];
+      const parsed = qs__default.parseUrl(url, config.qs);
+      if (config.strict && !isUrl__default(parsed.url.trim())) {
+        return node2;
+      }
+      for (const item of Object.keys(config.parameters)) {
+        parsed.query[item] = config.parameters[item];
+      }
+      node2.attrs[matchingAttribute] = qs__default.stringifyUrl(parsed, config.qs);
+      return node2;
+    });
+    return node;
+  };
+  return new Promise((resolve) => {
+    tree.walk(process);
+    resolve(tree);
+  });
+};
+
+module.exports = plugin;

dist/index.d.cts

@@ -0,0 +1,135 @@
+import { StringifyOptions } from 'query-string';
+
+type URLParametersConfig = {
+  /**
+  Object containing parameter name (key) and its value.
+
+  @default undefined
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      }
+    })
+  ])
+    .process('<a href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  parameters: Record<string, string>;
+
+  /**
+  Array of tag names to process.
+
+  By default, only URLs inside known attributes of tags in this array will be processed.
+
+  @default ['a']
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      tags: ['a', 'img']
+    })
+  ])
+    .process(`
+      <a href="https://example.com">Test</a>
+      <img src="https://example.com/image.jpg">
+    `)
+    .then(result => result.html)
+  ```
+  */
+  tags?: string[];
+
+  /**
+  Array of attributes to process for the given tags.
+
+  You may override this with your own list of attributes - the plugin will only process URLs in _these_ attributes.
+
+  @default ['href', 'src', 'poster', 'srcset', 'background']
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      attributes: ['data-href']
+    })
+  ])
+    .process('<a href="foo.html" data-href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  attributes?: string[];
+
+  /**
+  By default, query parameters are appended only to valid URLs.
+
+  Disable strict mode to append parameters to any string.
+
+  @default true
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      strict: false
+    })
+  ])
+    .process('<a href="example.html">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  strict?: boolean;
+
+  /**
+  Options to pass to the `query-string` library.
+
+  @default undefined
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: '@Bar@'
+      },
+      qs: {
+        encode: false
+      }
+    })
+  ])
+    .process('<a href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  qs?: StringifyOptions;
+}
+
+export type { URLParametersConfig };

dist/index.d.mts

@@ -0,0 +1,135 @@
+import { StringifyOptions } from 'query-string';
+
+type URLParametersConfig = {
+  /**
+  Object containing parameter name (key) and its value.
+
+  @default undefined
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      }
+    })
+  ])
+    .process('<a href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  parameters: Record<string, string>;
+
+  /**
+  Array of tag names to process.
+
+  By default, only URLs inside known attributes of tags in this array will be processed.
+
+  @default ['a']
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      tags: ['a', 'img']
+    })
+  ])
+    .process(`
+      <a href="https://example.com">Test</a>
+      <img src="https://example.com/image.jpg">
+    `)
+    .then(result => result.html)
+  ```
+  */
+  tags?: string[];
+
+  /**
+  Array of attributes to process for the given tags.
+
+  You may override this with your own list of attributes - the plugin will only process URLs in _these_ attributes.
+
+  @default ['href', 'src', 'poster', 'srcset', 'background']
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      attributes: ['data-href']
+    })
+  ])
+    .process('<a href="foo.html" data-href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  attributes?: string[];
+
+  /**
+  By default, query parameters are appended only to valid URLs.
+
+  Disable strict mode to append parameters to any string.
+
+  @default true
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: 'bar'
+      },
+      strict: false
+    })
+  ])
+    .process('<a href="example.html">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  strict?: boolean;
+
+  /**
+  Options to pass to the `query-string` library.
+
+  @default undefined
+
+  @example
+  ```
+  import posthtml from 'posthtml'
+  import urlParams from 'posthtml-url-parameters'
+
+  posthtml([
+    urlParams({
+      parameters: {
+        foo: '@Bar@'
+      },
+      qs: {
+        encode: false
+      }
+    })
+  ])
+    .process('<a href="https://example.com">Test</a>')
+    .then(result => result.html)
+  ```
+  */
+  qs?: StringifyOptions;
+}
+
+export type { URLParametersConfig };