@mfeflow/url-factory 0.0.0-stage → 0.2.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,46 @@
+type IdChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '_';
+/** The leading letters, digits and underscores of `S`: where `fillPath` ends a param name. */
+type Ident<S extends string, Acc extends string = ''> = S extends `${infer C}${infer Rest}` ? C extends IdChar ? Ident<Rest, `${Acc}${C}`> : Acc : Acc;
+/**
+ * Names of `:params` in a path template, e.g. `'/v1/orders/:orderId/items/:itemId'` gives
+ * `'orderId' | 'itemId'`. A name is letters, digits and underscores, as in `fillPath`, so
+ * `'/a/:order-id'` has the param `order`.
+ */
+export type PathParams<P extends string> = string extends P ? string : P extends `${string}:${infer Rest}` ? Exclude<Ident<Rest>, ''> | PathParams<Rest> : never;
+/**
+ * Fills the `:params` of a path template with encoded values. Throws for a missing param and for
+ * the values `.` and `..`, which would walk out of the path. `scope` and `id` only name the caller in
+ * the message.
+ */
+export declare function fillPath(template: string, params: Readonly<Record<string, string | number>> | undefined, scope: string, id: string): string;
+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>;
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+const PARAM = /:([A-Za-z0-9_]+)/g;
+function fillPath(template, params, scope, id) {
+    return template.replace(PARAM, (_match, name)=>{
+        const value = params?.[name];
+        if (void 0 === value) throw new Error(`${scope}: missing param "${name}" for "${id}"`);
+        const text = String(value);
+        if ('.' === text || '..' === text) throw new Error(`${scope}: param "${name}" for "${id}" cannot be "${text}"`);
+        return encodeURIComponent(text);
+    });
+}
+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 = fillPath(endpoint.path, options?.params, 'url-factory', key);
+        const url = new URL(path.slice(1), base.endsWith('/') ? base : `${base}/`);
+        appendQuery(url, options?.query);
+        return url.toString();
+    };
+}
+export { createUrlFactory, defineEndpoints, fillPath };

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.2.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"
+  }
 }