@bleedingdev/modern-js-plugin-bff 3.5.0-ultramodern.4 → 3.5.0-ultramodern.40

package/dist/esm-node/cli.mjs

@@ -1,34 +1,14 @@
 import "node:module";
 import { ApiRouter } from "@modern-js/bff-core";
-import { compile } from "@modern-js/server-utils";
-import { API_DIR, DEFAULT_API_PREFIX, SHARED_DIR, fs, normalizeOutputPath, resolveServerTsconfig } from "@modern-js/utils";
+import { normalizeOutputPath } from "@modern-js/utils";
 import path from "path";
-import clientGenerator from "./utils/clientGenerator.mjs";
-import pluginGenerator from "./utils/pluginGenerator.mjs";
-import runtimeGenerator from "./utils/runtimeGenerator.mjs";
+import { createCompressConfig } from "./cli/compress.mjs";
+import { createBffGenerator } from "./cli/generator.mjs";
+import { getPrimaryPrefix } from "./cli/prefix.mjs";
+import { isWatchableBffFile } from "./cli/watch.mjs";
 import { fileURLToPath as __rspack_fileURLToPath } from "node:url";
 import { dirname as __rspack_dirname } from "node:path";
 var __rspack_import_meta_dirname__ = __rspack_dirname(__rspack_fileURLToPath(import.meta.url));
