loopback-next (Agent Skills)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.

## Project Overview

LoopBack 4 is a highly extensible Node.js and TypeScript framework for building
APIs and microservices. This is the monorepo (`loopback-next`) containing all
core packages, extensions, and examples.

## Monorepo Structure

- **packages/** — Core framework packages (~29 packages)
- **extensions/** — Optional extensions (authentication-jwt, graphql, cron,
  metrics, logging, etc.)
- **examples/** — Sample applications demonstrating features
- **acceptance/** — Database connector acceptance tests
- **fixtures/** — Test fixtures and mock services
- **bodyparsers/** — Body parser extensions
- **sandbox/** — For testing monorepo packages as local dependencies
- **benchmark/** — Performance benchmarks
- **docs/** — Jekyll-based documentation site

Managed with **Lerna** (independent versioning) and **npm workspaces**.

## Build & Development Commands

```bash
# Install dependencies (also auto-updates TypeScript project references)
npm ci

# Build all packages (incremental TypeScript compilation)
npm run build

# Full clean rebuild
npm run clean && npm run build

# Build a single package
cd packages/<name> && npm run build
```

## Testing

```bash
# Full test suite (clean + build + mocha + nyc + lint)
npm test

# Run mocha tests only (skips build/lint — useful for fast iteration)
npm run mocha

# Test a single package (builds & tests it)
cd packages/<name> && npm test

# Disable parallel test execution
npm run mocha -- -j 1

# Run CI-only heavy tests locally
CI=1 npm test
```

Test framework: **Mocha** (parallel, 10s timeout) with **NYC** coverage. Tests
run against compiled JS in `dist/__tests__/`. The `pretest` script auto-builds,
so `npm test` in a package compiles then runs tests.

Test files follow the convention `{name}.{test-type}.ts` where test-type is
`unit`, `integration`, or `acceptance`, placed under
`src/__tests__/{unit,integration,acceptance}/`.

Build wrappers from `@loopback/build`: `lb-tsc`, `lb-mocha`, `lb-eslint`,
`lb-prettier`, `lb-nyc`, `lb-clean`.

## Linting & Formatting

```bash
# Run ESLint + Prettier checks
npm run lint

# Auto-fix lint and formatting issues
npm run lint:fix
```

**Prettier** config:
`{bracketSpacing: false, singleQuote: true, printWidth: 80, trailingComma: "all", arrowParens: "avoid"}`.

Pre-commit hook (Husky + lint-staged) auto-formats staged files. Bypass with
`LINT_STAGED=0`.

## Commit Message Convention

Uses **Conventional Commits** enforced by commitlint:

```
<type>(<scope>): <subject>
```

- **type**: feat, fix, docs, style, refactor, perf, test, build, ci, chore,
  revert
- **scope**: package directory name (e.g., `core`, `rest`, `context`,
  `repository`)
- **subject**: imperative, lowercase, no trailing dot

Use `git cz` (commitizen) for interactive commit message generation.

## Key Architectural Concepts

### Dependency Injection & Context

The IoC container (`@loopback/context`) is the foundation. `@loopback/core`
re-exports all of `@loopback/context`'s public API — application code should
import from `@loopback/core`, not `@loopback/context` directly.

**Core dependency chain**: `@loopback/metadata` → `@loopback/context` →
`@loopback/core` → `@loopback/boot`, `@loopback/rest`, etc.

### Foundation vs Framework Packages

- **Foundation-level** (internal building blocks, not directly consumed by
  apps): `context`, `metadata`, `express`, `http-server`, `openapi-v3`,
  `repository-json-schema`
- **Framework-level** (everything else — used directly by applications)

In documentation and examples, always reference framework-level packages.

### TypeScript Configuration

Two sets of tsconfig files serve different purposes:

- **Root `tsconfig.json`** — Used by VS Code for cross-package navigation
  (enables "go to definition" jumping to `.ts` source, cross-package rename
  refactoring)
- **Root `tsconfig.build.json`** — Used by ESLint
- **Per-package `tsconfig.json`** — Used by `npm run build` to compile each
  package to its `dist/` directory

All extend `@loopback/build/config/tsconfig.common.json`. TypeScript project
references are auto-updated via `bin/update-ts-project-refs.js` (runs on
`postinstall`).

Key compiler options: `strict: true`, `target: es2018`, `module: commonjs`,
`experimentalDecorators: true`, `emitDecoratorMetadata: true`.

## File Naming Convention

Follows Angular-style dotted naming: `{name}.{artifact-type}.ts`

Examples: `authenticate.decorator.ts`, `boot.component.ts`,
`user.controller.ts`, `todo.repository.ts`, `application.acceptance.ts`

## Code Style Rules (ESLint)

- `@typescript-eslint/no-explicit-any`: **error** — avoid `any` types
- `@typescript-eslint/no-floating-promises`: **error** — all promises must be
  awaited or handled
- `@typescript-eslint/await-thenable`: **error**
- `@typescript-eslint/no-misused-promises`: **error**
- `@typescript-eslint/return-await`: **error**
- `@typescript-eslint/no-shadow`: **error**
- `mocha/no-exclusive-tests`: **error** — no `.only()` in committed tests
- Naming: camelCase default, PascalCase for types, UPPER_CASE for constants,
  leading underscore for private/protected members, PascalCase for mixin
  functions ending in `Mixin`

## Copyright Headers

All source files must include the copyright header:

```ts
// Copyright IBM Corp. and LoopBack contributors <year>. All Rights Reserved.
// Node module: <package-name>
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT
```

Run `lb4 copyright` to update headers automatically.

## Adding a New Package

Use the helper script: `node bin/create-package.js <package-name>`. It
scaffolds, fixes up package.json, updates copyright, bootstraps dependencies,
and updates TypeScript project references.

After creation, update `CODEOWNERS` and `docs/site/MONOREPO.md`.

## Connector Limitation in Monorepo

When using datasource connectors inside the monorepo (e.g., in examples),
require the connector module directly in the config instead of using a string
name:

```ts
connector: require('loopback-connector-mongodb'); // not connector: 'mongodb'
```

This is due to how Lerna symlinks resolve module paths.

## Node.js Support

Engines: Node.js 18, 20, or 22. npm >= 7.

# Advanced Recipes

## Table of Contents

- [TypeScript Decorator Configuration](#typescript-decorator-configuration)
- [Custom Decorators](#custom-decorators)
- [Custom Injectors](#custom-injectors)
- [Parameterized Class Factories](#parameterized-class-factories)
- [Explicit Context DI in Interceptors](#explicit-context-di-in-interceptors)
- [Sync vs Async Resolution](#sync-vs-async-resolution)
- [Application Scaffolding Pattern](#application-scaffolding-pattern)

## TypeScript Decorator Configuration

LoopBack 4 decorators (`@inject`, `@injectable`, `@lifeCycleObserver`, etc.)
require these tsconfig settings:

```jsonc
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
  },
}
```

- **`experimentalDecorators`** — enables `@decorator` syntax (required for all
  LoopBack DI)
- **`emitDecoratorMetadata`** — emits type metadata at runtime so LoopBack can
  resolve injection targets by type

Without these, decorators either cause compile errors or silently fail at
runtime.

## Custom Decorators

Create a sugar decorator wrapping `@inject`:

```ts
import {BindingKey, inject} from '@loopback/core';

const CURRENT_USER = BindingKey.create<string>('currentUser');

function whoAmI() {
  return inject(CURRENT_USER);
}

class Greeter {
  constructor(@whoAmI() private userName: string) {}
  hello() {
    return `Hello, ${this.userName}`;
  }
}
```

Create a decorator using `DecoratorFactory`:

See `@loopback/example-context/src/custom-inject-decorator.ts`.

## Custom Injectors

Inject with custom resolve logic:

```ts
export function env(name: string) {
  return inject('', {resolve: () => process.env[name]});
}

class MyService {
  constructor(@env('DATABASE_URL') private dbUrl: string) {}
}
```

## Parameterized Class Factories

When top-level decorators can't reference variables, use a class factory:

```ts
import {
  BindingAddress,
  BindingTag,
  Constructor,
  Context,
  createBindingFromClass,
  inject,
  injectable,
} from '@loopback/core';

interface Greeter {
  hello(): string;
}

function createClassWithDecoration(
  bindingKeyForName: BindingAddress<string>,
  ...tags: BindingTag[]
): Constructor<Greeter> {
  @injectable({tags})
  class GreeterTemplate implements Greeter {
    constructor(@inject(bindingKeyForName) private userName: string) {}
    hello() {
      return `Hello, ${this.userName}`;
    }
  }
  return GreeterTemplate;
}

// Usage:
const ctx = new Context();
ctx.bind('name1').to('John');
const MyGreeter = createClassWithDecoration('name1', {tags: {prefix: '1'}});
ctx.add(createBindingFromClass(MyGreeter, {key: 'greeter1'}));
const greeter = await ctx.get<Greeter>('greeter1');
```

## Explicit Context DI in Interceptors

Use `instantiateClass` to trigger DI within interceptors or any context where
you need to create a class instance with injection:

```ts
import {inject, instantiateClass} from '@loopback/core';

class InjectionHelper {
  constructor(@inject('services.Logger') public readonly logger: Logger) {}
}

const interceptor: Interceptor = async (invocationCtx, next) => {
  const helper = await instantiateClass(InjectionHelper, invocationCtx);
  helper.logger.info('intercepting...');
  return next();
};
```

## Sync vs Async Resolution

- `Context.getSync()` — resolves synchronously (throws if any dependency is
  async)
- `Context.get()` — resolves asynchronously (returns Promise)

When `ValueOrPromise` is used, the framework auto-detects: returns a plain value
if all deps are sync, otherwise returns a `Promise`.

## Application Scaffolding Pattern

Standalone application with shutdown handling:

```ts
import {Application, ApplicationConfig} from '@loopback/core';

export class MyApplication extends Application {
  constructor(config?: ApplicationConfig) {
    super({shutdown: {signals: ['SIGINT']}, ...config});
    this.component(CoreComponent);
  }

  async main() {
    await this.start();
    const service = await this.get(GREETING_SERVICE);
    console.log(await service.greet('en', 'World'));
  }
}
```

Layered application with conditional components:

```ts
export class BaseApplication extends Application {
  constructor(config?: ApplicationConfig) {
    super({shutdown: {signals: ['SIGINT']}, ...config});
    this.component(BaseComponent);
  }
}

export class MessagingApplication extends BaseApplication {
  constructor() {
    super();
    this.component(MessagingComponent);
  }
}

// Entry point
export async function main() {
  const app = new MessagingApplication();
  app.component(PluginComponent); // add dynamically
  app.configure(MY_SERVICE_KEY).to({port: 3000}); // configure before start
  await app.start();
  return app;
}
```

# Interceptors and Life Cycle Observers

## Table of Contents

- [Interceptors Overview](#interceptors-overview)
- [Global Interceptors](#global-interceptors)
- [Interceptor Proxy](#interceptor-proxy)
- [Life Cycle Observers](#life-cycle-observers)
- [Dynamic Configuration via ContextView](#dynamic-configuration-via-contextview)

## Interceptors Overview

Interceptors provide aspect-oriented logic around method invocations. They
follow a chain-of-responsibility pattern with pre- and post-invocation hooks.

## Global Interceptors

Register an interceptor that applies to all invocations:

```ts
import {
  asGlobalInterceptor,
  inject,
  injectable,
  Interceptor,
  InvocationContext,
  InvocationResult,
  Provider,
  ValueOrPromise,
} from '@loopback/core';
import {CachingService} from '../caching-service';
import {CACHING_SERVICE} from '../keys';

@injectable(asGlobalInterceptor('caching'))
export class CachingInterceptor implements Provider<Interceptor> {
  constructor(
    @inject(CACHING_SERVICE) private cachingService: CachingService,
  ) {}

  value() {
    return async (
      ctx: InvocationContext,
      next: () => ValueOrPromise<InvocationResult>,
    ) => {
      const targetName = ctx.targetName;
      const cachingKey = `${targetName}:${JSON.stringify(ctx.args)}`;
      const cachedResult = await this.cachingService.get(cachingKey);
      if (cachedResult) return cachedResult;

      const result = await next();
      await this.cachingService.set(cachingKey, result);
      return result;
    };
  }
}

// Register:
app.add(createBindingFromClass(CachingInterceptor));
```

## Interceptor Proxy

Apply interceptors between service dependencies:

```ts
import {AsyncProxy} from '@loopback/core';

class Greeter {
  @inject(CONVERTER, {asProxyWithInterceptors: true})
  private converter: AsyncProxy<Converter>;

  async greet(name: string) {
    const msg = await this.converter.toUpperCase(name);
    return `Hello, ${msg}`;
  }
}

// Or resolve with proxy:
const greeter = await ctx.get(GREETER, {asProxyWithInterceptors: true});
```

## Life Cycle Observers

Participate in application `start`/`stop` events:

```ts
import {inject, lifeCycleObserver, LifeCycleObserver} from '@loopback/core';
import {CachingService} from '../caching-service';
import {CACHING_SERVICE} from '../keys';

@lifeCycleObserver('caching')
export class CacheObserver implements LifeCycleObserver {
  constructor(
    @inject(CACHING_SERVICE) private cachingService: CachingService,
  ) {}

  async start(): Promise<void> {
    await this.cachingService.start();
  }

  async stop(): Promise<void> {
    await this.cachingService.stop();
  }
}
```

### Observer Group Ordering

The group name (first argument to `@lifeCycleObserver`) controls execution
order. Groups are sorted **alphabetically** during `start()` and
reverse-alphabetically during `stop()`. Use numbered prefixes to enforce order:

```ts
@lifeCycleObserver('02-config') // starts first
export class ConfigObserver implements LifeCycleObserver {
  /* ... */
}

