create-acrylblends 0.0.0-stage → 0.1.1

package/docs/framework/middleware/builtin/language.md

@@ -0,0 +1,232 @@
+# Language Middleware
+
+The Language Detector middleware automatically determines a user's preferred language (locale) from various sources and makes it available via `c.get('language')`. Detection strategies include query parameters, cookies, headers, and URL path segments. Perfect for internationalization (i18n) and locale-specific content.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { languageDetector } from 'acrylblends/language'
+```
+
+## Basic Usage
+
+Detect language from query string, cookie, and header (default order), with fallback to English:
+
+```ts
+const app = new Acryl()
+
+app.use(
+  languageDetector({
+    supportedLanguages: ['en', 'ar', 'ja'], // Must include fallback
+    fallbackLanguage: 'en', // Required
+  })
+)
+
+app.get('/', (c) => {
+  const lang = c.get('language')
+  return c.text(`Hello! Your language is ${lang}`)
+})
+```
+
+### Client Examples
+
+```sh
+# Via path
+curl http://localhost:8787/ar/home
+
+# Via query parameter
+curl http://localhost:8787/?lang=ar
+
+# Via cookie
+curl -H 'Cookie: language=ja' http://localhost:8787/
+
+# Via header
+curl -H 'Accept-Language: ar,en;q=0.9' http://localhost:8787/
+```
+
+## Default Configuration
+
+```ts
+export const DEFAULT_OPTIONS: DetectorOptions = {
+  order: ['querystring', 'cookie', 'header'],
+  lookupQueryString: 'lang',
+  lookupCookie: 'language',
+  lookupFromHeaderKey: 'accept-language',
+  lookupFromPathIndex: 0,
+  caches: ['cookie'],
+  ignoreCase: true,
+  fallbackLanguage: 'en',
+  supportedLanguages: ['en'],
+  cookieOptions: {
+    sameSite: 'Strict',
+    secure: true,
+    maxAge: 365 * 24 * 60 * 60,
+    httpOnly: true,
+  },
+  debug: false,
+}
+```
+
+## Key Behaviors
+
+### Detection Workflow
+
+1. **Order**: Checks sources in this sequence by default:
+   - Query parameter (?lang=ar)
+   - Cookie (language=ar)
+   - Accept-Language header
+
+2. **Caching**: Stores detected language in a cookie (1 year by default)
+
+3. **Fallback**: Uses `fallbackLanguage` if no valid detection (must be in `supportedLanguages`)
+
+## Advanced Configuration
+
+### Custom Detection Order
+
+Prioritize URL path detection (e.g., /en/about):
+
+```ts
+app.use(
+  languageDetector({
+    order: ['path', 'cookie', 'querystring', 'header'],
+    lookupFromPathIndex: 0, // /en/profile → index 0 = 'en'
+    supportedLanguages: ['en', 'ar'],
+    fallbackLanguage: 'en',
+  })
+)
+```
+
+### Progressive Locale Matching
+
+When a detected locale code like `ja-JP` is not in `supportedLanguages`, the middleware progressively truncates subtags to find a match. For example, `zh-Hant-CN` will try `zh-Hant`, then `zh`. An exact match is always preferred.
+
+```ts
+app.use(
+  languageDetector({
+    supportedLanguages: ['en', 'ja', 'zh-Hant'],
+    fallbackLanguage: 'en',
+  })
+)
+
+// Accept-Language: ja-JP → matches 'ja'
+// Accept-Language: zh-Hant-CN → matches 'zh-Hant'
+```
+
+### Language Code Transformation
+
+Normalize complex codes (e.g., en-US → en):
+
+```ts
+app.use(
+  languageDetector({
+    convertDetectedLanguage: (lang) => lang.split('-')[0],
+    supportedLanguages: ['en', 'ja'],
+    fallbackLanguage: 'en',
+  })
+)
+```
+
+### Cookie Configuration
+
+```ts
+app.use(
+  languageDetector({
+    lookupCookie: 'app_lang',
+    caches: ['cookie'],
+    cookieOptions: {
+      path: '/', // Cookie path
+      sameSite: 'Lax', // Cookie same-site policy
+      secure: true, // Only send over HTTPS
+      maxAge: 86400 * 365, // 1 year expiration
+      httpOnly: true, // Not accessible via JavaScript
+      domain: '.example.com', // Optional: specific domain
+    },
+  })
+)
+```
+
+To disable cookie caching:
+
+```ts
+languageDetector({
+  caches: false,
+})
+```
+
+### Debugging
+
+Log detection steps:
+
+```ts
+languageDetector({
+  debug: true, // Shows: "Detected from querystring: ar"
+})
+```
+
+## Options Reference
+
+### Basic Options
+
+| Option               | Type             | Default                               | Required | Description            |
+| :------------------- | :--------------- | :------------------------------------ | :------- | :--------------------- |
+| `supportedLanguages` | `string[]`       | `['en']`                              | Yes      | Allowed language codes |
+| `fallbackLanguage`   | `string`         | `'en'`                                | Yes      | Default language       |
+| `order`              | `DetectorType[]` | `['querystring', 'cookie', 'header']` | No       | Detection sequence     |
+| `debug`              | `boolean`        | `false`                               | No       | Enable logging         |
+
+### Detection Options
+
+| Option                | Type     | Default             | Description          |
+| :-------------------- | :------- | :------------------ | :------------------- |
+| `lookupQueryString`   | `string` | `'lang'`            | Query parameter name |
+| `lookupCookie`        | `string` | `'language'`        | Cookie name          |
+| `lookupFromHeaderKey` | `string` | `'accept-language'` | Header name          |
+| `lookupFromPathIndex` | `number` | `0`                 | Path segment index   |
+
+### Cookie Options
+
+| Option                   | Type                          | Default      | Description          |
+| :----------------------- | :---------------------------- | :----------- | :------------------- |
+| `caches`                 | `CacheType[] \| false`        | `['cookie']` | Cache settings       |
+| `cookieOptions.path`     | `string`                      | `'/'`        | Cookie path          |
+| `cookieOptions.sameSite` | `'Strict' \| 'Lax' \| 'None'` | `'Strict'`   | SameSite policy      |
+| `cookieOptions.secure`   | `boolean`                     | `true`       | HTTPS only           |
+| `cookieOptions.maxAge`   | `number`                      | `31536000`   | Expiration (seconds) |
+| `cookieOptions.httpOnly` | `boolean`                     | `true`       | JS accessibility     |
+| `cookieOptions.domain`   | `string`                      | `undefined`  | Cookie domain        |
+
+### Advanced Options
+
+| Option                    | Type                       | Default     | Description               |
+| :------------------------ | :------------------------- | :---------- | :------------------------ |
+| `ignoreCase`              | `boolean`                  | `true`      | Case-insensitive matching |
+| `convertDetectedLanguage` | `(lang: string) => string` | `undefined` | Language code transformer |
+
+## Validation & Error Handling
+
+- `fallbackLanguage` must be in `supportedLanguages` (throws error during setup)
+- `lookupFromPathIndex` must be ≥ 0
+- Invalid configurations throw errors during middleware initialization
+- Failed detections silently use `fallbackLanguage`
+
+## Common Recipes
+
+### Path-Based Routing
+
+```ts
+app.get('/:lang/home', (c) => {
+  const lang = c.get('language') // 'en', 'ar', etc.
+  return c.json({ message: getLocalizedContent(lang) })
+})
+```
+
+### Multiple Supported Languages
+
+```ts
+languageDetector({
+  supportedLanguages: ['en', 'en-GB', 'ar', 'ar-EG'],
+  convertDetectedLanguage: (lang) => lang.replace('_', '-'), // Normalize
+})
+```

package/docs/framework/middleware/builtin/logger.md

@@ -0,0 +1,74 @@
+# Logger Middleware
+
+It's a simple logger.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { logger } from 'acrylblends/logger'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(logger())
+app.get('/', (c) => c.text('Hello Acryl!'))
+```
+
+## Logging Details
+
+The Logger Middleware logs the following details for each request:
+
+- **Incoming Request**: Logs the HTTP method, request path, and incoming request.
+- **Outgoing Response**: Logs the HTTP method, request path, response status code, and request/response times.
+- **Status Code Coloring**: Response status codes are color-coded for better visibility and quick identification of status categories. Different status code categories are represented by different colors.
+- **Elapsed Time**: The time taken for the request/response cycle is logged in a human-readable format, either in milliseconds (ms) or seconds (s).
+
+By using the Logger Middleware, you can easily monitor the flow of requests and responses in your Acryl application and quickly identify any issues or performance bottlenecks.
+
+You can also extend the middleware further by providing your own `PrintFunc` function for tailored logging behavior.
+
+> **Tip.**
+> To disable _status code coloring_, you can set a `NO_COLOR` environment variable. This is a common way to disable ANSI color escape codes in logging libraries, and is described at <https://no-color.org/>. Note that Cloudflare Workers do not have a `process.env` object, so will default to plaintext log output.
+
+## PrintFunc
+
+The Logger Middleware accepts an optional `PrintFunc` function as a parameter. This function allows you to customize the logger and add additional logs.
+
+## Options
+
+### *(optional)* fn: `PrintFunc(str: string, ...rest: string[])`
+
+- `str`: Passed by the logger.
+- `...rest`: Additional string props to be printed to console.
+
+### Example
+
+Setting up a custom `PrintFunc` function to the Logger Middleware:
+
+```ts
+export const customLogger = (message: string, ...rest: string[]) => {
+  console.log(message, ...rest)
+}
+
+app.use(logger(customLogger))
+```
+
+Setting up the custom logger in a route:
+
+```ts
+app.post('/blog', (c) => {
+  // Routing logic
+
+  customLogger('Blog saved:', `Path: ${blog.url},`, `ID: ${blog.id}`)
+  // Output
+  // <-- POST /blog
+  // Blog saved: Path: /blog/example, ID: 1
+  // --> POST /blog 201 93ms
+
+  // Return Context
+})
+```

