@bleedingdev/modern-js-bff-effect 3.8.3-ultramodern.2

package/dist/esm-node/effect/edge-dispatcher.mjs

@@ -0,0 +1,116 @@
+import "node:module";
+import { evaluateCrossProjectPolicy, resolveCrossProjectRequestObservation } from "@modern-js/bff-core/security/cross-project-policy";
+import { toHeaderRecord } from "../headers.mjs";
+import { dispatchEffectBffRequestWithContext } from "./dispatch.mjs";
+import { runWithEffectContext, useEffectContext, useOperationContext } from "./edge-context.mjs";
+import { resolveEffectBffModuleHandler } from "./module.mjs";
+import * as __rspack_external_effect_Config_76cfa59d from "effect/Config";
+import * as __rspack_external_effect_Effect_41060786 from "effect/Effect";
+import * as __rspack_external_effect_Layer_69c46453 from "effect/Layer";
+import * as __rspack_external_effect_Option_0498e63a from "effect/Option";
+import * as __rspack_external_effect_Schema_6065f72d from "effect/Schema";
+const NORMALIZED_POLICY_BOOLEAN_FIELDS = [
+    'enabled',
+    'requireEnvelope',
+    'requireOperationContext',
+    'requireOperationContextDetails',
+    'requireOperationSchemaHash',
+    'requireOperationVersion',
+    'allowUnknownOperations'
+];
+function assertNormalizedCrossProjectPolicy(policy) {
+    if (void 0 === policy) return;
+    if (!policy || 'object' != typeof policy || Array.isArray(policy)) throw new Error('[BFF][Effect] Edge cross-project policy must be a normalized object.');
+    for (const field of NORMALIZED_POLICY_BOOLEAN_FIELDS)if ('boolean' != typeof policy[field]) throw new Error(`[BFF][Effect] Edge cross-project policy requires boolean ${field}.`);
+    if (!policy.expectedOperationContracts || 'object' != typeof policy.expectedOperationContracts || Array.isArray(policy.expectedOperationContracts)) throw new Error('[BFF][Effect] Edge cross-project policy requires expectedOperationContracts object.');
+}
+function restoreEffectBffMountPath(request, prefix) {
+    const pathname = new URL(request.url).pathname;
+    if (!prefix || '/' === prefix) return pathname;
+    const normalizedPrefix = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+    return '/' === pathname ? normalizedPrefix : `${normalizedPrefix}${pathname}`;
+}
+async function dispatchEffectBffRequest(handler, request, options = {}) {
+    return dispatchEffectBffRequestWithContext(handler, request, {
+        ...options,
+        runWithEffectContext: runWithEffectContext
+    });
+}
+async function createEffectBffEdgeDispatcher(options) {
+    const crossProjectPolicy = options.crossProjectPolicy;
+    assertNormalizedCrossProjectPolicy(crossProjectPolicy);
+    const loaded = await resolveEffectBffModuleHandler(options.module, {
+        openapi: options.openapi,
+        dataPlatform: options.dataPlatform,
+        validateRequest: crossProjectPolicy?.enabled === true ? (request)=>{
+            const pathname = new URL(request.url).pathname;
+            const observedRequest = resolveCrossProjectRequestObservation({
+                method: request.method,
+                pathname
+            }, crossProjectPolicy) ?? {
+                method: request.method,
+                routePath: restoreEffectBffMountPath(request, options.prefix)
+            };
+            const violation = evaluateCrossProjectPolicy(toHeaderRecord(request.headers), crossProjectPolicy, observedRequest);
+            if (!violation) return null;
+            return new Response(JSON.stringify({
+                code: violation.code,
+                reason: violation.reason,
+                message: violation.message
+            }), {
+                status: violation.status,
+                headers: {
+                    'content-type': 'application/json; charset=utf-8'
+                }
+            });
+        } : void 0,
+        onWarning: options.onWarning
+    });
+    if (!loaded) throw new Error('[BFF][Effect] Invalid Effect edge module. Export defineEffectBff(...) or a { api, layer } HttpApi module.');
+    const retiredError = new Error('[BFF][Effect] Edge dispatcher is disposing or has been disposed.');
+    let acceptingRequests = true;
+    let activeDispatches = 0;
+    let resolveDrain;
+    let disposePromise;
+    return {
+        dispatch: (request, dispatchOptions = {})=>{
+            if (!acceptingRequests) return Promise.reject(retiredError);
+            activeDispatches += 1;
+            return dispatchEffectBffRequest(loaded.handler, request, {
+                ...dispatchOptions,
+                prefix: options.prefix,
+                onError: options.onError
+            }).finally(()=>{
+                activeDispatches -= 1;
+                if (0 === activeDispatches) {
+                    resolveDrain?.();
+                    resolveDrain = void 0;
+                }
+            });
+        },
+        dispose: ()=>{
+            disposePromise ??= (async ()=>{
+                acceptingRequests = false;
+                if (activeDispatches > 0) await new Promise((resolve)=>{
+                    resolveDrain = resolve;
+                });
+                await loaded.dispose?.();
+            })();
+            return disposePromise;
+        }
+    };
+}
+const createEffectBffTestHandler = createEffectBffEdgeHandler;
+async function createEffectBffEdgeHandler(options) {
+    const dispatcher = await createEffectBffEdgeDispatcher(options);
+    return {
+        handler: dispatcher.dispatch,
+        dispose: dispatcher.dispose
+    };
+}
+export { Cookies, Etag, FetchHttpClient, FindMyWay, Headers, HttpBody, HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse, HttpEffect, HttpIncomingMessage, HttpMethod, HttpMiddleware, HttpPlatform, HttpRouter, HttpServer, HttpServerError, HttpServerRequest, HttpServerRespondable, HttpServerResponse, HttpStaticServer, HttpStatus, HttpTraceContext, Multipart, MultipartParser, Template, Url, UrlParams } from "effect/unstable/http";
+export { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, HttpApiSecurity, HttpApiTest, OpenApi } from "effect/unstable/httpapi";
+export { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMessage, RpcMiddleware, RpcSchema, RpcSerialization, RpcServer, RpcTest, RpcWorker, Utils } from "effect/unstable/rpc";
+export { createHttpApiHandler, defineEffectBff, defineEffectRpcBff } from "./handler.mjs";
+export { createEffectOperationContext } from "./operation-context.mjs";
+export { __rspack_external_effect_Config_76cfa59d as Config, __rspack_external_effect_Effect_41060786 as Effect, __rspack_external_effect_Layer_69c46453 as Layer, __rspack_external_effect_Option_0498e63a as Option, __rspack_external_effect_Schema_6065f72d as Schema, createEffectBffEdgeDispatcher, createEffectBffEdgeHandler, createEffectBffTestHandler, dispatchEffectBffRequest, runWithEffectContext, useEffectContext, useOperationContext };

