@bleedingdev/modern-js-plugin-bff-extensions 3.8.3-ultramodern.2

package/package.json

@@ -0,0 +1,213 @@
+{
+  "name": "@bleedingdev/modern-js-plugin-bff-extensions",
+  "description": "Fork-owned UltraModern.js BFF adapters, generation, policy, and backend federation extensions.",
+  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "bugs": {
+    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "directory": "packages/cli/plugin-bff-extensions"
+  },
+  "license": "MIT",
+  "keywords": [
+    "bff",
+    "effect",
+    "framework",
+    "modern.js",
+    "ultramodern.js"
+  ],
+  "version": "3.8.3-ultramodern.2",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./hono": {
+      "types": "./dist/types/hono/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/hono/index.mjs",
+        "require": "./dist/cjs/hono/index.js"
+      },
+      "import": "./dist/esm/hono/index.mjs",
+      "default": "./dist/esm/hono/index.mjs"
+    },
+    "./cross-project-policy": {
+      "types": "./dist/types/cross-project-policy/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/cross-project-policy/index.mjs",
+        "require": "./dist/cjs/cross-project-policy/index.js"
+      },
+      "default": "./dist/cjs/cross-project-policy/index.js"
+    },
+    "./cross-project-generation": {
+      "types": "./dist/types/cross-project-generation/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/cross-project-generation/index.mjs",
+        "require": "./dist/cjs/cross-project-generation/index.js"
+      },
+      "default": "./dist/cjs/cross-project-generation/index.js"
+    },
+    "./effect-adapter": {
+      "types": "./dist/types/effect-adapter/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/effect-adapter/index.mjs",
+        "require": "./dist/cjs/effect-adapter/index.js"
+      },
+      "default": "./dist/cjs/effect-adapter/index.js"
+    },
+    "./effect-source-loader": {
+      "types": "./dist/types/effect-source-loader/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/effect-source-loader/index.mjs",
+        "require": "./dist/cjs/effect-source-loader/index.js"
+      },
+      "default": "./dist/cjs/effect-source-loader/index.js"
+    },
+    "./client-generator": {
+      "types": "./dist/types/client-generator/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/client-generator/index.mjs",
+        "require": "./dist/cjs/client-generator/index.js"
+      },
+      "default": "./dist/cjs/client-generator/index.js"
+    },
+    "./backend-federation": {
+      "types": "./dist/types/backend-federation/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/backend-federation/index.mjs",
+        "require": "./dist/cjs/backend-federation/index.js"
+      },
+      "import": "./dist/esm/backend-federation/index.mjs",
+      "default": "./dist/esm/backend-federation/index.mjs"
+    },
+    "./backend-federation/edge": {
+      "types": "./dist/types/backend-federation/edge.d.ts",
+      "node": {
+        "import": "./dist/esm-node/backend-federation/edge.mjs",
+        "require": "./dist/cjs/backend-federation/edge.js"
+      },
+      "import": "./dist/esm/backend-federation/edge.mjs",
+      "default": "./dist/esm/backend-federation/edge.mjs"
+    },
+    "./backend-federation/node": {
+      "types": "./dist/types/backend-federation/node.d.ts",
+      "node": {
+        "import": "./dist/esm-node/backend-federation/node.mjs",
+        "require": "./dist/cjs/backend-federation/node.js"
+      },
+      "default": "./dist/cjs/backend-federation/node.js"
+    },
+    "./backend-federation-manifest": {
+      "types": "./dist/types/backend-federation-manifest/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/backend-federation-manifest/index.mjs",
+        "require": "./dist/cjs/backend-federation-manifest/index.js"
+      },
+      "default": "./dist/cjs/backend-federation-manifest/index.js"
+    },
+    "./backend-federation-manifest/node": {
+      "types": "./dist/types/backend-federation-manifest/node.d.ts",
+      "node": {
+        "import": "./dist/esm-node/backend-federation-manifest/node.mjs",
+        "require": "./dist/cjs/backend-federation-manifest/node.js"
+      },
+      "default": "./dist/cjs/backend-federation-manifest/node.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "hono": [
+        "./dist/types/hono/index.d.ts",
+        "./src/hono/index.ts"
+      ],
+      "cross-project-policy": [
+        "./dist/types/cross-project-policy/index.d.ts",
+        "./src/cross-project-policy/index.ts"
+      ],
+      "cross-project-generation": [
+        "./dist/types/cross-project-generation/index.d.ts",
+        "./src/cross-project-generation/index.ts"
+      ],
+      "effect-adapter": [
+        "./dist/types/effect-adapter/index.d.ts",
+        "./src/effect-adapter/index.ts"
+      ],
+      "effect-source-loader": [
+        "./dist/types/effect-source-loader/index.d.ts",
+        "./src/effect-source-loader/index.ts"
+      ],
+      "client-generator": [
+        "./dist/types/client-generator/index.d.ts",
+        "./src/client-generator/index.ts"
+      ],
+      "backend-federation": [
+        "./dist/types/backend-federation/index.d.ts",
+        "./src/backend-federation/index.ts"
+      ],
+      "backend-federation/edge": [
+        "./dist/types/backend-federation/edge.d.ts",
+        "./src/backend-federation/edge.ts"
+      ],
+      "backend-federation/node": [
+        "./dist/types/backend-federation/node.d.ts",
+        "./src/backend-federation/node.ts"
+      ],
+      "backend-federation-manifest": [
+        "./dist/types/backend-federation-manifest/index.d.ts",
+        "./src/backend-federation-manifest/index.ts"
+      ],
+      "backend-federation-manifest/node": [
+        "./dist/types/backend-federation-manifest/node.d.ts",
+        "./src/backend-federation-manifest/node.ts"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=26.7.0"
+  },
+  "dependencies": {
+    "@modern-js/bff-core": "npm:@bleedingdev/modern-js-bff-core@3.8.3-ultramodern.2",
+    "@modern-js/bff-effect": "npm:@bleedingdev/modern-js-bff-effect@3.8.3-ultramodern.2",
+    "@modern-js/runtime-extensions": "npm:@bleedingdev/modern-js-runtime-extensions@3.8.3-ultramodern.2",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.8.3-ultramodern.2",
+    "@modern-js/server-runtime-extensions": "npm:@bleedingdev/modern-js-server-runtime-extensions@3.8.3-ultramodern.2",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.8.3-ultramodern.2",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.8.3-ultramodern.2",
+    "@module-federation/runtime": "2.9.0",
+    "esbuild": "^0.28.1"
+  },
+  "peerDependencies": {
+    "@effect/opentelemetry": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112"
+  },
+  "peerDependenciesMeta": {
+    "@effect/opentelemetry": {
+      "optional": true
+    },
+    "effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/opentelemetry": "4.0.0-rc.112",
+    "@rslib/core": "0.23.2",
+    "@scripts/rstest-config": "2.66.0",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "effect": "4.0.0-rc.112"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretest": "pnpm run build",
+    "dev": "rslib build --watch",
+    "build": "rslib build",
+    "test": "rstest"
+  }
+}