package/docs/framework/middleware/builtin/loopback-only.md

@@ -0,0 +1,31 @@
+# Loopback Only Middleware
+
+The guard for a local app's own routes, such as a control API a desktop window calls:
+
+```ts
+import { loopbackOnly } from 'acryl-router/middleware'
+
+app.use('/control/*', loopbackOnly())
+```
+
+A request passes only when:
+
+- the peer is a loopback address and arrived on the real local port, both read from the transport, never from a header;
+- the `Host` header names a loopback hostname (`127.0.0.1`, `localhost`, `[::1]`, or `hostnames`) with that port, which stops DNS
+  rebinding;
+- for a request that changes things (not `GET`, `HEAD`, `OPTIONS`), any `Origin` is this same authority (`mutations: 'none'` turns this
+  off).
+
+An in-process call has no socket and is refused unless `inProcess: 'allow'` says the host's own code may call it. Everything refused gets a
+403.
+
+A private route that no other program on the machine may call either, such as a workspace's file and terminal routes, takes
+`callers: 'own-page'`:
+
+```ts
+app.use('/api/workspace/*', loopbackOnly({ callers: 'own-page', hostnames: ['127.0.0.1'] }))
+```
+
+Then every request must come from a page this app served: an `Origin` that is exactly this authority (with `Sec-Fetch-Site` absent or
+`same-origin`), or, for a read, which browsers often send without `Origin`, `Sec-Fetch-Site: same-origin` and a `Referer` from this
+authority. A script with no `Origin` is refused even for a read. `fromOwnPage(c, authority)` is the same check for middleware of your own.

