{"id":38515222,"url":"https://github.com/claui/vscode-event-curator","last_synced_at":"2026-01-17T06:28:06.006Z","repository":{"id":144831546,"uuid":"616698928","full_name":"claui/vscode-event-curator","owner":"claui","description":"Useful document events for your VS Code extension to consume","archived":false,"fork":false,"pushed_at":"2024-09-02T15:11:45.000Z","size":2317,"stargazers_count":1,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-05T04:42:06.107Z","etag":null,"topics":["adapter","events","library","visual-studio-code","vscode"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/vscode-event-curator","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2023-03-20T22:43:02.000Z","updated_at":"2024-11-18T02:32:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"928189f0-be7b-4527-b79a-8c9632e284e7","html_url":"https://github.com/claui/vscode-event-curator","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/claui/vscode-event-curator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claui%2Fvscode-event-curator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claui%2Fvscode-event-curator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claui%2Fvscode-event-curator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claui%2Fvscode-event-curator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claui","download_url":"https://codeload.github.com/claui/vscode-event-curator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claui%2Fvscode-event-curator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28502277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["adapter","events","library","visual-studio-code","vscode"],"created_at":"2026-01-17T06:28:05.882Z","updated_at":"2026-01-17T06:28:05.960Z","avatar_url":"https://github.com/claui.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vscode-event-curator\n\nThis library provides alternative text document events for your\nVS Code extension to consume.\n\n## Motivation\n\nWhile Microsoft’s original VS Code API is a well-engineered piece of\ntech, its event model for text documents has a few rough edges.\n\nThis library sits on top of the VS Code API, emitting curated events.\nDepending on your use case, those curated events can be more practical\nthan the text document events the original VS Code API emits.\n\nThe following table explains the differences in a nutshell:\n\n| When a document is | Original VS Code API notifies you |    This API notifies you    |\n|:------------------:|:---------------------------------:|:---------------------------:|\n| **opened**         | All the time                      | If it matches your selector |\n| **changed**        | All the time, on every change, risk of infinite loops | If it matches your selector, coalescing the changes |\n| **closed**         | All the time                      | If it matches your selector |\n| **already open at activation time** |        —         | If it matches your selector |\n\n## Target audience\n\nThis library is for developers of VS Code extensions.  \nIf you’re not an extension developer, this library won’t be useful\nto you.\n\n## How to install\n\nUsing the npm CLI:\n\n```shell\nnpm install vscode-event-curator\n```\n\nUsing Yarn:\n\n```shell\nyarn add vscode-event-curator\n```\n\n## Usage\n\nIn your VS Code extension:\n\n```typescript\nimport { EventCurator } from \"./event-curator\";\n\nconst curator = new EventCurator({\n  language: \"my-lang\", // ID of your contributed language\n  changeEventThrottleMillis: 1000, // to coalesce change events\n});\n\n/*\n * Use this instead of `workspace.onDidOpenTextDocument`.\n * Filters out unwanted schemes and respects your language selector,\n * too.\n */\ncurator.onDidOpenRelevantTextDocument((document) =\u003e {\n  // …\n});\n\n/*\n * Use this instead of `workspace.onDidCloseTextDocument`, similarly.\n */\ncurator.onDidCloseRelevantTextDocument((document) =\u003e {\n  // …\n});\n\n/*\n * Use this instead of `workspace.onDidChangeTextDocument`.\n * This one throttles (coalesces) events for you, which means that\n * for each relevant text document, you get no more than one event\n * per `changeEventThrottleMillis` ms window.\n */\ncurator.onDidChangeRelevantTextDocument((document) =\u003e {\n  /*\n   * Note: unlike `workspace.onDidChangeTextDocument`, this event\n   * hands you just the `TextDocument`, i.e. not the itemized\n   * changes.\n   */\n});\n\n/*\n * Get notified of already-opened documents as your extension\n * wakes up.\n */\ncurator.onDidInitiallyFindRelevantTextDocument((document) =\u003e {\n  // …\n});\n```\n\n## Detailed explanation\n\nThis library introduces new event registration endpoints:\n\n- `onDidOpenRelevantTextDocument`\n  (replaces `workspace.onDidOpenTextDocument`)\n- `onDidCloseRelevantTextDocument`\n  (replaces `workspace.onDidCloseTextDocument`)\n- `onDidChangeRelevantTextDocument`\n  (replaces `workspace.onDidChangeTextDocument`)\n- `onDidInitiallyFindRelevantTextDocument` (new feature)\n\nThose new event registration endpoints filter out less-than-helpful\nevents by default. For example, the following events can be unwanted:\n\n- events that originate from log output channels;\n\n- events that belong to a language in which your extension is not\n  interested.\n\nWhile events that belong to an irrelevant language can be a nuisance,\nevents that originate from log output channels can even trigger\ninfinite loops in the extension host. For example, if your extension\nresponds to a `workspace.onDidChangeTextDocument` event by logging\nsomething to an output channel, VS Code registers that as a text\ndocument change, too. This in turn causes another\n`workspace.onDidChangeTextDocument` event to fire, possibly\ntriggering an endless feedback loop in your extension.\n\nAnother pitfall for `workspace.onDidChangeTextDocument` is that it’s\nnot rate limited. This can cause issues if an extension wants to\nupdate diagnostics in real time as the user types.  \nTo mitigate that, the new `onDidChangeRelevantTextDocument` event\nwill buffer and throttle the original events. That allows for\npractical rate limiting (e.g. 1000 milliseconds) while the user is\nactively editing a text document.\n\nIn addition to the events mentioned, a VS Code extension may also be\ninterested in all text documents that are already open at extension\nactivation time, because it wants to give those already-open\ntext documents the same treatment, UX-wise, as the text documents\nwhich the end user may be opening later. That would make for a more\nconsistent UX. To that end, this library provides an endpoint called\n`onDidInitiallyFindRelevantTextDocument`.\n\n## License\n\nCopyright (c) 2023 Claudia Pellegrino\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nFor a copy of the License, see [LICENSE.txt](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaui%2Fvscode-event-curator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaui%2Fvscode-event-curator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaui%2Fvscode-event-curator/lists"}