{"id":22221935,"url":"https://github.com/fabiospampinato/pollex","last_synced_at":"2025-07-27T16:31:49.023Z","repository":{"id":178174920,"uuid":"661456276","full_name":"fabiospampinato/pollex","owner":"fabiospampinato","description":"A tiny polling-based filesystem watcher that tries to be efficient.","archived":false,"fork":false,"pushed_at":"2024-04-04T23:03:36.000Z","size":13,"stargazers_count":27,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-27T13:03:44.235Z","etag":null,"topics":["esbuild","filesystem","poll","polling","tiny","watcher"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/fabiospampinato.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},"funding":{"github":"fabiospampinato","custom":"https://www.paypal.me/fabiospampinato"}},"created_at":"2023-07-02T22:41:33.000Z","updated_at":"2023-12-11T16:09:53.000Z","dependencies_parsed_at":"2024-08-23T01:13:45.465Z","dependency_job_id":"3fce6627-eeb2-4b69-93a5-57118f389912","html_url":"https://github.com/fabiospampinato/pollex","commit_stats":{"total_commits":12,"total_committers":1,"mean_commits":12.0,"dds":0.0,"last_synced_commit":"eeb7bdd1bbead6ebbd12b38e7f59c5ff71f22605"},"previous_names":["fabiospampinato/pollex"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fpollex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fpollex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fpollex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabiospampinato%2Fpollex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabiospampinato","download_url":"https://codeload.github.com/fabiospampinato/pollex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227817017,"owners_count":17824200,"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":["esbuild","filesystem","poll","polling","tiny","watcher"],"created_at":"2024-12-02T23:16:17.499Z","updated_at":"2024-12-02T23:16:18.064Z","avatar_url":"https://github.com/fabiospampinato.png","language":"TypeScript","funding_links":["https://github.com/sponsors/fabiospampinato","https://www.paypal.me/fabiospampinato"],"categories":[],"sub_categories":[],"readme":"# Pollex\n\nA tiny polling-based filesystem watcher that tries to be efficient.\n\nThis is a port of the idea behind [`esbuild`](https://esbuild.github.io/api/#watch)'s filesystem watcher, which uses polling but more efficiently than using it naively.\n\n## Features\n\nUnless you really want this I'd recommend using a [normal](https://github.com/fabiospampinato/watcher) filesystem watcher instead, since polling can get expensive.\n\n- Changes happening inside the root folder should get picked up roughly within `options.pollingIntervalCold / 2` milliseconds on average.\n- Changes happening inside files that the watcher already saw changing should get picked up roughly within `options.pollingIntervalHot / 2` milliseconds on average.\n- Basically files that changed already are considered hot and polled frequently, while random subsets of the other files are polled infrequently.\n- This should be roughly `options.pollingIntervalCold / options.pollingIntervalHot` times cheaper than just polling every file on a `options.pollingIntervalHot` interval.\n\nIn some niche scenarios a filesystem watcher that works like this could be useful:\n\n- It doesn't rely on potentially buggy native filesystem watching APIs, it just needs to be able to fire `stat` syscalls.\n- It works even over filesystems for which a native watching API is not available.\n- It doesn't run out of file descriptors, because it doesn't keep any open indefinitely.\n- It can potentially be used to react to filesystem events quicker than it's possible with `fs.watch` in Node, which is weirdly slow.\n- It's about 20x smaller than [`chokidar`](https://github.com/paulmillr/chokidar), with no third-party dependencies, and a way simpler implementation.\n\n## Install\n\n```sh\nnpm install --save pollex\n```\n\n## Usage\n\n```ts\nimport pollex from 'pollex';\n\n// Let's define some options\n\nconst pollexOptions = {\n  depth: 20, // Maximum depth to look at\n  limit: 1_000_000, // Maximum number of files explored, useful as a stop gap in some edge cases\n  followSymlinks: true, // Whether to follow symlinks or not\n  ignore: targetPath =\u003e /node_modules/.test ( targetPath ), // Function that if returns true will ignore this particular file or a directory and its descendants\n  ignoreInitial: true, // Ignore the initial \"add\" and \"addDir\" events while the folder is being scanned the first time\n  ignoreReady: true, // Ignore the \"ready\" event, useful in combination with \"ignoreInitial: true\" to only get notified about actual changes\n  pollingIntervalCold: 2000, // Poll all cold files, in different random subsets, within this amount of time, roughly\n  pollingIntervalHot: 50 // Poll all hot files within this amount of time, roughly\n};\n\n// Let's listen for events\n\npollex ( process.cwd (), ( event, targetPath ) =\u003e {\n\n  if ( event === 'add' ) {\n\n    // The file at \"targetPath\" got added\n\n  } else if ( event === 'addDir' ) {\n\n    // The folder at \"targetPath\" got added\n\n  } else if ( event === 'change' ) {\n\n    // The file at \"targetPath\" changed\n\n  } else if ( event === 'ready' ) {\n\n    // The initial scan has been done and all initial events have been emitted\n\n  } else if ( event === 'unlink' ) {\n\n    // The file at \"targetPath\" got deleted\n\n  } else if ( event === 'unlinkDir' ) {\n\n    // The folder at \"targetPath\" got deleted\n\n  }\n\n}, pollexOptions );\n```\n\n## License\n\nMIT © Fabio Spampinato\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fpollex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabiospampinato%2Fpollex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabiospampinato%2Fpollex/lists"}