create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/guides/testing.md

@@ -0,0 +1,133 @@
+# Testing
+
+[Vitest]: https://vitest.dev/
+
+Testing is important.
+In actuality, it is easy to test Acryl's applications.
+The way to create a test environment differs from each runtime, but the basic steps are the same.
+In this section, let's test with [Vitest] on Node.js. The same tests run on Bun with its own test runner, because an app is a function from `Request` to `Response`.
+
+## Request and Response
+
+All you need to do is create a Request and pass it to the Acryl application to validate the Response. You can then use the useful `app.request` method.
+
+> **Tip.** For a typed test client see the [testing helper](../helpers/testing.md).
+
+For example, consider an application that provides the following REST API.
+
+```ts
+app.get('/posts', (c) => {
+  return c.text('Many posts')
+})
+
+app.post('/posts', (c) => {
+  return c.json(
+    {
+      message: 'Created',
+    },
+    201,
+    {
+      'X-Custom': 'Thank you',
+    }
+  )
+})
+```
+
+Make a request to `GET /posts` and test the response.
+
+```ts
+describe('Example', () => {
+  test('GET /posts', async () => {
+    const res = await app.request('/posts')
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('Many posts')
+  })
+})
+```
+
+To make a request to `POST /posts`, do the following.
+
+```ts
+test('POST /posts', async () => {
+  const res = await app.request('/posts', {
+    method: 'POST',
+  })
+  expect(res.status).toBe(201)
+  expect(res.headers.get('X-Custom')).toBe('Thank you')
+  expect(await res.json()).toEqual({
+    message: 'Created',
+  })
+})
+```
+
+To make a request to `POST /posts` with `JSON` data, do the following.
+
+```ts
+test('POST /posts', async () => {
+  const res = await app.request('/posts', {
+    method: 'POST',
+    body: JSON.stringify({ message: 'hello acrylblends' }),
+    headers: new Headers({ 'Content-Type': 'application/json' }),
+  })
+  expect(res.status).toBe(201)
+  expect(res.headers.get('X-Custom')).toBe('Thank you')
+  expect(await res.json()).toEqual({
+    message: 'Created',
+  })
+})
+```
+
+To make a request to `POST /posts` with `multipart/form-data` data, do the following.
+
+```ts
+test('POST /posts', async () => {
+  const formData = new FormData()
+  formData.append('message', 'hello')
+  const res = await app.request('/posts', {
+    method: 'POST',
+    body: formData,
+  })
+  expect(res.status).toBe(201)
+  expect(res.headers.get('X-Custom')).toBe('Thank you')
+  expect(await res.json()).toEqual({
+    message: 'Created',
+  })
+})
+```
+
+You can also pass an instance of the Request class.
+
+```ts
+test('POST /posts', async () => {
+  const req = new Request('http://localhost/posts', {
+    method: 'POST',
+  })
+  const res = await app.request(req)
+  expect(res.status).toBe(201)
+  expect(res.headers.get('X-Custom')).toBe('Thank you')
+  expect(await res.json()).toEqual({
+    message: 'Created',
+  })
+})
+```
+
+In this way, you can test it as like an End-to-End.
+
+## Env
+
+To set `c.env` for testing, you can pass it as the 3rd parameter to `app.request`. This is useful for mocking values like platform bindings:
+
+```ts
+const MOCK_ENV = {
+  API_HOST: 'example.com',
+  DB: {
+    prepare: () => {
+      /* mocked D1 */
+    },
+  },
+}
+
+test('GET /posts', async () => {
+  const res = await app.request('/posts', {}, MOCK_ENV)
+})
+```

package/docs/framework/guides/validation.md

