immutable-js · jdeniau · Oct 17, 2024 · Aug 24, 2023 · Aug 24, 2023 · Aug 24, 2023
diff --git a/.eslintignore b/.eslintignore
@@ -2,3 +2,4 @@
 /pages/generated/**
 /dist/**
 node_modules
+/type-definitions/flow-tests
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,11 +1,17 @@
 {
   "root": true,
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
     "ecmaVersion": 6,
     "sourceType": "module"
   },
-  "extends": ["airbnb", "prettier"],
-  "plugins": ["react", "prettier"],
+  "extends": [
+    "airbnb",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:import/typescript",
+    "prettier"
+  ],
+  "plugins": ["react", "prettier", "@typescript-eslint"],
   "rules": {
     "array-callback-return": "off",
     "block-scoped-var": "off",
@@ -35,7 +41,7 @@
     "no-this-before-super": "off",
     "no-underscore-dangle": "off",
     "no-unused-expressions": "off",
-    "no-unused-vars": "error",
+    "no-unused-vars": "off",
     "no-use-before-define": "off",
     "no-useless-concat": "error",
     "no-var": "error",
@@ -61,10 +67,15 @@
     "react/self-closing-comp": "error",
     "react/sort-comp": "off",
     "react/jsx-props-no-spreading": "off",
+    "react/require-default-props": [
+      "error",
+      {
+        "functions": "ignore"
+      }
+    ],
     "jsx-a11y/no-static-element-interactions": "off",
     "import/extensions": [
       "error",
-      "always",
       { "js": "never", "ts": "never", "tsx": "never" }
     ],
     "import/newline-after-import": "error",
@@ -74,6 +85,39 @@
     "import/no-unresolved": "error",
     "import/no-useless-path-segments": "off",
     "import/prefer-default-export": "off",
-    "prettier/prettier": "error"
-  }
+    "prettier/prettier": "error",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["__tests__/*"],
+      "rules": {
+        "import/no-unresolved": [
+          "error",
+          {
+            "ignore": ["immutable"]
+          }
+        ]
+      }
+    },
+
+    {
+      "files": ["type-definitions/ts-tests/*"],
+      "rules": {
+        "no-lone-blocks": "off",
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unused-vars": "off",
+        "prefer-const": "off",
+        "import/no-unresolved": [
+          "error",
+          {
+            "ignore": ["immutable"]
+          }
+        ]
+      }
+    }
+  ]
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,9 +4,11 @@ on:
   push:
     branches:
       - main
+      - 5.x
   pull_request:
     branches:
       - main
+      - 5.x
 
 jobs:
   lint:
@@ -48,8 +50,8 @@ jobs:
       - run: npm run type-check
       - run: npm run check-git-clean
 
-  unit-test:
-    name: 'Build & Unit Test'
+  test:
+    name: 'Build & Unit Test & Type Test'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -63,7 +65,9 @@ jobs:
           restore-keys: ${{ runner.OS }}-node-
       - run: npm ci
       - run: npm run build
-      - run: npm run unit-test
+      - run: npm run test:unit
+      - run: npm run test:types -- --target 4.5,5.0,current
+      - run: npx size-limit
       - run: npm run check-git-clean
 
   website:
@@ -87,7 +91,7 @@ jobs:
 
   publish:
     name: 'Publish'
-    needs: [lint, type-check, unit-test, website]
+    needs: [lint, type-check, test, website]
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:

diff --git a/.prettierignore b/.prettierignore
@@ -1,5 +1,4 @@
 dist
 pages/generated
 pages/out
-type-definitions/ts-tests/
-type-definitions/flow-tests/
+type-definitions/flow-tests/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,150 @@ Dates are formatted as YYYY-MM-DD.
 
 ## Unreleased
 
+## [5.0.0]
+
+### Breaking changes
+
+To sum up, the **big** change in 5.0 is a Typescript change related to `Map` that is typed closer to the JS object. This is a huge change for TS users, but do not impact the runtime behavior. (see [Improve TypeScript definition for `Map`](#typescript-break-improve-typescript-definition-for-map) for more details)
+
+Other breaking changes are:
+
+#### [BREAKING] Remove deprecated methods:
+
+_Released in 5.0.0-rc.1_
+
+- `Map.of('k', 'v')`: use `Map([ [ 'k', 'v' ] ])` or `Map({ k: 'v' })`
+- `Collection.isIterable`: use `isIterable` directly
+- `Collection.isKeyed`: use `isKeyed` directly
+- `Collection.isIndexed`: use `isIndexed` directly
+- `Collection.isAssociative`: use `isAssociative` directly
+- `Collection.isOrdered`: use `isOrdered` directly
+
+#### [BREAKING] `OrdererMap` and `OrderedSet` hashCode implementation has been fixed
+
+_Released in 5.0.0-rc.1_
+
+Fix issue implementation of `hashCode` for `OrdererMap` and `OrderedSet` where equal objects might not return the same `hashCode`.
+
+Changed in [#2005](https://github.com/immutable-js/immutable-js/pull/2005)
+
+#### [BREAKING] Range function needs at least two defined parameters
+
+_Released in 5.0.0-beta.5_
+
+Range with `undefined` would end in an infinite loop. Now, you need to define at least the start and end values.
+
+If you need an infinite range, you can use `Range(0, Infinity)`.
+
+Changed in [#1967](https://github.com/immutable-js/immutable-js/pull/1967) by [@jdeniau](https://github.com/jdeniau)
+
+#### [Minor BC break] Remove default export
+
+_Released in 5.0.0-beta.1_
+
+Immutable does not export a default object containing all it's API anymore.
+As a drawback, you can not `immport Immutable` directly:
+
+```diff
+- import Immutable from 'immutable';
++ import { List, Map } from 'immutable';
+
+- const l = Immutable.List([Immutable.Map({ a: 'A' })]);
++ const l = List([Map({ a: 'A' })]);
+```
+
+If you want the non-recommanded, but shorter migration path, you can do this:
+
+```diff
+- import Immutable from 'immutable';
++ import * as Immutable from 'immutable';
+
+  const l = Immutable.List([Immutable.Map({ a: 'A' })]);
+```
+
+#### [TypeScript Break] Improve TypeScript definition for `Map`
+
+_Released in 5.0.0-beta.1_
+
+> If you do use TypeScript, then this change does not impact you : no runtime change here.
+> But if you use Map with TypeScript, this is a HUGE change !
+> Imagine the following code
+
+```ts
+const m = Map({ length: 3, 1: 'one' });
+```
+
+This was previously typed as `Map<string, string | number>`
+
+and return type of `m.get('length')` or `m.get('inexistant')` was typed as `string | number | undefined`.
+
+This made `Map` really unusable with TypeScript.
+
+Now the Map is typed like this:
+
+```ts
+MapOf<{
+    length: number;
+    1: string;
+}>
+```
+
+and the return type of `m.get('length')` is typed as `number`.
+
+The return of `m.get('inexistant')` throw the TypeScript error:
+
+> Argument of type '"inexistant"' is not assignable to parameter of type '1 | "length"
+
+##### If you want to keep the old definition
+
+**This is a minor BC for TS users**, so if you want to keep the old definition, you can declare you Map like this:
+
+```ts
+const m = Map<string, string | number>({ length: 3, 1: 'one' });
+```
+
+##### If you need to type the Map with a larger definition
+
+You might want to declare a wider definition, you can type your Map like this:
+
+```ts
+type MyMapType = {
+  length: number;
+  1: string | null;
+  optionalProperty?: string;
+};
+const m = Map<MyMapType>({ length: 3, 1: 'one' });
+```
+
+Keep in mind that the `MapOf` will try to be consistant with the simple TypeScript object, so you can not do this:
+
+```ts
+Map({ a: 'a' }).set('b', 'b');
+Map({ a: 'a' }).delete('a');
+```
+
+Like a simple object, it will only work if the type is forced:
+
+```ts
+Map<{ a: string; b?: string }>({ a: 'a' }).set('b', 'b'); // b is forced in type and optional
+Map<{ a?: string }>({ a: 'a' }).delete('a'); // you can only delete an optional key
+```
+
+##### Are all `Map` methods implemented ?
+
+For now, only `get`, `getIn`, `set`, `update`, `delete`, `remove`, `toJS`, `toJSON` methods are implemented. All other methods will fallback to the basic `Map` definition. Other method definition will be added later, but as some might be really complex, we prefer the progressive enhancement on the most used functions.
+
+### Fixes
+
+- Fix type inference for first() and last() [#2001](https://github.com/immutable-js/immutable-js/pull/2001) by [@butchler](https://github.com/butchler)
+
+### Internal
+
+- [Internal] Migrating TS type tests from dtslint to [TSTyche](https://tstyche.org/) [#1988](https://github.com/immutable-js/immutable-js/pull/1988) and [#1991](https://github.com/immutable-js/immutable-js/pull/1991) by [@mrazauskas](https://github.com/mrazauskas).
+  Special thanks to [@arnfaldur](https://github.com/arnfaldur) that migrated every type tests to tsd just before that.
+- [internal] Upgrade to rollup 3.x [#1965](https://github.com/immutable-js/immutable-js/pull/1965) by [@jdeniau](https://github.com/jdeniau)
+- [internal] upgrade tooling (TS, eslint) and documentation packages: #1971, #1972, #1973, #1974, #1975, #1976, #1977, #1978, #1979, #1980, #1981
+
 ## [4.3.7] - 2024-07-22
 
 - Fix issue with slice negative of filtered sequence [#2006](https://github.com/immutable-js/immutable-js/pull/2006) by [@jdeniau](https://github.com/jdeniau)

diff --git a/README.md b/README.md
@@ -86,7 +86,7 @@ map1.get('b') + ' vs. ' + map2.get('b'); // 2 vs. 50
 
 Immutable.js has no dependencies, which makes it predictable to include in a Browser.
 
-It's highly recommended to use a module bundler like [webpack](https://webpack.github.io/),
+It's highly recommended to use a module bundler like [webpack](https://webpack.js.org/),
 [rollup](https://rollupjs.org/), or
 [browserify](https://browserify.org/). The `immutable` npm module works
 without any additional consideration. All examples throughout the documentation
@@ -152,9 +152,9 @@ via relative path to the type definitions at the top of your file.
 
 ```js
 ///<reference path='./node_modules/immutable/dist/immutable.d.ts'/>
-import Immutable from 'immutable';
-var map1: Immutable.Map<string, number>;
-map1 = Immutable.Map({ a: 1, b: 2, c: 3 });
+import { Map } from 'immutable';
+var map1: Map<string, number>;
+map1 = Map({ a: 1, b: 2, c: 3 });
 var map2 = map1.set('b', 50);
 map1.get('b'); // 2
 map2.get('b'); // 50

diff --git a/__tests__/Comparator.ts b/__tests__/Comparator.ts
@@ -6,11 +6,12 @@ const expectedSortedNumbers: readonly number[] = [
   7, 95, 90, 92, 3, 5, 9, 4, 6, 10, 12,
 ];
 
+/* eslint-disable no-else-return */
 const testComparator: Comparator<number> = (left, right) => {
   //The number 7 always goes first...
-  if (left == 7) {
+  if (left === 7) {
     return PairSorting.LeftThenRight;
-  } else if (right == 7) {
+  } else if (right === 7) {
     return PairSorting.RightThenLeft;
   }
 
@@ -31,6 +32,7 @@ const testComparator: Comparator<number> = (left, right) => {
   //...and, finally, sort the numbers of each subgroup in ascending order.
   return left - right;
 };
+/* eslint-enable no-else-return */
 
 describe.each([
   ['List', List],

diff --git a/__tests__/Conversion.ts b/__tests__/Conversion.ts
@@ -1,10 +1,7 @@
 import { fromJS, is, List, Map, OrderedMap, Record } from 'immutable';
-
 import * as jasmineCheck from 'jasmine-check';
-jasmineCheck.install();
 
-// Symbols
-declare function Symbol(name: string): any;
+jasmineCheck.install();
 
 describe('Conversion', () => {
   // Note: order of keys based on Map's hashing order
@@ -107,7 +104,9 @@ describe('Conversion', () => {
   });
 
   it('Throws when provided circular reference', () => {
-    const o = { a: { b: { c: null as any } } };
+    type OType = { a: { b: { c: OType | null } } };
+
+    const o: OType = { a: { b: { c: null } } };
     o.a.b.c = o;
     expect(() => fromJS(o)).toThrow(
       'Cannot convert circular structure to Immutable'
@@ -117,7 +116,8 @@ describe('Conversion', () => {
   it('Converts deep JSON with custom conversion', () => {
     const seq = fromJS(js, function (key, sequence) {
       if (key === 'point') {
-        return new Point(sequence as any);
+        // @ts-expect-error -- to convert to real typing
+        return new Point(sequence);
       }
       return Array.isArray(this[key])
         ? sequence.toList()
@@ -128,7 +128,8 @@ describe('Conversion', () => {
   });
 
   it('Converts deep JSON with custom conversion including keypath if requested', () => {
-    const paths: Array<any> = [];
+    const paths: Array<Array<string | number> | undefined> = [];
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const seq1 = fromJS(js, function (key, sequence, keypath) {
       expect(arguments.length).toBe(3);
       paths.push(keypath);
@@ -147,6 +148,8 @@ describe('Conversion', () => {
       ['point'],
       ['list'],
     ]);
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const seq2 = fromJS(js, function (key, sequence) {
       expect(arguments[2]).toBe(undefined);
     });