@lifeCycleObserver('05-services') // starts second
export class ServiceObserver implements LifeCycleObserver {
  /* ... */
}

@lifeCycleObserver('10-app') // starts last
export class AppObserver implements LifeCycleObserver {
  /* ... */
}
```

### Inline Binding Metadata

Combine `@lifeCycleObserver` with scope and tags in the second argument:

```ts
import {
  BindingScope,
  ContextTags,
  lifeCycleObserver,
  LifeCycleObserver,
} from '@loopback/core';

@lifeCycleObserver('06-mcp', {
  scope: BindingScope.SINGLETON,
  tags: {[ContextTags.KEY]: MCP_HOST_FACTORY_KEY},
})
export class MCPHostFactory implements LifeCycleObserver {
  async start(): Promise<void> {
    /* initialize */
  }
  async stop(): Promise<void> {
    /* cleanup */
  }
}
```

This is equivalent to separately applying
`@injectable({scope: BindingScope.SINGLETON})` and tagging the binding.

## Dynamic Configuration via ContextView

React to configuration changes at runtime:

```ts
import {BindingScope, config, ContextView, injectable} from '@loopback/core';

@injectable({scope: BindingScope.SINGLETON})
export class CachingService {
  private timer: NodeJS.Timer;
  private store: Map<string, Message> = new Map();

