fix(workers): keep the type of an annotated ctx in withEvlog and defineWorkerFetch

.changeset/workers-ctx-type.md

@@ -0,0 +1,5 @@
+---
+"evlog": patch
+---
+
+`withEvlog` and `defineWorkerFetch` (`evlog/workers`) keep the type of an annotated `ctx`, so a handler typed with Cloudflare's `ExecutionContext` reaches `ctx.exports`, `ctx.props` and `ctx.passThroughOnException()` without a cast. An unannotated `ctx` is still `WorkerExecutionContext`.

packages/evlog/src/workers/index.ts

@@ -93,16 +93,20 @@ export function initWorkersLogger(options: LoggerConfig = {}): void {
  *   return new Response('ok')
  * })
  * ```
+ *
+ * @typeParam TCtx - The handler's `ctx`. Unannotated, it is {@link WorkerExecutionContext}; annotate `ctx` (for
+ *   example as `ExecutionContext` from `@cloudflare/workers-types`) or pass the type argument to reach the rest of
+ *   Cloudflare's context, such as `ctx.exports` or `ctx.props`.
  */
-export function defineWorkerFetch<TEnv = unknown>(
+export function defineWorkerFetch<TEnv = unknown, TCtx extends WorkerExecutionContext = WorkerExecutionContext>(
   handler: (
     request: Request,
     env: TEnv,
-    ctx: WorkerExecutionContext,
+    ctx: TCtx,
     log: AuditableLogger,
   ) => Response | Promise<Response>,
 ): {
-  fetch: (request: Request, env: TEnv, ctx: WorkerExecutionContext) => Promise<Response>
+  fetch: (request: Request, env: TEnv, ctx: TCtx) => Promise<Response>
 } {
   return {
     fetch(request, env, ctx) {
@@ -194,17 +198,21 @@ const integration = defineFrameworkIntegration<WorkersRequestContext>({
  *   },
  * )
  * ```
+ *
+ * @typeParam TCtx - The handler's `ctx`. Unannotated, it is {@link WorkerExecutionContext}; annotate `ctx` (for
+ *   example as `ExecutionContext` from `@cloudflare/workers-types`) or pass the type argument to reach the rest of
+ *   Cloudflare's context, such as `ctx.exports` or `ctx.props`.
  */
-export function withEvlog<TEnv = unknown>(
+export function withEvlog<TEnv = unknown, TCtx extends WorkerExecutionContext = WorkerExecutionContext>(
   handler: (
     request: Request,
     env: TEnv,
-    ctx: WorkerExecutionContext,
+    ctx: TCtx,
     log: AuditableLogger,
   ) => Response | Promise<Response>,
   options: EvlogWorkersOptions = {},
 ): {
-  fetch: (request: Request, env: TEnv, ctx: WorkerExecutionContext) => Promise<Response>
+  fetch: (request: Request, env: TEnv, ctx: TCtx) => Promise<Response>
 } {
   return {
     async fetch(request, env, ctx) {

packages/evlog/test/workers/ctx-typing.test.ts

@@ -0,0 +1,31 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type { WorkerExecutionContext } from '../../src/workers'
+import { defineWorkerFetch, withEvlog } from '../../src/workers'
+
+// Cloudflare's ExecutionContext beyond waitUntil, without depending on @cloudflare/workers-types
+interface ExecutionContext extends WorkerExecutionContext {
+  passThroughOnException(): void
+  props: unknown
+  exports: Record<string, unknown>
+}
+
+describe('evlog/workers ctx typing', () => {
+  it('keeps the type of an annotated ctx', () => {
+    const worker = withEvlog((_request, _env: unknown, ctx: ExecutionContext) => {
+      ctx.passThroughOnException()
+      return new Response(Object.keys(ctx.exports).join(','))
+    })
+    expectTypeOf(worker.fetch).parameter(2).toEqualTypeOf<ExecutionContext>()
+
+    const handler = defineWorkerFetch((_request, _env: unknown, ctx: ExecutionContext) => new Response(String(ctx.props)))
+    expectTypeOf(handler.fetch).parameter(2).toEqualTypeOf<ExecutionContext>()
+  })
+
+  it('types an unannotated ctx as WorkerExecutionContext', () => {
+    const worker = withEvlog((_request, _env, ctx) => {
+      expectTypeOf(ctx).toEqualTypeOf<WorkerExecutionContext>()
+      return new Response('ok')
+    })
+    expectTypeOf(worker.fetch).parameter(2).toEqualTypeOf<WorkerExecutionContext>()
+  })
+})