-const RUNTIME_CREATE_REQUEST = '@modern-js/plugin-bff/client';
-const WATCHABLE_EXTENSIONS = [
-    '.ts',
-    '.tsx',
-    '.js',
-    '.jsx',
-    '.mts',
-    '.cts',
-    '.mjs',
-    '.cjs',
-    '.json'
-];
-const isWatchableBffFile = (filename)=>WATCHABLE_EXTENSIONS.some((ext)=>filename.endsWith(ext));
-const normalizePrefixList = (prefix)=>{
-    if (Array.isArray(prefix)) return prefix.filter(Boolean);
-    return [
-        prefix || DEFAULT_API_PREFIX
-    ];
-};
-const getPrimaryPrefix = (prefix)=>normalizePrefixList(prefix)[0] || DEFAULT_API_PREFIX;
 const bffPlugin = ()=>({
         name: '@modern-js/plugin-bff',
         setup: (api)=>{
@@ -40,106 +20,14 @@ const bffPlugin = ()=>({
                     bffRuntimeFramework: 'hono' === userRuntimeFramework ? 'hono' : 'effect'
                 });
             }
-            const compileApi = async ()=>{
-                const { appDirectory, distDirectory, apiDirectory, sharedDirectory, moduleType } = api.getAppContext();
-                const modernConfig = api.getNormalizedConfig();
-                const distDir = path.resolve(distDirectory);
-                const apiDir = apiDirectory || path.resolve(appDirectory, API_DIR);
-                const sharedDir = sharedDirectory || path.resolve(appDirectory, SHARED_DIR);
-                const tsconfigPath = resolveServerTsconfig(appDirectory, modernConfig?.server?.tsconfigPath);
-                const sourceDirs = [];
-                if (await fs.pathExists(apiDir)) sourceDirs.push(apiDir);
-                if (await fs.pathExists(sharedDir)) sourceDirs.push(sharedDir);
-                const { alias } = modernConfig.source;
-                const { alias: resolveAlias } = modernConfig.resolve;
-                if (sourceDirs.length > 0) {
-                    const combinedAlias = [].concat(alias ?? []).concat(resolveAlias ?? []);
-                    await compile(appDirectory, {
-                        alias: combinedAlias
-                    }, {
-                        sourceDirs,
-                        distDir,
-                        tsconfigPath,
-                        moduleType,
-                        throwErrorInsteadOfExit: true
-                    });
-                }
-            };
-            const generator = async ()=>{
-                const { appDirectory, apiDirectory, lambdaDirectory, port, bffRuntimeFramework } = api.getAppContext();
-                const modernConfig = api.getNormalizedConfig();
-                const relativeDistPath = modernConfig?.output?.distPath?.root || 'dist';
-                const { bff } = modernConfig || {};
-                const prefix = getPrimaryPrefix(bff?.prefix);
-                const httpMethodDecider = bff?.httpMethodDecider;
-                const apiRouter = new ApiRouter({
-                    apiDir: apiDirectory,
-                    appDir: appDirectory,
-                    lambdaDir: lambdaDirectory,
-                    prefix,
-                    httpMethodDecider,
-                    isBuild: true
-                });
-                const lambdaDir = apiRouter.getLambdaDir();
-                const existLambda = apiRouter.isExistLambda();
-                const runtime = bff?.runtimeCreateRequest || RUNTIME_CREATE_REQUEST;
-                const relativeApiPath = path.relative(appDirectory, apiDirectory);
-                const relativeLambdaPath = path.relative(appDirectory, lambdaDir);
-                await pluginGenerator({
-                    prefix,
-                    appDirectory,
-                    relativeDistPath,
-                    relativeApiPath,
-                    relativeLambdaPath,
-                    runtimeFramework: 'hono' === bffRuntimeFramework ? 'hono' : 'effect'
-                });
-                await clientGenerator({
-                    prefix,
-                    appDir: appDirectory,
-                    apiDir: apiDirectory,
-                    lambdaDir,
-                    existLambda,
-                    port,
-                    requestCreator: bff?.requestCreator,
-                    httpMethodDecider,
-                    relativeDistPath,
-                    relativeApiPath,
-                    bffRuntimeFramework,
-                    effectEntry: bff?.effect?.entry,
-                    effectDataPlatformBatch: bff?.effect?.dataPlatform?.batch
-                });
-                await runtimeGenerator({
-                    runtime,
-                    appDirectory,
-                    relativeDistPath
-                });
-            };
-            const handleCrossProjectInvocation = async (isBuild = false)=>{
-                const { bff } = api.getNormalizedConfig();
-                if (bff?.crossProject) {
-                    if (!isBuild) await compileApi();
-                    await generator();
-                }
-            };
+            const { compileApi, handleCrossProjectInvocation } = createBffGenerator(api);
             const isHono = ()=>{
                 const { bffRuntimeFramework } = api.getAppContext();
                 return 'hono' === bffRuntimeFramework;
             };
-            const createCompressConfig = (devServer, prefix)=>{
-                if (!devServer || 'object' != typeof devServer || Array.isArray(devServer)) return;
-                const { compress } = devServer;
-                if (void 0 === compress || true === compress) {
-                    const prefixes = normalizePrefixList(prefix);
-                    return {
-                        filter: (req)=>!prefixes.some((item)=>req.url?.includes(item))
-                    };
-                }
-                if (false === compress) return false;
-                return compress;
-            };
             api.config(async ()=>{
                 const devServer = api.getConfig()?.tools?.devServer;
-                const prefix = api.getConfig()?.bff?.prefix || DEFAULT_API_PREFIX;
+                const prefix = api.getConfig()?.bff?.prefix;
                 const compress = createCompressConfig(devServer, prefix);
                 return {
                     tools: {
@@ -244,6 +132,4 @@ const bffPlugin = ()=>({
             });
         }
     });
-const cli = bffPlugin;
-export default cli;
 export { bffPlugin };

package/dist/esm-node/runtime/data-platform/batch/queue.mjs

@@ -0,0 +1,247 @@
+import "node:module";
+import { stableStringify } from "../codec.mjs";
+import { DEFAULT_DATA_BATCH_HEADER } from "../types.mjs";
+import { createBatchId, measureTextBytes, normalizeMethod, shouldBatchRequest, toHeaderRecord, toRequestBody } from "./request.mjs";
+import { isBatchResponsePayload, parseResponseLikeCreateRequest } from "./response.mjs";
+import { emitDataBatchTransportEvent } from "./telemetry.mjs";
+import { normalizeBatchEndpoint, toAbsoluteUrl } from "./url.mjs";
+function ensureBucket(buckets, endpoint) {
+    const existing = buckets.get(endpoint);
+    if (existing) return existing;
+    const next = {
+        items: [],
+        bytes: 0,
+        timer: null,
+        flushing: false
+    };
+    buckets.set(endpoint, next);
+    return next;
+}
+function createBatchTransportQueue({ options, baseFetch }) {
+    const flushIntervalMs = Math.max(0, options.flushIntervalMs ?? 8);
+    const maxBatchSize = Math.max(1, options.maxBatchSize ?? 16);
+    const maxBatchBytes = Math.max(1024, options.maxBatchBytes ?? 65536);
+    const requestTimeoutMs = options.requestTimeoutMs;
+    const allowedMethods = new Set((options.allowedMethods && options.allowedMethods.length > 0 ? options.allowedMethods : [
+        'GET'
+    ]).map((method)=>method.toUpperCase()));
+    const onEvent = options.onEvent;
+    const buckets = new Map();
+    const pendingByKey = new Map();
+    const disabledEndpoints = new Set();
+    let nextItemId = 0;
+    const runSingle = async (request)=>{
+        const response = await baseFetch(request.requestUrl, request.requestInit);
+        return parseResponseLikeCreateRequest(response);
+    };
+    const settleRequests = async (items, runner)=>{
+        await Promise.all(items.map(async (item)=>{
+            try {
+                const value = await runner(item);
+                item.resolve(value);
+            } catch (error) {
+                item.reject(error);
+            } finally{
+                pendingByKey.delete(item.key);
+            }
+        }));
+    };
+    const flushBucket = async (endpoint)=>{
+        const bucket = buckets.get(endpoint);
+        if (!bucket || bucket.flushing) return;
+        if (bucket.timer) {
+            clearTimeout(bucket.timer);
+            bucket.timer = null;
+        }
+        if (0 === bucket.items.length) return;
+        bucket.flushing = true;
+        const items = bucket.items;
+        bucket.items = [];
+        bucket.bytes = 0;
+        if (1 === items.length || disabledEndpoints.has(endpoint)) {
+            emitDataBatchTransportEvent(onEvent, {
+                type: disabledEndpoints.has(endpoint) ? 'fallback' : 'flush',
+                endpoint,
+                size: items.length,
+                reason: disabledEndpoints.has(endpoint) ? 'batch-disabled' : void 0
+            });
+            await settleRequests(items, runSingle);
+            bucket.flushing = false;
+            if (bucket.items.length > 0 && !bucket.timer) flushBucket(endpoint);
+            return;
+        }
+        const batchId = createBatchId();
+        const payload = {
+            protocolVersion: 1,
+            batchId,
+            sentAt: Date.now(),
+            items: items.map((item)=>item.item)
+        };
+        emitDataBatchTransportEvent(onEvent, {
+            type: 'flush',
+            endpoint,
+            batchId,
+            size: items.length
+        });
+        const payloadJson = JSON.stringify(payload);
+        const traceparent = items.find((item)=>'string' == typeof item.item.headers?.traceparent)?.item.headers?.traceparent || void 0;
+        const requestInit = {
+            method: 'POST',
+            headers: {
+                accept: 'application/json, */*;q=0.8',
+                'content-type': 'application/json; charset=utf-8',
+                [DEFAULT_DATA_BATCH_HEADER]: '1',
+                ...traceparent ? {
+                    traceparent
+                } : {}
+            },
+            body: payloadJson
+        };
+        let timeoutHandle = null;
+        try {
+            const controller = requestTimeoutMs && requestTimeoutMs > 0 ? new AbortController() : void 0;
+            if (controller) {
+                requestInit.signal = controller.signal;
+                timeoutHandle = setTimeout(()=>{
+                    controller.abort();
+                    emitDataBatchTransportEvent(onEvent, {
+                        type: 'fallback',
+                        endpoint,
+                        batchId,
+                        size: items.length,
+                        reason: 'batch-timeout'
+                    });
+                }, requestTimeoutMs);
+            }
+            const response = await baseFetch(endpoint, requestInit);
+            if (!response.ok) {
+                if (404 === response.status || 405 === response.status) {
+                    disabledEndpoints.add(endpoint);
+                    emitDataBatchTransportEvent(onEvent, {
+                        type: 'disable',
+                        endpoint,
+                        batchId,
+                        reason: `batch-endpoint-unavailable-${String(response.status)}`
+                    });
+                } else emitDataBatchTransportEvent(onEvent, {
+                    type: 'fallback',
+                    endpoint,
+                    batchId,
+                    size: items.length,
+                    reason: `batch-response-${String(response.status)}`
+                });
+                await settleRequests(items, runSingle);
+                bucket.flushing = false;
+                return;
+            }
+            const result = await response.json();
+            if (!isBatchResponsePayload(result)) {
+                emitDataBatchTransportEvent(onEvent, {
+                    type: 'fallback',
+                    endpoint,
+                    batchId,
+                    size: items.length,
+                    reason: 'invalid-batch-response'
+                });
+                await settleRequests(items, runSingle);
+                bucket.flushing = false;
+                return;
+            }
+            const itemMap = new Map();
+            for (const item of result.items)itemMap.set(item.id, item);
+            await settleRequests(items, async (request)=>{
+                const resultItem = itemMap.get(request.item.id);
+                if (!resultItem) return runSingle(request);
+                const reconstructedResponse = new Response(resultItem.body ?? '', {
+                    status: resultItem.status,
+                    headers: resultItem.headers
+                });
+                return parseResponseLikeCreateRequest(reconstructedResponse);
+            });
+        } catch (error) {
+            emitDataBatchTransportEvent(onEvent, {
+                type: 'fallback',
+                endpoint,
+                batchId,
+                size: items.length,
+                reason: 'batch-transport-error'
+            });
+            await settleRequests(items, runSingle);
+        } finally{
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            bucket.flushing = false;
+            if (bucket.items.length > 0 && !bucket.timer) flushBucket(endpoint);
+        }
+    };
+    return (input, init)=>{
+        const requestUrl = toAbsoluteUrl(input);
+        const batchEndpointUrl = normalizeBatchEndpoint(requestUrl, options.endpoint);
+        const endpoint = batchEndpointUrl.toString();
+        const method = normalizeMethod(init?.method);
+        const body = toRequestBody(init?.body ?? null);
+        const headers = toHeaderRecord(init?.headers);
+        const normalizedInit = {
+            ...init,
+            method,
+            headers,
+            body
+        };
+        if (disabledEndpoints.has(endpoint) || !shouldBatchRequest({
+            method,
+            body,
+            headers,
+            allowedMethods,
+            batchEndpoint: endpoint,
+            requestUrl
+        })) return baseFetch(requestUrl.toString(), normalizedInit).then(parseResponseLikeCreateRequest);
+        const itemId = `${Date.now().toString(36)}_${nextItemId.toString(36)}_${Math.random().toString(16).slice(2, 8)}`;
+        nextItemId += 1;
+        const item = {
+            id: itemId,
+            path: `${requestUrl.pathname}${requestUrl.search}`,
+            method,
+            headers,
+            ...body ? {
+                body
+            } : {}
+        };
+        const key = stableStringify({
+            endpoint,
+            path: item.path,
+            method: item.method,
+            headers: item.headers,
+            body: item.body ?? null
+        });
+        const existing = pendingByKey.get(key);
+        if (existing) return existing;
+        const size = measureTextBytes(stableStringify(item));
+        const promise = new Promise((resolve, reject)=>{
+            const bucket = ensureBucket(buckets, endpoint);
+            const queued = {
+                key,
+                endpoint,
+                requestUrl: requestUrl.toString(),
+                requestInit: normalizedInit,
+                item,
+                size,
+                resolve,
+                reject
+            };
+            bucket.items.push(queued);
+            bucket.bytes += size;
+            emitDataBatchTransportEvent(onEvent, {
+                type: 'enqueue',
+                endpoint,
+                size: bucket.items.length
+            });
+            if (bucket.items.length >= maxBatchSize || bucket.bytes >= maxBatchBytes) return void flushBucket(endpoint);
+            if (!bucket.timer) bucket.timer = setTimeout(()=>{
+                bucket.timer = null;
+                flushBucket(endpoint);
+            }, flushIntervalMs);
+        });
+        pendingByKey.set(key, promise);
+        return promise;
+    };
+}
+export { createBatchTransportQueue };

package/dist/esm-node/runtime/data-platform/batch/request.mjs

@@ -0,0 +1,46 @@
+import "node:module";
+import { DEFAULT_DATA_BATCH_HEADER } from "../types.mjs";
+function toHeaderRecord(headers) {
+    if (!headers) return {};
+    if (headers instanceof Headers) {
+        const next = {};
+        headers.forEach((value, key)=>{
+            next[key.toLowerCase()] = value;
+        });
+        return next;
+    }
+    if (Array.isArray(headers)) return headers.reduce((acc, [key, value])=>{
+        acc[String(key).toLowerCase()] = String(value);
+        return acc;
+    }, {});
+    return Object.entries(headers).reduce((acc, [key, value])=>{
+        if (void 0 === value) return acc;
+        acc[String(key).toLowerCase()] = Array.isArray(value) ? value.join(', ') : String(value);
+        return acc;
+    }, {});
+}
+function measureTextBytes(value) {
+    if ("u" > typeof TextEncoder) return new TextEncoder().encode(value).length;
+    if ("u" > typeof Buffer) return Buffer.byteLength(value);
+    return value.length;
+}
+function createBatchId() {
+    const now = Date.now().toString(36);
+    const random = Math.random().toString(16).slice(2, 10);
+    return `batch_${now}_${random}`;
+}
+function normalizeMethod(method) {
+    return (method || 'GET').toUpperCase();
+}
+function toRequestBody(initBody) {
+    if ('string' == typeof initBody) return initBody;
+    if ("u" > typeof URLSearchParams && initBody instanceof URLSearchParams) return initBody.toString();
+}
+function shouldBatchRequest(input) {
+    if (input.requestUrl.href === input.batchEndpoint) return false;
+    if ('off' === input.headers[DEFAULT_DATA_BATCH_HEADER]) return false;
+    if (!input.allowedMethods.has(input.method)) return false;
+    if (void 0 !== input.body) return false;
+    return true;
+}
+export { createBatchId, measureTextBytes, normalizeMethod, shouldBatchRequest, toHeaderRecord, toRequestBody };

package/dist/esm-node/runtime/data-platform/batch/response.mjs

@@ -0,0 +1,24 @@
+import "node:module";
+import { isPlainObject } from "../codec.mjs";
+function isBatchResponseItem(value) {
+    return isPlainObject(value) && 'string' == typeof value.id && 'number' == typeof value.status;
+}
+function isBatchResponsePayload(value) {
+    return isPlainObject(value) && 1 === value.protocolVersion && 'string' == typeof value.batchId && 'number' == typeof value.receivedAt && Array.isArray(value.items) && value.items.every((item)=>isBatchResponseItem(item));
+}
+async function parseResponseLikeCreateRequest(response) {
+    const contentType = (response.headers.get('content-type') || '').toLowerCase();
+    if (!response.ok) {
+        let data = null;
+        data = contentType.includes('application/json') ? await response.json() : await response.text();
+        response.data = data;
+        throw response;
+    }
+    if (contentType.includes('application/json') || contentType.includes('text/json')) return response.json();
+    if (contentType.includes('text/html') || contentType.includes('text/plain')) return response.text();
+    if (contentType.includes('application/x-www-form-urlencoded') || contentType.includes('multipart/form-data')) return response.formData();
+    if (contentType.includes('application/octet-stream')) return response.arrayBuffer();
+    if (contentType.includes('image/png')) return response;
+    return response.text();
+}
+export { isBatchResponsePayload, parseResponseLikeCreateRequest };

package/dist/esm-node/runtime/data-platform/batch/telemetry.mjs

@@ -0,0 +1,24 @@
+import "node:module";
+import { trace } from "@opentelemetry/api";
+const DATA_BATCH_TRANSPORT_OTEL_EVENT = 'modernjs.data.batch';
+function createDataBatchTransportTelemetryAttributes(event) {
+    return {
+        'modernjs.data.batch.type': event.type,
+        'modernjs.data.batch.endpoint': event.endpoint,
+        'modernjs.data.batch.degraded': 'fallback' === event.type || 'disable' === event.type,
+        ...event.batchId ? {
+            'modernjs.data.batch.id': event.batchId
+        } : {},
+        ...'number' == typeof event.size ? {
+            'modernjs.data.batch.size': event.size
+        } : {},
+        ...event.reason ? {
+            'modernjs.data.batch.reason': event.reason
+        } : {}
+    };
+}
+function emitDataBatchTransportEvent(onEvent, event) {
+    onEvent?.(event);
+    trace.getActiveSpan()?.addEvent(DATA_BATCH_TRANSPORT_OTEL_EVENT, createDataBatchTransportTelemetryAttributes(event));
+}
+export { DATA_BATCH_TRANSPORT_OTEL_EVENT, createDataBatchTransportTelemetryAttributes, emitDataBatchTransportEvent };

package/dist/esm-node/runtime/data-platform/batch/url.mjs

@@ -0,0 +1,26 @@
+import "node:module";
+import { DEFAULT_DATA_BATCH_ENDPOINT } from "../types.mjs";
+function resolveRuntimeOrigin() {
+    if ("u" > typeof window && window.location && 'string' == typeof window.location.origin && window.location.origin) return window.location.origin;
+    if ("u" > typeof globalThis && globalThis.location && 'string' == typeof globalThis.location?.origin) return globalThis.location.origin;
+    return 'http://localhost';
+}
+function toAbsoluteUrl(input) {
+    if (input instanceof URL) return input;
+    if ("u" > typeof Request && input instanceof Request) return new URL(input.url);
+    const value = String(input);
+    try {
+        return new URL(value);
+    } catch  {
+        return new URL(value, resolveRuntimeOrigin());
+    }
+}
+function normalizeBatchEndpoint(requestUrl, endpoint) {
+    const value = endpoint || DEFAULT_DATA_BATCH_ENDPOINT;
+    try {
+        return new URL(value);
+    } catch  {
+        return new URL(value, requestUrl.origin);
+    }
+}
+export { normalizeBatchEndpoint, resolveRuntimeOrigin, toAbsoluteUrl };

package/dist/esm-node/runtime/data-platform/batch-transport.mjs

@@ -0,0 +1,13 @@
+import "node:module";
+import { createBatchTransportQueue } from "./batch/queue.mjs";
+function createDataBatchTransport(options = {}) {
+    const fallbackFetch = 'function' == typeof fetch ? fetch.bind(globalThis) : void 0;
+    const baseFetch = options.fetch || fallbackFetch;
+    if (!baseFetch) throw new Error('createDataBatchTransport requires a fetch implementation');
+    return createBatchTransportQueue({
+        options,
+        baseFetch
+    });
+}
+export { DATA_BATCH_TRANSPORT_OTEL_EVENT, createDataBatchTransportTelemetryAttributes, emitDataBatchTransportEvent } from "./batch/telemetry.mjs";
+export { createDataBatchTransport };

package/dist/esm-node/runtime/data-platform/codec.mjs

@@ -0,0 +1,91 @@
+import "node:module";
+function isPlainObject(value) {
+    if ('object' != typeof value || null === value || Array.isArray(value)) return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || null === proto;
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) return value.map((item)=>canonicalize(item));
+    if (isPlainObject(value)) return Object.keys(value).sort().reduce((acc, key)=>{
+        acc[key] = canonicalize(value[key]);
+        return acc;
+    }, {});
+    return value;
+}
+function stableStringify(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function encodeRequestEnvelopeHeader(envelope) {
+    return encodeURIComponent(stableStringify(envelope));
+}
+function isRequestEnvelopeShape(value) {
+    if (!isPlainObject(value)) return false;
+    return 1 === value.protocolVersion && 'string' == typeof value.operationId && 'string' == typeof value.appNamespace && 'string' == typeof value.origin && 'string' == typeof value.scopeKey && 'string' == typeof value.inputHash && 'number' == typeof value.timestamp;
+}
+function decodeRequestEnvelopeHeader(value) {
+    try {
+        const decoded = decodeURIComponent(value);
+        const parsed = JSON.parse(decoded);
+        if (!isRequestEnvelopeShape(parsed)) return null;
+        return parsed;
+    } catch  {
+        return null;
+    }
+}
+function hashString(value) {
+    let hash = 0x811c9dc5;
+    for(let index = 0; index < value.length; index++){
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+function sanitizeSegment(segment) {
+    const normalized = segment.trim().replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return normalized.length > 0 ? normalized : 'unknown';
+}
+function normalizeOrigin(origin) {
+    const normalized = origin.trim();
+    try {
+        const url = new URL(normalized);
+        return `${url.protocol}//${url.host}`.toLowerCase();
+    } catch  {
+        return normalized.toLowerCase();
+    }
+}
+function normalizeOperationDescriptor(input) {
+    return {
+        appNamespace: sanitizeSegment(input.appNamespace),
+        apiId: sanitizeSegment(input.apiId),
+        group: sanitizeSegment(input.group),
+        endpoint: sanitizeSegment(input.endpoint),
+        schemaHash: input.schemaHash || null,
+        version: input.version ?? 1
+    };
+}
+function createOperationId(input) {
+    const descriptor = normalizeOperationDescriptor(input);
+    const readable = `${descriptor.appNamespace}.${descriptor.apiId}.${descriptor.group}.${descriptor.endpoint}.v${String(descriptor.version)}`;
+    return `${readable}:${hashString(stableStringify(descriptor))}`;
+}
+function buildScopeKey(scope) {
+    const canonical = {
+        appNamespace: sanitizeSegment(scope.appNamespace),
+        origin: normalizeOrigin(scope.origin),
+        tenantId: scope.tenantId ?? null,
+        userId: scope.userId ?? null,
+        sessionId: scope.sessionId ?? null
+    };
+    return `${canonical.appNamespace}:${hashString(stableStringify(canonical))}`;
+}
+function buildQueryKey(input) {
+    const canonical = {
+        operationId: input.operationId,
+        scopeKey: input.scopeKey,
+        requestMode: input.requestMode ?? 'cache-first',
+        requestInput: input.requestInput ?? null,
+        selectionPlan: input.selectionPlan ?? null
+    };
+    return `${input.operationId}:${hashString(stableStringify(canonical))}`;
+}
+export { buildQueryKey, buildScopeKey, createOperationId, decodeRequestEnvelopeHeader, encodeRequestEnvelopeHeader, hashString, isPlainObject, normalizeOrigin, sanitizeSegment, stableStringify };