  constructor(
    @config.view()
    private optionsView: ContextView<CachingServiceOptions>,
  ) {
    // React to configuration changes
    optionsView.on('refresh', () => {
      this.restart().catch(err => {
        console.error('Cannot restart the caching service.', err);
        process.exit(1);
      });
    });
  }

  async getTTL() {
    const options = await this.optionsView.singleValue();
    return options?.ttl ?? 5000;
  }

  async start(): Promise<void> {
    await this.clear();
    const ttl = await this.getTTL();
    this.timer = setInterval(() => {
      this.sweep().catch(console.warn);
    }, ttl);
  }

  async stop(): Promise<void> {
    if (this.timer) clearInterval(this.timer);
    await this.clear();
  }
}
```

---
name: loopback-core
description:
  Build large-scale, extensible Node.js applications and frameworks using
  LoopBack 4 core patterns. Use when building TypeScript/Node.js projects that
  need IoC containers, dependency injection, extension point/extension patterns,
  interceptors, life cycle observers, or component-based architecture. Triggers
  on tasks involving @loopback/core, @loopback/context, Context, Binding,
  @inject, @injectable, @extensionPoint, @extensions, LifeCycleObserver,
  Interceptor, or Component patterns. Also use when the user asks about
  structuring large-scale Node.js projects for extensibility and composability.
---

# Build Large-Scale Node.js Projects with LoopBack 4 Core

LoopBack 4 core provides an IoC container and DI framework in TypeScript
designed for async-first, large-scale Node.js applications. Import from
`@loopback/core` (not `@loopback/context`). This skill covers only
`@loopback/core` — not REST, repositories, or other LoopBack modules.

## Architecture Decision Tree

1. **Need to manage artifacts and their dependencies?** -> Context & Bindings
   ([context-and-bindings.md](references/context-and-bindings.md))
2. **Need loose coupling between artifact construction and behavior?** ->
   Dependency Injection
   ([dependency-injection.md](references/dependency-injection.md))
3. **Need a pluggable system where others can add capabilities?** -> Extension
   Point/Extension ([extension-points.md](references/extension-points.md))
4. **Need cross-cutting concerns (caching, logging, tracing)?** -> Interceptors
   ([interceptors-and-observers.md](references/interceptors-and-observers.md))
5. **Need to hook into app start/stop?** -> Life Cycle Observers
   ([interceptors-and-observers.md](references/interceptors-and-observers.md))
6. **Need runtime-configurable artifacts?** -> Configuration
   ([configuration.md](references/configuration.md))
7. **Need custom decorators, parameterized classes, or advanced patterns?** ->
   Advanced Recipes ([advanced-recipes.md](references/advanced-recipes.md))

## Quick Start: Minimal Extensible Application

```ts
import {
  Application,
  BindingKey,
  Component,
  Binding,
  createBindingFromClass,
  extensionPoint,
  extensions,
  BindingTemplate,
  extensionFor,
  injectable,
  Getter,
  config,
} from '@loopback/core';

