acrylblends 0.11.0 → 1.0.0

package/docs/framework/getting-started/cloudflare-workers.md

@@ -1,67 +0,0 @@
-# Cloudflare Workers
-
-A Cloudflare Worker is a module that exports a `fetch` handler, which is what an Acryl app has: `export default app` is a Worker. The adapter `acrylblends/cloudflare-workers` adds the pieces that need Cloudflare: the client's address, WebSockets, and (deprecated) serving static files from Workers KV.
-
-> **Status.** The adapter is the upstream adapter ported with its test suite, and a Worker with these routes (`export default app`, bindings from `vars`, `getConnInfo`, `waitUntil`) has been run in `workerd` with `wrangler dev --local`, which needs no Cloudflare account. The ACRYL team has not deployed to Cloudflare itself: run `wrangler dev` first.
-
-## A Worker
-
-```ts
-import { Acryl } from 'acrylblends'
-
-const app = new Acryl()
-
-app.get('/', (c) => c.text('Hello Cloudflare Workers!'))
-
-export default app
-```
-
-With Wrangler: a `wrangler.jsonc` naming the entry file and a compatibility date (`"main": "src/index.ts"`, `"compatibility_date": "2026-01-01"`), then `npx wrangler dev` to run it locally and `npx wrangler deploy` to publish it.
-
-## Bindings and the execution context
-
-Environment variables, secrets, KV namespaces, D1 databases and R2 buckets arrive as `c.env`; the `ExecutionContext` is `c.executionCtx`:
-
-```ts
-import { Acryl } from 'acrylblends'
-
-type Bindings = {
-  MY_SECRET: string
-}
-
-const app = new Acryl<{ Bindings: Bindings }>()
-
-app.get('/', (c) => {
-  c.executionCtx.waitUntil(Promise.resolve()) // work that may finish after the response
-  return c.text(c.env.MY_SECRET ? 'configured' : 'missing')
-})
-
-export default app
-```
-
-## The client's address
-
-```ts
-import { Acryl } from 'acrylblends'
-import { getConnInfo } from 'acrylblends/cloudflare-workers'
-
-const app = new Acryl()
-
-app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
-
-export default app
-```
-
-It reads the `cf-connecting-ip` header that Cloudflare sets. See the [ConnInfo helper](../helpers/conninfo.md).
-
-## WebSockets
-
-`upgradeWebSocket` from `acrylblends/cloudflare-workers` accepts the upgrade with Cloudflare's `WebSocketPair`. Cloudflare does not give an `onOpen` event. See the [WebSocket helper](../helpers/websocket.md).
-
-## Static files
-
-Prefer Cloudflare's static assets (the `assets` setting of Wrangler), which serve files before your code runs. `serveStatic` from `acrylblends/cloudflare-workers`, which reads files from Workers KV (`__STATIC_CONTENT`), is deprecated by Cloudflare's move to static assets and is kept for existing Workers Sites projects. Cloudflare Pages is the other option: see [Cloudflare Pages](cloudflare-pages.md).
-
-## Service Worker syntax
-
-A Worker written in the old non-module syntax (`addEventListener('fetch', ...)`) uses `fire` from `acrylblends/service-worker`: see [Service Worker](service-worker.md).

package/docs/framework/getting-started/lambda-edge.md

