@arraypress/extension-kit 1.10.0 → 1.11.1

package/src/settings/storage.d.ts

@@ -74,14 +74,45 @@ export declare const MAX_SYNC_ITEM_BYTES = 8192;
  */
 export declare function pick<T extends Record<string, unknown>>(object: T, keys: readonly string[]): Partial<T>;
 /**
- * How many bytes sync counts for one item: the key plus the value's JSON,
- * UTF-8 encoded, as Chrome measures `QUOTA_BYTES_PER_ITEM`.
+ * How many bytes sync counts for one item, as Chrome measures
+ * `QUOTA_BYTES_PER_ITEM`: the key plus the value's JSON as Chrome's own
+ * writer spells it, UTF-8 encoded. That writer (`base::WriteJson`) escapes
+ * `<` as `\u003C` and U+2028 / U+2029 as `\u2028` / `\u2029`, six bytes each,
+ * so text full of `<` (an HTML template) weighs far more in sync than its
+ * `JSON.stringify` length says. Checked against Chromium's
+ * `settings_storage_quota_enforcer.cc` and `base/json/string_escape.cc`.
  *
  * @param {string} key - The item's key.
  * @param {unknown} value - The item's value.
  * @returns {number} Bytes.
+ * @example
+ * syncItemBytes('k', 'a<b'); // 11: k + "a\u003Cb"
  */
 export declare function syncItemBytes(key: string, value: unknown): number;
+/**
+ * Whether two stored values are the same, whatever order their objects' keys come in.
+ *
+ * @param {unknown} a - One value.
+ * @param {unknown} b - The other.
+ * @returns {boolean} True when they'd be stored alike.
+ * @example
+ * sameValue({ a: 1, b: [2] }, { b: [2], a: 1 }); // true
+ */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * Run `work` while nothing else runs under the same name: in this page, the
+ * extension's other pages and its service worker alike (Web Locks, which an
+ * extension's contexts share), so a read-modify-write of one storage item
+ * can't interleave with another. `work` is told whether it had to wait.
+ *
+ * @template T
+ * @param {string} name - The lock's name.
+ * @param {(waited: boolean) => Promise<T>} work - What to do; `waited` is true when other work held the name first.
+ * @returns {Promise<T>} What `work` gives.
+ * @example
+ * await exclusive('unsyncedSettings', async () => storage.local.set({ held: { ...(await storage.local.get('held')).held, days } }));
+ */
+export declare function exclusive<T>(name: string, work: (waited: boolean) => Promise<T>): Promise<T>;
 /**
  * Whether an object has no own keys.
  *

package/src/settings/storage.js

@@ -53,16 +53,86 @@ export function pick(object, keys) {
   return /** @type {Partial<T>} */ (Object.fromEntries(keys.filter((key) => key in object).map((key) => [key, object[key]])));
 }
 
+/** What Chrome's JSON writer spells as six bytes where `JSON.stringify` writes fewer: `<` (one byte), U+2028 and U+2029 (three each). */
+const WIDER_IN_CHROME = /[<\u2028\u2029]/g;
+
 /**
- * How many bytes sync counts for one item: the key plus the value's JSON,
- * UTF-8 encoded, as Chrome measures `QUOTA_BYTES_PER_ITEM`.
+ * How many bytes sync counts for one item, as Chrome measures
+ * `QUOTA_BYTES_PER_ITEM`: the key plus the value's JSON as Chrome's own
+ * writer spells it, UTF-8 encoded. That writer (`base::WriteJson`) escapes
+ * `<` as `\u003C` and U+2028 / U+2029 as `\u2028` / `\u2029`, six bytes each,
+ * so text full of `<` (an HTML template) weighs far more in sync than its
+ * `JSON.stringify` length says. Checked against Chromium's
+ * `settings_storage_quota_enforcer.cc` and `base/json/string_escape.cc`.
  *
  * @param {string} key - The item's key.
  * @param {unknown} value - The item's value.
  * @returns {number} Bytes.
+ * @example
+ * syncItemBytes('k', 'a<b'); // 11: k + "a\u003Cb"
  */
 export function syncItemBytes(key, value) {
-  return new TextEncoder().encode(key + JSON.stringify(value)).length;
+  const json = String(JSON.stringify(value));
+  let wider = 0;
+  for (const [character] of json.matchAll(WIDER_IN_CHROME)) wider += character === '<' ? 5 : 3;
+  return new TextEncoder().encode(key + json).length + wider;
+}
+
+/**
+ * A value as text that reads the same however its objects' keys are ordered:
+ * Chrome hands a stored object back with its keys sorted.
+ *
+ * @param {unknown} value - Anything JSON can hold.
+ * @returns {string} Its JSON, object keys sorted.
+ */
+function canonical(value) {
+  return String(JSON.stringify(value, (_, inner) => (inner && typeof inner === 'object' && !Array.isArray(inner)
+    ? Object.fromEntries(Object.keys(inner).sort().map((key) => [key, inner[key]]))
+    : inner)));
+}
+
+/**
+ * Whether two stored values are the same, whatever order their objects' keys come in.
+ *
+ * @param {unknown} a - One value.
+ * @param {unknown} b - The other.
+ * @returns {boolean} True when they'd be stored alike.
+ * @example
+ * sameValue({ a: 1, b: [2] }, { b: [2], a: 1 }); // true
+ */
+export function sameValue(a, b) {
+  return canonical(a) === canonical(b);
+}
+
+/** Where there are no Web Locks (an old Node): each name's last piece of work, so the next waits for it. @type {Map<string, Promise<unknown>>} */
+const chains = new Map();
+
+/**
+ * Run `work` while nothing else runs under the same name: in this page, the
+ * extension's other pages and its service worker alike (Web Locks, which an
+ * extension's contexts share), so a read-modify-write of one storage item
+ * can't interleave with another. `work` is told whether it had to wait.
+ *
+ * @template T
+ * @param {string} name - The lock's name.
+ * @param {(waited: boolean) => Promise<T>} work - What to do; `waited` is true when other work held the name first.
+ * @returns {Promise<T>} What `work` gives.
+ * @example
+ * await exclusive('unsyncedSettings', async () => storage.local.set({ held: { ...(await storage.local.get('held')).held, days } }));
+ */
+export async function exclusive(name, work) {
+  const locks = /** @type {{navigator?: {locks?: LockManager}}} */ (globalThis).navigator?.locks;
+  if (locks) {
+    /** @type {{value: T} | null} */
+    const free = await locks.request(name, { ifAvailable: true }, async (lock) => (lock ? { value: await work(false) } : null));
+    return free ? free.value : locks.request(name, () => work(true));
+  }
+  const before = chains.get(name);
+  const run = (before ?? Promise.resolve()).then(() => work(before !== undefined));
+  const settled = run.catch(() => {});
+  chains.set(name, settled);
+  settled.then(() => { if (chains.get(name) === settled) chains.delete(name); });
+  return run;
 }
 
 /**

package/src/settings/store.d.ts

@@ -8,6 +8,15 @@
  * `chrome.storage.local` instead. Local also holds any write sync refused
  * (too many writes a minute, or an item over its size limit), kept under
  * `unsyncedKey`, read as if synced, and retried, so a change is never lost.
+ * Beside it (`<unsyncedKey>Was`) is what sync held for each when it was
+ * refused: once sync holds something else (the setting was changed since on
+ * another computer), the held change is the older one and is dropped, not
+ * read over the newer one or sent up over it.
+ *
+ * Holding a change is a read-modify-write of one local item, so it runs
+ * under a Web Lock the extension's pages and worker share: two refused
+ * writes at once keep both changes, and a retry can't put an older value
+ * back over a newer one.
  *
  * Each extension supplies its schema: the defaults and one normaliser that
  * coerces anything read from storage or a form into valid settings.
@@ -72,6 +81,11 @@ export type SettingsStore<S extends Record<string, unknown>> = {
      *   Try again to put earlier refusals into sync.
      */
     retryUnsynced: (storage: SyncedStorage) => Promise<boolean>;
+    /**
+     *   Whether trying again could help: something held is still the newest and small enough for sync
+     *   (an item over sync's size limit stays on this computer however often it's tried).
+     */
+    retryable: (storage: SyncedStorage) => Promise<boolean>;
     /**
      *   Save the settings `changes` names, normalised.
      */
