{"id":29041882,"url":"https://github.com/nasriyasoftware/overwatch","last_synced_at":"2025-10-19T18:26:57.592Z","repository":{"id":299769410,"uuid":"1004145670","full_name":"nasriyasoftware/Overwatch","owner":"nasriyasoftware","description":"Overwatch is a fast, reliable, and efficient file system watcher built with TypeScript. It supports flexible filtering using globs and regexes, making it ideal for scalable, cross-platform file monitoring with minimal resource usage.","archived":false,"fork":false,"pushed_at":"2025-06-18T07:48:20.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-18T07:48:33.181Z","etag":null,"topics":["cross-platform","filesystem","filewatcher","fs-monitoring","watcher"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nasriyasoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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,"zenodo":null},"funding":{"custom":["https://fund.nasriya.net"]}},"created_at":"2025-06-18T07:25:14.000Z","updated_at":"2025-06-18T07:46:31.000Z","dependencies_parsed_at":"2025-06-18T07:48:36.002Z","dependency_job_id":"0e3d9042-9864-4b5e-9f5d-e0e69080c3d2","html_url":"https://github.com/nasriyasoftware/Overwatch","commit_stats":null,"previous_names":["nasriyasoftware/overwatch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nasriyasoftware/Overwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FOverwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FOverwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FOverwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FOverwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nasriyasoftware","download_url":"https://codeload.github.com/nasriyasoftware/Overwatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nasriyasoftware%2FOverwatch/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262090278,"owners_count":23257125,"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":["cross-platform","filesystem","filewatcher","fs-monitoring","watcher"],"created_at":"2025-06-26T15:04:41.487Z","updated_at":"2025-10-19T18:26:57.586Z","avatar_url":"https://github.com/nasriyasoftware.png","language":"TypeScript","funding_links":["https://fund.nasriya.net"],"categories":[],"sub_categories":[],"readme":"[![N|Solid](https://static.wixstatic.com/media/72ffe6_da8d2142d49c42b29c96ba80c8a91a6c~mv2.png)](https://nasriya.net)\n\n# Overwatch.\n[![NPM License](https://img.shields.io/npm/l/%40nasriya%2Foverwatch?color=lightgreen)](https://github.com/nasriyasoftware/Overwatch?tab=License-1-ov-file) ![NPM Version](https://img.shields.io/npm/v/%40nasriya%2Foverwatch) ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40nasriya%2Foverwatch) ![Last Commit](https://img.shields.io/github/last-commit/nasriyasoftware/Overwatch.svg) [![Status](https://img.shields.io/badge/Status-Stable-lightgreen.svg)](link-to-your-status-page)\n\n##### Visit us at [www.nasriya.net](https://nasriya.net).\n\nMade with ❤️ in **Palestine** 🇵🇸\n___\n#### Overview\nOverwatch is a fast, reliable, and efficient file system watcher built with TypeScript. It supports flexible filtering using globs and regexes, making it ideal for scalable, cross-platform file monitoring with minimal resource usage.\n\n\u003e [!IMPORTANT]\n\u003e \n\u003e 🌟 **Support Our Open-Source Development!** 🌟\n\u003e We need your support to keep our projects going! If you find our work valuable, please consider contributing. Your support helps us continue to develop and maintain these tools.\n\u003e \n\u003e **[Click here to support us!](https://fund.nasriya.net/)**\n\u003e \n\u003e Every contribution, big or small, makes a difference. Thank you for your generosity and support!\n___\n### Installation\n```shell\nnpm i @nasriya/overwatch\n```\n\n### Importing\nImport in **ES6** module\n```ts\nimport overwatch from '@nasriya/overwatch';\n```\n\nImport in **CommonJS (CJS)**\n```js\nconst overwatch = require('@nasriya/overwatch').default;\n```\n___\n\n## Usage\n\n### 1. Defining watchers\n\n##### 📁 Watching Directories (Folders)\nUse `overwatch.watchFolder()` (recommended) or `overwatch.watch()` to watch a directory. You can optionally provide filters to include or exclude specific paths:\n\n```ts\n// Strongly recommended: use `watchFolder` for directories\nconst projectWatcher = await overwatch.watchFolder(process.cwd(), {\n   include: ['**/*.ts'], // Accepts globs, regex, or absolute paths\n   exclude: [/node_modules/, '**/*.test.ts'],\n});\n```\n\nOr without watching options:\n```ts\nconst projectWatcher = await overwatch.watchFolder(process.cwd());\n```\n\n##### 📄 Watching Files\nYou can also watch indivisual files:\n\n```ts\nconst fileWatcher = await overwatch.watchFile('src/config.json');\n```\n\n### 2. Handling events\nYou can attach a general handler for all change events:\n\n```ts\n// Handles all the watcher's events\nprojectWatcher.onChange(({ type, event }) =\u003e {\n    // Handle different event types\n    switch (type) {\n        case 'add':\n            console.log(`Added ${event.type}: ${event.path}`);\n            break;\n        case 'remove':\n            console.log(`Removed ${event.type}: ${event.path}`);\n            break;\n        case 'rename':\n            console.log(`Renamed ${event.type}: ${event.oldPath} -\u003e ${event.newPath}`);\n            break;\n        case 'update':\n            console.log(`Updated ${event.type}: ${event.path}`);\n            break;\n        case 'rootRemoved':\n            console.log(`Watcher root was deleted`);\n            break;\n    }\n\n    // NOTE: `event.type` is the type of the changed item, either `File` or `Folder`\n});\n```\n\nOr, register dedicated handlers for specific events:\n\n```ts\nprojectWatcher.onAdd((path) =\u003e {\n   console.log(`Added: ${path}`);\n});\n\nprojectWatcher.onRemove((event) =\u003e {\n   console.log(`${event.type} removed: ${event.path}`);\n});\n\nprojectWatcher.onRename((event) =\u003e {\n   console.log(`${event.type} renamed: ${event.oldPath} -\u003e ${event.newPath}`);\n});\n\nprojectWatcher.onUpdate((event) =\u003e {\n   console.log(`${event.type} updated: ${event.path}`);\n});\n```\n\nYou can also pass the handlers when you create the watcher:\n```ts\nconst projectWatcher = await overwatch.watchFolder(process.cwd(), {\n   include: ['**/*.ts'], // Accepts globs, regex, or absolute paths\n   exclude: [/node_modules/, '**/*.test.ts'],\n   onRename: (event) =\u003e {\n        console.log(`${event.type} renamed: ${event.oldPath} -\u003e ${event.newPath}`);\n   }\n});\n```\n\n### 3. Handling Root Deletion\nIf the root directory being watched is deleted, a special event is triggered:\n\n```ts\nprojectWatcher.onRootRemoved(() =\u003e {\n   console.log('The watched directory was deleted.');\n});\n```\n\n### Notes\n\n- ✅ `include` and `exclude` accept absolute paths, glob patterns (e.g., `'**/*.ts'`), and regular expressions (e.g., `/\\.test\\.ts$/`).\n- ✅ Prefer `watchFolder()` and `watchFile()` over the general `watch()` method for clearer intent and improved readability.\n- 📌 All watchers share a single internal engine — multiple watchers on the same path won't trigger redundant scans.\n- ⚠️ Filters (`include`, `exclude`) do **not** impact scanning performance; they only determine which changes are **emitted to the user**.\n- 📁 `event.type` refers to the type of the changed item — either `'File'` or `'Folder'`.\n- 🧠 Each watcher allows **only one handler per event type** — setting a new handler (e.g., via `onChange`) will **replace** the previous one.\n- 🚫 If the **root directory** being watched is deleted, the watcher is automatically removed, and a `rootRemoved` event is emitted.\n- ℹ️ The **root** is always a directory — even when watching a file, the root refers to its **parent folder**.\n- ⏸️ Use `overwatch.control.pause()` and `overwatch.control.resume()` to temporarily stop and restart the internal scanning engine without removing watchers.\n- 🔄 While paused, no file system changes are detected or emitted; resuming triggers an immediate scan and continues monitoring.\n- ✅ These control methods are safe to call multiple times and do not affect watcher registration or state.\n___\n## License\nThis software is licensed under the **Nasriya Open License (NOL)**, version 1.0.\nPlease read the license from [here](https://github.com/nasriyasoftware/Overwatch?tab=License-1-ov-file).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasriyasoftware%2Foverwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnasriyasoftware%2Foverwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnasriyasoftware%2Foverwatch/lists"}