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

package/src/data-platform/batch/request.ts

@@ -0,0 +1,130 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import type { DataBatchBody } from '../types';
+import { DEFAULT_DATA_BATCH_HEADER } from '../types';
+import { encodeBatchBody } from './protocol';
+
+export function toHeaderRecord(
+  headers: HeadersInit | undefined,
+): Record<string, string> {
+  if (!headers) {
+    return {};
+  }
+
+  if (headers instanceof Headers) {
+    const next: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      next[key.toLowerCase()] = value;
+    });
+    return next;
+  }
+
+  if (Array.isArray(headers)) {
+    return headers.reduce<Record<string, string>>((acc, [key, value]) => {
+      acc[String(key).toLowerCase()] = String(value);
+      return acc;
+    }, {});
+  }
+
+  return Object.entries(headers).reduce<Record<string, string>>(
+    (acc, [key, value]) => {
+      if (typeof value === 'undefined') {
+        return acc;
+      }
+      acc[String(key).toLowerCase()] = Array.isArray(value)
+        ? value.join(', ')
+        : String(value);
+      return acc;
+    },
+    {},
+  );
+}
+
+export function measureTextBytes(value: string) {
+  if (typeof TextEncoder !== 'undefined') {
+    return new TextEncoder().encode(value).length;
+  }
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.byteLength(value);
+  }
+  return value.length;
+}
+
+export function createBatchId() {
+  const now = Date.now().toString(36);
+  const random = Math.random().toString(16).slice(2, 10);
+  return `batch_${now}_${random}`;
+}
+
+export function normalizeMethod(method: string | undefined) {
+  return (method || 'GET').toUpperCase();
+}
+
+export type PreparedBatchRequestBody = {
+  body: DataBatchBody | undefined;
+  inferredContentType: string | undefined;
+  batchable: boolean;
+};
+
+export async function toRequestBody(
+  initBody: BodyInit | null | undefined,
+): Promise<PreparedBatchRequestBody> {
+  if (typeof initBody === 'undefined' || initBody === null) {
+    return {
+      body: undefined,
+      inferredContentType: undefined,
+      batchable: true,
+    };
+  }
+  if (
+    typeof ReadableStream !== 'undefined' &&
+    initBody instanceof ReadableStream
+  ) {
+    return {
+      body: undefined,
+      inferredContentType: undefined,
+      batchable: false,
+    };
+  }
+
+  try {
+    const response = new Response(initBody);
+    return {
+      body: encodeBatchBody(new Uint8Array(await response.arrayBuffer())),
+      inferredContentType: response.headers.get('content-type') || undefined,
+      batchable: true,
+    };
+  } catch {
+    return {
+      body: undefined,
+      inferredContentType: undefined,
+      batchable: false,
+    };
+  }
+}
+
+export function shouldBatchRequest(input: {
+  method: string;
+  body: string | undefined;
+  headers: Record<string, string>;
+  allowedMethods: Set<string>;
+  batchEndpoint: string;
+  requestUrl: URL;
+}) {
+  if (input.requestUrl.href === input.batchEndpoint) {
+    return false;
+  }
+
+  if (input.headers[DEFAULT_DATA_BATCH_HEADER] === 'off') {
+    return false;
+  }
+
+  if (!input.allowedMethods.has(input.method)) {
+    return false;
+  }
+
+  if (input.body !== undefined) {
+    return false;
+  }
+
+  return true;
+}

package/src/data-platform/batch/response.ts

