{"id":15788298,"url":"https://github.com/xitanggg/node-selection","last_synced_at":"2026-03-04T01:04:01.601Z","repository":{"id":214888798,"uuid":"737599632","full_name":"xitanggg/node-selection","owner":"xitanggg","description":"A simple Node.js util that allows you to retrieve user's current selection text on desktop","archived":false,"fork":false,"pushed_at":"2024-07-05T07:13:36.000Z","size":982,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T08:37:51.942Z","etag":null,"topics":["automation","desktop","electron","native-addon","node"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@xitanggg/node-selection","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xitanggg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-31T17:29:19.000Z","updated_at":"2025-03-16T15:26:21.000Z","dependencies_parsed_at":"2023-12-31T18:27:41.668Z","dependency_job_id":"263ab37a-4bbd-4f40-9eb6-334dbce9b732","html_url":"https://github.com/xitanggg/node-selection","commit_stats":{"total_commits":21,"total_committers":1,"mean_commits":21.0,"dds":0.0,"last_synced_commit":"2c4883bd43a9c5eda21f318b4e1d26f45f1a37f8"},"previous_names":["xitanggg/node-selection"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xitanggg%2Fnode-selection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xitanggg%2Fnode-selection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xitanggg%2Fnode-selection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xitanggg%2Fnode-selection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xitanggg","download_url":"https://codeload.github.com/xitanggg/node-selection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246620384,"owners_count":20806761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","desktop","electron","native-addon","node"],"created_at":"2024-10-04T21:41:43.663Z","updated_at":"2026-03-04T01:03:56.433Z","avatar_url":"https://github.com/xitanggg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🖱️Node Selection\n\nThis package provides a simple Node.js util that allows you to retrieve user's current selection text on desktop.\n\n- Support Windows and Mac\n  - Mac: Need to grant accessibility permission to the calling app (`Settings` -\u003e `Privacy \u0026 Security` -\u003e `Accessibility`) to call Apple's [Core Graphics framework](https://developer.apple.com/documentation/coregraphics) to post [CGEvent](https://developer.apple.com/documentation/coregraphics/cgevent) to simulate copy operation\n- Require Node.js \u003e= 10\n\n## 📦Installation\n\n```bash\nnpm i @xitanggg/node-selection\n```\n\n## ℹ️Usage\n\n**Common Usage**\n\n```typescript\nimport { getSelectionText } from '@xitanggg/node-selection';\n\nconst selectionText = getSelectionText();\n```\n\n**Custom Usage**\n\n`getSelectionText` accepts an optional `timeOutMs` as its first input argument, which sets the max time to wait for selection text to appear in the clipboard during clipboard polling. It defaults to 80ms, and can be adjusted lower or higher depending on OS and use case. Smaller selection text is faster to copy while larger selection text takes longer.\n\n```typescript\nimport { getSelectionText } from '@xitanggg/node-selection';\n\nconst LONGER_COPY_TIME_OUT_MS = 100;\nconst selectionText = getSelectionText(LONGER_COPY_TIME_OUT_MS);\n```\n\nThere is also an optional `printTimeToCopy` as its second input argument, which defaults to `false`, but if set to `true`, prints the time taken to copy selection text to clipboard to console. It can be useful for debugging and adjusting `timeOutMs` based on OS and use case.\n\n```typescript\nconst PRINT_TIME_TO_COPY = true;\nconst selectionText = getSelectionText(\n\tLONGER_COPY_TIME_OUT_MS,\n\tPRINT_TIME_TO_COPY\n);\n```\n\n## 💡Implementation\n\n**Core Logic**\n\nThe implementation is written in Rust and is ~150 lines of code in a single file `/src/lib.rs`.\n\nThe selection text is retrieved in a 6-step process:\n\n1. Save clipboard existing text or image\n2. Clear clipboard\n3. Simulate `Ctrl + C` (`Cmd + C` in Mac) keyboard input to copy selection text to clipboard\n4. Poll clipboard to retrieve selection text in a loop every 1ms. The loop breaks if the selection text is found or it times out after 80ms by default\n5. Restore clipboard previous text or image to minimize side effects to users\n6. Return selection text as the result\n\n**Dependencies**\n\nFor clipboard operation, it uses [Arboard (Arthur's Clipboard)](https://github.com/1Password/arboard).\n\nFor keyboard input simulation, it uses [enigo](https://github.com/enigo-rs/enigo) in Windows, and [core-foundation-rs's core-graphics](https://github.com/servo/core-foundation-rs) in Mac.\n\nArboard supports getting and setting clipboard text and image, which should satisfy most use cases. But it is worth noting that it doesn't support other clipboard contents, e.g. html, rtf, file. A `copy` method is provided for those who would like to implement custom logics to save and restore clipboard state or just want to call `Ctrl + C` (`Cmd + C` in Mac) to perform copy.\n\n```typescript\nimport { copy } from '@xitanggg/node-selection';\n\n// Skip custom logics to save clipboard state\ncopy();\n// Skip custom logics to poll clipboard and restore clipboard state\n```\n\n**Build \u0026 Distribution**\n\nIt uses [NAPI-RS](https://github.com/napi-rs/napi-rs) to compile the Rust source code into binaries via GitHub actions, package it as a Node-API native addon, and then publish it to npm for distribution and easy use.\n\nOne very nice thing about the NAPI-RS tooling is that the binary has been built, so this package just works after installation, i.e. no need to build it yourself. Also, the binary is selectively installed, meaning installation only installs the binary that your system needs, e.g. windows or Mac, to keep the size small instead of including all binaries at once.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxitanggg%2Fnode-selection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxitanggg%2Fnode-selection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxitanggg%2Fnode-selection/lists"}