Skip to content

Commit 7cb261d

Browse files
chriskyfungchriskyfung
authored
🔀 Merge pull request #9 from chriskyfung/feature/improvements-and-ci
✨ feat: Add CI workflow, improve build, and update docs
2 parents 716f0e7 + 88ce7a5 commit 7cb261d

File tree

11 files changed

+300
-150
lines changed

11 files changed

+300
-150
lines changed

‎.github/workflows/ci.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
build-and-test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
node-version: [18.x, 20.x, 22.x, 24.x]
15+
steps:
16+
- uses: actions/checkout@v4
17+
- name: Use Node.js ${{ matrix.node-version }}
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: ${{ matrix.node-version }}
21+
cache: 'npm'
22+
- name: Install dependencies
23+
run: npm ci
24+
- name: Run validation
25+
run: npm run validate
26+
- name: Build project
27+
run: npm run build

‎.gitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,6 @@ $RECYCLE.BIN/
194194
/dist
195195
.clasp.json
196196
.clasp.json.bk
197-
appsscript.json
198197
node_modules
199198
private.[gj]s
200199
IMPROVEMENTS.md

‎GEMINI.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,14 @@ This is a Google Apps Script project for cleaning old emails in Gmail based on r
1616
2. **Testing**: This project uses [Jest](https://jestjs.io/) for automated testing. Run `npm test` to execute the test suite.
1717
3. **Code Style**: The project is configured with ESLint and Prettier for code quality and consistent formatting. Run `npm run lint` to check for any linting issues. Please adhere to the existing code style.
1818
4. **TypeScript Migration**: The project is a good candidate for migration to TypeScript for improved type safety. If significant changes are made, consider proposing this migration.
19-
5. **Commit Messages**: Use the GitMoji convention for commit messages (e.g., `✨ feat: ...`, `🐛 fix: ...`).
19+
5. **Commit Messages**: Follow the GitMoji convention for commit messages. The format is `emoji type(scope): subject`. For a complete list of emojis and their meanings, refer to the [GitMoji website](https://gitmoji.dev).
20+
- Use lowercase for the subject line (after the colon).
21+
- **CI/Build System (`ci`, `chore`):**
22+
- Use `👷` for adding or updating the CI build system (e.g., GitHub Actions).
23+
- Use `🔧` for configuration file changes.
24+
- Use `🔨` for development script updates.
25+
- Example: `👷 ci: add new workflow`
26+
- Example: `🔧 chore(eslint): update eslint config`
27+
- **Documentation (`docs`):**
28+
- Use `📝` for adding or updating documentation.
29+
- Example: `📝 docs(readme): update installation instructions`

‎README.md

Lines changed: 3 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -12,127 +12,16 @@ This is a Google Apps Script project that helps you delete old emails in Gmail t
1212

1313
## How to use
1414

15-
1. Create a new Google Apps Script project in Google Drive.
16-
2. Copy and paste the code from `src/code.js` and `src/examples.js` into the script editor.
17-
3. From the `examples.js` file, choose a function that matches your needs, or create a new one. You can then run this function from the Apps Script editor.
18-
19-
For example, to run one of the pre-made functions, you would select it in the editor's function list and click **Run**.
20-
21-
The `main` function, which does the core work, has been updated to be more flexible. Here is how you would call it inside a custom function:
22-
23-
```js
24-
function removeOldGoogleAlerts() {
25-
const query = 'from:(Google Alerts <[email protected]>)';
26-
const regex = /[0-9]{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)/m;
27-
28-
// Call main with an options object for configuration
29-
main(query, regex, {
30-
tresholdInDays: 90, // Optional: default is 60
31-
isDryRun: true, // Optional: default is true
32-
mode: 'html', // Optional: default is 'plain'
33-
dateFormatter: (textWithDate, lastMessageDate) => {
34-
/*
35-
Your code to extract and format the date part to a date string
36-
that can be parsed by the Date constructor.
37-
*/
38-
// This is just an example, a real implementation is needed here.
39-
return new Date().toISOString();
40-
}
41-
});
42-
}
43-
```
44-
45-
> [!NOTE]
46-
> **`query`**: A string that specifies the search criteria for the emails you want to delete. It should follow the same syntax as the Gmail search box. For example, `from:(Google Alerts <[email protected]>)` will match all emails from Google Alerts. You can find more examples and tips on how to use the Gmail search operators [here](https://developers.google.com/codelabs/apps-script-fundamentals-1).
47-
>
48-
> **`regex`**: A regular expression that matches the date part of the email subject or body. It should be enclosed in slashes and follow the JavaScript regex syntax. For example, `/[0-9]{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)/m` will match a date like “8 Feb” or “23 Nov” in the email.
49-
>
50-
> The third parameter to `main` is now an **options object** with the following optional properties:
51-
>
52-
> - **`tresholdInDays`**: The number of days to keep emails. Defaults to `60`.
53-
> - **`isDryRun`**: A boolean value that indicates whether to run the script in test mode or not. If `true` (the default), the script will only log the emails that match the query and the regex, but will not delete them. If `false`, the script will delete the emails permanently. It is recommended to run the script with `isDryRun` set to `true` first to make sure it works as expected.
54-
> - **`mode`**: A string that specifies whether to process the email body as plain text or HTML. Can be either `'plain'` (default) or `'html'`. If set to `'html'`, the script will strip all HTML tags from the email body before searching for the regex pattern.
55-
> - **`dateFormatter`**: A function that takes two parameters: `textWithDate` and `lastMessageDate`. The `textWithDate` is a string that contains the date part extracted from the email body. The `lastMessageDate` is a date object that represents the latest date of the email thread. The function should return a date string like `yyyy-MM-dd` that can be parsed by `new Date()`.
56-
57-
4. Save and run the desired function from the script editor. You can use the **Run** menu or the **Run** button in the toolbar.
58-
59-
> [!IMPORTANT]
60-
> When running the script for the first time, you may need to authorize it to access your Gmail account.
61-
62-
5. Optionally, set up a trigger to run a function periodically. You can do this by clicking the **Triggers** icon in the left sidebar, then clicking the **Add a trigger** button, and choosing the options you want. For example, you can set the script to run every day, week, or month.
63-
64-
> [!WARNING]
65-
> This script will delete your emails permanently, without moving them to the trash. Please use it with caution and make sure you have a backup of your important emails. You can run the script with the `isDryRun` option set to `true` first to see what emails will be deleted.
15+
For detailed instructions on how to set up and use this script, please see the [**Usage Guide**](./docs/usage.md).
6616

6717
## Development
6818

69-
This project uses [ESLint](https://eslint.org/) for code linting and [Prettier](https://prettier.io/) for code formatting. It is recommended to run the linter before committing any changes.
70-
71-
To run the linter, use the following command:
72-
73-
```bash
74-
npm run lint
75-
```
76-
77-
This project uses [Jest](https://jestjs.io/) for automated testing.
78-
79-
To run the tests, use the following command:
80-
81-
```bash
82-
npm test
83-
```
84-
85-
### Build Process
86-
87-
This project uses [Rollup](https://rollupjs.org/) to bundle the source files from `src/` into the `dist/` directory, which is ready for deployment with `@google/clasp`.
88-
89-
To build the project, run:
90-
91-
```bash
92-
npm run build
93-
```
94-
95-
This command bundles `src/code.js` and processes `src/examples.js` into the `dist/` directory. It also removes a Node.js-specific code block from `code.js` that is used for testing with Jest.
96-
97-
#### Excluding Example Functions
98-
99-
You can prevent specific functions from `src/examples.js` from being included in the final `dist/examples.js` file. This is useful if you only need a subset of the example functions for your deployment.
100-
101-
To exclude functions, add their names to the `config.examples.exclude` array in your `package.json` file:
102-
103-
```json
104-
{
105-
"name": "gmail-regex-cleaner-apps-script",
106-
"version": "1.0.0",
107-
// ...
108-
"config": {
109-
"examples": {
110-
"exclude": [
111-
"removeAffiliatesOne",
112-
"removeCorelAffiliateInfo"
113-
]
114-
}
115-
},
116-
// ...
117-
}
118-
```
119-
120-
When you run `npm run build`, the functions listed in the `exclude` array will be omitted from the output.
121-
122-
#### Timezone Update
123-
124-
Optionally, you can update the timezone in the `dist/appsscript.json` manifest to match your local machine's timezone. This is useful to ensure that scheduled triggers run at the correct time.
125-
126-
To update the timezone, run the following command **after** the build command:
127-
128-
```bash
129-
npm run update-timezone
130-
```
19+
This project uses ESLint for linting, Prettier for formatting, Jest for testing, and Rollup for building. For more details on the development setup and build process, please see the [**Development Guide**](./docs/development.md).
13120

13221
## Disclaimer
13322

13423
This script is provided as is, without any warranty or liability. Use it at your own risk. Make sure to test the script before using it on your Gmail account. The script may delete emails that you want to keep, or fail to delete emails that you want to remove. The script may also exceed the quota limits of Google Apps Script or Gmail API, resulting in errors or partial execution. The author is not responsible for any loss or damage caused by the use of this script.
13524

13625
## License
13726

138-
This project is distributed under the AGPL-3.0 license. You can use, modify, and distribute this project, as long as you comply with the terms and conditions in the [LICENSE](/LICENSE) file.
27+
This project is distributed under the AGPL-3.0 license. You can use, modify, and distribute this project, as long as you comply with the terms and conditions in the [LICENSE](/LICENSE) file.

‎docs/development.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Development
2+
3+
This project uses [ESLint](https://eslint.org/) for code linting and [Prettier](https://prettier.io/) for code formatting. It is recommended to run the linter before committing any changes.
4+
5+
To run the linter, use the following command:
6+
7+
```bash
8+
npm run lint
9+
```
10+
11+
This project uses [Jest](https://jestjs.io/) for automated testing.
12+
13+
To run the tests, use the following command:
14+
15+
```bash
16+
npm test
17+
```
18+
19+
## Build Process
20+
21+
This project uses [Rollup](https://rollupjs.org/) to bundle the source files from `src/` into the `dist/` directory, which is ready for deployment with `@google/clasp`.
22+
23+
To build the project, run:
24+
25+
```bash
26+
npm run build
27+
```
28+
29+
This command bundles `src/code.js` and processes `src/examples.js` into the `dist/` directory. It also removes a Node.js-specific code block from `code.js` that is used for testing with Jest.
30+
31+
### Excluding Example Functions
32+
33+
You can prevent specific functions from `src/examples.js` from being included in the final `dist/examples.js` file. This is useful if you only need a subset of the example functions for your deployment.
34+
35+
To exclude functions, add their names to the `config.examples.exclude` array in your `package.json` file:
36+
37+
```json
38+
{
39+
"name": "gmail-regex-cleaner-apps-script",
40+
"version": "1.0.0",
41+
// ...
42+
"config": {
43+
"examples": {
44+
"exclude": [
45+
"removeAffiliatesOne",
46+
"removeCorelAffiliateInfo"
47+
]
48+
}
49+
},
50+
// ...
51+
}
52+
```
53+
54+
When you run `npm run build`, the functions listed in the `exclude` array will be omitted from the output.
55+
56+
### Timezone Update
57+
58+
Optionally, you can update the timezone in the `dist/appsscript.json` manifest to match your local machine's timezone. This is useful to ensure that scheduled triggers run at the correct time.
59+
60+
To update the timezone, run the following command **after** the build command:
61+
62+
```bash
63+
npm run update-timezone
64+
```

‎docs/usage.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# How to Use
2+
3+
1. Create a new Google Apps Script project in Google Drive.
4+
2. Copy and paste the code from `dist/code.js` and `dist/examples.js` into the script editor.
5+
3. From the `examples.js` file, choose a function that matches your needs, or create a new one. You can then run this function from the Apps Script editor.
6+
7+
For example, to run one of the pre-made functions, you would select it in the editor's function list and click **Run**.
8+
9+
The `main` function, which does the core work, has been updated to be more flexible. Here is how you would call it inside a custom function:
10+
11+
```js
12+
function removeOldGoogleAlerts() {
13+
const query = 'from:(Google Alerts <[email protected]>)';
14+
const regex = /[0-9]{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)/m;
15+
16+
// Call main with an options object for configuration
17+
main(query, regex, {
18+
tresholdInDays: 90, // Optional: default is 60
19+
isDryRun: true, // Optional: default is true
20+
mode: 'html', // Optional: default is 'plain'
21+
dateFormatter: (textWithDate, lastMessageDate) => {
22+
/*
23+
Your code to extract and format the date part to a date string
24+
that can be parsed by the Date constructor.
25+
*/
26+
// This is just an example, a real implementation is needed here.
27+
return new Date().toISOString();
28+
}
29+
});
30+
}
31+
```
32+
33+
> [!NOTE]
34+
> **`query`**: A string that specifies the search criteria for the emails you want to delete. It should follow the same syntax as the Gmail search box. For example, `from:(Google Alerts <[email protected]>)` will match all emails from Google Alerts. You can find more examples and tips on how to use the Gmail search operators [here](https://developers.google.com/codelabs/apps-script-fundamentals-1).
35+
>
36+
> **`regex`**: A regular expression that matches the date part of the email subject or body. It should be enclosed in slashes and follow the JavaScript regex syntax. For example, `/[0-9]{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)/m` will match a date like “8 Feb” or “23 Nov” in the email.
37+
>
38+
> The third parameter to `main` is now an **options object** with the following optional properties:
39+
>
40+
> - **`tresholdInDays`**: The number of days to keep emails. Defaults to `60`.
41+
> - **`isDryRun`**: A boolean value that indicates whether to run the script in test mode or not. If `true` (the default), the script will only log the emails that match the query and the regex, but will not delete them. If `false`, the script will delete the emails permanently. It is recommended to run the script with `isDryRun` set to `true` first to make sure it works as expected.
42+
> - **`mode`**: A string that specifies whether to process the email body as plain text or HTML. Can be either `'plain'` (default) or `'html'`. If set to `'html'`, the script will strip all HTML tags from the email body before searching for the regex pattern.
43+
> - **`dateFormatter`**: A function that takes two parameters: `textWithDate` and `lastMessageDate`. The `textWithDate` is a string that contains the date part extracted from the email body. The `lastMessageDate` is a date object that represents the latest date of the email thread. The function should return a date string like `yyyy-MM-dd` that can be parsed by `new Date()`.
44+
45+
4. Save and run the desired function from the script editor. You can use the **Run** menu or the **Run** button in the toolbar.
46+
47+
> [!IMPORTANT]
48+
> When running the script for the first time, you may need to authorize it to access your Gmail account.
49+
50+
5. Optionally, set up a trigger to run a function periodically. You can do this by clicking the **Triggers** icon in the left sidebar, then clicking the **Add a trigger** button, and choosing the options you want. For example, you can set the script to run every day, week, or month.
51+
52+
> [!WARNING]
53+
> This script will delete your emails permanently, without moving them to the trash. Please use it with caution and make sure you have a backup of your important emails. You can run the script with the `isDryRun` option set to `true` first to see what emails will be deleted.

0 commit comments

Comments
 (0)