package/dist/esm-node/effect/edge.mjs

@@ -0,0 +1,2 @@
+import "node:module";
+export * from "./edge-dispatcher.mjs";

package/dist/esm-node/effect/endpoint-contracts.mjs

@@ -0,0 +1,69 @@
+import "node:module";
+import { createOperationContractHash } from "@modern-js/bff-core";
+import { classifyEffectBffEntryModule, isValidatorAwareHandlerFactory } from "./entry-shape.mjs";
+function resolveEffectEndpointName(endpoint) {
+    if ('string' == typeof endpoint.identifier && endpoint.identifier) return endpoint.identifier;
+    if ('string' == typeof endpoint.name && endpoint.name) return endpoint.name;
+    return '';
+}
+function ensureLeadingSlash(pathname) {
+    return pathname.startsWith('/') ? pathname : `/${pathname}`;
+}
+function normalizeEffectPrefix(prefix) {
+    if ('/' === prefix) return '';
+    return ensureLeadingSlash(prefix || '/api');
+}
+function getEffectRoutePath(prefix, endpointPath) {
+    const normalizedPrefix = normalizeEffectPrefix(prefix);
+    const normalizedEndpointPath = ensureLeadingSlash(endpointPath);
+    const finalEndpointPath = '/' === normalizedEndpointPath ? '' : endpointPath;
+    if (!normalizedPrefix && !finalEndpointPath) return '/';
+    return `${normalizedPrefix}${finalEndpointPath || ''}`;
+}
+function resolveEffectApiId(api) {
+    const fallback = 'EffectHttpApi';
+    if ('identifier' in api && 'string' == typeof api.identifier && api.identifier) return api.identifier;
+    return fallback;
+}
+function collectEffectEndpoints(reflect, api, prefix) {
+    const endpoints = [];
+    const apiId = resolveEffectApiId(api);
+    reflect(api, {
+        onGroup: ()=>{},
+        onEndpoint: ({ group, endpoint })=>{
+            endpoints.push({
+                apiId,
+                groupName: String(group.identifier),
+                endpointName: resolveEffectEndpointName(endpoint),
+                method: String(endpoint.method).toUpperCase(),
+                routePath: getEffectRoutePath(prefix, String(endpoint.path))
+            });
+        }
+    });
+    return endpoints.sort((a, b)=>{
+        if (a.groupName === b.groupName) return a.endpointName.localeCompare(b.endpointName);
+        return a.groupName.localeCompare(b.groupName);
+    });
+}
+function toOperationContractSources(endpoints) {
+    return endpoints.map(createEffectOperationContractSource);
+}
+function createEffectOperationContractSource(endpoint) {
+    return {
+        name: endpoint.endpointName,
+        httpMethod: endpoint.method,
+        routePath: endpoint.routePath
+    };
+}
+async function extractHttpApiFromModule(mod, isHttpApi) {
+    const facts = classifyEffectBffEntryModule(mod, {
+        isRequestHandler: (value)=>'function' == typeof value,
+        isValidatorAwareHandlerFactory: isValidatorAwareHandlerFactory,
+        isHttpApi
+    });
+    return !facts?.legacyShape && facts?.api !== void 0 && facts.hasRuntimeLayer && (void 0 === facts.createHandler || facts.createHandlerValidatorAware) ? facts.api : null;
+}
+function createEffectEndpointContractHash(endpoint, requestId) {
+    return createOperationContractHash(createEffectOperationContractSource(endpoint), requestId);
+}
+export { collectEffectEndpoints, createEffectEndpointContractHash, ensureLeadingSlash, extractHttpApiFromModule, normalizeEffectPrefix, toOperationContractSources };

