create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/api/request.md

@@ -0,0 +1,396 @@
+# AcrylRequest
+
+The `AcrylRequest` is an object that can be taken from `c.req` which wraps a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
+
+## param()
+
+Get the values of path parameters.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+// Captured params
+app.get('/entry/:id', async (c) => {
+  const id = c.req.param('id')
+  //    ^?
+  // ...
+})
+
+// Get all params at once
+app.get('/entry/:id/comment/:commentId', async (c) => {
+  const { id, commentId } = c.req.param()
+  //      ^?
+})
+```
+
+## query()
+
+Get querystring parameters.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+// Query params
+app.get('/search', async (c) => {
+  const query = c.req.query('q')
+  //     ^?
+})
+
+// Get all params at once
+app.get('/search', async (c) => {
+  const { q, limit, offset } = c.req.query()
+  //      ^?
+})
+```
+
+## queries()
+
+Get multiple querystring parameter values, e.g. `/search?tags=A&tags=B`
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/search', async (c) => {
+  // tags will be string[]
+  const tags = c.req.queries('tags')
+  //     ^?
+  // ...
+})
+```
+
+## header()
+
+Get the request header value.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/', (c) => {
+  const userAgent = c.req.header('User-Agent')
+  //      ^?
+  return c.text(`Your user agent is ${userAgent}`)
+})
+```
+
+**Warning.**
+
+When `c.req.header()` is called with no arguments, all keys in the returned record are **lowercase**.
+
+If you want to get the value of a header with an uppercase name,
+use `c.req.header(“X-Foo”)`.
+
+```ts
+// ❌ Will not work
+const headerRecord = c.req.header()
+const foo = headerRecord['X-Foo']
+
+// ✅ Will work
+const foo = c.req.header('X-Foo')
+```
+
+## parseBody()
+
+Parse Request body of type `multipart/form-data` or `application/x-www-form-urlencoded`
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.parseBody()
+  // ...
+})
+```
+
+`parseBody()` supports the following behaviors.
+
+**Single file**
+
+```ts twoslash
+import { Context } from 'acrylblends'
+declare const c: Context
+// ---cut---
+const body = await c.req.parseBody()
+const data = body['foo']
+//    ^?
+```
+
+`body['foo']` is `(string | File)`.
+
+If multiple files are uploaded, the last one will be used.
+
+### Multiple files
+
+```ts twoslash
+import { Context } from 'acrylblends'
+declare const c: Context
+// ---cut---
+const body = await c.req.parseBody()
+body['foo[]']
+```
+
+`body['foo[]']` is always `(string | File)[]`.
+
+`[]` postfix is required.
+
+### Multiple files or fields with same name
+
+If you have an input field that allows multiple `<input type="file" multiple />` or multiple checkboxes with the same name `<input type="checkbox" name="favorites" value="Acryl"/>`.
+
+```ts twoslash
+import { Context } from 'acrylblends'
+declare const c: Context
+// ---cut---
+const body = await c.req.parseBody({ all: true })
+body['foo']
+```
+
+`all` option is disabled by default.
+
+- If `body['foo']` is multiple files, it will be parsed to `(string | File)[]`.
+- If `body['foo']` is single file, it will be parsed to `(string | File)`.
+
+### Dot notation
+
+If you set the `dot` option `true`, the return value is structured based on the dot notation.
+
+Imagine receiving the following data:
+
+```ts twoslash
+const data = new FormData()
+data.append('obj.key1', 'value1')
+data.append('obj.key2', 'value2')
+```
+
+You can get the structured value by setting the `dot` option `true`:
+
+```ts twoslash
+import { Context } from 'acrylblends'
+declare const c: Context
+// ---cut---
+const body = await c.req.parseBody({ dot: true })
+// body is `{ obj: { key1: 'value1', key2: 'value2' } }`
+```
+
+## json()
+
+Parses the request body of type `application/json`
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.json()
+  // ...
+})
+```
+
+## text()
+
+Parses the request body of type `text/plain`
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.text()
+  // ...
+})
+```
+
+## arrayBuffer()
+
+Parses the request body as an `ArrayBuffer`
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.arrayBuffer()
+  // ...
+})
+```
+
+## blob()
+
+Parses the request body as a `Blob`.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.blob()
+  // ...
+})
+```
+
+## formData()
+
+Parses the request body as a `FormData`.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.post('/entry', async (c) => {
+  const body = await c.req.formData()
+  // ...
+})
+```
+
+## valid()
+
+Get the validated data.
+
+```ts
+app.post('/posts', async (c) => {
+  const { title, body } = c.req.valid('form')
+  // ...
+})
+```
+
+Available targets are below.
+
+- `form`
+- `json`
+- `query`
+- `header`
+- `cookie`
+- `param`
+
+See the [Validation section](../guides/validation.md) for usage examples.
+
+## routePath
+
+> **Warning.** **Deprecated in v4.8.0**: This property is deprecated. Use `routePath()` from [Route Helper](../helpers/route.md) instead.
+
+You can retrieve the registered path within the handler like this:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/posts/:id', (c) => {
+  return c.json({ path: c.req.routePath })
+})
+```
+
+If you access `/posts/123`, it will return `/posts/:id`:
+
+```json
+{ "path": "/posts/:id" }
+```
+
+## matchedRoutes
+
+> **Warning.** **Deprecated in v4.8.0**: This property is deprecated. Use `matchedRoutes()` from [Route Helper](../helpers/route.md) instead.
+
+It returns matched routes within the handler, which is useful for debugging.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.use(async function logger(c, next) {
+  await next()
+  c.req.matchedRoutes.forEach(({ handler, method, path }, i) => {
+    const name =
+      handler.name ||
+      (handler.length < 2 ? '[handler]' : '[middleware]')
+    console.log(
+      method,
+      ' ',
+      path,
+      ' '.repeat(Math.max(10 - path.length, 0)),
+      name,
+      i === c.req.routeIndex ? '<- respond from here' : ''
+    )
+  })
+})
+```
+
+## path
+
+The request pathname.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/about/me', async (c) => {
+  const pathname = c.req.path // `/about/me`
+  // ...
+})
+```
+
+## url
+
+The request url strings.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/about/me', async (c) => {
+  const url = c.req.url // `http://localhost:8787/about/me`
+  // ...
+})
+```
+
+## method
+
+The method name of the request.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/about/me', async (c) => {
+  const method = c.req.method // `GET`
+  // ...
+})
+```
+
+## raw
+
+The raw [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
+
+```ts
+// For Cloudflare Workers
+app.post('/', async (c) => {
+  const metadata = c.req.raw.cf?.hostMetadata?
+  // ...
+})
+```
+
+## cloneRawRequest()
+
+Clones the raw Request object from a AcrylRequest. Works even after the request body has been consumed by validators or AcrylRequest methods.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+
+import { cloneRawRequest } from 'acrylblends/request'
+import { validator } from 'acrylblends/validator'
+
+app.post(
+  '/forward',
+  validator('json', (data) => data),
+  async (c) => {
+    // Clone after validation
+    const clonedReq = await cloneRawRequest(c.req)
+    // Does not throw the error
+    await clonedReq.json()
+    // ...
+  }
+)
+```

package/docs/framework/api/routing.md

@@ -0,0 +1,303 @@
+# Routing
+
+Routing of Acryl is flexible and intuitive.
+Let's take a look.
+
+## Basic
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+// HTTP Methods
+app.get('/', (c) => c.text('GET /'))
+app.post('/', (c) => c.text('POST /'))
+app.put('/', (c) => c.text('PUT /'))
+app.delete('/', (c) => c.text('DELETE /'))
+app.query('/', (c) => c.text('QUERY /'))
+
+// Wildcard
+app.get('/wild/*/card', (c) => {
+  return c.text('GET /wild/*/card')
+})
+
+// Any HTTP methods
+app.all('/hello', (c) => c.text('Any Method /hello'))
+
+// Custom HTTP method
+app.on('PURGE', '/cache', (c) => c.text('PURGE Method /cache'))
+
+// Multiple Method
+app.on(['PUT', 'DELETE'], '/post', (c) =>
+  c.text('PUT or DELETE /post')
+)
+
+// Multiple Paths
+app.on('GET', ['/hello', '/ja/hello', '/en/hello'], (c) =>
+  c.text('Hello')
+)
+```
+
+## Path Parameter
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/user/:name', async (c) => {
+  const name = c.req.param('name')
+  //       ^?
+  // ...
+})
+```
+
+or all parameters at once:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/posts/:id/comment/:comment_id', async (c) => {
+  const { id, comment_id } = c.req.param()
+  //       ^?
+  // ...
+})
+```
+
+## Optional Parameter
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+// Will match `/api/animal` and `/api/animal/:type`
+app.get('/api/animal/:type?', (c) => c.text('Animal!'))
+```
+
+## Regexp
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/post/:date{[0-9]+}/:title{[a-z]+}', async (c) => {
+  const { date, title } = c.req.param()
+  //       ^?
+  // ...
+})
+```
+
+## Including slashes
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/posts/:filename{.+\\.png}', async (c) => {
+  //...
+})
+```
+
+## Chained route
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app
+  .get('/endpoint', (c) => {
+    return c.text('GET /endpoint')
+  })
+  .post((c) => {
+    return c.text('POST /endpoint')
+  })
+  .delete((c) => {
+    return c.text('DELETE /endpoint')
+  })
+```
+
+## Grouping
+
+You can group the routes with the Acryl instance and add them to the main app with the route method.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const book = new Acryl()
+
+book.get('/', (c) => c.text('List Books')) // GET /book
+book.get('/:id', (c) => {
+  // GET /book/:id
+  const id = c.req.param('id')
+  return c.text('Get Book: ' + id)
+})
+book.post('/', (c) => c.text('Create Book')) // POST /book
+
+const app = new Acryl()
+app.route('/book', book)
+```
+
+## Grouping without changing base
+
+You can also group multiple instances while keeping base.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const book = new Acryl()
+book.get('/book', (c) => c.text('List Books')) // GET /book
+book.post('/book', (c) => c.text('Create Book')) // POST /book
+
+const user = new Acryl().basePath('/user')
+user.get('/', (c) => c.text('List Users')) // GET /user
+user.post('/', (c) => c.text('Create User')) // POST /user
+
+const app = new Acryl()
+app.route('/', book) // Handle /book
+app.route('/', user) // Handle /user
+```
+
+## Base path
+
+You can specify the base path.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const api = new Acryl().basePath('/api')
+api.get('/book', (c) => c.text('List Books')) // GET /api/book
+```
+
+## Routing with hostname
+
+It works fine if it includes a hostname.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const app = new Acryl({
+  getPath: (req) => req.url.replace(/^https?:\/([^?]+).*$/, '$1'),
+})
+
+app.get('/www1.example.com/hello', (c) => c.text('hello www1'))
+app.get('/www2.example.com/hello', (c) => c.text('hello www2'))
+```
+
+## Routing with `host` Header value
+
+Acryl can handle the `host` header value if you set the `getPath()` function in the Acryl constructor.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+// ---cut---
+const app = new Acryl({
+  getPath: (req) =>
+    '/' +
+    req.headers.get('host') +
+    req.url.replace(/^https?:\/\/[^/]+(\/[^?]*).*/, '$1'),
+})
+
+app.get('/www1.example.com/hello', (c) => c.text('hello www1'))
+
+// A following request will match the route:
+// new Request('http://www1.example.com/hello', {
+//  headers: { host: 'www1.example.com' },
+// })
+```
+
+By applying this, for example, you can change the routing by `User-Agent` header.
+
+## Routing priority
+
+Handlers or middleware will be executed in registration order.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/book/a', (c) => c.text('a')) // a
+app.get('/book/:slug', (c) => c.text('common')) // common
+```
+
+```
+GET /book/a ---> `a`
+GET /book/b ---> `common`
+```
+
+When a handler is executed, the process will be stopped.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('*', (c) => c.text('common')) // common
+app.get('/foo', (c) => c.text('foo')) // foo
+```
+
+```
+GET /foo ---> `common` // foo will not be dispatched
+```
+
+If you have the middleware that you want to execute, write the code above the handler.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { logger } from 'acrylblends/logger'
+const app = new Acryl()
+// ---cut---
+app.use(logger())
+app.get('/foo', (c) => c.text('foo'))
+```
+
+If you want to have a "_fallback_" handler, write the code below the other handler.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+// ---cut---
+app.get('/bar', (c) => c.text('bar')) // bar
+app.get('*', (c) => c.text('fallback')) // fallback
+```
+
+```
+GET /bar ---> `bar`
+GET /foo ---> `fallback`
+```
+
+## Grouping ordering
+
+Note that the mistake of grouping routings is hard to notice.
+The `route()` function takes the stored routing from the second argument (such as `three` or `two`) and adds it to its own (`two` or `app`) routing.
+
+```ts
+three.get('/hi', (c) => c.text('hi'))
+two.route('/three', three)
+app.route('/two', two)
+
+export default app
+```
+
+It will return 200 response.
+
+```
+GET /two/three/hi ---> `hi`
+```
+
+However, if they are in the wrong order, it will return a 404.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+const app = new Acryl()
+const two = new Acryl()
+const three = new Acryl()
+// ---cut---
+three.get('/hi', (c) => c.text('hi'))
+app.route('/two', two) // `two` does not have routes
+two.route('/three', three)
+
+export default app
+```
+
+```
+GET /two/three/hi ---> 404 Not Found
+```