> ## Documentation Index
> Fetch the complete documentation index at: https://brushysuite.gfrancodev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scoped containers

> ScopedContainer, createScope, and manual scope buckets.

Besides automatic request scope, `@brushy/di-core` exposes explicit scope APIs for tests, background jobs, and non-HTTP workflows.

## `createScope(scopeKey?)`

Returns a `ScopedContainer` bound to a scope object:

```typescript theme={null}
const scope = container.createScope();
const svc = scope.resolve(USER_SERVICE);

scope.dispose(); // clears scoped instances for this bucket
```

Pass a custom `scopeKey` to share a bucket across callers:

```typescript theme={null}
const key = { jobId: "batch-42" };
const scopeA = container.createScope(key);
const scopeB = container.createScope(key);
// Both resolve the same scoped instances for tokens registered as scoped
```

## `ScopedContainer` API

```typescript theme={null}
class ScopedContainer {
  resolve<T>(token): T;
  dispose(): void;
}
```

`dispose()` calls `container.clearScopedInstances(scopeKey)`.

## Low-level scope bucket

```typescript theme={null}
const bucket = container.getOrCreateScopeBucket(scopeKey);
container.resolveInScope(USER_SERVICE, scopeKey, bucket);
container.clearScopedInstances(scopeKey);
```

## When to use explicit scopes

| Scenario             | Approach                                        |
| -------------------- | ----------------------------------------------- |
| HTTP requests (Node) | `brushyRequestScope()` middleware: automatic    |
| Unit tests           | `runInRequestScope(() => …)` or `createScope()` |
| WebSocket sessions   | `createScope({ connectionId })` per connection  |
| Batch jobs           | `runInRequestScope({ scope: { jobId } }, fn)`   |

## Cleanup

Request scope middleware and `runInRequestScope` call `container.clearRequestScope()` on exit unless `skipRequestScopeCleanup: true`.

For manual scopes, always call `scope.dispose()` or `clearScopedInstances` when the unit of work ends.