feat(perf): up performance from quadratic to linear time (#77)

.github/workflows/gh-packages-publish.yml

@@ -25,7 +25,7 @@ jobs:
         run: npm run lint
 
       - name: Test
-        run: npm run test --ci --coverage --maxWorkers=2
+        run: npm run test:ci
 
       - name: Build
         run: npm run build

.github/workflows/main.yml

@@ -29,7 +29,7 @@ jobs:
         run: npm run lint
 
       - name: Test
-        run: npm run test --ci --coverage --maxWorkers=2
+        run: npm run test:ci
 
       - name: Build
         run: npm run build

.github/workflows/npm-publish.yml

@@ -29,7 +29,7 @@ jobs:
         run: npm run lint
 
       - name: Test
-        run: npm run test --ci --coverage --maxWorkers=2
+        run: npm run test:ci
 
       - name: Build
         run: npm run build

.github/workflows/pull-request.yml

@@ -12,7 +12,7 @@ jobs:
       - name: Lint
         run: npm run lint
       - name: Test
-        run: npm run test --ci --coverage --maxWorkers=2
+        run: npm run test:ci
       - name: Build
         run: npm run build
       - name: size-limit-action

README.md

@@ -17,34 +17,51 @@ const listGroup = [
 const byAge = createGroup('age');
 
 byAge(listGroup);
+/**
+ *  {
+ *    entities: {
+ *      '20': [
+ *        {
+ *          age: 20,
+ *          name: 'Dan',
+ *        },
+ *      ],
+ *      '22': [
+ *        {
+ *          age: 22,
+ *          name: 'Woofer',
+ *        },
+ *      ],
+ *      '5': [
+ *        {
+ *          age: 5,
+ *          name: 'Dan',
+ *        },
+ *        {
+ *          age: 5,
+ *          name: 'Puppy',
+ *        },
+ *      ],
+ *    },
+ *    ids: [5, 22, 20],
+ *  }
+ */
 
-/** yields **/
-
-{
-  entities: {
-    '20': [
-      {
-        age: 20,
-        name: 'Dan',
-      },
-    ],
-    '22': [
-      {
-        age: 22,
-        name: 'Woofer',
-      },
-    ],
-    '5': [
-      {
-        age: 5,
-        name: 'Dan',
-      },
-      {
-        age: 5,
-        name: 'Puppy',
-      },
-    ],
-  },
-  ids: [5, 22, 20],
-}
+const byName = createGroup('name');
+
+byName(listGroup);
+
+/**
+ * {
+ *   entities: {
+ *     Dan: [
+ *       { name: 'Dan', age: 5 },
+ *       { name: 'Dan', age: 20 }
+ *     ],
+ *     Puppy: [ { name: 'Puppy', age: 5 } ],
+ *     Woofer: [ { name: 'Woofer', age: 22 } ]
+ *   },
+ *   ids: [ 'Dan', 'Puppy', 'Woofer' ]
+ *  }
+ */
 ```

package.json

@@ -33,7 +33,9 @@
     "release": "scripty",
     "size": "scripty",
     "size:analyze": "scripty",
-    "test": "scripty"
+    "test": "scripty",
+    "test:ci": "scripty",
+    "test:watch": "scripty"
   },
   "config": {
     "commitizen": {
@@ -99,4 +101,4 @@
       "limit": "1 KB"
     }
   ]
-}
+}

scripts/build/index.sh

@@ -1,7 +1,6 @@
 
 #!/usr/bin/env sh
-source ./scripts/shared.sh
 
 npm run clean
-echo "┏━━━ 📦 $PACKAGE_NAME: build ━━━━━━━━━━━━━━━━━━━"
+echo "┏━━━ 📦 build ━━━━━━━━━━━━━━━━━━━"
 tsc && rollup -c

scripts/clean/index.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-source ./scripts/shared.sh
 
-echo "┏━━━ 🧹 $PACKAGE_NAME: clean  ━━━━━━━━━━━━━━━━━━━"
+echo "┏━━━ 🧹 clean  ━━━━━━━━━━━━━━━━━━━"
 rimraf ./dist

scripts/lint/index.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-source ./scripts/shared.sh
 
-echo "┏━━━ 🕵️‍♀️ $PACKAGE_NAME lint ━━━━━━━"
+echo "┏━━━ 🕵️‍♀️ lint ━━━━━━━"
 eslint src --quiet --ext .ts 

scripts/size/analyze.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-source ./scripts/shared.sh
 
-echo "┏━━━ 🛍️ $PACKAGE_NAME size:analyze ━━━━━━━"
+echo "┏━━━ 🛍️ size:analyze ━━━━━━━"
 size-limit --why

scripts/size/index.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env sh
-source ./scripts/shared.sh
 
-echo "┏━━━ 🛍️ $PACKAGE_NAME: size ━━━━━━━"
+echo "┏━━━ 🛍️ size ━━━━━━━"
 size-limit

scripts/test/ci.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+node --expose-gc ./node_modules/.bin/jest --runInBand --coverage --verbose --forceExit --detectOpenHandles --ci

scripts/test/index.sh

@@ -1,3 +1,3 @@
 #!/usr/bin/env sh
 
-npx jest
+npx jest --runInBand --coverage --verbose --forceExit --detectOpenHandles

scripts/test/watch.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+npx jest --runInBand --watchAll --forceExit --detectOpenHandles

src/test-helpers/__fixtures__/TEN_ITEMS.ts

@@ -0,0 +1,12 @@
+export const TEN_ITEMS = [
+  { name: 'Dan', age: 5 },
+  { name: 'Puppy', age: 5 },
+  { name: 'Woofer', age: 22 },
+  { name: 'Dan', age: 20 },
+  { name: 'Cat', age: 11 },
+  { name: 'Dog', age: 2 },
+  { name: 'Pig', age: 20 },
+  { name: 'Cow', age: 6 },
+  { name: 'Horse', age: 9 },
+  { name: 'Pig', age: 2 },
+];

src/test-helpers/__fixtures__/index.ts

@@ -0,0 +1 @@
+export * from './TEN_ITEMS';

src/test-helpers/getNItems/getNItems.ts

@@ -0,0 +1,7 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { TEN_ITEMS } from '../__fixtures__';
+
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+export const getNItems = (count: number) =>
+  Array.from({ length: count / TEN_ITEMS.length }).flatMap(() => TEN_ITEMS);

src/test-helpers/getNItems/index.ts

@@ -0,0 +1 @@
+export * from './getNItems';

src/test-helpers/index.ts

@@ -0,0 +1,3 @@
+export * from './getNItems';
+export * from './logPerformance';
+export * from './__fixtures__';

src/test-helpers/logPerformance/index.ts

@@ -0,0 +1 @@
+export * from './logPerformance';

src/test-helpers/logPerformance/logPerformance.ts

@@ -0,0 +1,16 @@
+export const logPerformance = (opts: {
+  name: string;
+  fn: () => void;
+  assertion: (actual: number) => void;
+}) => {
+  const { name, fn, assertion } = opts;
+
+  const start = performance.now();
+  fn();
+  const end = performance.now();
+
+  const duration = end - start;
+  assertion(duration);
+
+  console.table({ [name]: `${duration}ms` });
+};

src/typings/types.ts

@@ -1,6 +1,6 @@
 export type ObjectKey = string | number | symbol;
 
 export type EntityDict<Entity, Key extends ObjectKey> = {
-  entities: Record<Key, Entity | undefined>;
+  entities: Record<Key, Entity[] | undefined>;
   ids: Key[];
 };

src/utils/_internal/groupBy.ts → src/utils/__internal__/groupBy.slow.ts

@@ -1,6 +1,9 @@
 import type { EntityDict } from '../../typings';
 
-export const groupBy = <K extends keyof T, T extends Record<K, T[K]>>(
+/**
+ * O(n^2) implementation of groupBy
+ */
+export const groupBySlow = <K extends keyof T, T extends Record<K, T[K]>>(
   key: K,
   items: T[]
 ) =>

src/utils/__internal__/groupBy.ts

@@ -0,0 +1,23 @@
+import type { EntityDict } from '../../typings';
+
+/**
+ * O(n) implementation of groupBy
+ */
+export const groupBy = <K extends keyof T, T extends Record<K, T[K]>>(
+  key: K,
+  items: T[]
+) => {
+  const result = { entities: {}, ids: [] } as EntityDict<T, T[K]>;
+
+  for (let i = 0; i < items.length; i++) {
+    if (result.entities[items[i][key]]) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      result.entities[items[i][key]]!.push(items[i]);
+    } else {
+      result.entities[items[i][key]] = [items[i]];
+      result.ids.push(items[i][key]);
+    }
+  }
+
+  return result;
+};

src/utils/createGroup/createGroup.perf.spec.ts

@@ -0,0 +1,72 @@
+import { getNItems, logPerformance } from '../../test-helpers';
+import { createGroup } from './createGroup';
+
+const ONE_THOUSAND_ITEMS = getNItems(1000);
+const TEN_THOUSAND_ITEMS = getNItems(10_000);
+const ONE_MILLION_ITEMS = getNItems(1_000_000);
+const TEN_MILLION_ITEMS = getNItems(10_000_000);
+
+const TEN_MILLISECONDS = 10;
+const ONE_HUNDRED_MILLISECONDS = 100;
+const FIVE_HUNDRED_MILLISECONDS = 500;
+const ONE_SECOND = 1000;
+
+const byAge = createGroup('age');
+
+describe('createGroup - performance', () => {
+  it('[One thousand items]: executes in less than 10ms', (done) => {
+    expect(ONE_THOUSAND_ITEMS.length).toBe(1000);
+
+    logPerformance({
+      name: 'One thousand items',
+      fn: () => byAge(ONE_THOUSAND_ITEMS),
+      assertion: (milliseconds) => {
+        expect(milliseconds).toBeLessThan(TEN_MILLISECONDS);
+        global.gc?.();
+        done();
+      },
+    });
+  });
+
+  test('[Ten thousand items]: executes in less than 100ms', (done) => {
+    expect(TEN_THOUSAND_ITEMS.length).toBe(10_000);
+
+    logPerformance({
+      name: 'Ten thousand items',
+      fn: () => byAge(TEN_THOUSAND_ITEMS),
+      assertion: (milliseconds) => {
+        expect(milliseconds).toBeLessThan(ONE_HUNDRED_MILLISECONDS);
+        global.gc?.();
+        done();
+      },
+    });
+  });
+  it('[One million items]: executes in less than 500ms', (done) => {
+    expect(ONE_MILLION_ITEMS.length).toBe(1_000_000);
+
+    logPerformance({
+      name: 'One Million Items',
+      fn: () => byAge(ONE_MILLION_ITEMS),
+      assertion: (actual) => {
+        expect(actual).toBeLessThan(FIVE_HUNDRED_MILLISECONDS);
+        global.gc?.();
+        done();
+      },
+    });
+  });
+
+  test('[Ten million items]: executes in less than 1s', (done) => {
+    expect(TEN_MILLION_ITEMS.length).toBe(10_000_000);
+
+    logPerformance({
+      name: 'Ten Million Items',
+      fn: () => byAge(TEN_MILLION_ITEMS),
+      assertion: (actual) => {
+        expect(actual).toBeLessThan(ONE_SECOND);
+        global.gc?.();
+        done();
+      },
+    });
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  });
+});

src/utils/createGroup/createGroup.spec.ts

@@ -6,10 +6,11 @@ const listGroup = [
   { name: 'Woofer', age: 22 },
   { name: 'Dan', age: 20 },
 ];
+
 describe('createGroup', () => {
   it('one', () => {
-    const byId = createGroup('age');
-    expect(byId(listGroup)).toEqual({
+    const byAge = createGroup('age');
+    expect(byAge(listGroup)).toEqual({
       entities: {
         '20': [
           {

src/utils/createGroup/createGroup.ts

@@ -1,5 +1,5 @@
 import type { EntityDict, ObjectKey } from '../../typings';
-import { groupBy } from '../_internal';
+import { groupBy } from '../__internal__';
 
 export function createGroup<K extends ObjectKey>(key: K) {
   return function groupList<T extends Record<K, T[K]>>(