@fluojs/graphql 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+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.ko.md

@@ -0,0 +1,158 @@
+# @fluojs/graphql
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 데코레이터 기반 GraphQL 통합 패키지입니다. **GraphQL Yoga**를 기반으로 설계되었으며, 깊은 DI 통합과 퍼스트 파티 DataLoader 지원을 통해 고성능의 명세 준수 GraphQL 실행 파이프라인을 제공합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [핵심 기능](#핵심-기능)
+- [운영 가드레일](#운영-가드레일)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+pnpm add @fluojs/graphql graphql graphql-yoga
+```
+
+## 사용 시점
+
+- TypeScript 데코레이터를 사용하여 타입 안전한 GraphQL API를 구축할 때 (**Code-first**).
+- 기존 GraphQL 스키마를 fluo 애플리케이션에 통합할 때 (**Schema-first**).
+- GraphQL resolver 내에서 request-scoped provider를 포함한 원활한 의존성 주입이 필요할 때.
+- Request-scoped **DataLoader** 패턴을 사용하여 효율적인 데이터 페칭을 수행할 때.
+
+## 빠른 시작
+
+`GraphqlModule.forRoot(...)`를 등록하고 표준 데코레이터를 사용하여 resolver를 정의합니다. 현재 `@fluojs/graphql`는 동기 모듈 엔트리포인트만 제공하며 `GraphqlModule.forRootAsync(...)` 계약은 없습니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { bootstrapNodeApplication } from '@fluojs/runtime/node';
+import { GraphqlModule, Query, Resolver, Arg } from '@fluojs/graphql';
+
+@Resolver()
+class HelloResolver {
+  @Query()
+  hello(@Arg('name') name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+
+@Module({
+  imports: [
+    GraphqlModule.forRoot({
+      resolvers: [HelloResolver]
+    })
+  ],
+  providers: [HelloResolver]
+})
+class AppModule {}
+
+const app = await bootstrapNodeApplication(AppModule);
+await app.listen(3000);
+// curl -X POST http://localhost:3000/graphql \
+//   -H "Content-Type: application/json" \
+//   -d '{"query": "{ hello(name: \"fluo\") }"}'
+```
+
+## 핵심 기능
+
+### Code-first Resolvers
+fluo는 표준 데코레이터를 사용하여 GraphQL 스키마를 정의합니다. `@Resolver`, `@Query`, `@Mutation`, `@Subscription`을 사용하여 클래스 메서드를 GraphQL 작업에 매핑합니다.
+
+### Request-Scoped DataLoaders
+내장된 DataLoader 통합을 통해 N+1 문제를 효율적으로 해결합니다. Loader는 각 GraphQL 작업마다 자동으로 격리됩니다.
+
+```typescript
+import { createDataLoader, type GraphQLContext } from '@fluojs/graphql';
+
+const userLoader = createDataLoader(async (ids: string[]) => {
+  const users = await userService.findByIds(ids);
+  return ids.map(id => users.find(u => u.id === id));
+});
+
+@Resolver()
+class UserResolver {
+  @Query()
+  async user(@Arg('id') id: string, context: GraphQLContext) {
+    return userLoader(context).load(id);
+  }
+}
+```
+
+### 프로토콜 지원
+- **HTTP**: 표준 GET/POST 쿼리 및 뮤테이션.
+- **SSE**: Server-Sent Events를 통한 구독(기본값).
+- **WebSockets**: 실시간 구독을 위한 선택적 `graphql-ws` 지원.
+
+```typescript
+GraphqlModule.forRoot({
+  subscriptions: {
+    websocket: {
+      enabled: true,
+      limits: {
+        maxConnections: 100,
+        maxPayloadBytes: 64 * 1024,
+        maxOperationsPerConnection: 25,
+      },
+    }
+  }
+})
+```
+
+## 운영 가드레일
+
+- `graphiql`을 명시적으로 켜거나 `introspection: true`를 설정하지 않으면 스키마 introspection은 기본적으로 비활성화됩니다.
+- 문서 depth, field complexity, aggregate query cost에 대한 request validation budget이 기본적으로 보수적인 값으로 활성화됩니다.
+- WebSocket 구독 경로에는 별도의 전송 budget이 기본 적용됩니다: 동시 연결 `100`, 최대 payload 크기 `64 KiB`, 연결당 활성 operation `25`개입니다.
+- 무제한 WebSocket 동작이 정말 필요할 때만 `subscriptions.websocket.limits = false`를 사용하고, 그 경우에도 동일한 수준의 외부 제어 수단을 마련해야 합니다.
+- 무제한 동작이 꼭 필요할 때만 `limits: false`를 사용하고, 그 경우에는 외부 제어 수단을 함께 두어야 합니다.
+
+```typescript
+GraphqlModule.forRoot({
+  graphiql: false,
+  introspection: false,
+  limits: {
+    maxDepth: 8,
+    maxComplexity: 120,
+    maxCost: 240,
+  },
+  subscriptions: {
+    websocket: {
+      enabled: true,
+      limits: {
+        maxConnections: 100,
+        maxPayloadBytes: 64 * 1024,
+        maxOperationsPerConnection: 25,
+      },
+    },
+  },
+  resolvers: [HelloResolver],
+})
+```
+
+## 공개 API
+
+- `GraphqlModule.forRoot(options)`: GraphQL 통합을 위한 메인 엔트리 포인트.
+- `Resolver`, `Query`, `Mutation`, `Subscription`: 작업 데코레이터.
+- `Arg`: 인자 매핑 데코레이터.
+- `createDataLoader`, `createDataLoaderMap`: DataLoader 팩토리 헬퍼.
+- `GraphQLContext`: GraphQL 실행 컨텍스트를 위한 타입 정의.
+
+## 관련 패키지
+
+- `@fluojs/core`: 핵심 DI 및 모듈 시스템.
+- `@fluojs/http`: 기반 HTTP 추상화.
+- `@fluojs/validation`: GraphQL 입력을 위한 통합 DTO 검증.
+
+## 예제 소스
+
+- `packages/graphql/src/module.test.ts`: 통합 테스트 및 사용 예제.
+- `examples/graphql-yoga`: 전체 GraphQL 애플리케이션 예제.

package/README.md

@@ -0,0 +1,158 @@
+# @fluojs/graphql
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Decorator-based GraphQL integration for fluo. Built on **GraphQL Yoga**, it provides a high-performance, specification-compliant GraphQL execution pipeline with deep DI integration and first-party DataLoader support.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Core Capabilities](#core-capabilities)
+- [Operational Guardrails](#operational-guardrails)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+pnpm add @fluojs/graphql graphql graphql-yoga
+```
+
+## When to Use
+
+- When building type-safe GraphQL APIs using TypeScript decorators (**Code-first**).
+- When integrating existing GraphQL schemas into a fluo application (**Schema-first**).
+- When you need seamless dependency injection within GraphQL resolvers, including request-scoped providers.
+- When performing efficient data fetching using request-scoped **DataLoader** patterns.
+
+## Quick Start
+
+Register `GraphqlModule.forRoot(...)` and define a resolver using standard decorators. `@fluojs/graphql` currently exposes a synchronous module entrypoint only; there is no `GraphqlModule.forRootAsync(...)` contract.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { bootstrapNodeApplication } from '@fluojs/runtime/node';
+import { GraphqlModule, Query, Resolver, Arg } from '@fluojs/graphql';
+
+@Resolver()
+class HelloResolver {
+  @Query()
+  hello(@Arg('name') name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+
+@Module({
+  imports: [
+    GraphqlModule.forRoot({
+      resolvers: [HelloResolver]
+    })
+  ],
+  providers: [HelloResolver]
+})
+class AppModule {}
+
+const app = await bootstrapNodeApplication(AppModule);
+await app.listen(3000);
+// curl -X POST http://localhost:3000/graphql \
+//   -H "Content-Type: application/json" \
+//   -d '{"query": "{ hello(name: \"fluo\") }"}'
+```
+
+## Core Capabilities
+
+### Code-first Resolvers
+fluo uses standard decorators to define your GraphQL schema. Use `@Resolver`, `@Query`, `@Mutation`, and `@Subscription` to map class methods to GraphQL operations.
+
+### Request-Scoped DataLoaders
+Efficiently solve the N+1 problem with built-in DataLoader integration. Loaders are automatically isolated per GraphQL operation.
+
+```typescript
+import { createDataLoader, type GraphQLContext } from '@fluojs/graphql';
+
+const userLoader = createDataLoader(async (ids: string[]) => {
+  const users = await userService.findByIds(ids);
+  return ids.map(id => users.find(u => u.id === id));
+});
+
+@Resolver()
+class UserResolver {
+  @Query()
+  async user(@Arg('id') id: string, context: GraphQLContext) {
+    return userLoader(context).load(id);
+  }
+}
+```
+
+### Protocol Support
+- **HTTP**: Standard GET/POST queries and mutations.
+- **SSE**: Subscriptions over Server-Sent Events (default).
+- **WebSockets**: Optional `graphql-ws` support for real-time subscriptions.
+
+```typescript
+GraphqlModule.forRoot({
+  subscriptions: {
+    websocket: {
+      enabled: true,
+      limits: {
+        maxConnections: 100,
+        maxPayloadBytes: 64 * 1024,
+        maxOperationsPerConnection: 25,
+      },
+    }
+  }
+})
+```
+
+## Operational Guardrails
+
+- Schema introspection is disabled by default unless you explicitly enable `graphiql` or set `introspection: true`.
+- Request validation budgets are enabled by default with conservative limits for document depth, field complexity, and aggregate query cost.
+- WebSocket subscriptions use separate transport budgets by default: `100` concurrent connections, `64 KiB` maximum payload size, and `25` active operations per connection.
+- Set `subscriptions.websocket.limits = false` only when you intentionally need unbounded websocket behavior and can enforce equivalent controls elsewhere.
+- Pass `limits: false` only when you intentionally need unbounded behavior and can compensate with external controls.
+
+```typescript
+GraphqlModule.forRoot({
+  graphiql: false,
+  introspection: false,
+  limits: {
+    maxDepth: 8,
+    maxComplexity: 120,
+    maxCost: 240,
+  },
+  subscriptions: {
+    websocket: {
+      enabled: true,
+      limits: {
+        maxConnections: 100,
+        maxPayloadBytes: 64 * 1024,
+        maxOperationsPerConnection: 25,
+      },
+    },
+  },
+  resolvers: [HelloResolver],
+})
+```
+
+## Public API
+
+- `GraphqlModule.forRoot(options)`: Main entry point for GraphQL integration.
+- `Resolver`, `Query`, `Mutation`, `Subscription`: Operation decorators.
+- `Arg`: Argument mapping decorator.
+- `createDataLoader`, `createDataLoaderMap`: DataLoader factory helpers.
+- `GraphQLContext`: Type definition for the GraphQL execution context.
+
+## Related Packages
+
+- `@fluojs/core`: Core DI and module system.
+- `@fluojs/http`: Underlying HTTP abstraction.
+- `@fluojs/validation`: Integrated DTO validation for GraphQL inputs.
+
+## Example Sources
+
+- `packages/graphql/src/module.test.ts`: Integration tests and usage examples.
+- `examples/graphql-yoga`: Complete GraphQL application example.

package/dist/dataloader/dataloader.d.ts

@@ -0,0 +1,127 @@
+import DataLoader from 'dataloader';
+import { type GraphQLContext } from '../types.js';
+/**
+ * Returns a request-scoped loader instance from GraphQL context cache.
+ *
+ * @param context GraphQL operation context that holds the request-scoped loader cache.
+ * @param key Stable cache key for this loader instance within a single operation.
+ * @param createLoader Factory used when no loader is cached yet for `key`.
+ * @returns The cached or newly created loader instance for the current operation.
+ */
+export declare function getRequestScopedDataLoader<TLoader>(context: GraphQLContext, key: string | symbol, createLoader: () => TLoader): TLoader;
+/**
+ * Creates an accessor that resolves one request-scoped loader from context.
+ *
+ * @param key Stable cache key for this loader instance within a single operation.
+ * @param createLoader Factory used when no loader is cached yet for `key`.
+ * @returns A context accessor that always resolves the per-operation cached loader.
+ */
+export declare function createRequestScopedDataLoaderFactory<TLoader>(key: string | symbol, createLoader: () => TLoader): (context: GraphQLContext) => TLoader;
+/**
+ * Options accepted by {@link createDataLoader}. Extends the standard
+ * `DataLoader.Options` with an optional `key` used to deduplicate loader
+ * instances inside the per-operation request-scoped cache.
+ */
+export interface FluoDataLoaderOptions<K, V, C = K> extends DataLoader.Options<K, V, C> {
+    /**
+     * Cache key used to store/retrieve this loader in the per-operation
+     * request-scoped cache.  When omitted a unique `Symbol` is generated
+     * automatically, which means every call-site gets its own loader instance
+     * per operation — usually what you want.
+     */
+    key?: string | symbol;
+}
+/**
+ * A function returned by {@link createDataLoader} that, given a
+ * {@link GraphQLContext}, returns a request-scoped `DataLoader` instance.
+ *
+ * Call this inside any resolver method to obtain a DataLoader that is
+ * automatically scoped to the current GraphQL operation.
+ */
+export type RequestScopedDataLoaderAccessor<K, V> = (context: GraphQLContext) => DataLoader<K, V>;
+/**
+ * Create a request-scoped `DataLoader` accessor.
+ *
+ * This is the recommended first-party entry point for DataLoader usage in
+ * `@fluojs/graphql`.  It combines the `dataloader` package with Fluo's
+ * per-operation request-scoped cache so that:
+ *
+ * - Each GraphQL operation gets its own `DataLoader` instance (cache isolation).
+ * - Concurrent operations never share batched results.
+ * - The accessor is safe to call from singleton resolvers — no `@Scope('request')` required.
+ *
+ * @example
+ * ```ts
+ * import { createDataLoader, type GraphQLContext } from '@fluojs/graphql';
+ *
+ * const getUserById = createDataLoader<string, User | null>(async (ids) => {
+ *   const users = await userRepo.findManyByIds([...ids]);
+ *   const map = new Map(users.map(u => [u.id, u]));
+ *   return ids.map(id => map.get(id) ?? null);
+ * });
+ *
+ * // inside a resolver method:
+ * const user = await getUserById(context).load(userId);
+ * ```
+ *
+ * @param batchFn DataLoader batch function that maps requested keys to ordered values.
+ * @param options Optional DataLoader options plus an optional stable Fluo cache key.
+ * @returns A request-scoped accessor that resolves a `DataLoader` for the current operation.
+ */
+export declare function createDataLoader<K, V, C = K>(batchFn: DataLoader.BatchLoadFn<K, V>, options?: FluoDataLoaderOptions<K, V, C>): RequestScopedDataLoaderAccessor<K, V>;
+/**
+ * Describes a single loader entry in a {@link DataLoaderMap}.
+ */
+export interface DataLoaderDefinition<K, V, C = K> {
+    batch: DataLoader.BatchLoadFn<K, V>;
+    options?: DataLoader.Options<K, V, C>;
+}
+/**
+ * A map from loader names to their definitions.
+ *
+ * @example
+ * ```ts
+ * const loaders = {
+ *   userById: { batch: async (ids) => ... },
+ *   postsByAuthor: { batch: async (authorIds) => ..., options: { cache: false } },
+ * } satisfies DataLoaderMap;
+ * ```
+ */
+export type DataLoaderMap = Record<string, DataLoaderDefinition<any, any, any>>;
+/**
+ * The resolved accessor type: each key from the definition map becomes a
+ * `DataLoader` instance keyed by the original batch function's types.
+ */
+export type ResolvedDataLoaders<TMap extends DataLoaderMap> = {
+    [K in keyof TMap]: TMap[K] extends DataLoaderDefinition<infer TKey, infer TValue, any> ? DataLoader<TKey, TValue> : never;
+};
+/**
+ * Create a set of named, request-scoped DataLoaders from a definition map.
+ *
+ * This is convenient when a resolver (or a group of resolvers) needs multiple
+ * loaders — instead of declaring each one individually, define them as a map
+ * and retrieve the whole set per operation.
+ *
+ * @example
+ * ```ts
+ * const loaders = createDataLoaderMap({
+ *   userById: {
+ *     batch: async (ids) => {
+ *       const users = await repo.findManyByIds([...ids]);
+ *       const map = new Map(users.map(u => [u.id, u]));
+ *       return ids.map(id => map.get(id) ?? null);
+ *     },
+ *   },
+ * });
+ *
+ * // inside resolver:
+ * const { userById } = loaders(context);
+ * const user = await userById.load('abc');
+ * ```
+ *
+ * @param definitions Loader definitions keyed by loader name.
+ * @returns A context accessor that resolves all named loaders for one GraphQL operation.
+ */
+export declare function createDataLoaderMap<TMap extends DataLoaderMap>(definitions: TMap): (context: GraphQLContext) => ResolvedDataLoaders<TMap>;
+export { DataLoader };
+//# sourceMappingURL=dataloader.d.ts.map

package/dist/dataloader/dataloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataloader.d.ts","sourceRoot":"","sources":["../../src/dataloader/dataloader.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,OAAO,EAAuC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAChD,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,YAAY,EAAE,MAAM,OAAO,GAC1B,OAAO,CAaT;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,OAAO,EAC1D,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,YAAY,EAAE,MAAM,OAAO,GAC1B,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAEtC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAE,SAAQ,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrF;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,+BAA+B,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,KAAK,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAC1C,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EACrC,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACvC,+BAA+B,CAAC,CAAC,EAAE,CAAC,CAAC,CAQvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC;IAC/C,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,aAAa,IAAI;KAC3D,CAAC,IAAI,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS,oBAAoB,CAAC,MAAM,IAAI,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC,GAClF,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GACxB,KAAK;CACV,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,SAAS,aAAa,EAC5D,WAAW,EAAE,IAAI,GAChB,CAAC,OAAO,EAAE,cAAc,KAAK,mBAAmB,CAAC,IAAI,CAAC,CAiBxD;AAED,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/dataloader/dataloader.js

@@ -0,0 +1,151 @@
+import DataLoader from 'dataloader';
+import { GRAPHQL_REQUEST_SCOPED_LOADER_CACHE } from '../types.js';
+
+/**
+ * Returns a request-scoped loader instance from GraphQL context cache.
+ *
+ * @param context GraphQL operation context that holds the request-scoped loader cache.
+ * @param key Stable cache key for this loader instance within a single operation.
+ * @param createLoader Factory used when no loader is cached yet for `key`.
+ * @returns The cached or newly created loader instance for the current operation.
+ */
+export function getRequestScopedDataLoader(context, key, createLoader) {
+  const cache = context[GRAPHQL_REQUEST_SCOPED_LOADER_CACHE] ?? new Map();
+  context[GRAPHQL_REQUEST_SCOPED_LOADER_CACHE] = cache;
+  const existing = cache.get(key);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const created = createLoader();
+  cache.set(key, created);
+  return created;
+}
+
+/**
+ * Creates an accessor that resolves one request-scoped loader from context.
+ *
+ * @param key Stable cache key for this loader instance within a single operation.
+ * @param createLoader Factory used when no loader is cached yet for `key`.
+ * @returns A context accessor that always resolves the per-operation cached loader.
+ */
+export function createRequestScopedDataLoaderFactory(key, createLoader) {
+  return context => getRequestScopedDataLoader(context, key, createLoader);
+}
+
+/**
+ * Options accepted by {@link createDataLoader}. Extends the standard
+ * `DataLoader.Options` with an optional `key` used to deduplicate loader
+ * instances inside the per-operation request-scoped cache.
+ */
+
+/**
+ * A function returned by {@link createDataLoader} that, given a
+ * {@link GraphQLContext}, returns a request-scoped `DataLoader` instance.
+ *
+ * Call this inside any resolver method to obtain a DataLoader that is
+ * automatically scoped to the current GraphQL operation.
+ */
+
+/**
+ * Create a request-scoped `DataLoader` accessor.
+ *
+ * This is the recommended first-party entry point for DataLoader usage in
+ * `@fluojs/graphql`.  It combines the `dataloader` package with Fluo's
+ * per-operation request-scoped cache so that:
+ *
+ * - Each GraphQL operation gets its own `DataLoader` instance (cache isolation).
+ * - Concurrent operations never share batched results.
+ * - The accessor is safe to call from singleton resolvers — no `@Scope('request')` required.
+ *
+ * @example
+ * ```ts
+ * import { createDataLoader, type GraphQLContext } from '@fluojs/graphql';
+ *
+ * const getUserById = createDataLoader<string, User | null>(async (ids) => {
+ *   const users = await userRepo.findManyByIds([...ids]);
+ *   const map = new Map(users.map(u => [u.id, u]));
+ *   return ids.map(id => map.get(id) ?? null);
+ * });
+ *
+ * // inside a resolver method:
+ * const user = await getUserById(context).load(userId);
+ * ```
+ *
+ * @param batchFn DataLoader batch function that maps requested keys to ordered values.
+ * @param options Optional DataLoader options plus an optional stable Fluo cache key.
+ * @returns A request-scoped accessor that resolves a `DataLoader` for the current operation.
+ */
+export function createDataLoader(batchFn, options) {
+  const {
+    key: userKey,
+    ...dataloaderOptions
+  } = options ?? {};
+  const cacheKey = userKey ?? Symbol('fluo.dataloader');
+  return createRequestScopedDataLoaderFactory(cacheKey, () => new DataLoader(batchFn, dataloaderOptions));
+}
+
+/**
+ * Describes a single loader entry in a {@link DataLoaderMap}.
+ */
+
+/**
+ * A map from loader names to their definitions.
+ *
+ * @example
+ * ```ts
+ * const loaders = {
+ *   userById: { batch: async (ids) => ... },
+ *   postsByAuthor: { batch: async (authorIds) => ..., options: { cache: false } },
+ * } satisfies DataLoaderMap;
+ * ```
+ */
+
+/**
+ * The resolved accessor type: each key from the definition map becomes a
+ * `DataLoader` instance keyed by the original batch function's types.
+ */
+
+/**
+ * Create a set of named, request-scoped DataLoaders from a definition map.
+ *
+ * This is convenient when a resolver (or a group of resolvers) needs multiple
+ * loaders — instead of declaring each one individually, define them as a map
+ * and retrieve the whole set per operation.
+ *
+ * @example
+ * ```ts
+ * const loaders = createDataLoaderMap({
+ *   userById: {
+ *     batch: async (ids) => {
+ *       const users = await repo.findManyByIds([...ids]);
+ *       const map = new Map(users.map(u => [u.id, u]));
+ *       return ids.map(id => map.get(id) ?? null);
+ *     },
+ *   },
+ * });
+ *
+ * // inside resolver:
+ * const { userById } = loaders(context);
+ * const user = await userById.load('abc');
+ * ```
+ *
+ * @param definitions Loader definitions keyed by loader name.
+ * @returns A context accessor that resolves all named loaders for one GraphQL operation.
+ */
+export function createDataLoaderMap(definitions) {
+  const accessors = new Map();
+  for (const [name, def] of Object.entries(definitions)) {
+    accessors.set(name, createDataLoader(def.batch, {
+      ...def.options,
+      key: Symbol(`fluo.dataloader.map.${name}`)
+    }));
+  }
+  return context => {
+    const result = {};
+    for (const [name, accessor] of accessors) {
+      result[name] = accessor(context);
+    }
+    return result;
+  };
+}
+export { DataLoader };

package/dist/dataloader.d.ts

@@ -0,0 +1,2 @@
+export * from './dataloader/dataloader.js';
+//# sourceMappingURL=dataloader.d.ts.map

package/dist/dataloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataloader.d.ts","sourceRoot":"","sources":["../src/dataloader.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC"}

package/dist/dataloader.js

@@ -0,0 +1 @@
+export * from './dataloader/dataloader.js';

package/dist/decorators.d.ts

@@ -0,0 +1,21 @@
+import type { GraphqlArgType, GraphqlRootOutputType } from './types.js';
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
+type StandardFieldDecoratorFn = <This, Value>(value: undefined, context: ClassFieldDecoratorContext<This, Value>) => void;
+export interface ResolverMethodOptions {
+    fieldName?: string;
+    input?: Function;
+    topics?: string | string[];
+    argTypes?: Record<string, GraphqlArgType>;
+    outputType?: GraphqlRootOutputType;
+}
+type ClassDecoratorLike = StandardClassDecoratorFn;
+type MethodDecoratorLike = StandardMethodDecoratorFn;
+type FieldDecoratorLike = StandardFieldDecoratorFn;
+export declare function Resolver(typeName?: string): ClassDecoratorLike;
+export declare function Query(fieldNameOrOptions?: string | ResolverMethodOptions): MethodDecoratorLike;
+export declare function Mutation(fieldNameOrOptions?: string | ResolverMethodOptions): MethodDecoratorLike;
+export declare function Subscription(fieldNameOrOptions?: string | ResolverMethodOptions): MethodDecoratorLike;
+export declare function Arg(argName?: string): FieldDecoratorLike;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoB,cAAc,EAAE,qBAAqB,EAA6C,MAAM,YAAY,CAAC;AAGrI,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,wBAAwB,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;AAE1H,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,KAAK,kBAAkB,GAAG,wBAAwB,CAAC;AACnD,KAAK,mBAAmB,GAAG,yBAAyB,CAAC;AACrD,KAAK,kBAAkB,GAAG,wBAAwB,CAAC;AAoGnD,wBAAgB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAQ9D;AAED,wBAAgB,KAAK,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,qBAAqB,GAAG,mBAAmB,CAE9F;AAED,wBAAgB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,qBAAqB,GAAG,mBAAmB,CAEjG;AAED,wBAAgB,YAAY,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,qBAAqB,GAAG,mBAAmB,CAErG;AAED,wBAAgB,GAAG,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAmBxD"}