// 1. Define the extension contract
export interface Greeter {
  language: string;
  greet(name: string): string;
}

export const GREETER_EXTENSION_POINT_NAME = 'greeters';

export const asGreeter: BindingTemplate = binding => {
  extensionFor(GREETER_EXTENSION_POINT_NAME)(binding);
  binding.tag({namespace: 'greeters'});
};

// 2. Define the extension point
@extensionPoint(GREETER_EXTENSION_POINT_NAME)
export class GreetingService {
  constructor(
    @extensions() private getGreeters: Getter<Greeter[]>,
    @config() public readonly options?: {color: string},
  ) {}
  async greet(language: string, name: string): Promise<string> {
    const greeters = await this.getGreeters();
    const greeter = greeters.find(g => g.language === language);
    return greeter ? greeter.greet(name) : `Hello, ${name}!`;
  }
}

// 3. Implement extensions
@injectable(asGreeter)
export class EnglishGreeter implements Greeter {
  language = 'en';
  greet(name: string) {
    return `Hello, ${name}!`;
  }
}

@injectable(asGreeter)
export class ChineseGreeter implements Greeter {
  language = 'zh';
  greet(name: string) {
    return `${name}，你好！`;
  }
}

// 4. Bundle into a component
export const GREETING_SERVICE = BindingKey.create<GreetingService>(
  'services.GreetingService',
);