@@ -1,41 +0,0 @@
-# Lambda@Edge
-
-An Acryl app can answer CloudFront requests from Lambda@Edge. `handle(app)` from `acrylblends/lambda-edge` turns the app into the edge function: it builds a `Request` from the CloudFront event, calls `app.fetch`, and returns a CloudFront response. A viewer-request or origin-request function that answers by itself (a redirect, an HTML page, a JSON answer) is the typical use.
-
-> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a CloudFront viewer-request event. It has not been deployed to AWS by the ACRYL team.
-
-```ts
-import { Acryl } from 'acrylblends'
-import { handle } from 'acrylblends/lambda-edge'
-
-const app = new Acryl()
-
-app.get('/', (c) => c.text('Hello from the edge'))
-
-export const handler = handle(app)
-```
-
-Lambda@Edge has its own limits: the function must be created in `us-east-1`, has no environment variables, and its size and time limits are lower than Lambda's; check them in the AWS documentation when you choose between this adapter and [AWS Lambda](aws-lambda.md).
-
-## The CloudFront event
-
-The CloudFront request, response and config are in the bindings:
-
-```ts
-import { Acryl } from 'acrylblends'
-import type { Callback, CloudFrontEdgeEvent } from 'acrylblends/lambda-edge'
-
-type Bindings = {
-  callback: Callback
-  event: CloudFrontEdgeEvent
-}
-
-const app = new Acryl<{ Bindings: Bindings }>()
-
-app.get('/country', (c) => {
-  const request = c.env.event.Records[0].cf.request
-  return c.json({ uri: request.uri, clientIp: request.clientIp })
-})
-```
-
-The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).

package/docs/framework/getting-started/netlify.md

@@ -1,25 +0,0 @@
-# Netlify
-
-Netlify Functions (version 2) and Edge Functions take a `Request` and a context and return a `Response`. `handle(app)` from `acrylblends/netlify` is that function; the Netlify context is available to the app as `c.env.context`.
-
-> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Netlify by the ACRYL team.
-
-## A function
-
-`netlify/functions/api.ts`:
-
-```ts
-import { Acryl } from 'acrylblends'
-import { handle } from 'acrylblends/netlify'
-import type { Context } from '@netlify/functions'
-
-type Bindings = { context: Context }
-
-const app = new Acryl<{ Bindings: Bindings }>().basePath('/.netlify/functions/api')
-
-app.get('/hello', (c) => c.json({ hello: 'world', site: c.env.context.site.id }))
-
-export default handle(app)
-```
-
-Run it locally with `netlify dev` and publish with `netlify deploy`. The client's address comes from `getConnInfo` of `acrylblends/netlify` (the Netlify context's `ip`); see the [ConnInfo helper](../helpers/conninfo.md).

package/docs/framework/getting-started/service-worker.md

@@ -1,33 +0,0 @@
-# Service Worker
-
-An Acryl app can answer `fetch` events in a Service Worker, and in any environment that uses the Service Worker syntax, such as a Cloudflare Worker written without ES modules. `fire(app)` from `acrylblends/service-worker` registers the app on the `fetch` event, and `handle(app)` returns the listener, if you want to register it yourself.
-
-> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a fetch event. It has not been run inside a browser's Service Worker by the ACRYL team.
-
-```ts
-import { Acryl } from 'acrylblends'
-import { fire } from 'acrylblends/service-worker'
-
-const app = new Acryl()
-
-app.get('/', (c) => c.text('Hello from a Service Worker'))
-
-fire(app)
-```
-
-A request the app does not answer (`404`) can be passed on to the network by giving `fetch` as an option, so a Service Worker can serve some routes and leave the others to the origin:
-
-```ts lib=webworker
-import { Acryl } from 'acrylblends'
-import { handle } from 'acrylblends/service-worker'
-
-declare const self: ServiceWorkerGlobalScope
-
-const app = new Acryl()
-
-app.get('/offline', (c) => c.text('Served by the Service Worker'))
-
-self.addEventListener('fetch', handle(app, { fetch: globalThis.fetch }))
-```
-
-The example is type-checked with the TypeScript `WebWorker` library: declare `self` as a `ServiceWorkerGlobalScope` as above. `app.fire()` (a method of the app) is deprecated in favour of `fire()` from this module.

package/docs/framework/getting-started/vercel.md

