@mfeflow/url-factory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @mfeflow/url-factory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed API URLs for micro-frontends. Path params are checked from the template at compile time, and base URLs are read from runtime config on every call, so one build runs in every environment.
+
+## Install
+
+```sh
+pnpm add @mfeflow/url-factory
+```
+
+## Usage
+
+```ts
+import { createUrlFactory, defineEndpoints } from '@mfeflow/url-factory';
+
+const endpoints = defineEndpoints({
+  getOrder: { service: 'orders', path: '/v1/orders/:orderId' },
+  listOrders: { service: 'orders', path: '/v1/orders' },
+});
+
+const services: Record<string, string> = { orders: 'https://api.example.com' };
+const apiUrl = createUrlFactory(endpoints, (service) => services[service]);
+
+apiUrl('getOrder', { params: { orderId: 42 }, query: { expand: 'items' } });
+// https://api.example.com/v1/orders/42?expand=items
+apiUrl('getOrder'); // compile error: params are required
+```
+
+A missing param, an unknown endpoint or a service without a base URL throws with a message that names it.
+
+## Module Federation sharing
+
+Bucket: **stateless**. Nothing here holds state shared between micro-frontends, so each remote can bundle its own copy and different versions can run side by side. No sharing config is needed.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/** Names of `:params` in a path template, e.g. `'/v1/orders/:orderId/items/:itemId'` → `'orderId' | 'itemId'`. */
+export type PathParams<P extends string> = P extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParams<`/${Rest}`> : P extends `${string}:${infer Param}` ? Param : never;
+export type QueryValue = string | number | boolean | null | undefined | readonly (string | number | boolean)[];
+export type Query = Readonly<Record<string, QueryValue>>;
+export interface Endpoint {
+    /** Key into the runtime config's service base URLs, e.g. `orders`. */
+    readonly service: string;
+    /** Path template relative to the service base, e.g. `/v1/orders/:orderId`. */
+    readonly path: string;
+}
+export type Endpoints = Readonly<Record<string, Endpoint>>;
+/** `[options?]` for paths without params, `[options]` with required `params` otherwise. */
+export type UrlArgs<P extends string> = [PathParams<P>] extends [never] ? [options?: {
+    query?: Query;
+}] : [options: {
+    params: Readonly<Record<PathParams<P>, string | number>>;
+    query?: Query;
+}];
+export type UrlFactory<E extends Endpoints> = <K extends keyof E & string>(key: K, ...args: UrlArgs<E[K]['path']>) => string;
+/** Identity helper that keeps the literal path types, so params are checked. */
+export declare function defineEndpoints<const E extends Endpoints>(endpoints: E): E;
+/**
+ * Builds absolute URLs for `endpoints`. `baseUrl(service)` is called on every
+ * call, so it can read runtime config that loads after the factory is created.
+ *
+ * ```ts
+ * const endpoints = defineEndpoints({ getOrder: { service: 'orders', path: '/v1/orders/:orderId' } });
+ * const apiUrl = createUrlFactory(endpoints, (s) => getRuntimeConfig().services[s]);
+ * apiUrl('getOrder', { params: { orderId: 42 }, query: { expand: 'items' } });
+ * ```
+ */
+export declare function createUrlFactory<E extends Endpoints>(endpoints: E, baseUrl: (service: E[keyof E]['service']) => string | undefined): UrlFactory<E>;

package/dist/index.js

@@ -0,0 +1,27 @@
+function defineEndpoints(endpoints) {
+    for (const [key, e] of Object.entries(endpoints))if (!e.path.startsWith('/')) throw new Error(`Endpoint "${key}": path must start with "/"`);
+    return endpoints;
+}
+function appendQuery(url, query) {
+    if (!query) return;
+    for (const [name, value] of Object.entries(query))if (null != value) if (Array.isArray(value)) for (const item of value)url.searchParams.append(name, String(item));
+    else url.searchParams.append(name, String(value));
+}
+function createUrlFactory(endpoints, baseUrl) {
+    return (key, ...args)=>{
+        const endpoint = endpoints[key];
+        if (!endpoint) throw new Error(`url-factory: unknown endpoint "${key}"`);
+        const base = baseUrl(endpoint.service);
+        if (!base) throw new Error(`url-factory: no base URL for service "${endpoint.service}" (endpoint "${key}")`);
+        const options = args[0];
+        const path = endpoint.path.replace(/:([A-Za-z0-9_]+)/g, (_match, name)=>{
+            const value = options?.params?.[name];
+            if (void 0 === value) throw new Error(`url-factory: missing param "${name}" for "${key}"`);
+            return encodeURIComponent(String(value));
+        });
+        const url = new URL(path.slice(1), base.endsWith('/') ? base : `${base}/`);
+        appendQuery(url, options?.query);
+        return url.toString();
+    };
+}
+export { createUrlFactory, defineEndpoints };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@mfeflow/url-factory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Typed API URLs for micro-frontends: path params are checked from the template at compile time, base URLs come from runtime config, so one build runs in every environment.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "url",
+    "typescript",
+    "api",
+    "runtime-config",
+    "react",
+    "rsbuild"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/url-factory"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@rslib/core": "1.0.5",
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "stateless"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }