@go-go-scope/adapter-koa 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thelinuxlich (Alisson Cavalcante Agiani)
+
+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,114 @@
+# @go-go-scope/adapter-koa
+
+Koa adapter for go-go-scope - request-scoped structured concurrency with automatic cleanup.
+
+## Installation
+
+```bash
+npm install @go-go-scope/adapter-koa koa
+```
+
+## Usage
+
+### Basic
+
+```typescript
+import Koa from 'koa'
+import Router from '@koa/router'
+import { koaGoGoScope, getScope, getRootScope } from '@go-go-scope/adapter-koa'
+
+const app = new Koa()
+const router = new Router()
+
+// Apply middleware
+app.use(koaGoGoScope({ name: 'my-api', metrics: true }))
+
+// Use scope in routes
+router.get('/users/:id', async (ctx) => {
+  const scope = getScope(ctx)
+  
+  const [err, user] = await scope.task(
+    () => fetchUser(ctx.params.id),
+    { retry: 'exponential', timeout: 5000 }
+  )
+  
+  if (err) {
+    ctx.status = 500
+    ctx.body = { error: err.message }
+    return
+  }
+  
+  ctx.body = user
+})
+
+app.use(router.routes())
+app.listen(3000)
+```
+
+### Options
+
+```typescript
+app.use(koaGoGoScope({
+  name: 'my-api',        // Root scope name
+  metrics: true,          // Enable metrics collection
+  timeout: 30000,        // Default request timeout
+  onError: (err, ctx) => {  // Optional error handler
+    console.error('Scope error:', err)
+  }
+}))
+```
+
+### Accessing Root Scope
+
+```typescript
+// Access root scope from any context
+app.use(async (ctx, next) => {
+  const rootScope = getRootScope(ctx)
+  const metrics = rootScope.metrics()
+  console.log('App metrics:', metrics)
+  await next()
+})
+```
+
+### Graceful Shutdown
+
+```typescript
+import { closeKoaScope } from '@go-go-scope/adapter-koa'
+
+const server = app.listen(3000)
+
+process.on('SIGTERM', async () => {
+  await closeKoaScope()
+  server.close(() => {
+    process.exit(0)
+  })
+})
+```
+
+## API
+
+### `koaGoGoScope(options?)`
+
+Creates Koa middleware that provides request-scoped structured concurrency.
+
+**Options:**
+- `name`: Root scope name (default: 'koa-app')
+- `metrics`: Enable metrics collection (default: false)
+- `timeout`: Default request timeout in ms
+- `onError`: Error handler callback
+
+### `getScope(ctx)`
+
+Get the request-scoped scope from Koa context.
+
+### `getRootScope(ctx)`
+
+Get the root application scope from Koa context.
+
+### `closeKoaScope()`
+
+Gracefully shutdown the root scope (for use in SIGTERM handlers).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { Scope } from 'go-go-scope';
+import { Context, Middleware } from 'koa';
+
+/**
+ * Koa adapter for go-go-scope
+ * Provides request-scoped structured concurrency for Koa applications
+ */
+
+declare module "koa" {
+    interface DefaultState {
+        scope: Scope<Record<string, unknown>>;
+        rootScope: Scope<Record<string, unknown>>;
+    }
+}
+interface KoaGoGoScopeOptions {
+    /** Root scope name */
+    name?: string;
+    /** Enable metrics collection */
+    metrics?: boolean;
+    /** Default timeout for all requests */
+    timeout?: number;
+    /** Optional error handler */
+    onError?: (error: Error, ctx: Context) => void;
+}
+/**
+ * Koa middleware for go-go-scope integration
+ *
+ * @example
+ * ```typescript
+ * import Koa from 'koa'
+ * import { koaGoGoScope } from '@go-go-scope/adapter-koa'
+ *
+ * const app = new Koa()
+ * app.use(koaGoGoScope({ name: 'my-api', metrics: true }))
+ *
+ * app.use(async (ctx) => {
+ *   const scope = ctx.state.scope
+ *   const [err, user] = await scope.task(
+ *     () => fetchUser(ctx.params.id),
+ *     { retry: 'exponential' }
+ *   )
+ *
+ *   if (err) {
+ *     ctx.status = 500
+ *     ctx.body = { error: err.message }
+ *     return
+ *   }
+ *   ctx.body = user
+ * })
+ * ```
+ */
+declare function koaGoGoScope(options?: KoaGoGoScopeOptions): Middleware;
+/**
+ * Get the request-scoped scope from Koa context
+ */
+declare function getScope(ctx: Context): Scope<Record<string, unknown>>;
+/**
+ * Get the root application scope from Koa context
+ */
+declare function getRootScope(ctx: Context): Scope<Record<string, unknown>>;
+/**
+ * Graceful shutdown helper for Koa applications
+ * Disposes the root scope when the server is closing
+ *
+ * @example
+ * ```typescript
+ * process.on('SIGTERM', async () => {
+ *   await closeKoaScope()
+ *   server.close()
+ * })
+ * ```
+ */
+declare function closeKoaScope(): Promise<void>;
+
+export { closeKoaScope, getRootScope, getScope, koaGoGoScope };
+export type { KoaGoGoScopeOptions };

package/dist/index.mjs

@@ -0,0 +1,51 @@
+import { scope } from 'go-go-scope';
+
+let rootScope = null;
+function koaGoGoScope(options = {}) {
+  const { name = "koa-app", metrics = false, timeout, onError } = options;
+  if (!rootScope) {
+    rootScope = scope({ name, metrics });
+  }
+  return async (ctx, next) => {
+    if (!rootScope) {
+      throw new Error("Root scope not initialized");
+    }
+    const scopeOptions = {
+      parent: rootScope,
+      name: `request-${ctx.request.url}`
+    };
+    if (timeout) scopeOptions.timeout = timeout;
+    const requestScope = scope(scopeOptions);
+    ctx.state.scope = requestScope;
+    ctx.state.rootScope = rootScope;
+    try {
+      await next();
+    } catch (error) {
+      if (onError) {
+        onError(error, ctx);
+      }
+      throw error;
+    } finally {
+      await requestScope[Symbol.asyncDispose]().catch((err) => {
+        if (onError) {
+          onError(err, ctx);
+        }
+      });
+    }
+  };
+}
+function getScope(ctx) {
+  return ctx.state.scope;
+}
+function getRootScope(ctx) {
+  return ctx.state.rootScope;
+}
+async function closeKoaScope() {
+  if (rootScope) {
+    await rootScope[Symbol.asyncDispose]().catch(() => {
+    });
+    rootScope = null;
+  }
+}
+
+export { closeKoaScope, getRootScope, getScope, koaGoGoScope };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@go-go-scope/adapter-koa",
+  "version": "2.2.0",
+  "description": "Koa adapter for go-go-scope - request-scoped structured concurrency",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "keywords": [
+    "koa",
+    "adapter",
+    "go-go-scope",
+    "structured-concurrency",
+    "middleware"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "author": "thelinuxlich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thelinuxlich/go-go-scope.git",
+    "directory": "packages/adapter-koa"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "go-go-scope": "2.2.0"
+  },
+  "peerDependencies": {
+    "koa": "^3.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/koa": "^2.15.0",
+    "@types/node": "^24",
+    "koa": "^3.1.0",
+    "pkgroll": "^2.26.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "lint": "biome check --write src/",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}