🔀 Merge branch 'release/4.0.0'

.eslintrc

@@ -4,18 +4,19 @@
     "plugin:@typescript-eslint/recommended",
     "plugin:prettier/recommended"
   ],
-  "env": {
-    "jest": true
-  },
   "settings": {
     "import/resolver": {
       "node": {
-        "extensions": [".js", ".ts"]
+        "extensions": [".ts"]
       }
     }
   },
   "rules": {
     "import/extensions": "off",
+    "import/no-extraneous-dependencies": [
+      "error",
+      { "devDependencies": ["**/*.test.[jt]s", "**/*.config.[jt]s"] }
+    ],
     "import/prefer-default-export": "off",
     "no-param-reassign": ["error", { "props": false }]
   }

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 14
+          node-version: 18
           cache: 'npm'
 
       - name: Install dependencies

.gitignore

@@ -1,4 +1,3 @@
 node_modules/
 dist/
 coverage/
-types/

.prettierignore

@@ -1,5 +1,4 @@
 coverage/
 dist/
-types/
 
 package-lock.json

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2023-02-18
+
+### Added
+
+- Exported types that the end user may need
+
+### Changed
+
+- **BREAKING** Renamed `parseStringSync` into `parseString`. The old async `parseString` has been removed
+- **BREAKING** In case of a system message the `author` property will be now set to `null` as opposed to the string `"System"`
+- Ship ESM and CJS versions, as well as a version for browsers. All files are minified. The new structure is the following:
+
+  ```sh
+  dist/
+  ├── index.cjs       # CommonJS
+  ├── index.d.ts      # Types
+  ├── index.global.js # Browser without ESM
+  └── index.js        # ESM
+  ```
+
+- Replaced jest with vitest
+- Replaced rollup with tsup
+
 ## [3.2.3] - 2023-02-17
 
 ### Changed
@@ -268,6 +291,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
+[4.0.0]: https://github.com/Pustur/whatsapp-chat-parser/compare/3.2.3...4.0.0
 [3.2.3]: https://github.com/Pustur/whatsapp-chat-parser/compare/3.2.2...3.2.3
 [3.2.2]: https://github.com/Pustur/whatsapp-chat-parser/compare/3.2.1...3.2.2
 [3.2.1]: https://github.com/Pustur/whatsapp-chat-parser/compare/3.2.0...3.2.1

README.md

@@ -7,7 +7,11 @@
 
 > A package to parse WhatsApp chats with Node.js or in the browser 💬
 