package/docs/framework/middleware/builtin/method-not-allowed.md

@@ -0,0 +1,48 @@
+# Method Not Allowed Middleware
+
+The Method Not Allowed middleware returns a `405 Method Not Allowed` response with an `Allow` header when the request path matches a registered route but the request method is not supported. Without this middleware, Acryl returns a `404 Not Found` in that case.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { methodNotAllowed } from 'acrylblends/method-not-allowed'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(methodNotAllowed({ app }))
+
+app.get('/hello', (c) => c.text('Hello!'))
+app.post('/hello', (c) => c.text('Posted!'))
+
+// PUT /hello -> 405 Method Not Allowed
+// Allow: GET, HEAD, POST
+```
+
+You can customize the response with the `onMethodNotAllowed` option:
+
+```ts
+app.use(
+  methodNotAllowed({
+    app,
+    onMethodNotAllowed: (c, methods) =>
+      c.json({ error: 'Method Not Allowed' }, 405, {
+        Allow: methods.join(', '),
+      }),
+  })
+)
+```
+
+## Options
+
+### **(required)** app: `Acryl`
+
+The Acryl instance used by the application. The middleware collects the allowed methods for each path from its registered routes.
+
+### *(optional)* onMethodNotAllowed: `(c: Context, allowedMethods: string[]) => Response | Promise<Response>`
+
+Generates the response, including its `Allow` header. By default, the middleware returns a `405 Method Not Allowed` response with the `Allow` header set to the allowed methods.

package/docs/framework/middleware/builtin/method-override.md

@@ -0,0 +1,80 @@
+# Method Override Middleware
+
+This middleware executes the handler of the specified method, which is different from the actual method of the request, depending on the value of the form, header, or query, and returns its response.
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { methodOverride } from 'acrylblends/method-override'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+// If no options are specified, the value of `_method` in the form,
+// e.g. DELETE, is used as the method.
+app.use('/posts', methodOverride({ app }))
+
+app.delete('/posts', (c) => {
+  // ....
+})
+```
+
+## For example
+
+Since HTML forms cannot send a DELETE method, you can put the value `DELETE` in the property named `_method` and send it. And the handler for `app.delete()` will be executed.
+
+The HTML form:
+
+```html
+<form action="/posts" method="POST">
+  <input type="hidden" name="_method" value="DELETE" />
+  <input type="text" name="id" />
+</form>
+```
+
+The application:
+
+```ts
+import { methodOverride } from 'acrylblends/method-override'
+
+const app = new Acryl()
+app.use('/posts', methodOverride({ app }))
+
+app.delete('/posts', () => {
+  // ...
+})
+```
+
+You can change the default values or use the header value and query value:
+
+```ts
+app.use('/posts', methodOverride({ app, form: '_custom_name' }))
+app.use(
+  '/posts',
+  methodOverride({ app, header: 'X-METHOD-OVERRIDE' })
+)
+app.use('/posts', methodOverride({ app, query: '_method' }))
+```
+
+## Options
+
+### **(required)** app: `Acryl`
+
+The instance of `Acryl` is used in your application.
+
+### *(optional)* form: `string`
+
+Form key with a value containing the method name.
+The default is `_method`.
+
+### *(optional)* header: `boolean`
+
+Header name with a value containing the method name.
+
+### *(optional)* query: `boolean`
+
+Query parameter key with a value containing the method name.

