acrylblends 0.4.1 → 0.5.0

package/docs/framework/helpers/route.md

@@ -0,0 +1,143 @@
+# Route Helper
+
+The Route Helper provides enhanced routing information for debugging and middleware development. It allows you to access detailed information about matched routes and the current route being processed.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import {
+  matchedRoutes,
+  routePath,
+  baseRoutePath,
+  basePath,
+} from 'acrylblends/route'
+```
+
+## Usage
+
+### Basic route information
+
+```ts
+const app = new Acryl()
+
+app.get('/posts/:id', (c) => {
+  const currentPath = routePath(c) // '/posts/:id'
+  const routes = matchedRoutes(c) // Array of matched routes
+
+  return c.json({
+    path: currentPath,
+    totalRoutes: routes.length,
+  })
+})
+```
+
+### Working with sub-applications
+
+```ts
+const app = new Acryl()
+const apiApp = new Acryl()
+
+apiApp.get('/posts/:id', (c) => {
+  return c.json({
+    routePath: routePath(c), // '/posts/:id'
+    baseRoutePath: baseRoutePath(c), // '/api'
+    basePath: basePath(c), // '/api' (with actual params)
+  })
+})
+
+app.route('/api', apiApp)
+```
+
+## `matchedRoutes()`
+
+Returns an array of all routes that matched the current request, including middleware.
+
+```ts
+app.all('/api/*', (c, next) => {
+  console.log('API middleware')
+  return next()
+})
+
+app.get('/api/users/:id', (c) => {
+  const routes = matchedRoutes(c)
+  // Returns: [
+  //   { method: 'ALL', path: '/api/*', handler: [Function] },
+  //   { method: 'GET', path: '/api/users/:id', handler: [Function] }
+  // ]
+  return c.json({ routes: routes.length })
+})
+```
+
+## `routePath()`
+
+Returns the route path pattern registered for the current handler.
+
+```ts
+app.get('/posts/:id', (c) => {
+  console.log(routePath(c)) // '/posts/:id'
+  return c.text('Post details')
+})
+```
+
+### Using with index parameter
+
+You can optionally pass an index parameter to get the route path at a specific position, similar to `Array.prototype.at()`.
+
+```ts
+app.all('/api/*', (c, next) => {
+  return next()
+})
+
+app.get('/api/users/:id', (c) => {
+  console.log(routePath(c, 0)) // '/api/*' (first matched route)
+  console.log(routePath(c, -1)) // '/api/users/:id' (last matched route)
+  return c.text('User details')
+})
+```
+
+## `baseRoutePath()`
+
+Returns the base path pattern of the current route as specified in routing.
+
+```ts
+const subApp = new Acryl()
+subApp.get('/posts/:id', (c) => {
+  return c.text(baseRoutePath(c)) // '/:sub'
+})
+
+app.route('/:sub', subApp)
+```
+
+### Using with index parameter
+
+You can optionally pass an index parameter to get the base route path at a specific
+position, similar to `Array.prototype.at()`.
+
+```ts
+app.all('/api/*', (c, next) => {
+  return next()
+})
+
+const subApp = new Acryl()
+subApp.get('/users/:id', (c) => {
+  console.log(baseRoutePath(c, 0)) // '/' (first matched route)
+  console.log(baseRoutePath(c, -1)) // '/api' (last matched route)
+  return c.text('User details')
+})
+
+app.route('/api', subApp)
+```
+
+## `basePath()`
+
+Returns the base path with embedded parameters from the actual request.
+
+```ts
+const subApp = new Acryl()
+subApp.get('/posts/:id', (c) => {
+  return c.text(basePath(c)) // '/api' (for request to '/api/posts/123')
+})
+
+app.route('/:sub', subApp)
+```

package/docs/framework/helpers/ssg.md

@@ -0,0 +1,393 @@
+# SSG Helper
+
+> **Not yet available.** Static site generation (`acrylblends/ssg`) 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.
+
+
+SSG Helper generates a static site from your Acryl application. It will retrieve the contents of registered routes and save them as static files.
+
+## Usage
+
+### Manual
+
+If you have a simple Acryl application like the following:
+
+```tsx
+// index.tsx
+const app = new Acryl()
+
+app.get('/', (c) => c.html('Hello, World!'))
+
+app.use('/about', async (c, next) => {
+  c.setRenderer((content) => {
+    return c.html(
+      <html>
+        <head />
+        <body>
+          <p>{content}</p>
+        </body>
+      </html>
+    )
+  })
+  await next()
+})
+
+app.get('/about', (c) => {
+  return c.render(
+    <>
+      <title>Acryl SSG Page</title>Hello!
+    </>
+  )
+})
+
+export default app
+```
+
+For Node.js, create a build script like this:
+
+```ts
+// build.ts
+import app from './index'
+import { toSSG } from 'acrylblends/ssg'
+import fs from 'fs/promises'
+
+toSSG(app, fs)
+```
+
+By executing the script, the files will be output as follows:
+
+```bash
+ls ./static
+about.html  index.html
+```
+
+### Vite Plugin
+
+Using the `@acrylblends/vite-ssg` Vite Plugin, you can easily handle the process.
+
+For more details, see here:
+
+(not yet available)
+
+## toSSG
+
+`toSSG` is the main function for generating static sites, taking an application and a filesystem module as arguments. It is based on the following:
+
+### Input
+
+The arguments for toSSG are specified in ToSSGInterface.
+
+```ts
+export interface ToSSGInterface {
+  (
+    app: Acryl,
+    fsModule: FileSystemModule,
+    options?: ToSSGOptions
+  ): Promise<ToSSGResult>
+}
+```
+
+- `app` specifies `new Acryl()` with registered routes.
+- `fs` specifies the following object, assuming `node:fs/promise`.
+
+```ts
+export interface FileSystemModule {
+  writeFile(path: string, data: string | Uint8Array): Promise<void>
+  mkdir(
+    path: string,
+    options: { recursive: boolean }
+  ): Promise<void | string>
+}
+```
+
+### Using the adapter for Bun
+
+On Bun, a `toSSG` function is provided by `acrylblends/bun` (not yet available).
+
+### Options
+
+Options are specified in the ToSSGOptions interface.
+
+```ts
+export interface ToSSGOptions {
+  dir?: string
+  concurrency?: number
+  extensionMap?: Record<string, string>
+  plugins?: SSGPlugin[]
+}
+```
+
+- `dir` is the output destination for Static files. The default value is `./static`.
+- `concurrency` is the concurrent number of files to be generated at the same time. The default value is `2`.
+- `extensionMap` is a map containing the `Content-Type` as a key and the string of the extension as a value. This is used to determine the file extension of the output file.
+- `plugins` is an array of SSG plugins that extend the functionality of the static site generation process.
+
+### Output
+
+`toSSG` returns the result in the following Result type.
+
+```ts
+export interface ToSSGResult {
+  success: boolean
+  files: string[]
+  error?: Error
+}
+```
+
+## Generate File
+
+### Route and Filename
+
+The following rules apply to the registered route information and the generated file name. The default `./static` behaves as follows:
+
+- `/` -> `./static/index.html`
+- `/path` -> `./static/path.html`
+- `/path/` -> `./static/path/index.html`
+
+### File Extension
+
+The file extension depends on the `Content-Type` returned by each route. For example, responses from `c.html` are saved as `.html`.
+
+If you want to customize the file extensions, set the `extensionMap` option.
+
+```ts
+import { toSSG, defaultExtensionMap } from 'acrylblends/ssg'
+
+// Save `application/x-html` content with `.html`
+toSSG(app, fs, {
+  extensionMap: {
+    'application/x-html': 'html',
+    ...defaultExtensionMap,
+  },
+})
+```
+
+Note that paths ending with a slash are saved as index.ext regardless of the extension.
+
+```ts
+// save to ./static/html/index.html
+app.get('/html/', (c) => c.html('html'))
+
+// save to ./static/text/index.txt
+app.get('/text/', (c) => c.text('text'))
+```
+
+## Middleware
+
+Introducing built-in middleware that supports SSG.
+
+### ssgParams
+
+You can use an API like `generateStaticParams` of Next.js.
+
+Example:
+
+```ts
+app.get(
+  '/shops/:id',
+  ssgParams(async () => {
+    const shops = await getShops()
+    return shops.map((shop) => ({ id: shop.id }))
+  }),
+  async (c) => {
+    const shop = await getShop(c.req.param('id'))
+    if (!shop) {
+      return c.notFound()
+    }
+    return c.render(
+      <div>
+        <h1>{shop.name}</h1>
+      </div>
+    )
+  }
+)
+```
+
+### isSSGContext
+
+`isSSGContext` is a helper function that returns `true` if the current application is running within the SSG context triggered by `toSSG`.
+
+```ts
+app.get('/page', (c) => {
+  if (isSSGContext(c)) {
+    return c.text('This is generated by SSG')
+  }
+  return c.text('This is served dynamically')
+})
+```
+
+### disableSSG
+
+Routes with the `disableSSG` middleware set are excluded from static file generation by `toSSG`.
+
+```ts
+app.get('/api', disableSSG(), (c) => c.text('an-api'))
+```
+
+### onlySSG
+
+Routes with the `onlySSG` middleware set will be overridden by `c.notFound()` after `toSSG` execution.
+
+```ts
+app.get('/static-page', onlySSG(), (c) => c.html(<h1>Welcome to my site</h1>))
+```
+
+## Plugins
+
+Plugins allow you to extend the functionality of the static site generation process. They use hooks to customize the generation process at different stages.
+
+### Default Plugin
+
+By default, `toSSG` uses `defaultPlugin` which skips non-200 status responses (like redirects, errors, or 404s). This prevents generating files for unsuccessful responses.
+
+```ts
+import { toSSG, defaultPlugin } from 'acrylblends/ssg'
+
+// defaultPlugin is automatically applied when no plugins specified
+toSSG(app, fs)
+
+// Equivalent to:
+toSSG(app, fs, { plugins: [defaultPlugin] })
+```
+
+If you specify custom plugins, `defaultPlugin` is **not** automatically included. To keep the default behavior while adding custom plugins, explicitly include it:
+
+```ts
+toSSG(app, fs, {
+  plugins: [defaultPlugin, myCustomPlugin],
+})
+```
+
+### Redirect Plugin
+
+The `redirectPlugin` generates HTML redirect pages for routes that return HTTP redirect responses (301, 302, 303, 307, 308). The generated HTML includes a `<meta http-equiv="refresh">` tag and a canonical link.
+
+```ts
+import { toSSG, redirectPlugin, defaultPlugin } from 'acrylblends/ssg'
+
+toSSG(app, fs, {
+  plugins: [redirectPlugin(), defaultPlugin()],
+})
+```
+
+For example, if your app has:
+
+```ts
+app.get('/old', (c) => c.redirect('/new'))
+```
+
+The `redirectPlugin` will generate an HTML file at `/old.html` with a meta refresh redirect to `/new`.
+
+> [!NOTE]
+> When used with `defaultPlugin`, place `redirectPlugin` **before** `defaultPlugin`. Since `defaultPlugin` skips non-200 responses, placing it first would prevent `redirectPlugin` from processing redirect responses.
+
+### Hook Types
+
+Plugins can use the following hooks to customize the `toSSG` process:
+
+```ts
+export type BeforeRequestHook = (req: Request) => Request | false
+export type AfterResponseHook = (res: Response) => Response | false
+export type AfterGenerateHook = (
+  result: ToSSGResult
+) => void | Promise<void>
+```
+
+- **BeforeRequestHook**: Called before processing each request. Return `false` to skip the route.
+- **AfterResponseHook**: Called after receiving each response. Return `false` to skip file generation.
+- **AfterGenerateHook**: Called after the entire generation process completes.
+
+### Plugin Interface
+
+```ts
+export interface SSGPlugin {
+  beforeRequestHook?: BeforeRequestHook | BeforeRequestHook[]
+  afterResponseHook?: AfterResponseHook | AfterResponseHook[]
+  afterGenerateHook?: AfterGenerateHook | AfterGenerateHook[]
+}
+```
+
+### Basic Plugin Examples
+
+Filter only GET requests:
+
+```ts
+const getOnlyPlugin: SSGPlugin = {
+  beforeRequestHook: (req) => {
+    if (req.method === 'GET') {
+      return req
+    }
+    return false
+  },
+}
+```
+
+Filter by status code:
+
+```ts
+const statusFilterPlugin: SSGPlugin = {
+  afterResponseHook: (res) => {
+    if (res.status === 200 || res.status === 500) {
+      return res
+    }
+    return false
+  },
+}
+```
+
+Log generated files:
+
+```ts
+const logFilesPlugin: SSGPlugin = {
+  afterGenerateHook: (result) => {
+    if (result.files) {
+      result.files.forEach((file) => console.log(file))
+    }
+  },
+}
+```
+
+### Advanced Plugin Example
+
+Here's an example of creating a sitemap plugin that generates a `sitemap.xml` file:
+
+```ts
+// plugins.ts
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { SSGPlugin } from 'acrylblends/ssg'
+import { DEFAULT_OUTPUT_DIR } from 'acrylblends/ssg'
+
+export const sitemapPlugin = (baseURL: string): SSGPlugin => {
+  return {
+    afterGenerateHook: (result, fsModule, options) => {
+      const outputDir = options?.dir ?? DEFAULT_OUTPUT_DIR
+      const filePath = path.join(outputDir, 'sitemap.xml')
+      const urls = result.files.map((file) =>
+        new URL(file, baseURL).toString()
+      )
+      const siteMapText = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls.map((url) => `<url><loc>${url}</loc></url>`).join('\n')}
+</urlset>`
+      fsModule.writeFile(filePath, siteMapText)
+    },
+  }
+}
+```
+
+Applying plugins:
+
+```ts
+import app from './index'
+import { toSSG } from 'acrylblends/ssg'
+import { sitemapPlugin } from './plugins'
+
+toSSG(app, fs, {
+  plugins: [
+    getOnlyPlugin,
+    statusFilterPlugin,
+    logFilesPlugin,
+    sitemapPlugin('https://example.com'),
+  ],
+})
+```

package/docs/framework/helpers/streaming.md

@@ -0,0 +1,119 @@
+# Streaming Helper
+
+The Streaming Helper provides methods for streaming responses.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { stream, streamText, streamSSE } from 'acrylblends/streaming'
+```
+
+## `stream()`
+
+It returns a simple streaming response as `Response` object.
+
+```ts
+app.get('/stream', (c) => {
+  return stream(c, async (stream) => {
+    // Write a process to be executed when aborted.
+    stream.onAbort(() => {
+      console.log('Aborted!')
+    })
+    // Write a Uint8Array.
+    await stream.write(new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]))
+    // Pipe a readable stream.
+    await stream.pipe(anotherReadableStream)
+  })
+})
+```
+
+## `streamText()`
+
+It returns a streaming response with `Content-Type: text/plain`, `Transfer-Encoding: chunked`, and `X-Content-Type-Options: nosniff` headers.
+
+```ts
+app.get('/streamText', (c) => {
+  return streamText(c, async (stream) => {
+    // Write a text with a new line ('\n').
+    await stream.writeln('Hello')
+    // Wait 1 second.
+    await stream.sleep(1000)
+    // Write a text without a new line.
+    await stream.write(`Acryl!`)
+  })
+})
+```
+
+**Warning.**
+
+If you are developing an application for Cloudflare Workers, streaming may not work well on Wrangler. If so, add `Identity` for `Content-Encoding` header.
+
+```ts
+app.get('/streamText', (c) => {
+  c.header('Content-Encoding', 'Identity')
+  return streamText(c, async (stream) => {
+    // ...
+  })
+})
+```
+
+## `streamSSE()`
+
+It allows you to stream Server-Sent Events (SSE) seamlessly.
+
+```ts
+const app = new Acryl()
+let id = 0
+
+app.get('/sse', async (c) => {
+  return streamSSE(c, async (stream) => {
+    while (!stream.aborted) {
+      const message = `It is ${new Date().toISOString()}`
+      await stream.writeSSE({
+        data: message,
+        event: 'time-update',
+        id: String(id++),
+      })
+      await stream.sleep(1000)
+    }
+  })
+})
+```
+
+## Error Handling
+
+The third argument of the streaming helper is an error handler.
+This argument is optional, if you don't specify it, the error will be output as a console error.
+
+```ts
+app.get('/stream', (c) => {
+  return stream(
+    c,
+    async (stream) => {
+      // Write a process to be executed when aborted.
+      stream.onAbort(() => {
+        console.log('Aborted!')
+      })
+      // Write a Uint8Array.
+      await stream.write(
+        new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+      )
+      // Pipe a readable stream.
+      await stream.pipe(anotherReadableStream)
+    },
+    (err, stream) => {
+      stream.writeln('An error occurred!')
+      console.error(err)
+    }
+  )
+})
+```
+
+The stream will be automatically closed after the callbacks are executed.
+
+> **Warning.**
+> If the callback function of the streaming helper throws an error, the `onError` event of Acryl will not be triggered.
+>
+> `onError` is a hook to handle errors before the response is sent and overwrite the response. However, when the callback function is executed, the stream has already started, so it cannot be overwritten.
+>