core-services-sdk 1.3.39 → 1.3.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.39",
+  "version": "1.3.41",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/mongodb/paginate.js

@@ -1,7 +1,7 @@
 import { ObjectId } from 'mongodb'
 
 /**
- * Pagination with SQL-like ascending/descending
+ * Pagination with SQL-like ascending/descending and total count
  *
  * @param {import('mongodb').Collection} collection
  * @param {Object} options
@@ -11,7 +11,7 @@ import { ObjectId } from 'mongodb'
  * @param {'asc'|'desc'} [options.order='asc']
  * @param {number} [options.limit=10]
  */
-export async function paginate(
+export async function paginateCursor(
   collection,
   {
     limit = 10,
@@ -25,24 +25,131 @@ export async function paginate(
   const query = { ...filter }
   const sort = { [cursorField]: order === 'asc' ? 1 : -1 }
 
+  // Cursor filtering
   if (cursor) {
     if (cursorField === '_id') {
       cursor = new ObjectId(cursor)
     }
-
     query[cursorField] = order === 'asc' ? { $gt: cursor } : { $lt: cursor }
   }
 
+  // Fetch results
   const results = await collection
     .find(query, { projection })
     .sort(sort)
     .limit(limit)
     .toArray()
 
+  // Get total count (for the original filter, not including cursor)
+  const totalCount = await collection.countDocuments(filter)
+
+  const paginationEdges =
+    results.length > 0
+      ? await getPaginationEdges({
+          order,
+          filter,
+          results,
+          collection,
+          cursorField,
+        })
+      : { hasNext: null, hasPrevious: null }
+
+  const { hasNext, hasPrevious } = paginationEdges
+  return {
+    order,
+    totalCount,
+    list: results,
+    previous: hasPrevious && results.length ? results[0][cursorField] : null,
+    next:
+      hasNext && results.length
+        ? results[results.length - 1][cursorField]
+        : null,
+  }
+}
+
+export async function getPaginationEdges({
+  order,
+  filter,
+  results,
+  collection,
+  cursorField,
+}) {
+  const first = results[0][cursorField]
+  const last = results[results.length - 1][cursorField]
+
+  // Check if there are items before the first
+  const hasPrevious =
+    (await collection.countDocuments({
+      ...filter,
+      [cursorField]: order === 'asc' ? { $lt: first } : { $gt: first },
+    })) > 0
+
+  // Check if there are items after the last
+  const hasNext =
+    (await collection.countDocuments({
+      ...filter,
+      [cursorField]: order === 'asc' ? { $gt: last } : { $lt: last },
+    })) > 0
+
+  return {
+    hasNext,
+    hasPrevious,
+  }
+}
+
+import { ObjectId } from 'mongodb'
+
+/**
+ * Classic page/limit pagination with total count
+ *
+ * @param {import('mongodb').Collection} collection
+ * @param {Object} options
+ * @param {Object} [options.filter={}] - MongoDB filter
+ * @param {string} [options.cursorField='_id'] - Field to sort by
+ * @param {'asc'|'desc'} [options.order='desc'] - Sort order
+ * @param {number} [options.limit=10] - Items per page
+ * @param {number} [options.page=1] - Page number (1-based)
+ * @param {Object} [options.projection] - Projection fields
+ */
+export async function paginate(
+  collection,
+  {
+    filter = {},
+    projection,
+    order = 'desc',
+    cursorField = '_id',
+    limit = 10,
+    page = 1,
+  } = {},
+) {
+  // Validation
+  if (page < 1) page = 1
+  if (limit < 1) limit = 10
+
+  const sort = { [cursorField]: order === 'asc' ? 1 : -1 }
+  const skip = (page - 1) * limit
+
+  const [results, totalCount] = await Promise.all([
+    collection
+      .find(filter, { projection })
+      .sort(sort)
+      .skip(skip)
+      .limit(limit)
+      .toArray(),
+    collection.countDocuments(filter),
+  ])
+
+  const totalPages = Math.ceil(totalCount / limit)
+  const hasNext = page < totalPages
+  const hasPrevious = page > 1
+
   return {
     order,
+    totalCount,
+    totalPages,
+    currentPage: page,
+    hasNext,
+    hasPrevious,
     list: results,
-    previous: results.length ? results[0][cursorField] : null,
-    next: results.length ? results[results.length - 1][cursorField] : null,
   }
 }

package/tests/mongodb/paginate-cursor.helper.integration.test.js

@@ -0,0 +1,351 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
+
+import { paginateCursor } from '../../src/mongodb/paginate.js'
+import { startMongo, stopMongo } from '../resources/docker-mongo-test.js'
+import { initializeMongoDb } from '../../src/mongodb/initialize-mongodb.js'
+
+const MONGO_PORT = 29050
+const CONTAINER_NAME = 'mongo-auth-attempts-paginate-cursor-test'
+
+let db
+let collection
+describe('paginateCursor - Integration', () => {
+  beforeAll(async () => {
+    startMongo(MONGO_PORT, CONTAINER_NAME)
+
+    db = await initializeMongoDb({
+      config: {
+        uri: `mongodb://0.0.0.0:${MONGO_PORT}`,
+        options: { dbName: 'users-management' },
+      },
+      collectionNames: {
+        TestDocs: 'test_docs',
+      },
+    })
+
+    collection = db.TestDocs
+  })
+  afterAll(() => {
+    stopMongo(CONTAINER_NAME)
+  })
+
+  beforeEach(async () => {
+    await collection.deleteMany({})
+  })
+
+  const seedDocs = async (count = 12) => {
+    const docs = Array.from({ length: count }).map((_, i) => ({
+      name: `doc_${i}`,
+      createdAt: new Date(Date.now() + i * 1000),
+    }))
+    await collection.insertMany(docs)
+    return docs
+  }
+
+  it('returns first page with limit', async () => {
+    await seedDocs(12)
+
+    const result = await paginateCursor(collection, {
+      filter: {},
+      limit: 5,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+
+    expect(result.list).toHaveLength(5)
+    expect(result.next).toBeDefined()
+    expect(result.previous).toBeNull()
+  })
+
+  it('returns empty when no docs match filter', async () => {
+    const result = await paginateCursor(collection, {
+      filter: { name: 'not-exist' },
+      limit: 5,
+      order: 'desc',
+    })
+
+    expect(result.list).toHaveLength(0)
+    expect(result.next).toBeNull()
+  })
+
+  it('supports ascending order', async () => {
+    const docs = await seedDocs(3)
+
+    const ascResult = await paginateCursor(collection, {
+      filter: {},
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    expect(ascResult.list[0].name).toBe(docs[0].name)
+  })
+
+  it('supports descending order', async () => {
+    const docs = await seedDocs(3)
+
+    const descResult = await paginateCursor(collection, {
+      filter: {},
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+
+    expect(descResult.list[0].name).toBe(docs[2].name)
+  })
+
+  it('paginateCursors with cursor (next page)', async () => {
+    await seedDocs(7)
+
+    // first page
+    const firstPage = await paginateCursor(collection, {
+      filter: {},
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    expect(firstPage.list).toHaveLength(3)
+    expect(firstPage.next).toBeDefined()
+
+    // second page using cursor
+    const secondPage = await paginateCursor(collection, {
+      filter: {},
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+
+    expect(secondPage.list).toHaveLength(3)
+    // validate no overlap between first and second page
+    expect(secondPage.list[0]._id.toString()).not.toBe(
+      firstPage.list[0]._id.toString(),
+    )
+    expect(secondPage.list.map((d) => d._id.toString())).not.toEqual(
+      firstPage.list.map((d) => d._id.toString()),
+    )
+  })
+
+  it('paginateCursors with stringified ObjectId as cursor', async () => {
+    const docs = await seedDocs(5)
+
+    // @ts-ignore
+    const stringCursor = docs[2]._id.toString()
+
+    const page = await paginateCursor(collection, {
+      filter: {},
+      limit: 2,
+      order: 'asc',
+      cursorField: '_id',
+      cursor: stringCursor,
+    })
+
+    expect(page.list).toHaveLength(2)
+
+    // @ts-ignore
+    expect(page.list[0]._id.toString()).toBe(docs[3]._id.toString())
+    // @ts-ignore
+    expect(page.list[1]._id.toString()).toBe(docs[4]._id.toString())
+  })
+
+  // ---------- PAGINATION EDGES (ASC ORDER) ----------
+
+  it('ASC - first page: has next, no previous', async () => {
+    await seedDocs(7)
+
+    const page = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    expect(page.list).toHaveLength(3)
+    expect(page.previous).toBeNull()
+    expect(page.next).not.toBeNull()
+  })
+
+  it('ASC - middle page: has both next and previous', async () => {
+    await seedDocs(9)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    const middlePage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+
+    expect(middlePage.list).toHaveLength(3)
+    expect(middlePage.previous).not.toBeNull()
+    expect(middlePage.next).not.toBeNull()
+  })
+
+  it('ASC - last page: has previous, no next', async () => {
+    await seedDocs(7)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+    const secondPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+    const lastPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: secondPage.next,
+    })
+
+    expect(lastPage.list.length).toBeGreaterThan(0)
+    expect(lastPage.previous).not.toBeNull()
+    expect(lastPage.next).toBeNull()
+  })
+
+  it('ASC - single page: no next, no previous', async () => {
+    await seedDocs(2)
+
+    const singlePage = await paginateCursor(collection, {
+      limit: 5,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    expect(singlePage.list).toHaveLength(2)
+    expect(singlePage.previous).toBeNull()
+    expect(singlePage.next).toBeNull()
+  })
+
+  // ---------- PAGINATION EDGES (DESC ORDER) ----------
+
+  it('DESC - first page: has next, no previous', async () => {
+    await seedDocs(7)
+
+    const page = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+
+    expect(page.list).toHaveLength(3)
+    expect(page.previous).toBeNull()
+    expect(page.next).not.toBeNull()
+  })
+
+  it('DESC - middle page: has both next and previous', async () => {
+    await seedDocs(9)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+
+    const middlePage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+
+    expect(middlePage.list).toHaveLength(3)
+    expect(middlePage.previous).not.toBeNull()
+    expect(middlePage.next).not.toBeNull()
+  })
+
+  it('DESC - last page: has previous, no next', async () => {
+    await seedDocs(7)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+    const secondPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+    const lastPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'desc',
+      cursorField: 'createdAt',
+      cursor: secondPage.next,
+    })
+
+    expect(lastPage.list.length).toBeGreaterThan(0)
+    expect(lastPage.previous).not.toBeNull()
+    expect(lastPage.next).toBeNull()
+  })
+
+  it('DESC - single page: no next, no previous', async () => {
+    await seedDocs(2)
+
+    const singlePage = await paginateCursor(collection, {
+      limit: 5,
+      order: 'desc',
+      cursorField: 'createdAt',
+    })
+
+    expect(singlePage.list).toHaveLength(2)
+    expect(singlePage.previous).toBeNull()
+    expect(singlePage.next).toBeNull()
+  })
+
+  // ---------- STABILITY CHECKS ----------
+
+  it('returns consistent next/previous cursors across calls', async () => {
+    await seedDocs(6)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    const secondPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+    console.log(secondPage)
+    const firstPageLast = firstPage.list[firstPage.list.length - 1].createdAt
+    const secondPageFirst = secondPage.list[0].createdAt
+
+    expect(secondPageFirst.getTime()).toBeGreaterThan(firstPageLast.getTime())
+    expect(secondPage.previous).toEqual(secondPage.list[0].createdAt)
+    expect(secondPage.next).toBeNull()
+  })
+
+  it('totalCount remains constant across pages', async () => {
+    await seedDocs(8)
+
+    const firstPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    const secondPage = await paginateCursor(collection, {
+      limit: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+      cursor: firstPage.next,
+    })
+
+    expect(firstPage.totalCount).toBe(8)
+    expect(secondPage.totalCount).toBe(8)
+  })
+})

package/tests/mongodb/paginate.helper.integration.test.js

@@ -1,17 +1,17 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest'
-
 import { paginate } from '../../src/mongodb/paginate.js'
 import { startMongo, stopMongo } from '../resources/docker-mongo-test.js'
 import { initializeMongoDb } from '../../src/mongodb/initialize-mongodb.js'
 
-const MONGO_PORT = 29050
+const MONGO_PORT = 29051
 const CONTAINER_NAME = 'mongo-auth-attempts-paginate-test'
 
 let db
 let collection
+
 describe('paginate - Integration', () => {
   beforeAll(async () => {
-    startMongo(MONGO_PORT, CONTAINER_NAME)
+    await startMongo(MONGO_PORT, CONTAINER_NAME)
 
     db = await initializeMongoDb({
       config: {
@@ -19,21 +19,22 @@ describe('paginate - Integration', () => {
         options: { dbName: 'users-management' },
       },
       collectionNames: {
-        TestDocs: 'test_docs',
+        TestDocs: 'test_docs_page',
       },
     })
 
     collection = db.TestDocs
   })
-  afterAll(() => {
-    stopMongo(CONTAINER_NAME)
+
+  afterAll(async () => {
+    await stopMongo(CONTAINER_NAME)
   })
 
   beforeEach(async () => {
     await collection.deleteMany({})
   })
 
-  const seedDocs = async (count = 12) => {
+  const seedDocs = async (count = 25) => {
     const docs = Array.from({ length: count }).map((_, i) => ({
       name: `doc_${i}`,
       createdAt: new Date(Date.now() + i * 1000),
@@ -42,110 +43,152 @@ describe('paginate - Integration', () => {
     return docs
   }
 
-  it('returns first page with limit', async () => {
-    await seedDocs(12)
+  it('returns first page with correct size and metadata', async () => {
+    await seedDocs(15)
 
     const result = await paginate(collection, {
-      filter: {},
       limit: 5,
-      order: 'desc',
+      page: 1,
+      order: 'asc',
       cursorField: 'createdAt',
     })
 
     expect(result.list).toHaveLength(5)
-    expect(result.next).toBeDefined()
-    expect(result.previous).toBeDefined()
+    expect(result.currentPage).toBe(1)
+    expect(result.totalPages).toBe(3)
+    expect(result.hasNext).toBe(true)
+    expect(result.hasPrevious).toBe(false)
   })
 
-  it('returns empty when no docs match filter', async () => {
+  it('returns middle page correctly', async () => {
+    await seedDocs(15)
+
     const result = await paginate(collection, {
-      filter: { name: 'not-exist' },
       limit: 5,
-      order: 'desc',
+      page: 2,
+      order: 'asc',
+      cursorField: 'createdAt',
     })
 
-    expect(result.list).toHaveLength(0)
-    expect(result.next).toBeNull()
+    expect(result.list).toHaveLength(5)
+    expect(result.currentPage).toBe(2)
+    expect(result.hasNext).toBe(true)
+    expect(result.hasPrevious).toBe(true)
   })
 
-  it('supports ascending order', async () => {
-    const docs = await seedDocs(3)
+  it('returns last page correctly', async () => {
+    await seedDocs(15)
 
-    const ascResult = await paginate(collection, {
-      filter: {},
-      limit: 3,
+    const result = await paginate(collection, {
+      limit: 5,
+      page: 3,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
+
+    expect(result.list).toHaveLength(5)
+    expect(result.hasNext).toBe(false)
+    expect(result.hasPrevious).toBe(true)
+  })
+
+  it('returns empty list for page out of range', async () => {
+    await seedDocs(10)
+
+    const result = await paginate(collection, {
+      limit: 5,
+      page: 5,
       order: 'asc',
       cursorField: 'createdAt',
     })
 
-    expect(ascResult.list[0].name).toBe(docs[0].name)
+    expect(result.list).toHaveLength(0)
+    expect(result.hasNext).toBe(false)
+    expect(result.hasPrevious).toBe(true)
+  })
+
+  it('returns totalCount consistent across pages', async () => {
+    await seedDocs(9)
+
+    const page1 = await paginate(collection, {
+      limit: 3,
+      page: 1,
+    })
+
+    const page2 = await paginate(collection, {
+      limit: 3,
+      page: 2,
+    })
+
+    expect(page1.totalCount).toBe(9)
+    expect(page2.totalCount).toBe(9)
   })
 
   it('supports descending order', async () => {
-    const docs = await seedDocs(3)
+    const docs = await seedDocs(6)
 
-    const descResult = await paginate(collection, {
-      filter: {},
+    const result = await paginate(collection, {
       limit: 3,
+      page: 1,
       order: 'desc',
       cursorField: 'createdAt',
     })
 
-    expect(descResult.list[0].name).toBe(docs[2].name)
+    expect(result.list[0].name).toBe(docs[5].name)
+    expect(result.list[2].name).toBe(docs[3].name)
   })
 
-  it('paginates with cursor (next page)', async () => {
-    await seedDocs(7)
+  it('supports ascending order', async () => {
+    const docs = await seedDocs(6)
 
-    // first page
-    const firstPage = await paginate(collection, {
-      filter: {},
+    const result = await paginate(collection, {
       limit: 3,
+      page: 1,
       order: 'asc',
       cursorField: 'createdAt',
     })
 
-    expect(firstPage.list).toHaveLength(3)
-    expect(firstPage.next).toBeDefined()
+    expect(result.list[0].name).toBe(docs[0].name)
+    expect(result.list[2].name).toBe(docs[2].name)
+  })
+
+  it('returns no documents when filter excludes all', async () => {
+    await seedDocs(5)
 
-    // second page using cursor
-    const secondPage = await paginate(collection, {
-      filter: {},
+    const result = await paginate(collection, {
+      filter: { name: 'not_existing' },
       limit: 3,
-      order: 'asc',
-      cursorField: 'createdAt',
-      cursor: firstPage.next,
+      page: 1,
     })
 
-    expect(secondPage.list).toHaveLength(3)
-    // validate no overlap between first and second page
-    expect(secondPage.list[0]._id.toString()).not.toBe(
-      firstPage.list[0]._id.toString(),
-    )
-    expect(secondPage.list.map((d) => d._id.toString())).not.toEqual(
-      firstPage.list.map((d) => d._id.toString()),
-    )
+    expect(result.list).toHaveLength(0)
+    expect(result.totalCount).toBe(0)
+    expect(result.totalPages).toBe(0)
   })
 
-  it('paginates with stringified ObjectId as cursor', async () => {
-    const docs = await seedDocs(5)
+  it('paginates deterministically across pages', async () => {
+    const docs = await seedDocs(9)
 
-    // @ts-ignore
-    const stringCursor = docs[2]._id.toString()
+    const page1 = await paginate(collection, {
+      limit: 3,
+      page: 1,
+      order: 'asc',
+      cursorField: 'createdAt',
+    })
 
-    const page = await paginate(collection, {
-      filter: {},
-      limit: 2,
+    const page2 = await paginate(collection, {
+      limit: 3,
+      page: 2,
       order: 'asc',
-      cursorField: '_id',
-      cursor: stringCursor,
+      cursorField: 'createdAt',
     })
 
-    expect(page.list).toHaveLength(2)
+    // ensure continuity: last of page1 == item before first of page2
+    const lastOfPage1 = page1.list[page1.list.length - 1].name
+    const firstOfPage2 = page2.list[0].name
 
-    // @ts-ignore
-    expect(page.list[0]._id.toString()).toBe(docs[3]._id.toString())
-    // @ts-ignore
-    expect(page.list[1]._id.toString()).toBe(docs[4]._id.toString())
+    const indexDiff =
+      docs.findIndex((d) => d.name === firstOfPage2) -
+      docs.findIndex((d) => d.name === lastOfPage1)
+    expect(indexDiff).toBe(1)
   })
 })

package/types/mongodb/paginate.d.ts

@@ -1,5 +1,5 @@
 /**
- * Pagination with SQL-like ascending/descending
+ * Pagination with SQL-like ascending/descending and total count
  *
  * @param {import('mongodb').Collection} collection
  * @param {Object} options
@@ -27,8 +27,25 @@ export function paginate(
   },
 ): Promise<{
   order: 'asc' | 'desc'
+  totalCount: number
   list: import('mongodb').WithId<import('bson').Document>[]
   previous: any
   next: any
 }>
+export function getPaginationEdges({
+  order,
+  filter,
+  results,
+  collection,
+  cursorField,
+}: {
+  order: any
+  filter: any
+  results: any
+  collection: any
+  cursorField: any
+}): Promise<{
+  hasNext: boolean
+  hasPrevious: boolean
+}>
 import { ObjectId } from 'mongodb'