package/dist/esm-node/effect/entry-shape-registry.mjs

@@ -0,0 +1,18 @@
+import "node:module";
+"use strict";
+import { __webpack_require__ } from "../rslib-runtime.mjs";
+__webpack_require__.add({
+    "./src/effect/entry-shape-registry.cjs" (module) {
+        const validatorAwareHandlerFactories = new WeakSet();
+        module.exports = {
+            register (factory) {
+                validatorAwareHandlerFactories.add(factory);
+                return factory;
+            },
+            is (factory) {
+                return 'function' == typeof factory && validatorAwareHandlerFactories.has(factory);
+            }
+        };
+    }
+});
+__webpack_require__("./src/effect/entry-shape-registry.cjs");

package/dist/esm-node/effect/entry-shape.mjs

@@ -0,0 +1,63 @@
+import "node:module";
+function createLocalValidatorAwareHandlerFactoryRegistry() {
+    const factories = new WeakSet();
+    return {
+        register (factory) {
+            factories.add(factory);
+            return factory;
+        },
+        is (factory) {
+            return 'function' == typeof factory && factories.has(factory);
+        }
+    };
+}
+function loadNodeValidatorAwareHandlerFactoryRegistry() {
+    const moduleUrl = import.meta.url;
+    if ('string' != typeof moduleUrl || !moduleUrl.startsWith('file:')) return createLocalValidatorAwareHandlerFactoryRegistry();
+    const moduleBuiltin = process.getBuiltinModule('node:module');
+    try {
+        return moduleBuiltin.createRequire(moduleUrl)("#effect-entry-shape-registry");
+    } catch (error) {
+        if (null !== error && 'object' == typeof error && 'code' in error && 'MODULE_NOT_FOUND' === error.code) return createLocalValidatorAwareHandlerFactoryRegistry();
+        throw error;
+    }
+}
+const validatorAwareHandlerFactoryRegistry = loadNodeValidatorAwareHandlerFactoryRegistry();
+function registerValidatorAwareHandlerFactory(factory) {
+    return validatorAwareHandlerFactoryRegistry.register(factory);
+}
+function isValidatorAwareHandlerFactory(factory) {
+    return validatorAwareHandlerFactoryRegistry.is(factory);
+}
+const strictEffectApproachMessage = '[BFF][Effect] strictEffectApproach is enforced: Effect API entries export defineEffectBff(...) or { api, layer } HttpApi module. Raw handler exports, default request handlers, unbranded custom createHandler factories not valid Effect API entries.';
+function isEffectEntryRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function classifyEffectBffEntryModule(value, predicates) {
+    if (!isEffectEntryRecord(value)) return null;
+    const rootModule = value;
+    if (predicates.isRequestHandler(rootModule.handler)) return createEntryShapeFacts(rootModule, predicates, '`handler` export');
+    const defaultEntry = rootModule.default;
+    if (predicates.isRequestHandler(defaultEntry)) return createEntryShapeFacts(rootModule, predicates, 'default request handler');
+    const module = isEffectEntryRecord(defaultEntry) ? {
+        ...rootModule,
+        ...defaultEntry
+    } : rootModule;
+    if (predicates.isRequestHandler(module.handler)) return createEntryShapeFacts(module, predicates, '`handler` export');
+    return createEntryShapeFacts(module, predicates);
+}
+function createEntryShapeFacts(module, predicates, legacyShape) {
+    const createHandler = 'function' == typeof module.createHandler ? module.createHandler : void 0;
+    const api = predicates.isHttpApi(module.api) ? module.api : void 0;
+    const hasRuntimeLayer = void 0 !== module.layer;
+    return {
+        module,
+        legacyShape,
+        createHandler,
+        createHandlerValidatorAware: void 0 !== createHandler && predicates.isValidatorAwareHandlerFactory(createHandler),
+        api,
+        layer: module.layer,
+        hasRuntimeLayer
+    };
+}
+export { classifyEffectBffEntryModule, isValidatorAwareHandlerFactory, registerValidatorAwareHandlerFactory, strictEffectApproachMessage };

