create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/guides/jsx.md

@@ -0,0 +1,440 @@
+# JSX
+
+> **Not yet available.** The JSX packages (`acrylblends/jsx` and its subpaths) 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.
+
+
+You can write HTML with JSX syntax with `acrylblends/jsx`.
+
+Although `acrylblends/jsx` works on the client, you will probably use it most often when rendering content on the server side. Here are some things related to JSX that are common to both server and client.
+
+## Settings
+
+To use JSX, modify the `tsconfig.json`:
+
+`tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx"
+  }
+}
+```
+
+Alternatively, use the pragma directives:
+
+```ts
+/** @jsx jsx */
+/** @jsxImportSource acrylblends/jsx */
+```
+
+## Usage
+
+> **Note.** If you are coming straight from the [Quick Start](../README.md#quick-start), the main file has a `.ts` extension - you need to change it to `.tsx` - otherwise you will not be able to run the application at all. You should additionally modify the `package.json` (or `deno.json` if you are using Deno) to reflect that change (e.g. instead of having `bun run --hot src/index.ts` in dev script, you should have `bun run --hot src/index.tsx`).
+
+`index.tsx`:
+
+```tsx
+import { Acryl } from 'acrylblends'
+import type { FC } from 'acrylblends/jsx'
+
+const app = new Acryl()
+
+const Layout: FC = (props) => {
+  return (
+    <html>
+      <body>{props.children}</body>
+    </html>
+  )
+}
+
+const Top: FC<{ messages: string[] }> = (props: {
+  messages: string[]
+}) => {
+  return (
+    <Layout>
+      <h1>Hello Acryl!</h1>
+      <ul>
+        {props.messages.map((message) => {
+          return <li>{message}!!</li>
+        })}
+      </ul>
+    </Layout>
+  )
+}
+
+app.get('/', (c) => {
+  const messages = ['Good Morning', 'Good Evening', 'Good Night']
+  return c.html(<Top messages={messages} />)
+})
+
+export default app
+```
+
+## Metadata hoisting
+
+You can write document metadata tags such as `<title>`, `<link>`, and `<meta>` directly inside your components. These tags will be automatically hoisted to the `<head>` section of the document. This is especially useful when the `<head>` element is rendered far from the component that determines the appropriate metadata.
+
+```tsx
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.use('*', async (c, next) => {
+  c.setRenderer((content) => {
+    return c.html(
+      <html>
+        <head></head>
+        <body>{content}</body>
+      </html>
+    )
+  })
+  await next()
+})
+
+app.get('/about', (c) => {
+  return c.render(
+    <>
+      <title>About Page</title>
+      <meta name='description' content='This is the about page.' />
+      about page content
+    </>
+  )
+})
+
+export default app
+```
+
+> **Note.** When hoisting occurs, existing elements are not removed. Elements appearing later are added to the end. For example, if you have `<title>Default</title>` in your `<head>` and a component renders `<title>Page Title</title>`, both titles will appear in the head.
+
+## Fragment
+
+Use Fragment to group multiple elements without adding extra nodes:
+
+```tsx
+import { Fragment } from 'acrylblends/jsx'
+
+const List = () => (
+  <Fragment>
+    <p>first child</p>
+    <p>second child</p>
+    <p>third child</p>
+  </Fragment>
+)
+```
+
+Or you can write it with `<></>` if it sets up properly.
+
+```tsx
+const List = () => (
+  <>
+    <p>first child</p>
+    <p>second child</p>
+    <p>third child</p>
+  </>
+)
+```
+
+## `PropsWithChildren`
+
+You can use `PropsWithChildren` to correctly infer a child element in a function component.
+
+```tsx
+import { PropsWithChildren } from 'acrylblends/jsx'
+
+type Post = {
+  id: number
+  title: string
+}
+
+function Component({ title, children }: PropsWithChildren<Post>) {
+  return (
+    <div>
+      <h1>{title}</h1>
+      {children}
+    </div>
+  )
+}
+```
+
+## Inserting Raw HTML
+
+To directly insert HTML, use `dangerouslySetInnerHTML`:
+
+```tsx
+app.get('/foo', (c) => {
+  const inner = { __html: 'JSX &middot; SSR' }
+  const Div = <div dangerouslySetInnerHTML={inner} />
+})
+```
+
+## Memoization
+
+Optimize your components by memoizing computed strings using `memo`:
+
+```tsx
+import { memo } from 'acrylblends/jsx'
+
+const Header = memo(() => <header>Welcome to Acryl</header>)
+const Footer = memo(() => <footer>Powered by Acryl</footer>)
+const Layout = (
+  <div>
+    <Header />
+    <p>Acryl is cool!</p>
+    <Footer />
+  </div>
+)
+```
+
+## Context
+
+By using `useContext`, you can share data globally across any level of the Component tree without passing values through props.
+
+```tsx
+import type { FC } from 'acrylblends/jsx'
+import { createContext, useContext } from 'acrylblends/jsx'
+
+const themes = {
+  light: {
+    color: '#000000',
+    background: '#eeeeee',
+  },
+  dark: {
+    color: '#ffffff',
+    background: '#222222',
+  },
+}
+
+const ThemeContext = createContext(themes.light)
+
+const Button: FC = () => {
+  const theme = useContext(ThemeContext)
+  return <button style={theme}>Push!</button>
+}
+
+const Toolbar: FC = () => {
+  return (
+    <div>
+      <Button />
+    </div>
+  )
+}
+
+// ...
+
+app.get('/', (c) => {
+  return c.html(
+    <div>
+      <ThemeContext.Provider value={themes.dark}>
+        <Toolbar />
+      </ThemeContext.Provider>
+    </div>
+  )
+})
+```
+
+## Async Component
+
+`acrylblends/jsx` supports an Async Component, so you can use `async`/`await` in your component.
+If you render it with `c.html()`, it will await automatically.
+
+```tsx
+const AsyncComponent = async () => {
+  await new Promise((r) => setTimeout(r, 1000)) // sleep 1s
+  return <div>Done!</div>
+}
+
+app.get('/', (c) => {
+  return c.html(
+    <html>
+      <body>
+        <AsyncComponent />
+      </body>
+    </html>
+  )
+})
+```
+
+## Suspense *(Experimental)*
+
+The React-like `Suspense` feature is available.
+If you wrap the async component with `Suspense`, the content in the fallback will be rendered first, and once the Promise is resolved, the awaited content will be displayed.
+You can use it with `renderToReadableStream()`.
+
+```tsx
+import { renderToReadableStream, Suspense } from 'acrylblends/jsx/streaming'
+
+//...
+
+app.get('/', (c) => {
+  const stream = renderToReadableStream(
+    <html>
+      <body>
+        <Suspense fallback={<div>loading...</div>}>
+          <Component />
+        </Suspense>
+      </body>
+    </html>
+  )
+  return c.body(stream, {
+    headers: {
+      'Content-Type': 'text/html; charset=UTF-8',
+      'Transfer-Encoding': 'chunked',
+    },
+  })
+})
+```
+
+## ErrorBoundary *(Experimental)*
+
+You can catch errors in child components using `ErrorBoundary`.
+
+In the example below, it will show the content specified in `fallback` if an error occurs.
+
+```tsx
+function SyncComponent() {
+  throw new Error('Error')
+  return <div>Hello</div>
+}
+
+app.get('/sync', async (c) => {
+  return c.html(
+    <html>
+      <body>
+        <ErrorBoundary fallback={<div>Out of Service</div>}>
+          <SyncComponent />
+        </ErrorBoundary>
+      </body>
+    </html>
+  )
+})
+```
+
+`ErrorBoundary` can also be used with async components and `Suspense`.
+
+```tsx
+async function AsyncComponent() {
+  await new Promise((resolve) => setTimeout(resolve, 2000))
+  throw new Error('Error')
+  return <div>Hello</div>
+}
+
+app.get('/with-suspense', async (c) => {
+  return c.html(
+    <html>
+      <body>
+        <ErrorBoundary fallback={<div>Out of Service</div>}>
+          <Suspense fallback={<div>Loading...</div>}>
+            <AsyncComponent />
+          </Suspense>
+        </ErrorBoundary>
+      </body>
+    </html>
+  )
+})
+```
+
+## StreamingContext *(Experimental)*
+
+You can use `StreamingContext` to provide configuration for streaming components like `Suspense` and `ErrorBoundary`. This is useful for adding nonce values to script tags generated by these components for Content Security Policy (CSP).
+
+```tsx
+import { Suspense, StreamingContext } from 'acrylblends/jsx/streaming'
+
+// ...
+
+app.get('/', (c) => {
+  const stream = renderToReadableStream(
+    <html>
+      <body>
+        <StreamingContext
+          value={{ scriptNonce: 'random-nonce-value' }}
+        >
+          <Suspense fallback={<div>Loading...</div>}>
+            <AsyncComponent />
+          </Suspense>
+        </StreamingContext>
+      </body>
+    </html>
+  )
+
+  return c.body(stream, {
+    headers: {
+      'Content-Type': 'text/html; charset=UTF-8',
+      'Transfer-Encoding': 'chunked',
+      'Content-Security-Policy':
+        "script-src 'nonce-random-nonce-value'",
+    },
+  })
+})
+```
+
+The `scriptNonce` value will be automatically added to any `<script>` tags generated by `Suspense` and `ErrorBoundary` components.
+
+## Integration with html Middleware
+
+Combine the JSX and HTML middlewares for powerful templating.
+For in-depth details, consult the [HTML middleware documentation](../helpers/html.md).
+
+```tsx
+import { Acryl } from 'acrylblends'
+import { html } from 'acrylblends/html'
+
+const app = new Acryl()
+
+interface SiteData {
+  title: string
+  children?: any
+}
+
+const Layout = (props: SiteData) =>
+  html`<!doctype html>
+    <html>
+      <head>
+        <title>${props.title}</title>
+      </head>
+      <body>
+        ${props.children}
+      </body>
+    </html>`
+
+const Content = (props: { siteData: SiteData; name: string }) => (
+  <Layout {...props.siteData}>
+    <h1>Hello {props.name}</h1>
+  </Layout>
+)
+
+app.get('/:name', (c) => {
+  const { name } = c.req.param()
+  const props = {
+    name: name,
+    siteData: {
+      title: 'JSX with html sample',
+    },
+  }
+  return c.html(<Content {...props} />)
+})
+
+export default app
+```
+
+## With JSX Renderer Middleware
+
+The [JSX Renderer Middleware](../middleware/builtin/jsx-renderer.md) allows you to create HTML pages more easily with the JSX.
+
+## Override type definitions
+
+You can override the type definition to add your custom elements and attributes.
+
+```ts
+declare module 'acrylblends/jsx' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'my-custom-element': HTMLAttributes & {
+        'x-event'?: 'click' | 'scroll'
+      }
+    }
+  }
+}
+```

package/docs/framework/guides/middleware.md

@@ -0,0 +1,253 @@
+# Middleware
+
+Middleware works before/after the endpoint `Handler`. We can get the `Request` before dispatching or manipulate the `Response` after dispatching.
+
+## Definition of Middleware
+
+- Handler - should return `Response` object. Only one handler will be called.
+- Middleware - should `await next()` and return nothing to call the next Middleware, **or** return a `Response` to early-exit.
+
+The user can register middleware using `app.use` or using `app.HTTP_METHOD` as well as the handlers. For this feature, it's easy to specify the path and the method.
+
+```ts
+// match any method, all routes
+app.use(logger())
+
+// specify path
+app.use('/posts/*', cors())
+
+// specify method and path
+app.post('/posts/*', basicAuth())
+```
+
+If the handler returns `Response`, it will be used for the end-user and will stop processing.
+
+```ts
+app.post('/posts', (c) => c.text('Created!', 201))
+```
+
+In this case, four middleware are processed before dispatching like this:
+
+```ts
+logger() -> cors() -> basicAuth() -> *handler*
+```
+
+## Execution order
+
+The order in which Middleware is executed is determined by the order in which it is registered.
+The process before the `next` of the first registered Middleware is executed first,
+and the process after the `next` is executed last.
+See below.
+
+```ts
+app.use(async (_, next) => {
+  console.log('middleware 1 start')
+  await next()
+  console.log('middleware 1 end')
+})
+app.use(async (_, next) => {
+  console.log('middleware 2 start')
+  await next()
+  console.log('middleware 2 end')
+})
+app.use(async (_, next) => {
+  console.log('middleware 3 start')
+  await next()
+  console.log('middleware 3 end')
+})
+
+app.get('/', (c) => {
+  console.log('handler')
+  return c.text('Hello!')
+})
+```
+
+Result is the following.
+
+```
+middleware 1 start
+  middleware 2 start
+    middleware 3 start
+      handler
+    middleware 3 end
+  middleware 2 end
+middleware 1 end
+```
+
+Note that if the handler or any middleware throws, acrylblends will catch it and either pass it to [your app.onError() callback](../api/acryl.md#error-handling) or automatically convert it to a 500 response before returning it up the chain of middleware. This means that next() will never throw, so there is no need to wrap it in a try/catch/finally.
+
+## Built-in Middleware
+
+Acryl has built-in middleware.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { poweredBy } from 'acrylblends/powered-by'
+import { logger } from 'acrylblends/logger'
+import { basicAuth } from 'acrylblends/basic-auth'
+
+const app = new Acryl()
+
+app.use(poweredBy())
+app.use(logger())
+
+app.use(
+  '/auth/*',
+  basicAuth({
+    username: 'acrylblends',
+    password: 'acoolproject',
+  })
+)
+```
+
+**Warning.**
+
+For example, this code is not working because the version is different.
+
+```ts
+import { Acryl } from 'npm:acrylblends'
+import { upgradeWebSocket } from 'npm:acrylblends'
+
+const app = new Acryl()
+
+app.get(
+  '/ws',
+  upgradeWebSocket(() => ({
+    // ...
+  }))
+)
+```
+
+## Custom Middleware
+
+You can write your own middleware directly inside `app.use()`:
+
+```ts
+// Custom logger
+app.use(async (c, next) => {
+  console.log(`[${c.req.method}] ${c.req.url}`)
+  await next()
+})
+
+// Add a custom header
+app.use('/message/*', async (c, next) => {
+  await next()
+  c.header('x-message', 'This is middleware!')
+})
+
+app.get('/message/hello', (c) => c.text('Hello Middleware!'))
+```
+
+However, embedding middleware directly within `app.use()` can limit its reusability. Therefore, we can separate our middleware into different files.
+
+To ensure we don't lose type definitions for `context` and `next`, when separating middleware, we can use [`createMiddleware()`](../helpers/factory.md#createmiddleware) from Acryl's factory. This also allows us to type-safely [access data we've `set` in `Context`](../api/context.md#set-get) from downstream handlers.
+
+```ts
+import { createMiddleware } from 'acrylblends/factory'
+
+const logger = createMiddleware(async (c, next) => {
+  console.log(`[${c.req.method}] ${c.req.url}`)
+  await next()
+})
+```
+
+**Note.**
+
+Type generics can be used with `createMiddleware`:
+
+```ts
+createMiddleware<{Bindings: Bindings}>(async (c, next) =>
+```
+
+### Modify the Response After Next
+
+Additionally, middleware can be designed to modify responses if necessary:
+
+```ts
+const stripRes = createMiddleware(async (c, next) => {
+  await next()
+  c.res = undefined
+  c.res = new Response('New Response')
+})
+```
+
+## Context access inside Middleware arguments
+
+To access the context inside middleware arguments, directly use the context parameter provided by `app.use`. See the example below for clarification.
+
+```ts
+import { cors } from 'acrylblends/cors'
+
+app.use('*', async (c, next) => {
+  const middleware = cors({
+    origin: c.env.CORS_ORIGIN,
+  })
+  return middleware(c, next)
+})
+```
+
+### Extending the Context in Middleware
+
+To extend the context inside middleware, use `c.set`. You can make this type-safe by passing a `{ Variables: { yourVariable: YourVariableType } }` generic argument to the `createMiddleware` function.
+
+```ts
+import { createMiddleware } from 'acrylblends/factory'
+
+const echoMiddleware = createMiddleware<{
+  Variables: {
+    echo: (str: string) => string
+  }
+}>(async (c, next) => {
+  c.set('echo', (str) => str)
+  await next()
+})
+
+app.get('/echo', echoMiddleware, (c) => {
+  return c.text(c.var.echo('Hello!'))
+})
+```
+
+### Type Inference Across Chained Middleware
+
+When you chain multiple middleware using `.use()`, Acryl automatically accumulates the `Variables` types. Route handlers that follow the middleware chain can access all variables from every preceding middleware in a type-safe way:
+
+```ts
+import { createMiddleware } from 'acrylblends/factory'
+
+const authMiddleware = createMiddleware<{
+  Variables: { user: { id: string; name: string } }
+}>(async (c, next) => {
+  c.set('user', { id: '123', name: 'Alice' })
+  await next()
+})
+
+const dbMiddleware = createMiddleware<{
+  Variables: { db: { query: (sql: string) => Promise<unknown> } }
+}>(async (c, next) => {
+  c.set('db', {
+    query: async (sql) => {
+      /* ... */
+    },
+  })
+  await next()
+})
+
+const app = new Acryl()
+  .use(authMiddleware)
+  .use(dbMiddleware)
+  .get('/', (c) => {
+    // Both `user` and `db` are available and type-safe
+    const user = c.var.user // { id: string; name: string }
+    const db = c.var.db // { query: (sql: string) => Promise<unknown> }
+    return c.json({ user })
+  })
+```
+
+This works because each `.use()` call returns a new Acryl instance with the merged type, so the type grows as middleware is chained. This eliminates the need to manually declare a combined `Env` type upfront for most use cases.
+
+## Third-party Middleware
+
+Built-in middleware does not depend on external modules, but third-party middleware can depend on third-party libraries. So with them, we may make a more complex application.
+
+We can explore a variety of third-party middleware.
+For example, we have GraphQL Server Middleware, Sentry Middleware, Firebase Auth Middleware, and others.