export class GreetingComponent implements Component {
  bindings: Binding[] = [
    createBindingFromClass(GreetingService, {key: GREETING_SERVICE}),
    createBindingFromClass(EnglishGreeter),
    createBindingFromClass(ChineseGreeter),
  ];
}

// 5. Compose components via nesting
export class CoreComponent implements Component {
  // services: auto-registered service/provider classes
  services = [SomeUtilityService];
}

export class AppComponent implements Component {
  // components: nested components (registered recursively)
  components = [CoreComponent, GreetingComponent];
  // services: additional services for this layer
  services = [AppSpecificService];
}

// 6. Wire up the application
export class MyApp extends Application {
  constructor() {
    super({shutdown: {signals: ['SIGINT']}});
    this.component(AppComponent);
  }
  async main() {
    const svc = await this.get(GREETING_SERVICE);
    console.log(await svc.greet('en', 'World'));
  }
}
```

## Core Patterns Summary

| Pattern           | Key APIs                                                                                      | When to Use                                   |
| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Context & Binding | `Context`, `bind()`, `toClass()`, `toDynamicValue()`, `toProvider()`                          | Managing artifacts and their dependencies     |
| DI                | `@inject()`, `@inject.getter()`, `@inject.view()`                                             | Decoupling construction from behavior         |
| Extension Point   | `@extensionPoint()`, `@extensions()`, `@extensions.list()`, `extensionFor()`, `@injectable()` | Pluggable, open-ended feature sets            |
| Interceptor       | `@injectable(asGlobalInterceptor())`, `Provider<Interceptor>`                                 | Cross-cutting concerns                        |
| Observer          | `@lifeCycleObserver('group')`, `LifeCycleObserver`                                            | Startup/shutdown hooks (group controls order) |
| Configuration     | `@config()`, `@config.view()`, `app.configure()`                                              | Runtime-configurable behavior                 |
| Component         | `Component`, `components[]`, `services[]`, `bindings[]`                                       | Composable packaging of artifacts             |

## Key Rules

- Always import from `@loopback/core`, not `@loopback/context`
- Use `BindingKey.create<T>()` for strongly-typed keys
- Extension injection: `@extensions()` returns `Getter<T[]>` (lazy, picks up
  dynamic additions); `@extensions.list()` returns `T[]` (eager, simpler when
  extensions are static at startup)
- Use `@config()` for artifact configuration, `app.configure(key).to(value)` to
  set it
- Use `@injectable(bindingTemplate)` to decorate extension classes — can combine
  scope and extension:
  `@injectable({scope: BindingScope.SINGLETON}, extensionFor(POINT))`
- Use `createBindingFromClass()` to create bindings that respect `@injectable`
  metadata
- Compose components hierarchically: `components[]` for nesting, `services[]`
  for auto-registration, `bindings[]` for custom bindings
- Use `BindingScope.SINGLETON` for shared stateful services
- Use `CoreBindings.APPLICATION_INSTANCE` to inject the Application itself
- Use `ContextTags.KEY` to tag bindings with a stable key:
  `tags: {[ContextTags.KEY]: MY_KEY}`
- Lifecycle observer groups are sorted alphabetically — use numbered prefixes
  (e.g., `'03-setup'`, `'10-app'`) to control startup order

## References

- **Context & Bindings**:
  [references/context-and-bindings.md](references/context-and-bindings.md) —
  creating contexts, binding types, scopes, finding bindings, context hierarchy,
  views, components
- **Dependency Injection**:
  [references/dependency-injection.md](references/dependency-injection.md) —
  constructor/property/method injection, getters, views, custom decorators,
  custom injectors
- **Extension Points**:
  [references/extension-points.md](references/extension-points.md) — defining
  contracts, extension point classes, implementing/registering extensions,
  configuration
- **Interceptors & Observers**:
  [references/interceptors-and-observers.md](references/interceptors-and-observers.md)
  — global interceptors, interceptor proxies, life cycle observers, dynamic
  config via ContextView
- **Configuration**: [references/configuration.md](references/configuration.md)
  — `@config()`, `@config.view()`, dynamic config, custom resolvers, sync vs
  async
- **Advanced Recipes**:
  [references/advanced-recipes.md](references/advanced-recipes.md) — custom
  decorators, custom injectors, parameterized class factories, application
  scaffolding