https://github.com/eibens/wsfs
WebSocket server (ws) that broadcasts file system (fs) events to its clients.
https://github.com/eibens/wsfs
deno events fs server typescript web websocket
Last synced: about 2 months ago
JSON representation
WebSocket server (ws) that broadcasts file system (fs) events to its clients.
- Host: GitHub
- URL: https://github.com/eibens/wsfs
- Owner: eibens
- License: mit
- Created: 2021-06-16T08:05:00.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-23T19:29:14.000Z (about 5 years ago)
- Last Synced: 2025-05-27T00:11:23.897Z (about 1 year ago)
- Topics: deno, events, fs, server, typescript, web, websocket
- Language: TypeScript
- Homepage:
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [wsfs]
> [wsfs] starts a WebSocket server (ws) that broadcasts file system (fs) events
> to its clients. It is implemented in TypeScript for [Deno].
[![License][license-shield]](LICENSE) [![Deno doc][deno-doc-shield]][deno-doc]
[![Deno module][deno-land-shield]][deno-land]
[![Github tag][github-shield]][github] [![Build][build-shield]][build]
[![Code coverage][coverage-shield]][coverage]
# Motivation
For developing websites or web-based applications, it can sometimes be useful if
one can use the web-browser to access information from a file system. For
example, an automatic reload can be triggered when source files change, or a
file listing can be updated when new files are added in a cloud storage app.
There is no native API that allows a web-browser to watch a file system. [wsfs]
implements a protocol for collecting and broadcasting that information to
clients. Building on the WebSocket protocol further guarantees that updates can
be delivered quickly and frequently.
# Scenarios
- You are developing a website in a source code editor. In order to see the
changes, you have to manually reload the website in the web-browser. By
running `wsfs` in the directory and listening to the WebSocket server in a
`` element, automatic reloads can be triggered after every change.
- You are deploying a web app that allows users to upload files to a shared
folder. The users have to reload the file listing to see whether another user
has changed the contents of the folder. By running `wsfs` on the server users
can be notified automatically.
# [cli.ts]
The CLI serves as (1) a convenient way of using [wsfs] in practice, and (2) as
an application example for [mod.ts]. Usage and installation instructions can be
printed in a terminal with [deno]:
```sh
deno run https://deno.land/x/wsfs/cli.ts --help
```
# [serve.ts]
The `serve` function returns a `Server` object. If successful, it starts two
processes: (1) the WebSocket server and (2) the file watcher. Both can be shut
down with the `Server.close` function:
```ts
import { serve, Server } from "https://deno.land/x/wsfs/serve.ts";
// Start server.
const server: Server = serve();
// Print server URL.
console.log(server.url);
// Shut down the server at some point.
await server.close();
```
A `ServeOptions` object can be specified to configure the server. All entries
are optional:
```ts
import { Event, serve, ServeOptions } from "./serve.ts";
const options: ServeOptions = {
// Default settings for starting the server at: ws://localhost:1234
hostname: "localhost",
port: 1234,
// Specify the path to observe.
path: ".",
// Handle server events.
handle: (e: Event) => console.log(e),
};
const server = serve(options);
await server.close();
```
# That's it!
[wsfs on GitHub][github]
[wsfs]: #
[eibens/wsfs on GitHub]: https://github.com/eibens/wsfs
[cli.ts]: cli.ts
[serve.ts]: serve.ts
[deno]: https://deno.land
<!-- badges -->
[github]: https://github.com/eibens/wsfs
[github-shield]: https://img.shields.io/github/v/tag/eibens/wsfs?label&logo=github
[coverage-shield]: https://img.shields.io/codecov/c/github/eibens/wsfs?logo=codecov&label
[license-shield]: https://img.shields.io/github/license/eibens/wsfs?color=informational
[coverage]: https://codecov.io/gh/eibens/wsfs
[build]: https://github.com/eibens/wsfs/actions/workflows/ci.yml
[build-shield]: https://img.shields.io/github/workflow/status/eibens/wsfs/ci?logo=github&label
[deno-doc]: https://doc.deno.land/https/deno.land/x/wsfs/mod.ts
[deno-doc-shield]: https://img.shields.io/badge/doc-informational?logo=deno
[deno-land]: https://deno.land/x/wsfs
[deno-land-shield]: https://img.shields.io/badge/x/wsfs-informational?logo=deno&label