Add descriptions and examples to READMEs

Author: mrbbot

packages/cache/README.md

@@ -1,4 +1,24 @@
 # `@miniflare/cache`
 
 Cache module for [Miniflare](https://github.com/cloudflare/miniflare): a fun,
-full-featured, fully-local simulator for Cloudflare Workers
+full-featured, fully-local simulator for Cloudflare Workers. See
+[✨ Cache](https://miniflare.dev/cache.html) for more details.
+
+## Example
+
+```js
+import { Cache } from "@miniflare/cache";
+import { Response } from "@miniflare/core";
+import { MemoryStorage } from "@miniflare/storage-memory";
+
+const cache = new Cache(new MemoryStorage());
+
+const key = "http://localhost";
+const res = new Response("body", {
+  headers: { "Cache-Control": "max-age=3600" },
+});
+await cache.put(key, res);
+
+const cachedRes = await cache.match(key);
+console.log(await cachedRes.text()); // body
+```

packages/cli-parser/README.md

@@ -2,4 +2,25 @@
 
 CLI option parsing module for
 [Miniflare](https://github.com/cloudflare/miniflare): a fun, full-featured,
-fully-local simulator for Cloudflare Workers
+fully-local simulator for Cloudflare Workers. See
+[💻 Using the CLI](https://miniflare.dev/cli.html) for more details.
+
+## Example
+
+```js
+import { buildHelp, parseArgv } from "@miniflare/cli-parser";
+import { BuildPlugin } from "@miniflare/core";
+import { KVPlugin } from "@miniflare/kv";
+
+const plugins = { BuildPlugin, KVPlugin };
+
+const help = buildHelp(plugins, "exec");
+console.log(help); // Usage: exec ...
+
+const options = parseArgv(plugins, [
+  "--build-command",
+  "npm run build",
+  "--kv-persist",
+]);
+console.log(options); // { buildCommand: "npm run build", kvPersist: true };
+```

packages/core/README.md

@@ -1,4 +1,49 @@
 # `@miniflare/core`
 
 Core module for [Miniflare](https://github.com/cloudflare/miniflare): a fun,
-full-featured, fully-local simulator for Cloudflare Workers
+full-featured, fully-local simulator for Cloudflare Workers. See
+[🧰 Using the API](https://miniflare.dev/api.html) for more details.
+
+## Example
+
+```js
+import { CorePlugin, MiniflareCore } from "@miniflare/core";
+import { KVPlugin } from "@miniflare/kv";
+import { VMScriptRunner } from "@miniflare/runner-vm";
+import { Log, LogLevel } from "@miniflare/shared";
+import { MemoryStorage } from "@miniflare/storage-memory";
+
+export class StorageFactory {
+  storages = new Map();
+
+  storage(namespace) {
+    let storage = this.storages.get(namespace);
+    if (storage) return storage;
+    this.storages.set(namespace, (storage = new MemoryStorage()));
+    return storage;
+  }
+}
+
+const plugins = { CorePlugin, KVPlugin };
+const ctx = {
+  log: new Log(LogLevel.INFO),
+  storageFactory: new StorageFactory(),
+  scriptRunner: new VMScriptRunner(),
+};
+
+const mf = new MiniflareCore(plugins, ctx, {
+  modules: true,
+  script: `export default {
+    async fetch(request, env) {
+      return new Response(await env.TEST_NAMESPACE.get("key"));
+    }
+  }`,
+  kvNamespaces: ["TEST_NAMESPACE"],
+});
+
+const { TEST_NAMESPACE } = await mf.getBindings();
+await TEST_NAMESPACE.put("key", "value");
+
+const res = await mf.dispatchFetch("http://localhost");
+console.log(await res.text()); // value
+```

packages/durable-objects/README.md

@@ -1,4 +1,17 @@
 # `@miniflare/durable-objects`
 
 Durable Objects module for [Miniflare](https://github.com/cloudflare/miniflare):
-a fun, full-featured, fully-local simulator for Cloudflare Workers
+a fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[📌 Durable Objects](https://miniflare.dev/durable-objects.html) for more
+details.
+
+## Example
+
+```js
+import { DurableObjectStorage } from "@miniflare/durable-objects";
+import { MemoryStorage } from "@miniflare/storage-memory";
+
+const storage = new DurableObjectStorage(new MemoryStorage());
+await storage.put("key", "value");
+console.log(await storage.get("key")); // value
+```

packages/html-rewriter/README.md

@@ -1,4 +1,22 @@
 # `@miniflare/html-rewriter`
 
 HTMLRewriter module for [Miniflare](https://github.com/cloudflare/miniflare): a
-fun, full-featured, fully-local simulator for Cloudflare Workers
+fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[📄 HTMLRewriter](https://miniflare.dev/html-rewriter.html) for more details.
+
+## Example
+
+```js
+import { Response } from "@miniflare/core";
+import { HTMLRewriter } from "@miniflare/html-rewriter";
+
+const rewriter = new HTMLRewriter().on("p", {
+  element(element) {
+    element.setInnerContent("new");
+  },
+});
+
+const res = new Response("<p>old</p>");
+const transformed = rewriter.transform(res);
+console.log(await transformed.text()); // <p>new</p>
+```

packages/http-server/README.md

@@ -1,4 +1,60 @@
 # `@miniflare/http-server`
 
 HTTP server module for [Miniflare](https://github.com/cloudflare/miniflare): a
-fun, full-featured, fully-local simulator for Cloudflare Workers
+fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[🧰 Using the API](https://miniflare.dev/api.html) for more details.
+
+## Example
+
+```js
+import { CorePlugin, MiniflareCore } from "@miniflare/core";
+import {
+  HTTPPlugin,
+  convertNodeRequest,
+  createServer,
+  startServer,
+} from "@miniflare/http-server";
+import { VMScriptRunner } from "@miniflare/runner-vm";
+import { Log, LogLevel } from "@miniflare/shared";
+import { MemoryStorage } from "@miniflare/storage-memory";
+import http from "http";
+
+// Converting Node.js http.IncomingMessage to Miniflare's Request
+http.createServer(async (nodeReq, nodeRes) => {
+  const req = await convertNodeRequest(nodeReq, "http://upstream", {
+    forwardedProto: "http",
+    realIp: "127.0.0.1",
+    cf: { colo: "SFO" },
+  });
+  nodeRes.end(await req.text());
+});
+
+// Creating and starting HTTP servers
+export class BadStorageFactory {
+  storage() {
+    throw new Error("This example shouldn't need storage!");
+  }
+}
+
+const plugins = { CorePlugin, HTTPPlugin };
+const ctx = {
+  log: new Log(LogLevel.INFO),
+  storageFactory: new BadStorageFactory(),
+  scriptRunner: new VMScriptRunner(),
+};
+
+const mf = new MiniflareCore(plugins, ctx, {
+  modules: true,
+  script: `export default {
+    async fetch(request, env) {
+      return new Response("body");
+    }
+  }`,
+  port: 5000,
+});
+
+// Start the server yourself...
+const server = await createServer(mf);
+// ...or get Miniflare to start it for you, logging to port
+const server2 = await startServer(mf);
+```

packages/jest-environment-miniflare/README.md

@@ -1,4 +1,11 @@
 # `@miniflare/jest`
 
 Jest testing module for [Miniflare](https://github.com/cloudflare/miniflare): a
-fun, full-featured, fully-local simulator for Cloudflare Workers
+fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[🤹 Jest Environment ](https://v2.miniflare.dev/jest.html) for more details.
+
+## Example
+
+See
+[this repository](https://github.com/mrbbot/miniflare-typescript-esbuild-jest)
+for an example using TypeScript.

packages/kv/README.md

@@ -1,4 +1,16 @@
 # `@miniflare/kv`
 
 Workers KV module for [Miniflare](https://github.com/cloudflare/miniflare): a
-fun, full-featured, fully-local simulator for Cloudflare Workers
+fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[📦 KV](https://miniflare.dev/kv.html) for more details.
+
+## Example
+
+```js
+import { KVNamespace } from "@miniflare/kv";
+import { MemoryStorage } from "@miniflare/storage-memory";
+
+const ns = new KVNamespace(new MemoryStorage());
+await ns.put("key", "value");
+console.log(await ns.get("key")); // value
+```

packages/runner-vm/README.md

@@ -2,4 +2,40 @@
 
 VM script runner module for
 [Miniflare](https://github.com/cloudflare/miniflare): a fun, full-featured,
-fully-local simulator for Cloudflare Workers
+fully-local simulator for Cloudflare Workers.
+
+## Example
+
+```js
+import { VMScriptRunner } from "@miniflare/runner-vm";
+
+const runner = new VMScriptRunner();
+// Pass `console` into sandbox
+const globalScope = { console };
+
+// Run regular script
+const blueprint1 = {
+  code: 'console.log("hello")',
+  filePath: "test.js",
+};
+await runner.run(globalScope, blueprint1); // hello
+
+// Run module script
+const blueprint2 = {
+  code: 'import thing from "./thing.js"; console.log(thing);',
+  filePath: "test.mjs",
+};
+const moduleRules = [{ type: "ESModule", include: /\.js$/ }];
+// Assuming thing.js contains `"export default "thing";`...
+await runner.run(globalScope, blueprint2, moduleRules); // thing
+
+// Run module script with additional module
+const blueprint3 = {
+  code: `import additional from "__ADDITIONAL"; console.log(additional);`,
+  filePath: "test.mjs",
+};
+const modules = {
+  __ADDITIONAL: { default: "stuff" },
+};
+await runner.run(globalScope, blueprint3, moduleRules, modules); // stuff
+```

packages/scheduler/README.md

@@ -1,4 +1,40 @@
 # `@miniflare/scheduler`
 
 Scheduler module for [Miniflare](https://github.com/cloudflare/miniflare): a
-fun, full-featured, fully-local simulator for Cloudflare Workers
+fun, full-featured, fully-local simulator for Cloudflare Workers. See
+[⏰ Scheduled Events](https://miniflare.dev/scheduled.html) for more details.
+
+## Example
+
+```js
+import { CorePlugin, MiniflareCore } from "@miniflare/core";
+import { VMScriptRunner } from "@miniflare/runner-vm";
+import { Log, LogLevel } from "@miniflare/shared";
+import { SchedulerPlugin, startScheduler } from "@miniflare/scheduler";
+import { MemoryStorage } from "@miniflare/storage-memory";
+
+export class BadStorageFactory {
+  storage() {
+    throw new Error("This example shouldn't need storage!");
+  }
+}
+const plugins = { CorePlugin, SchedulerPlugin };
+const ctx = {
+  log: new Log(LogLevel.INFO),
+  storageFactory: new BadStorageFactory(),
+  scriptRunner: new VMScriptRunner(),
+};
+
+const mf = new MiniflareCore(plugins, ctx, {
+  modules: true,
+  script: `export default {
+    async scheduled(request, env) {
+      console.log("tick");
+    }
+  }`,
+  crons: ["* * * * *"],
+});
+
+const scheduler = await startScheduler(mf); // tick, tick, tick, ...
+scheduler.dispose();
+```