Merge remote-tracking branch 'origin/main' into jd-feat-tsMapObject

Author: jdeniau

.github/workflows/release.yml

@@ -1,6 +1,7 @@
 name: Release
 
 on:
+  workflow_dispatch: ~
   release:
     types: [published]
 

CHANGELOG.md

@@ -6,7 +6,7 @@ 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).
 Dates are formatted as YYYY-MM-DD.
 
-## [Unreleased]
+## Unreleased
 
 ### Changed
 
@@ -38,7 +38,6 @@ 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:
@@ -57,7 +56,6 @@ type MyMapType = {
   1: string | null;
   optionalProperty?: string;
 };
-
 const m = Map<MyMapType>({ length: 3, 1: 'one' });
 ```
 
@@ -79,6 +77,30 @@ Map<{ a?: string }>({ a: 'a' }).delete('a'); // you can only delete an optional
 
 For now, only `get`, `getIn`, `set`, `update`, `delete` and `remove` 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.
 
+
+
+## [4.2.4] - 2023-02-06
+
+- Improve type infererence for from JS by [KSXGitHub](https://github.com/KSXGitHub) [#1927](https://github.com/immutable-js/immutable-js/pull/1927)
+
+## [4.2.3] - 2023-02-02
+
+- TypeScript: `groupBy` return either a `Map` or an `OrderedMap`: make the type more precise than base `Collection` [#1924](https://github.com/immutable-js/immutable-js/pull/1924)
+
+## [4.2.2] - 2023-01-02
+
+- [Flow] Add type for `partition` method [#1920](https://github.com/immutable-js/immutable-js/pull/1920) by [Dagur](https://github.com/Dagur)
+
+## [4.2.1] - 2022-12-23
+
+- [Typescript] rollback some of the change on `toJS` to avoir circular reference
+
+## [4.2.0] - 2022-12-22
+
+- [TypeScript] Better type for toJS [#1917](https://github.com/immutable-js/immutable-js/pull/1917) by [jdeniau](https://github.com/jdeniau)
+  - [TS Minor Break] tests are ran with TS > 4.5 only. It was tested with TS > 2.1 previously, but we want to level up TS types with recent features. TS 4.5 has been released more than one year before this release. If it does break your implementation (it might not), you should probably consider upgrading to the latest TS version.
+- Added a `partition` method to all containers [#1916](https://github.com/immutable-js/immutable-js/pull/1916) by [johnw42](https://github.com/johnw42)
+
 ## [4.1.0] - 2022-05-23
 
 - Accept Symbol as Map key. [#1859](https://github.com/immutable-js/immutable-js/pull/1859) by [jdeniau](https://github.com/jdeniau)

README.md

@@ -637,6 +637,46 @@ Range(1, Infinity)
 // 1006008
 ```
 