-# Introduction
+## Important notice
+
+🚨 `v4.0.0` brings some **BREAKING CHANGES**, check out the [release page](https://github.com/Pustur/whatsapp-chat-parser/releases/tag/4.0.0) for more info.
+
+## Introduction
 
 This library allows you to parse WhatsApp chat logs from text format into javascript objects, enabling you to more easily manipulate the data, create statistics, export it in different formats, etc.
 
@@ -24,32 +28,14 @@ $ npm install whatsapp-chat-parser
 
 ### Node
 
-```javascript
+```js
 import fs from 'node:fs';
-import whatsapp from 'whatsapp-chat-parser';
+import * as whatsapp from 'whatsapp-chat-parser';
 
-// Sync
 const text = fs.readFileSync('path/to/_chat.txt', 'utf8');
-const messages = whatsapp.parseStringSync(text);
+const messages = whatsapp.parseString(text);
 
 console.log(messages);
-
-// Promise chain
-fs.promises
-  .readFile('path/to/_chat.txt', 'utf8')
-  .then(text => whatsapp.parseString(text))
-  .then(messages => console.log(messages))
-  .catch(error => console.error(error));
-
-// Promises with async / await
-try {
-  const text = await fs.promises.readFile('path/to/_chat.txt', 'utf8');
-  const messages = await whatsapp.parseString(text);
-
-  console.log(messages);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ### Browser
@@ -58,9 +44,23 @@ Add the script to your HTML file (usually just before the closing `</body>` tag)
 Then use it in your JavaScript code, the `whatsappChatParser` variable will be globally available.
 
 ```html
-<script src="path/to/whatsapp-chat-parser.min.js"></script>
+<script src="path/to/index.global.js"></script>
 <script>
-  const messages = whatsappChatParser.parseStringSync(
+  const messages = whatsappChatParser.parseString(
+    '06/03/2017, 00:45 - Sample User: This is a test message',
+  );
+
+  console.log(messages);
+</script>
+```
+
+Or with `type="module"` loading the ESM version:
+
+```html
+<script type="module">
+  import * as whatsapp from 'path/to/index.js';
+
+  const messages = whatsapp.parseString(
     '06/03/2017, 00:45 - Sample User: This is a test message',
   );
 
@@ -71,16 +71,16 @@ Then use it in your JavaScript code, the `whatsappChatParser` variable will be g
 You can also use the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/whatsapp-chat-parser).
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/whatsapp-chat-parser/dist/whatsapp-chat-parser.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/whatsapp-chat-parser/dist/index.global.js"></script>
 <!-- Or use a specific version -->
-<script src="https://cdn.jsdelivr.net/npm/whatsapp-chat-parser@3.2.3/dist/whatsapp-chat-parser.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/whatsapp-chat-parser@4.0.0/dist/index.global.js"></script>
 ```
 
-&nbsp;
+## Message structure
 
 The `messages` variable is an array of objects like this:
 
-```javascript
+```js
 [
   {
     date: '2018-06-02T22:45:00.000Z', // Date object
@@ -97,7 +97,7 @@ The `messages` variable is an array of objects like this:
 
 When using the option [`parseAttachments`](#options), the message may contain an additional property `attachment`:
 
-```javascript
+```js
 [
   {
     date: '2018-06-02T23:50:00.000Z', // Date object
@@ -110,21 +110,21 @@ When using the option [`parseAttachments`](#options), the message may contain an
 ];
 ```
 
-In the case of a system message, the author will be `System`
+In the case of a system message, the author will be `null`
 
-```javascript
+```js
 [
   {
     date: '2018-06-02T22:45:00.000Z', // Date object
-    author: 'System',
+    author: null,
     message: 'You created group "Party 🎉"',
   },
 ];
 ```
 
 ## API
 
-### parseString(string, [options]) → Promise
+### parseString(string, [options]) → Array
 
 **string**
 
@@ -138,10 +138,6 @@ Type: `object`
 
 A configuration object, more details below
 
-### parseStringSync(string, [options]) → Array
-
-Same as `parseString` but returns the messages directly instead of a promise.
-
 ## Options
 
 <!-- prettier-ignore-start -->
@@ -151,6 +147,13 @@ Same as `parseString` but returns the messages directly instead of a promise.
 | parseAttachments | `Boolean` | `false` | Specify if attachments should be parsed. If set to `true`, messages with attachments will include an `attachment` property with information about the attachment. |
 <!-- prettier-ignore-end -->
 
+## A note about messages order
+
+Sometimes, likely due to connection issues, WhatsApp exports contain messages that are not chronologically ordered.  
+This library won't change the order of the messages, but if your application expects a certain order make sure to sort the array of messages accordingly before use.
+
+See [#247](https://github.com/Pustur/whatsapp-chat-parser/issues/247) for more info.
+
 ## How to export WhatsApp chats
 
 - [Android](https://faq.whatsapp.com/android/chats/how-to-save-your-chat-history)
@@ -159,7 +162,7 @@ Same as `parseString` but returns the messages directly instead of a promise.
 ## Technologies used
 
 - Language: [TypeScript](https://www.typescriptlang.org/)
-- Testing: [Jest](https://jestjs.io/)
+- Testing: [Vitest](https://vitest.dev/)
 - Code formatting: [Prettier](https://prettier.io/)
 - Linting: [ESLint](https://eslint.org/) (with [Airbnb rules](https://www.npmjs.com/package/eslint-config-airbnb-base))