@fastly/expressly 1.0.1-0 → 1.1.0

package/docs/docs/handling-data/search-params.md

@@ -1,45 +0,0 @@
----
-sidebar_position: 5
----
-
-# Query strings
-
-Search (query string) parameters can be accessed in the `req.query` object, which implements the [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) interface.
-
-## Get the value of a search parameter
-
-Use `req.query.get(key)` to get the first value associated with a given search parameter. If you need to check whether a parameter is set, use `*.query.has(name)`:
-
-```javascript
-router.get("/page", (req, res) => {
-  if (req.query.has("id")) {
-    res.send(`Your page id is: ${req.query.get("id")}`)
-  } else {
-    res.send("No id! Add one like this: /page?id=123")
-  }
-})
-```
-
-> 💡 You can use `req.query.getAll(key)` to get all the values of query string array.
-
-## Listing search parameters
-
-Use `req.query.entries()` method to iterate through all key/value pairs in the same order as they appear in the query string.
-
-```javascript
-for (const [key, value] of req.query.entries()) {
-    console.log(`Query parameter: ${key}`, value);
-}
-```
-
-If you need only the keys or values, use `req.query.keys()` or `req.query.values()`, respectively.
-
-## Manipulating query strings
-
-`req.query` is a [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object. You can use a bunch of utility methods to work with query parameters:
-
-* **req.query.set(name, value)** sets the value of a given search parameter.
-* **req.query.append(name, value)** appends a new search parameter.
-* **req.query.delete(name)** removes a search parameter and its value(s).
-* **req.query.sort()** sorts all query string parameters by name.
-* **req.query.toString()** returns a serialized query string suitable for use in a URL.

package/docs/docs/intro.md

@@ -1,61 +0,0 @@
----
-sidebar_position: 1
----
-
-# Getting started
-
-Discover **expressly** _in less than 5 minutes_.
-
----
-
-First, head over to [developer.fastly.com](https://developer.fastly.com) to get started with JavaScript on Fastly's Compute@Edge:
-
-1. Learn about Compute@Edge: [developer.fastly.com/learning/compute/](https://developer.fastly.com/learning/compute/)
-2. Create your first JavaScript app: [developer.fastly.com/learning/compute/javascript/](https://developer.fastly.com/learning/compute/javascript/)
-
-## Install expressly
-
-Install expressly from the [npm registry](https://www.npmjs.com/package/@fastly/expressly):
-
-```shell
-npm i @fastly/expressly
-```
-
-```shell
-yarn add @fastly/expressly
-```
-
-## Your first expressly app
-
-Replace the contents of your Compute@Edge app's `src/index.js` with the following:
-
-```javascript
-import { Router } from "@fastly/expressly";
-
-const router = new Router();
-
-router.get("/", async (req, res) => {
-  return res.send("Hello world!");
-});
-
-router.listen();
-```
-
-## Try it out
-
-Start your app locally:
-
-```shell
-fastly compute serve
-```
-
-This will start your service on [http://localhost:7676](http://localhost:7676).
-
-### Live reloading
-
-You can use a tool called [`nodemon`](https://www.npmjs.com/package/nodemon) to automatically reload your app when you make a change in your local development environment.
-
-```shell
-npx nodemon --exec \
-  "npm run build && fastly compute serve --skip-build"
-```

package/docs/docs/middleware/_category_.json

@@ -1,5 +0,0 @@
-{
-    "label": "Middleware",
-    "position": 5
-  }
-  

package/docs/docs/middleware/controlling-flow.md

@@ -1,41 +0,0 @@
----
-sidebar_position: 2
----
-
-# Controlling flow
-
-**expressly** allows you to control the flow of a request with middleware.
-
-For example, you could edit the Request object:
-
-```javascript
-router.use((req, res) => {
-  if (req.url.pathname == "/") {
-    req.url.pathname = "/home";
-  }
-});
-```
-
-This will **not** redirect the user; instead, it will affect the route selection logic downstream. In this case, a subsequent `router.get("/")` will not match the request, but `router.get("/home")` will.
-
-## Stopping a request
-
-If you need to end the response process early (for example, in order to block unauthenticated requests), you can call [`res.end`](../handling-data/response.md#resend) (or [`res.send`](../handling-data/response.md#ressend)) from middleware. 
-
-```javascript
-router.use("/account/", (req, res) => {
-  if(!("userId" in req.cookies)){
-    res.end("You must be logged in to view this page");
-  }
-});
-```
-
-You can also end the response process by _redirecting_ to a different route:
-
-```javascript
-router.use("/account/", (req, res) => {
-  if(!("userId" in req.cookies)){
-    res.redirect("/login");
-  }
-});
-```

package/docs/docs/middleware/error-middleware.md

@@ -1,41 +0,0 @@
----
-sidebar_position: 3
-title: Handling errors
----
-
-# Error middleware
-
-**expressly** catches and processes errors that occur both synchronously and asynchronously. 
-
-```javascript
-router.get("/", (req, res) => {
-  throw new Error("BROKEN"); // expressly will catch this.
-})
-```
-
-## The default error handler
-
-**expressly** comes with a built-in error handler that takes care of any errors that might be encountered in the app. This [default error-handling middleware](https://github.com/fastly/expressly/blob/main/src/lib/routing/router.ts#L12) function is added at the end of the router stack, after all other middleware and request handlers.
-
-## Error-handling middleware
-
-You can define custom error-handling middleware functions in the same way as other middleware functions, except with **three** arguments instead of two, specifically with the signature `(err, req, res)`.
-
-The example below shows how to use error middleware to serve a custom error page:
-
-```javascript
-router.use((err, req, res) => {
-  console.error(err);
-  res.withStatus(500).send(`Uh-oh! Something went wrong: ${e.message}`);
-});
-```
-
-If you only want error middleware to run on specific routes, you can pass a path to the middleware:
-
-```javascript
-router.use("/api/(.*)", (err, req, res) => {
-  console.log("Errored on handling a request to the API!");
-});
-```
-
-> **expressly** uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) to [pattern-match routes](../routing.md#route-matching).

package/docs/docs/middleware/what-is-middleware.md

@@ -1,31 +0,0 @@
----
-sidebar_position: 1
----
-
-# What is middleware?
-
-Middleware allows you to run code on a request before any routes are run. This is useful for things like authentication, header manipulation, and anything else that needs to happen before your routes are handled. 
-
-## router.use()
-
-Middleware is attached by calling the `router.use()` method.
-
-The example below shows how to use middleware to add a header to all requests:
-
-```javascript
-router.use((req, res) => {
-  res.setHeader("x-powered-by", "expressly");
-});
-```
-
-> 🚨 **Unlike Express**, middleware accept only two arguments, `req` and `res`. **expressly** does away with the `next` function; all errors are caught and handled by [error middleware](error-middleware.md). 
-
-If you only want middleware to run on specific routes, you can pass a path to the middleware:
-
-```javascript
-router.use("/api/(.*)", (req, res) => {
-  console.log("Got a request to the API!");
-});
-```
-
-> **expressly** uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) to [pattern-match routes](../routing.md#route-matching). This means that your middleware mount paths can contain wildcards and even regular expressions. 

package/docs/docs/origin-data/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Origin data",
-  "position": 6
-}

package/docs/docs/origin-data/working-with-origins.md

@@ -1,49 +0,0 @@
----
-sidebar_position: 1
----
-
-# Working with origins
-
-Accessing data from origins is done via the standard Fetch API available in Compute@Edge. [Read more on developer.fastly.com.](https://developer.fastly.com/learning/compute/javascript/#communicating-with-backend-servers-and-the-fastly-cache)
-
-## Performance
-
-> 💡 The most efficient way of proxying data from your origin to the client is to ensure you do not consume the body in your code. 
-
-Below, a `fetch()` request is made to an origin and the entire Response object passed through to `res.send()`. Doing this avoids reading the content of the response which saves processing time and memory.
-
-```javascript
-router.get("/origin", async (req, res) => {
-  res.send(await fetch(
-    "https://example.com", { backend: "my-origin" }
-  ));
-});
-```
-
-### `req` and `res`
-
-`req` and `res` are compatible with anything that expects a `Request` or `Response`. It's therefore possible to pass `req` directly to `fetch()`, for example:
-
-```javascript
-router.get("/origin", async (req, res) => {
-  res.send(await fetch(
-    req, { backend: "my-origin" }
-  ));
-});
-```
-
-## Reading a response
-
-If you need to read the body of a response, you can do so like this:
-
-```javascript
-router.get("/api", async (req, res) => {
-  let originRequest = await fetch(
-    "https://example.com", { backend: "my-origin" }
-  );
-
-  let body = await originRequest.text();
-
-  res.send(`Body had a length of ${body.length}`);
-});
-```

package/docs/docs/routing.md

@@ -1,163 +0,0 @@
----
-sidebar_position: 3
----
-
-# Routing
-
-**expressly** provides the `Router` object which stores configuration for your routing. Create a new router like this:
-
-```javascript
-import { Router } from "@fastly/expressly";
-
-const router = new Router();
-```
-
-> 💡 `Router` supports additional [configuration](config.md).
-
-## Creating a route
-
-Then add a route by calling `router.HTTP_METHOD(PATH, handler)`. Adding a route for `GET` requests to `/hello-world` looks like this:
-
-```javascript
-router.get("/hello-world", (req, res) => {
-  res.send("Hello world!");
-});
-```
-
-In the example above, if a request is made to the `/hello-world` path, your handler will run and return "Hello world!"
-
-### What is a handler?
-
-A handler is the function **expressly** will call to get a response to send back to the client. It is passed two arguments, the **req**uest and the **res**ponse.
-
-```javascript
-router.post("/", (req, res) => {
-  res.send("<h1>This is the response!</h1>");
-});
-```
-
-> 🚨 **Unlike Express**, handlers accept only two arguments, `req` and `res`. **expressly** does away with the `next` function; uncaught errors are passed to [error middleware](./middleware/error-middleware.md). 
-
-## Listening for requests
-
-After you have configured your routing logic, you **must** call `router.listen()` to bind the router to incoming requests.
-
-### Hello world!
-
-```javascript
-import { Router } from "@fastly/expressly";
-
-const router = new Router();
-
-router.get("/", async (req, res) => {
-  return res.send("Hello world!");
-});
-
-router.listen();
-```
-
-## Route matching
-
-### HTTP methods
-
-With **expressly**, you can handle multiple HTTP methods per route:
-
-```javascript
-router.route(["GET", "POST"], "/my-page", async (req, res) => {
-  return res.send(`You made a ${req.method} request to my page!`);
-});
-```
-
-If you want to handle _all_ HTTP methods on one route you can use `router.all`:
-
-```javascript
-router.all("/dead-end", (req, res) => {
-  res.end("Nothing to see here!");
-});
-```
-
-### Route matching
-
-**expressly** uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for pattern-matching routes:
-
-- `router.HTTP_METHOD(PATTERN, handler)`
-- `router.all(PATTERN, handler)`
-- `router.route(HTTP_METHOD[], PATTERN, handler)`
-
-#### Wildcards
-
-You can use wildcard parameters `(.*)` in order to match multiple URLs with one route.
-
-```javascript
-router.get("/assets/(.*)", (req, res) => {
-  res.send(`You are visiting: ${req.path}`);
-});
-```
-
-> 🚨 There is no wildcard asterisk (`*`) in **expressly** - use parameters instead (`(.*)` or `:splat*`).
-
-
-```javascript
-router.get("(.*)", (req, res) => {
-  res.send("Hello world!");
-});
-```
-
-The above will match `GET` requests to any path.
-
-#### Regular expressions
-
-You can use regular expressions in order to match multiple URLs with one route.
-
-```javascript
-router.get(/.*fly$/, (req, res) => {
-  res.send(`You are visiting: ${req.path}`);
-});
-```
-
-The route path above will match `butterfly` and `dragonfly`, but not `butterfly-net` or `flyer`.
-
-#### Path parameters
-
-You can specify parameters on your routes. The values of these parameters will be parsed and available inside your handler, in the `req.params` object.
-
-```javascript
-router.get("/profile/:userId", (req, res) => {
-  let userId = req.params.userId;
-  res.send(`This is the profile for user ${userId}`);
-});
-```
-
-You can use regular expressions to constrain matching rules for parameters.
-
-```javascript
-router.get("/books/:id(\\d+)", (req, res) => {
-  let bookId = req.params.id;
-  res.send(`Book ID: ${bookId}`);
-});
-```
-
-## Custom 404
-
-For a custom 404 response, you can add a catch-all request handler after all other routes and middleware:
-
-```javascript
-router.all(("(.*)", (req, res) => {
-  res.status = 404;
-  return res.send("Page not found!");
-});
-```
-
-Alternatively, you can achieve the same using [error middleware](middleware/error-middleware.md):
-
-```javascript
-router.use((err, req, res) => {
-  if(err.status === 404) {
-    res.send("Page not found!");
-  }
-});
-```
-
-> 💡 **expressly** decorates errors with a `status` property as follows:
-> * `404` – when no route was matched for the request path 
-> * `405` – when a route was found, but the request's HTTP method did not match. 

package/docs/docusaurus.config.js

@@ -1,119 +0,0 @@
-// @ts-check
-// Note: type annotations allow type checking and IDEs autocompletion
-
-const lightCodeTheme = require("prism-react-renderer/themes/github");
-const darkCodeTheme = require("prism-react-renderer/themes/nightOwl");
-
-/** @type {import('@docusaurus/types').Config} */
-const config = {
-  title: "expressly",
-  tagline: "Express-style router for Fastly's Compute@Edge",
-  url: "https://expressly.edgecompute.app",
-  baseUrl: "/",
-  onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
-  favicon: "img/favicon.ico",
-  organizationName: "fastly", 
-  projectName: "expressly", 
-
-  presets: [
-    [
-      "@docusaurus/preset-classic",
-      /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
-        docs: {
-          sidebarPath: require.resolve("./sidebars.js"),
-          sidebarCollapsed: false,
-          editUrl: 'https://github.com/fastly/expressly/edit/main/docs/',
-        },
-        theme: {
-          customCss: require.resolve("./src/css/custom.css"),
-        },
-      }),
-    ],
-  ],
-
-  themeConfig:
-    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
-      colorMode: {
-        respectPrefersColorScheme: true,
-      },
-      navbar: {
-        title: "expressly",
-        logo: {
-          alt: "expressly Logo",
-          src: 'img/logo.png',
-        },
-        items: [
-          {
-            type: "doc",
-            docId: "intro",
-            position: "left",
-            label: "Docs",
-          },
-          {
-            href: "https://developer.fastly.com/solutions/examples/javascript/",
-            label: "Examples",
-            position: "left",
-          },
-          {
-            href: "https://github.com/fastly/expressly",
-            label: "GitHub",
-            position: "right",
-          },
-        ],
-      },
-      footer: {
-        style: "dark",
-        links: [
-          {
-            title: "expressly",
-            items: [
-              {
-                label: "Documentation",
-                to: "/docs/intro",
-              },
-              {
-                label: "Examples",
-                href: "https://developer.fastly.com/solutions/examples/javascript/",
-              },
-            ],
-          },
-          {
-            title: "Compute@Edge",
-            items: [
-              {
-                label: "Learn about Compute@Edge",
-                href: "https://developer.fastly.com/learning/compute/",
-              },
-              {
-                label: "Create your first JavaScript app",
-                href: "https://developer.fastly.com/learning/compute/javascript/",
-              },
-              {
-                label: "Fastly Developer Hub",
-                href: "https://developer.fastly.com/",
-              },
-            ],
-          },
-          {
-            title: "Fastly",
-            items: [
-              {
-                label: "Twitter",
-                href: "https://twitter.com/fastly",
-              },
-            ],
-          },
-        ],
-        copyright: `Copyright © ${new Date().getFullYear()} Fastly Inc. All rights reserved.`,
-      },
-      prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
-      },
-    }),
-};
-
-module.exports = config;

package/docs/package.json

@@ -1,48 +0,0 @@
-{
-  "name": "expressly-docs",
-  "version": "0.0.0",
-  "description": "Documentation for expressly - an Express-style router for Fastly's Compute@Edge",
-  "private": true,
-  "engines": {
-    "node": "^16.15.0"
-  },
-  "scripts": {
-    "docusaurus": "docusaurus",
-    "start": "docusaurus start",
-    "build": "docusaurus build",
-    "swizzle": "docusaurus swizzle",
-    "deploy": "docusaurus deploy",
-    "clear": "docusaurus clear",
-    "serve": "docusaurus serve",
-    "write-translations": "docusaurus write-translations",
-    "write-heading-ids": "docusaurus write-heading-ids",
-    "typecheck": "tsc"
-  },
-  "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.21",
-    "@docusaurus/preset-classic": "2.0.0-beta.21",
-    "@mdx-js/react": "^1.6.22",
-    "clsx": "^1.1.1",
-    "prism-react-renderer": "^1.3.3",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
-  },
-  "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
-    "@tsconfig/docusaurus": "^1.0.5",
-    "@types/react": "^17.0.2",
-    "typescript": "^4.7.3"
-  },
-  "browserslist": {
-    "production": [
-      ">0.5%",
-      "not dead",
-      "not op_mini all"
-    ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  }
-}

package/docs/sidebars.js

@@ -1,31 +0,0 @@
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  main: [{ type: "autogenerated", dirName: "." }],
-
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['hello'],
-    },
-  ],
-   */
-};
-
-module.exports = sidebars;

package/docs/src/components/HomepageFeatures.module.css

@@ -1,11 +0,0 @@
-.features {
-  display: flex;
-  align-items: center;
-  padding: 2rem 0;
-  width: 100%;
-}
-
-.featureSvg {
-  height: 200px;
-  width: 200px;
-}