@softarc/native-federation-runtime 4.0.0-RC2 → 4.0.0-RC4

package/README.md

@@ -0,0 +1,11 @@
+# runtime
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build runtime` to build the library.
+
+## Running unit tests
+
+Run `nx test runtime` to execute the unit tests via [Vitest](https://vitest.dev/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softarc/native-federation-runtime",
-  "version": "4.0.0-RC2",
+  "version": "4.0.0-RC4",
   "type": "module",
   "license": "MIT",
   "main": "./index.js",
@@ -16,8 +16,13 @@
   },
   "files": [
     "lib",
+    "index.d.ts",
+    "index.js",
     "!**/*.tsbuildinfo"
   ],
+  "dependencies": {
+    "@softarc/native-federation": "4.0.0-RC4"
+  },
   "devDependencies": {
     "@types/node": "^22.5.4",
     "vitest": "^3.0.0",

package/lib/get-shared.d.ts

@@ -1,19 +0,0 @@
-type Type<T> = new () => T;
-export type ShareObject = {
-    version: string;
-    scope?: string;
-    get: () => Promise<() => Type<unknown>>;
-    shareConfig?: {
-        singleton?: boolean;
-        requiredVersion: string;
-    };
-};
-export type ShareConfig = {
-    [pkgName: string]: Array<ShareObject>;
-};
-export type ShareOptions = {
-    singleton: boolean;
-    requiredVersionPrefix: '^' | '~' | '>' | '>=' | '';
-};
-export declare function getShared(options?: ShareOptions): ShareConfig;
-export {};

package/lib/init-federation.d.ts

@@ -1,104 +0,0 @@
-import { type FederationInfo } from '@softarc/native-federation/domain';
-import { type InitFederationOptions, type ProcessRemoteInfoOptions } from './model/federation-info.js';
-import { type ImportMap } from './model/import-map.js';
-/**
- * Initializes the Native Federation runtime for the host application.
- *
- * This is the main entry point for setting up federation. It performs the following:
- * 1. Loads the host's remoteEntry.json to discover shared dependencies
- * 2. Loads each remote's remoteEntry.json to discover exposed modules
- * 3. Creates an ES Module import map with proper scoping
- * 4. Injects the import map into the DOM as a <script type="importmap-shim">
- *
- * The import map allows dynamic imports to resolve correctly:
- * - Host shared deps go in root imports (e.g., "angular": "./angular.js")
- * - Remote exposed modules go in root imports (e.g., "mfe1/Component": "http://...")
- * - Remote shared deps go in scoped imports for proper resolution
- *
- * @param remotesOrManifestUrl - Either:
- *   - A record of remote names to their remoteEntry.json URLs
- *     Example: { mfe1: 'http://localhost:3000/remoteEntry.json' }
- *   - A URL to a manifest.json that contains the remotes record
- *     Example: 'http://localhost:3000/federation-manifest.json'
- *
- * @param options - Configuration options:
- *   - cacheTag: A version string to append as query param for cache busting
- *     Example: { cacheTag: 'v1.0.0' } results in '?t=v1.0.0' on all requests
- *
- * @returns The final merged ImportMap that was injected into the DOM
- *
- */
-export declare function initFederation(remotesOrManifestUrl?: Record<string, string> | string, options?: InitFederationOptions): Promise<ImportMap>;
-/**
- * Fetches and registers multiple remote applications in parallel and merges their import maps.
- *
- * This function is the orchestrator for loading all remotes. It:
- * 1. Creates a promise for each remote to load its remoteEntry.json
- * 2. Applies cache busting to each remote URL
- * 3. Handles errors gracefully (logs or throws based on options)
- * 4. Merges all successful remote import maps into one
- *
- * Each remote contributes:
- * - Its exposed modules to the root imports
- * - Its shared dependencies to scoped imports
- *
- * @param remotes - Record of remote names to their remoteEntry.json URLs
- * @param options - Processing options including:
- *   - throwIfRemoteNotFound: Whether to throw or log on remote load failure
- *   - cacheTag: Cache busting tag to append to URLs
- *
- * @returns Merged import map containing all remotes' contributions
- *
- */
-export declare function fetchAndRegisterRemotes(remotes: Record<string, string>, options?: ProcessRemoteInfoOptions): Promise<ImportMap>;
-/**
- * @deprecated Use `fetchAndRegisterRemotes` instead.
- * @param remotes
- * @param options
- * @returns
- */
-export declare function processRemoteInfos(remotes: Record<string, string>, options?: ProcessRemoteInfoOptions): Promise<ImportMap>;
-/**
- * Fetches a single remote application's remoteEntry.json file and registers it in the system (global registry).
- *
- * This function handles everything needed to integrate one remote:
- * 1. Fetches the remote's remoteEntry.json file
- * 2. Extracts the base URL from the remoteEntry path
- * 3. Creates import map entries for exposed modules and shared deps
- * 4. Registers the remote in the global remotes registry
- * 5. Sets up hot reload watching if configured (development mode)
- *
- * @param federationInfoUrl - Full URL to the remote's remoteEntry.json
- * @param remoteName - Name to use for this remote (optional, uses info.name if not provided)
- *
- * @returns Import map containing this remote's exposed modules and shared dependencies
- *
- * @example
- * ```typescript
- * const importMap = await fetchAndRegisterRemote(
- *   'http://localhost:3000/mfe1/remoteEntry.json',
- *   'mfe1'
- * );
- * // Result: {
- * //   imports: { 'mfe1/Component': 'http://localhost:3000/mfe1/Component.js' },
- * //   scopes: { 'http://localhost:3000/mfe1/': { 'lodash': '...' } }
- * // }
- * ```
- */
-export declare function fetchAndRegisterRemote(federationInfoUrl: string, remoteName?: string): Promise<ImportMap>;
-/**
- * Processes the host application's federation info into an import map.
- *
- * The host app typically doesn't expose modules (it's the consumer),
- * but it does share dependencies that should be available to remotes.
- *
- * Host shared dependencies go in root-level imports (not scoped) because:
- * 1. The host loads first and establishes the base environment
- * 2. Remotes should prefer host versions to avoid duplication
- *
- * @param hostInfo - Federation info from the host's remoteEntry.json
- * @param relBundlesPath - Relative path to the host's bundle directory (default: './')
- *
- * @returns Import map with host's shared dependencies in root imports
- */
-export declare function processHostInfo(hostInfo: FederationInfo, relBundlesPath?: string): Promise<ImportMap>;

package/lib/load-remote-module.d.ts

@@ -1,82 +0,0 @@
-/**
- * Options for loading a remote module.
- *
- * @template T - The expected type of the module's exports
- *
- * @property remoteEntry - Optional URL to the remote's remoteEntry.json file.
- *   Used for lazy-loading remotes that weren't registered during initFederation
- *   Example: 'http://localhost:3000/remoteEntry.json'
- *
- * @property remoteName - Optional name of the remote application.
- *   Should match the name used during initFederation or the name in remoteEntry.json.
- *   Example: 'mfe1'
- *
- * @property exposedModule - The key of the exposed module to load (required).
- *   Must match the key defined in the remote's federation config.
- *   Example: './Component' or './Dashboard'
- *
- * @property fallback - Optional fallback value to return if the remote or module cannot be loaded.
- *   Prevents throwing errors and provides graceful degradation.
- *   Example: A default component or null
- */
-export type LoadRemoteModuleOptions<T = any> = {
-    remoteEntry?: string;
-    remoteName?: string;
-    exposedModule: string;
-    fallback?: T;
-};
-/**
- * Dynamically loads a remote module at runtime from a federated application.
- *
- * This is the primary API for consuming remote modules after federation has been initialized.
- * It supports two calling patterns:
- *
- * **Pattern 1: Using options object**
- * ```typescript
- * const module = await loadRemoteModule({
- *   remoteName: 'mfe1',
- *   exposedModule: './Component',
- *   fallback: DefaultComponent
- * });
- * ```
- *
- * **Pattern 2: Using positional arguments**
- * ```typescript
- * const module = await loadRemoteModule('mfe1', './Component');
- * ```
- *
- * ## Loading Process
- *
- * 1. **Normalize Options**: Converts arguments into a standard options object
- * 2. **Ensure Remote Initialized**: If remoteEntry is provided and remote isn't loaded,
- *    fetches and registers it dynamically
- * 3. **Resolve Remote Name**: Determines remote name from options or remoteEntry URL
- * 4. **Validate Remote**: Checks if remote exists in the registry
- * 5. **Validate Exposed Module**: Verifies the requested module is exposed by the remote
- * 6. **Import Module**: Uses dynamic import or import-shim to load the module
- * 7. **Handle Errors**: Returns fallback if provided, otherwise throws
- *
- * ## Lazy Loading Support
- *
- * If you provide a `remoteEntry` URL for a remote that wasn't initialized during
- * `initFederation()`, this function will automatically:
- * - Fetch the remote's remoteEntry.json
- * - Register it in the global registry
- * - Update the import map
- * - Then load the requested module
- *
- * This enables on-demand loading of remotes based on user interactions.
- *
- *
- * @template T - The expected type of the module's exports
- *
- * @param options - Configuration object for loading the remote module
- * @returns Promise resolving to the loaded module or fallback value
- *
- * @throws Error if remote is not found and no fallback is provided
- * @throws Error if exposed module doesn't exist and no fallback is provided
- * @throws Error if module import fails and no fallback is provided
- *
- */
-export declare function loadRemoteModule<T = any>(options: LoadRemoteModuleOptions): Promise<T>;
-export declare function loadRemoteModule<T = any>(remoteName: string, exposedModule: string): Promise<T>;

package/lib/model/build-notifications-options.d.ts

@@ -1 +0,0 @@
-export declare const BUILD_NOTIFICATIONS_ENDPOINT = "/@angular-architects/native-federation:build-notifications";

package/lib/model/externals.d.ts

@@ -1,3 +0,0 @@
-import type { SharedInfo } from '@softarc/native-federation/domain';
-export declare function getExternalUrl(shared: SharedInfo): string | undefined;
-export declare function setExternalUrl(shared: SharedInfo, url: string): void;

package/lib/model/federation-info.d.ts

@@ -1,6 +0,0 @@
-export interface InitFederationOptions {
-    cacheTag?: string;
-}
-export interface ProcessRemoteInfoOptions extends InitFederationOptions {
-    throwIfRemoteNotFound: boolean;
-}

package/lib/model/global-cache.d.ts

@@ -1,11 +0,0 @@
-import type { Remote } from './remotes.js';
-export declare const nfNamespace = "__NATIVE_FEDERATION__";
-export type NfCache = {
-    externals: Map<string, string>;
-    remoteNamesToRemote: Map<string, Remote>;
-    baseUrlToRemoteNames: Map<string, string>;
-};
-export type Global = {
-    [nfNamespace]: NfCache;
-};
-export declare const globalCache: NfCache;

package/lib/model/import-map.d.ts

@@ -1,7 +0,0 @@
-export type Imports = Record<string, string>;
-export type Scopes = Record<string, Imports>;
-export type ImportMap = {
-    imports: Imports;
-    scopes: Scopes;
-};
-export declare function mergeImportMaps(map1: ImportMap, map2: ImportMap): ImportMap;

package/lib/model/remotes.d.ts

@@ -1,9 +0,0 @@
-import type { FederationInfo } from '@softarc/native-federation/domain';
-export type Remote = FederationInfo & {
-    baseUrl: string;
-};
-export declare function addRemote(remoteName: string, remote: Remote): void;
-export declare function getRemoteNameByBaseUrl(baseUrl: string): string | undefined;
-export declare function isRemoteInitialized(baseUrl: string): boolean;
-export declare function getRemote(remoteName: string): Remote | undefined;
-export declare function hasRemote(remoteName: string): boolean;

package/lib/utils/add-import-map.d.ts

@@ -1,2 +0,0 @@
-import type { ImportMap } from '../model/import-map.js';
-export declare function appendImportMap(importMap: ImportMap): void;

package/lib/utils/path-utils.d.ts

@@ -1,13 +0,0 @@
-/**
- * Returns the full directory of a given path.
- * @param url - The path to get the directory of.
- * @returns The full directory of the path.
- */
-export declare function getDirectory(url: string): string;
-/**
- * Joins two paths together taking into account trailing slashes and "./" prefixes.
- * @param path1 - The first path to join.
- * @param path2 - The second path to join.
- * @returns The joined path.
- */
-export declare function joinPaths(path1: string, path2: string): string;

package/lib/utils/trusted-types.d.ts

@@ -1 +0,0 @@
-export declare function tryCreateTrustedScript(script: string): string | TrustedScript;

package/lib/watch-federation-build.d.ts

@@ -1,9 +0,0 @@
-/**
- * Watches for federation build completion events and automatically reloads the page.
- *
- * This function establishes a Server-Sent Events (SSE) connection to listen for
- * 'federation-rebuild-complete' notifications. When a build completes successfully,
- * it triggers a page reload to reflect the latest changes.
- * @param endpoint - The SSE endpoint URL to watch for build notifications.
- */
-export declare function watchFederationBuildCompletion(endpoint: string): void;