@@ -0,0 +1,74 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { isPlainObject } from '../codec';
+import type { DataBatchResponseItem, DataBatchResponsePayload } from '../types';
+import { isBatchBody, isBatchHeaderList, isNullBodyStatus } from './protocol';
+
+function isBatchResponseItem(value: unknown): value is DataBatchResponseItem {
+  return (
+    isPlainObject(value) &&
+    typeof value.id === 'string' &&
+    typeof value.status === 'number' &&
+    (typeof value.headers === 'undefined' ||
+      isBatchHeaderList(value.headers)) &&
+    (typeof value.body === 'undefined' || isBatchBody(value.body)) &&
+    !(isNullBodyStatus(value.status) && typeof value.body !== 'undefined')
+  );
+}
+
+export function isBatchResponsePayload(
+  value: unknown,
+): value is DataBatchResponsePayload {
+  return (
+    isPlainObject(value) &&
+    value.protocolVersion === 2 &&
+    typeof value.batchId === 'string' &&
+    typeof value.receivedAt === 'number' &&
+    Array.isArray(value.items) &&
+    value.items.every(item => isBatchResponseItem(item))
+  );
+}
+
+export async function parseResponseLikeCreateRequest(response: Response) {
+  const contentType = (
+    response.headers.get('content-type') || ''
+  ).toLowerCase();
+
+  if (!response.ok) {
+    let data: unknown = null;
+    if (contentType.includes('application/json')) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+    (response as Response & { data?: unknown }).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();
+}

package/src/data-platform/batch/telemetry.ts

@@ -0,0 +1,47 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { trace } from '@opentelemetry/api';
+
+import type {
+  DataBatchTransportEvent,
+  DataBatchTransportTelemetryAttributes,
+} from '../types';
+
+export const DATA_BATCH_TRANSPORT_OTEL_EVENT = 'modernjs.data.batch';
+
+export function createDataBatchTransportTelemetryAttributes(
+  event: DataBatchTransportEvent,
+): DataBatchTransportTelemetryAttributes {
+  return {
+    'modernjs.data.batch.type': event.type,
+    'modernjs.data.batch.endpoint': event.endpoint,
+    'modernjs.data.batch.degraded':
+      event.type === 'fallback' || event.type === 'disable',
+    ...(event.batchId ? { 'modernjs.data.batch.id': event.batchId } : {}),
+    ...(typeof event.size === 'number'
+      ? { 'modernjs.data.batch.size': event.size }
+      : {}),
+    ...(event.reason ? { 'modernjs.data.batch.reason': event.reason } : {}),
+  };
+}
+
+export function emitDataBatchTransportEvent(
+  onEvent: ((event: DataBatchTransportEvent) => void) | undefined,
+  event: DataBatchTransportEvent,
+) {
+  try {
+    onEvent?.(event);
+  } catch {
+    // Observability callbacks must not affect transport state or settlement.
+  }
+
+  try {
+    trace
+      .getActiveSpan()
+      ?.addEvent(
+        DATA_BATCH_TRANSPORT_OTEL_EVENT,
+        createDataBatchTransportTelemetryAttributes(event),
+      );
+  } catch {
+    // OpenTelemetry exporters are observational and must remain non-fatal.
+  }
+}

package/src/data-platform/batch/url.ts

@@ -0,0 +1,54 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import type { DataTransportRequestInfo } from '../types';
+import { DEFAULT_DATA_BATCH_ENDPOINT } from '../types';
+
+export function resolveRuntimeOrigin() {
+  if (
+    typeof window !== 'undefined' &&
+    window.location &&
+    typeof window.location.origin === 'string' &&
+    window.location.origin
+  ) {
+    return window.location.origin;
+  }
+
+  if (
+    typeof globalThis !== 'undefined' &&
+    (globalThis as { location?: { origin?: string } }).location &&
+    typeof (globalThis as { location?: { origin?: string } }).location
+      ?.origin === 'string'
+  ) {
+    return (globalThis as { location?: { origin?: string } }).location!.origin!;
+  }
+
+  return 'http://localhost';
+}
+
+export function toAbsoluteUrl(input: DataTransportRequestInfo) {
+  if (input instanceof URL) {
+    return input;
+  }
+
+  if (typeof Request !== 'undefined' && input instanceof Request) {
+    return new URL(input.url);
+  }
+
+  const value = String(input);
+  try {
+    return new URL(value);
+  } catch {
+    return new URL(value, resolveRuntimeOrigin());
+  }
+}
+
+export function normalizeBatchEndpoint(
+  requestUrl: URL,
+  endpoint: string | undefined,
+): URL {
+  const value = endpoint || DEFAULT_DATA_BATCH_ENDPOINT;
+  try {
+    return new URL(value);
+  } catch {
+    return new URL(value, requestUrl.origin);
+  }
+}

package/src/data-platform/batch-transport.ts

@@ -0,0 +1,22 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+
+import { createBatchTransportQueue } from './batch/queue';
+import type { DataBatchTransportOptions } from './types';
+
+export {
+  createDataBatchTransportTelemetryAttributes,
+  DATA_BATCH_TRANSPORT_OTEL_EVENT,
+  emitDataBatchTransportEvent,
+} from './batch/telemetry';
+
+export function createDataBatchTransport(
+  options: DataBatchTransportOptions = {},
+) {
+  const fallbackFetch =
+    typeof fetch === 'function' ? fetch.bind(globalThis) : undefined;
+  const baseFetch = options.fetch || fallbackFetch;
+  if (!baseFetch) {
+    throw new Error('createDataBatchTransport requires a fetch implementation');
+  }
+  return createBatchTransportQueue({ options, baseFetch });
+}

package/src/data-platform/codec.ts

@@ -0,0 +1,145 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import type {
+  CacheScope,
+  DataRequestMode,
+  OperationDescriptor,
+  RequestEnvelope,
+  SelectionPlan,
+} from './types';
+
+export function isPlainObject(
+  value: unknown,
+): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(item => canonicalize(item));
+  }
+
+  if (isPlainObject(value)) {
+    return Object.keys(value)
+      .sort()
+      .reduce<Record<string, unknown>>((acc, key) => {
+        acc[key] = canonicalize(value[key]);
+        return acc;
+      }, {});
+  }
+
+  return value;
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function encodeRequestEnvelopeHeader(envelope: RequestEnvelope): string {
+  return encodeURIComponent(stableStringify(envelope));
+}
+
+function isRequestEnvelopeShape(value: unknown): value is RequestEnvelope {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+
+  return (
+    value.protocolVersion === 1 &&
+    typeof value.operationId === 'string' &&
+    typeof value.appNamespace === 'string' &&
+    typeof value.origin === 'string' &&
+    typeof value.scopeKey === 'string' &&
+    typeof value.inputHash === 'string' &&
+    typeof value.timestamp === 'number'
+  );
+}
+
+export function decodeRequestEnvelopeHeader(
+  value: string,
+): RequestEnvelope | null {
+  try {
+    const decoded = decodeURIComponent(value);
+    const parsed = JSON.parse(decoded);
+    if (!isRequestEnvelopeShape(parsed)) {
+      return null;
+    }
+
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function hashString(value: string): string {
+  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');
+}
+
+export function sanitizeSegment(segment: string): string {
+  const normalized = segment.trim().replace(/[^a-zA-Z0-9_-]+/g, '_');
+  return normalized.length > 0 ? normalized : 'unknown';
+}
+
+export function normalizeOrigin(origin: string): string {
+  const normalized = origin.trim();
+  try {
+    const url = new URL(normalized);
+    return `${url.protocol}//${url.host}`.toLowerCase();
+  } catch {
+    return normalized.toLowerCase();
+  }
+}
+
+function normalizeOperationDescriptor(input: OperationDescriptor) {
+  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,
+  };
+}
+
+export function createOperationId(input: OperationDescriptor): string {
+  const descriptor = normalizeOperationDescriptor(input);
+  const readable = `${descriptor.appNamespace}.${descriptor.apiId}.${descriptor.group}.${descriptor.endpoint}.v${String(descriptor.version)}`;
+  return `${readable}:${hashString(stableStringify(descriptor))}`;
+}
+
+export function buildScopeKey(scope: CacheScope): string {
+  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))}`;
+}
+
+export function buildQueryKey(input: {
+  operationId: string;
+  scopeKey: string;
+  requestMode?: DataRequestMode;
+  requestInput?: unknown;
+  selectionPlan?: SelectionPlan;
+}): string {
+  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))}`;
+}

