@blueprint-ts/core 4.0.0-beta.8 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## v4.0.0 - 2026-03-01
+
+# [4.0.0](/compare/v4.0.0-beta.10...v4.0.0) (2026-03-01)
+## v4.0.0-beta.10 - 2026-02-28 (beta)
+
+# [4.0.0-beta.10](/compare/v4.0.0-beta.9...v4.0.0-beta.10) (2026-02-28)
+
+
+### Features
+
+* **pagination:** support local row removal without reload 3a66689
+## v4.0.0-beta.9 - 2026-02-28 (beta)
+
+# [4.0.0-beta.9](/compare/v4.0.0-beta.8...v4.0.0-beta.9) (2026-02-28)
 ## v4.0.0-beta.8 - 2026-02-28 (beta)
 
 # [4.0.0-beta.8](/compare/v4.0.0-beta.7...v4.0.0-beta.8) (2026-02-28)

package/docs/services/pagination/index.md

@@ -38,7 +38,7 @@ If you are using Vue, the library provides `VuePaginationDriverFactory` and `Vue
 - `flush`: clears existing data before applying the next page
 - `replace`: replaces existing data instead of appending (useful for infinite scroll)
 
-`updateRows` is available on all paginators. See [Updating Rows](./updating-rows).
+`updateRows` and `removeRows` are available on all paginators. See [Updating Rows](./updating-rows).
 
 ## Using Laravel Pagination
 

package/docs/services/pagination/updating-rows.md

@@ -34,3 +34,19 @@ const updated = paginator.updateRows(
     (row) => ({ ...row, updatedAt: new Date().toISOString() })
 )
 ```
