@nsnanocat/preference-panes 0.2.0 → 0.3.0

package/package.json

@@ -1,66 +1,66 @@
 {
-  "name": "@nsnanocat/preference-panes",
-  "version": "0.2.0",
-  "description": "Shared settings API runtime for JavaScript proxy modules",
-  "author": "VirgilClyne <Virgil@nanocat.me>",
-  "homepage": "https://NSNanoCat.github.io/preference-panes",
-  "keywords": [
-    "loon",
-    "quantumult",
-    "surge",
-    "shadowrocket",
-    "stash",
-    "egern",
-    "settings"
-  ],
-  "license": "Apache-2.0",
-  "bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
-  "type": "module",
-  "main": "src/index.mjs",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.mjs"
-    },
-    "./browser": {
-      "types": "./src/browser/index.d.ts",
-      "import": "./src/browser/index.mjs"
-    },
-    "./browser/panel.css": "./src/browser/panel.css",
-    "./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
-    "./dist/preference-panes.request.js": "./dist/preference-panes.request.js"
-  },
-  "types": "src/index.d.ts",
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "check": "npm run lint && npm run typecheck && npm test",
-    "lint": "biome check .",
-    "format": "biome check --write .",
-    "typecheck": "tsc --noEmit",
-    "build": "rollup -c",
-    "prepack": "npm run build",
-    "apifox:generate": "node apifox/generate.mjs",
-    "apifox:check": "node apifox/generate.mjs --check"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
-  },
-  "files": [
-    "src",
-    "dist"
-  ],
-  "dependencies": {
-    "@nsnanocat/url": "^1.2.6",
-    "@nsnanocat/util": "^2.7.4"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "2.4.6",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "rollup": "^4.63.1",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+	"name": "@nsnanocat/preference-panes",
+	"version": "0.3.0",
+	"description": "Shared settings API runtime for JavaScript proxy modules",
+	"author": "VirgilClyne <Virgil@nanocat.me>",
+	"homepage": "https://NSNanoCat.github.io/preference-panes",
+	"keywords": [
+		"loon",
+		"quantumult",
+		"surge",
+		"shadowrocket",
+		"stash",
+		"egern",
+		"settings"
+	],
+	"license": "Apache-2.0",
+	"bugs": "https://github.com/NSNanoCat/PreferencePanes/issues",
+	"type": "module",
+	"main": "src/index.mjs",
+	"exports": {
+		".": {
+			"types": "./src/index.d.ts",
+			"import": "./src/index.mjs"
+		},
+		"./browser": {
+			"types": "./src/browser/index.d.ts",
+			"import": "./src/browser/index.mjs"
+		},
+		"./browser/panel.css": "./src/browser/panel.css",
+		"./dist/preference-panes.mjs": "./dist/preference-panes.mjs",
+		"./dist/preference-panes.request.js": "./dist/preference-panes.request.js"
+	},
+	"types": "src/index.d.ts",
+	"scripts": {
+		"test": "node --test test/*.test.mjs",
+		"check": "npm run lint && npm run typecheck && npm test",
+		"lint": "biome check .",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit",
+		"build": "rollup -c",
+		"prepack": "npm run build",
+		"apifox:generate": "node apifox/generate.mjs",
+		"apifox:check": "node apifox/generate.mjs --check"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/NSNanoCat/PreferencePanes.git"
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"dependencies": {
+		"@nsnanocat/url": "^1.2.6",
+		"@nsnanocat/util": "^2.7.4"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.6",
+		"@rollup/plugin-node-resolve": "^16.0.3",
+		"rollup": "^4.63.1",
+		"typescript": "^5.9.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }

package/src/SettingsHandler.mjs

@@ -1,138 +1,142 @@
 import { URL } from "@nsnanocat/url";
-import { fetch } from "@nsnanocat/util/polyfill/fetch";
 import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
 import { Storage } from "@nsnanocat/util/polyfill/Storage";
-import { normalizeBoxJs, validValue } from "./lib/boxjs.mjs";
-import { parseSettingsPath } from "./lib/settings-path.mjs";
+import { parseSettingsPathname, validatePathParts } from "./lib/settings-path.mjs";
 
 /**
- * 使用 util 下载 BoxJS、校验字段并读写持久化存储。
- * Download BoxJS through util, validate fields and handle persistent storage.
+ * 按插件声明的根和模块桥接持久化存储，不下载或解析 BoxJS。
+ * Bridge persistence within the installed root and module without downloading or parsing BoxJS.
  */
 export class SettingsHandler {
-  #origin;
-  #configURL;
-  #requestHeader;
-  #resolveSettings;
+	/** @type {string} 接管来源 / Handled origin. */
+	#origin;
+	/** @type {string} 安装配置中的存储根 / Storage root from installation config. */
+	#storageKey;
+	/** @type {string} 安装配置中的模块 / Module from installation config. */
+	#module;
+	/** @type {string} 页面标记头 / Page marker header. */
+	#requestHeader;
 
-  /** @param {import("./index.js").SettingsHandlerOptions} options 来源、配置地址与 GET 解析器 / Origin, config source and GET resolver. */
-  constructor({ origin, configURL, requestHeader = "X-Settings-Client", resolveSettings }) {
-    const target = new URL(origin);
-    if (target.protocol !== "https:" || target.pathname !== "/" || target.search || target.hash || target.username || target.password)
-      throw new TypeError("origin must be an HTTPS origin");
-    const source = new URL(configURL);
-    if (source.protocol !== "https:" || source.username || source.password || source.hash)
-      throw new TypeError("configURL must be an HTTPS URL without credentials or fragment");
-    if (!/^[a-z][a-z0-9-]*$/i.test(requestHeader)) throw new TypeError("Invalid requestHeader");
-    this.#origin = target.origin;
-    this.#configURL = source.href;
-    this.#requestHeader = requestHeader;
-    this.#resolveSettings = resolveSettings;
-  }
+	/**
+	 * 固定来源、存储根和模块，构造时不访问网络或存储。
+	 * Fix the origin, storage root and module without network or storage access at construction.
+	 * @param {import("./index.js").SettingsHandlerOptions} options 插件安装配置 / Plugin installation config.
+	 * @throws {TypeError} 安装配置无效 / Invalid installation config.
+	 */
+	constructor({ origin, storageKey, module, requestHeader = "X-Settings-Client" }) {
+		const target = new URL(origin);
+		if (target.protocol !== "https:" || target.pathname !== "/" || target.search || target.hash || target.username || target.password) throw new TypeError("origin must be an HTTPS origin");
+		if (typeof storageKey !== "string" || !storageKey || storageKey.startsWith("@")) throw new TypeError("storageKey must be a literal root key");
+		validatePathParts([module]);
+		if (!/^[a-z][a-z0-9-]*$/i.test(requestHeader)) throw new TypeError("Invalid requestHeader");
+		this.#origin = target.origin;
+		this.#storageKey = storageKey;
+		this.#module = module;
+		this.#requestHeader = requestHeader;
+	}
 
-  async #loadConfig(module) {
-    const response = await fetch({ url: this.#configURL, method: "GET", headers: { "Cache-Control": "no-cache" }, timeout: 5000 });
-    if (response.status !== 200) throw new Error(`BoxJS source HTTP ${response.status}`);
-    return normalizeBoxJs(JSON.parse(response.body), module);
-  }
-
-  /**
-   * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
-   * @returns {Promise<import("./index.js").SettingsResponse | undefined>} API 响应，非本来源 API 则不处理 / API response, or undefined outside the configured API origin.
-   */
-  async handle(request) {
-    const url = new URL(request.url);
-    if (url.origin !== this.#origin || !url.pathname.startsWith("/api/")) return;
-    const headers = { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" };
-    const reply = (status, data) => ({ status, headers, body: request.method === "HEAD" ? "" : JSON.stringify(data) });
-    let parts;
-    try {
-      parts = parseSettingsPath(request.url);
-    } catch (error) {
-      return reply(400, { error: error.message });
-    }
-    const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-    if (requestHeaders[this.#requestHeader.toLowerCase()] !== "1" || (requestHeaders.origin && requestHeaders.origin !== this.#origin))
-      return reply(403, { error: "Forbidden settings client" });
-    if (!["HEAD", "GET", "POST", "DELETE"].includes(request.method))
-      return { ...reply(405, { error: "Method not allowed" }), headers: { ...headers, Allow: "HEAD, GET, POST, DELETE" } };
-    let definition;
-    try {
-      definition = await this.#loadConfig(parts[0]);
-    } catch (error) {
-      return reply(502, { error: `Module configuration unavailable: ${error.message}` });
-    }
-    const key = parts.join(".");
-    const field = definition.fields.find((field) => field.key === key);
-    const descendants = definition.fields.filter((field) => field.key.startsWith(`${key}.`));
-    if (!field && !descendants.length) return reply(404, { error: `Unknown setting path: ${key}` });
-    if (request.method === "HEAD") return reply(200, undefined);
-    if (request.method === "GET") {
-      const stored = Storage.getItem(definition.storageKey, {});
-      const effective = this.#resolveSettings ? this.#resolveSettings(stored, definition) : stored;
-      if (!isRecord(effective)) throw new TypeError("resolved settings must be a synchronous object");
-      if (field) {
-        const value = pathValue(effective, parts);
-        return value === undefined ? reply(404, { error: `Setting has no stored value: ${key}` }) : reply(200, value);
-      }
-      const subtree = {};
-      // 只返回配置文件公开的字段；默认值由浏览器用 BoxJS val 生成。
-      // Expose only declared fields; the browser renders defaults from BoxJS val.
-      for (const descendant of descendants) {
-        const fullPath = descendant.key.split(".");
-        const value = pathValue(effective, fullPath);
-        if (value !== undefined) _.set(subtree, fullPath.slice(parts.length), value);
-      }
-      return reply(200, subtree);
-    }
-    if (!field) return reply(405, { error: "Only individual declared keys can be modified" });
-    let value;
-    if (request.method === "POST") {
-      if (requestHeaders["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json")
-        return reply(415, { error: "Expected application/json" });
-      if (typeof request.body !== "string") return reply(400, { error: "Expected a JSON string body" });
-      if (request.body.length > 65536) return reply(413, { error: "Body exceeds 65536 UTF-16 code units" });
-      try {
-        value = JSON.parse(request.body);
-      } catch {
-        return reply(400, { error: "Invalid JSON" });
-      }
-      if (!validValue(field, value)) return reply(400, { error: `Invalid setting value: ${key}` });
-    }
-    const saved = Storage.getItem(definition.storageKey, {});
-    if (!isRecord(saved)) throw new TypeError("stored settings must be an object");
-    const parent = settingsParent(saved, parts, request.method === "POST");
-    if (parent) {
-      if (request.method === "DELETE") _.unset(parent, [parts.at(-1)]);
-      else _.set(parent, [parts.at(-1)], value);
-    }
-    if (!Storage.setItem(definition.storageKey, saved)) return reply(500, { error: "Settings storage write failed" });
-    return reply(200, request.method === "DELETE" ? { deleted: true } : { saved: true });
-  }
+	/**
+	 * GET 返回指定值，POST 替换指定值，DELETE 删除指定键或整个模块。
+	 * GET returns a value, POST replaces it, and DELETE removes a key or the entire module.
+	 * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+	 * @returns {Promise<import("./index.js").SettingsResponse | undefined>} 响应或非接管请求 / Response, or undefined for an unhandled request.
+	 */
+	async handle(request) {
+		const url = new URL(request.url);
+		if (url.origin !== this.#origin || !url.pathname.startsWith("/api/")) return;
+		const headers = { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" };
+		const reply = (status, data) => ({ status, headers, body: request.method === "HEAD" ? "" : JSON.stringify(data) });
+		let parts;
+		try {
+			parts = parseSettingsPathname(url.pathname);
+		} catch (error) {
+			return reply(400, { error: error.message });
+		}
+		if (parts[0] !== this.#module) return reply(404, { error: "Module is not handled" });
+		const requestHeaders = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+		if (requestHeaders[this.#requestHeader.toLowerCase()] !== "1" || (requestHeaders.origin && requestHeaders.origin !== this.#origin)) return reply(403, { error: "Forbidden settings client" });
+		let value;
+		switch (request.method) {
+			case "HEAD":
+				return reply(200, undefined);
+			case "GET":
+			case "DELETE":
+				break;
+			case "POST":
+				if (requestHeaders["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") return reply(415, { error: "Expected application/json" });
+				if (typeof request.body !== "string") return reply(400, { error: "Expected a JSON string body" });
+				if (request.body.length > 65536) return reply(413, { error: "Body exceeds 65536 UTF-16 code units" });
+				try {
+					value = JSON.parse(request.body);
+				} catch {
+					return reply(400, { error: "Invalid JSON" });
+				}
+				break;
+			default:
+				return { ...reply(405, { error: "Method not allowed" }), headers: { ...headers, Allow: "HEAD, GET, POST, DELETE" } };
+		}
+		try {
+			const root = Storage.getItem(this.#storageKey, {});
+			if (!isRecord(root)) throw new TypeError("stored root must be an object");
+			const parent = storageParent(root, parts, request.method === "POST");
+			const key = parts.at(-1);
+			switch (request.method) {
+				case "GET": {
+					const result = parent ? _.get(parent, [key]) : undefined;
+					return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
+				}
+				case "POST":
+					_.set(parent, [key], value);
+					break;
+				case "DELETE":
+					if (parent) _.unset(parent, [key]);
+					break;
+			}
+			if (!Storage.setItem(this.#storageKey, root)) throw new Error("Storage write failed");
+			return reply(200, request.method === "POST" ? { saved: true } : { deleted: true });
+		} catch (error) {
+			return reply(500, { error: error.message });
+		}
+	}
 }
 
+/**
+ * 判断根节点是否为普通对象。
+ * Determine whether a root node is a plain object.
+ * @param {unknown} value 待检查值 / Value to inspect.
+ * @returns {boolean} 是否为普通对象 / Whether this is a plain object.
+ */
 function isRecord(value) {
-  return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+	return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
 }
 
-function pathValue(root, parts) {
-  const parent = settingsParent(root, parts, false);
-  return parent ? _.get(parent, [parts.at(-1)]) : undefined;
-}
-
-// util 的 @root.path 允许序列化中间对象；统一解码并保留相邻键。
-// Decode util-serialized intermediate objects while retaining sibling keys.
-function settingsParent(root, parts, create) {
-  let parent = root;
-  for (const part of parts.slice(0, -1)) {
-    let next = _.get(parent, [part]);
-    if (next === undefined) {
-      if (!create) return;
-      next = {};
-    } else if (typeof next === "string") next = JSON.parse(next);
-    if (!isRecord(next)) throw new TypeError(`Stored path is not an object: ${part}`);
-    _.set(parent, [part], next);
-    parent = next;
-  }
-  return parent;
+/**
+ * 遍历父路径，兼容旧存储中 JSON 字符串形式的中间节点。
+ * Traverse parents, supporting legacy intermediate nodes serialized as JSON strings.
+ * @param {Record<string, unknown>} root 存储根 / Storage root.
+ * @param {string[]} parts 完整路径 / Complete path.
+ * @param {boolean} create 是否创建缺失节点 / Whether to create missing parents.
+ * @returns {object | undefined} 父节点，缺失且不创建时为 undefined / Parent, or undefined when absent and not creating.
+ * @throws {TypeError} 无法继续遍历标量节点 / A scalar node cannot be traversed.
+ */
+function storageParent(root, parts, create) {
+	let parent = root;
+	for (const part of parts.slice(0, -1)) {
+		let next = _.get(parent, [part]);
+		switch (typeof next) {
+			case "undefined":
+				if (!create) return;
+				next = {};
+				break;
+			case "string":
+				next = JSON.parse(next);
+				break;
+			default:
+				break;
+		}
+		if (!isRecord(next) && !Array.isArray(next)) throw new TypeError("Stored parent is not an object or array");
+		_.set(parent, [part], next);
+		parent = next;
+	}
+	return parent;
 }