@valliappan-periannan/pagination-sorter 0.2.1

package/README.md

@@ -0,0 +1,136 @@
+# @valliappan-periannan/pagination-sorter
+
+[![CI](https://github.com/Valliappan21/pagination-sorter/actions/workflows/ci.yml/badge.svg)](https://github.com/Valliappan21/pagination-sorter/actions/workflows/ci.yml)
+
+Small JavaScript utility for deriving pagination metadata from an existing list,
+a new list, and a page size.
+
+## Installation
+
+```bash
+npm install @valliappan-periannan/pagination-sorter
+```
+
+## Usage
+
+```js
+const { sortPagination } = require('@valliappan-periannan/pagination-sorter');
+
+const pagination = sortPagination({
+  existingList: [{ id: 1 }, { id: 2 }, { id: 3 }],
+  newList: [{ id: 4 }, { id: 5 }],
+  numberOfItems: 2,
+  filterField: 'id'
+});
+
+console.log(pagination);
+```
+
+## Try Now
+
+Run the local example:
+
+```bash
+npm run try-now
+```
+
+The example uses these defined lists from `examples/try-now.js`:
+
+```js
+const data = {
+  existingList: [
+    { id: 1, name: 'Alpha' },
+    { id: 2, name: 'Beta' },
+    { id: 3, name: 'Gamma' },
+    { id: 4, name: 'Delta' }
+  ],
+  newList: [
+    { id: 4, name: 'Delta duplicate' },
+    { id: 5, name: 'Epsilon' },
+    { id: 6, name: 'Zeta' },
+    { id: 7, name: 'Eta' }
+  ],
+  numberOfItems: 3,
+  filterField: 'id'
+};
+```
+
+Edit the lists, `numberOfItems`, or `filterField` in `examples/try-now.js`, then rerun
+`npm run try-now` to see the updated pagination result.
+
+## Benchmark
+
+Run the 10 lakh records benchmark:
+
+```bash
+npm run benchmark
+```
+
+The benchmark generates 1,000,000 records, validates the pagination result, and
+prints elapsed time and memory usage. It reports timing only, so performance
+differences between machines do not fail the run.
+
+Generate a markdown benchmark report:
+
+```bash
+npm run benchmark:report
+```
+
+## Latest Benchmark Report
+
+The GitHub Actions workflow generates a benchmark report for 10 lakh records on
+every push and pull request.
+
+View the latest report from the CI workflow runs:
+
+https://github.com/Valliappan21/pagination-sorter/actions/workflows/ci.yml
+
+Each run includes the benchmark in the job summary and uploads
+`benchmark-report.md` as the `benchmark-report` artifact.
+
+## Release
+
+Publishing to npm runs through GitHub Actions when a GitHub Release is
+published. The repository must have an `NPM_TOKEN` secret with permission to
+publish `@valliappan-periannan/pagination-sorter`.
+
+The publish workflow validates tests, generates the benchmark report, verifies
+package contents with `npm pack --dry-run`, and publishes with
+`npm publish --access public`.
+
+## API
+
+### `sortPagination(data)`
+
+Accepts one object:
+
+```js
+{
+  existingList: [],
+  newList: [],
+  numberOfItems: 10,
+  filterField: 'id'
+}
+```
+
+Returns:
+
+```js
+{
+  combinedList,
+  currentPageItems,
+  totalItems,
+  pageSize,
+  totalPages,
+  currentPage,
+  nextPage,
+  previousPage,
+  hasNextPage,
+  hasPreviousPage
+}
+```
+
+`numberOfItems` is treated as the page size. `filterField` is mandatory and
+must be the name of a field whose value is a string or number on every list
+item. `combinedList` keeps the first item for each field value, checking
+`existingList` first and then adding only unique items from `newList`.

package/benchmark/report.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const { performance } = require('node:perf_hooks');
+const packageJson = require('../package.json');
+const { sortPagination } = require('../index');
+
+const TOTAL_RECORDS = 1000000;
+const EXISTING_RECORDS = 750000;
+const NEW_RECORDS = TOTAL_RECORDS - EXISTING_RECORDS;
+const PAGE_SIZE = 1000;
+const FILTER_FIELD = 'id';
+
+function createRecords(length, offset = 0) {
+  return Array.from({ length }, (_, index) => ({ id: offset + index + 1 }));
+}
+
+function formatBytes(bytes) {
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+
+const existingList = createRecords(EXISTING_RECORDS);
+const newList = createRecords(NEW_RECORDS, EXISTING_RECORDS);
+
+const start = performance.now();
+const result = sortPagination({
+  existingList,
+  newList,
+  numberOfItems: PAGE_SIZE,
+  filterField: FILTER_FIELD
+});
+const duration = performance.now() - start;
+
+assert.equal(result.totalItems, TOTAL_RECORDS);
+assert.equal(result.totalPages, 1000);
+assert.equal(result.currentPage, 751);
+assert.equal(result.previousPage, 750);
+assert.equal(result.nextPage, 752);
+assert.equal(result.hasPreviousPage, true);
+assert.equal(result.hasNextPage, true);
+assert.equal(result.currentPageItems[0].id, 750001);
+assert.equal(result.currentPageItems[result.currentPageItems.length - 1].id, 751000);
+
+const memory = process.memoryUsage();
+const report = `# Benchmark Report
+
+## ${packageJson.name}
+
+| Metric | Value |
+| --- | --- |
+| Benchmark | 10 lakh records |
+| Node.js | ${process.version} |
+| Platform | ${os.platform()} ${os.release()} |
+| Total records | ${TOTAL_RECORDS.toLocaleString('en-US')} |
+| Existing records | ${EXISTING_RECORDS.toLocaleString('en-US')} |
+| New records | ${NEW_RECORDS.toLocaleString('en-US')} |
+| Page size | ${PAGE_SIZE.toLocaleString('en-US')} |
+| Filter field | ${FILTER_FIELD} |
+| Total pages | ${result.totalPages.toLocaleString('en-US')} |
+| Current page | ${result.currentPage.toLocaleString('en-US')} |
+| Elapsed time | ${duration.toFixed(3)} ms |
+| Heap used | ${formatBytes(memory.heapUsed)} |
+| RSS | ${formatBytes(memory.rss)} |
+| Correctness | Passed |
+`;
+
+fs.writeFileSync('benchmark-report.md', report);
+console.log(report);

package/benchmark/ten-lakh-records.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const { performance } = require('node:perf_hooks');
+const { sortPagination } = require('../index');
+
+const TOTAL_RECORDS = 1000000;
+const EXISTING_RECORDS = 750000;
+const NEW_RECORDS = TOTAL_RECORDS - EXISTING_RECORDS;
+const PAGE_SIZE = 1000;
+
+function createRecords(length, offset = 0) {
+  return Array.from({ length }, (_, index) => ({ id: offset + index + 1 }));
+}
+
+function formatBytes(bytes) {
+  return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+
+const existingList = createRecords(EXISTING_RECORDS);
+const newList = createRecords(NEW_RECORDS, EXISTING_RECORDS);
+
+const start = performance.now();
+const result = sortPagination({
+  existingList,
+  newList,
+  numberOfItems: PAGE_SIZE,
+  filterField: 'id'
+});
+const duration = performance.now() - start;
+
+assert.equal(result.totalItems, TOTAL_RECORDS);
+assert.equal(result.totalPages, 1000);
+assert.equal(result.currentPage, 751);
+assert.equal(result.previousPage, 750);
+assert.equal(result.nextPage, 752);
+assert.equal(result.hasPreviousPage, true);
+assert.equal(result.hasNextPage, true);
+assert.equal(result.currentPageItems[0].id, 750001);
+assert.equal(result.currentPageItems[result.currentPageItems.length - 1].id, 751000);
+
+const memory = process.memoryUsage();
+
+console.log('Pagination benchmark: 10 lakh records');
+console.log(`Total records: ${result.totalItems}`);
+console.log(`Page size: ${result.pageSize}`);
+console.log(`Total pages: ${result.totalPages}`);
+console.log(`Current page: ${result.currentPage}`);
+console.log(`Elapsed time: ${duration.toFixed(3)} ms`);
+console.log(`Heap used: ${formatBytes(memory.heapUsed)}`);
+console.log(`RSS: ${formatBytes(memory.rss)}`);

package/examples/try-now.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { sortPagination } = require('../index');
+
+const data = {
+  existingList: [
+    { id: 1, name: 'Alpha' },
+    { id: 2, name: 'Beta' },
+    { id: 3, name: 'Gamma' },
+    { id: 4, name: 'Delta' }
+  ],
+  newList: [
+    { id: 4, name: 'Delta duplicate' },
+    { id: 5, name: 'Epsilon' },
+    { id: 6, name: 'Zeta' },
+    { id: 7, name: 'Eta' }
+  ],
+  numberOfItems: 3,
+  filterField: 'id'
+};
+
+const pagination = sortPagination(data);
+
+console.log(JSON.stringify(pagination, null, 2));

package/index.js

@@ -0,0 +1,135 @@
+'use strict';
+
+function assertArray(value, name) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${name} must be an array.`);
+  }
+}
+
+function assertPageSize(value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TypeError('numberOfItems must be a positive integer.');
+  }
+}
+
+function assertFilterField(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('filterField must be a non-empty string.');
+  }
+}
+
+function getPaginationItems(existingList, newList, filterField) {
+  const seenValues = new Set();
+  const combinedList = new Array(existingList.length + newList.length);
+  let writeIndex = 0;
+  let existingItemCount = 0;
+
+  for (let index = 0; index < existingList.length; index += 1) {
+    const item = existingList[index];
+
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TypeError(`existingList[${index}] must be an object.`);
+    }
+
+    const value = item[filterField];
+    const valueType = typeof value;
+
+    if (valueType !== 'string' && valueType !== 'number') {
+      throw new TypeError(
+        `existingList[${index}].${filterField} must be a string or number.`
+      );
+    }
+
+    if (!seenValues.has(value)) {
+      seenValues.add(value);
+      combinedList[writeIndex] = item;
+      writeIndex += 1;
+      existingItemCount += 1;
+    }
+  }
+
+  for (let index = 0; index < newList.length; index += 1) {
+    const item = newList[index];
+
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TypeError(`newList[${index}] must be an object.`);
+    }
+
+    const value = item[filterField];
+    const valueType = typeof value;
+
+    if (valueType !== 'string' && valueType !== 'number') {
+      throw new TypeError(
+        `newList[${index}].${filterField} must be a string or number.`
+      );
+    }
+
+    if (!seenValues.has(value)) {
+      seenValues.add(value);
+      combinedList[writeIndex] = item;
+      writeIndex += 1;
+    }
+  }
+
+  combinedList.length = writeIndex;
+  seenValues.clear();
+
+  return {
+    combinedList,
+    existingItemCount
+  };
+}
+
+function getCurrentPage(existingItemCount, totalPages, pageSize) {
+  if (totalPages === 0 || existingItemCount === 0) {
+    return 1;
+  }
+
+  const nextPage = Math.floor(existingItemCount / pageSize) + 1;
+  return Math.min(nextPage, totalPages);
+}
+
+function sortPagination(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new TypeError('data must be an object.');
+  }
+
+  const { existingList, newList, numberOfItems, filterField } = data;
+
+  assertArray(existingList, 'existingList');
+  assertArray(newList, 'newList');
+  assertPageSize(numberOfItems);
+  assertFilterField(filterField);
+
+  const paginationItems = getPaginationItems(existingList, newList, filterField);
+  const combinedList = paginationItems.combinedList;
+  const totalItems = combinedList.length;
+  const pageSize = numberOfItems;
+  const totalPages = Math.ceil(totalItems / pageSize);
+  const currentPage = getCurrentPage(
+    paginationItems.existingItemCount,
+    totalPages,
+    pageSize
+  );
+  const startIndex = (currentPage - 1) * pageSize;
+  const currentPageItems = combinedList.slice(startIndex, startIndex + pageSize);
+  const hasPreviousPage = currentPage > 1;
+  const hasNextPage = currentPage < totalPages;
+
+  return {
+    combinedList,
+    currentPageItems,
+    totalItems,
+    pageSize,
+    totalPages,
+    currentPage,
+    nextPage: hasNextPage ? currentPage + 1 : null,
+    previousPage: hasPreviousPage ? currentPage - 1 : null,
+    hasNextPage,
+    hasPreviousPage
+  };
+}
+
+module.exports = {
+  sortPagination
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@valliappan-periannan/pagination-sorter",
+  "version": "0.2.1",
+  "description": "Utility helper for deriving pagination metadata from existing and new lists.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "examples/**",
+    "benchmark/**"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "try-now": "node examples/try-now.js",
+    "benchmark": "node benchmark/ten-lakh-records.js",
+    "benchmark:report": "node benchmark/report.js"
+  },
+  "keywords": [
+    "pagination",
+    "list",
+    "metadata",
+    "utility"
+  ],
+  "author": "",
+  "license": "MIT"
+}