@@ -0,0 +1,383 @@
+# Validation
+
+Acryl provides only a very thin Validator.
+However, it can be powerful when combined with a third-party Validator.
+In addition, the RPC feature allows you to share API specifications with your clients through types.
+
+## Manual validator
+
+First, introduce a way to validate incoming values without using the third-party Validator.
+
+Import `validator` from `acrylblends/validator`.
+
+```ts
+import { validator } from 'acrylblends/validator'
+```
+
+To validate form data, specify `form` as the first argument and a callback as the second argument.
+In the callback, validates the value and return the validated values at the end.
+The `validator` can be used as middleware.
+
+```ts
+app.post(
+  '/posts',
+  validator('form', (value, c) => {
+    const body = value['body']
+    if (!body || typeof body !== 'string') {
+      return c.text('Invalid!', 400)
+    }
+    return {
+      body: body,
+    }
+  }),
+  //...
+```
+
+Within the handler, you can get the validated value with `c.req.valid('form')`.
+
+```ts
+, (c) => {
+  const { body } = c.req.valid('form')
+  // ... do something
+  return c.json(
+    {
+      message: 'Created!',
+    },
+    201
+  )
+}
+```
+
+Validation targets include `json`, `query`, `header`, `param` and `cookie` in addition to `form`.
+
+**Warning.**
+
+When you validate `json` or `form`, the request _must_ contain a matching `content-type` header (e.g. `Content-Type: application/json` for `json`). Otherwise, the request body will not be parsed and you will receive an empty object (`{}`) as value in the callback.
+
+It is important to set the `content-type` header when testing using
+[`app.request()`](../api/request.md).
+
+Given an application like this.
+
+```ts
+const app = new Acryl()
+app.post(
+  '/testing',
+  validator('json', (value, c) => {
+    // pass-through validator
+    return value
+  }),
+  (c) => {
+    const body = c.req.valid('json')
+    return c.json(body)
+  }
+)
+```
+
+Your tests can be written like this.
+
+```ts
+// ❌ this will not work
+const res = await app.request('/testing', {
+  method: 'POST',
+  body: JSON.stringify({ key: 'value' }),
+})
+const data = await res.json()
+console.log(data) // {}
+
+// ✅ this will work
+const res = await app.request('/testing', {
+  method: 'POST',
+  body: JSON.stringify({ key: 'value' }),
+  headers: new Headers({ 'Content-Type': 'application/json' }),
+})
+const data = await res.json()
+console.log(data) // { key: 'value' }
+```
+
+**Warning.**
+
+When you validate `header`, you need to use **lowercase** name as the key.
+
+If you want to validate the `Idempotency-Key` header, you need to use `idempotency-key` as the key.
+
+```ts
+// ❌ this will not work
+app.post(
+  '/api',
+  validator('header', (value, c) => {
+    // idempotencyKey is always undefined
+    // so this middleware always return 400 as not expected
+    const idempotencyKey = value['Idempotency-Key']
+
+    if (idempotencyKey == undefined || idempotencyKey === '') {
+      throw new HTTPException(400, {
+        message: 'Idempotency-Key is required',
+      })
+    }
+    return { idempotencyKey }
+  }),
+  (c) => {
+    const { idempotencyKey } = c.req.valid('header')
+    // ...
+  }
+)
+
+// ✅ this will work
+app.post(
+  '/api',
+  validator('header', (value, c) => {
+    // can retrieve the value of the header as expected
+    const idempotencyKey = value['idempotency-key']
+
+    if (idempotencyKey == undefined || idempotencyKey === '') {
+      throw new HTTPException(400, {
+        message: 'Idempotency-Key is required',
+      })
+    }
+    return { idempotencyKey }
+  }),
+  (c) => {
+    const { idempotencyKey } = c.req.valid('header')
+    // ...
+  }
+)
+```
+
+## Multiple validators
+
+You can also include multiple validators to validate different parts of request:
+
+```ts
+app.post(
+  '/posts/:id',
+  validator('param', ...),
+  validator('query', ...),
+  validator('json', ...),
+  (c) => {
+    //...
+  }
+)
+```
+
+## With Zod
+
+You can use [Zod](https://zod.dev), one of third-party validators.
+We recommend using a third-party validator.
+
+Install from the Npm registry.
+
+**npm**
+
+```sh
+npm i zod
+```
+
+**yarn**
+
+```sh
+yarn add zod
+```
+
+**pnpm**
+
+```sh
+pnpm add zod
+```
+
+**bun**
+
+```sh
+bun add zod
+```
+
+Import `z` from `zod`.
+
+```ts
+import * as z from 'zod'
+```
+
+Write your schema.
+
+```ts
+const schema = z.object({
+  body: z.string(),
+})
+```
+
+You can use the schema in the callback function for validation and return the validated value.
+
+```ts
+const route = app.post(
+  '/posts',
+  validator('form', (value, c) => {
+    const parsed = schema.safeParse(value)
+    if (!parsed.success) {
+      return c.text('Invalid!', 401)
+    }
+    return parsed.data
+  }),
+  (c) => {
+    const { body } = c.req.valid('form')
+    // ... do something
+    return c.json(
+      {
+        message: 'Created!',
+      },
+      201
+    )
+  }
+)
+```
+
+## Standard Schema validator
+
+[Standard Schema](https://standardschema.dev/) is a specification that gives TypeScript validation libraries a common interface, so a tool can accept Zod, Valibot, ArkType and
+others without an adapter for each.
+
+`schemaValidator` is part of acrylblends: it validates a request target with any Standard Schema and makes the parsed value available as `c.req.valid(target)`.
+
+```ts
+import { schemaValidator } from 'acrylblends/schema-validator'
+```
+
+A failed validation answers 400 with `{ "error": "invalid <target>", "issues": [{ "message", "path" }] }`. The failure shapes, the JSON `Content-Type` rule and a body that
+is not JSON are described in [Validation with Standard Schema](../cordis/validation.md).
+
+### With Zod
+
+You can use Zod with the schema validator:
+
+**npm**
+
+```sh
+npm i zod
+```
+
+**yarn**
+
+```sh
+yarn add zod
+```
+
+**pnpm**
+
+```sh
+pnpm add zod
+```
+
+**bun**
+
+```sh
+bun add zod
+```
+
+```ts
+import * as z from 'zod'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+})
+
+app.post('/author', schemaValidator('json', schema), (c) => {
+  const data = c.req.valid('json')
+  return c.json({
+    success: true,
+    message: `${data.name} is ${data.age}`,
+  })
+})
+```
+
+### With Valibot
+
+[Valibot](https://valibot.dev/) is a lightweight alternative to Zod with a modular design:
+
+**npm**
+
+```sh
+npm i valibot
+```
+
+**yarn**
+
+```sh
+yarn add valibot
+```
+
+**pnpm**
+
+```sh
+pnpm add valibot
+```
+
+**bun**
+
+```sh
+bun add valibot
+```
+
+```ts
+import * as v from 'valibot'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const schema = v.object({
+  name: v.string(),
+  age: v.number(),
+})
+
+app.post('/author', schemaValidator('json', schema), (c) => {
+  const data = c.req.valid('json')
+  return c.json({
+    success: true,
+    message: `${data.name} is ${data.age}`,
+  })
+})
+```
+
+### With ArkType
+
+[ArkType](https://arktype.io/) offers TypeScript-native syntax for runtime validation:
+
+**npm**
+
+```sh
+npm i arktype
+```
+
+**yarn**
+
+```sh
+yarn add arktype
+```
+
+**pnpm**
+
+```sh
+pnpm add arktype
+```
+
+**bun**
+
+```sh
+bun add arktype
+```
+
+```ts
+import { type } from 'arktype'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const schema = type({
+  name: 'string',
+  age: 'number',
+})
+
+app.post('/author', schemaValidator('json', schema), (c) => {
+  const data = c.req.valid('json')
+  return c.json({
+    success: true,
+    message: `${data.name} is ${data.age}`,
+  })
+})
+```

package/docs/framework/helpers/accepts.md

@@ -0,0 +1,60 @@
+# Accepts Helper
+
+Accepts Helper helps to handle Accept headers in the Requests.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { accepts } from 'acrylblends/accepts'
+```
+
+## `accepts()`
+
+The `accepts()` function looks at the Accept header, such as Accept-Encoding and Accept-Language, and returns the proper value.
+
+```ts
+import { accepts } from 'acrylblends/accepts'
+
+app.get('/', (c) => {
+  const accept = accepts(c, {
+    header: 'Accept-Language',
+    supports: ['en', 'ja', 'zh'],
+    default: 'en',
+  })
+  return c.json({ lang: accept })
+})
+```
+
+### `AcceptHeader` type
+
+The definition of the `AcceptHeader` type is as follows.
+
+```ts
+export type AcceptHeader =
+  | 'Accept'
+  | 'Accept-Charset'
+  | 'Accept-Encoding'
+  | 'Accept-Language'
+  | 'Accept-Patch'
+  | 'Accept-Post'
+  | 'Accept-Ranges'
+```
+
+## Options
+
+### **(required)** header: `AcceptHeader`
+
+The target accept header.
+
+### **(required)** supports: `string[]`
+
+The header values which your application supports.
+
+### **(required)** default: `string`
+
+The default values.
+
+### *(optional)* match: `(accepts: Accept[], config: acceptsConfig) => string`
+
+The custom match function.

package/docs/framework/helpers/adapter.md

@@ -0,0 +1,87 @@
+# Adapter Helper
+
+The Adapter Helper provides a seamless way to interact with various platforms through a unified interface.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { env, getRuntimeKey } from 'acrylblends/adapter'
+```
+
+## `env()`
+
+The `env()` function facilitates retrieving environment variables across different runtimes, extending beyond just Cloudflare Workers' Bindings. The value that can be retrieved with `env(c)` may be different for each runtime.
+
+```ts
+import { env } from 'acrylblends/adapter'
+
+app.get('/env', (c) => {
+  // NAME is process.env.NAME on Node.js or Bun
+  // NAME is the value written in `wrangler.toml` on Cloudflare
+  const { NAME } = env<{ NAME: string }>(c)
+  return c.text(NAME)
+})
+```
+
+Supported Runtimes, Serverless Platforms and Cloud Services:
+
+- Cloudflare Workers
+  - `wrangler.toml`
+  - `wrangler.jsonc`
+- Deno
+  - [`Deno.env`](https://docs.deno.com/runtime/manual/basics/env_variables)
+  - `.env` file
+- Bun
+  - [`Bun.env`](https://bun.com/guides/runtime/set-env)
+  - `process.env`
+- Node.js
+  - `process.env`
+- Vercel
+  - [Environment Variables on Vercel](https://vercel.com/docs/projects/environment-variables)
+- AWS Lambda
+  - [Environment Variables on AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/samples-blank.html#samples-blank-architecture)
+- Lambda@Edge\
+  Environment Variables on Lambda are [not supported](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html) by Lambda@Edge, you need to use [Lambda@Edge event](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/lambda-event-structure.html) as an alternative.
+- Fastly Compute\
+  On Fastly Compute, you can use the ConfigStore to manage user-defined data.
+- Netlify\
+  On Netlify, you can use the [Netlify Contexts](https://docs.netlify.com/site-deploys/overview/#deploy-contexts) to manage user-defined data.
+
+### Specify the runtime
+
+You can specify the runtime to get environment variables by passing the runtime key as the second argument.
+
+```ts
+app.get('/env', (c) => {
+  const { NAME } = env<{ NAME: string }>(c, 'workerd')
+  return c.text(NAME)
+})
+```
+
+## `getRuntimeKey()`
+
+The `getRuntimeKey()` function returns the identifier of the current runtime.
+
+```ts
+app.get('/', (c) => {
+  if (getRuntimeKey() === 'workerd') {
+    return c.text('You are on Cloudflare')
+  } else if (getRuntimeKey() === 'bun') {
+    return c.text('You are on Bun')
+  }
+  ...
+})
+```
+
+### Available Runtimes Keys
+
+Here are the available runtimes keys, unavailable runtime key runtimes may be supported and labeled as `other`, with some being inspired by [WinterCG's Runtime Keys](https://runtime-keys.proposal.wintercg.org/):
+
+- `workerd` - Cloudflare Workers
+- `deno`
+- `bun`
+- `node`
+- `edge-light` - Vercel Edge Functions
+- `fastly` - Fastly Compute
+- `other` - Other unknown runtimes keys