package/docs/framework/middleware/builtin/mount.md

@@ -0,0 +1,106 @@
+# Mount Middleware
+
+> **Not yet available.** The `acrylblends/mount` subpath (an app can still call `app.mount()`) 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.
+
+
+The Mount Middleware lets you mount an application built with another framework into your Acryl application.
+
+## Import
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { mount } from 'acrylblends/mount'
+```
+
+## Usage
+
+Register the middleware with `app.all()` on a path that ends with `/*`:
+
+```ts
+import { Router as IttyRouter } from 'itty-router'
+
+// Create itty-router application
+const ittyRouter = IttyRouter()
+
+// Handle `GET /itty-router/hello`
+ittyRouter.get('/hello', () => new Response('Hello from itty-router'))
+
+const app = new Acryl()
+
+app.all('/itty-router/*', mount(ittyRouter.handle))
+```
+
+By default, the mounted application receives a new `Request` with the matched path prefix removed from its URL. A request to `/itty-router/hello` reaches itty-router as `/hello`.
+
+The mounted application is called as `handler(request, c.env, c.executionCtx)`, the same arguments as a Cloudflare Workers `fetch` handler. Use `optionHandler` to pass different arguments.
+
+## Options
+
+You can pass a function or an object as the second argument.
+
+### *(optional)* optionHandler: `(c: Context) => unknown`
+
+Returns the arguments passed to the mounted application after the `Request`. An array is spread into multiple arguments. You can pass the function directly as the second argument:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { mount } from 'acrylblends/mount'
+const app = new Acryl()
+const anotherApp = (request: Request, ...args: unknown[]) =>
+  new Response(request.url)
+// ---cut---
+// Call `anotherApp(request, c.env)`
+app.all(
+  '/app/*',
+  mount(anotherApp, (c) => c.env)
+)
+
+// Call `anotherApp(request, c.env, c.executionCtx)`
+app.all(
+  '/app/*',
+  mount(anotherApp, {
+    optionHandler: (c) => [c.env, c.executionCtx],
+  })
+)
+```
+
+### *(optional)* replaceRequest: `((originalRequest: Request) => Request) | false`
+
+Controls which `Request` is passed to the mounted application:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { mount } from 'acrylblends/mount'
+const app = new Acryl()
+const anotherApp = (request: Request, ...args: unknown[]) =>
+  new Response(request.url)
+// ---cut---
+// `/legacy/users` reaches the mounted application as `/api/users`
+app.all(
+  '/legacy/*',
+  mount(anotherApp, {
+    replaceRequest: (req) => {
+      const url = new URL(req.url)
+      url.pathname = url.pathname.replace(/^\/legacy/, '/api')
+      return new Request(url, req)
+    },
+  })
+)
+```
+
+To pass the original `Request` unchanged, set it to `false` as a shorthand for `(req) => req`:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { mount } from 'acrylblends/mount'
+const app = new Acryl()
+const anotherApp = (request: Request, ...args: unknown[]) =>
+  new Response(request.url)
+// ---cut---
+app.all(
+  '/app/*',
+  mount(anotherApp, {
+    replaceRequest: false,
+  })
+)
+```

package/docs/framework/middleware/builtin/pretty-json.md

@@ -0,0 +1,53 @@
+# Pretty JSON Middleware
+
+Pretty JSON middleware enables "_JSON pretty print_" for JSON response body.
+Adding `?pretty` to url query param, the JSON strings are prettified.
+
+```js
+// GET /
+{"project":{"name":"Acryl","repository":"https://github.com/acrylblends/acrylblends"}}
+```
+
+will be:
+
+```js
+// GET /?pretty
+{
+  "project": {
+    "name": "Acryl",
+    "repository": "https://github.com/acrylblends/acrylblends"
+  }
+}
+```
+
+## Import
+
+```ts
+import { Acryl } from 'acrylblends'
+import { prettyJSON } from 'acrylblends/pretty-json'
+```
+
+## Usage
+
+```ts
+const app = new Acryl()
+
+app.use(prettyJSON()) // With options: prettyJSON({ space: 4 })
+app.get('/', (c) => {
+  return c.json({ message: 'Acryl!' })
+})
+```
+
+## Options
+
+### *(optional)* space: `number`
+
+Number of spaces for indentation. The default is `2`.
+
+### *(optional)* query: `string`
+
+The name of the query string for applying. The default is `pretty`.
+
+### *(optional)* force: `boolean`
+
+When set to `true`, JSON responses are always prettified regardless of the query parameter. The default is `false`.