{"id":16641841,"url":"https://github.com/samthor/sents","last_synced_at":"2025-12-27T04:05:27.663Z","repository":{"id":57372159,"uuid":"316874198","full_name":"samthor/sents","owner":"samthor","description":"Cross-platform filesystem watcher with zero dependencies","archived":false,"fork":false,"pushed_at":"2021-07-31T01:47:42.000Z","size":167,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-24T04:29:19.429Z","etag":null,"topics":["filesystem","library","nodejs","watch"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/samthor.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}},"created_at":"2020-11-29T04:17:40.000Z","updated_at":"2021-07-31T01:54:52.000Z","dependencies_parsed_at":"2022-09-10T02:11:07.220Z","dependency_job_id":null,"html_url":"https://github.com/samthor/sents","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fsents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fsents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fsents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fsents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samthor","download_url":"https://codeload.github.com/samthor/sents/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243164986,"owners_count":20246718,"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":["filesystem","library","nodejs","watch"],"created_at":"2024-10-12T07:48:03.815Z","updated_at":"2025-12-27T04:05:22.624Z","avatar_url":"https://github.com/samthor.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Test](https://github.com/samthor/sents/actions/workflows/node.js.yml/badge.svg)](https://github.com/samthor/sents)\n\nFilesystem watcher that uses `fs.watch` and friends (i.e., no polling).\n\n⚠️ **This is the library—check out [sents-cli](https://npmjs.com/package/sents-cli) to use this on the command-line.**\n\n# Features\n\n* Zero dependencies 🍩 and no native code\n* Supports macOS, Linux, Windows (and probably others) via the same API\n* Supports hard links (announces changes at all places inode is found)\n* Handles awkward renames on case-insensitive filesystems (\"foo\" =\u003e \"FOO\" is announced)\n\nIt does not support some features:\n\n* Following symlinks\n* Renames (instead announce delete/add\u0026mdash;what do renames mean in a world of hard links?)\n* Watching across volumes\n* And it should not be used on network shares (they need polling, every watcher hates these)\n\n# Usage\n\nBasic usage:\n\n```js\nimport buildWatcher from 'sents';\n\n// Create a watcher by passing a directory name (\".\" for the current dir).\nconst watcher = buildWatcher('.');\n\n// Type can be 'add', 'change', or 'remove'.\nwatcher.on('raw', (filename, type, ino) =\u003e {\n  console.warn(type.toUpperCase(), filename, ino);\n});\n\n// If the watcher emits an error, it's no longer usable.\nwatcher.on('error', (e) =\u003e {\n  console.warn('got error', e);\n});\n\n// Call .close() to shut down the watcher.\nsetTimeout(() =\u003e {\n  watcher.close();\n}, 60 * 1000);\n```\n\nNote that this watches a single _directory_, and directly watching files is not supported.\n\nThe only events emitted by `sents` are \"ready\", \"raw\", and \"error\".\n\n# Options\n\nThis also supports some options:\n\n```js\nconst watcher = buildWatcher('.', {\n  dotfiles: false,\n  filter: (rel) =\u003e true,\n  delay: 1000,\n});\n```\n\n* `dotfiles` controls whether files starting with '.' are returned (default `false`)\n* `filter` allows filtering of the results (return `true` to include, default includes all)\n  - When directories are passed, they'll end with `path.sep` (i.e., \"/\" most places); if you filter them, you'll _never_ be asked or notified about their subdirectories\n  - This should be a pure function—don't change results over time—otherwise, you're gonna have a bad time\n* `delay` allows you to delay and aggregate changes by ms (if unset, uses a microtask)\n\n# Notes\n\nOn macOS and Windows, watching a whole directory subtree is fairly cheap.\nOn Linux and other platforms, this package installs a watcher on every subdirectory.\nKeep this in mind when building tools using `sents`—be sure to use `filter` to limit what you're watching.\n\n## Ready Check\n\nIf you don't want to get all initial updates (i.e., the first scan of files) then you do either of:\n\n```js\nawait watcher.ready;\nwatcher.once('ready', () =\u003e {...});\n```\n\n## Glob Support\n\nThis doesn't have glob support or any built-in filtering aside the controls above.\nIf you want to write a command-line tool or similar, you should build a `filter` function that supports globs.\nCheck out [sents-cli](https://npmjs.com/package/sents-cli).\n\n## Files Only\n\nTechnically this package isn't a _file_ watcher, it's a _directory_ watcher (most files watchers are).\nIt's not more efficient to watch single files than it is a whole directory (since it has to be watched in case the file is removed).\nIf you just want to watch a small number of files for changes, be sure to allow them specifically in `filter`, while ignoring all other files or directories.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fsents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamthor%2Fsents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fsents/lists"}