package/src/backend-federation/edge-runtime.ts

@@ -0,0 +1,258 @@
+import type { BackendFederationExpectedIdentity } from './identity';
+import type { BackendFederationEntryExports } from './types';
+import { validateLoadedBackendFederatedEffectApi } from './validate-loaded';
+
+export type BackendFederationEdgeLoadEntryPlugin = {
+  name: string;
+  loadEntry: (args: {
+    remoteInfo: BackendFederationEdgeRemote;
+  }) =>
+    | BackendFederationEntryExports
+    | undefined
+    | Promise<BackendFederationEntryExports | undefined>;
+};
+
+export type BackendFederationEdgeLoadEntryPluginOptions = {
+  /**
+   * Resolve the fork-owned edge entry contract, not a raw Module Federation
+   * container. The edge runtime calls its optional `init` once per remote with
+   * `{ hostName }`, then caches each loaded expose.
+   */
+  resolveEntry: (
+    remote: BackendFederationEdgeRemote,
+  ) =>
+    | BackendFederationEntryExports
+    | undefined
+    | Promise<BackendFederationEntryExports | undefined>;
+};
+
+export type BackendFederationEdgeRemote = {
+  entry: `${'binding' | 'service' | 'static'}:${string}`;
+  entryGlobalName?: string;
+  expose?: string;
+  name: string;
+  shareScope?: string | string[];
+  type?: 'commonjs-module' | 'module' | string;
+  verification?: never;
+};
+
+type BackendFederationEdgeRuntimeBaseOptions = {
+  entryPolicy?: never;
+  hostName: string;
+  plugins?: BackendFederationEdgeLoadEntryPlugin[];
+  remote?: BackendFederationEdgeRemote;
+  remotes?: BackendFederationEdgeRemote[];
+};
+
+export type BackendFederationEdgeRuntimeOptions =
+  BackendFederationEdgeRuntimeBaseOptions & {
+    expected: BackendFederationExpectedIdentity;
+  };
+
+type EdgeRuntimeLoadOptions = BackendFederationEdgeRuntimeBaseOptions & {
+  allowMissingIdentityMetadata?: boolean;
+  expected?: BackendFederationExpectedIdentity;
+};
+
+function parseRemoteRequest(request: string) {
+  const separator = request.indexOf('/');
+  if (separator <= 0 || separator === request.length - 1) {
+    throw new Error(
+      `[BFF][Effect] Invalid backend federation request ${request}.`,
+    );
+  }
+  return {
+    expose: `./${request.slice(separator + 1).replace(/^\.\//u, '')}`,
+    remoteName: request.slice(0, separator),
+  };
+}
+
+function requireEdgeRemote(
+  remotes: readonly BackendFederationEdgeRemote[],
+  remoteName: string,
+) {
+  const remote = remotes.find(candidate => candidate.name === remoteName);
+  if (remote === undefined) {
+    throw new Error(
+      `[BFF][Effect] Missing backend federation remote ${remoteName}.`,
+    );
+  }
+  if (!/^(?:binding|service|static):/u.test(remote.entry)) {
+    throw new Error(
+      `[BFF][Effect] Edge backend federation remote ${remote.name} must use static or service-binding entries.`,
+    );
+  }
+  return remote;
+}
+
+async function resolveEdgeEntry(
+  plugins: readonly BackendFederationEdgeLoadEntryPlugin[],
+  remote: BackendFederationEdgeRemote,
+) {
+  for (const plugin of plugins) {
+    const entry = await plugin.loadEntry?.({ remoteInfo: remote });
+    if (entry !== undefined) {
+      return entry;
+    }
+  }
+  if (remote.entry.startsWith('static:') && remote.entryGlobalName) {
+    const globalEntry = (globalThis as Record<string, unknown>)[
+      remote.entryGlobalName
+    ];
+    if (typeof globalEntry === 'object' && globalEntry !== null) {
+      return globalEntry as BackendFederationEntryExports;
+    }
+    throw new Error(
+      `[BFF][Effect] Missing static backend federation entry global ${remote.entryGlobalName} for remote ${remote.name}.`,
+    );
+  }
+  throw new Error(
+    `[BFF][Effect] Missing static or service-binding entry provider for backend federation remote ${remote.name}.`,
+  );
+}
+
+class EdgeBackendFederationRuntime {
+  readonly #entries = new Map<string, Promise<BackendFederationEntryExports>>();
+  readonly #expected: BackendFederationExpectedIdentity | undefined;
+  readonly #hostName: string;
+  readonly #allowMissingIdentityMetadata: boolean;
+  readonly #modules = new Map<string, Promise<unknown>>();
+  readonly #plugins: readonly BackendFederationEdgeLoadEntryPlugin[];
+  readonly #remotes: BackendFederationEdgeRemote[];
+
+  constructor(options: EdgeRuntimeLoadOptions) {
+    if (options.entryPolicy !== undefined) {
+      throw new Error(
+        '[BFF][Effect] Edge backend federation does not execute entry evaluators. Register a static or service-binding entry provider.',
+      );
+    }
+    this.#allowMissingIdentityMetadata =
+      options.allowMissingIdentityMetadata === true;
+    this.#expected = options.expected;
+    this.#hostName = options.hostName;
+    this.#plugins = options.plugins ?? [];
+    this.#remotes = [...(options.remotes ?? [])];
+    const configuredRemote = options.remote;
+    if (configuredRemote !== undefined) {
+      const existingIndex = this.#remotes.findIndex(
+        remote => remote.name === configuredRemote.name,
+      );
+      if (existingIndex >= 0) {
+        this.#remotes[existingIndex] = configuredRemote;
+      } else {
+        this.#remotes.push(configuredRemote);
+      }
+    }
+  }
+
+  #loadEntry(remote: BackendFederationEdgeRemote) {
+    const existing = this.#entries.get(remote.name);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const loading = resolveEdgeEntry(this.#plugins, remote).then(
+      async entry => {
+        await entry.init?.({ hostName: this.#hostName });
+        return entry;
+      },
+    );
+    this.#entries.set(remote.name, loading);
+    loading.catch(() => {
+      if (this.#entries.get(remote.name) === loading) {
+        this.#entries.delete(remote.name);
+      }
+    });
+    return loading;
+  }
+
+  #loadModule(request: string) {
+    const { expose, remoteName } = parseRemoteRequest(request);
+    const remote = requireEdgeRemote(this.#remotes, remoteName);
+    return this.#loadEntry(remote).then(async entry => {
+      if (typeof entry.get !== 'function') {
+        throw new Error(
+          `[BFF][Effect] Backend federation remote ${remote.name} entry must expose get().`,
+        );
+      }
+      const factory = await entry.get(expose);
+      if (typeof factory !== 'function') {
+        throw new Error(
+          `[BFF][Effect] Backend federation expose ${remote.name}/${expose.replace(/^\.\//u, '')} must load factory function.`,
+        );
+      }
+      const loaded = await factory();
+      return validateLoadedBackendFederatedEffectApi(loaded, {
+        allowMissingIdentityMetadata: this.#allowMissingIdentityMetadata,
+        expected: this.#expected,
+        remoteName,
+        remoteRequest: request,
+      });
+    });
+  }
+
+  async loadRemote<T>(request: string): Promise<T> {
+    const existing = this.#modules.get(request);
+    if (existing !== undefined) {
+      return existing as Promise<T>;
+    }
+    const loading = this.#loadModule(request);
+    this.#modules.set(request, loading);
+    loading.catch(() => {
+      if (this.#modules.get(request) === loading) {
+        this.#modules.delete(request);
+      }
+    });
+    return loading as Promise<T>;
+  }
+}
+
+export type BackendFederationEdgeRuntime = {
+  loadRemote<T>(request: string): Promise<T>;
+};
+
+export function createBackendFederationLoadEntryPlugin(
+  options: BackendFederationEdgeLoadEntryPluginOptions,
+): BackendFederationEdgeLoadEntryPlugin {
+  return {
+    name: 'modernjs-backend-federation-load-entry',
+    loadEntry({ remoteInfo }) {
+      return Promise.resolve(options.resolveEntry(remoteInfo)).then(entry => {
+        if (entry === undefined) {
+          return;
+        }
+        return {
+          get(id: string) {
+            return () =>
+              Promise.resolve(entry.get(id)).then(factory => factory());
+          },
+          init(...args: unknown[]) {
+            return entry.init?.(...args);
+          },
+        };
+      });
+    },
+  };
+}
+
+export function createBackendFederationRuntime(
+  options: BackendFederationEdgeRuntimeOptions,
+): BackendFederationEdgeRuntime {
+  if (
+    options.expected === undefined ||
+    typeof options.expected.unitId !== 'string' ||
+    options.expected.unitId.length === 0 ||
+    typeof options.expected.buildMarker !== 'string' ||
+    options.expected.buildMarker.length === 0
+  ) {
+    throw new Error(
+      '[BFF][Effect] Edge backend federation runtime requires expected.unitId and expected.buildMarker.',
+    );
+  }
+  return new EdgeBackendFederationRuntime(options);
+}
+
+export function createBackendFederationRuntimeForLoad(
+  options: EdgeRuntimeLoadOptions,
+): BackendFederationEdgeRuntime {
+  return new EdgeBackendFederationRuntime(options);
+}

