feat: parse prefs.js (#65)

* feat: parse prefs.js

* fix: compatible with zotero-types

* refactor: split func

* refactor: use PrefsManager

* tweaks

* style: fix lint

* docs: add docs for prefs manager

Author: northword

docs/src/build.md

@@ -180,10 +180,85 @@ export default defineConfig({
 
 ### Preference Management
 
-> In development.
+- Supports prefixing preference keys in `prefs.js`.
+- Generates TypeScript declaration files (`.d.ts`) for preferences.
+
+Configure via `build.prefs`:
+
+```ts twoslash
+import { defineConfig } from "zotero-plugin-scaffold";
+// ---cut---
+export default defineConfig({
+  build: {
+    prefs: {
+      prefixPrefKeys: true,
+      prefix: "extensions.myPlugin",
+      dts: "typings/prefs.d.ts"
+    }
+  }
+});
+```
+
+#### Adding Prefixes
+
+When `build.prefs.prefixPrefKeys` is enabled, preferences should be written as follows:
+
+::: code-group
+
+```js [src/prefs.js]
+pref("lintOnAdded", true);
+```
+
+```html [src/preference.xhtml]
+<vbox>
+  <groupbox>
+    <checkbox preference="lintOnAdded" data-l10n-id="linter-lint-on-item-added" native="true" />
+  </groupbox>
+</vbox>
+```
+
+```js [dist/prefs.js]
+pref("extensions.myPlugin.lintOnAdded", true);
+```
+
+```html [dist/preference.xhtml]
+<vbox>
+  <groupbox>
+    <checkbox preference="extensions.myPlugin.lintOnAdded" data-l10n-id="linter-lint-on-item-added" native="true" />
+  </groupbox>
+</vbox>
+```
 
-- Supports prefixing preference keys in `prefs.js` with a custom namespace.
-- Optionally generates TypeScript declaration files (`.d.ts`) for preferences.
+:::
+
+#### Generating DTS Files
+
+Relies on the `zotero-types` package to provide type declarations for `Zotero.Prefs`.
+
+You can also use the following helper to get or set preferences while omitting the prefix, simplifying your code.
+
+```ts
+const PREFS_PREFIX = "extensions.myPlugin";
+
+/**
+ * Get preference value.
+ * Wrapper of `Zotero.Prefs.get`.
+ * @param key
+ */
+export function getPref<K extends keyof _PluginPrefsMap>(key: K) {
+  return Zotero.Prefs.get(`${PREFS_PREFIX}.${key}` as PluginPrefKey<K>, true);
+}
+
+/**
+ * Set preference value.
+ * Wrapper of `Zotero.Prefs.set`.
+ * @param key
+ * @param value
+ */
+export function setPref<K extends keyof _PluginPrefsMap>(key: K, value: PluginPrefsMap[PluginPrefKey<K>]) {
+  return Zotero.Prefs.set(`${PREFS_PREFIX}.${key}` as PluginPrefKey<K>, value, true);
+}
+```
 
 ### Script Bundling
 

packages/scaffold/src/config.ts

@@ -45,6 +45,7 @@ function resolveConfig(config: Config): Context {
   config.id ||= config.name;
   config.namespace ||= config.name;
   config.xpiName ||= kebabCase(config.name);
+  config.build.prefs.prefix ||= `extensions.${config.namespace}`;
 
   // Parse template strings in config
   const isPreRelease = version.includes("-");
@@ -99,6 +100,11 @@ const defaultConfig = {
       prefixFluentMessages: true,
       prefixLocaleFiles: true,
     },
+    prefs: {
+      prefix: "",
+      prefixPrefKeys: true,
+      dts: "typings/prefs.d.ts",
+    },
     esbuildOptions: [],
     makeManifest: {
       enable: true,

packages/scaffold/src/core/builder.ts

@@ -1,16 +1,18 @@
 import type { Context } from "../types/index.js";
 import type { Manifest } from "../types/manifest.js";
 import type { UpdateJSON } from "../types/update-json.js";
+import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
-import { basename, dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import process from "node:process";
 import AdmZip from "adm-zip";
 import chalk from "chalk";
 import { toMerged } from "es-toolkit";
 import { build as buildAsync } from "esbuild";
-import { copy, emptyDir, move, outputJSON, readJSON, writeJson } from "fs-extra/esm";
+import { copy, emptyDir, move, outputFile, outputJSON, readJSON, writeJson } from "fs-extra/esm";
 import { glob } from "tinyglobby";
 import { generateHash } from "../utils/crypto.js";
+import { PrefsManager, renderPluginPrefsDts } from "../utils/prefs-manager.js";
 import { dateFormat, replaceInFile, toArray } from "../utils/string.js";
 import { Base } from "./base.js";
 
@@ -52,6 +54,8 @@ export default class Build extends Base {
     await this.prepareLocaleFiles();
     await this.ctx.hooks.callHook("build:fluent", this.ctx);
 
+    await this.preparePrefs();
+
     this.logger.tip("Bundling scripts");
     await this.esbuild();
     await this.ctx.hooks.callHook("build:bundle", this.ctx);
@@ -236,6 +240,61 @@ export default class Build extends Base {
     });
   }
 
+  async preparePrefs() {
+    const { dts, prefixPrefKeys, prefix } = this.ctx.build.prefs;
+    const { dist } = this.ctx;
+
+    // Skip if not enable this builder
+    if (!prefixPrefKeys && !dts)
+      return;
+
+    // Skip if no prefs.js
+    const prefsFilePath = join(dist, "addon", "prefs.js");
+    if (!existsSync(prefsFilePath))
+      return;
+
+    // Parse prefs.js
+    const prefsManager = new PrefsManager("pref");
+    await prefsManager.read(prefsFilePath);
+    const prefsWithPrefix = prefsManager.getPrefsWithPrefix(prefix);
+    const prefsWithoutPrefix = prefsManager.getPrefsWithoutPrefix(prefix);
+
+    // Generate prefs.d.ts
+    if (dts) {
+      const dtsContent = renderPluginPrefsDts(prefsWithoutPrefix, prefix);
+      await outputFile(dts, dtsContent, "utf-8");
+    }
+
+    // Generate prefixed prefs.js
+    if (prefixPrefKeys) {
+      prefsManager.clearPrefs();
+      prefsManager.setPrefs(prefsWithPrefix);
+      await prefsManager.write(prefsFilePath);
+    }
+
+    // Prefix pref keys in xhtml
+    if (prefixPrefKeys) {
+      const HTML_PREFERENCE_PATTERN = new RegExp(`preference="((?!${prefix})\\S*)"`, "g");
+      const xhtmlPaths = await glob(`${dist}/addon/**/*.xhtml`);
+      await Promise.all(xhtmlPaths.map(async (path) => {
+        let content = await readFile(path, "utf-8");
+        const matchs = [...content.matchAll(HTML_PREFERENCE_PATTERN)];
+        for (const match of matchs) {
+          const [matched, key] = match;
+          if (!prefsWithoutPrefix[key] && !prefsWithoutPrefix[key]) {
+            this.logger.warn(`preference key '${key}' in ${path} not init in prefs.js`);
+            continue;
+          }
+          if (key.startsWith(prefix))
+            continue;
+          else
+            content = content.replace(matched, `preference="${prefix}.${key}"`);
+        }
+        await outputFile(path, content, "utf-8");
+      }));
+    }
+  }
+
   esbuild() {
     const { build: { esbuildOptions } } = this.ctx;
 

packages/scaffold/src/types/config.ts

@@ -220,6 +220,40 @@ export interface BuildConfig {
      */
     prefixFluentMessages: boolean;
   };
+  prefs: {
+    /**
+     * Prefixes the keys of preferences in `prefs.js` and
+     * the value of the `preference` attribute in XHTML files.
+     *
+     * 为 `prefs.js` 中的首选项键和 XHTML 文件中的 `preference` 属性的值
+     * 添加前缀。
+     *
+     * @default true
+     */
+    prefixPrefKeys: boolean;
+    /**
+     * Prefixes for Preference Keys, no dot at the end.
+     *
+     * 首选项键的前缀，结尾不需要加点号。
+     *
+     * @default 'extensions.${namespace}'
+     */
+    prefix: string;
+    /**
+     * Generate prefs.d.ts form prefs.js.
+     *
+     * - false: disable
+     * - string: path of dts file
+     *
+     * 为首选项生成类型声明文件。
+     *
+     * - false: 禁用
+     * - string：dts 文件路径
+     *
+     * @default 'typings/prefs.d.ts'
+     */
+    dts: false | string;
+  };
   /**
    * Configurations of esbuild.
    *

packages/scaffold/src/utils/prefs.ts renamed to packages/scaffold/src/utils/prefs-manager.ts

@@ -2,20 +2,18 @@ import { readFile } from "node:fs/promises";
 import { isNotNil } from "es-toolkit";
 import { outputFile } from "fs-extra/esm";
 import { logger } from "./log.js";
-import { prefs as defaultPrefs } from "./zotero/preference.js";
 
 export type Prefs = Record<string, string | number | boolean | undefined | null>;
 
 export class PrefsManager {
   private namespace: "pref" | "user_pref";
-  private prefs: Prefs;
+  private prefs: Prefs = {};
 
   constructor(namespace: "pref" | "user_pref") {
     this.namespace = namespace;
-    this.prefs = { ...defaultPrefs };
   }
 
-  private parsePrefjs(content: string) {
+  private parse(content: string) {
     // eslint-disable-next-line regexp/no-super-linear-backtracking
     const prefPattern = /^(pref|user_pref)\s*\(\s*["']([^"']+)["']\s*,\s*(.+)\s*\)\s*;$/gm;
     const matches = content.matchAll(prefPattern);
@@ -26,12 +24,7 @@ export class PrefsManager {
     };
   }
 
-  public async read(path: string) {
-    const content = await readFile(path, "utf-8");
-    this.parsePrefjs(content);
-  }
-
-  private renderPrefjs() {
+  private render() {
     return Object.entries(this.prefs).map(([key, value]) => {
       if (!isNotNil(value))
         return "";
@@ -41,7 +34,7 @@ export class PrefsManager {
         cleanValue = `${value}`;
       }
       else if (typeof value === "string") {
-        cleanValue = `${value.replace("\n", "\\n")}`;
+        cleanValue = value; // `${value.replace("\n", "\\n")}`;
       }
       else if (typeof value === "number") {
         cleanValue = value.toString();
@@ -51,8 +44,13 @@ export class PrefsManager {
     }).filter(c => !!c).join("\n");
   }
 
-  public async write(path: string) {
-    const content = this.renderPrefjs();
+  async read(path: string) {
+    const content = await readFile(path, "utf-8");
+    this.parse(content);
+  }
+
+  async write(path: string) {
+    const content = this.render();
     // console.log(content);
     await outputFile(path, content, "utf-8");
     logger.debug("The <profile>/prefs.js has been modified.");
@@ -75,4 +73,56 @@ export class PrefsManager {
   getPrefs() {
     return this.prefs;
   }
+
+  clearPrefs() {
+    this.prefs = {};
+  }
+
+  getPrefsWithPrefix(prefix: string) {
+    const _prefs: Prefs = {};
+    for (const pref in this.prefs) {
+      if (pref.startsWith(prefix))
+        _prefs[pref] = this.prefs[pref];
+      else
+        _prefs[`${prefix}.${pref}`] = this.prefs[pref];
+    }
+    return _prefs;
+  }
+
+  getPrefsWithoutPrefix(prefix: string) {
+    const _prefs: Prefs = {};
+    for (const pref in this.prefs) {
+      _prefs[pref.replace(`${prefix}.`, "")] = this.prefs[pref];
+    }
+    return _prefs;
+  }
+}
+
+export function renderPluginPrefsDts(prefs: Prefs, prefix: string) {
+  const dtsContent = `
+/* prettier-ignore */
+/* eslint-disable */
+// @ts-nocheck
+// Generated by zotero-plugin-scaffold
+
+type _PluginPrefsMap = {
+  ${Object.entries(prefs).map(([key, value]) => {
+    return `"${key}": ${typeof value};`;
+  }).join("\n  ")}
+};
+
+type PluginPrefKey<K extends keyof _PluginPrefsMap> = \`${prefix}.\${K}\`;
+
+type PluginPrefsMap = {
+  [K in keyof _PluginPrefsMap as PluginPrefKey<K>]: _PluginPrefsMap[K]
+};
+
+declare namespace _ZoteroTypes {
+  interface Prefs {
+    get: <K extends keyof PluginPrefsMap>(key: K, global?: boolean) => PluginPrefsMap[K];
+    set: <K extends keyof PluginPrefsMap>(key: K, value: PluginPrefsMap[K], global?: boolean) => any;
+  }
+}
+`;
+  return dtsContent;
 }

packages/scaffold/src/utils/zotero-runner.ts

@@ -7,8 +7,9 @@ import { delay, toMerged } from "es-toolkit";
 import { ensureDir, outputFile, outputJSON, pathExists, readJSON, remove } from "fs-extra/esm";
 import { isLinux, isMacOS, isWindows } from "std-env";
 import { logger } from "./log.js";
-import { PrefsManager } from "./prefs.js";
+import { PrefsManager } from "./prefs-manager.js";
 import { isRunning } from "./process.js";
+import { prefs as defaultPrefs } from "./zotero/preference.js";
 import { findFreeTcpPort, RemoteFirefox } from "./zotero/remote-zotero.js";
 
 export interface ZoteroRunnerOptions {
@@ -128,9 +129,10 @@ export class ZoteroRunner {
     // Setup prefs.js
     const prefsPath = join(this.options.profile.path, "prefs.js");
     const prefsManager = new PrefsManager("user_pref");
+    prefsManager.setPrefs(defaultPrefs);
+    prefsManager.setPrefs(this.options.profile.customPrefs);
     if (await pathExists(prefsPath))
       await prefsManager.read(prefsPath);
-    prefsManager.setPrefs(this.options.profile.customPrefs);
     prefsManager.setPrefs({
       "extensions.lastAppBuildId": null,
       "extensions.lastAppVersion": null,