@fastly/hono-fastly-compute 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [unreleased]
+
+## [0.2.0] - 2025-10-06
+
+### Changed
+
+- BREAKING: Updated to new identifiers from `@fastly/compute-js-context`
+
+## [0.1.0] - 2025-10-03
+
+### Added
+
+- Initial public release
+
+[unreleased]: https://github.com/fastly/hono-fastly-compute/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/fastly/hono-fastly-compute/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/fastly/hono-fastly-compute/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Hono Adapter for Fastly Compute
+
+This library provides an adapter for using the [Hono](https://hono.dev/) web framework with [Fastly Compute](https://www.fastly.com/products/edge-compute). It simplifies the process of creating Hono applications that run on Fastly's edge platform.
+
+## Features
+
+- **Seamless Integration**: Easily adapt your Hono application to Fastly Compute's event-driven architecture.
+- **Type-Safe Bindings**: Automatically infer types for your Fastly resources (like KV Stores and Config Stores) using the `buildFire` function.
+- **Simplified Setup**: The `buildFire` utility streamlines the process of setting up your application and its environment bindings.
+- **Middleware Utility**: Includes a `logFastlyServiceVersion` middleware for easy debugging and version tracking.
+
+## Installation
+
+```bash
+npm install @fastly/hono-fastly-compute
+```
+
+## Usage
+
+Here's a basic example of how to create a Hono application and run it on Fastly Compute.
+
+### Basic Example
+
+```typescript
+import { Hono } from 'hono';
+import { buildFire } from '@fastly/hono-fastly-compute';
+
+// buildFire creates a `fire` function bound to your environment bindings.
+// If you have no bindings, pass an empty object.
+const fire = buildFire({
+  assets: 'KVStore',
+  config: 'ConfigStore:my-config',
+});
+
+// Use the inferred Bindings type in your Hono environment
+type Env = {
+  Bindings: typeof fire.Bindings;
+};
+
+const app = new Hono<Env>();
+
+app.get('/', async (c) => {
+  // Access your bindings from the context
+  const value = await c.env.assets.get('some-key');
+  const setting = c.env.config.get('some-setting');
+  return c.json({ value, setting });
+});
+
+fire(app);
+```
+
+### Using the `logFastlyServiceVersion` Middleware
+
+This package includes a simple middleware to log the `FASTLY_SERVICE_VERSION` for debugging purposes.
+
+```typescript
+import { Hono } from 'hono';
+import { buildFire, logFastlyServiceVersion } from '@fastly/hono-fastly-compute';
+
+const fire = buildFire({});
+const app = new Hono();
+
+// Use the middleware
+app.use('*', logFastlyServiceVersion());
+
+app.get('/', (c) => c.text('Hello!'));
+
+fire(app);
+```
+
+## API
+
+### `buildFire(bindingsDefs)`
+
+Creates a `fire` function that is bound to a specific set of environment bindings.
+
+- **`bindingsDefs`**: An object mapping binding names to their resource types
+   - Keys: The property name used to access the resource
+   - Values: A string in the format 'ResourceType'
+      - If the actual name of the object differs from the Key, or if its name
+         is not a valid JavaScript identifier, use 'ResourceType:actual-name'
+- **Returns**: A `fire` function
+
+The returned `fire` function has two purposes:
+1. When called with a Hono app instance (`fire(app)`), it registers the app to handle fetch events.
+2. It exposes a `Bindings` type (`typeof fire.Bindings`) that you can use to define your Hono `Env`.
+
+### `handle(app, bindingsDefs, options)`
+
+The core adapter function that connects Hono to the Fastly Compute `FetchEvent`. The `buildFire` function is a higher-level utility that uses `handle` internally.
+
+- **`app`**: The Hono application instance.
+- **`bindingsDefs`**: The environment bindings definition.
+- **`options`**: An optional object with a `fetch` property.
+
+### `logFastlyServiceVersion()`
+
+A middleware for Hono that logs the string `FASTLY_SERVICE_VERSION: <service-version>` environment variable to the console.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/build/bindings.d.ts

@@ -0,0 +1,37 @@
+import { Acl } from 'fastly:acl';
+import { Backend } from 'fastly:backend';
+import { ConfigStore } from 'fastly:config-store';
+import { KVStore } from 'fastly:kv-store';
+import { Logger } from 'fastly:logger';
+import { SecretStore } from 'fastly:secret-store';
+import { Context } from "@h7/fastly-compute-js-context";
+type Def<T extends string> = T | `${T}:${string}`;
+type Defs<T extends string> = T extends string ? Def<T> : never;
+declare const BindingStringToContextKeyMapping: {
+    readonly Acl: "ACLS";
+    readonly Backend: "BACKENDS";
+    readonly ConfigStore: "CONFIG_STORES";
+    readonly env: "ENV";
+    readonly KVStore: "KV_STORES";
+    readonly Logger: "LOGGERS";
+    readonly SecretStore: "SECRET_STORES";
+};
+export type ResourceType = keyof typeof BindingStringToContextKeyMapping;
+export type BindingsString = Defs<ResourceType>;
+export type EnvBindingsDefs = Record<string, BindingsString>;
+type BindingStringToResourceInstanceTypeMapping = {
+    Acl: Acl;
+    Backend: Backend;
+    ConfigStore: ConfigStore;
+    env: string;
+    KVStore: KVStore;
+    Logger: Logger;
+    SecretStore: SecretStore;
+};
+export type ResourceInstance<T> = T extends Def<infer K extends keyof BindingStringToResourceInstanceTypeMapping> ? BindingStringToResourceInstanceTypeMapping[K] : never;
+export type BuildBindings<T extends EnvBindingsDefs> = {
+    [K in keyof T]: ResourceInstance<T[K]>;
+};
+export declare function buildEnvironment<T extends EnvBindingsDefs>(context: Context, envBindingsDefs: T): BuildBindings<T>;
+export {};
+//# sourceMappingURL=bindings.d.ts.map

package/build/bindings.js

@@ -0,0 +1,53 @@
+const BindingStringToContextKeyMapping = {
+    Acl: 'ACLS',
+    Backend: 'BACKENDS',
+    ConfigStore: 'CONFIG_STORES',
+    env: 'ENV',
+    KVStore: 'KV_STORES',
+    Logger: 'LOGGERS',
+    SecretStore: 'SECRET_STORES',
+};
+function isResourceType(resourceType) {
+    return resourceType in BindingStringToContextKeyMapping;
+}
+function getResourceType(typeName) {
+    const [resourceType,] = typeName.split(':');
+    if (isResourceType(resourceType)) {
+        return resourceType;
+    }
+    return undefined;
+}
+function getResourceName(key, typeName) {
+    const [, seg,] = typeName.split(':');
+    return seg ?? key;
+}
+export function buildEnvironment(context, envBindingsDefs) {
+    const target = {};
+    const getEntry = (key) => {
+        if (typeof key !== "string") {
+            return undefined;
+        }
+        console.log('key', key);
+        const typeName = envBindingsDefs[key];
+        const resourceType = getResourceType(typeName);
+        if (resourceType == null) {
+            return undefined;
+        }
+        const resourceName = getResourceName(key, typeName);
+        const contextKey = BindingStringToContextKeyMapping[resourceType];
+        const contextEntry = context[contextKey];
+        if (contextEntry == null) {
+            return undefined;
+        }
+        return contextEntry[resourceName];
+    };
+    const handler = {
+        get(_, key) {
+            return getEntry(key);
+        },
+        has(_, key) {
+            return getEntry(key) !== undefined;
+        },
+    };
+    return new Proxy(target, handler);
+}

package/build/fire.d.ts

@@ -0,0 +1,75 @@
+import type { Schema } from 'hono';
+import type { HonoBase } from 'hono/hono-base';
+import type { ContextProxy, BindingsDefs } from '@fastly/compute-js-context';
+import { type HandleOptions } from './handler.js';
+type FireFn<D extends BindingsDefs> = {
+    /**
+     * Registers a Hono app to handle fetch events in Fastly Compute.
+     *
+     * This sets up `addEventListener('fetch', handle(app, envBindingsDefs, options))`
+     * using the bindings you passed to `buildFire()`.
+     *
+     * @param app - The Hono application instance to serve
+     * @param options - Options for handling requests (fetch defaults to undefined)
+     *
+     * @example
+     * const fire = buildFire({ foo: "KVStore" });
+     *
+     * type Env = {
+     *   Variables: Variables;
+     *   Bindings: typeof fire.Bindings;
+     * };
+     *
+     * const app = new Hono<Env>();
+     * fire(app);
+     */
+    <V extends {
+        Variables?: object;
+    }, S extends Schema, BasePath extends string>(app: HonoBase<(keyof D extends never ? {} : {
+        Bindings: ContextProxy<D>;
+    }) & V, S, BasePath>, options?: HandleOptions): void;
+    /**
+     * The inferred bindings type, derived from the defs passed to `buildFire()`.
+     * Use this in your Env definition: `{ Bindings: typeof fire.Bindings }`.
+     */
+    Bindings: ContextProxy<D>;
+    /** For debugging: the raw defs object you passed to buildFire */
+    defs: D;
+};
+/**
+ * Creates a `fire` function bound to a specific set of environment bindings.
+ *
+ * Call `buildFire()` with the shape of your bindings. The returned `fire` function
+ * registers your Hono app to handle fetch events in Fastly Compute, and also exposes
+ * a `.Bindings` type you can use when defining your `Env`.
+ *
+ * ### Example: With bindings
+ * ```ts
+ * const fire = buildFire({ grip: "ConfigStore", foo: "KVStore" });
+ *
+ * type Env = {
+ *   Variables: Variables;
+ *   Bindings: typeof fire.Bindings; // infer binding types automatically
+ * };
+ *
+ * const app = new Hono<Env>();
+ * fire(app);
+ * ```
+ *
+ * ### Example: No bindings
+ * ```ts
+ * const fire = buildFire({});
+ *
+ * const app = new Hono();
+ * fire(app);
+ * ```
+ *
+ * @param bindingsDefs - A mapping of binding names to binding types
+ *                          (e.g. `{ foo: "KVStore", bar: "ConfigStore" }`).
+ * @returns A `fire` function that:
+ *  - Registers your Hono app to handle fetch events
+ *  - Exposes a `.Bindings` type inferred from the given defs
+ */
+export declare function buildFire<D extends BindingsDefs>(bindingsDefs: D): FireFn<D>;
+export {};
+//# sourceMappingURL=fire.d.ts.map

package/build/fire.js

@@ -0,0 +1,44 @@
+import { handle } from './handler.js';
+/**
+ * Creates a `fire` function bound to a specific set of environment bindings.
+ *
+ * Call `buildFire()` with the shape of your bindings. The returned `fire` function
+ * registers your Hono app to handle fetch events in Fastly Compute, and also exposes
+ * a `.Bindings` type you can use when defining your `Env`.
+ *
+ * ### Example: With bindings
+ * ```ts
+ * const fire = buildFire({ grip: "ConfigStore", foo: "KVStore" });
+ *
+ * type Env = {
+ *   Variables: Variables;
+ *   Bindings: typeof fire.Bindings; // infer binding types automatically
+ * };
+ *
+ * const app = new Hono<Env>();
+ * fire(app);
+ * ```
+ *
+ * ### Example: No bindings
+ * ```ts
+ * const fire = buildFire({});
+ *
+ * const app = new Hono();
+ * fire(app);
+ * ```
+ *
+ * @param bindingsDefs - A mapping of binding names to binding types
+ *                          (e.g. `{ foo: "KVStore", bar: "ConfigStore" }`).
+ * @returns A `fire` function that:
+ *  - Registers your Hono app to handle fetch events
+ *  - Exposes a `.Bindings` type inferred from the given defs
+ */
+export function buildFire(bindingsDefs) {
+    const fireFn = ((app, options = {
+        fetch: undefined,
+    }) => {
+        addEventListener('fetch', handle(app, bindingsDefs, options));
+    });
+    fireFn.defs = bindingsDefs;
+    return fireFn;
+}

package/build/handler.d.ts

@@ -0,0 +1,18 @@
+import type { Schema } from 'hono';
+import type { HonoBase } from 'hono/hono-base';
+import { type BindingsDefs, type ContextProxy } from '@fastly/compute-js-context';
+type Handler = (evt: FetchEvent) => void;
+export type HandleOptions = {
+    fetch?: typeof fetch;
+};
+export type MaybeBindings<D extends BindingsDefs> = keyof D extends never ? {} : {
+    Bindings: ContextProxy<D>;
+};
+/**
+ * Adapter for Fastly Compute
+ */
+export declare const handle: <D extends BindingsDefs, V extends {
+    Variables?: object;
+}, S extends Schema, BasePath extends string>(app: HonoBase<MaybeBindings<D> & V, S, BasePath>, envBindingsDefs: D, opts?: HandleOptions) => Handler;
+export {};
+//# sourceMappingURL=handler.d.ts.map

package/build/handler.js

@@ -0,0 +1,26 @@
+import { createContext, buildContextProxy, } from '@fastly/compute-js-context';
+/**
+ * Adapter for Fastly Compute
+ */
+export const handle = (app, envBindingsDefs, opts = {
+    // To use `fetch` on a Service Worker correctly, bind it to `globalThis`.
+    fetch: globalThis.fetch.bind(globalThis),
+}) => {
+    return (evt) => {
+        evt.respondWith((async () => {
+            const context = createContext();
+            const env = buildContextProxy(context, envBindingsDefs);
+            const res = await app.fetch(evt.request, env, {
+                waitUntil: evt.waitUntil.bind(evt),
+                passThroughOnException() {
+                    throw new Error('Not implemented');
+                },
+                props: undefined,
+            });
+            if (opts.fetch && res.status === 404) {
+                return await opts.fetch(evt.request);
+            }
+            return res;
+        })());
+    };
+};

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export * from './fire.js';
+export * from './handler.js';
+export * from './utils.js';
+export type { ResourceType, Context, ContextProxy, BindingsDefs, } from '@fastly/compute-js-context';
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './fire.js';
+export * from './handler.js';
+export * from './utils.js';

package/build/utils.d.ts

@@ -0,0 +1,2 @@
+export declare const logFastlyServiceVersion: () => import("hono").MiddlewareHandler<any, string, {}>;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.js

@@ -0,0 +1,6 @@
+import { env } from 'fastly:env';
+import { createMiddleware } from 'hono/factory';
+export const logFastlyServiceVersion = () => createMiddleware(async (_, next) => {
+    console.log('FASTLY_SERVICE_VERSION', env('FASTLY_SERVICE_VERSION'));
+    await next();
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fastly/hono-fastly-compute",
+  "version": "0.2.0",
+  "description": "Helper utilities for using Hono with Fastly Compute",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fastly/hono-fastly-compute.git"
+  },
+  "author": {
+    "name": "Katsuyuki Omuro",
+    "email": "komuro@fastly.com"
+  },
+  "type": "module",
+  "main": "./build/index.js",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "types": "./build/index.d.ts",
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf build"
+  },
+  "dependencies": {
+    "@fastly/js-compute": "^3.0.0",
+    "@fastly/compute-js-context": "^0.3.0"
+  },
+  "devDependencies": {
+    "hono": "^4.9.5",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "@fastly/js-compute": "^3.0.0",
+    "hono": "^4.5.0"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.js.map",
+    "build/**/*.d.ts",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "hono",
+    "fastly",
+    "compute"
+  ]
+}