@@ -116,6 +130,9 @@ export type SettingsStore<S extends Record<string, unknown>> = {
  *   everything reached sync.
  * @property {(storage: SyncedStorage) => Promise<boolean>} retryUnsynced
  *   Try again to put earlier refusals into sync.
+ * @property {(storage: SyncedStorage) => Promise<boolean>} retryable
+ *   Whether trying again could help: something held is still the newest and small enough for sync
+ *   (an item over sync's size limit stays on this computer however often it's tried).
  * @property {(storage: SyncedStorage, changes: Partial<S>) => Promise<{settings: S, synced: boolean}>} save
  *   Save the settings `changes` names, normalised.
  * @property {(changes: Record<string, StorageChange>, area: string) => (keyof S & string)[]} changed

package/src/settings/store.js

@@ -8,6 +8,15 @@
  * `chrome.storage.local` instead. Local also holds any write sync refused
  * (too many writes a minute, or an item over its size limit), kept under
  * `unsyncedKey`, read as if synced, and retried, so a change is never lost.
+ * Beside it (`<unsyncedKey>Was`) is what sync held for each when it was
+ * refused: once sync holds something else (the setting was changed since on
+ * another computer), the held change is the older one and is dropped, not
+ * read over the newer one or sent up over it.
+ *
+ * Holding a change is a read-modify-write of one local item, so it runs
+ * under a Web Lock the extension's pages and worker share: two refused
+ * writes at once keep both changes, and a retry can't put an older value
+ * back over a newer one.
  *
  * Each extension supplies its schema: the defaults and one normaliser that
  * coerces anything read from storage or a form into valid settings.
@@ -15,7 +24,7 @@
  * @module settings/store
  */
 
-import { MAX_SYNC_ITEM_BYTES, isEmpty, pick, syncItemBytes } from './storage.js';
+import { MAX_SYNC_ITEM_BYTES, exclusive, isEmpty, pick, sameValue, syncItemBytes } from './storage.js';
 
 /** @import { StorageChange, SyncedStorage } from './storage.js' */
 
@@ -51,6 +60,9 @@ import { MAX_SYNC_ITEM_BYTES, isEmpty, pick, syncItemBytes } from './storage.js'
  *   everything reached sync.
  * @property {(storage: SyncedStorage) => Promise<boolean>} retryUnsynced
  *   Try again to put earlier refusals into sync.
+ * @property {(storage: SyncedStorage) => Promise<boolean>} retryable
+ *   Whether trying again could help: something held is still the newest and small enough for sync
+ *   (an item over sync's size limit stays on this computer however often it's tried).
  * @property {(storage: SyncedStorage, changes: Partial<S>) => Promise<{settings: S, synced: boolean}>} save
  *   Save the settings `changes` names, normalised.
  * @property {(changes: Record<string, StorageChange>, area: string) => (keyof S & string)[]} changed
@@ -78,9 +90,36 @@ export function createSettingsStore({ defaults, normalize: normalizeRaw, localKe
   /** @param {Record<string, unknown> | null} [raw] @returns {S} */
   const normalize = (raw) => normalizeRaw(raw ?? {});
 
+  /** The local item holding what sync held for each refused setting: `{key: [value]}`, `[]` for nothing. */
+  const wasKey = `${unsyncedKey}Was`;
+
+  /**
+   * What an area holds for a key, in a form that tells nothing from `null`.
+   *
+   * @param {Record<string, unknown>} items - What a `get` gave.
+   * @param {string} key - The key.
+   * @returns {unknown[]} `[value]`, or `[]` when it holds nothing.
+   */
+  const seen = (items, key) => (key in items ? [items[key]] : []);
+
+  /**
+   * The held changes that are still the newest: sync holds what it did when each was refused.
+   * One held before `wasKey` existed has nothing to compare, and counts as newest.
+   *
+   * @param {Record<string, unknown>} held - The held changes.
+   * @param {Record<string, unknown[]>} was - What sync held when each was refused.
+   * @param {Record<string, unknown>} synced - What sync holds now.
+   * @returns {Record<string, unknown>} The ones to keep.
+   */
+  const newest = (held, was, synced) => Object.fromEntries(Object.entries(pick(held, syncedKeys))
+    .filter(([key]) => !(key in was) || sameValue(was[key], seen(synced, key))));
+
   /**
    * Start one sync write of `values` at once; resolves to what sync refused.
-   * An item too big for sync isn't even tried.
+   * An item too big for sync isn't even tried. When Chrome refuses several
+   * together for anything but its write rate, each is tried on its own, so
+   * one item Chrome won't take (the whole of sync is full, or it weighs more
+   * there than here) doesn't keep the others on this computer.
    *
    * @param {SyncedStorage} storage
    * @param {Record<string, unknown>} values
@@ -91,10 +130,13 @@ export function createSettingsStore({ defaults, normalize: normalizeRaw, localKe
     const fits = Object.fromEntries(entries.filter(([key, value]) => syncItemBytes(key, value) <= MAX_SYNC_ITEM_BYTES));
     const refused = Object.fromEntries(entries.filter(([key]) => !(key in fits)));
     if (isEmpty(fits)) return Promise.resolve(refused);
-    return storage.sync.set(fits).then(() => refused, (/** @type {unknown} */ error) => {
-      console.warn('Settings: Chrome Sync refused the change; keeping it on this computer and trying again later.',
-        /** @type {Error | undefined} */ (error)?.message ?? error);
-      return { ...refused, ...fits };
+    return storage.sync.set(fits).then(() => refused, async (/** @type {unknown} */ error) => {
+      const message = String(/** @type {Error | undefined} */ (error)?.message ?? error);
+      console.warn('Settings: Chrome Sync refused the change; keeping it on this computer and trying again later.', message);
+      const keys = Object.keys(fits);
+      if (keys.length === 1 || /MAX_WRITE_OPERATIONS/.test(message)) return { ...refused, ...fits };
+      const alone = await Promise.all(keys.map((key) => storage.sync.set({ [key]: fits[key] }).then(() => [], () => [key])));
+      return { ...refused, ...pick(fits, alone.flat()) };
     });
   }
 
@@ -102,30 +144,54 @@ export function createSettingsStore({ defaults, normalize: normalizeRaw, localKe
   async function load(storage) {
     const [synced, local] = await Promise.all([
       storage.sync.get([...syncedKeys]),
-      storage.local.get([...localKeys, unsyncedKey]),
+      storage.local.get([...localKeys, unsyncedKey, wasKey]),
     ]);
-    const { [unsyncedKey]: unsynced = {}, ...here } = local;
-    return normalize({ ...synced, ...pick(unsynced, syncedKeys), ...here });
+    const { [unsyncedKey]: unsynced = {}, [wasKey]: was = {}, ...here } = local;
+    return normalize({ ...synced, ...newest(unsynced, was, synced), ...here });
   }
 
   /**
    * One sync write for all of `values` (sync allows 120 a minute), then any
-   * that sync refused before. What sync refuses is kept in local, where
-   * `load` still reads it, and goes up with the next write or
-   * `retryUnsynced`.
+   * that sync refused before and that are still the newest. What sync refuses
+   * is kept in local, where `load` still reads it, and goes up with the next
+   * write or `retryUnsynced`.
    *
    * @type {SettingsStore<S>['writeSynced']}
    */
-  async function writeSynced(storage, values) {
+  function writeSynced(storage, values) {
     // Sent before anything is awaited, so a page that's closing still gets it out.
     const sending = send(storage, values);
-    const { [unsyncedKey]: held } = await storage.local.get([unsyncedKey]);
-    let refused = await sending;
-    const older = Object.fromEntries(Object.entries(pick(held ?? {}, syncedKeys)).filter(([key]) => !(key in values)));
-    if (!isEmpty(older)) refused = { ...(await send(storage, older)), ...refused };
-    if (!isEmpty(refused)) await storage.local.set({ [unsyncedKey]: refused });
-    else if (held) await storage.local.remove(unsyncedKey);
-    return isEmpty(refused);
+    return exclusive(`settings:${unsyncedKey}`, async (waited) => {
+      let refused = await sending;
+      const sent = Object.keys(values).filter((key) => !(key in refused));
+      if (waited && sent.length) {
+        // The work waited for may have been a retry that sent an older value after this one: put this one back.
+        const now = await storage.sync.get(sent);
+        const undone = pick(values, sent.filter((key) => !sameValue(seen(now, key), [values[key]])));
+        if (!isEmpty(undone)) refused = { ...refused, ...(await send(storage, undone)) };
+      }
+      const { [unsyncedKey]: held = {}, [wasKey]: was = {} } = await storage.local.get([unsyncedKey, wasKey]);
+      const heldKeys = Object.keys(pick(held, syncedKeys)).filter((key) => !(key in values));
+      const synced = await storage.sync.get([...heldKeys, ...Object.keys(refused)]);
+      const older = pick(newest(held, was, synced), heldKeys);
+      const stillOlder = isEmpty(older) ? {} : await send(storage, older);
+      const keep = { ...stillOlder, ...refused };
+      const keepWas = Object.fromEntries(Object.keys(keep).map((key) => [key, key in refused || !(key in was) ? seen(synced, key) : was[key]]));
+      if (isEmpty(keep)) {
+        if (!isEmpty(held) || !isEmpty(was)) await storage.local.remove([unsyncedKey, wasKey]);
+      } else if (!sameValue(keep, held) || !sameValue(keepWas, was)) {
+        await storage.local.set({ [unsyncedKey]: keep, [wasKey]: keepWas });
+      }
+      return isEmpty(keep);
+    });
+  }
+
+  /** @type {SettingsStore<S>['retryable']} */
+  async function retryable(storage) {
+    const { [unsyncedKey]: held = {}, [wasKey]: was = {} } = await storage.local.get([unsyncedKey, wasKey]);
+    const keys = Object.keys(pick(held, syncedKeys));
+    if (!keys.length) return false;
+    return Object.entries(newest(held, was, await storage.sync.get(keys))).some(([key, value]) => syncItemBytes(key, value) <= MAX_SYNC_ITEM_BYTES);
   }
 
   /**
@@ -166,6 +232,7 @@ export function createSettingsStore({ defaults, normalize: normalizeRaw, localKe
     normalize,
     load,
     writeSynced,
+    retryable,
     retryUnsynced: (/** @type {SyncedStorage} */ storage) => writeSynced(storage, {}),
     save,
     changed,

package/src/sites/sites.d.ts

@@ -7,7 +7,11 @@
  * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
- * `localhost`). Text without a scheme is read as https.
+ * `localhost`). Text without a scheme is read as https. Only a real host
+ * name is a site: a `*` typed inside one would make a match pattern Chrome
+ * refuses (`*://*.*.example.com/*`), and with it the whole
+ * `registerContentScripts` call, so the extension would stop following its
+ * settings (checked in Chromium 156: "Invalid host wildcard").
  *
  * @module sites/sites
  */
@@ -35,6 +39,7 @@ export declare function siteOrigin(input: unknown): string | null;
  * @example
  * siteHost(' https://www.GitHub.com/a ');  // 'github.com'
  * siteHost('news.bbc.co.uk');              // 'news.bbc.co.uk'
+ * siteHost('*.example.com');               // 'example.com': a list covers subdomains anyway
  * siteHost('not a site');                  // null
  */
 export declare function siteHost(input: unknown): string | null;

package/src/sites/sites.js

@@ -7,7 +7,11 @@
  * taken out or edited. Pure.
  *
  * A site is a web host: http or https, with a dot in its name (or
- * `localhost`). Text without a scheme is read as https.
+ * `localhost`). Text without a scheme is read as https. Only a real host
+ * name is a site: a `*` typed inside one would make a match pattern Chrome
+ * refuses (`*://*.*.example.com/*`), and with it the whole
+ * `registerContentScripts` call, so the extension would stop following its
+ * settings (checked in Chromium 156: "Invalid host wildcard").
  *
  * @module sites/sites
  */
@@ -18,19 +22,31 @@ export const MAX_HOST_LENGTH = 253;
 /** A scheme at the start of what was typed; `localhost:8080` is a host and port, not one. */
 const SCHEME = /^[a-z][a-z\d+.-]*:(?!\d)/i;
 
+/** A match pattern's wildcards at the start of what was typed: `*://` for any scheme, `*.` for subdomains. A listed site covers its subdomains anyway. */
+const PATTERN_START = /^(?:\*:\/\/)?((?:[a-z][a-z\d+.-]*:\/\/)?)\*\./i;
+
+/**
+ * A host name as the URL parser gives it (lower case, punycode), and nothing else it lets through:
+ * labels of letters, digits, `-` and `_`, none empty, a dot at the end allowed. `*`, commas and
+ * empty labels pass the parser, and a `*` goes on to make a match pattern Chrome refuses.
+ */
+const HOST_NAME = /^[a-z\d_](?:[a-z\d_-]*[a-z\d_])?(?:\.[a-z\d_](?:[a-z\d_-]*[a-z\d_])?)*\.?$/;
+
 /**
- * What was typed (or stored, or a page's address) as a web URL.
+ * What was typed (or stored, or a page's address) as a web URL. A match pattern's wildcards at
+ * the start (`*.example.com`, `*://*.example.com/*`) are dropped: the site is `example.com`.
  *
  * @param {unknown} input - Anything.
  * @returns {URL | null} The URL, or null when it isn't a web site's.
  */
 function webUrl(input) {
   // Only text: a stray number would otherwise read as an IP address (3 → "0.0.0.3").
-  const text = typeof input === 'string' ? input.trim() : '';
+  const text = typeof input === 'string' ? input.trim().replace(PATTERN_START, '$1').replace(/^\*:\/\//, '') : '';
   if (!text || /\s/.test(text)) return null;
   try {
     const url = new URL(SCHEME.test(text) ? text : `https://${text}`);
     if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+    if (!HOST_NAME.test(url.hostname)) return null;
     return url.hostname.includes('.') || url.hostname === 'localhost' ? url : null;
   } catch {
     return null;
@@ -63,6 +79,7 @@ export function siteOrigin(input) {
  * @example
  * siteHost(' https://www.GitHub.com/a ');  // 'github.com'
  * siteHost('news.bbc.co.uk');              // 'news.bbc.co.uk'
+ * siteHost('*.example.com');               // 'example.com': a list covers subdomains anyway
  * siteHost('not a site');                  // null
  */
 export function siteHost(input) {