+## Comparison of filter(), groupBy(), and partition()
+
+The `filter()`, `groupBy()`, and `partition()` methods are similar in that they
+all divide a collection into parts based on applying a function to each element.
+All three call the predicate or grouping function once for each item in the
+input collection.  All three return zero or more collections of the same type as
+their input.  The returned collections are always distinct from the input
+(according to `===`), even if the contents are identical.
+
+Of these methods, `filter()` is the only one that is lazy and the only one which
+discards items from the input collection. It is the simplest to use, and the
+fact that it returns exactly one collection makes it easy to combine with other
+methods to form a pipeline of operations.
+
+The `partition()` method is similar to an eager version of `filter()`, but it
+returns two collections; the first contains the items that would have been
+discarded by `filter()`, and the second contains the items that would have been
+kept.  It always returns an array of exactly two collections, which can make it
+easier to use than `groupBy()`.  Compared to making two separate calls to
+`filter()`, `partition()` makes half as many calls it the predicate passed to
+it.
+
+The `groupBy()` method is a more generalized version of `partition()` that can
+group by an arbitrary function rather than just a predicate.  It returns a map
+with zero or more entries, where the keys are the values returned by the
+grouping function, and the values are nonempty collections of the corresponding
+arguments.  Although `groupBy()` is more powerful than `partition()`, it can be
+harder to use because it is not always possible predict in advance how many
+entries the returned map will have and what their keys will be.
+
+| Summary                       | `filter` | `partition` | `groupBy`      |
+|:------------------------------|:---------|:------------|:---------------|
+| ease of use                   | easiest  | moderate    | hardest        |
+| generality                    | least    | moderate    | most           |
+| laziness                      | lazy     | eager       | eager          |
+| # of returned sub-collections | 1        | 2           | 0 or more      |
+| sub-collections may be empty  | yes      | yes         | no             |
+| can discard items             | yes      | no          | no             |
+| wrapping container            | none     | array       | Map/OrderedMap |
+
 ## Additional Tools and Resources
 
 - [Atom-store](https://github.com/jameshopkins/atom-store/)

__tests__/KeyedSeq.ts

@@ -32,6 +32,23 @@ describe('KeyedSeq', () => {
       [3, 26],
       [4, 28],
     ]);
+    const [indexed0, indexed1] = seq
+      .partition(isEven)
+      .map(part => part.skip(10).take(5));
+    expect(indexed0.entrySeq().toArray()).toEqual([
+      [0, 21],
+      [1, 23],
+      [2, 25],
+      [3, 27],
+      [4, 29],
+    ]);
+    expect(indexed1.entrySeq().toArray()).toEqual([
+      [0, 20],
+      [1, 22],
+      [2, 24],
+      [3, 26],
+      [4, 28],
+    ]);
 
     // Where Keyed Sequences maintain keys.
     const keyed = seq.toKeyedSeq();
@@ -43,6 +60,23 @@ describe('KeyedSeq', () => {
       [26, 26],
       [28, 28],
     ]);
+    const [keyed0, keyed1] = keyed
+      .partition(isEven)
+      .map(part => part.skip(10).take(5));
+    expect(keyed0.entrySeq().toArray()).toEqual([
+      [21, 21],
+      [23, 23],
+      [25, 25],
+      [27, 27],
+      [29, 29],
+    ]);
+    expect(keyed1.entrySeq().toArray()).toEqual([
+      [20, 20],
+      [22, 22],
+      [24, 24],
+      [26, 26],
+      [28, 28],
+    ]);
   });
 
   it('works with reverse', () => {

__tests__/List.ts

@@ -569,6 +569,17 @@ describe('List', () => {
     expect(r.toArray()).toEqual(['b', 'd', 'f']);
   });
 
+  it('partitions values', () => {
+    const v = List.of('a', 'b', 'c', 'd', 'e', 'f');
+    const r = v
+      .partition((value, index) => index % 2 === 1)
+      .map(part => part.toArray());
+    expect(r).toEqual([
+      ['a', 'c', 'e'],
+      ['b', 'd', 'f'],
+    ]);
+  });
+
   it('filters values based on type', () => {
     class A {}
     class B extends A {
@@ -588,6 +599,29 @@ describe('List', () => {
     expect(l2.every(v => v instanceof C)).toBe(true);
   });
 
+  it('partitions values based on type', () => {
+    class A {}
+    class B extends A {
+      b(): void {
+        return;
+      }
+    }
+    class C extends A {
+      c(): void {
+        return;
+      }
+    }
+    const l1 = List<A>([new B(), new C(), new B(), new C()]);
+    // tslint:disable-next-line:arrow-parens
+    const [la, lc]: [List<A>, List<C>] = l1.partition(
+      (v): v is C => v instanceof C
+    );
+    expect(la.size).toEqual(2);
+    expect(la.some(v => v instanceof C)).toBe(false);
+    expect(lc.size).toEqual(2);
+    expect(lc.every(v => v instanceof C)).toBe(true);
+  });
+
   it('reduces values', () => {
     const v = List.of(1, 10, 100);
     const r = v.reduce<number>((reduction, value) => reduction + value);

__tests__/Map.ts

@@ -304,6 +304,17 @@ describe('Map', () => {
     expect(r.toObject()).toEqual({ b: 2, d: 4, f: 6 });
   });
 
+  it('partitions values', () => {
+    const m = Map({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
+    const r = m
+      .partition(value => value % 2 === 1)
+      .map(part => part.toObject());
+    expect(r).toEqual([
+      { b: 2, d: 4, f: 6 },
+      { a: 1, c: 3, e: 5 },
+    ]);
+  });
+
   it('derives keys', () => {
     const v = Map({ a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 });
     expect(v.keySeq().toArray()).toEqual(['a', 'b', 'c', 'd', 'e', 'f']);

__tests__/MultiRequire.js

@@ -5,7 +5,7 @@ jest.resetModules();
 const Immutable2 = require('../src/Immutable');
 
 describe('MultiRequire', () => {
-  it('might require two different instances of Immutable', () => {
+  it.skip('might require two different instances of Immutable', () => {
     expect(Immutable1).not.toBe(Immutable2);
     expect(Immutable1.Map({ a: 1 }).toJS()).toEqual({ a: 1 });
     expect(Immutable2.Map({ a: 1 }).toJS()).toEqual({ a: 1 });

__tests__/Range.ts

@@ -148,6 +148,16 @@ describe('Range', () => {
     expect(r.toArray()).toEqual([0, 2, 4, 6, 8]);
   });
 
+  it('partitions values', () => {
+    const r = Range(0, 10)
+      .partition(v => v % 2 === 0)
+      .map(part => part.toArray());
+    expect(r).toEqual([
+      [1, 3, 5, 7, 9],
+      [0, 2, 4, 6, 8],
+    ]);
+  });
+
   it('reduces values', () => {
     const v = Range(0, 10, 2);
     const r = v.reduce<number>((a, b) => a + b, 0);

__tests__/Set.ts

@@ -131,6 +131,11 @@ describe('Set', () => {
     expect(Set.intersect([])).toBe(Set());
   });
 
+  it('concatenates strings using union', () => {
+    const s = Set(['one', 'two']);
+    expect(s.union('three').toArray()).toEqual(['one', 'two', 'three']);
+  });
+
   it('iterates values', () => {
     const s = Set([1, 2, 3]);
     const iterator = jest.fn();

__tests__/groupBy.ts

@@ -1,6 +1,53 @@
-import { Collection, Map, Seq } from 'immutable';
+import {
+  Collection,
+  Map,
+  Seq,
+  isOrdered,
+  OrderedMap,
+  List,
+  OrderedSet,
+  Set,
+  Stack,
+  Record,
+} from 'immutable';
 
 describe('groupBy', () => {
+  it.each`
+    constructor   | constructorIsOrdered | isObject
+    ${Collection} | ${true}              | ${false}
+    ${List}       | ${true}              | ${false}
+    ${Seq}        | ${true}              | ${false}
+    ${Set}        | ${false}             | ${false}
+    ${Stack}      | ${true}              | ${false}
+    ${OrderedSet} | ${true}              | ${false}
+    ${Map}        | ${false}             | ${true}
+    ${OrderedMap} | ${true}              | ${true}
+  `(
+    'groupBy returns ordered or unordered of the base type is ordered or not: $constructor.name',
+    ({ constructor, constructorIsOrdered, isObject }) => {
+      const iterableConstructor = ['a', 'b', 'a', 'c'];
+      const objectConstructor = { a: 1, b: 2, c: 3, d: 1 };
+
+      const col = constructor(
+        isObject ? objectConstructor : iterableConstructor
+      );
+
+      const grouped = col.groupBy(v => v);
+
+      // all groupBy should be instance of Map
+      expect(grouped).toBeInstanceOf(Map);
+
+      // ordered objects should be instance of OrderedMap
+      expect(isOrdered(col)).toBe(constructorIsOrdered);
+      expect(isOrdered(grouped)).toBe(constructorIsOrdered);
+      if (constructorIsOrdered) {
+        expect(grouped).toBeInstanceOf(OrderedMap);
+      } else {
+        expect(grouped).not.toBeInstanceOf(OrderedMap);
+      }
+    }
+  );
+
   it('groups keyed sequence', () => {
     const grouped = Seq({ a: 1, b: 2, c: 3, d: 4 }).groupBy(x => x % 2);
     expect(grouped.toJS()).toEqual({ 1: { a: 1, c: 3 }, 0: { b: 2, d: 4 } });
@@ -14,53 +61,38 @@ describe('groupBy', () => {
   });
 
   it('groups indexed sequence', () => {
-    expect(
-      Seq([1, 2, 3, 4, 5, 6])
-        .groupBy(x => x % 2)
-        .toJS()
-    ).toEqual({ 1: [1, 3, 5], 0: [2, 4, 6] });
+    const group = Seq([1, 2, 3, 4, 5, 6]).groupBy(x => x % 2);
+
+    expect(group.toJS()).toEqual({ 1: [1, 3, 5], 0: [2, 4, 6] });
   });
 
   it('groups to keys', () => {
-    expect(
-      Seq([1, 2, 3, 4, 5, 6])
-        .groupBy(x => (x % 2 ? 'odd' : 'even'))
-        .toJS()
-    ).toEqual({ odd: [1, 3, 5], even: [2, 4, 6] });
+    const group = Seq([1, 2, 3, 4, 5, 6]).groupBy(x =>
+      x % 2 ? 'odd' : 'even'
+    );
+    expect(group.toJS()).toEqual({ odd: [1, 3, 5], even: [2, 4, 6] });
   });
 
   it('groups indexed sequences, maintaining indicies when keyed sequences', () => {
-    expect(
-      Seq([1, 2, 3, 4, 5, 6])
-        .groupBy(x => x % 2)
-        .toJS()
-    ).toEqual({ 1: [1, 3, 5], 0: [2, 4, 6] });
-    expect(
-      Seq([1, 2, 3, 4, 5, 6])
-        .toKeyedSeq()
-        .groupBy(x => x % 2)
-        .toJS()
-    ).toEqual({ 1: { 0: 1, 2: 3, 4: 5 }, 0: { 1: 2, 3: 4, 5: 6 } });
-  });
+    const group = Seq([1, 2, 3, 4, 5, 6]).groupBy(x => x % 2);
 
-  it('has groups that can be mapped', () => {
-    expect(
-      Seq([1, 2, 3, 4, 5, 6])
-        .groupBy(x => x % 2)
-        .map(group => group.map(value => value * 10))
-        .toJS()
-    ).toEqual({ 1: [10, 30, 50], 0: [20, 40, 60] });
+    expect(group.toJS()).toEqual({ 1: [1, 3, 5], 0: [2, 4, 6] });
+
+    const keyedGroup = Seq([1, 2, 3, 4, 5, 6])
+      .toKeyedSeq()
+      .groupBy(x => x % 2);
+
+    expect(keyedGroup.toJS()).toEqual({
+      1: { 0: 1, 2: 3, 4: 5 },
+      0: { 1: 2, 3: 4, 5: 6 },
+    });
   });
 
-  it('returns an ordered map from an ordered collection', () => {
-    const seq = Seq(['Z', 'Y', 'X', 'Z', 'Y', 'X']);
-    expect(Collection.isOrdered(seq)).toBe(true);
-    const seqGroups = seq.groupBy(x => x);
-    expect(Collection.isOrdered(seqGroups)).toBe(true);
+  it('has groups that can be mapped', () => {
+    const mappedGroup = Seq([1, 2, 3, 4, 5, 6])
+      .groupBy(x => x % 2)
+      .map(group => group.map(value => value * 10));
 
-    const map = Map({ x: 1, y: 2 });
-    expect(Collection.isOrdered(map)).toBe(false);
-    const mapGroups = map.groupBy(x => x);
-    expect(Collection.isOrdered(mapGroups)).toBe(false);
+    expect(mappedGroup.toJS()).toEqual({ 1: [10, 30, 50], 0: [20, 40, 60] });
   });
 });