package/src/backend-federation/edge.ts

@@ -0,0 +1,128 @@
+import {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+} from '@modern-js/utils/universal';
+import {
+  type BackendFederationEdgeLoadEntryPlugin,
+  type BackendFederationEdgeLoadEntryPluginOptions,
+  type BackendFederationEdgeRemote,
+  type BackendFederationEdgeRuntimeOptions,
+  createBackendFederationRuntimeForLoad,
+} from './edge-runtime';
+import type { BackendFederationExpectedIdentity } from './identity';
+import { LEGACY_LOAD_WARNING } from './legacy-warning';
+import type {
+  BackendFederatedEffectApiModule,
+  BackendFederationLoadOptions,
+  BackendFederationIdentityLoadOptions as UniversalBackendFederationIdentityLoadOptions,
+} from './types';
+import { normalizeExpose } from './utils';
+
+export {
+  type BackendFederationEdgeLoadEntryPlugin,
+  type BackendFederationEdgeLoadEntryPluginOptions,
+  type BackendFederationEdgeRemote,
+  type BackendFederationEdgeRuntime,
+  type BackendFederationEdgeRuntimeOptions,
+  createBackendFederationLoadEntryPlugin,
+  createBackendFederationRuntime,
+} from './edge-runtime';
+export {
+  type BackendFederationExpectedIdentity,
+  type BackendFederationIdentityIssue,
+  validateExpectedBackendFederationIdentity,
+} from './identity';
+export type {
+  BackendFederatedEffectApiModule,
+  BackendFederationEntryExports,
+} from './types';
+
+export {
+  BACKEND_FEDERATION_CONTRACT_VERSION,
+  BACKEND_FEDERATION_EFFECT_EXPOSE,
+  BACKEND_FEDERATION_MANIFEST_FILE,
+  BACKEND_FEDERATION_NODE_ADAPTER_VERSION,
+};
+
+export type BackendFederationRemote = BackendFederationEdgeRemote;
+export type BackendFederationRuntimeOptions =
+  BackendFederationEdgeRuntimeOptions;
+export type BackendFederationLoadEntryPluginOptions =
+  BackendFederationEdgeLoadEntryPluginOptions;
+
+export type EdgeBackendFederationLoadOptions = Omit<
+  BackendFederationLoadOptions,
+  'entryPolicy' | 'plugins' | 'remote' | 'remotes' | 'runtime'
+> & {
+  entryPolicy?: never;
+  plugins?: BackendFederationEdgeLoadEntryPlugin[];
+  remote?: BackendFederationEdgeRemote;
+  remotes?: BackendFederationEdgeRemote[];
+  runtime?: never;
+};
+
+export type EdgeBackendFederationIdentityLoadOptions = Omit<
+  UniversalBackendFederationIdentityLoadOptions,
+  'entryPolicy' | 'plugins' | 'remote' | 'remotes' | 'runtime'
+> & {
+  entryPolicy?: never;
+  plugins?: BackendFederationEdgeLoadEntryPlugin[];
+  remote?: BackendFederationEdgeRemote;
+  remotes?: BackendFederationEdgeRemote[];
+  runtime?: never;
+};
+
+export type BackendFederationIdentityLoadOptions =
+  EdgeBackendFederationIdentityLoadOptions;
+
+export function loadBackendFederatedEffectApi(
+  options: EdgeBackendFederationIdentityLoadOptions,
+): Promise<BackendFederatedEffectApiModule>;
+/** @deprecated Pass `expected` delivery-unit identity. */
+export function loadBackendFederatedEffectApi(
+  options: EdgeBackendFederationLoadOptions,
+): Promise<BackendFederatedEffectApiModule>;
+export function loadBackendFederatedEffectApi(
+  options: EdgeBackendFederationLoadOptions & {
+    expected?: BackendFederationExpectedIdentity;
+    allowMissingIdentityMetadata?: boolean;
+  },
+): Promise<BackendFederatedEffectApiModule> {
+  if (
+    (options as BackendFederationLoadOptions).runtime !== undefined ||
+    (options as BackendFederationLoadOptions).entryPolicy !== undefined
+  ) {
+    return Promise.reject(
+      new Error(
+        '[BFF][Effect] Edge backend federation does not execute custom runtimes or entry evaluators. Register a static or service-binding entry provider.',
+      ),
+    );
+  }
+
+  const remoteName = options.remote?.name ?? options.remoteName;
+  if (remoteName === undefined || remoteName.length === 0) {
+    return Promise.reject(
+      new Error('[BFF][Effect] Missing backend federation remote name.'),
+    );
+  }
+
+  if (options.expected === undefined) {
+    console.warn(LEGACY_LOAD_WARNING);
+  }
+
+  const expose =
+    options.expose ??
+    options.remote?.expose ??
+    BACKEND_FEDERATION_EFFECT_EXPOSE;
+  const remoteRequest = `${remoteName}/${normalizeExpose(expose)}`;
+
+  let runtime;
+  try {
+    runtime = createBackendFederationRuntimeForLoad(options);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  return runtime.loadRemote(remoteRequest);
+}