package/src/data-platform/index.ts

@@ -0,0 +1,63 @@
+export { measureTextBytes, normalizeMethod } from './batch/request';
+export {
+  createDataBatchTransport,
+  createDataBatchTransportTelemetryAttributes,
+  DATA_BATCH_TRANSPORT_OTEL_EVENT,
+  emitDataBatchTransportEvent,
+} from './batch-transport';
+export {
+  buildQueryKey,
+  buildScopeKey,
+  createOperationId,
+  decodeRequestEnvelopeHeader,
+  encodeRequestEnvelopeHeader,
+  isPlainObject,
+  normalizeOrigin,
+  stableStringify,
+} from './codec';
+export {
+  createInvalidationEvent,
+  shouldApplyInvalidation,
+} from './invalidation';
+export {
+  deriveChildTraceContext,
+  formatTraceparentHeader,
+  parseTraceparentHeader,
+} from './trace';
+export type {
+  CacheScope,
+  DataBatchBody,
+  DataBatchHeader,
+  DataBatchRequestItem,
+  DataBatchRequestPayload,
+  DataBatchResponseItem,
+  DataBatchResponsePayload,
+  DataBatchTransportEvent,
+  DataBatchTransportOptions,
+  DataBatchTransportTelemetryAttributes,
+  DataMutationMode,
+  DataRequestMode,
+  HydrationEnvelope,
+  HydrationEnvelopeValidationOptions,
+  InvalidationEvent,
+  InvalidationSubscriber,
+  OperationDescriptor,
+  RequestEnvelope,
+  RequestEnvelopeValidationOptions,
+  SelectionPlan,
+  SelectionPlanValidationOptions,
+  SelectionPlanValidationResult,
+  TraceContext,
+} from './types';
+export {
+  DEFAULT_DATA_BATCH_ENDPOINT,
+  DEFAULT_DATA_BATCH_HEADER,
+  DEFAULT_DATA_ENVELOPE_HEADER,
+} from './types';
+export {
+  createHydrationEnvelope,
+  createRequestEnvelope,
+  validateHydrationEnvelope,
+  validateRequestEnvelope,
+  validateSelectionPlan,
+} from './validation';

