Merge pull request #110 from posthtml/feat/esm

.eslintrc

@@ -0,0 +1,23 @@
+{
+  "parserOptions": {
+    "sourceType": "module",
+    "ecmaVersion": 2023
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "indent": [2, 2, {"SwitchCase": 1}],
+    "quotes": [2, "single"],
+    "linebreak-style": [2, "unix"],
+    "camelcase": [2, {"properties": "always"}],
+    "brace-style": [2, "1tbs", {"allowSingleLine": true}]
+  },
+  "env": {
+    "es6": true,
+    "node": true,
+    "browser": false
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ]
+}

.github/dependabot.yml

@@ -3,6 +3,4 @@ updates:
 - package-ecosystem: npm
   directory: "/"
   schedule:
-    interval: monthly
-    time: "22:00"
-  open-pull-requests-limit: 10
+    interval: weekly

.github/workflows/nodejs.yml

@@ -7,23 +7,22 @@ on:
   push:
     branches: [main]
   pull_request:
-    branches: [main]
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [14, 16, 18]
+        node-version: [18, 20]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-      - run: npm install
+      - run: npm ci
       - run: npm test
         env:
           CI: true

readme.md → README.md

@@ -11,7 +11,7 @@
 
 ## About
 
-This is a PostHTML plugin that allows you to add parameters to URLs.
+This is a PostHTML plugin that allows you to add query string parameters to URLs.
 
 ## Install
 
@@ -22,18 +22,18 @@ npm i posthtml posthtml-url-parameters
 ## Usage
 
 ```js
-const posthtml = require('posthtml')
-const urlParams = require('posthtml-url-parameters')
+import posthtml from 'posthtml'
+import urlParams from 'posthtml-url-parameters'
 
 posthtml([
-    urlParams({
-      parameters: { foo: 'bar', baz: 'qux' }
-    })
-  ])
+  urlParams({
+    parameters: { foo: 'bar', baz: 'qux' }
+  })
+])
   .process('<a href="https://example.com">Test</div>')
   .then(result => console.log(result.html)))
 
-  // <a href="https://example.com?baz=qux&foo=bar">Test</div>
+// <a href="https://example.com?baz=qux&foo=bar">Test</div>
 ```
 
 ## Configuration
@@ -47,12 +47,19 @@ Object containing parameter name (key) and its value.
 Example:
 
 ```js
-require('posthtml-url-parameters')({
-  parameters: {
-    utm_source: 'Campaign',
-    '1stDraft': true
-  }
-})
+import posthtml from 'posthtml'
+import urlParams from 'posthtml-url-parameters'
+
+posthtml([
+  urlParams({
+    parameters: {
+      utm_source: 'Campaign',
+      '1stDraft': true
+    }
+  })
+])
+  .process('<a href="https://example.com">Test</a>')
+  .then(result => console.log(result.html))
 ```
 
 ### `tags`
@@ -66,19 +73,30 @@ By default, only URLs inside [known attributes](#attributes) of tags in this arr
 Example:
 
 ```js
-require('posthtml-url-parameters')({
-  tags: ['a', 'link'],
-  // ...
-})
+import posthtml from 'posthtml'
+import urlParams from 'posthtml-url-parameters'
+
+posthtml([
+  urlParams({
+    tags: ['a', 'img']
+  })
+])
+  .process(`
+    <a href="https://example.com">Test</a>
+    <img src="https://example.com/image.jpg">
+  `)
+  .then(result => console.log(result.html))
 ```
 
 You may use some CSS selectors when specifying tags:
 
 ```js
-require('posthtml-url-parameters')({
-  tags: ['a.button', 'a[href*="example.com"]' 'link'],
-  // ...
-})
+posthtml([
+  urlParams({
+    tags: ['a.button', 'a[href*="example.com"]' 'link'],
+  })
+])
+  .process(/*...*/)
 ```
 
 All [`posthtml-match-helper` selectors](https://github.com/posthtml/posthtml-match-helper) are supported.
@@ -114,8 +132,8 @@ By default, the plugin will append query parameters only to valid URLs.
 You may disable `strict` mode to append parameters to any string:
 
 ```js
-const posthtml = require('posthtml')
-const urlParams = require('posthtml-url-parameters')
+import posthtml from 'posthtml'
+import urlParams from 'posthtml-url-parameters'
 
 posthtml([
   urlParams({
@@ -138,8 +156,8 @@ Options to pass to `query-string` - see available options [here](https://github.
 For example, you may disable encoding:
 
 ```js
-const posthtml = require('posthtml')
-const urlParams = require('posthtml-url-parameters')
+import posthtml from 'posthtml'
+import urlParams from 'posthtml-url-parameters'
 
 posthtml([
   urlParams({
@@ -152,7 +170,7 @@ posthtml([
   .process('<a href="https://example.com">Test</a>')
   .then(result => console.log(result.html)))
 
-  // <a href="https://example.com?foo=@Bar@">Test</a>
+// <a href="https://example.com?foo=@Bar@">Test</a>
 ```
 
 [npm]: https://www.npmjs.com/package/posthtml-url-parameters
@@ -161,5 +179,5 @@ posthtml([
 [npm-stats-shield]: https://img.shields.io/npm/dt/posthtml-url-parameters.svg
 [github-ci]: https://github.com/posthtml/posthtml-url-parameters/actions
 [github-ci-shield]: https://github.com/posthtml/posthtml-url-parameters/actions/workflows/nodejs.yml/badge.svg
-[license]: ./license
+[license]: ./LICENSE
 [license-shield]: https://img.shields.io/npm/l/posthtml-url-parameters.svg

lib/index.d.ts

@@ -0,0 +1,133 @@
+import type {StringifyOptions} from 'query-string';
+
+export 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;
+}

lib/index.js

@@ -1,8 +1,8 @@
-const qs = require('query-string')
-const isUrl = require('is-url-superb')
-const matchHelper = require('posthtml-match-helper')
+import qs from 'query-string'
+import isUrl from 'is-url-superb'
+import matchHelper from 'posthtml-match-helper'
 
-module.exports = (config = {}) => tree => {
+const plugin = (config = {}) => tree => {
   config.strict = typeof config.strict === 'boolean' ? config.strict : true
 
   const process = node => {
@@ -49,3 +49,5 @@ module.exports = (config = {}) => tree => {
     resolve(tree)
   })
 }
+
+export default plugin