Add multiget to usersettings to batch get()s in one call and cache the result for a short period

Signed-off-by: Gustaf Räntilä <g.rantila@gmail.com>

plugins/user-settings-common/package.json

@@ -37,6 +37,10 @@
     "postpack": "backstage-cli package postpack",
     "test": "backstage-cli package test"
   },
+  "dependencies": {
+    "@backstage/errors": "workspace:^",
+    "@backstage/types": "workspace:^"
+  },
   "devDependencies": {
     "@backstage/cli": "workspace:^"
   }

plugins/user-settings-common/report.api.md

@@ -3,6 +3,40 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import type { JsonValue } from '@backstage/types';
+import type { SerializedError } from '@backstage/errors';
+
+// @public (undocumented)
+export function isMultiUserSettingError(
+  setting: MultiUserSetting,
+): setting is MultiUserSettingError;
+
+// @public
+export type MultiUserSetting = MultiUserSettingError | MultiUserSettingSuccess;
+
+// @public
+export type MultiUserSettingError = {
+  bucket: string;
+  key: string;
+  error: SerializedError;
+};
+
+// @public
+export type MultiUserSettingSuccess = {
+  bucket: string;
+  key: string;
+  value: JsonValue;
+};
+
+// @public (undocumented)
+export function parseDataLoaderKey(bucketAndKey: string): {
+  bucket: string;
+  key: string;
+};
+
+// @public (undocumented)
+export function stringifyDataLoaderKey(bucket: string, key: string): string;
+
 // @public (undocumented)
 export type UserSettingsSignal = {
   type: 'key-changed' | 'key-deleted';

plugins/user-settings-common/src/index.ts

@@ -15,3 +15,6 @@
  */
 
 export * from './types';
+export { isMultiUserSettingError } from './types';
+
+export { stringifyDataLoaderKey, parseDataLoaderKey } from './keys';

plugins/user-settings-common/src/keys.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** @public */
+export function stringifyDataLoaderKey(bucket: string, key: string) {
+  return `${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`;
+}
+
+/** @public */
+export function parseDataLoaderKey(bucketAndKey: string) {
+  const [bucket, key] = bucketAndKey.split('/');
+  return { bucket: decodeURIComponent(bucket), key: decodeURIComponent(key) };
+}

plugins/user-settings-common/src/types.ts

@@ -14,8 +14,47 @@
  * limitations under the License.
  */
 
+import type { SerializedError } from '@backstage/errors';
+import type { JsonValue } from '@backstage/types';
+
 /** @public */
 export type UserSettingsSignal = {
   type: 'key-changed' | 'key-deleted';
   key: string;
 };
+
+/**
+ * A failed fetch of a user setting in a bucket
+ *
+ * @public
+ */
+export type MultiUserSettingError = {
+  bucket: string;
+  key: string;
+  error: SerializedError;
+};
+
+/**
+ * A successful value of a user setting in a bucket
+ *
+ * @public
+ */
+export type MultiUserSettingSuccess = {
+  bucket: string;
+  key: string;
+  value: JsonValue;
+};
+
+/**
+ * A single setting in a bucket, or an error, used result from the /multi endpoint
+ *
+ * @public
+ */
+export type MultiUserSetting = MultiUserSettingError | MultiUserSettingSuccess;
+
+/** @public */
+export function isMultiUserSettingError(
+  setting: MultiUserSetting,
+): setting is MultiUserSettingError {
+  return 'error' in setting;
+}