Bulk Delete Items
Relevant source files
The following files were used as context for generating this wiki page:
Bulk Delete Items is a critical administrative feature of the Refined GitHub Projects extension that allows users to permanently remove multiple items from a GitHub Project V2 simultaneously. This operation bypasses the standard one-by-one deletion process provided by the native GitHub interface, streamlining project maintenance for large-scale boards. Sources: README.md:104, README.md:139
The feature is implemented through a distributed architecture involving a React-based UI component for confirmation and a background service worker that executes sequential GraphQL mutations. To prevent rate-limiting or automated bans (403 Abuse alerts), deletions are processed through a global queue with mandatory delays between each operation. Sources: src/entries/background/handlers/bulk-handlers.ts:315-333, CONTRIBUTING.md:14-17
User Interface and Triggering
The bulk delete operation is triggered via the Bulk Actions Bar, which appears at the bottom of the GitHub Projects table view when one or more items are selected. Sources: src/components/bulk/bulk-actions-bar.tsx:135-155
Selection and Shortcuts
Users can select items manually or use global keyboard shortcuts to initiate the flow. Administrative privileges are typically required for this "Danger Zone" operation. Sources: README.md:139, src/components/bulk/bulk-actions-bar.tsx:1022-1050
| Action | Shortcut (Mac) | Shortcut (Windows/Linux) |
|---|---|---|
| Select All | ⌘A | Ctrl+A |
| Delete Items | ⌘⇧⌫ | Ctrl+⇧⌫ |
| Quick Delete | Delete | Delete |
Sources: src/components/bulk/bulk-actions-bar.tsx:325-337, src/components/bulk/bulk-actions-bar.tsx:490-500
The Confirmation Modal
Before any API calls are made, the BulkDeleteModal is presented to the user. This modal serves as a safety guardrail, displaying the exact count of items to be removed and requiring a explicit confirmation click. Sources: src/components/bulk/bulk-delete-modal.tsx:10-50, src/components/bulk/bulk-actions-bar.tsx:773-780
Execution Architecture
The deletion process follows a strictly sequential data flow to ensure stability and compliance with GitHub's secondary rate limits.
Process Flow Diagram
The following diagram illustrates the flow from user selection to the final GraphQL mutation.
Background Logic
The background handler bulkDelete manages the operation lifecycle:
- Concurrency Check: Verifies if the maximum concurrent bulk updates (3) has been reached using
isBulkFull(). Sources: src/entries/background/handlers/bulk-handlers.ts:321-324 - Item Resolution: Converts DOM-extracted IDs (e.g.,
issue:12345) into real ProjectV2Item Node IDs required by the GraphQL API. Sources: src/entries/background/handlers/bulk-handlers.ts:337, src/entries/background/helpers.ts:544-550 - Task Creation: Maps resolved items into
QueueTaskobjects. Sources: src/entries/background/handlers/bulk-handlers.ts:348-354 - Sequential Execution: Uses
processQueueto run tasks one-by-one, with a 1-secondsleep(1000)between each mutation to avoid PAT bans. Sources: src/entries/background/handlers/bulk-handlers.ts:352, src/entries/background/helpers.ts:673
API Implementation
The system utilizes the GitHub GraphQL API for all deletion operations. The specific mutation used is DELETE_PROJECT_ITEM.
GraphQL Mutation Detail
// src/lib/graphql/mutations.ts (referenced in bulk-handlers.ts)
export const DELETE_PROJECT_ITEM = gql`
mutation($projectId: ID!, $itemId: ID!) {
deleteProjectV2Item(input: { projectId: $projectId, itemId: $itemId }) {
deletedItemId
}
}
`
Sources: src/entries/background/handlers/bulk-handlers.ts:24, src/entries/background/handlers/bulk-handlers.ts:351
Progress Tracking
Throughout the deletion process, the background worker sends queueStateUpdate messages to the content script. This drives the Live Queue Tracker UI, showing real-time status such as "Removing item 3 of 10…". Sources: src/entries/background/handlers/bulk-handlers.ts:357-375, README.md:175-180
| State | Broadcast Message Detail |
|---|---|
| Resolving | status: "Resolving items..." |
| Progressing | status: "Removing item X of N..." |
| Paused | paused: true (triggered by 403/429 errors) |
| Complete | status: "Done!" |
Sources: src/entries/background/handlers/bulk-handlers.ts:333-380, src/entries/background/helpers.ts:685-715
Rate Limit Handling
If GitHub returns a 403 or 429 status code, the operation is caught by the withRateLimitRetry helper. The queue enters a paused state, and the background worker waits for the duration specified in the Retry-After header (defaulting to 60 seconds) before attempting to resume the task. Sources: src/entries/background/helpers.ts:705-725
Conclusion
Bulk Delete Items provides an essential safety-first implementation for project cleanup. By combining a React-based confirmation flow with a robust, sequential background queue, the system ensures that destructive operations are performed accurately while protecting the user's GitHub Personal Access Token from rate-limit penalties. Sources: README.md:182-187, CONTRIBUTING.md:14-20