@route-forge/core 0.0.1

package/dist/index.js

@@ -0,0 +1,690 @@
+// src/cache.ts
+var KEY_PREFIX = "route-forge:";
+function pickStorage(storage) {
+  if (storage === "memory") return null;
+  if (typeof globalThis === "undefined") return null;
+  if (storage === "sessionStorage") {
+    return globalThis.sessionStorage ?? null;
+  }
+  if (storage === "localStorage") {
+    return globalThis.localStorage ?? null;
+  }
+  return null;
+}
+var RouteCache = class {
+  constructor(opts) {
+    this.memory = /* @__PURE__ */ new Map();
+    this.storage = opts.storage;
+    this.fallbackTtl = opts.ttl;
+    this.backend = pickStorage(opts.storage);
+  }
+  key(level) {
+    return `${KEY_PREFIX}${level}`;
+  }
+  get(level) {
+    if (this.storage === "memory" || !this.backend) {
+      return this.getFromMemory(level);
+    }
+    const raw = this.backend.getItem(this.key(level));
+    if (!raw) return void 0;
+    try {
+      const entry = JSON.parse(raw);
+      if (this.isExpired(entry)) {
+        this.del(level);
+        return void 0;
+      }
+      return entry;
+    } catch {
+      return void 0;
+    }
+  }
+  getFromMemory(level) {
+    const entry = this.memory.get(level);
+    if (!entry) return void 0;
+    if (this.isExpired(entry)) {
+      this.memory.delete(level);
+      return void 0;
+    }
+    return entry;
+  }
+  set(resp) {
+    const ttl = resp.cache !== void 0 && resp.cache !== null ? resp.cache : this.fallbackTtl;
+    const entry = {
+      level: resp.level,
+      routes: resp.routes,
+      ttl,
+      cachedAt: Date.now()
+    };
+    if (this.storage === "memory" || !this.backend) {
+      this.memory.set(resp.level, entry);
+      return;
+    }
+    try {
+      this.backend.setItem(this.key(resp.level), JSON.stringify(entry));
+    } catch {
+      this.memory.set(resp.level, entry);
+    }
+  }
+  del(level) {
+    this.memory.delete(level);
+    if (this.backend) {
+      try {
+        this.backend.removeItem(this.key(level));
+      } catch {
+      }
+    }
+  }
+  clear() {
+    this.memory.clear();
+    if (this.backend) {
+      try {
+        const toRemove = [];
+        for (let i = 0; i < this.backend.length; i++) {
+          const k = this.backend.key(i);
+          if (k && k.startsWith(KEY_PREFIX)) toRemove.push(k);
+        }
+        for (const k of toRemove) this.backend.removeItem(k);
+      } catch {
+      }
+    }
+  }
+  isExpired(entry) {
+    if (entry.ttl === null) return false;
+    if (entry.ttl === 0) return false;
+    return Date.now() - entry.cachedAt > entry.ttl * 1e3;
+  }
+};
+
+// src/errors.ts
+var ForgeError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = opts.code;
+    if (opts.route !== void 0) this.route = opts.route;
+    if (opts.level !== void 0) this.level = opts.level;
+    if (opts.context !== void 0) this.context = opts.context;
+    if (opts.cause !== void 0) this.cause = opts.cause;
+  }
+};
+var UnknownRouteError = class extends ForgeError {
+  constructor(route, level) {
+    super(`Route "${route}" not found${level ? ` in level "${level}"` : ""}`, {
+      code: "RF_FE_001",
+      route,
+      level
+    });
+  }
+};
+var UnknownLevelError = class extends ForgeError {
+  constructor(level) {
+    super(`Level "${level}" not declared in options.levels`, {
+      code: "RF_FE_002",
+      level
+    });
+  }
+};
+var MissingRouteParamError = class extends ForgeError {
+  constructor(route, missingParams) {
+    super(`Missing path parameter(s) ${missingParams.join(", ")} for route "${route}"`, {
+      code: "RF_FE_003",
+      route,
+      context: { missingParams }
+    });
+  }
+};
+var InsufficientAuthError = class extends ForgeError {
+  constructor(level) {
+    super(`Insufficient auth: level "${level}" requires login`, {
+      code: "RF_FE_004",
+      level
+    });
+  }
+};
+var AdapterNotFoundError = class extends ForgeError {
+  constructor(adapter) {
+    super(`Adapter "${adapter}" not available; install axios or use 'builtin'`, {
+      code: "RF_FE_005",
+      context: { adapter }
+    });
+  }
+};
+var InvalidInterceptorReturnError = class extends ForgeError {
+  constructor(route) {
+    super(`Request interceptor must return a RequestConfig object`, {
+      code: "RF_FE_006",
+      route
+    });
+  }
+};
+var NetworkError = class extends ForgeError {
+  constructor(message, route, level, cause) {
+    super(message, { code: "RF_FE_007", route, level, cause });
+  }
+};
+var HTTPError = class extends ForgeError {
+  constructor(message, opts) {
+    super(message, {
+      code: "RF_FE_008",
+      route: opts.route,
+      level: opts.level,
+      context: { status: opts.status, url: opts.url, method: opts.method },
+      cause: opts.cause
+    });
+  }
+};
+
+// src/interceptors.ts
+var InterceptorManagerImpl = class {
+  constructor() {
+    this.handlers = [];
+    this.nextId = 0;
+  }
+  use(onFulfilled, onRejected) {
+    const id = this.nextId++;
+    this.handlers.push({ id, onFulfilled, onRejected });
+    return id;
+  }
+  eject(id) {
+    const idx = this.handlers.findIndex((h) => h.id === id);
+    if (idx >= 0) this.handlers.splice(idx, 1);
+  }
+  clear() {
+    this.handlers = [];
+  }
+  forEach(fn) {
+    for (const h of this.handlers) fn(h);
+  }
+  /** 测试用：当前注册数量 */
+  get size() {
+    return this.handlers.length;
+  }
+};
+async function runRequestInterceptors(manager, initial) {
+  const handlers = [];
+  manager.forEach((h) => handlers.push(h));
+  handlers.reverse();
+  let p = Promise.resolve(initial);
+  for (const h of handlers) {
+    const onF = h.onFulfilled;
+    const onR = h.onRejected;
+    p = p.then(
+      async (v) => {
+        if (!onF) return v;
+        const result = await onF(v);
+        if (result === null || typeof result !== "object") {
+          throw new InvalidInterceptorReturnError();
+        }
+        return result;
+      },
+      (e) => onR ? onR(e) : Promise.reject(e)
+    );
+  }
+  return p;
+}
+async function runResponseInterceptors(manager, source) {
+  const handlers = [];
+  manager.forEach((h) => handlers.push(h));
+  let p = source;
+  for (const h of handlers) {
+    const onF = h.onFulfilled;
+    const onR = h.onRejected;
+    p = p.then(
+      (v) => onF ? onF(v) : v,
+      (e) => onR ? onR(e) : Promise.reject(e)
+    );
+  }
+  return p;
+}
+function createInterceptorManager() {
+  return new InterceptorManagerImpl();
+}
+
+// src/adapters/builtin-http.ts
+function createBuiltinHttp(forgeInterceptors) {
+  const requestMgr = forgeInterceptors?.request ?? createInterceptorManager();
+  const responseMgr = forgeInterceptors?.response ?? createInterceptorManager();
+  async function request(config) {
+    const finalConfig = await runRequestInterceptors(requestMgr, config);
+    const signal = finalConfig.timeout && finalConfig.timeout > 0 ? AbortSignal.timeout(finalConfig.timeout) : void 0;
+    let url = finalConfig.url;
+    if (finalConfig.paramsSerializer && finalConfig.params) {
+      const qs = finalConfig.paramsSerializer(finalConfig.params);
+      if (qs) {
+        url = url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
+      }
+    }
+    const fetchInit = {
+      method: finalConfig.method,
+      headers: new Headers(finalConfig.headers)
+    };
+    if (signal) fetchInit.signal = signal;
+    if (finalConfig.body !== void 0 && !["GET", "HEAD"].includes(finalConfig.method.toUpperCase())) {
+      fetchInit.body = typeof finalConfig.body === "string" ? finalConfig.body : JSON.stringify(finalConfig.body);
+    }
+    const res = await fetch(url, fetchInit);
+    const text = await res.text();
+    let data = text;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+      }
+    }
+    const responseData = {
+      route: finalConfig.route,
+      level: finalConfig.level,
+      method: finalConfig.method,
+      url,
+      status: res.status,
+      headers: res.headers,
+      data,
+      config: finalConfig
+    };
+    return runResponseInterceptors(
+      responseMgr,
+      Promise.resolve(responseData)
+    );
+  }
+  const get = (url, config) => request({ ...config, url, method: "GET" });
+  const post = (url, config) => request({ ...config, url, method: "POST" });
+  const put = (url, config) => request({ ...config, url, method: "PUT" });
+  const patch = (url, config) => request({ ...config, url, method: "PATCH" });
+  const del = (url, config) => request({ ...config, url, method: "DELETE" });
+  return {
+    request,
+    interceptors: {
+      request: requestMgr,
+      response: responseMgr
+    },
+    runsInterceptors: true,
+    get,
+    post,
+    put,
+    patch,
+    delete: del
+  };
+}
+
+// src/adapters/axios.ts
+async function wrapAxiosAdapter() {
+  let axios;
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      'axios'
+    );
+    axios = mod.default ?? mod;
+  } catch {
+    if (typeof globalThis !== "undefined" && globalThis.axios) {
+      axios = globalThis.axios;
+    }
+  }
+  if (!axios || typeof axios.request !== "function") return null;
+  async function request(config) {
+    const headers = { ...config.headers };
+    const res = await axios.request({
+      url: config.url,
+      method: config.method,
+      headers,
+      data: config.body
+      // axios 会处理 baseURL/transformRequest 等 defaults
+    });
+    return {
+      route: config.route,
+      level: config.level,
+      method: config.method,
+      url: config.url,
+      status: res.status,
+      headers: new Headers(res.headers ?? {}),
+      data: res.data,
+      config
+    };
+  }
+  return { request, interceptors: void 0 };
+}
+
+// src/adapters/index.ts
+async function resolveAdapter(opts) {
+  const { adapter } = opts;
+  if (adapter && typeof adapter === "object") {
+    return {
+      request: (config) => adapter.request(config),
+      interceptors: adapter.interceptors
+    };
+  }
+  if (adapter === "builtin") {
+    return createBuiltinHttp(opts.forgeInterceptors);
+  }
+  if (adapter === "axios") {
+    const wrapped2 = await wrapAxiosAdapter();
+    if (!wrapped2) throw new AdapterNotFoundError("axios");
+    return wrapped2;
+  }
+  const wrapped = await wrapAxiosAdapter().catch(() => null);
+  if (wrapped) return wrapped;
+  return createBuiltinHttp(opts.forgeInterceptors);
+}
+
+// src/forge.ts
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_CACHE_TTL = 3600;
+var DEFAULT_NAME_SEPARATOR = ".";
+function createRouteForge(options) {
+  if (!options.endpoint) throw new TypeError("options.endpoint is required");
+  const {
+    adapter = "auto",
+    timeout = DEFAULT_TIMEOUT,
+    baseURL = "",
+    nameSeparator = DEFAULT_NAME_SEPARATOR,
+    auth,
+    interceptors: declarativeInterceptors,
+    cache: cacheOpts = {}
+  } = options;
+  const explicitLevels = options.levels;
+  const explicitEager = options.eager;
+  const explicitStrict = options.strict ?? false;
+  const explicitEndpoint = options.endpoint;
+  let effectiveLevels = explicitLevels ?? [];
+  let effectiveEager = explicitEager ?? [];
+  let effectiveStrict = explicitStrict;
+  let effectiveEndpoint = explicitEndpoint;
+  const summaryPromise = (async () => {
+    try {
+      const summaryUrl = explicitEndpoint;
+      const resp = await fetch(summaryUrl, { method: "GET" });
+      if (!resp.ok) {
+        console.warn(
+          `[route-forge] summary endpoint ${summaryUrl} unreachable (HTTP ${resp.status}); falling back to explicit options`
+        );
+        return null;
+      }
+      return await resp.json();
+    } catch (e) {
+      if (explicitLevels && explicitLevels.length > 0) {
+        console.warn(
+          `[route-forge] summary endpoint unreachable: ${e.message}; using explicit levels`
+        );
+        return null;
+      }
+      throw new UnknownLevelError("(auto-discovery)");
+    }
+  })();
+  const autoDiscoveryPromise = summaryPromise.then((summary) => {
+    if (summary === null) {
+      return;
+    }
+    if (summary.config.endpoint_prefix && summary.config.endpoint_prefix !== explicitEndpoint) {
+      console.warn(
+        `[route-forge] backend endpoint_prefix "${summary.config.endpoint_prefix}" overrides frontend endpoint "${explicitEndpoint}"`
+      );
+      effectiveEndpoint = summary.config.endpoint_prefix;
+    }
+    if (summary.config.strict_mode && !explicitStrict) {
+      console.warn(
+        "[route-forge] backend strict_mode=true overrides frontend strict=false; forcing strict=true"
+      );
+      effectiveStrict = true;
+    }
+    const backendLevels = Object.keys(summary.levels);
+    if (explicitLevels && explicitLevels.length > 0) {
+      const intersection = explicitLevels.filter((l) => backendLevels.includes(l));
+      const removed = explicitLevels.filter((l) => !backendLevels.includes(l));
+      if (removed.length > 0) {
+        console.warn(
+          `[route-forge] levels not in backend summary and dropped: ${removed.join(", ")}`
+        );
+      }
+      effectiveLevels = intersection;
+    } else {
+      effectiveLevels = backendLevels;
+    }
+    if (!explicitEager) {
+      effectiveEager = backendLevels.filter((lvl) => summary.levels[lvl]?.load === "eager");
+    }
+  });
+  autoDiscoveryPromise.catch(() => {
+  });
+  const cacheTtl = cacheOpts.ttl ?? DEFAULT_CACHE_TTL;
+  const cacheStorage = cacheOpts.storage ?? "memory";
+  const cache = new RouteCache({ storage: cacheStorage, ttl: cacheTtl });
+  const requestInterceptors = new InterceptorManagerImpl();
+  const responseInterceptors = new InterceptorManagerImpl();
+  if (declarativeInterceptors?.request) {
+    for (const pair of declarativeInterceptors.request) {
+      const [onFulfilled, onRejected] = pair;
+      requestInterceptors.use(onFulfilled, onRejected);
+    }
+  }
+  if (declarativeInterceptors?.response) {
+    for (const pair of declarativeInterceptors.response) {
+      const [onFulfilled, onRejected] = pair;
+      responseInterceptors.use(onFulfilled, onRejected);
+    }
+  }
+  const adapterPromise = resolveAdapter({
+    adapter,
+    forgeInterceptors: { request: requestInterceptors, response: responseInterceptors }
+  });
+  let adapterResolved = false;
+  let adapterObj = null;
+  async function ensureAdapter() {
+    if (!adapterResolved) {
+      adapterObj = await adapterPromise.catch((e) => {
+        if (e instanceof AdapterNotFoundError) throw e;
+        return resolveAdapter({ adapter: "builtin" });
+      });
+      adapterResolved = true;
+    }
+    return adapterObj;
+  }
+  const inflight = /* @__PURE__ */ new Map();
+  function isAuthRequired(level) {
+    return Boolean(auth?.levels?.[level]);
+  }
+  function assertAuth(level) {
+    if (isAuthRequired(level) && auth?.state && !auth.state()) {
+      throw new InsufficientAuthError(level);
+    }
+  }
+  function assertLevelDeclared(level) {
+    if (!effectiveLevels.includes(level)) {
+      throw new UnknownLevelError(level);
+    }
+  }
+  function buildUrl(level) {
+    const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+    const ep = effectiveEndpoint.startsWith("/") ? effectiveEndpoint : `/${effectiveEndpoint}`;
+    return `${base}${ep}/${encodeURIComponent(level)}`;
+  }
+  async function fetchLevel(level) {
+    const adp = await ensureAdapter();
+    const config = {
+      route: `__forge__.load.${level}`,
+      level,
+      method: "GET",
+      url: buildUrl(level),
+      headers: { Accept: "application/json" },
+      params: {},
+      timeout,
+      meta: {
+        name: `__forge__.load.${level}`,
+        uri: buildUrl(level),
+        methods: ["GET"],
+        parameters: [],
+        level
+      }
+    };
+    const resp = await adp.request(config);
+    if (!resp || resp.status < 200 || resp.status >= 300) {
+      throw new Error(`Failed to load level ${level}: HTTP ${resp?.status}`);
+    }
+    const data = resp.data;
+    return data;
+  }
+  async function loadOne(level) {
+    assertLevelDeclared(level);
+    assertAuth(level);
+    if (cache.get(level)) return;
+    const existing = inflight.get(level);
+    if (existing) return existing;
+    const p = (async () => {
+      try {
+        const resp = await fetchLevel(level);
+        cache.set(resp);
+      } finally {
+        inflight.delete(level);
+      }
+    })();
+    inflight.set(level, p);
+    return p;
+  }
+  async function load(level) {
+    await autoDiscoveryPromise;
+    const list = Array.isArray(level) ? level : [level];
+    await Promise.all(list.map(loadOne));
+  }
+  function route(name, params) {
+    const meta = findRouteMeta(name);
+    if (!meta) {
+      if (effectiveStrict) throw new UnknownRouteError(name);
+      return "";
+    }
+    return buildRequestUrl(meta, params ?? {});
+  }
+  function buildRequestUrl(meta, params) {
+    let uri = meta.uri;
+    for (const p of meta.parameters) {
+      const v = params[p];
+      if (v === void 0) {
+        if (effectiveStrict) throw new MissingRouteParamError(meta.name, [p]);
+        uri = uri.replace(`{${p}}`, "");
+      } else {
+        uri = uri.replace(`{${p}}`, encodeURIComponent(String(v)));
+      }
+    }
+    const base = baseURL.endsWith("/") ? baseURL.slice(0, -1) : baseURL;
+    return uri.startsWith("/") ? `${base}${uri}` : `${base}/${uri}`;
+  }
+  function findRouteMeta(name) {
+    for (const level of effectiveLevels) {
+      const entry = cache.get(level);
+      const meta = entry?.routes[name];
+      if (meta) {
+        return { ...meta, level };
+      }
+    }
+    return void 0;
+  }
+  async function api(name, params = {}) {
+    await autoDiscoveryPromise;
+    const meta = findRouteMeta(name);
+    if (!meta) {
+      const firstSeg = name.split(nameSeparator)[0];
+      if (firstSeg && effectiveLevels.includes(firstSeg)) {
+        await load(firstSeg);
+      }
+      const reMeta = findRouteMeta(name);
+      if (!reMeta) {
+        if (effectiveStrict) throw new UnknownRouteError(name);
+        return void 0;
+      }
+      return doApiCall(reMeta, params);
+    }
+    return doApiCall(meta, params);
+  }
+  async function doApiCall(meta, params) {
+    assertAuth(meta.level ?? "");
+    const { query, body, headers, ...pathParams } = params;
+    for (const p of meta.parameters) {
+      if (pathParams[p] === void 0) {
+        if (effectiveStrict) throw new MissingRouteParamError(meta.name, [p]);
+      }
+    }
+    const method = pickMethod(meta);
+    const urlWithQuery = appendQuery(buildRequestUrl(meta, pathParams), query);
+    const config = {
+      route: meta.name,
+      level: meta.level ?? "",
+      method,
+      url: urlWithQuery,
+      headers: { Accept: "application/json", ...headers ?? {} },
+      body,
+      params: pathParams,
+      timeout,
+      meta
+    };
+    const adp = await ensureAdapter();
+    const finalConfig = adp.runsInterceptors ? config : await runRequestInterceptors(requestInterceptors, config);
+    const source = adp.request(finalConfig).then(
+      (resp) => {
+        if (resp.status < 200 || resp.status >= 300) {
+          throw new HTTPError(
+            `HTTP ${resp.status} for route "${resp.route}" (${resp.method} ${resp.url})`,
+            {
+              route: resp.route,
+              level: resp.level,
+              status: resp.status,
+              url: resp.url,
+              method: resp.method
+            }
+          );
+        }
+        return resp;
+      },
+      (err) => {
+        if (err instanceof ForgeError) throw err;
+        throw new NetworkError(
+          err instanceof Error ? err.message : String(err),
+          meta.name,
+          meta.level,
+          err
+        );
+      }
+    );
+    if (adp.runsInterceptors) return source;
+    return runResponseInterceptors(responseInterceptors, source);
+  }
+  function invalidate(level) {
+    if (level) cache.del(level);
+    else cache.clear();
+  }
+  void autoDiscoveryPromise.then(() => {
+    if (effectiveEager.length > 0) {
+      void Promise.all(effectiveEager.map((lvl) => load(lvl))).catch((e) => {
+        console.warn(`[route-forge] eager load failed: ${e.message}`);
+      });
+    }
+  }).catch(() => {
+  });
+  return {
+    api,
+    load,
+    route,
+    invalidate,
+    interceptors: {
+      request: requestInterceptors,
+      response: responseInterceptors
+    }
+  };
+}
+function pickMethod(meta) {
+  const m = meta.methods.find((x) => x.toUpperCase() !== "HEAD");
+  return (m ?? meta.methods[0] ?? "GET").toUpperCase();
+}
+function appendQuery(url, query) {
+  if (!query) return url;
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === void 0 || v === null) continue;
+    usp.append(k, String(v));
+  }
+  const qs = usp.toString();
+  if (!qs) return url;
+  return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
+}
+
+export { AdapterNotFoundError, ForgeError, HTTPError, InsufficientAuthError, InterceptorManagerImpl, InvalidInterceptorReturnError, MissingRouteParamError, NetworkError, RouteCache, UnknownLevelError, UnknownRouteError, createInterceptorManager, createRouteForge };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map