+
+## Removing Rows
+
+Use `removeRows` to delete items from the current page data without reloading. By default it also decrements `total`
+by the number of removed rows. Set `adjustTotal: false` to skip that behavior.
+
+```typescript
+// Remove a single item
+const removed = paginator.removeRows((row) => row.id === targetId)
+
+// Remove all drafts without adjusting total
+const removedDrafts = paginator.removeRows(
+    (row) => row.status === 'draft',
+    { adjustTotal: false }
+)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "4.0.0-beta.8",
+  "version": "4.0.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/release-tool.json

@@ -20,7 +20,7 @@
       "subdir": "",
       "commit_message": "docs: publish {tag}",
       "add_nojekyll": true,
-      "force_push": false
+      "force_push": true
     }
   }
 }

package/src/pagination/BasePaginator.ts

@@ -55,6 +55,25 @@ export abstract class BasePaginator<ResourceInterface, ViewDriver extends BaseVi
     return updated
   }
 
+  public removeRows(
+    predicate: (row: ResourceInterface, index: number, data: ResourceInterface[]) => boolean,
+    options?: { adjustTotal?: boolean }
+  ): number {
+    const data = this.viewDriver.getData()
+    const next = data.filter((row, index) => !predicate(row, index, data))
+    const removed = data.length - next.length
+
+    if (removed > 0) {
+      this.viewDriver.setData(next)
+
+      if (options?.adjustTotal ?? true) {
+        this.viewDriver.setTotal(Math.max(0, this.viewDriver.getTotal() - removed))
+      }
+    }
+
+    return removed
+  }
+
   public getTotal(): number {
     return this.viewDriver.getTotal()
   }

package/src/requests/BaseRequest.ts

@@ -113,7 +113,8 @@ export abstract class BaseRequest<
   }
 
   public buildUrl(): URL {
-    const url = this.params !== undefined && Object.keys(this.params).length === 0 ? this.url() : this.url() + '?' + qs.stringify(this.params)
+    const hasParams = this.params !== undefined && Object.keys(this.params).length > 0
+    const url = hasParams ? this.url() + '?' + qs.stringify(this.params) : this.url()
 
     return new URL(url, this.baseUrl() ?? BaseRequest.defaultBaseUrl)
   }

package/src/vue/forms/validation/rules/EmailRule.ts

@@ -14,7 +14,7 @@ export class EmailRule<FormBody extends object> extends BaseRule<FormBody> {
       return false
     }
 
-    return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(value)
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
   }
 
   public getMessage(): string {

package/tests/service/bulkRequests/BulkRequestSender.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from 'vitest'
+import { BulkRequestSender, BulkRequestExecutionMode } from '../../../src/bulkRequests/BulkRequestSender'
+import { BulkRequestWrapper } from '../../../src/bulkRequests/BulkRequestWrapper'
+import { BulkRequestEventEnum } from '../../../src/bulkRequests/BulkRequestEvent.enum'
+
+const createRequest = (options: { failTimes?: number } = {}) => {
+  let calls = 0
+
+  return {
+    send: vi.fn().mockImplementation(() => {
+      calls += 1
+      if (options.failTimes && calls <= options.failTimes) {
+        return Promise.reject(new Error('fail'))
+      }
+      return Promise.resolve('ok')
+    }),
+    isLoading: vi.fn().mockReturnValue(false),
+    setAbortSignal: vi.fn(),
+  }
+}
+
+describe('BulkRequestSender', () => {
+  it('sends requests in parallel and emits success events', async () => {
+    const wrappers = [new BulkRequestWrapper(createRequest() as any), new BulkRequestWrapper(createRequest() as any)]
+
+    const sender = new BulkRequestSender(wrappers, BulkRequestExecutionMode.PARALLEL)
+    const onSuccess = vi.fn()
+
+    sender.on(BulkRequestEventEnum.REQUEST_SUCCESSFUL, onSuccess)
+
+    const result = await sender.send()
+
+    expect(onSuccess).toHaveBeenCalledTimes(2)
+    expect(result.getSuccessCount()).toBe(2)
+    expect(result.getErrorCount()).toBe(0)
+    expect(result.getSuccessfulResponses()).toEqual(['ok', 'ok'])
+  })
+
+  it('retries failed requests and emits failure events when still failing', async () => {
+    const failingRequest = createRequest({ failTimes: 2 })
+    const wrapper = new BulkRequestWrapper(failingRequest as any)
+
+    const sender = new BulkRequestSender([wrapper], BulkRequestExecutionMode.SEQUENTIAL, 1)
+    const onFailed = vi.fn()
+
+    sender.on(BulkRequestEventEnum.REQUEST_FAILED, onFailed)
+
+    await sender.send()
+
+    expect(failingRequest.send).toHaveBeenCalledTimes(2)
+    expect(onFailed).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports loading state when any request is loading', () => {
+    const request1 = createRequest()
+    const request2 = createRequest()
+    request2.isLoading = vi.fn().mockReturnValue(true)
+
+    const sender = new BulkRequestSender(
+      [new BulkRequestWrapper(request1 as any), new BulkRequestWrapper(request2 as any)],
+      BulkRequestExecutionMode.PARALLEL
+    )
+
+    expect(sender.isLoading).toBe(true)
+  })
+
+  it('removes event handlers with off()', () => {
+    const sender = new BulkRequestSender([], BulkRequestExecutionMode.PARALLEL)
+    const handler = vi.fn()
+
+    sender.on(BulkRequestEventEnum.REQUEST_SUCCESSFUL, handler)
+    sender.off(BulkRequestEventEnum.REQUEST_SUCCESSFUL)
+
+    expect((sender as any).events.has(BulkRequestEventEnum.REQUEST_SUCCESSFUL)).toBe(false)
+  })
+})

package/tests/service/bulkRequests/BulkRequestWrapper.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from 'vitest'
+import { BulkRequestWrapper } from '../../../src/bulkRequests/BulkRequestWrapper'
+
+const createRequest = (behavior: { shouldFail?: boolean } = {}) => {
+  return {
+    send: vi.fn().mockImplementation(() => {
+      if (behavior.shouldFail) {
+        return Promise.reject(new Error('fail'))
+      }
+      return Promise.resolve('ok')
+    }),
+    isLoading: vi.fn().mockReturnValue(false),
+    setAbortSignal: vi.fn(),
+  }
+}
+
+describe('BulkRequestWrapper', () => {
+  it('stores response on success', async () => {
+    const request = createRequest()
+    const wrapper = new BulkRequestWrapper(request as any)
+
+    await wrapper.send()
+
+    expect(wrapper.getResponse()).toBe('ok')
+    expect(wrapper.getError()).toBeNull()
+    expect(wrapper.hasError()).toBe(false)
+    expect(wrapper.wasSent()).toBe(true)
+  })
+
+  it('stores error on failure', async () => {
+    const request = createRequest({ shouldFail: true })
+    const wrapper = new BulkRequestWrapper(request as any)
+
+    await wrapper.send()
+
+    expect(wrapper.getResponse()).toBeNull()
+    expect(wrapper.getError()).toBeInstanceOf(Error)
+    expect(wrapper.hasError()).toBe(true)
+    expect(wrapper.wasSent()).toBe(true)
+  })
+
+  it('passes abort signal to request', async () => {
+    const request = createRequest()
+    const wrapper = new BulkRequestWrapper(request as any)
+    const controller = new AbortController()
+
+    await wrapper.send(controller.signal)
+
+    expect(request.setAbortSignal).toHaveBeenCalledWith(controller.signal)
+  })
+})

package/tests/service/pagination/BasePaginator.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { BasePaginator } from '../../../src/pagination/BasePaginator'
+import { PaginationDataDto } from '../../../src/pagination/dtos/PaginationDataDto'
+import type { BaseViewDriverContract } from '../../../src/pagination/contracts/BaseViewDriverContract'
+
+class TestViewDriver implements BaseViewDriverContract<number[]> {
+  private data: number[] = []
+  private total = 0
+
+  setData(data: number[]): void {
+    this.data = data
+  }
+
+  getData(): number[] {
+    return this.data
+  }
+
+  setTotal(value: number): void {
+    this.total = value
+  }
+
+  getTotal(): number {
+    return this.total
+  }
+}
+
+class TestPaginator extends BasePaginator<number, TestViewDriver> {
+  protected override viewDriver = new TestViewDriver()
+
+  public exposePass(dto: PaginationDataDto<number[]>, options?: { flush?: boolean }) {
+    this.passDataToViewDriver(dto, options)
+  }
+
+  public exposeHandleStale() {
+    return this.handleStaleResponse()
+  }
+
+  public getViewDriver() {
+    return this.viewDriver
+  }
+}
+
+describe('BasePaginator', () => {
+  it('updates rows and returns updated count', () => {
+    const paginator = new TestPaginator(null)
+    paginator.getViewDriver().setData([1, 2, 3])
+
+    const updated = paginator.updateRows(
+      (row) => row % 2 === 0,
+      (row) => row * 10
+    )
+
+    expect(updated).toBe(1)
+    expect(paginator.getPageData()).toEqual([1, 20, 3])
+  })
+
+  it('removes rows and adjusts total', () => {
+    const paginator = new TestPaginator(null)
+    paginator.getViewDriver().setData([1, 2, 3])
+    paginator.getViewDriver().setTotal(3)
+
+    const removed = paginator.removeRows((row) => row > 1)
+
+    expect(removed).toBe(2)
+    expect(paginator.getPageData()).toEqual([1])
+    expect(paginator.getTotal()).toBe(1)
+  })
+
+  it('can remove rows without adjusting total', () => {
+    const paginator = new TestPaginator(null)
+    paginator.getViewDriver().setData([1, 2, 3])
+    paginator.getViewDriver().setTotal(3)
+
+    paginator.removeRows((row) => row === 1, { adjustTotal: false })
+
+    expect(paginator.getPageData()).toEqual([2, 3])
+    expect(paginator.getTotal()).toBe(3)
+  })
+
+  it('passes data to view driver and marks initialized', () => {
+    const paginator = new TestPaginator(null)
+
+    paginator.exposePass(new PaginationDataDto([4, 5], 2), { flush: true })
+
+    expect(paginator.getPageData()).toEqual([4, 5])
+    expect(paginator.getTotal()).toBe(2)
+    expect(paginator.isInitialized()).toBe(true)
+  })
+
+  it('handles stale response by returning current data/total', () => {
+    const paginator = new TestPaginator(null)
+    paginator.getViewDriver().setData([7])
+    paginator.getViewDriver().setTotal(9)
+
+    const dto = paginator.exposeHandleStale()
+
+    expect(dto.getData()).toEqual([7])
+    expect(dto.getTotal()).toBe(9)
+  })
+})

package/tests/service/pagination/InfiniteScroller.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { InfiniteScroller } from '../../../src/pagination/InfiniteScroller'
+import { PaginationDataDto } from '../../../src/pagination/dtos/PaginationDataDto'
+import type { PaginationDataDriverContract } from '../../../src/pagination/contracts/PaginationDataDriverContract'
+import type { ViewDriverFactoryContract } from '../../../src/pagination/contracts/ViewDriverFactoryContract'
+import type { ViewDriverContract } from '../../../src/pagination/contracts/ViewDriverContract'
+
+class StubViewDriver implements ViewDriverContract<number[]> {
+  private data: number[] = []
+  private total = 0
+  private currentPage: number
+  private pageSize: number
+
+  constructor(pageNumber: number, pageSize: number) {
+    this.currentPage = pageNumber
+    this.pageSize = pageSize
+  }
+
+  setData(data: number[]): void {
+    this.data = data
+  }
+
+  getData(): number[] {
+    return this.data
+  }
+
+  setTotal(value: number): void {
+    this.total = value
+  }
+
+  getTotal(): number {
+    return this.total
+  }
+
+  getCurrentPage(): number {
+    return this.currentPage
+  }
+
+  setPage(value: number): void {
+    this.currentPage = value
+  }
+
+  setPageSize(value: number): void {
+    this.pageSize = value
+  }
+
+  getPageSize(): number {
+    return this.pageSize
+  }
+
+  getLastPage(): number {
+    return Math.max(1, Math.ceil(this.total / this.pageSize))
+  }
+
+  getPages(): number[] {
+    return Array.from({ length: this.getLastPage() }, (_, i) => i + 1)
+  }
+}
+
+class StubViewDriverFactory implements ViewDriverFactoryContract {
+  public make<ResourceInterface>(pageNumber: number, pageSize: number): ViewDriverContract<ResourceInterface[]> {
+    return new StubViewDriver(pageNumber, pageSize) as ViewDriverContract<ResourceInterface[]>
+  }
+}
+
+describe('InfiniteScroller', () => {
+  it('concatenates data by default', async () => {
+    let call = 0
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => {
+        call += 1
+        return new PaginationDataDto(call === 1 ? [1, 2] : [3], 3)
+      },
+    }
+
+    const paginator = new InfiniteScroller<number[]>(dataDriver, 1, 2, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    await paginator.load()
+    await paginator.load()
+
+    expect(paginator.getPageData()).toEqual([1, 2, 3])
+  })
+
+  it('replaces data when replace is true', async () => {
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => new PaginationDataDto([9], 1),
+    }
+
+    const paginator = new InfiniteScroller<number[]>(dataDriver, 1, 2, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    ;(paginator as any).viewDriver.setData([1, 2])
+
+    await paginator.load(1, { replace: true })
+
+    expect(paginator.getPageData()).toEqual([9])
+  })
+})

package/tests/service/pagination/PageAwarePaginator.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import { PageAwarePaginator } from '../../../src/pagination/PageAwarePaginator'
+import { PaginationDataDto } from '../../../src/pagination/dtos/PaginationDataDto'
+import { StaleResponseException } from '../../../src/requests/exceptions/StaleResponseException'
+import type { PaginationDataDriverContract } from '../../../src/pagination/contracts/PaginationDataDriverContract'
+import type { ViewDriverContract } from '../../../src/pagination/contracts/ViewDriverContract'
+import type { ViewDriverFactoryContract } from '../../../src/pagination/contracts/ViewDriverFactoryContract'
+
+class StubViewDriver implements ViewDriverContract<number[]> {
+  private data: number[] = []
+  private total = 0
+  private currentPage: number
+  private pageSize: number
+
+  constructor(pageNumber: number, pageSize: number) {
+    this.currentPage = pageNumber
+    this.pageSize = pageSize
+  }
+
+  setData(data: number[]): void {
+    this.data = data
+  }
+
+  getData(): number[] {
+    return this.data
+  }
+
+  setTotal(value: number): void {
+    this.total = value
+  }
+
+  getTotal(): number {
+    return this.total
+  }
+
+  getCurrentPage(): number {
+    return this.currentPage
+  }
+
+  setPage(value: number): void {
+    this.currentPage = value
+  }
+
+  setPageSize(value: number): void {
+    this.pageSize = value
+  }
+
+  getPageSize(): number {
+    return this.pageSize
+  }
+
+  getLastPage(): number {
+    return Math.max(1, Math.ceil(this.total / this.pageSize))
+  }
+
+  getPages(): number[] {
+    return Array.from({ length: this.getLastPage() }, (_, i) => i + 1)
+  }
+}
+
+class StubViewDriverFactory implements ViewDriverFactoryContract {
+  public make<ResourceInterface>(pageNumber: number, pageSize: number): ViewDriverContract<ResourceInterface[]> {
+    return new StubViewDriver(pageNumber, pageSize) as ViewDriverContract<ResourceInterface[]>
+  }
+}
+
+describe('PageAwarePaginator', () => {
+  it('loads data and updates view driver', async () => {
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => new PaginationDataDto([1, 2], 2),
+    }
+
+    const paginator = new PageAwarePaginator<number[]>(dataDriver, 1, 2, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    const dto = await paginator.load(2)
+
+    expect(dto.getData()).toEqual([1, 2])
+    expect(paginator.getCurrentPage()).toBe(2)
+    expect(paginator.getPageData()).toEqual([1, 2])
+    expect(paginator.getTotal()).toBe(2)
+  })
+
+  it('computes item range and pages', () => {
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => new PaginationDataDto([1], 10),
+    }
+
+    const paginator = new PageAwarePaginator<number[]>(dataDriver, 2, 5, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    expect(paginator.getFromItemNumber()).toBe(6)
+    expect(paginator.getToItemNumber()).toBe(10)
+    paginator.getPageData()
+  })
+
+  it('resets page number when page size exceeds total', () => {
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => new PaginationDataDto([1, 2], 3),
+    }
+
+    const paginator = new PageAwarePaginator<number[]>(dataDriver, 2, 2, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    ;(paginator as any).viewDriver.setTotal(3)
+    paginator.setPageSize(2)
+
+    expect(paginator.getCurrentPage()).toBe(1)
+  })
+
+  it('returns stale data when StaleResponseException occurs', async () => {
+    const dataDriver: PaginationDataDriverContract<number[]> = {
+      get: async () => {
+        throw new StaleResponseException()
+      },
+    }
+
+    const paginator = new PageAwarePaginator<number[]>(dataDriver, 1, 2, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    ;(paginator as any).viewDriver.setData([9])
+    ;(paginator as any).viewDriver.setTotal(9)
+
+    const dto = await paginator.load()
+
+    expect(dto.getData()).toEqual([9])
+    expect(dto.getTotal()).toBe(9)
+  })
+})

package/tests/service/pagination/StatePaginator.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { StatePaginator } from '../../../src/pagination/StatePaginator'
+import { StatePaginationDataDto } from '../../../src/pagination/dtos/StatePaginationDataDto'
+import type { BaseViewDriverContract } from '../../../src/pagination/contracts/BaseViewDriverContract'
+import type { BaseViewDriverFactoryContract } from '../../../src/pagination/contracts/BaseViewDriverFactoryContract'
+import type { StatePaginationDataDriverContract } from '../../../src/pagination/contracts/StatePaginationDataDriverContract'
+
+class StubViewDriver implements BaseViewDriverContract<number[]> {
+  private data: number[] = []
+  private total = 0
+
+  setData(data: number[]): void {
+    this.data = data
+  }
+
+  getData(): number[] {
+    return this.data
+  }
+
+  setTotal(value: number): void {
+    this.total = value
+  }
+
+  getTotal(): number {
+    return this.total
+  }
+}
+
+class StubViewDriverFactory implements BaseViewDriverFactoryContract {
+  public make<ResourceInterface>(): BaseViewDriverContract<ResourceInterface[]> {
+    return new StubViewDriver() as BaseViewDriverContract<ResourceInterface[]>
+  }
+}
+
+describe('StatePaginator', () => {
+  it('loads and appends data, tracking state', async () => {
+    const dataDriver: StatePaginationDataDriverContract<number[]> = {
+      get: async () => new StatePaginationDataDto([1, 2], 2, 'next'),
+    }
+
+    const paginator = new StatePaginator<number[]>(dataDriver, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    const dto = await paginator.load()
+
+    expect(dto.getData()).toEqual([1, 2])
+    expect(paginator.getPageData()).toEqual([1, 2])
+    expect(paginator.getTotal()).toBe(2)
+    expect(paginator.getCurrentState()).toBe('next')
+    expect(paginator.hasNextPage()).toBe(true)
+  })
+
+  it('supports loadNext and replace option', async () => {
+    let call = 0
+    const dataDriver: StatePaginationDataDriverContract<number[]> = {
+      get: async (state) => {
+        call += 1
+        return new StatePaginationDataDto(call === 1 ? [1] : [2], 2, state ? null : 'next')
+      },
+    }
+
+    const paginator = new StatePaginator<number[]>(dataDriver, {
+      viewDriverFactory: new StubViewDriverFactory(),
+    })
+
+    await paginator.load()
+    await paginator.loadNext()
+
+    expect(paginator.getPageData()).toEqual([1, 2])
+    expect(paginator.hasNextPage()).toBe(false)
+
+    ;(paginator as any).passStateDataToViewDriver(new StatePaginationDataDto([9], 1, null), { replace: true })
+    expect(paginator.getPageData()).toEqual([9])
+  })
+})