Merge pull request #1 from luckrnx09/luckrnx09-init

Feat: Add EmailMinifier

Author: luckrnx09

.eslintrc

@@ -0,0 +1,18 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "plugins": [
+    "prettier"
+  ],
+  "rules": {
+    "prettier/prettier": "error",
+    "@typescript-eslint/no-explicit-any": "warn"
+  },
+  "ignorePatterns": [
+    "dist"
+  ]
+}

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on: [push, pull_request]
+
+env:
+  FORCE_COLOR: 2
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18.x"
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Run tests
+        run: pnpm run test

.gitignore

@@ -128,3 +128,6 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+.npmrc
+pnpm-lock.yaml

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2
+}

README.md

@@ -1 +1,98 @@
-# email-minifier
+# EmailMinifier
+
+[![npm version](https://img.shields.io/npm/v/email-minifier.svg)](https://www.npmjs.com/package/email-minifier)
+
+
+EmailMinifier is a well-tested email minifier based on TypeScript for browser and Node.js
+
+As a quick start, you can [Try it online](https://luckrnx09.github.io/email-minifier/playground) - NOT READY, Welcome to submit a PR 🚀
+
+## Why not HTMLMinifier
+
+EmailMinifier is a great tool for compressing HTML. But email is different from HTML in many ways, compression of HTML is often not the best solution.
+- JavaScript code is not supported or required in emails.
+- The interactive behavior of the email is very limited, most HTML attributes are useless for the email but still load them when user open it.
+- Some email clients crop oversized emails (e.g. Gmail) and the style of the email is broken after cropping, which is extremely detrimental to marketing.
+- ...
+
+## Installation
+
+You can use the tool you like to install EmailMinifier:
+
+npm
+```shell
+npm install email-minifier 
+```
+
+yarn
+```shell
+yarn add email-minifier 
+```
+
+pnpm
+```shell
+pnpm install email-minifier 
+```
+ 
+## Usage
+
+For both browser and Node.js if you use ESM:
+
+```javascript
+import { EmailMinifier } from 'email-minifier';
+(async () => { 
+    const emailBody = `<div class="hello"></div>`;
+    const options = {};
+    const result = await new EmailMinifier(emailBody).minify(options);
+    console.log(result);
+})();
+```
+
+
+For Node.js only if you use CommonJS:
+
+```javascript
+const { EmailMinifier } = require('email-minifier');
+(async () => { 
+    const emailBody = `<div class="hello"></div>`;
+    const options = {};
+    const result = await new EmailMinifier(emailBody).minify(options);
+    console.log(result);
+})();
+```
+
+The `minify()` method will returns a Promise with the shape as follow:
+
+```javascript
+{
+    original: '', // the original email body string
+    minified: '', // minified email body string will be here, if no tasks ran, it'll be null
+    tasks: [] // all ran tasks when minify email body
+}
+```
+
+All available properties for `options` are as follows
+
+| Option                         | Description     | Default |
+|--------------------------------|-----------------|---------|
+| `minifyIds`                | Minifiy id attributes used in style tags | `true` |
+| `minifyClasses`    | Minifiy class attributes used in style tags | `true` |
+| `minifyDatasets`    | Minifiy data-* attributes used in style tags | `true` |
+| `removeUnusedAttrs`    | Remove custom attributes unused in style tags | `false` |
+| `minifyStyles`    | Minifiy CSS content for all the style tags | `true` |
+
+For `removeUnusedAttrs`, if you want to remove the specific unused attributes, you can provide an array with `RegExp` instances to match them. 
+
+For example: 
+```javascript
+const options = {
+    removeUnusedAttrs: [
+        new RegExp('custom-test-id') // Remove `custom-test-id` attributes if they not used in style tags
+    ]
+}
+```
+
+
+
+# License
+See [LICENSE](./LICENSE)

jest.config.ts

@@ -0,0 +1,20 @@
+import type { JestConfigWithTsJest } from 'ts-jest';
+
+const config: JestConfigWithTsJest = {
+  verbose: true,
+  transform: {
+    '^.+\\.ts?$': [
+      'ts-jest',
+      {
+        useESM: true,
+      },
+    ],
+  },
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  testMatch: ['<rootDir>/**/*.test.ts'],
+};
+
+export default config;

lib/document.ts

@@ -0,0 +1,10 @@
+export const createDocument = async (html: string): Promise<Document> => {
+  const isNode =
+    typeof window === 'undefined' && typeof document === 'undefined';
+  if (isNode) {
+    const { JSDOM } = await import('jsdom');
+    return new JSDOM(html).window.document;
+  } else {
+    return Promise.resolve(new DOMParser().parseFromString(html, 'text/html'));
+  }
+};

lib/email-minifier.ts

@@ -0,0 +1,100 @@
+import { Sequence } from './sequence';
+import { createDocument } from './document';
+import { TaskManager } from './task-manager';
+import { Context, ComposeOption } from './types';
+
+const DEFAULT_COMPOSE_OPTIONS: ComposeOption = {
+  minifyIds: true,
+  minifyClasses: true,
+  minifyDatasets: true,
+  minifyStyles: true,
+  removeUnusedAttrs: false,
+};
+/**
+ * Minify an email body
+ * @example
+ * const minifier = new EmailMinifier('<html>...</html>');
+ * const result = await minifier.minify();
+ * console.log(result.minified);
+ */
+export class EmailMinifier {
+  private emailBody: string;
+
+  constructor(emailBody: string) {
+    this.emailBody = emailBody;
+  }
+  /**
+   * Compose the minify tasks
+   */
+  private compose = (
+    context: Context,
+    options?: ComposeOption,
+  ): TaskManager => {
+    const taskManager = new TaskManager();
+    const {
+      minifyIds,
+      minifyClasses,
+      minifyDatasets,
+      minifyStyles,
+      removeUnusedAttrs,
+    } = { ...DEFAULT_COMPOSE_OPTIONS, ...(options ?? {}) };
+
+    const { document } = context;
+
+    document.body.querySelectorAll('*').forEach((el) => {
+      minifyIds && taskManager.add('minify-ids', el, context);
+      minifyClasses && taskManager.add('minify-classes', el, context);
+      removeUnusedAttrs &&
+        taskManager.add('remove-unused-attrs', el, context, {
+          matches: removeUnusedAttrs,
+        });
+      minifyDatasets && taskManager.add('minify-dataset-attrs', el, context);
+    });
+    document.head.querySelectorAll('style').forEach((el) => {
+      taskManager.add('minify-styles', el, context, {
+        minifyStyles,
+      });
+    });
+    return taskManager;
+  };
+
+  private async createContext(): Promise<Context> {
+    const { emailBody } = this;
+    const document = await createDocument(emailBody);
+    return {
+      originalEmailBody: emailBody,
+      styles: Array.from(document.head.querySelectorAll('style'))
+        .map((el) => el.textContent)
+        .join('\n'),
+      document,
+      idSequence: new Sequence(),
+      classSequence: new Sequence(),
+      mapping: {
+        ids: new Map<string, string>(),
+        classes: new Map<string, string>(),
+        dataSets: new Map<string, string>(),
+      },
+    };
+  }
+
+  async minify(options?: ComposeOption) {
+    const context = await this.createContext();
+    const taskManager = this.compose(context, options);
+    const { originalEmailBody, document } = context;
+    const tasks = taskManager.runAll();
+
+    if (tasks.length === 0) {
+      return {
+        original: originalEmailBody,
+        minified: null,
+        tasks,
+      };
+    }
+
+    return {
+      original: originalEmailBody,
+      minified: document.documentElement.outerHTML,
+      tasks,
+    };
+  }
+}

lib/index.ts

@@ -0,0 +1 @@
+export { EmailMinifier } from './email-minifier';

lib/sequence.ts

@@ -0,0 +1,37 @@
+/**
+ * Generates a sequence of alphabetical characters.
+ */
+export class Sequence {
+  private current: string[];
+
+  constructor() {
+    this.current = ['a'];
+  }
+
+  next() {
+    const sequence = this.current.join('');
+    let i = this.current.length - 1;
+
+    while (i >= 0) {
+      if (this.current[i] !== 'z') {
+        this.current[i] = this.getNextChar(this.current[i]);
+        break;
+      } else {
+        this.current[i] = 'a';
+        i--;
+      }
+    }
+
+    if (i < 0) {
+      this.current.unshift('a');
+    }
+
+    return sequence;
+  }
+
+  private getNextChar(char: string): string {
+    const charCode = char.charCodeAt(0);
+    const nextCharCode = charCode + 1;
+    return String.fromCharCode(nextCharCode);
+  }
+}