@gutil/config 1.0.1 → 2.0.0

package/README.md

@@ -0,0 +1,103 @@
+# @gutil/config
+
+从配置中心（Spring Cloud Config）获取应用配置。
+
+- 无运行时依赖，基于原生 `fetch`，要求 Node.js >= 18
+- 同时提供 CommonJS 和 ESM，自带类型声明
+
+## 安装
+
+```bash
+npm install @gutil/config
+```
+
+## 使用
+
+```ts
+import { Config } from '@gutil/config';
+
+const config = await Config.create({
+	baseUrl: 'https://config.example.com',
+	application: ['user', 'application'],
+	profile: 'dev',
+	label: 'master',
+	auth: {
+		username: process.env.CONFIG_USERNAME!,
+		password: process.env.CONFIG_PASSWORD!,
+	},
+});
+
+config.get('eureka.instance.prefer-ip-address'); // true
+config.get<number>('server.port', { defaultValue: 3000 }); // number
+config.get('host', { prefix: 'eureka' }); // 等价于 get('eureka.host')
+config.get('spring.datasource.url', { application: 'application' });
+config.has('server.port');
+config.all(); // 默认应用的全部配置
+
+await config.reload(); // 重新拉取，失败时保留旧配置
+```
+
+也可以先创建实例再手动加载：
+
+```ts
+const config = new Config(options);
+await config.load(); // 并发调用只会发一次请求
+```
+
+## 选项
+
+| 选项          | 类型                                 | 默认值       | 说明                                                            |
+| ------------- | ------------------------------------ | ------------ | --------------------------------------------------------------- |
+| `baseUrl`     | `string`                             | -            | 配置中心地址                                                    |
+| `application` | `string \| string[]`                 | -            | 应用名称，第一个为默认应用                                      |
+| `profile`     | `string`                             | `'default'`  | 环境，多个用逗号分隔                                            |
+| `label`       | `string`                             | -            | 分支或标签，支持 `release/1.0` 这类带 `/` 的名称                |
+| `auth`        | `{ username, password }`             | -            | Basic 认证，也可以写在 `baseUrl` 中（`https://user:pass@host`） |
+| `headers`     | `Record<string, string>`             | -            | 额外的请求头                                                    |
+| `timeout`     | `number`                             | `10000`      | 单次请求超时（毫秒）                                            |
+| `retries`     | `number`                             | `0`          | 网络错误或 5xx 时的重试次数                                     |
+| `retryDelay`  | `number`                             | `1000`       | 重试间隔（毫秒）                                                |
+| `coerce`      | `boolean \| (value, key) => unknown` | `true`       | 是否把字符串转换为布尔、数字、`null`                            |
+| `fetch`       | `typeof fetch`                       | 全局 `fetch` | 自定义请求函数，可用于测试或代理                                |
+
+默认的类型转换规则：`"true"` / `"false"` 转为布尔值，`"null"` 转为 `null`，`"-1"`、`"1.5"` 这类十进制数字转为数字；`"007"` 和超出安全整数范围的数字保留为字符串。
+
+同一个 key 在多个配置文件中出现时，以配置中心的优先级为准（例如 `user-dev.yml` 优先于 `user.yml`）。
+
+所有错误都会抛出 `ConfigError`，HTTP 错误带有 `status` 字段，底层错误在 `cause` 中。
+
+## 从 1.x 升级
+
+| 1.x                             | 2.0                         |
+| ------------------------------- | --------------------------- |
+| `applicationNames`              | `application`               |
+| `branch`                        | `label`                     |
+| `auth.userName`                 | `auth.username`             |
+| `get(key, { applicationName })` | `get(key, { application })` |
+| `get(key, { keyPrefix })`       | `get(key, { prefix })`      |
+| `ConfigException`               | `ConfigError`               |
+
+行为变化：
+
+- 环境配置（如 `user-dev.yml`）现在会正确覆盖通用配置（如 `user.yml`），1.x 中是反的。
+- 支持 `.yml` 后缀的配置文件，1.x 只识别 `.yaml` 和 `.properties`。
+- 负数、小数会转换为数字；`"007"` 和超大整数不再转换。
+- 不再依赖 rxjs，最低 Node.js 版本为 18。
+
+## 开发
+
+```bash
+npm install
+npm test           # 单元测试
+npm run typecheck
+npm run build
+```
+
+连接真实配置中心的集成测试默认跳过，设置环境变量后运行：
+
+```bash
+CONFIG_BASE_URL=https://config.example.com CONFIG_APPLICATION=application \
+CONFIG_PROFILE=dev CONFIG_USERNAME=xxx CONFIG_PASSWORD=xxx npm test
+```
+
+发布：`npm publish`（会自动执行类型检查、测试和构建）。

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+interface BasicAuth {
+    username: string;
+    password: string;
+}
+type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
+type CoerceFn = (value: unknown, key: string) => unknown;
+interface ConfigOptions {
+    /** 配置中心地址，例如 https://config.example.com */
+    baseUrl: string;
+    /** 应用名称，多个应用时第一个为默认应用 */
+    application: string | string[];
+    /** 环境，多个环境用逗号分隔，默认 default */
+    profile?: string;
+    /** 分支 / 标签，例如 master、release/1.0 */
+    label?: string;
+    auth?: BasicAuth;
+    headers?: Record<string, string>;
+    /** 单次请求超时时间（毫秒），默认 10000 */
+    timeout?: number;
+    /** 失败重试次数，默认 0；4xx 响应不重试 */
+    retries?: number;
+    /** 重试间隔（毫秒），默认 1000 */
+    retryDelay?: number;
+    /**
+     * 配置值类型转换，默认 true：把 "true" / "false" / "null" / 数字字符串转换为对应类型。
+     * 传 false 保留原始值，或传入自定义函数。
+     */
+    coerce?: boolean | CoerceFn;
+    /** 自定义请求函数，默认使用全局 fetch */
+    fetch?: FetchFn;
+}
+interface GetOptions<T> {
+    /** 应用名称，默认为第一个应用 */
+    application?: string;
+    /** key 前缀，例如 get('host', { prefix: 'eureka' }) 等价于 get('eureka.host') */
+    prefix?: string;
+    defaultValue?: T;
+}
+type ConfigValues = Record<string, unknown>;
+interface PropertySource {
+    name: string;
+    source?: Record<string, unknown>;
+}
+interface Environment {
+    name?: string;
+    profiles?: string[];
+    label?: string | null;
+    version?: string | null;
+    propertySources?: PropertySource[];
+}
+
+declare class Config {
+    private readonly client;
+    private readonly applications;
+    private readonly profiles;
+    private readonly coerce?;
+    private data;
+    private pending;
+    /** 创建实例并完成首次加载 */
+    static create(options: ConfigOptions): Promise<Config>;
+    constructor(options: ConfigOptions);
+    get loaded(): boolean;
+    /** 加载配置，已加载时不会重复请求 */
+    load(): Promise<void>;
+    /** 重新拉取配置；失败时保留之前的配置 */
+    reload(): Promise<void>;
+    get<T = unknown>(key: string, options: GetOptions<T> & {
+        defaultValue: T;
+    }): T;
+    get<T = unknown>(key: string, options?: GetOptions<T>): T | undefined;
+    has(key: string, application?: string): boolean;
+    /** 获取某个应用的全部配置 */
+    all(application?: string): Readonly<ConfigValues>;
+    private values;
+    private refresh;
+}
+
+declare class ConfigError extends Error {
+    readonly status?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+
+/**
+ * 配置中心返回的值大多是字符串，这里转换成对应的类型。
+ * 超出安全整数范围的数字保留为字符串，避免丢失精度。
+ */
+declare function coerceValue(value: unknown): unknown;
+
+export { type BasicAuth, type CoerceFn, Config, ConfigError, type ConfigOptions, type ConfigValues, type Environment, type FetchFn, type GetOptions, type PropertySource, coerceValue };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+interface BasicAuth {
+    username: string;
+    password: string;
+}
+type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
+type CoerceFn = (value: unknown, key: string) => unknown;
+interface ConfigOptions {
+    /** 配置中心地址，例如 https://config.example.com */
+    baseUrl: string;
+    /** 应用名称，多个应用时第一个为默认应用 */
+    application: string | string[];
+    /** 环境，多个环境用逗号分隔，默认 default */
+    profile?: string;
+    /** 分支 / 标签，例如 master、release/1.0 */
+    label?: string;
+    auth?: BasicAuth;
+    headers?: Record<string, string>;
+    /** 单次请求超时时间（毫秒），默认 10000 */
+    timeout?: number;
+    /** 失败重试次数，默认 0；4xx 响应不重试 */
+    retries?: number;
+    /** 重试间隔（毫秒），默认 1000 */
+    retryDelay?: number;
+    /**
+     * 配置值类型转换，默认 true：把 "true" / "false" / "null" / 数字字符串转换为对应类型。
+     * 传 false 保留原始值，或传入自定义函数。
+     */
+    coerce?: boolean | CoerceFn;
+    /** 自定义请求函数，默认使用全局 fetch */
+    fetch?: FetchFn;
+}
+interface GetOptions<T> {
+    /** 应用名称，默认为第一个应用 */
+    application?: string;
+    /** key 前缀，例如 get('host', { prefix: 'eureka' }) 等价于 get('eureka.host') */
+    prefix?: string;
+    defaultValue?: T;
+}
+type ConfigValues = Record<string, unknown>;
+interface PropertySource {
+    name: string;
+    source?: Record<string, unknown>;
+}
+interface Environment {
+    name?: string;
+    profiles?: string[];
+    label?: string | null;
+    version?: string | null;
+    propertySources?: PropertySource[];
+}
+
+declare class Config {
+    private readonly client;
+    private readonly applications;
+    private readonly profiles;
+    private readonly coerce?;
+    private data;
+    private pending;
+    /** 创建实例并完成首次加载 */
+    static create(options: ConfigOptions): Promise<Config>;
+    constructor(options: ConfigOptions);
+    get loaded(): boolean;
+    /** 加载配置，已加载时不会重复请求 */
+    load(): Promise<void>;
+    /** 重新拉取配置；失败时保留之前的配置 */
+    reload(): Promise<void>;
+    get<T = unknown>(key: string, options: GetOptions<T> & {
+        defaultValue: T;
+    }): T;
+    get<T = unknown>(key: string, options?: GetOptions<T>): T | undefined;
+    has(key: string, application?: string): boolean;
+    /** 获取某个应用的全部配置 */
+    all(application?: string): Readonly<ConfigValues>;
+    private values;
+    private refresh;
+}
+
+declare class ConfigError extends Error {
+    readonly status?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+
+/**
+ * 配置中心返回的值大多是字符串，这里转换成对应的类型。
+ * 超出安全整数范围的数字保留为字符串，避免丢失精度。
+ */
+declare function coerceValue(value: unknown): unknown;
+
+export { type BasicAuth, type CoerceFn, Config, ConfigError, type ConfigOptions, type ConfigValues, type Environment, type FetchFn, type GetOptions, type PropertySource, coerceValue };

package/dist/index.js

@@ -0,0 +1,276 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Config: () => Config,
+  ConfigError: () => ConfigError,
+  coerceValue: () => coerceValue
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_promises = require("timers/promises");
+
+// src/errors.ts
+var ConfigError = class extends Error {
+  status;
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "ConfigError";
+    this.status = options.status;
+  }
+};
+
+// src/client.ts
+function parseBaseUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch (error) {
+    throw new ConfigError("Invalid `baseUrl`", { cause: error });
+  }
+  const auth = url.username ? {
+    username: decodeURIComponent(url.username),
+    password: decodeURIComponent(url.password)
+  } : void 0;
+  url.username = "";
+  url.password = "";
+  return { baseUrl: url.toString().replace(/\/+$/, ""), auth };
+}
+function buildUrl(baseUrl, applications, profiles, label) {
+  const segments = [
+    applications.map(encodeURIComponent).join(","),
+    profiles.map(encodeURIComponent).join(",")
+  ];
+  if (label) segments.push(encodeURIComponent(label.replace(/\//g, "(_)")));
+  return `${baseUrl.replace(/\/+$/, "")}/${segments.join("/")}`;
+}
+function buildHeaders(options) {
+  const headers = {
+    Accept: "application/json",
+    ...options.headers
+  };
+  const { auth } = options;
+  if (auth?.username) {
+    const token = Buffer.from(
+      `${auth.username}:${auth.password ?? ""}`
+    ).toString("base64");
+    headers.Authorization = `Basic ${token}`;
+  }
+  return headers;
+}
+function isTimeout(error) {
+  return error?.name === "TimeoutError";
+}
+async function requestOnce(url, options) {
+  const timeoutMessage = `Request to ${url} timed out after ${options.timeout}ms`;
+  let response;
+  try {
+    response = await options.fetch(url, {
+      method: "GET",
+      headers: buildHeaders(options),
+      signal: AbortSignal.timeout(options.timeout)
+    });
+  } catch (error) {
+    const message = isTimeout(error) ? timeoutMessage : `Request to ${url} failed: ${error?.message ?? String(error)}`;
+    throw new ConfigError(message, { cause: error });
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => void 0);
+    throw new ConfigError(
+      `Request to ${url} failed with status ${response.status}`,
+      {
+        status: response.status
+      }
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    const message = isTimeout(error) ? timeoutMessage : `Invalid JSON response from ${url}`;
+    throw new ConfigError(message, { cause: error });
+  }
+  if (!body || typeof body !== "object" || body.propertySources !== void 0 && !Array.isArray(body.propertySources)) {
+    throw new ConfigError(`Unexpected response from ${url}`);
+  }
+  return body;
+}
+function isRetryable(error) {
+  const status = error instanceof ConfigError ? error.status : void 0;
+  return status === void 0 || status >= 500;
+}
+async function fetchEnvironment(options) {
+  const url = buildUrl(
+    options.baseUrl,
+    options.applications,
+    options.profiles,
+    options.label
+  );
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await requestOnce(url, options);
+    } catch (error) {
+      if (attempt >= options.retries || !isRetryable(error)) throw error;
+      await (0, import_promises.setTimeout)(options.retryDelay);
+    }
+  }
+}
+
+// src/coerce.ts
+var NUMBER_PATTERN = /^-?(0|[1-9]\d*)(\.\d+)?$/;
+function coerceValue(value) {
+  if (typeof value !== "string") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (NUMBER_PATTERN.test(value)) {
+    const num = Number(value);
+    if (Number.isInteger(num) && !Number.isSafeInteger(num)) return value;
+    return num;
+  }
+  return value;
+}
+
+// src/parser.ts
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matchesApplication(sourceName, application, profiles) {
+  const profilePart = profiles.length ? `(?:-(?:${profiles.map(escapeRegExp).join("|")}))?` : "";
+  const pattern = new RegExp(
+    `(?:^|[/\\\\\\[\\s'":])${escapeRegExp(application)}${profilePart}\\.(?:ya?ml|properties)(?:$|[\\]\\s'"])`
+  );
+  return pattern.test(sourceName);
+}
+function parseEnvironment(env, applications, profiles, coerce) {
+  const result = /* @__PURE__ */ new Map();
+  for (const application of applications) {
+    const values = /* @__PURE__ */ Object.create(null);
+    for (const { name, source } of env.propertySources ?? []) {
+      if (!source || !matchesApplication(name, application, profiles))
+        continue;
+      for (const [key, raw] of Object.entries(source)) {
+        if (Object.hasOwn(values, key)) continue;
+        values[key] = coerce ? coerce(raw, key) : raw;
+      }
+    }
+    result.set(application, values);
+  }
+  return result;
+}
+
+// src/config.ts
+var Config = class _Config {
+  client;
+  applications;
+  profiles;
+  coerce;
+  data = null;
+  pending = null;
+  /** 创建实例并完成首次加载 */
+  static async create(options) {
+    const config = new _Config(options);
+    await config.load();
+    return config;
+  }
+  constructor(options) {
+    const applications = [options.application].flat().filter(Boolean);
+    if (!options.baseUrl) throw new ConfigError("`baseUrl` is required");
+    if (!applications.length)
+      throw new ConfigError("`application` is required");
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    if (typeof fetchFn !== "function") {
+      throw new ConfigError(
+        "Global fetch is not available, please pass `fetch` option"
+      );
+    }
+    const profiles = (options.profile ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+    if (!profiles.length) profiles.push("default");
+    const { baseUrl, auth: urlAuth } = parseBaseUrl(options.baseUrl);
+    this.applications = applications;
+    this.profiles = profiles;
+    this.coerce = options.coerce === false ? void 0 : typeof options.coerce === "function" ? options.coerce : coerceValue;
+    this.client = {
+      baseUrl,
+      applications,
+      profiles,
+      label: options.label,
+      auth: options.auth ?? urlAuth,
+      headers: options.headers,
+      timeout: options.timeout ?? 1e4,
+      retries: options.retries ?? 0,
+      retryDelay: options.retryDelay ?? 1e3,
+      fetch: fetchFn
+    };
+  }
+  get loaded() {
+    return this.data !== null;
+  }
+  /** 加载配置，已加载时不会重复请求 */
+  load() {
+    if (this.data) return Promise.resolve();
+    return this.refresh();
+  }
+  /** 重新拉取配置；失败时保留之前的配置 */
+  reload() {
+    return this.refresh();
+  }
+  get(key, options = {}) {
+    const values = this.values(options.application);
+    const fullKey = options.prefix ? `${options.prefix}.${key}` : key;
+    return Object.hasOwn(values, fullKey) ? values[fullKey] : options.defaultValue;
+  }
+  has(key, application) {
+    return Object.hasOwn(this.values(application), key);
+  }
+  /** 获取某个应用的全部配置 */
+  all(application) {
+    return { ...this.values(application) };
+  }
+  values(application = this.applications[0]) {
+    if (!this.data)
+      throw new ConfigError("Config is not loaded, call `load()` first");
+    const values = this.data.get(application);
+    if (!values)
+      throw new ConfigError(`Unknown application "${application}"`);
+    return values;
+  }
+  refresh() {
+    this.pending ??= fetchEnvironment(this.client).then((env) => {
+      this.data = parseEnvironment(
+        env,
+        this.applications,
+        this.profiles,
+        this.coerce
+      );
+    }).finally(() => {
+      this.pending = null;
+    });
+    return this.pending;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Config,
+  ConfigError,
+  coerceValue
+});