package/dist/esm-node/effect/handler/batch-handler.mjs

@@ -0,0 +1,233 @@
+import "node:module";
+import { DEFAULT_DATA_BATCH_HEADER, DEFAULT_DATA_ENVELOPE_HEADER, decodeRequestEnvelopeHeader, isPlainObject, normalizeMethod } from "../../data-platform/index.mjs";
+import { decodeBatchBody, isBatchBody, toBatchResponseItem } from "../../data-platform/batch/protocol.mjs";
+import { BatchItemTimeoutError, createBatchValidationResponse, isBatchRequestPayload, mapWithConcurrency, normalizeBatchAllowedMethods, normalizeBatchPath, promiseWithTimeout, toBatchItemError } from "./batch.mjs";
+import { getMountedPrefixFromContext, removeMountedPrefixFromBatchPath } from "./routing.mjs";
+const HOP_BY_HOP_BATCH_ITEM_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade'
+]);
+const OUTER_BOUND_BATCH_ITEM_HEADERS = new Set([
+    'authorization',
+    'cookie',
+    'forwarded',
+    'origin',
+    'referer',
+    'sec-fetch-dest',
+    'sec-fetch-mode',
+    'sec-fetch-site',
+    'sec-fetch-user',
+    'x-forwarded-client-cert',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-port',
+    'x-forwarded-proto',
+    'x-real-ip',
+    'x-subject-id',
+    'x-tenant-id',
+    'x-user-id',
+    'x-verified-producer'
+]);
+const TRANSPORT_CONTROLLED_BATCH_ITEM_HEADERS = new Set([
+    'content-length',
+    'host',
+    ...HOP_BY_HOP_BATCH_ITEM_HEADERS
+]);
+async function readRequestTextWithinLimit(request, maxBytes) {
+    const contentLength = request.headers.get('content-length');
+    if (null !== contentLength) {
+        if (!/^\d+$/.test(contentLength)) return {
+            status: 'invalid-content-length'
+        };
+        if (BigInt(contentLength) > BigInt(maxBytes)) return {
+            status: 'too-large'
+        };
+    }
+    if (null === request.body) return {
+        status: 'ok',
+        text: ''
+    };
+    const reader = request.body.getReader();
+    const decoder = new TextDecoder();
+    const text = [];
+    let bytesRead = 0;
+    try {
+        while(true){
+            const chunk = await reader.read();
+            if (chunk.done) {
+                text.push(decoder.decode());
+                return {
+                    status: 'ok',
+                    text: text.join('')
+                };
+            }
+            bytesRead += chunk.value.byteLength;
+            if (bytesRead > maxBytes) {
+                await reader.cancel('batch-payload-too-large');
+                return {
+                    status: 'too-large'
+                };
+            }
+            text.push(decoder.decode(chunk.value, {
+                stream: true
+            }));
+        }
+    } catch  {
+        return {
+            status: 'read-error'
+        };
+    } finally{
+        reader.releaseLock();
+    }
+}
+function createDataPlatformBatchRequestHandler(options) {
+    const dataPlatformBatchOptions = options.dataPlatform?.batch;
+    const batchEnabled = dataPlatformBatchOptions?.enabled !== false;
+    const batchPath = normalizeBatchPath(dataPlatformBatchOptions?.endpoint);
+    const batchMaxSize = Math.max(1, dataPlatformBatchOptions?.maxBatchSize ?? 16);
+    const batchMaxBytes = Math.max(1024, dataPlatformBatchOptions?.maxBatchBytes ?? 65536);
+    const batchConcurrency = Math.max(1, dataPlatformBatchOptions?.maxConcurrency ?? 4);
+    const batchItemTimeoutMs = Math.max(0, dataPlatformBatchOptions?.requestTimeoutMs ?? 10000);
+    const batchAllowedMethods = normalizeBatchAllowedMethods(dataPlatformBatchOptions?.allowedMethods);
+    const envelopeHeader = options.dataPlatform?.envelopeHeader || DEFAULT_DATA_ENVELOPE_HEADER;
+    const normalizedEnvelopeHeader = envelopeHeader.toLowerCase();
+    const handle = async (request, context)=>{
+        const mountedPrefix = getMountedPrefixFromContext(request, context);
+        const method = normalizeMethod(request.method);
+        if ('POST' !== method) return createBatchValidationResponse('Batch endpoint only supports POST requests', 405);
+        const contentType = request.headers.get('content-type') || '';
+        if (!contentType.includes('application/json')) return createBatchValidationResponse('Batch endpoint requires application/json content-type', 415);
+        const bodyResult = await readRequestTextWithinLimit(request, batchMaxBytes);
+        if ('too-large' === bodyResult.status) return createBatchValidationResponse(`Batch payload exceeds max size (${String(batchMaxBytes)} bytes)`, 413);
+        if ('invalid-content-length' === bodyResult.status) return createBatchValidationResponse('Batch payload has invalid content-length');
+        if ('read-error' === bodyResult.status) return createBatchValidationResponse('Unable to read batch payload');
+        const payloadText = bodyResult.text;
+        let payload;
+        try {
+            payload = JSON.parse(payloadText);
+        } catch  {
+            return createBatchValidationResponse('Invalid batch payload JSON');
+        }
+        if (!isBatchRequestPayload(payload)) return createBatchValidationResponse('Invalid batch payload shape');
+        if (0 === payload.items.length) return createBatchValidationResponse('Batch payload items cannot be empty');
+        if (payload.items.length > batchMaxSize) return createBatchValidationResponse(`Batch item count exceeds max size (${String(batchMaxSize)})`, 413);
+        const batchRequestOrigin = new URL(request.url).origin;
+        const responseItems = await mapWithConcurrency(payload.items, batchConcurrency, async (rawItem, index)=>{
+            const fallbackId = `item_${String(index)}`;
+            const itemId = isPlainObject(rawItem) && 'string' == typeof rawItem.id ? rawItem.id : fallbackId;
+            if (!isPlainObject(rawItem)) return toBatchItemError(itemId, 400, 'Invalid batch item; expected object');
+            if ('string' != typeof rawItem.path || 0 === rawItem.path.length) return toBatchItemError(itemId, 400, 'Invalid batch item path');
+            if (!rawItem.path.startsWith('/')) return toBatchItemError(itemId, 400, 'Batch item path must start with "/"');
+            const normalizedItemPath = removeMountedPrefixFromBatchPath(rawItem.path, mountedPrefix);
+            const itemPathname = normalizedItemPath.split('?')[0] || normalizedItemPath;
+            if (itemPathname === batchPath || itemPathname.startsWith(`${batchPath}/`)) return toBatchItemError(itemId, 400, 'Batch item path cannot target batch endpoint');
+            const itemMethod = normalizeMethod('string' == typeof rawItem.method ? rawItem.method : void 0);
+            if (!batchAllowedMethods.has(itemMethod)) return toBatchItemError(itemId, 405, `Batch item method ${itemMethod} is not allowed`);
+            if (void 0 !== rawItem.body && !isBatchBody(rawItem.body)) return toBatchItemError(itemId, 400, 'Batch item body must use the base64 body protocol');
+            if (('GET' === itemMethod || 'HEAD' === itemMethod) && void 0 !== rawItem.body) return toBatchItemError(itemId, 400, `${itemMethod} batch item cannot include body`);
+            const normalizedHeaders = {};
+            if (void 0 !== rawItem.headers) {
+                if (!isPlainObject(rawItem.headers)) return toBatchItemError(itemId, 400, 'Batch item headers must be an object');
+                for (const [key, value] of Object.entries(rawItem.headers)){
+                    if ('string' != typeof value) return toBatchItemError(itemId, 400, `Invalid header "${key}" for batch item`);
+                    normalizedHeaders[key.toLowerCase()] = value;
+                }
+            }
+            const connectionScopedHeaders = new Set((normalizedHeaders.connection || '').split(',').map((header)=>header.trim().toLowerCase()).filter(Boolean));
+            for (const header of Object.keys(normalizedHeaders))if (TRANSPORT_CONTROLLED_BATCH_ITEM_HEADERS.has(header) || OUTER_BOUND_BATCH_ITEM_HEADERS.has(header) || connectionScopedHeaders.has(header)) delete normalizedHeaders[header];
+            if (!normalizedHeaders.traceparent) {
+                const encodedEnvelope = normalizedHeaders[normalizedEnvelopeHeader];
+                if ('string' == typeof encodedEnvelope) {
+                    const envelope = decodeRequestEnvelopeHeader(encodedEnvelope);
+                    if (envelope?.traceparent) normalizedHeaders.traceparent = envelope.traceparent;
+                }
+            }
+            for (const header of OUTER_BOUND_BATCH_ITEM_HEADERS){
+                const value = request.headers.get(header);
+                if (null !== value) normalizedHeaders[header] = value;
+            }
+            if (!normalizedHeaders.traceparent) {
+                const requestTraceparent = request.headers.get('traceparent');
+                if (requestTraceparent) normalizedHeaders.traceparent = requestTraceparent;
+            }
+            const targetUrl = new URL(normalizedItemPath, request.url);
+            if (targetUrl.origin !== batchRequestOrigin) return toBatchItemError(itemId, 400, 'Batch item path must stay on the same origin');
+            let requestHeaders;
+            try {
+                requestHeaders = new Headers(normalizedHeaders);
+            } catch  {
+                return toBatchItemError(itemId, 400, 'Invalid batch item headers');
+            }
+            const body = 'GET' === itemMethod || 'HEAD' === itemMethod ? void 0 : void 0 === rawItem.body ? void 0 : decodeBatchBody(rawItem.body);
+            if (void 0 === body) requestHeaders.delete('content-type');
+            const itemAbortController = new AbortController();
+            const abortFromBatchRequest = ()=>itemAbortController.abort(request.signal.reason);
+            if (request.signal.aborted) abortFromBatchRequest();
+            else request.signal.addEventListener('abort', abortFromBatchRequest, {
+                once: true
+            });
+            const itemRequest = new Request(targetUrl.toString(), {
+                method: itemMethod,
+                headers: requestHeaders,
+                body,
+                signal: itemAbortController.signal
+            });
+            try {
+                const itemResponse = await promiseWithTimeout(options.handleItem(itemRequest, context), batchItemTimeoutMs, (error)=>itemAbortController.abort(error));
+                if (!(itemResponse instanceof Response)) return toBatchItemError(itemId, 500, 'Invalid response returned by batch item handler');
+                return toBatchResponseItem(itemId, itemResponse, 'HEAD' === itemMethod);
+            } catch (error) {
+                if (error instanceof BatchItemTimeoutError) {
+                    console.error({
+                        event: 'bff.batch.item.timeout',
+                        batchId: payload.batchId,
+                        itemId,
+                        method: itemMethod,
+                        path: itemPathname,
+                        errorName: error.name
+                    });
+                    return toBatchItemError(itemId, 504, 'Batch item request timed out');
+                }
+                if (error instanceof Response) return toBatchResponseItem(itemId, error, 'HEAD' === itemMethod);
+                console.error({
+                    event: 'bff.batch.item.failure',
+                    batchId: payload.batchId,
+                    itemId,
+                    method: itemMethod,
+                    path: itemPathname,
+                    errorName: error instanceof Error ? error.name : 'UnknownError'
+                });
+                return toBatchItemError(itemId, 500, 'Internal Server Error');
+            } finally{
+                request.signal.removeEventListener('abort', abortFromBatchRequest);
+            }
+        });
+        const responsePayload = {
+            protocolVersion: 2,
+            batchId: payload.batchId,
+            receivedAt: Date.now(),
+            items: responseItems
+        };
+        return new Response(JSON.stringify(responsePayload), {
+            status: 200,
+            headers: {
+                'content-type': 'application/json; charset=utf-8',
+                [DEFAULT_DATA_BATCH_HEADER]: '2',
+                'x-modernjs-data-batch-id': payload.batchId
+            }
+        });
+    };
+    return {
+        enabled: batchEnabled,
+        path: batchPath,
+        handle
+    };
+}
+export { createDataPlatformBatchRequestHandler };

