create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/helpers/factory.md

@@ -0,0 +1,180 @@
+# Factory Helper
+
+The Factory Helper provides useful functions for creating Acryl's components such as Middleware. Sometimes it's difficult to set the proper TypeScript types, but this helper facilitates that.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { createFactory, createMiddleware } from 'acrylblends/factory'
+```
+
+## `createFactory()`
+
+`createFactory()` will create an instance of the Factory class.
+
+```ts
+import { createFactory } from 'acrylblends/factory'
+
+const factory = createFactory()
+```
+
+You can pass your Env types as Generics:
+
+```ts
+type Env = {
+  Variables: {
+    foo: string
+  }
+}
+
+const factory = createFactory<Env>()
+```
+
+### Options
+
+### *(optional)* defaultAppOptions: `AcrylOptions`
+
+The default options to pass to the Acryl application created by `createApp()`.
+
+```ts
+const factory = createFactory({
+  defaultAppOptions: { strict: false },
+})
+
+const app = factory.createApp() // `strict: false` is applied
+```
+
+## `createMiddleware()`
+
+`createMiddleware()` is shortcut of `factory.createMiddleware()`.
+This function will create your custom middleware.
+
+```ts
+const messageMiddleware = createMiddleware(async (c, next) => {
+  await next()
+  c.res.headers.set('X-Message', 'Good morning!')
+})
+```
+
+Tip: If you want to get an argument like `message`, you can create it as a function like the following.
+
+```ts
+const messageMiddleware = (message: string) => {
+  return createMiddleware(async (c, next) => {
+    await next()
+    c.res.headers.set('X-Message', message)
+  })
+}
+
+app.use(messageMiddleware('Good evening!'))
+```
+
+## `factory.createHandlers()`
+
+`createHandlers()` helps to define handlers in a different place than `app.get('/')`.
+
+```ts
+import { createFactory } from 'acrylblends/factory'
+import { logger } from 'acrylblends/logger'
+declare module 'acrylblends' {
+  interface ContextVariableMap {
+    foo: string
+  }
+}
+
+// ...
+
+const factory = createFactory()
+
+const middleware = factory.createMiddleware(async (c, next) => {
+  c.set('foo', 'bar')
+  await next()
+})
+
+const handlers = factory.createHandlers(logger(), middleware, (c) => {
+  return c.json(c.var.foo)
+})
+
+app.get('/api', ...handlers)
+```
+
+## `factory.createApp()`
+
+`createApp()` helps to create an instance of Acryl with the proper types. If you use this method with `createFactory()`, you can avoid redundancy in the definition of the `Env` type.
+
+If your application is like this, you have to set the `Env` in two places:
+
+```ts
+import { createMiddleware } from 'acrylblends/factory'
+
+type Env = {
+  Variables: {
+    myVar: string
+  }
+}
+
+// 1. Set the `Env` to `new Acryl()`
+const app = new Acryl<Env>()
+
+// 2. Set the `Env` to `createMiddleware()`
+const mw = createMiddleware<Env>(async (c, next) => {
+  await next()
+})
+
+app.use(mw)
+```
+
+By using `createFactory()` and `createApp()`, you can set the `Env` only in one place.
+
+```ts
+import { createFactory } from 'acrylblends/factory'
+
+// ...
+
+// Set the `Env` to `createFactory()`
+const factory = createFactory<Env>()
+
+const app = factory.createApp()
+
+// factory also has `createMiddleware()`
+const mw = factory.createMiddleware(async (c, next) => {
+  await next()
+})
+```
+
+`createFactory()` can receive the `initApp` option to initialize an `app` created by `createApp()`. The following is an example that uses the option.
+
+```ts
+// factory-with-db.ts
+type Env = {
+  Bindings: {
+    MY_DB: D1Database
+  }
+  Variables: {
+    db: DrizzleD1Database
+  }
+}
+
+export default createFactory<Env>({
+  initApp: (app) => {
+    app.use(async (c, next) => {
+      const db = drizzle(c.env.MY_DB)
+      c.set('db', db)
+      await next()
+    })
+  },
+})
+```
+
+```ts
+// crud.ts
+import factoryWithDB from './factory-with-db'
+
+const app = factoryWithDB.createApp()
+
+app.post('/posts', (c) => {
+  c.var.db.insert()
+  // ...
+})
+```

package/docs/framework/helpers/html.md

@@ -0,0 +1,123 @@
+# html Helper
+
+The html Helper lets you write HTML in JavaScript template literal with a tag named `html`. Using `raw()`, the content will be rendered as is. You have to escape these strings by yourself.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { html, raw } from 'acrylblends/html'
+```
+
+## `html`
+
+```ts
+const app = new Acryl()
+
+app.get('/:username', (c) => {
+  const { username } = c.req.param()
+  return c.html(
+    html`<!doctype html>
+      <h1>Hello! ${username}!</h1>`
+  )
+})
+```
+
+### Insert snippets into JSX
+
+Insert the inline script into JSX:
+
+```tsx
+app.get('/', (c) => {
+  return c.html(
+    <html>
+      <head>
+        <title>Test Site</title>
+        {html`
+          <script>
+            // No need to use dangerouslySetInnerHTML.
+            // If you write it here, it will not be escaped.
+          </script>
+        `}
+      </head>
+      <body>Hello!</body>
+    </html>
+  )
+})
+```
+
+### Act as functional component
+
+Since `html` returns an HtmlEscapedString, it can act as a fully functional component without using JSX.
+
+#### Use `html` to speed up the process instead of `memo`
+
+```ts
+const Footer = () => html`
+  <footer>
+    <address>My Address...</address>
+  </footer>
+`
+```
+
+### Receives props and embeds values
+
+```ts
+interface SiteData {
+  title: string
+  description: string
+  image: string
+  children?: any
+}
+const Layout = (props: SiteData) => html`
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>${props.title}</title>
+  <meta name="description" content="${props.description}">
+  <head prefix="og: http://ogp.me/ns#">
+  <meta property="og:type" content="article">
+  <!-- More elements slow down JSX, but not template literals. -->
+  <meta property="og:title" content="${props.title}">
+  <meta property="og:image" content="${props.image}">
+</head>
+<body>
+  ${props.children}
+</body>
+</html>
+`
+
+const Content = (props: { siteData: SiteData; name: string }) => (
+  <Layout {...props.siteData}>
+    <h1>Hello {props.name}</h1>
+  </Layout>
+)
+
+app.get('/', (c) => {
+  const props = {
+    name: 'World',
+    siteData: {
+      title: 'Hello <> World',
+      description: 'This is a description',
+      image: 'https://example.com/image.png',
+    },
+  }
+  return c.html(<Content {...props} />)
+})
+```
+
+## `raw()`
+
+```ts
+app.get('/', (c) => {
+  const name = 'John &quot;Johnny&quot; Smith'
+  return c.html(html`<p>I'm ${raw(name)}.</p>`)
+})
+```
+
+## Tips
+
+Thanks to these libraries, Visual Studio Code and vim also interprets template literals as HTML, allowing syntax highlighting and formatting to be applied.
+
+- <https://marketplace.visualstudio.com/items?itemName=bierner.lit-html>
+- <https://github.com/MaxMEllon/vim-jsx-pretty>

package/docs/framework/helpers/jwt.md

@@ -0,0 +1,184 @@
+# JWT Authentication Helper
+
+This helper provides functions for encoding, decoding, signing, and verifying JSON Web Tokens (JWTs). JWTs are commonly used for authentication and authorization purposes in web applications. This helper offers robust JWT functionality with support for various cryptographic algorithms.
+
+## Import
+
+To use this helper, you can import it as follows:
+
+```ts
+import { decode, sign, verify } from 'acrylblends/jwt'
+```
+
+> **Note.** [JWT Middleware](../middleware/builtin/jwt.md) also import the `jwt` function from the `acrylblends/jwt`.
+
+## `sign()`
+
+This function generates a JWT token by encoding a payload and signing it using the specified algorithm and secret.
+
+```ts
+sign(
+  payload: unknown,
+  secret: string,
+  alg?: 'HS256';
+
+): Promise<string>;
+```
+
+### Example
+
+```ts
+import { sign } from 'acrylblends/jwt'
+
+const payload = {
+  sub: 'user123',
+  role: 'admin',
+  exp: Math.floor(Date.now() / 1000) + 60 * 5, // Token expires in 5 minutes
+}
+const secret = 'mySecretKey'
+const token = await sign(payload, secret)
+```
+
+### Options
+
+<br/>
+
+#### **(required)** payload: `unknown`
+
+The JWT payload to be signed. You can include other claims like in [Payload Validation](#payload-validation).
+
+#### **(required)** secret: `string`
+
+The secret key used for JWT verification or signing.
+
+#### *(optional)* alg: [AlgorithmTypes](#supported-algorithmtypes)
+
+The algorithm used for JWT signing or verification. The default is HS256.
+
+## `verify()`
+
+This function checks if a JWT token is genuine and still valid. It ensures the token hasn't been altered and checks validity only if you added [Payload Validation](#payload-validation).
+
+```ts
+verify(
+  token: string,
+  secret: string,
+  alg: 'HS256';
+  issuer?: string | RegExp;
+  aud?: string | string[] | RegExp;
+): Promise<any>;
+
+```
+
+### Example
+
+```ts
+import { verify } from 'acrylblends/jwt'
+
+const tokenToVerify = 'token'
+const secretKey = 'mySecretKey'
+
+const decodedPayload = await verify(tokenToVerify, secretKey, 'HS256')
+console.log(decodedPayload)
+```
+
+### Options
+
+<br/>
+
+#### **(required)** token: `string`
+
+The JWT token to be verified.
+
+#### **(required)** secret: `string`
+
+The secret key used for JWT verification or signing.
+
+#### **(required)** alg: [AlgorithmTypes](#supported-algorithmtypes)
+
+The algorithm used for JWT signing or verification.
+
+#### *(optional)* issuer: `string | RegExp`
+
+The expected issuer used for JWT verification.
+
+#### *(optional)* aud: `string | string[] | RegExp`
+
+The expected audience used for JWT verification. If this is set, the token must include an `aud` claim and at least one audience value must match.
+
+## `decode()`
+
+This function decodes a JWT token without performing signature verification. It extracts and returns the header and payload from the token.
+
+```ts
+decode(token: string): { header: any; payload: any };
+```
+
+### Example
+
+```ts
+import { decode } from 'acrylblends/jwt'
+
+// Decode the JWT token
+const tokenToDecode =
+  'eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcjEyMyIsICJyb2xlIjogImFkbWluIn0.JxUwx6Ua1B0D1B0FtCrj72ok5cm1Pkmr_hL82sd7ELA'
+
+const { header, payload } = decode(tokenToDecode)
+
+console.log('Decoded Header:', header)
+console.log('Decoded Payload:', payload)
+```
+
+### Options
+
+<br/>
+
+#### **(required)** token: `string`
+
+The JWT token to be decoded.
+
+> The `decode` function allows you to inspect the header and payload of a JWT token _**without**_ performing verification. This can be useful for debugging or extracting information from JWT tokens.
+
+## Payload Validation
+
+When verifying a JWT token, the following payload validations are performed:
+
+- `exp`: The token is checked to ensure it has not expired.
+- `nbf`: The token is checked to ensure it is not being used before a specified time.
+- `iat`: The token is checked to ensure it is not issued in the future.
+- `iss`: The token is checked to ensure it has been issued by a trusted issuer.
+- `aud`: The token is checked to ensure it is intended for an accepted audience when the `aud` verification parameter is set.
+
+Please ensure that your JWT payload includes these fields, as an object, if you intend to perform these checks during verification.
+
+## Custom Error Types
+
+The module also defines custom error types to handle JWT-related errors.
+
+- `JwtAlgorithmNotImplemented`: Indicates that the requested JWT algorithm is not implemented.
+- `JwtTokenInvalid`: Indicates that the JWT token is invalid.
+- `JwtTokenNotBefore`: Indicates that the token is being used before its valid date.
+- `JwtTokenExpired`: Indicates that the token has expired.
+- `JwtTokenIssuedAt`: Indicates that the "iat" claim in the token is incorrect.
+- `JwtTokenIssuer`: Indicates that the "iss" claim in the token is incorrect.
+- `JwtPayloadRequiresAud`: Indicates that an `aud` claim is required when `aud` verification is configured.
+- `JwtTokenAudience`: Indicates that the token's `aud` claim does not match the expected audience.
+- `JwtTokenSignatureMismatched`: Indicates a signature mismatch in the token.
+
+## Supported AlgorithmTypes
+
+The module supports the following JWT cryptographic algorithms:
+
+- `HS256`: HMAC using SHA-256
+- `HS384`: HMAC using SHA-384
+- `HS512`: HMAC using SHA-512
+- `RS256`: RSASSA-PKCS1-v1_5 using SHA-256
+- `RS384`: RSASSA-PKCS1-v1_5 using SHA-384
+- `RS512`: RSASSA-PKCS1-v1_5 using SHA-512
+- `PS256`: RSASSA-PSS using SHA-256 and MGF1 with SHA-256
+- `PS384`: RSASSA-PSS using SHA-386 and MGF1 with SHA-386
+- `PS512`: RSASSA-PSS using SHA-512 and MGF1 with SHA-512
+- `ES256`: ECDSA using P-256 and SHA-256
+- `ES384`: ECDSA using P-384 and SHA-384
+- `ES512`: ECDSA using P-521 and SHA-512
+- `EdDSA`: EdDSA using Ed25519

package/docs/framework/helpers/proxy.md

@@ -0,0 +1,118 @@
+# Proxy Helper
+
+> **Not yet available.** The proxy helper (`acrylblends/proxy`) is documented here so the page structure matches the rest of the framework, and is not part of acrylblends yet. The code on this page is not checked by the docs tests.
+
+
+Proxy Helper provides useful functions when using Acryl application as a (reverse) proxy.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { proxy } from 'acrylblends/proxy'
+```
+
+## `proxy()`
+
+`proxy()` is a `fetch()` API wrapper for proxy. The parameters and return value are the same as for `fetch()` (except for the proxy-specific options).
+
+The `Accept-Encoding` header is replaced with an encoding that the current runtime can handle. Unnecessary response headers are removed, and a `Response` object is returned that can be sent from the handler.
+
+### Examples
+
+Simple usage:
+
+```ts
+app.get('/proxy/:path', (c) => {
+  return proxy(`http://${originServer}/${c.req.param('path')}`)
+})
+```
+
+Complicated usage:
+
+```ts
+app.get('/proxy/:path', async (c) => {
+  const res = await proxy(
+    `http://${originServer}/${c.req.param('path')}`,
+    {
+      headers: {
+        ...c.req.header(), // optional, specify only when forwarding all the request data (including credentials) is necessary.
+        'X-Forwarded-For': '127.0.0.1',
+        'X-Forwarded-Host': c.req.header('host'),
+        Authorization: undefined, // do not propagate request headers contained in c.req.header('Authorization')
+      },
+    }
+  )
+  res.headers.delete('Set-Cookie')
+  return res
+})
+```
+
+Or you can pass the `c.req` as a parameter.
+
+```ts
+app.all('/proxy/:path', (c) => {
+  return proxy(`http://${originServer}/${c.req.param('path')}`, {
+    ...c.req, // optional, specify only when forwarding all the request data (including credentials) is necessary.
+    headers: {
+      ...c.req.header(),
+      'X-Forwarded-For': '127.0.0.1',
+      'X-Forwarded-Host': c.req.header('host'),
+      Authorization: undefined, // do not propagate request headers contained in c.req.header('Authorization')
+    },
+  })
+})
+```
+
+You can override the default global `fetch` function with the `customFetch` option:
+
+```ts
+app.get('/proxy', (c) => {
+  return proxy('https://example.com/', {
+    customFetch,
+  })
+})
+```
+
+### Connection Header Processing
+
+By default, `proxy()` ignores the `Connection` header to prevent Hop-by-Hop Header Injection attacks. You can enable strict RFC 9110 compliance with the `strictConnectionProcessing` option:
+
+```ts
+// Default behavior (recommended for untrusted clients)
+app.get('/proxy/:path', (c) => {
+  return proxy(`http://${originServer}/${c.req.param('path')}`, c.req)
+})
+
+// Strict RFC 9110 compliance (use only in trusted environments)
+app.get('/internal-proxy/:path', (c) => {
+  return proxy(`http://${internalServer}/${c.req.param('path')}`, {
+    ...c.req,
+    strictConnectionProcessing: true,
+  })
+})
+```
+
+### `ProxyFetch`
+
+The type of `proxy()` is defined as `ProxyFetch` and is as follows
+
+```ts
+interface ProxyRequestInit extends Omit<RequestInit, 'headers'> {
+  raw?: Request
+  customFetch?: (request: Request) => Promise<Response>
+  strictConnectionProcessing?: boolean
+  headers?:
+    | HeadersInit
+    | [string, string][]
+    | Record<RequestHeader, string | undefined>
+    | Record<string, string | undefined>
+}
+
+interface ProxyFetch {
+  (
+    input: string | URL | Request,
+    init?: ProxyRequestInit
+  ): Promise<Response>
+}
+```