Prepare for 1.2.0 release: bump version and add docs

Author: mrbbot

CHANGELOG.md

@@ -1,5 +1,37 @@
 # 🚧 Changelog
 
+## 1.2.0
+
+### Features
+
+- Added **Redis** persistence support for
+  [📦 KV](https://miniflare.dev/kv.html#persistence),
+  [✨ Cache](https://miniflare.dev/cache.html#persistence) and
+  [📌 Durable Objects](https://miniflare.dev/durable-objects.html#persistence)
+- Added support for loading scripts from `package.json`, closes
+  [issue #7](https://github.com/mrbbot/miniflare/issues/7). See
+  [💻 Using the CLI](https://miniflare.dev/cli.html#script-requirement) and
+  [⚡️ Developing with esbuild](https://miniflare.dev/recipes/esbuild.html#dependencies)
+  for more details.
+- Added `FormData` to the sandbox, closes
+  [issue #6](https://github.com/mrbbot/miniflare/issues/6)
+- Added an automatic update checker. See
+  [💻 Using the CLI](https://miniflare.dev/cli.html#update-checker) for more
+  details.
+- [📚 Modules](https://miniflare.dev/modules.html) mode is now always enabled
+  when specifying
+  [📌 Durable Objects](https://miniflare.dev/durable-objects.html##objects)
+  bindings
+
+### Fixes
+
+- Fixed **Windows** support, closes
+  [issue #10](https://github.com/mrbbot/miniflare/issues/10)
+- Fixed issue where scripts were not reloaded correctly when editing script path
+  in `wrangler.toml`. Scripts are now always reloaded on options change.
+  `Miniflare.reloadScript()` is now deprecated. You should use
+  `Miniflare.reloadOptions()` instead.
+
 ## 1.1.0
 
 ### Features
@@ -98,7 +130,7 @@
 - Fixed handling of `ignoreMethod` option for `Cache` `match` and `delete`
 - Disabled edge caching when using Workers Sites, files are now always loaded
   from disk
-- Provide `Set` and `WeakSet` from Miniflare's realm to sandbox, removing
+- Provided `Set` and `WeakSet` from Miniflare's realm to sandbox, removing
   `Promise`, so `(async () => {})() instanceof Promise` evaluates to `true`
 
 ## 0.1.1

README.md

@@ -51,7 +51,7 @@ $ miniflare worker.js --watch --debug
 [mf:dbg] - Scripts: worker.js
 [mf:dbg] Reloading worker.js...
 [mf:inf] Worker reloaded!
-[mf:dbg] Watching .env, worker.js, wrangler.toml...
+[mf:dbg] Watching .env, package.json, worker.js, wrangler.toml...
 [mf:inf] Listening on :8787
 [mf:inf] - http://127.0.0.1:8787
 ```
@@ -85,6 +85,7 @@ Options:
   -d, --debug             Log debug messages                           [boolean]
   -c, --wrangler-config   Path to wrangler.toml                         [string]
       --wrangler-env      Environment in wrangler.toml to use           [string]
+      --package           Path to package.json                          [string]
   -m, --modules           Enable modules                               [boolean]
       --modules-rule      Modules import rule (TYPE=GLOB)                [array]
       --build-command     Command to build project                      [string]
@@ -105,6 +106,7 @@ Options:
   -e, --env               Path to .env file                             [string]
   -b, --binding           Bind variable/secret (KEY=VALUE)               [array]
       --wasm              WASM module to bind (NAME=PATH)                [array]
+      --disable-updater   Disable update checker                       [boolean]
 ```
 
 ## Acknowledgements

docs/api.md

@@ -43,14 +43,15 @@ The [Guide](/fetch.html) goes into more detail on configuring specific features.
 
 <!--prettier-ignore-start-->
 ::: warning
-Like the CLI, the API will automatically load `.env` and `wrangler.toml` files
+Like the CLI, the API will automatically load `.env`, `package.json` and `wrangler.toml` files
 in the current working directory. This may lead to unexpected results. You can
-disable this by setting `envPath` and `wranglerConfigPath` options to paths of
+disable this by setting `envPath`, `packagePath` and `wranglerConfigPath` options to paths of
 empty files:
 
 ```js
 const mf = new Miniflare({
   envPath: ".env.empty",
+  packagePath: "package.empty.json", // Containing empty object: {}
   wranglerConfigPath: "wrangler.empty.toml"
 });
 ```
@@ -72,7 +73,7 @@ const mf = new Miniflare({
 });
 ```
 
-### Watching and Reloading
+### Watching, Reloading and Disposing
 
 You can watch scripts, `.env` files and `wrangler.toml` files with the `watch`
 option. When this is enabled, you must `dispose` of the watcher when you're done
@@ -86,13 +87,14 @@ const mf = new Miniflare({
 await mf.dispose();
 ```
 
+You must also `dispose` if you're persisting KV, cache, or Durable Object data
+in Redis to close opened connections.
+
 You can also manually reload scripts (main and Durable Object's) and options
-(`.env` and `wrangler.toml`) too with `reloadScript` and `reloadOptions`.
-Reloading scripts implicitly reloads options too:
+(`.env` and `wrangler.toml`) too with `reloadOptions`:
 
 ```js
 const mf = new Miniflare({ ... });
-await mf.reloadScript();
 await mf.reloadOptions();
 ```
 

docs/cache.md

@@ -27,29 +27,36 @@ await caches.open("cache_name");
 
 By default, cached data is stored in memory. It will persist between reloads,
 but not CLI invocations or different `Miniflare` instances. To enable
-persistence to the file system, specify the cache persistence option:
+persistence to the file system or Redis, specify the cache persistence option:
 
 ```shell
 $ miniflare --cache-persist # Defaults to ./mf/cache
 $ miniflare --cache-persist ./data/  # Custom path
+$ miniflare --cache-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
 cache_persist = true # Defaults to ./mf/cache
 cache_persist = "./data/" # Custom path
+cache_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
   cachePersist: true, // Defaults to ./mf/cache
   cachePersist: "./data", // Custom path
+  cachePersist: "redis://localhost:6379", // Redis server
 });
 ```
 
-Each namespace will get its own directory within the cache persistence
-directory.
+When using the file system, each namespace will get its own directory within the
+cache persistence directory.
+
+When using Redis, each key will be prefixed with the namespace. If you're using
+this with the API, make sure you call `dispose` on your `Miniflare` instance to
+close database connections.
 
 ## Manipulating Outside Workers
 

docs/cli.md

@@ -45,19 +45,6 @@ See [🛠 Builds](/builds.html) for more details.
 :::
 <!--prettier-ignore-end-->
 
-<!--prettier-ignore-start-->
-::: warning
-[📚 Modules](/modules.html) support currently requires the
-`--experimental-vm-modules` flag. This is enabled by default, but requires the
-`-S` flag of `/usr/bin/env`. If your operating system doesn't support the `-S`
-flag (e.g. Ubuntu 18.04), you can run the following instead:
-
-```shell
-$ node --experimental-vm-modules ./node_modules/.bin/miniflare worker.js
-```
-:::
-<!--prettier-ignore-end-->
-
 ### Watching and Debugging
 
 Add `--watch`/`-w` and `--debug`/`-d` flags to reload the worker whenever
@@ -70,16 +57,16 @@ $ miniflare worker.js --watch --debug
 [mf:dbg] - Scripts: worker.js
 [mf:dbg] Reloading worker.js...
 [mf:inf] Worker reloaded!
-[mf:dbg] Watching .env, worker.js, wrangler.toml...
+[mf:dbg] Watching .env, package.json, worker.js, wrangler.toml...
 [mf:inf] Listening on :8787
 [mf:inf] - http://127.0.0.1:8787
 ```
 
 ### Configuration Autoloading
 
-Note that `.env` and `wrangler.toml` files are also being watched. These files
-are always loaded automatically and configure your worker's environment in
-addition to the CLI flags. See the
+Note that `.env`, `package.json` and `wrangler.toml` files are also being
+watched. These files are always loaded automatically and configure your worker's
+environment in addition to the CLI flags. See the
 [Wrangler Configuration](#wrangler-configuration) reference below for more
 details, but as an example, with the following `wrangler.toml` file and
 `worker.js` files:
@@ -106,14 +93,34 @@ $ miniflare worker.js --wrangler-config wrangler.other.toml
 ### Script Requirement
 
 The only required option is the script to run. This can either be passed as a
-command line argument as we've been doing so far, or in a `wrangler.toml` file:
+command line argument as we've been doing so far, in a `wrangler.toml` file or
+in a `package.json` file. The command line argument takes priority, then the
+script in `wrangler.toml`, then the `main` or `module` field in `package.json`
+(depending on whether `modules` support is enabled):
 
 ```toml
+# wrangler.toml
 [build.upload]
 dir = "" # Defaults to "dist"
 main = "./worker.js"
 ```
 
+```json
+// package.json
+{
+  "main": "worker.js", // "service-worker" format
+  "module": "worker.mjs" // "modules" format
+}
+```
+
+### Update Checker
+
+The CLI includes an automatic update checker that looks for new versions of
+Miniflare once a day. As Cloudflare are always improving and tweaking workers,
+you should aim to install these promptly for improved compatibility with the
+real workers environment. You can disable this with the `--disable-updater`
+flag.
+
 ## Reference
 
 ### Flags
@@ -129,6 +136,7 @@ Options:
   -d, --debug             Log debug messages                           [boolean]
   -c, --wrangler-config   Path to wrangler.toml                         [string]
       --wrangler-env      Environment in wrangler.toml to use           [string]
+      --package           Path to package.json                          [string]
   -m, --modules           Enable modules                               [boolean]
       --modules-rule      Modules import rule (TYPE=GLOB)                [array]
       --build-command     Command to build project                      [string]
@@ -149,6 +157,7 @@ Options:
   -e, --env               Path to .env file                             [string]
   -b, --binding           Bind variable/secret (KEY=VALUE)               [array]
       --wasm              WASM module to bind (NAME=PATH)                [array]
+      --disable-updater   Disable update checker                       [boolean]
 ```
 
 ### Wrangler Configuration

docs/durable-objects.md

@@ -48,40 +48,47 @@ const mf = new Miniflare({
 ```
 
 <!--prettier-ignore-start-->
-::: warning
-Durable Objects require the `modules` option to be enabled. This is enabled
-automatically if Durable Object bindings are specified in `wrangler.toml`.
-See [📚 Modules](/modules.html) for more details.
+::: tip
+The `modules` option is automatically enabled when specifying Durable Object
+bindings. See [📚 Modules](/modules.html) for more details.
 :::
 <!--prettier-ignore-end-->
 
 ## Persistence
 
 By default, Durable Object data is stored in memory. It will persist between
 reloads, but not CLI invocations or different `Miniflare` instances. To enable
-persistence to the file system, specify the Durable Object persistence option:
+persistence to the file system or Redis, specify the Durable Object persistence
+option:
 
 ```shell
 $ miniflare --do-persist # Defaults to ./mf/do
 $ miniflare --do-persist ./data/  # Custom path
+$ miniflare --do-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
 durable_objects_persist = true # Defaults to ./mf/do
 durable_objects_persist = "./data/" # Custom path
+durable_objects_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
   durableObjectsPersist: true, // Defaults to ./mf/do
   durableObjectsPersist: "./data", // Custom path
+  durableObjectsPersist: "redis://localhost:6379", // Redis server
 });
 ```
 
-Each object instance will get its own directory within the Durable Object
-persistence directory.
+When using the file system, each object instance will get its own directory
+within the Durable Object persistence directory.
+
+When using Redis, each key will be prefixed with the object name and instance.
+If you're using this with the API, make sure you call `dispose` on your
+`Miniflare` instance to close database connections.
 
 ## Manipulating Outside Workers
 

docs/fetch.md

@@ -81,6 +81,23 @@ console.log(waitUntil[0]); // 1
 console.log(waitUntil[1]); // "2"
 ```
 
+When using the API to dispatch events, you are responsible for adding
+[`CF-*` headers](https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-Cloudflare-handle-HTTP-Request-headers-)
+and the
+[`cf` object](https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties).
+This lets you control their values for testing:
+
+```js
+const res = await mf.dispatchFetch("http://localhost:8787", {
+  headers: {
+    "CF-IPCountry": "GB",
+  },
+  cf: {
+    country: "GB",
+  },
+});
+```
+
 ## Upstream
 
 Miniflare will call each `fetch` listener until a response is returned. If no

docs/kv.md

@@ -50,31 +50,39 @@ user's computer) so it doesn't really mean anything.
 
 By default, KV data is stored in memory. It will persist between reloads, but
 not CLI invocations or different `Miniflare` instances. To enable persistence to
-the file system, specify the KV persistence option:
+the file system or Redis, specify the KV persistence option:
 
 ```shell
 $ miniflare --kv-persist # Defaults to ./mf/kv
 $ miniflare --kv-persist ./data/  # Custom path
+$ miniflare --kv-persist redis://localhost:6379  # Redis server
 ```
 
 ```toml
 # wrangler.toml
 [miniflare]
 kv_persist = true # Defaults to ./mf/kv
 kv_persist = "./data/" # Custom path
+kv_persist = "redis://localhost:6379" # Redis server
 ```
 
 ```js
 const mf = new Miniflare({
   kvPersist: true, // Defaults to ./mf/kv
   kvPersist: "./data", // Custom path
+  kvPersist: "redis://localhost:6379", // Redis server
 });
 ```
 
-Each namespace will get its own directory within the KV persistence directory.
-Key names are sanitised before data is read/written. Metadata is stored in files
-with a `.meta.json` suffix. These also contain original key names, so they can
-be returned when listing keys.
+When using the file system, each namespace will get its own directory within the
+KV persistence directory. Key names are sanitised before data is read/written.
+Metadata is stored in files with a `.meta.json` suffix. These also contain
+original key names, so they can be returned when listing keys.
+
+When using Redis, each key will be prefixed with the namespace and `:value:`.
+Metadata will be prefixed with the namespace and `:meta:`. If you're using this
+with the API, make sure you call `dispose` on your `Miniflare` instance to close
+database connections.
 
 ## Manipulating Outside Workers
 

docs/recipes/esbuild.md

@@ -15,11 +15,12 @@ $ npm init -y
 $ npm install -D esbuild miniflare
 ```
 
-Update the `scripts` field in `package.json` to the following:
+Update the `main` and `scripts` fields in `package.json` to the following:
 
 ```json
 {
-  ...
+  ...,
+  "main": "./dist/index.js",
   "scripts": {
     "build": "esbuild --bundle --sourcemap --outdir=dist ./src/index.js",
     "dev": "miniflare --watch --debug"
@@ -47,7 +48,6 @@ kv_namespaces = [
 command = "npm run build"
 [build.upload]
 format = "service-worker"
-main = "./index.js"
 ```
 
 ## Worker Script