@nsnanocat/preference-panes 1.1.1 → 1.1.3

package/src/api.mjs

@@ -1,15 +1,13 @@
 import { URL } from "@nsnanocat/url";
-import { fetch as transport } from "@nsnanocat/util";
 import { $app } from "@nsnanocat/util/lib/app.mjs";
 import { done } from "@nsnanocat/util/lib/done.mjs";
+import { Lodash as _ } from "@nsnanocat/util/polyfill/Lodash.mjs";
 import { Storage } from "@nsnanocat/util/polyfill/Storage";
 import { validatePathParts } from "./lib/settings-path.mjs";
 
-const MISSING = Symbol("missing");
-
 /**
- * PreferencePanes 后端 API，只处理模块数据和持久化请求。
- * PreferencePanes backend API handling only module data and persistence requests.
+ * PreferencePanes 后端 API，只提供通用持久化操作。
+ * PreferencePanes backend API providing generic persistence operations only.
  */
 class API {
     /**
@@ -31,141 +29,124 @@ class API {
     }
 
     /**
-     * 处理 `/api/{module}` 及其动作，不接管页面或静态资源。
-     * Handle `/api/{module}` and its actions without intercepting pages or static assets.
+     * 处理固定存储动作，不接管模块配置、页面或静态资源。
+     * Handle fixed storage actions without intercepting module configurations, pages, or static assets.
      * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
      * @returns {Promise<import("./index.js").SettingsResponse | undefined>} API 响应或未接管 / API response or pass-through.
      */
     async handle(request) {
         const url = new URL(request.url);
-        const match = /^\/api\/([a-zA-Z0-9_-]+)(?:\/(get|set|delete))?\/?$/.exec(url.pathname);
-        if (!match) return;
-        const [, module, action] = match;
-        const configuration = `${url.origin}/configs/${module}`;
-        switch (true) {
-            case !action && request.method === "HEAD":
-                return this.#probe(request, configuration);
-            case Boolean(action) && request.method === "POST":
-                return this.#action(request, module, action, configuration);
-            default:
-                return this.#response(request, 405, { error: "Use HEAD for module probes and POST for module actions" });
-        }
+        const action = /^\/api\/(get|set|delete)$/.exec(url.pathname)?.[1];
+        if (action) return this.#store(request, action);
+        return;
     }
 
-    async #probe(request, configuration) {
-        let result;
+    /**
+     * 使用唯一 form 字段中的完整 @root.path 执行存储操作。
+     * Execute a storage operation using the complete @root.path from the sole form field.
+     * @param {import("./index.js").SettingsRequest} request 代理请求 / Proxy request.
+     * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+     * @returns {import("./index.js").SettingsResponse} 操作响应 / Operation response.
+     */
+    #store(request, action) {
+        const reply = (status, data) => this.#response(request, status, data);
+        if (request.method !== "POST") return reply(405, { error: "Use POST with a form body" });
+        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+        if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return reply(415, { error: "Expected application/x-www-form-urlencoded" });
+        if (typeof request.body !== "string" || request.body.length > 65536) return reply(400, { error: "Expected a form body up to 65536 characters" });
+        let parts, value;
         try {
-            result = await transport({ url: configuration, method: "HEAD", timeout: 5000, headers: { Accept: "application/json" } });
+            const fields = request.body.split("&");
+            if (fields.length !== 1) throw new TypeError("Send exactly one storage key");
+            const separator = fields[0].indexOf("=");
+            if (separator < 0) throw new TypeError("Expected @root.path=value");
+            const key = decodeURIComponent(fields[0].slice(0, separator).replace(/\+/g, " "));
+            value = decodeURIComponent(fields[0].slice(separator + 1).replace(/\+/g, " "));
+            if (!key.startsWith("@")) throw new TypeError("Storage keys must start with @");
+            parts = validatePathParts(key.slice(1).split("."));
+            if (parts.length < 2) throw new TypeError("Specify a storage root and child path");
         } catch (error) {
-            return this.#response(request, 502, { error: error.message });
+            return reply(400, { error: error.message });
         }
-        const version = this.#header(result.headers, "x-preferencepanes-version");
-        return this.#response(request, result.statusCode ?? result.status, undefined, version ? { "X-PreferencePanes-Version": version } : {});
-    }
-
-    async #action(request, module, action, configuration) {
-        const payload = this.#jsonBody(request);
-        const target = await this.#load(module, configuration);
-        switch (action) {
-            case "get": {
-                const value = Storage.getItem(payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key), MISSING);
-                return value === MISSING ? this.#response(request, 404, { error: "Stored path does not exist" }) : this.#response(request, 200, value);
-            }
-            case "set":
-                if (!Object.hasOwn(payload ?? {}, "value")) throw Object.assign(new TypeError("A value is required"), { status: 400 });
-                if (!Storage.setItem(this.#storagePath(target, payload.key), payload.value)) throw new Error("Storage write failed");
-                return this.#response(request, 200, { saved: true });
-            case "delete": {
-                const path = payload?.scope ? this.#scopePath(target, payload.scope) : this.#storagePath(target, payload?.key);
-                if (!Storage.removeItem(path)) throw new Error("Storage write failed");
-                return this.#response(request, 200, { deleted: true });
+        if (action === "set") {
+            try {
+                value = JSON.parse(value);
+            } catch (error) {
+                if (!(error instanceof SyntaxError)) throw error;
             }
         }
-    }
-
-    async #load(module, configuration) {
-        let result;
+        const [storageKey, ...path] = parts;
         try {
-            result = await transport({ url: configuration, method: "GET", timeout: 5000, headers: { Accept: "application/json" } });
-        } catch (error) {
-            throw Object.assign(new Error(`Configuration request failed: ${error.message}`), { status: 502 });
-        }
-        const status = result.statusCode ?? result.status;
-        if (status !== 200) throw Object.assign(new Error(`Configuration HTTP ${status}`), { status });
-        try {
-            const body = typeof result.body === "string" ? result.body : new TextDecoder().decode(result.body);
-            const boxjs = JSON.parse(body);
-            const apps = Array.isArray(boxjs) ? [{ settings: boxjs }] : (boxjs.apps ?? [boxjs]);
-            if (!Array.isArray(apps)) throw new TypeError("Expected BoxJS apps array");
-            const entries = [];
-            let storageKey;
-            for (const app of apps) {
-                if (!app || !Array.isArray(app.settings)) throw new TypeError("Expected BoxJS settings array");
-                for (const entry of app.settings) {
-                    if (typeof entry.id !== "string") throw new TypeError("BoxJS settings require string IDs");
-                    if (!entry.id.startsWith("@")) {
-                        if (Array.isArray(boxjs)) throw new TypeError("BoxJS settings require @root.path IDs");
-                        continue;
-                    }
-                    const [root, ...parts] = entry.id.slice(1).split(".");
-                    if (!root || root.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
-                    validatePathParts(parts);
-                    if (parts[0] !== module) continue;
-                    if (storageKey && storageKey !== root) throw new TypeError(`A module must use one storage root: ${module}`);
-                    storageKey = root;
-                    entries.push(entry);
+            const root = Storage.getItem(storageKey, {});
+            if (!isRecord(root)) throw new TypeError("Stored root must be an object");
+            const parent = storageParent(root, path, action === "set");
+            const key = path.at(-1);
+            switch (action) {
+                case "get": {
+                    const result = parent ? _.get(parent, [key]) : undefined;
+                    return result === undefined ? reply(404, { error: "Stored path does not exist" }) : reply(200, result);
                 }
+                case "set":
+                    _.set(parent, [key], value);
+                    break;
+                case "delete":
+                    if (parent) _.unset(parent, [key]);
+                    break;
             }
-            if (!entries.length) throw new TypeError(`No BoxJS settings for module: ${module}`);
-            return { entries, module, storageKey, version: this.#header(result.headers, "x-preferencepanes-version") };
-        } catch (error) {
-            throw Object.assign(new Error(`Invalid BoxJS: ${error.message}`), { status: 422 });
-        }
-    }
-
-    #jsonBody(request) {
-        const headers = Object.fromEntries(Object.entries(request.headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
-        if (headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json") throw Object.assign(new TypeError("Expected application/json"), { status: 415 });
-        if (typeof request.body !== "string" || request.body.length > 65536) throw Object.assign(new TypeError("Expected a JSON body up to 65536 characters"), { status: 400 });
-        try {
-            return JSON.parse(request.body);
+            if (!Storage.setItem(storageKey, root)) throw new Error("Storage write failed");
+            return reply(200, action === "set" ? { saved: true } : { deleted: true });
         } catch (error) {
-            throw Object.assign(error, { status: 400 });
-        }
-    }
-
-    #storagePath(target, key) {
-        if (typeof key !== "string") throw Object.assign(new TypeError("A BoxJS field path is required"), { status: 400 });
-        const path = `@${target.storageKey}.${key}`;
-        if (!target.entries.some(entry => entry.id === path)) throw Object.assign(new TypeError(`Unknown BoxJS field: ${key}`), { status: 400 });
-        return path;
-    }
-
-    #scopePath(target, scope) {
-        switch (scope) {
-            case "settings":
-                return `@${target.storageKey}.${target.module}.Settings`;
-            case "caches":
-                return `@${target.storageKey}.${target.module}.Caches`;
-            case "module":
-                return `@${target.storageKey}.${target.module}`;
-            default:
-                throw Object.assign(new TypeError("Scope must be settings, caches or module"), { status: 400 });
+            return reply(500, { error: error.message });
         }
     }
 
-    #response(request, status, body, extraHeaders = {}) {
+    #response(request, status, body) {
         return {
             status,
-            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", ...extraHeaders },
+            headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" },
             body: request.method === "HEAD" ? "" : JSON.stringify(body),
         };
     }
+}
+
+/**
+ * 判断存储根是否为普通对象。
+ * Determine whether a storage root 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;
+}
 
-    #header(headers, name) {
-        const entry = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === name);
-        return entry?.[1] === undefined ? undefined : String(entry[1]).trim();
+/**
+ * 遍历父路径，并解码旧存储中的 JSON 字符串中间节点。
+ * Traverse parent paths and decode legacy intermediate nodes stored 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 node or undefined.
+ */
+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;
 }
 
 new API().run();

package/src/browser/ModuleStatus.mjs

@@ -76,7 +76,7 @@ export class ModuleStatus extends EventTarget {
             const response = await probeModule(url, { ...options, signal: controller.signal });
             if (controller !== this.#controller) return response;
             const version = response.status === 200 ? response.headers.get("X-PreferencePanes-Version")?.trim() || null : null;
-            this.#render(response.status === 200 ? "installed" : "missing", version);
+            this.#render(version ? "installed" : "missing", version);
             return response;
         } catch (error) {
             if (controller !== this.#controller) return;

package/src/browser/boxjs.mjs

@@ -25,6 +25,7 @@ export function normalizeBoxJs(config, module) {
             if (!storageKey || storageKey.startsWith("@") || parts.length < 2) throw new TypeError("A BoxJS setting must be below a literal storage root and module");
             validatePathParts(parts);
             const name = parts[0];
+            if (["get", "set", "delete"].includes(name)) throw new TypeError(`Reserved API module name: ${name}`);
             let target = modules.get(name);
             if (!target) {
                 target = { module: name, storageKey, entries: [], owners: new Set() };

package/src/browser/client.mjs

@@ -67,7 +67,7 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Settings 内容或 undefined / Settings content or undefined.
      */
     async readSettings() {
-        const response = await this.#send("get", { scope: "settings" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#definition.settingsPath.join(".")}`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -77,7 +77,7 @@ export class PreferencesClient {
      * @returns {Promise<unknown>} Caches 内容或 undefined / Caches content or undefined.
      */
     async readCaches() {
-        const response = await this.#send("get", { scope: "caches" });
+        const response = await this.#send("get", `@${this.#definition.storageKey}.${this.#module}.Caches`);
         return response.status === 404 ? undefined : response.json();
     }
 
@@ -87,7 +87,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     clearCaches() {
-        return this.#change("delete", { scope: "caches" }, "clearCaches");
+        return this.#change("delete", `${this.#module}.Caches`, undefined, "clearCaches");
     }
 
     /**
@@ -96,7 +96,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     reset() {
-        return this.#change("delete", { scope: "module" }, "reset");
+        return this.#change("delete", this.#module, undefined, "reset");
     }
 
     /**
@@ -116,7 +116,7 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     set(key, value) {
-        return this.#change("set", { key, value }, "write", key);
+        return this.#change("set", key, value, "write");
     }
 
     /**
@@ -126,30 +126,31 @@ export class PreferencesClient {
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
     remove(key) {
-        return this.#change("delete", { key }, "delete", key);
+        return this.#change("delete", key, undefined, "delete");
     }
 
     /**
-     * 向模块 API 发送 JSON 动作。
-     * Send a JSON action to the module API.
-     * @param {"get" | "set" | "delete"} action 模块动作 / Module action.
-     * @param {unknown} payload JSON 请求体 / JSON request body.
+     * 向固定存储 API 发送完整路径的 form 动作。
+     * Send a complete-path form action to the fixed storage API.
+     * @param {"get" | "set" | "delete"} action 存储动作 / Storage action.
+     * @param {string} path 完整 @root.path / Complete @root.path.
+     * @param {unknown} [value] set 写入值 / Value written by set.
      * @returns {Promise<Response>} 原始响应 / Raw response.
      */
-    async #send(action, payload) {
+    async #send(action, path, value) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         if (this.#session.signal.aborted) abort();
         this.#session.signal.addEventListener("abort", abort, { once: true });
         const timer = setTimeout(abort, this.#timeout);
         try {
-            const response = await this.#request(`/api/${encodeURIComponent(this.#module)}/${action}`, {
+            const response = await this.#request(`/api/${action}`, {
                 method: "POST",
                 credentials: "omit",
                 cache: "no-store",
                 signal: controller.signal,
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify(payload),
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams([[path, action === "set" ? JSON.stringify(value) : ""]]).toString(),
             });
             if (response.status !== 200 && !(action === "get" && response.status === 404)) throw new Error(`HTTP ${response.status}`);
             return response;
@@ -163,28 +164,28 @@ export class PreferencesClient {
      * 执行写入动作；成功后只更新当前页面值。
      * Execute a mutation and update only the current page values after success.
      * @param {"set" | "delete"} action API 动作 / API action.
-     * @param {Record<string, unknown>} payload JSON 请求体 / JSON request body.
+     * @param {string} key 不含存储根的路径 / Path without the storage root.
+     * @param {unknown} value set 写入值 / Value written by set.
      * @param {"write" | "delete" | "clearCaches" | "reset"} operation 通知操作 / Notification operation.
-     * @param {string} [key] 字段路径 / Field path.
      * @returns {Promise<void>} 操作完成 / Operation completion.
      */
-    async #change(action, payload, operation, key) {
+    async #change(action, key, value, operation) {
         if (this.#saving) throw new Error("A settings write is already in progress");
         this.#saving = true;
         try {
-            if (operation === "write") {
-                const field = this.#definition.fields.find(candidate => candidate.key === key);
-                if (!field || !validValue(field, payload.value)) throw new TypeError("Invalid setting value");
+            let field;
+            if (operation === "write" || operation === "delete") {
+                field = this.#definition.fields.find(candidate => candidate.key === key);
+                if (!field || (operation === "write" && !validValue(field, value))) throw new TypeError("Invalid setting value");
             }
-            await this.#send(action, payload);
+            await this.#send(action, `@${this.#definition.storageKey}.${key}`, value);
             switch (operation) {
                 case "write":
-                    this.#values[key] = structuredClone(payload.value);
+                    this.#values[key] = structuredClone(value);
                     break;
                 case "delete": {
-                    const field = this.#definition.fields.find(candidate => candidate.key === key);
                     delete this.#values[key];
-                    if (field && Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
+                    if (Object.hasOwn(field, "defaultValue")) this.#values[key] = structuredClone(field.defaultValue);
                     break;
                 }
                 case "clearCaches":

package/src/browser/index.mjs

@@ -1,3 +1,4 @@
+import { normalizeBoxJs } from "./boxjs.mjs";
 import { statusView } from "./components.mjs";
 import { mount } from "./mount.mjs";
 import { installDefaultStyles } from "./styles.mjs";
@@ -24,8 +25,8 @@ class ModulePage {
     }
 
     /**
-     * 从规范模块路径读取 BoxJS JSON 并挂载通用前端。
-     * Read BoxJS JSON from the conventional module path and mount the generic frontend.
+     * 通过模块 API 读取 BoxJS JSON 并挂载通用前端。
+     * Read BoxJS JSON through the module API and mount the generic frontend.
      * @returns {Promise<void>} 启动完成 / Startup completion.
      */
     async start() {
@@ -37,9 +38,11 @@ class ModulePage {
             const match = /^\/settings\/([a-zA-Z0-9_-]+)\/?$/.exec(this.#window.location.pathname);
             const module = embedded ?? match?.[1];
             if (!module) throw new TypeError("Open a concrete module URL");
-            const response = await fetch(`/configs/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
+            const response = await fetch(`/api/${encodeURIComponent(module)}`, { cache: "no-store", credentials: "omit", headers: { Accept: "application/json" } });
             if (response.status !== 200) throw new Error(`HTTP ${response.status}`);
-            this.#view = mount(await response.json());
+            const boxjs = await response.json();
+            normalizeBoxJs(boxjs, module);
+            this.#view = mount(boxjs);
         } catch (error) {
             this.#root.replaceChildren(statusView(`加载失败：${error.message}`, () => this.start()));
         }

package/src/index.d.ts

@@ -92,8 +92,8 @@ export interface SettingsRequest {
      */
     headers?: Record<string, string | undefined>;
     /**
-     * 模块动作的 JSON 正文
-     * JSON body for a module action.
+     * 存储动作的 form 正文
+     * Form body for a storage action.
      */
     body?: string;
 }