package/src/data-platform/invalidation.ts

@@ -0,0 +1,57 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { buildScopeKey, createOperationId, sanitizeSegment } from './codec';
+import type {
+  CacheScope,
+  InvalidationEvent,
+  InvalidationSubscriber,
+  OperationDescriptor,
+} from './types';
+
+export function createInvalidationEvent(input: {
+  sourceOperation: OperationDescriptor;
+  sourceScope: CacheScope;
+  targetNamespaces?: string[];
+  targetOperations?: OperationDescriptor[];
+}): InvalidationEvent {
+  return {
+    sourceNamespace: sanitizeSegment(input.sourceOperation.appNamespace),
+    sourceOperationId: createOperationId(input.sourceOperation),
+    scopeKey: buildScopeKey(input.sourceScope),
+    targetNamespaces: input.targetNamespaces?.map(namespace =>
+      sanitizeSegment(namespace),
+    ),
+    targetOperationIds: input.targetOperations?.map(operation =>
+      createOperationId(operation),
+    ),
+  };
+}
+
+export function shouldApplyInvalidation(
+  event: InvalidationEvent,
+  subscriber: InvalidationSubscriber,
+): boolean {
+  if (subscriber.scopeKey && subscriber.scopeKey !== event.scopeKey) {
+    return false;
+  }
+
+  const sameNamespace = subscriber.namespace === event.sourceNamespace;
+  const allowedCrossNamespace =
+    subscriber.acceptCrossNamespace === true &&
+    event.targetNamespaces?.includes(subscriber.namespace) === true;
+
+  if (!sameNamespace && !allowedCrossNamespace) {
+    return false;
+  }
+
+  if (!subscriber.operationIds || subscriber.operationIds.length === 0) {
+    return true;
+  }
+
+  if (!event.targetOperationIds || event.targetOperationIds.length === 0) {
+    return true;
+  }
+
+  return subscriber.operationIds.some(operationId =>
+    event.targetOperationIds?.includes(operationId),
+  );
+}

package/src/data-platform/trace.ts

@@ -0,0 +1,49 @@
+// @effect-diagnostics asyncFunction:off globalDate:off globalRandom:off globalTimers:off newPromise:off strictBooleanExpressions:off
+import { parseTraceparent } from '@modern-js/create-request';
+
+import type { TraceContext } from './types';
+
+function isAllZeroHex(value: string): boolean {
+  return /^0+$/.test(value);
+}
+
+function isValidHex(value: string, length: number): boolean {
+  return value.length === length && /^[0-9a-f]+$/.test(value);
+}
+
+export function parseTraceparentHeader(header: string): TraceContext | null {
+  return parseTraceparent(header) ?? null;
+}
+
+export function formatTraceparentHeader(trace: TraceContext): string {
+  const traceId = trace.traceId.toLowerCase();
+  const spanId = trace.spanId.toLowerCase();
+
+  if (!isValidHex(traceId, 32) || !isValidHex(spanId, 16)) {
+    throw new Error('Invalid trace context: traceId/spanId format mismatch');
+  }
+
+  if (isAllZeroHex(traceId) || isAllZeroHex(spanId)) {
+    throw new Error('Invalid trace context: traceId/spanId cannot be zero');
+  }
+
+  const flags = trace.sampled ? '01' : '00';
+  return `00-${traceId}-${spanId}-${flags}`;
+}
+
+export function deriveChildTraceContext(
+  parent: TraceContext,
+  childSpanId: string,
+): TraceContext {
+  const normalizedSpanId = childSpanId.toLowerCase();
+  if (!isValidHex(normalizedSpanId, 16) || isAllZeroHex(normalizedSpanId)) {
+    throw new Error('Invalid child span id');
+  }
+
+  return {
+    traceId: parent.traceId.toLowerCase(),
+    spanId: normalizedSpanId,
+    sampled: parent.sampled,
+    parentSpanId: parent.spanId.toLowerCase(),
+  };
+}