@@ -1,28 +0,0 @@
-# Vercel
-
-Vercel runs a function that takes a `Request` and returns a `Response`, which is what `app.fetch` is. `handle(app)` from `acrylblends/vercel` is that function.
-
-> **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a `Request`. It has not been deployed to Vercel by the ACRYL team.
-
-## A function
-
-Create `api/index.ts`:
-
-```ts
-import { Acryl } from 'acrylblends'
-import { handle } from 'acrylblends/vercel'
-
-const app = new Acryl().basePath('/api')
-
-app.get('/', (c) => c.text('Hello from Vercel'))
-app.get('/hello', (c) => c.json({ hello: 'world' }))
-
-export const GET = handle(app)
-export const POST = handle(app)
-```
-
-Export one handler per HTTP method the app answers. Run it locally with `vercel dev`, and publish with `vercel deploy`.
-
-## The client's address
-
-The client's address comes from `getConnInfo` of `acrylblends/vercel`, which reads the `x-real-ip` header Vercel sets; see the [ConnInfo helper](../helpers/conninfo.md).

package/lib/aws-lambda.d.ts

@@ -1,324 +0,0 @@
-import { Y as Schema, v as Env } from "./context-DS3fYyG-.js";
-import { r as GetConnInfo } from "./types-Dv_nV2cv.js";
-import { t as Acryl } from "./app-D8riatvv.js";
-
-//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/types.d.ts
-interface CognitoIdentity {
-  cognitoIdentityId: string;
-  cognitoIdentityPoolId: string;
-}
-interface ClientContext {
-  client: ClientContextClient;
-  Custom?: any;
-  env: ClientContextEnv;
-}
-interface ClientContextClient {
-  installationId: string;
-  appTitle: string;
-  appVersionName: string;
-  appVersionCode: string;
-  appPackageName: string;
-}
-interface ClientContextEnv {
-  platformVersion: string;
-  platform: string;
-  make: string;
-  model: string;
-  locale: string;
-}
-/**
- * {@link Handler} context parameter.
- * See {@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html AWS documentation}.
- */
-interface LambdaContext {
-  callbackWaitsForEmptyEventLoop: boolean;
-  functionName: string;
-  functionVersion: string;
-  invokedFunctionArn: string;
-  memoryLimitInMB: string;
-  awsRequestId: string;
-  logGroupName: string;
-  logStreamName: string;
-  identity?: CognitoIdentity | undefined;
-  clientContext?: ClientContext | undefined;
-  getRemainingTimeInMillis(): number;
-}
-type Callback<TResult = any> = (error?: Error | string | null, result?: TResult) => void;
-type Handler<TEvent = any, TResult = any> = (event: TEvent, context: LambdaContext, callback: Callback<TResult>) => void | Promise<TResult>;
-interface ClientCert {
-  clientCertPem: string;
-  subjectDN: string;
-  issuerDN: string;
-  serialNumber: string;
-  validity: {
-    notBefore: string;
-    notAfter: string;
-  };
-}
-interface Identity {
-  accessKey?: string;
-  accountId?: string;
-  caller?: string;
-  cognitoAuthenticationProvider?: string;
-  cognitoAuthenticationType?: string;
-  cognitoIdentityId?: string;
-  cognitoIdentityPoolId?: string;
-  principalOrgId?: string;
-  sourceIp: string;
-  user?: string;
-  userAgent: string;
-  userArn?: string;
-  clientCert?: ClientCert;
-}
-interface ApiGatewayRequestContext {
-  accountId: string;
-  apiId: string;
-  authorizer: {
-    claims?: unknown;
-    scopes?: unknown;
-  };
-  domainName: string;
-  domainPrefix: string;
-  extendedRequestId: string;
-  httpMethod: string;
-  identity: Identity;
-  path: string;
-  protocol: string;
-  requestId: string;
-  requestTime: string;
-  requestTimeEpoch: number;
-  resourceId?: string;
-  resourcePath: string;
-  stage: string;
-}
-interface Authorizer {
-  iam?: {
-    accessKey: string;
-    accountId: string;
-    callerId: string;
-    cognitoIdentity: null;
-    principalOrgId: null;
-    userArn: string;
-    userId: string;
-  };
-  jwt?: {
-    claims: Record<string, string | number | boolean | string[]>;
-    scopes: string[] | null;
-  };
-  /**
-   * The `context` object returned by a Lambda (REQUEST) authorizer.
-   * It is `null` when the authorizer returns no context.
-   */
-  lambda?: Record<string, unknown> | null;
-}
-interface ApiGatewayRequestContextV2 {
-  accountId: string;
-  apiId: string;
-  authentication: null;
-  authorizer: Authorizer;
-  domainName: string;
-  domainPrefix: string;
-  http: {
-    method: string;
-    path: string;
-    protocol: string;
-    sourceIp: string;
-    userAgent: string;
-  };
-  requestId: string;
-  routeKey: string;
-  stage: string;
-  time: string;
-  timeEpoch: number;
-}
-interface ALBRequestContext {
-  elb: {
-    targetGroupArn: string;
-  };
-}
-interface LatticeRequestContextV2 {
-  serviceNetworkArn: string;
-  serviceArn: string;
-  targetGroupArn: string;
-  region: string;
-  timeEpoch: string;
-  identity: {
-    sourceVpcArn?: string;
-    type?: string;
-    principal?: string;
-    principalOrgID?: string;
-    sessionName?: string;
-    x509IssuerOu?: string;
-    x509SanDns?: string;
-    x509SanNameCn?: string;
-    x509SanUri?: string;
-    x509SubjectCn?: string;
-  };
-}
-//#endregion
-//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/handler.d.ts
-type LambdaEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2 | ALBProxyEvent | LatticeProxyEventV2;
-interface LatticeProxyEventV2 {
-  version: string;
-  path: string;
-  method: string;
-  headers: Record<string, string[] | undefined>;
-  queryStringParameters: Record<string, string[] | undefined>;
-  body: string | null;
-  isBase64Encoded: boolean;
-  requestContext: LatticeRequestContextV2;
-}
-interface APIGatewayProxyEventV2 {
-  version: string;
-  routeKey: string;
-  headers: Record<string, string | undefined>;
-  multiValueHeaders?: undefined;
-  cookies?: string[];
-  rawPath: string;
-  rawQueryString: string;
-  body: string | null;
-  isBase64Encoded: boolean;
-  requestContext: ApiGatewayRequestContextV2;
-  queryStringParameters?: {
-    [name: string]: string | undefined;
-  };
-  pathParameters?: {
-    [name: string]: string | undefined;
-  };
-  stageVariables?: {
-    [name: string]: string | undefined;
-  };
-}
-interface APIGatewayProxyEvent {
-  version: string;
-  httpMethod: string;
-  headers: Record<string, string | undefined>;
-  multiValueHeaders?: {
-    [headerKey: string]: string[];
-  };
-  path: string;
-  body: string | null;
-  isBase64Encoded: boolean;
-  queryStringParameters?: Record<string, string | undefined>;
-  requestContext: ApiGatewayRequestContext;
-  resource: string;
-  multiValueQueryStringParameters?: {
-    [parameterKey: string]: string[];
-  };
-  pathParameters?: Record<string, string>;
-  stageVariables?: Record<string, string>;
-}
-interface ALBProxyEvent {
-  httpMethod: string;
-  headers?: Record<string, string | undefined>;
-  multiValueHeaders?: Record<string, string[] | undefined>;
-  path: string;
-  body: string | null;
-  isBase64Encoded: boolean;
-  queryStringParameters?: Record<string, string | undefined>;
-  multiValueQueryStringParameters?: {
-    [parameterKey: string]: string[];
-  };
-  requestContext: ALBRequestContext;
-}
-type WithHeaders = {
-  headers: Record<string, string | string[]>;
-  multiValueHeaders?: undefined;
-};
-type WithMultiValueHeaders = {
-  headers?: undefined;
-  multiValueHeaders: Record<string, string[]>;
-};
-type APIGatewayProxyResult = {
-  statusCode: number;
-  statusDescription?: string;
-  body: string;
-  cookies?: string[];
-  isBase64Encoded: boolean;
-} & (WithHeaders | WithMultiValueHeaders);
-declare const streamHandle: <E extends Env = Env, S extends Schema = {}, BasePath extends string = "/">(app: Acryl<E, S, BasePath>) => Handler;
-type HandleOptions = {
-  isContentTypeBinary: ((contentType: string) => boolean) | undefined;
-};
-/**
- * Converts a Acryl application to an AWS Lambda handler.
- *
- * Accepts events from API Gateway (v1 and v2), Application Load Balancer (ALB),
- * and Lambda Function URLs.
- *
- * @param app - The Acryl application instance
- * @param options - Optional configuration
- * @param options.isContentTypeBinary - A function to determine if the content type is binary.
- *                                      If not provided, the default function will be used.
- * @returns Lambda handler function
- *
- * @example
- * ```js
- * import { Acryl } from 'acrylblends'
- * import { handle } from 'acrylblends/aws-lambda'
- *
- * const app = new Acryl()
- *
- * app.get('/', (c) => c.text('Hello from Lambda'))
- * app.get('/json', (c) => c.json({ message: 'Hello JSON' }))
- *
- * export const handler = handle(app)
- * ```
- *
- * @example
- * ```js
- * // With custom binary content type detection
- * import { handle, defaultIsContentTypeBinary } from 'acrylblends/aws-lambda'
- * export const handler = handle(app, {
- *   isContentTypeBinary: (contentType) => {
- *     if (defaultIsContentTypeBinary(contentType)) {
- *       // default logic same as prior to v4.8.4
- *       return true
- *     }
- *     return contentType.startsWith('image/') || contentType === 'application/pdf'
- *   }
- * })
- * ```
- */
-declare const handle: <E extends Env = Env, S extends Schema = {}, BasePath extends string = "/">(app: Acryl<E, S, BasePath>, {
-  isContentTypeBinary
-}?: HandleOptions) => (<L extends LambdaEvent>(event: L, lambdaContext?: LambdaContext) => Promise<APIGatewayProxyResult & (L extends {
-  multiValueHeaders: Record<string, string[]>;
-} ? WithMultiValueHeaders : WithHeaders)>);
-/**
- * Check if the given content type is binary.
- * This is a default function and may be overwritten by the user via `isContentTypeBinary` option in handler().
- * @param contentType The content type to check.
- * @returns True if the content type is binary, false otherwise.
- */
-declare const defaultIsContentTypeBinary: (contentType: string) => boolean;
-//#endregion
-//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/conninfo.d.ts
-/**
- * Get connection information from AWS Lambda
- *
- * Extracts client IP from various Lambda event sources:
- * - API Gateway v1 (REST API): requestContext.identity.sourceIp
- * - API Gateway v2 (HTTP API/Function URLs): requestContext.http.sourceIp
- * - ALB: Falls back to x-forwarded-for header
- *
- * @param c - Context
- * @returns Connection information including remote address
- * @example
- * ```ts
- * import { Acryl } from 'acrylblends'
- * import { handle, getConnInfo } from 'acrylblends/aws-lambda'
- *
- * const app = new Acryl()
- *
- * app.get('/', (c) => {
- *   const info = getConnInfo(c)
- *   return c.text(`Your IP: ${info.remote.address}`)
- * })
- *
- * export const handler = handle(app)
- * ```
- */
-declare const getConnInfo: GetConnInfo;
-//#endregion
-export { type ALBRequestContext, type APIGatewayProxyResult, type ApiGatewayRequestContext, type ApiGatewayRequestContextV2, type LambdaContext, type LambdaEvent, defaultIsContentTypeBinary, getConnInfo, handle, streamHandle };