package/dist/esm-node/effect/handler/batch.mjs

@@ -0,0 +1,106 @@
+import "node:module";
+import { DEFAULT_DATA_BATCH_ENDPOINT, isPlainObject, normalizeMethod } from "../../data-platform/index.mjs";
+import { encodeBatchText } from "../../data-platform/batch/protocol.mjs";
+function normalizeBatchPath(pathname) {
+    if (!pathname || '/' === pathname) return DEFAULT_DATA_BATCH_ENDPOINT;
+    if (!pathname.startsWith('/')) return `/${pathname}`;
+    return pathname;
+}
+function normalizeBatchAllowedMethods(allowedMethods) {
+    const source = Array.isArray(allowedMethods) && allowedMethods.length > 0 ? allowedMethods : [
+        'GET'
+    ];
+    return new Set(source.map((method)=>method.toUpperCase()));
+}
+function isBatchRequestPayload(value) {
+    return isPlainObject(value) && 2 === value.protocolVersion && 'string' == typeof value.batchId && 'number' == typeof value.sentAt && Array.isArray(value.items);
+}
+function createBatchValidationResponse(message, status = 400) {
+    return new Response(JSON.stringify({
+        message
+    }), {
+        status,
+        headers: {
+            'content-type': 'application/json; charset=utf-8'
+        }
+    });
+}
+function cloneWithoutJsonBodyHeaders(request) {
+    const headers = new Headers(request.headers);
+    headers.delete('content-type');
+    headers.delete('content-length');
+    return new Request(request.url, {
+        method: request.method,
+        headers,
+        signal: request.signal
+    });
+}
+async function prepareJsonRequestBody(request) {
+    const method = normalizeMethod(request.method);
+    if ('GET' === method || 'HEAD' === method) return request;
+    const contentType = (request.headers.get('content-type') || '').toLowerCase();
+    if (!contentType.includes('application/json')) return request;
+    if (null === request.body) return cloneWithoutJsonBodyHeaders(request);
+    try {
+        const bodyText = await request.clone().text();
+        if ('' === bodyText) return cloneWithoutJsonBodyHeaders(request);
+        JSON.parse(bodyText);
+    } catch  {
+        return createBatchValidationResponse('Invalid JSON request body');
+    }
+    return request;
+}
+function toBatchItemError(id, status, message) {
+    return {
+        id,
+        status,
+        headers: [
+            [
+                'content-type',
+                'application/json; charset=utf-8'
+            ]
+        ],
+        body: encodeBatchText(JSON.stringify({
+            message
+        }))
+    };
+}
+class BatchItemTimeoutError extends Error {
+}
+function promiseWithTimeout(effect, timeoutMs, onTimeout) {
+    if (timeoutMs <= 0) return effect;
+    return new Promise((resolve, reject)=>{
+        const timer = setTimeout(()=>{
+            const error = new BatchItemTimeoutError(`Batch item timeout after ${String(timeoutMs)}ms`);
+            onTimeout?.(error);
+            reject(error);
+        }, timeoutMs);
+        effect.then((value)=>{
+            clearTimeout(timer);
+            resolve(value);
+        }, (error)=>{
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+async function mapWithConcurrency(items, concurrency, mapper) {
+    if (0 === items.length) return [];
+    const normalizedConcurrency = Math.max(1, concurrency);
+    const output = new Array(items.length);
+    let index = 0;
+    const workers = Array.from({
+        length: Math.min(normalizedConcurrency, items.length)
+    }, async ()=>{
+        while(true){
+            const currentIndex = index;
+            index += 1;
+            if (currentIndex >= items.length) return;
+            output[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    });
+    await Promise.all(workers);
+    return output;
+}
+export { toHeaderRecord } from "../../headers.mjs";
+export { BatchItemTimeoutError, createBatchValidationResponse, isBatchRequestPayload, mapWithConcurrency, normalizeBatchAllowedMethods, normalizeBatchPath, prepareJsonRequestBody, promiseWithTimeout, toBatchItemError };

package/dist/esm-node/effect/handler/definition.mjs

@@ -0,0 +1,59 @@
+import "node:module";
+import { registerValidatorAwareHandlerFactory } from "../entry-shape.mjs";
+import { mergeDataPlatformOptions } from "./envelope.mjs";
+import { createHttpApiHandler } from "./http.mjs";
+import { createRpcApiHandler } from "./rpc.mjs";
+function defineEffectBff(definition) {
+    const createHandler = registerValidatorAwareHandlerFactory((options)=>{
+        const rpcDefinition = definition.rpc;
+        let mergedRpcOptions = rpcDefinition;
+        if (rpcDefinition && options?.rpc) mergedRpcOptions = {
+            ...rpcDefinition,
+            ...options.rpc
+        };
+        return createHttpApiHandler({
+            api: definition.api,
+            layer: definition.layer,
+            openapi: options?.openapi,
+            rpc: mergedRpcOptions,
+            dataPlatform: mergeDataPlatformOptions(definition.dataPlatform, options?.dataPlatform),
+            interceptRequest: definition.interceptRequest,
+            validateRequest: options?.validateRequest
+        });
+    });
+    const client = createLoaderMaterializedClientPlaceholder();
+    return {
+        ...definition,
+        createHandler,
+        client
+    };
+}
+const LOADER_CLIENT_IGNORED_KEYS = new Set([
+    'then',
+    'catch',
+    'finally',
+    'toJSON',
+    '$$typeof'
+]);
+function createLoaderMaterializedClientPlaceholder() {
+    const explain = (property)=>{
+        throw new Error(`[BFF][Effect] client.${String(property)} is not available here: the typed client only exists when the API entry is imported through the "@api/index" transformed path (the BFF loader replaces it with generated client code). On the server, use HttpApiClient or call the Effect layer directly.`);
+    };
+    return new Proxy(Object.create(null), {
+        get (_target, property) {
+            if ('symbol' == typeof property || LOADER_CLIENT_IGNORED_KEYS.has(property)) return;
+            return explain(property);
+        }
+    });
+}
+function defineEffectRpcBff(definition) {
+    const createHandler = (options)=>createRpcApiHandler({
+            ...definition,
+            ...options
+        });
+    return {
+        ...definition,
+        createHandler
+    };
+}
+export { defineEffectBff, defineEffectRpcBff };