@open-pioneer/local-storage 4.8.0-dev.20260910101405 → 4.9.0-dev.20260930055642
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -1
- package/LocalStorageServiceImpl.d.ts +4 -10
- package/LocalStorageServiceImpl.js +8 -262
- package/LocalStorageServiceImpl.js.map +1 -1
- package/README.md +65 -26
- package/SessionStorageServiceImpl.d.ts +7 -0
- package/SessionStorageServiceImpl.js +17 -0
- package/SessionStorageServiceImpl.js.map +1 -0
- package/StorageServiceImpl.d.ts +29 -0
- package/StorageServiceImpl.js +280 -0
- package/StorageServiceImpl.js.map +1 -0
- package/_virtual/source-info.js +4 -2
- package/api.d.ts +55 -14
- package/package.json +13 -4
- package/services.d.ts +1 -0
- package/services.js +1 -0
- package/services.js.map +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
# @open-pioneer/local-storage
|
|
2
2
|
|
|
3
|
-
## 4.
|
|
3
|
+
## 4.9.0-dev.20260930055642
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- d7a657b: Add a new `SessionStorageService` based on the browser's [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
|
|
8
|
+
The new service has the same API as the `LocalStorageService`.
|
|
9
|
+
|
|
10
|
+
Reference the interface name `local-storage.SessionStorageService` to inject an instance of the new service.
|
|
11
|
+
|
|
12
|
+
The storage API types have been renamed to storage-kind-neutral names: `StorageAPI`, `StorageNamespace`, `StorageProperties` and the new common interface `StorageService`.
|
|
13
|
+
The previous names `LocalStorageAPI`, `LocalStorageNamespace` and `LocalStorageProperties` are still valid, but have been marked as deprecated.
|
|
14
|
+
|
|
15
|
+
## 4.8.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
|
6
18
|
|
|
@@ -1,13 +1,7 @@
|
|
|
1
1
|
import { ServiceOptions } from "@open-pioneer/runtime";
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
|
|
2
|
+
import { LocalStorageService } from "./api";
|
|
3
|
+
import { StorageServiceImpl } from "./StorageServiceImpl";
|
|
4
|
+
/** Implements the {@link LocalStorageService} on top of the browser's `localStorage`. */
|
|
5
|
+
export declare class LocalStorageServiceImpl extends StorageServiceImpl implements LocalStorageService {
|
|
5
6
|
constructor(options: ServiceOptions);
|
|
6
|
-
destroy(): void;
|
|
7
|
-
get isSupported(): boolean;
|
|
8
|
-
get(key: string): unknown;
|
|
9
|
-
set(key: string, value: unknown): void;
|
|
10
|
-
remove(key: string): void;
|
|
11
|
-
removeAll(): void;
|
|
12
|
-
getNamespace(key: string): LocalStorageNamespace;
|
|
13
7
|
}
|
|
@@ -1,270 +1,16 @@
|
|
|
1
|
-
import { createLogger
|
|
1
|
+
import { createLogger } from '@open-pioneer/core';
|
|
2
2
|
import { sourceId } from './_virtual/source-info.js';
|
|
3
|
+
import { StorageServiceImpl } from './StorageServiceImpl.js';
|
|
3
4
|
|
|
4
5
|
const LOG = createLogger(sourceId);
|
|
5
|
-
|
|
6
|
-
const ERROR_IDS = {
|
|
7
|
-
CORRUPTED_DATA: "local-storage:corrupted-data",
|
|
8
|
-
INVALID_PATH: "local-storage:invalid-path",
|
|
9
|
-
INVALID_VALUE: "local-storage:invalid-value",
|
|
10
|
-
NOT_SUPPORTED: "local-storage:not-supported",
|
|
11
|
-
INTERNAL: "local-storage:internal-error"
|
|
12
|
-
};
|
|
13
|
-
class LocalStorageServiceImpl {
|
|
14
|
-
// Key in local storage.
|
|
15
|
-
#rootKey;
|
|
16
|
-
// Root value. A (possibly nested) JSON structure that is persisted into local storage.
|
|
17
|
-
// This value (or its children) are modified via the various `get` / `set` / `clear` / etc. methods
|
|
18
|
-
// on the service itself and on the namespace objects obtained through the service.
|
|
19
|
-
#rootValue = {};
|
|
20
|
-
// Reference to the local storage (if supported).
|
|
21
|
-
#localStorage;
|
|
22
|
-
// The root namespace works on `rootValue` directly.
|
|
23
|
-
#rootNamespace;
|
|
6
|
+
class LocalStorageServiceImpl extends StorageServiceImpl {
|
|
24
7
|
constructor(options) {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
}
|
|
8
|
+
super(options, {
|
|
9
|
+
log: LOG,
|
|
10
|
+
label: "local storage",
|
|
11
|
+
getStorage: () => globalThis.localStorage
|
|
12
|
+
});
|
|
31
13
|
}
|
|
32
|
-
destroy() {
|
|
33
|
-
if (this.#saveTimeout) {
|
|
34
|
-
clearTimeout(this.#saveTimeout);
|
|
35
|
-
this.#saveTimeout = void 0;
|
|
36
|
-
}
|
|
37
|
-
if (this.#localStorage) {
|
|
38
|
-
this.#save();
|
|
39
|
-
}
|
|
40
|
-
}
|
|
41
|
-
get isSupported() {
|
|
42
|
-
return !!this.#rootNamespace;
|
|
43
|
-
}
|
|
44
|
-
get(key) {
|
|
45
|
-
return this.#getRootNamespace().get(key);
|
|
46
|
-
}
|
|
47
|
-
set(key, value) {
|
|
48
|
-
return this.#getRootNamespace().set(key, value);
|
|
49
|
-
}
|
|
50
|
-
remove(key) {
|
|
51
|
-
return this.#getRootNamespace().remove(key);
|
|
52
|
-
}
|
|
53
|
-
removeAll() {
|
|
54
|
-
return this.#getRootNamespace().removeAll();
|
|
55
|
-
}
|
|
56
|
-
getNamespace(key) {
|
|
57
|
-
return this.#getRootNamespace().getNamespace(key);
|
|
58
|
-
}
|
|
59
|
-
// Debounce save() calls to avoid saving after every 'set'.
|
|
60
|
-
// This gives us some improved performance when there are multiple sets
|
|
61
|
-
// in quick succession.
|
|
62
|
-
#saveTimeout;
|
|
63
|
-
#triggerSave() {
|
|
64
|
-
if (this.#saveTimeout) {
|
|
65
|
-
clearTimeout(this.#saveTimeout);
|
|
66
|
-
}
|
|
67
|
-
this.#saveTimeout = setTimeout(() => {
|
|
68
|
-
this.#saveTimeout = void 0;
|
|
69
|
-
this.#save();
|
|
70
|
-
}, SAVE_TIMEOUT);
|
|
71
|
-
}
|
|
72
|
-
/**
|
|
73
|
-
* Loads persisted data from local storage.
|
|
74
|
-
* If the data is invalid (e.g. bad json), this will revert to the default (an empty object).
|
|
75
|
-
*
|
|
76
|
-
* This method is called during service startup to load the initial state.
|
|
77
|
-
*/
|
|
78
|
-
#load() {
|
|
79
|
-
try {
|
|
80
|
-
const storage = this.#localStorage;
|
|
81
|
-
if (!storage) {
|
|
82
|
-
throw new Error(ERROR_IDS.INTERNAL, "Local storage is not available.");
|
|
83
|
-
}
|
|
84
|
-
const json = storage.getItem(this.#rootKey);
|
|
85
|
-
if (json == null) {
|
|
86
|
-
this.#rootValue = {};
|
|
87
|
-
this.#save();
|
|
88
|
-
return;
|
|
89
|
-
}
|
|
90
|
-
try {
|
|
91
|
-
const data = JSON.parse(json);
|
|
92
|
-
if (!isObject(data)) {
|
|
93
|
-
throw new Error(
|
|
94
|
-
ERROR_IDS.CORRUPTED_DATA,
|
|
95
|
-
"Persisted value should be an object."
|
|
96
|
-
);
|
|
97
|
-
}
|
|
98
|
-
this.#rootValue = data;
|
|
99
|
-
} catch (jsonError) {
|
|
100
|
-
LOG.warn("Invalid persisted data, reverting to default.", jsonError);
|
|
101
|
-
this.#rootValue = {};
|
|
102
|
-
this.#save();
|
|
103
|
-
}
|
|
104
|
-
} catch (e) {
|
|
105
|
-
LOG.error(`Failed to load from local storage`, e);
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
/**
|
|
109
|
-
* Persists the current state of `rootValue` to local storage.
|
|
110
|
-
* This method is called whenever the state was modified.
|
|
111
|
-
*/
|
|
112
|
-
#save() {
|
|
113
|
-
try {
|
|
114
|
-
const storage = this.#localStorage;
|
|
115
|
-
if (!storage) {
|
|
116
|
-
throw new Error(ERROR_IDS.INTERNAL, "Local storage is not available.");
|
|
117
|
-
}
|
|
118
|
-
const json = JSON.stringify(this.#rootValue);
|
|
119
|
-
storage.setItem(this.#rootKey, json);
|
|
120
|
-
} catch (e) {
|
|
121
|
-
LOG.error(`Failed to save to local storage`, e);
|
|
122
|
-
}
|
|
123
|
-
}
|
|
124
|
-
#getRootNamespace() {
|
|
125
|
-
const root = this.#rootNamespace;
|
|
126
|
-
if (!root) {
|
|
127
|
-
throw new Error(
|
|
128
|
-
ERROR_IDS.NOT_SUPPORTED,
|
|
129
|
-
"Local storage is not supported by this browser."
|
|
130
|
-
);
|
|
131
|
-
}
|
|
132
|
-
return root;
|
|
133
|
-
}
|
|
134
|
-
#createRootNamespace() {
|
|
135
|
-
const storageAccess = {
|
|
136
|
-
getByPath: (path) => {
|
|
137
|
-
return cloneJSON(getPath(this.#rootValue, path));
|
|
138
|
-
},
|
|
139
|
-
setByPath: (path, value) => {
|
|
140
|
-
if (!isSupportedValue(value)) {
|
|
141
|
-
throw new Error(
|
|
142
|
-
ERROR_IDS.INVALID_VALUE,
|
|
143
|
-
"The value is not supported by local storage."
|
|
144
|
-
);
|
|
145
|
-
}
|
|
146
|
-
value = cloneJSON(value);
|
|
147
|
-
if (path.length === 0) {
|
|
148
|
-
if (!isObject(value)) {
|
|
149
|
-
throw new Error(
|
|
150
|
-
ERROR_IDS.INVALID_VALUE,
|
|
151
|
-
"The root value must be a plain object."
|
|
152
|
-
);
|
|
153
|
-
}
|
|
154
|
-
this.#rootValue = value;
|
|
155
|
-
} else {
|
|
156
|
-
setPath(this.#rootValue, path, value);
|
|
157
|
-
}
|
|
158
|
-
this.#triggerSave();
|
|
159
|
-
}
|
|
160
|
-
};
|
|
161
|
-
return new StorageNamespaceImpl([], storageAccess);
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
|
-
class StorageNamespaceImpl {
|
|
165
|
-
#path;
|
|
166
|
-
#access;
|
|
167
|
-
constructor(path, access) {
|
|
168
|
-
this.#path = path;
|
|
169
|
-
this.#access = access;
|
|
170
|
-
}
|
|
171
|
-
get(key) {
|
|
172
|
-
return this.#access.getByPath([...this.#path, key]);
|
|
173
|
-
}
|
|
174
|
-
set(key, value) {
|
|
175
|
-
this.#access.setByPath([...this.#path, key], value);
|
|
176
|
-
}
|
|
177
|
-
remove(key) {
|
|
178
|
-
this.#access.setByPath([...this.#path, key], void 0);
|
|
179
|
-
}
|
|
180
|
-
removeAll() {
|
|
181
|
-
this.#access.setByPath(this.#path, {});
|
|
182
|
-
}
|
|
183
|
-
getNamespace(key) {
|
|
184
|
-
const existingValue = this.get(key);
|
|
185
|
-
if (existingValue === void 0) {
|
|
186
|
-
this.set(key, {});
|
|
187
|
-
} else if (!isObject(existingValue)) {
|
|
188
|
-
throw new Error(
|
|
189
|
-
ERROR_IDS.INVALID_PATH,
|
|
190
|
-
`Cannot use '${key}' as a namespace because it is not associated with an object.`
|
|
191
|
-
);
|
|
192
|
-
}
|
|
193
|
-
return new StorageNamespaceImpl(this.#path.concat([key]), this.#access);
|
|
194
|
-
}
|
|
195
|
-
}
|
|
196
|
-
const DEFAULT_KEY = "trails-state";
|
|
197
|
-
function getPath(object, path) {
|
|
198
|
-
let current = object;
|
|
199
|
-
for (const p of path) {
|
|
200
|
-
if (!isObject(current)) {
|
|
201
|
-
throw new Error(
|
|
202
|
-
ERROR_IDS.INVALID_PATH,
|
|
203
|
-
`Cannot get nested property '${p}' because the parent is no object.`
|
|
204
|
-
);
|
|
205
|
-
}
|
|
206
|
-
current = current[p];
|
|
207
|
-
}
|
|
208
|
-
return current;
|
|
209
|
-
}
|
|
210
|
-
function setPath(object, path, value) {
|
|
211
|
-
if (!path.length) {
|
|
212
|
-
throw new Error(ERROR_IDS.INTERNAL, "Path must not be empty.");
|
|
213
|
-
}
|
|
214
|
-
let current = object;
|
|
215
|
-
for (let i = 0, n = path.length - 1; i < n; ++i) {
|
|
216
|
-
const p = path[i];
|
|
217
|
-
const next = current[p];
|
|
218
|
-
if (!isObject(next)) {
|
|
219
|
-
throw new Error(
|
|
220
|
-
ERROR_IDS.INVALID_PATH,
|
|
221
|
-
`Cannot set property on '${p}' because it is no object.`
|
|
222
|
-
);
|
|
223
|
-
}
|
|
224
|
-
current = next;
|
|
225
|
-
}
|
|
226
|
-
const prop = path[path.length - 1];
|
|
227
|
-
current[prop] = value;
|
|
228
|
-
}
|
|
229
|
-
function isObject(object) {
|
|
230
|
-
return !!(object && typeof object === "object" && !Array.isArray(object));
|
|
231
|
-
}
|
|
232
|
-
function isSupportedValue(value) {
|
|
233
|
-
const type = typeof value;
|
|
234
|
-
return type === "boolean" || type === "number" || type === "string" || type === "undefined" || value === null || Array.isArray(value) || isObject(value);
|
|
235
|
-
}
|
|
236
|
-
function getRootKey(properties) {
|
|
237
|
-
const storageId = properties.storageId;
|
|
238
|
-
if (!storageId || typeof storageId !== "string") {
|
|
239
|
-
LOG.warn(
|
|
240
|
-
`The 'storageId' property of the 'local-storage' package should be set to a valid string to avoid collisions with other applications. Defaulting to '${DEFAULT_KEY}'.`
|
|
241
|
-
);
|
|
242
|
-
return DEFAULT_KEY;
|
|
243
|
-
}
|
|
244
|
-
return storageId;
|
|
245
|
-
}
|
|
246
|
-
function getLocalStorage() {
|
|
247
|
-
if (typeof Storage === "undefined") {
|
|
248
|
-
LOG.warn("Local storage is not supported by this browser.");
|
|
249
|
-
return void 0;
|
|
250
|
-
}
|
|
251
|
-
try {
|
|
252
|
-
const storage = globalThis.localStorage;
|
|
253
|
-
if (!storage) {
|
|
254
|
-
LOG.warn("Local storage is not supported by this browser.");
|
|
255
|
-
return void 0;
|
|
256
|
-
}
|
|
257
|
-
return storage;
|
|
258
|
-
} catch (e) {
|
|
259
|
-
LOG.warn("Local storage is not supported by this browser.", e);
|
|
260
|
-
return void 0;
|
|
261
|
-
}
|
|
262
|
-
}
|
|
263
|
-
function cloneJSON(value) {
|
|
264
|
-
if (value != null) {
|
|
265
|
-
value = JSON.parse(JSON.stringify(value));
|
|
266
|
-
}
|
|
267
|
-
return value;
|
|
268
14
|
}
|
|
269
15
|
|
|
270
16
|
export { LocalStorageServiceImpl };
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"LocalStorageServiceImpl.js","sources":["LocalStorageServiceImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport { createLogger, Error } from \"@open-pioneer/core\";\nimport { ServiceOptions } from \"@open-pioneer/runtime\";\nimport { sourceId } from \"open-pioneer:source-info\";\nimport { LocalStorageNamespace, LocalStorageProperties, LocalStorageService } from \"./api\";\n\nconst LOG = createLogger(sourceId);\n\nconst SAVE_TIMEOUT = 0;\n\nconst ERROR_IDS = {\n CORRUPTED_DATA: \"local-storage:corrupted-data\",\n INVALID_PATH: \"local-storage:invalid-path\",\n INVALID_VALUE: \"local-storage:invalid-value\",\n NOT_SUPPORTED: \"local-storage:not-supported\",\n INTERNAL: \"local-storage:internal-error\"\n} as const;\n\nexport class LocalStorageServiceImpl implements LocalStorageService {\n // Key in local storage.\n #rootKey: string;\n\n // Root value. A (possibly nested) JSON structure that is persisted into local storage.\n // This value (or its children) are modified via the various `get` / `set` / `clear` / etc. methods\n // on the service itself and on the namespace objects obtained through the service.\n #rootValue: Record<string, unknown> = {};\n\n // Reference to the local storage (if supported).\n #localStorage: Storage | undefined;\n\n // The root namespace works on `rootValue` directly.\n #rootNamespace: StorageNamespaceImpl | undefined;\n\n constructor(options: ServiceOptions) {\n this.#rootKey = getRootKey(options.properties);\n this.#localStorage = getLocalStorage();\n if (this.#localStorage) {\n this.#load();\n this.#rootNamespace = this.#createRootNamespace();\n }\n }\n\n destroy() {\n if (this.#saveTimeout) {\n clearTimeout(this.#saveTimeout);\n this.#saveTimeout = undefined;\n }\n if (this.#localStorage) {\n this.#save();\n }\n }\n\n get isSupported(): boolean {\n return !!this.#rootNamespace;\n }\n\n get(key: string): unknown {\n return this.#getRootNamespace().get(key);\n }\n\n set(key: string, value: unknown): void {\n return this.#getRootNamespace().set(key, value);\n }\n\n remove(key: string): void {\n return this.#getRootNamespace().remove(key);\n }\n\n removeAll(): void {\n return this.#getRootNamespace().removeAll();\n }\n\n getNamespace(key: string): LocalStorageNamespace {\n return this.#getRootNamespace().getNamespace(key);\n }\n\n // Debounce save() calls to avoid saving after every 'set'.\n // This gives us some improved performance when there are multiple sets\n // in quick succession.\n #saveTimeout: ReturnType<(typeof globalThis)[\"setTimeout\"]> | undefined;\n #triggerSave(): void {\n if (this.#saveTimeout) {\n clearTimeout(this.#saveTimeout);\n }\n this.#saveTimeout = setTimeout(() => {\n this.#saveTimeout = undefined;\n this.#save();\n }, SAVE_TIMEOUT);\n }\n\n /**\n * Loads persisted data from local storage.\n * If the data is invalid (e.g. bad json), this will revert to the default (an empty object).\n *\n * This method is called during service startup to load the initial state.\n */\n #load() {\n try {\n const storage = this.#localStorage;\n if (!storage) {\n // Should not happen (load is called only when storage is available).\n throw new Error(ERROR_IDS.INTERNAL, \"Local storage is not available.\");\n }\n\n const json = storage.getItem(this.#rootKey);\n if (json == null) {\n // No previous value\n this.#rootValue = {};\n this.#save();\n return;\n }\n\n try {\n const data = JSON.parse(json);\n if (!isObject(data)) {\n throw new Error(\n ERROR_IDS.CORRUPTED_DATA,\n \"Persisted value should be an object.\"\n );\n }\n this.#rootValue = data;\n } catch (jsonError) {\n LOG.warn(\"Invalid persisted data, reverting to default.\", jsonError);\n this.#rootValue = {};\n this.#save();\n }\n } catch (e) {\n LOG.error(`Failed to load from local storage`, e);\n }\n }\n\n /**\n * Persists the current state of `rootValue` to local storage.\n * This method is called whenever the state was modified.\n */\n #save() {\n try {\n const storage = this.#localStorage;\n if (!storage) {\n // Should not happen (setting values is only possible if supported).\n throw new Error(ERROR_IDS.INTERNAL, \"Local storage is not available.\");\n }\n\n const json = JSON.stringify(this.#rootValue);\n storage.setItem(this.#rootKey, json);\n } catch (e) {\n LOG.error(`Failed to save to local storage`, e);\n }\n }\n\n #getRootNamespace(): StorageNamespaceImpl {\n const root = this.#rootNamespace;\n if (!root) {\n throw new Error(\n ERROR_IDS.NOT_SUPPORTED,\n \"Local storage is not supported by this browser.\"\n );\n }\n return root;\n }\n\n #createRootNamespace(): StorageNamespaceImpl {\n const storageAccess: StorageAccess = {\n getByPath: (path) => {\n // Clone to protect against side effects on internal value\n return cloneJSON(getPath(this.#rootValue, path));\n },\n setByPath: (path, value) => {\n if (!isSupportedValue(value)) {\n throw new Error(\n ERROR_IDS.INVALID_VALUE,\n \"The value is not supported by local storage.\"\n );\n }\n\n // Clone to protect against side effects on original value\n value = cloneJSON(value);\n\n // Rewrite root object if path is empty.\n if (path.length === 0) {\n if (!isObject(value)) {\n throw new Error(\n ERROR_IDS.INVALID_VALUE,\n \"The root value must be a plain object.\"\n );\n }\n this.#rootValue = value;\n } else {\n setPath(this.#rootValue, path, value);\n }\n\n this.#triggerSave();\n }\n };\n return new StorageNamespaceImpl([], storageAccess);\n }\n}\n\ninterface StorageAccess {\n getByPath(path: string[]): unknown;\n setByPath(path: string[], value: unknown): void;\n}\n\nclass StorageNamespaceImpl implements LocalStorageNamespace {\n #path: string[];\n #access: StorageAccess;\n\n constructor(path: string[], access: StorageAccess) {\n this.#path = path;\n this.#access = access;\n }\n\n get(key: string): unknown {\n return this.#access.getByPath([...this.#path, key]);\n }\n\n set(key: string, value: unknown): void {\n this.#access.setByPath([...this.#path, key], value);\n }\n\n remove(key: string): void {\n this.#access.setByPath([...this.#path, key], undefined);\n }\n\n removeAll(): void {\n this.#access.setByPath(this.#path, {});\n }\n\n getNamespace(key: string): StorageNamespaceImpl {\n const existingValue = this.get(key);\n if (existingValue === undefined) {\n this.set(key, {});\n } else if (!isObject(existingValue)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot use '${key}' as a namespace because it is not associated with an object.`\n );\n }\n\n return new StorageNamespaceImpl(this.#path.concat([key]), this.#access);\n }\n}\n\nconst DEFAULT_KEY = \"trails-state\";\n\n/**\n * Retrieves the property at `path` from the nested `object`.\n * Returns `object` if path is empty.\n */\nfunction getPath(object: Record<string, unknown>, path: string[]): unknown {\n let current: unknown = object;\n for (const p of path) {\n if (!isObject(current)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot get nested property '${p}' because the parent is no object.`\n );\n }\n current = current[p];\n }\n return current;\n}\n\n/**\n * Sets the property at `path` in the nested `object` to `value`.\n * Throws an error if the path is empty.\n */\nfunction setPath(object: Record<string, unknown>, path: string[], value: unknown): void {\n if (!path.length) {\n throw new Error(ERROR_IDS.INTERNAL, \"Path must not be empty.\");\n }\n\n let current = object;\n for (let i = 0, n = path.length - 1; i < n; ++i) {\n // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion\n const p = path[i]!;\n\n const next = current[p];\n if (!isObject(next)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot set property on '${p}' because it is no object.`\n );\n }\n current = next;\n }\n\n // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion\n const prop = path[path.length - 1]!;\n current[prop] = value;\n}\n\n/**\n * Returns true if `object` is a plain object (or record).\n */\nfunction isObject(object: unknown): object is Record<string, unknown> {\n return !!(object && typeof object === \"object\" && !Array.isArray(object));\n}\n\n/**\n * Returns true if `value` looks like a JSON value.\n */\nfunction isSupportedValue(value: unknown) {\n const type = typeof value;\n return (\n type === \"boolean\" ||\n type === \"number\" ||\n type === \"string\" ||\n type === \"undefined\" ||\n value === null ||\n Array.isArray(value) ||\n isObject(value)\n );\n}\n\nfunction getRootKey(properties: Partial<LocalStorageProperties>): string {\n const storageId = properties.storageId;\n if (!storageId || typeof storageId !== \"string\") {\n LOG.warn(\n `The 'storageId' property of the 'local-storage' package should be set to a valid string to avoid collisions with other applications.` +\n ` Defaulting to '${DEFAULT_KEY}'.`\n );\n return DEFAULT_KEY;\n }\n return storageId;\n}\n\nfunction getLocalStorage(): Storage | undefined {\n if (typeof Storage === \"undefined\") {\n LOG.warn(\"Local storage is not supported by this browser.\");\n return undefined;\n }\n\n try {\n const storage = globalThis.localStorage;\n if (!storage) {\n LOG.warn(\"Local storage is not supported by this browser.\");\n return undefined;\n }\n return storage;\n } catch (e) {\n LOG.warn(\"Local storage is not supported by this browser.\", e);\n return undefined;\n }\n}\n\nfunction cloneJSON(value: unknown): unknown {\n if (value != null) {\n value = JSON.parse(JSON.stringify(value));\n }\n return value;\n}\n"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"LocalStorageServiceImpl.js","sources":["LocalStorageServiceImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport { createLogger } from \"@open-pioneer/core\";\nimport { ServiceOptions } from \"@open-pioneer/runtime\";\nimport { sourceId } from \"open-pioneer:source-info\";\nimport { LocalStorageService } from \"./api\";\nimport { StorageServiceImpl } from \"./StorageServiceImpl\";\n\nconst LOG = createLogger(sourceId);\n\n/** Implements the {@link LocalStorageService} on top of the browser's `localStorage`. */\nexport class LocalStorageServiceImpl extends StorageServiceImpl implements LocalStorageService {\n constructor(options: ServiceOptions) {\n super(options, {\n log: LOG,\n label: \"local storage\",\n getStorage: () => globalThis.localStorage\n });\n }\n}\n"],"names":[],"mappings":";;;;AASA,MAAM,GAAA,GAAM,aAAa,QAAQ,CAAA;AAG1B,MAAM,gCAAgC,kBAAA,CAAkD;AAAA,EAC3F,YAAY,OAAA,EAAyB;AACjC,IAAA,KAAA,CAAM,OAAA,EAAS;AAAA,MACX,GAAA,EAAK,GAAA;AAAA,MACL,KAAA,EAAO,eAAA;AAAA,MACP,UAAA,EAAY,MAAM,UAAA,CAAW;AAAA,KAChC,CAAA;AAAA,EACL;AACJ;;"}
|
package/README.md
CHANGED
|
@@ -1,40 +1,63 @@
|
|
|
1
1
|
# @open-pioneer/local-storage
|
|
2
2
|
|
|
3
|
-
This package provides access to the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
|
|
3
|
+
This package provides access to the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
Packages using the `LocalStorageService` can work with arbitrary values (including nested data structures) through a convenient API.
|
|
5
|
+
It provides two services with an identical API, differing only in the lifetime and the visibility of their data:
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
| Service | Interface name | Lifetime | Visibility |
|
|
8
|
+
| ----------------------- | ------------------------------------- | ------------------------------------------ | ------------------------------------- |
|
|
9
|
+
| `LocalStorageService` | `local-storage.LocalStorageService` | until explicitly removed | shared by all tabs of the same origin |
|
|
10
|
+
| `SessionStorageService` | `local-storage.SessionStorageService` | until the tab is closed (survives reloads) | the current tab only |
|
|
11
|
+
|
|
12
|
+
A single storage key (configurable, see [Configuration](#configuration)) is used to keep track of the application's data.
|
|
13
|
+
Packages using these services can work with arbitrary values (including nested data structures) through a convenient API.
|
|
14
|
+
|
|
15
|
+
> NOTE: Both services read their data from the browser on application startup.
|
|
16
|
+
> Changes made via a service are reflected in the browser's storage immediately.
|
|
17
|
+
> Concurrent changes made to the browser's storage **are not** reflected by the services.
|
|
11
18
|
> In other words, there is no two-way synchronization between the two systems while the application is running.
|
|
12
19
|
>
|
|
13
|
-
> You should not attempt to modify the
|
|
20
|
+
> You should not attempt to modify the storage value managed by these services (see `storageId` in [Configuration](#configuration)) through the "raw" Browser APIs while the application is running.
|
|
14
21
|
> Other keys are safe to use.
|
|
15
22
|
|
|
16
23
|
## Usage
|
|
17
24
|
|
|
18
|
-
Reference the interface name `local-storage.LocalStorageService` to inject an instance of `LocalStorageService`.
|
|
25
|
+
Reference the interface name `local-storage.LocalStorageService` to inject an instance of `LocalStorageService`, or `local-storage.SessionStorageService` to inject an instance of `SessionStorageService`.
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
// build.config.mjs
|
|
29
|
+
import { defineBuildConfig } from "@open-pioneer/build-support";
|
|
30
|
+
|
|
31
|
+
export default defineBuildConfig({
|
|
32
|
+
services: {
|
|
33
|
+
MyService: {
|
|
34
|
+
references: {
|
|
35
|
+
localStorage: "local-storage.LocalStorageService",
|
|
36
|
+
sessionStorage: "local-storage.SessionStorageService"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
});
|
|
41
|
+
```
|
|
19
42
|
|
|
20
|
-
### Checking for
|
|
43
|
+
### Checking for storage support
|
|
21
44
|
|
|
22
|
-
Not all browsers implement or enable support for local storage.
|
|
23
|
-
Use the `.isSupported` property to check whether
|
|
45
|
+
Not all browsers implement or enable support for local storage and session storage.
|
|
46
|
+
Use the `.isSupported` property to check whether the storage can be used at all:
|
|
24
47
|
|
|
25
48
|
```js
|
|
26
49
|
const storageService = ...; // injected
|
|
27
50
|
console.log(storageService.isSupported);
|
|
28
51
|
```
|
|
29
52
|
|
|
30
|
-
If
|
|
53
|
+
If the storage is not supported, other methods (such as `get()` and `set()`) throw an error.
|
|
31
54
|
|
|
32
55
|
### Reading and writing values
|
|
33
56
|
|
|
34
|
-
In its most basic form, you can use
|
|
35
|
-
In the background, changes to the service are always persisted into
|
|
57
|
+
In its most basic form, you can use either service similar to a map.
|
|
58
|
+
In the background, changes to the service are always persisted into the browser's storage.
|
|
36
59
|
|
|
37
|
-
All
|
|
60
|
+
All values used in these services are serialized to JSON via `JSON.stringify()`.
|
|
38
61
|
Thus, only values supported by JSON can be used.
|
|
39
62
|
|
|
40
63
|
Example:
|
|
@@ -50,16 +73,16 @@ storageService.set("foo", {
|
|
|
50
73
|
});
|
|
51
74
|
storageService.get("foo"); // returns (copy of) previous value
|
|
52
75
|
storageService.remove("foo");
|
|
53
|
-
storageService.
|
|
76
|
+
storageService.removeAll();
|
|
54
77
|
```
|
|
55
78
|
|
|
56
79
|
### Namespaces
|
|
57
80
|
|
|
58
|
-
You can use
|
|
81
|
+
You can use either service to manage hierarchical data, including objects and arrays (see above).
|
|
59
82
|
_Namespaces_ can help you treat an object as a group of (nested) properties.
|
|
60
83
|
Getting or setting entries in the namespace update an object behind the scenes.
|
|
61
84
|
|
|
62
|
-
To use a namespace, call `getNamespace(key)` on either
|
|
85
|
+
To use a namespace, call `getNamespace(key)` on either service or on another `StorageNamespace` object.
|
|
63
86
|
The `key` used in `getNamespace(key)` should either already be associated with an object or it should not be set to a value at all.
|
|
64
87
|
If `key` is not yet associated with an existing object, a new empty object is created.
|
|
65
88
|
|
|
@@ -71,9 +94,9 @@ const namespace = storageService.getNamespace("my-key");
|
|
|
71
94
|
namespace.set("foo", "bar"); // actually sets `"my-key" -> "foo"`
|
|
72
95
|
```
|
|
73
96
|
|
|
74
|
-
`getNamespace("my-key")` returns a `
|
|
97
|
+
`getNamespace("my-key")` returns a `StorageNamespace` instance that manipulates the object at `"my-key"`.
|
|
75
98
|
|
|
76
|
-
Namespaces provide a convenient way to scope your component's
|
|
99
|
+
Namespaces provide a convenient way to scope your component's values, avoiding conflicts with other packages.
|
|
77
100
|
For example, you can use your package name as the namespace key:
|
|
78
101
|
|
|
79
102
|
```js
|
|
@@ -86,16 +109,32 @@ namespace.set("my-state", "some-value-to-save");
|
|
|
86
109
|
|
|
87
110
|
### Configuration
|
|
88
111
|
|
|
89
|
-
| Name | Type | Description
|
|
90
|
-
| ----------- | ------ |
|
|
91
|
-
| `storageId` | String | The key under which the
|
|
112
|
+
| Name | Type | Description |
|
|
113
|
+
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| `storageId` | String | The key under which the data is saved. This value should be configured to a reasonably unique value to avoid clashes with other applications at the same origin. Defaults to `trails-state` (with a warning). |
|
|
115
|
+
|
|
116
|
+
`storageId` applies to **both** services.
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
// app.ts
|
|
120
|
+
const Element = createCustomElement({
|
|
121
|
+
// ...
|
|
122
|
+
config: {
|
|
123
|
+
properties: {
|
|
124
|
+
"@open-pioneer/local-storage": {
|
|
125
|
+
storageId: "my-app"
|
|
126
|
+
} satisfies StorageProperties
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
});
|
|
130
|
+
```
|
|
92
131
|
|
|
93
132
|
### Implementation notes
|
|
94
133
|
|
|
95
|
-
|
|
96
|
-
This JSON object is loaded from and saved to the browser
|
|
134
|
+
Each service manages its data as a single, hierarchical JSON object.
|
|
135
|
+
This JSON object is loaded from and saved to the respective browser storage area using the `storageId` key.
|
|
97
136
|
|
|
98
|
-
The top level value is always an object; its properties are manipulated when calling `get`, `set` etc. on the
|
|
137
|
+
The top level value is always an object; its properties are manipulated when calling `get`, `set` etc. on the service.
|
|
99
138
|
Nested values can be arbitrary (JSON-compatible) values.
|
|
100
139
|
|
|
101
140
|
## License
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { ServiceOptions } from "@open-pioneer/runtime";
|
|
2
|
+
import { SessionStorageService } from "./api";
|
|
3
|
+
import { StorageServiceImpl } from "./StorageServiceImpl";
|
|
4
|
+
/** Implements the {@link SessionStorageService} on top of the browser's `sessionStorage`. */
|
|
5
|
+
export declare class SessionStorageServiceImpl extends StorageServiceImpl implements SessionStorageService {
|
|
6
|
+
constructor(options: ServiceOptions);
|
|
7
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { createLogger } from '@open-pioneer/core';
|
|
2
|
+
import { sourceId$1 as sourceId } from './_virtual/source-info.js';
|
|
3
|
+
import { StorageServiceImpl } from './StorageServiceImpl.js';
|
|
4
|
+
|
|
5
|
+
const LOG = createLogger(sourceId);
|
|
6
|
+
class SessionStorageServiceImpl extends StorageServiceImpl {
|
|
7
|
+
constructor(options) {
|
|
8
|
+
super(options, {
|
|
9
|
+
log: LOG,
|
|
10
|
+
label: "session storage",
|
|
11
|
+
getStorage: () => globalThis.sessionStorage
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export { SessionStorageServiceImpl };
|
|
17
|
+
//# sourceMappingURL=SessionStorageServiceImpl.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"SessionStorageServiceImpl.js","sources":["SessionStorageServiceImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport { createLogger } from \"@open-pioneer/core\";\nimport { ServiceOptions } from \"@open-pioneer/runtime\";\nimport { sourceId } from \"open-pioneer:source-info\";\nimport { SessionStorageService } from \"./api\";\nimport { StorageServiceImpl } from \"./StorageServiceImpl\";\n\nconst LOG = createLogger(sourceId);\n\n/** Implements the {@link SessionStorageService} on top of the browser's `sessionStorage`. */\nexport class SessionStorageServiceImpl extends StorageServiceImpl implements SessionStorageService {\n constructor(options: ServiceOptions) {\n super(options, {\n log: LOG,\n label: \"session storage\",\n getStorage: () => globalThis.sessionStorage\n });\n }\n}\n"],"names":[],"mappings":";;;;AASA,MAAM,GAAA,GAAM,aAAa,QAAQ,CAAA;AAG1B,MAAM,kCAAkC,kBAAA,CAAoD;AAAA,EAC/F,YAAY,OAAA,EAAyB;AACjC,IAAA,KAAA,CAAM,OAAA,EAAS;AAAA,MACX,GAAA,EAAK,GAAA;AAAA,MACL,KAAA,EAAO,iBAAA;AAAA,MACP,UAAA,EAAY,MAAM,UAAA,CAAW;AAAA,KAChC,CAAA;AAAA,EACL;AACJ;;"}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type Logger } from "@open-pioneer/core";
|
|
2
|
+
import { ServiceOptions } from "@open-pioneer/runtime";
|
|
3
|
+
import { StorageNamespace, StorageService } from "./api";
|
|
4
|
+
/** Configures a concrete storage service implementation. */
|
|
5
|
+
export interface StorageServiceConfig {
|
|
6
|
+
/** The logger of the concrete service. */
|
|
7
|
+
readonly log: Logger;
|
|
8
|
+
/** Human readable name of the storage, in lower case (e.g. `"local storage"`). */
|
|
9
|
+
readonly label: string;
|
|
10
|
+
/**
|
|
11
|
+
* Returns the browser storage used by this service.
|
|
12
|
+
* May return `undefined` - or throw - if the storage is not available.
|
|
13
|
+
*/
|
|
14
|
+
getStorage(): Storage | undefined;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Shared implementation for services that provide access to one of the browser's storage areas.
|
|
18
|
+
*/
|
|
19
|
+
export declare abstract class StorageServiceImpl implements StorageService {
|
|
20
|
+
#private;
|
|
21
|
+
constructor(options: ServiceOptions, config: StorageServiceConfig);
|
|
22
|
+
destroy(): void;
|
|
23
|
+
get isSupported(): boolean;
|
|
24
|
+
get(key: string): unknown;
|
|
25
|
+
set(key: string, value: unknown): void;
|
|
26
|
+
remove(key: string): void;
|
|
27
|
+
removeAll(): void;
|
|
28
|
+
getNamespace(key: string): StorageNamespace;
|
|
29
|
+
}
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
import { Error } from '@open-pioneer/core';
|
|
2
|
+
|
|
3
|
+
const SAVE_TIMEOUT = 0;
|
|
4
|
+
const DEFAULT_KEY = "trails-state";
|
|
5
|
+
const ERROR_IDS = {
|
|
6
|
+
CORRUPTED_DATA: "local-storage:corrupted-data",
|
|
7
|
+
INVALID_PATH: "local-storage:invalid-path",
|
|
8
|
+
INVALID_VALUE: "local-storage:invalid-value",
|
|
9
|
+
NOT_SUPPORTED: "local-storage:not-supported",
|
|
10
|
+
INTERNAL: "local-storage:internal-error"
|
|
11
|
+
};
|
|
12
|
+
class StorageServiceImpl {
|
|
13
|
+
// Logger of the concrete service.
|
|
14
|
+
#log;
|
|
15
|
+
// Human readable name of the storage, used in messages.
|
|
16
|
+
#label;
|
|
17
|
+
// Key in the browser storage.
|
|
18
|
+
#rootKey;
|
|
19
|
+
// Root value. A (possibly nested) JSON structure that is persisted into the browser storage.
|
|
20
|
+
// This value (or its children) are modified via the various `get` / `set` / `removeAll` / etc. methods
|
|
21
|
+
// on the service itself and on the namespace objects obtained through the service.
|
|
22
|
+
#rootValue = {};
|
|
23
|
+
// Reference to the browser storage (if supported).
|
|
24
|
+
#storage;
|
|
25
|
+
// The root namespace works on `rootValue` directly.
|
|
26
|
+
#rootNamespace;
|
|
27
|
+
constructor(options, config) {
|
|
28
|
+
this.#log = config.log;
|
|
29
|
+
this.#label = config.label;
|
|
30
|
+
this.#rootKey = getRootKey(options.properties, this.#log);
|
|
31
|
+
this.#storage = this.#initStorage(config.getStorage);
|
|
32
|
+
if (this.#storage) {
|
|
33
|
+
this.#load();
|
|
34
|
+
this.#rootNamespace = this.#createRootNamespace();
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
destroy() {
|
|
38
|
+
if (this.#saveTimeout) {
|
|
39
|
+
clearTimeout(this.#saveTimeout);
|
|
40
|
+
this.#saveTimeout = void 0;
|
|
41
|
+
}
|
|
42
|
+
if (this.#storage) {
|
|
43
|
+
this.#save();
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
get isSupported() {
|
|
47
|
+
return !!this.#rootNamespace;
|
|
48
|
+
}
|
|
49
|
+
get(key) {
|
|
50
|
+
return this.#getRootNamespace().get(key);
|
|
51
|
+
}
|
|
52
|
+
set(key, value) {
|
|
53
|
+
return this.#getRootNamespace().set(key, value);
|
|
54
|
+
}
|
|
55
|
+
remove(key) {
|
|
56
|
+
return this.#getRootNamespace().remove(key);
|
|
57
|
+
}
|
|
58
|
+
removeAll() {
|
|
59
|
+
return this.#getRootNamespace().removeAll();
|
|
60
|
+
}
|
|
61
|
+
getNamespace(key) {
|
|
62
|
+
return this.#getRootNamespace().getNamespace(key);
|
|
63
|
+
}
|
|
64
|
+
// Debounce save() calls to avoid saving after every 'set'.
|
|
65
|
+
// This gives us some improved performance when there are multiple sets
|
|
66
|
+
// in quick succession.
|
|
67
|
+
#saveTimeout;
|
|
68
|
+
#triggerSave() {
|
|
69
|
+
if (this.#saveTimeout) {
|
|
70
|
+
clearTimeout(this.#saveTimeout);
|
|
71
|
+
}
|
|
72
|
+
this.#saveTimeout = setTimeout(() => {
|
|
73
|
+
this.#saveTimeout = void 0;
|
|
74
|
+
this.#save();
|
|
75
|
+
}, SAVE_TIMEOUT);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Detects the browser storage used by this service.
|
|
79
|
+
* Returns `undefined` (and logs a warning) if the storage is not available.
|
|
80
|
+
*/
|
|
81
|
+
#initStorage(getStorage) {
|
|
82
|
+
const notSupported = `This browser does not support ${this.#label}.`;
|
|
83
|
+
if (typeof Storage === "undefined") {
|
|
84
|
+
this.#log.warn(notSupported);
|
|
85
|
+
return void 0;
|
|
86
|
+
}
|
|
87
|
+
try {
|
|
88
|
+
const storage = getStorage();
|
|
89
|
+
if (!storage) {
|
|
90
|
+
this.#log.warn(notSupported);
|
|
91
|
+
return void 0;
|
|
92
|
+
}
|
|
93
|
+
return storage;
|
|
94
|
+
} catch (e) {
|
|
95
|
+
this.#log.warn(notSupported, e);
|
|
96
|
+
return void 0;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Loads persisted data from the browser storage.
|
|
101
|
+
* If the data is invalid (e.g. bad json), this will revert to the default (an empty object).
|
|
102
|
+
*
|
|
103
|
+
* This method is called during service startup to load the initial state.
|
|
104
|
+
*/
|
|
105
|
+
#load() {
|
|
106
|
+
try {
|
|
107
|
+
const storage = this.#storage;
|
|
108
|
+
if (!storage) {
|
|
109
|
+
throw new Error(ERROR_IDS.INTERNAL, `Storage is not available.`);
|
|
110
|
+
}
|
|
111
|
+
const json = storage.getItem(this.#rootKey);
|
|
112
|
+
if (json == null) {
|
|
113
|
+
this.#rootValue = {};
|
|
114
|
+
this.#save();
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
try {
|
|
118
|
+
const data = JSON.parse(json);
|
|
119
|
+
if (!isObject(data)) {
|
|
120
|
+
throw new Error(
|
|
121
|
+
ERROR_IDS.CORRUPTED_DATA,
|
|
122
|
+
"Persisted value should be an object."
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
this.#rootValue = data;
|
|
126
|
+
} catch (jsonError) {
|
|
127
|
+
this.#log.warn("Invalid persisted data, reverting to default.", jsonError);
|
|
128
|
+
this.#rootValue = {};
|
|
129
|
+
this.#save();
|
|
130
|
+
}
|
|
131
|
+
} catch (e) {
|
|
132
|
+
this.#log.error(`Failed to load from ${this.#label}`, e);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Persists the current state of `rootValue` to the browser storage.
|
|
137
|
+
* This method is called whenever the state was modified.
|
|
138
|
+
*/
|
|
139
|
+
#save() {
|
|
140
|
+
try {
|
|
141
|
+
const storage = this.#storage;
|
|
142
|
+
if (!storage) {
|
|
143
|
+
throw new Error(ERROR_IDS.INTERNAL, `Storage is not available.`);
|
|
144
|
+
}
|
|
145
|
+
const json = JSON.stringify(this.#rootValue);
|
|
146
|
+
storage.setItem(this.#rootKey, json);
|
|
147
|
+
} catch (e) {
|
|
148
|
+
this.#log.error(`Failed to save to ${this.#label}`, e);
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
#getRootNamespace() {
|
|
152
|
+
const root = this.#rootNamespace;
|
|
153
|
+
if (!root) {
|
|
154
|
+
throw new Error(
|
|
155
|
+
ERROR_IDS.NOT_SUPPORTED,
|
|
156
|
+
`This browser does not support ${this.#label}.`
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
return root;
|
|
160
|
+
}
|
|
161
|
+
#createRootNamespace() {
|
|
162
|
+
const storageAccess = {
|
|
163
|
+
getByPath: (path) => {
|
|
164
|
+
return cloneJSON(getPath(this.#rootValue, path));
|
|
165
|
+
},
|
|
166
|
+
setByPath: (path, value) => {
|
|
167
|
+
if (!isSupportedValue(value)) {
|
|
168
|
+
throw new Error(
|
|
169
|
+
ERROR_IDS.INVALID_VALUE,
|
|
170
|
+
`The value is not supported by ${this.#label}.`
|
|
171
|
+
);
|
|
172
|
+
}
|
|
173
|
+
value = cloneJSON(value);
|
|
174
|
+
if (path.length === 0) {
|
|
175
|
+
if (!isObject(value)) {
|
|
176
|
+
throw new Error(
|
|
177
|
+
ERROR_IDS.INVALID_VALUE,
|
|
178
|
+
"The root value must be a plain object."
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
this.#rootValue = value;
|
|
182
|
+
} else {
|
|
183
|
+
setPath(this.#rootValue, path, value);
|
|
184
|
+
}
|
|
185
|
+
this.#triggerSave();
|
|
186
|
+
}
|
|
187
|
+
};
|
|
188
|
+
return new StorageNamespaceImpl([], storageAccess);
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
class StorageNamespaceImpl {
|
|
192
|
+
#path;
|
|
193
|
+
#access;
|
|
194
|
+
constructor(path, access) {
|
|
195
|
+
this.#path = path;
|
|
196
|
+
this.#access = access;
|
|
197
|
+
}
|
|
198
|
+
get(key) {
|
|
199
|
+
return this.#access.getByPath([...this.#path, key]);
|
|
200
|
+
}
|
|
201
|
+
set(key, value) {
|
|
202
|
+
this.#access.setByPath([...this.#path, key], value);
|
|
203
|
+
}
|
|
204
|
+
remove(key) {
|
|
205
|
+
this.#access.setByPath([...this.#path, key], void 0);
|
|
206
|
+
}
|
|
207
|
+
removeAll() {
|
|
208
|
+
this.#access.setByPath(this.#path, {});
|
|
209
|
+
}
|
|
210
|
+
getNamespace(key) {
|
|
211
|
+
const existingValue = this.get(key);
|
|
212
|
+
if (existingValue === void 0) {
|
|
213
|
+
this.set(key, {});
|
|
214
|
+
} else if (!isObject(existingValue)) {
|
|
215
|
+
throw new Error(
|
|
216
|
+
ERROR_IDS.INVALID_PATH,
|
|
217
|
+
`Cannot use '${key}' as a namespace because it is not associated with an object.`
|
|
218
|
+
);
|
|
219
|
+
}
|
|
220
|
+
return new StorageNamespaceImpl(this.#path.concat([key]), this.#access);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
function getPath(object, path) {
|
|
224
|
+
let current = object;
|
|
225
|
+
for (const p of path) {
|
|
226
|
+
if (!isObject(current)) {
|
|
227
|
+
throw new Error(
|
|
228
|
+
ERROR_IDS.INVALID_PATH,
|
|
229
|
+
`Cannot get nested property '${p}' because the parent is no object.`
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
current = current[p];
|
|
233
|
+
}
|
|
234
|
+
return current;
|
|
235
|
+
}
|
|
236
|
+
function setPath(object, path, value) {
|
|
237
|
+
if (!path.length) {
|
|
238
|
+
throw new Error(ERROR_IDS.INTERNAL, "Path must not be empty.");
|
|
239
|
+
}
|
|
240
|
+
let current = object;
|
|
241
|
+
for (let i = 0, n = path.length - 1; i < n; ++i) {
|
|
242
|
+
const p = path[i];
|
|
243
|
+
const next = current[p];
|
|
244
|
+
if (!isObject(next)) {
|
|
245
|
+
throw new Error(
|
|
246
|
+
ERROR_IDS.INVALID_PATH,
|
|
247
|
+
`Cannot set property on '${p}' because it is no object.`
|
|
248
|
+
);
|
|
249
|
+
}
|
|
250
|
+
current = next;
|
|
251
|
+
}
|
|
252
|
+
const prop = path[path.length - 1];
|
|
253
|
+
current[prop] = value;
|
|
254
|
+
}
|
|
255
|
+
function isObject(object) {
|
|
256
|
+
return !!(object && typeof object === "object" && !Array.isArray(object));
|
|
257
|
+
}
|
|
258
|
+
function isSupportedValue(value) {
|
|
259
|
+
const type = typeof value;
|
|
260
|
+
return type === "boolean" || type === "number" || type === "string" || type === "undefined" || value === null || Array.isArray(value) || isObject(value);
|
|
261
|
+
}
|
|
262
|
+
function getRootKey(properties, log) {
|
|
263
|
+
const storageId = properties.storageId;
|
|
264
|
+
if (!storageId || typeof storageId !== "string") {
|
|
265
|
+
log.warn(
|
|
266
|
+
`The 'storageId' property of the 'local-storage' package should be set to a valid string to avoid collisions with other applications. Defaulting to '${DEFAULT_KEY}'.`
|
|
267
|
+
);
|
|
268
|
+
return DEFAULT_KEY;
|
|
269
|
+
}
|
|
270
|
+
return storageId;
|
|
271
|
+
}
|
|
272
|
+
function cloneJSON(value) {
|
|
273
|
+
if (value != null) {
|
|
274
|
+
value = JSON.parse(JSON.stringify(value));
|
|
275
|
+
}
|
|
276
|
+
return value;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
export { StorageServiceImpl };
|
|
280
|
+
//# sourceMappingURL=StorageServiceImpl.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"StorageServiceImpl.js","sources":["StorageServiceImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\n\nimport { Error, type Logger } from \"@open-pioneer/core\";\nimport { ServiceOptions } from \"@open-pioneer/runtime\";\nimport { StorageNamespace, StorageProperties, StorageService } from \"./api\";\n\nconst SAVE_TIMEOUT = 0;\n\nconst DEFAULT_KEY = \"trails-state\";\n\nconst ERROR_IDS = {\n CORRUPTED_DATA: \"local-storage:corrupted-data\",\n INVALID_PATH: \"local-storage:invalid-path\",\n INVALID_VALUE: \"local-storage:invalid-value\",\n NOT_SUPPORTED: \"local-storage:not-supported\",\n INTERNAL: \"local-storage:internal-error\"\n} as const;\n\n/** Configures a concrete storage service implementation. */\nexport interface StorageServiceConfig {\n /** The logger of the concrete service. */\n readonly log: Logger;\n\n /** Human readable name of the storage, in lower case (e.g. `\"local storage\"`). */\n readonly label: string;\n\n /**\n * Returns the browser storage used by this service.\n * May return `undefined` - or throw - if the storage is not available.\n */\n getStorage(): Storage | undefined;\n}\n\n/**\n * Shared implementation for services that provide access to one of the browser's storage areas.\n */\nexport abstract class StorageServiceImpl implements StorageService {\n // Logger of the concrete service.\n #log: Logger;\n\n // Human readable name of the storage, used in messages.\n #label: string;\n\n // Key in the browser storage.\n #rootKey: string;\n\n // Root value. A (possibly nested) JSON structure that is persisted into the browser storage.\n // This value (or its children) are modified via the various `get` / `set` / `removeAll` / etc. methods\n // on the service itself and on the namespace objects obtained through the service.\n #rootValue: Record<string, unknown> = {};\n\n // Reference to the browser storage (if supported).\n #storage: Storage | undefined;\n\n // The root namespace works on `rootValue` directly.\n #rootNamespace: StorageNamespaceImpl | undefined;\n\n constructor(options: ServiceOptions, config: StorageServiceConfig) {\n this.#log = config.log;\n this.#label = config.label;\n this.#rootKey = getRootKey(options.properties, this.#log);\n this.#storage = this.#initStorage(config.getStorage);\n if (this.#storage) {\n this.#load();\n this.#rootNamespace = this.#createRootNamespace();\n }\n }\n\n destroy() {\n if (this.#saveTimeout) {\n clearTimeout(this.#saveTimeout);\n this.#saveTimeout = undefined;\n }\n if (this.#storage) {\n this.#save();\n }\n }\n\n get isSupported(): boolean {\n return !!this.#rootNamespace;\n }\n\n get(key: string): unknown {\n return this.#getRootNamespace().get(key);\n }\n\n set(key: string, value: unknown): void {\n return this.#getRootNamespace().set(key, value);\n }\n\n remove(key: string): void {\n return this.#getRootNamespace().remove(key);\n }\n\n removeAll(): void {\n return this.#getRootNamespace().removeAll();\n }\n\n getNamespace(key: string): StorageNamespace {\n return this.#getRootNamespace().getNamespace(key);\n }\n\n // Debounce save() calls to avoid saving after every 'set'.\n // This gives us some improved performance when there are multiple sets\n // in quick succession.\n #saveTimeout: ReturnType<(typeof globalThis)[\"setTimeout\"]> | undefined;\n #triggerSave(): void {\n if (this.#saveTimeout) {\n clearTimeout(this.#saveTimeout);\n }\n this.#saveTimeout = setTimeout(() => {\n this.#saveTimeout = undefined;\n this.#save();\n }, SAVE_TIMEOUT);\n }\n\n /**\n * Detects the browser storage used by this service.\n * Returns `undefined` (and logs a warning) if the storage is not available.\n */\n #initStorage(getStorage: () => Storage | undefined): Storage | undefined {\n const notSupported = `This browser does not support ${this.#label}.`;\n if (typeof Storage === \"undefined\") {\n this.#log.warn(notSupported);\n return undefined;\n }\n\n try {\n const storage = getStorage();\n if (!storage) {\n this.#log.warn(notSupported);\n return undefined;\n }\n return storage;\n } catch (e) {\n this.#log.warn(notSupported, e);\n return undefined;\n }\n }\n\n /**\n * Loads persisted data from the browser storage.\n * If the data is invalid (e.g. bad json), this will revert to the default (an empty object).\n *\n * This method is called during service startup to load the initial state.\n */\n #load() {\n try {\n const storage = this.#storage;\n if (!storage) {\n // Should not happen (load is called only when storage is available).\n throw new Error(ERROR_IDS.INTERNAL, `Storage is not available.`);\n }\n\n const json = storage.getItem(this.#rootKey);\n if (json == null) {\n // No previous value\n this.#rootValue = {};\n this.#save();\n return;\n }\n\n try {\n const data = JSON.parse(json);\n if (!isObject(data)) {\n throw new Error(\n ERROR_IDS.CORRUPTED_DATA,\n \"Persisted value should be an object.\"\n );\n }\n this.#rootValue = data;\n } catch (jsonError) {\n this.#log.warn(\"Invalid persisted data, reverting to default.\", jsonError);\n this.#rootValue = {};\n this.#save();\n }\n } catch (e) {\n this.#log.error(`Failed to load from ${this.#label}`, e);\n }\n }\n\n /**\n * Persists the current state of `rootValue` to the browser storage.\n * This method is called whenever the state was modified.\n */\n #save() {\n try {\n const storage = this.#storage;\n if (!storage) {\n // Should not happen (setting values is only possible if supported).\n throw new Error(ERROR_IDS.INTERNAL, `Storage is not available.`);\n }\n\n const json = JSON.stringify(this.#rootValue);\n storage.setItem(this.#rootKey, json);\n } catch (e) {\n this.#log.error(`Failed to save to ${this.#label}`, e);\n }\n }\n\n #getRootNamespace(): StorageNamespaceImpl {\n const root = this.#rootNamespace;\n if (!root) {\n throw new Error(\n ERROR_IDS.NOT_SUPPORTED,\n `This browser does not support ${this.#label}.`\n );\n }\n return root;\n }\n\n #createRootNamespace(): StorageNamespaceImpl {\n const storageAccess: StorageAccess = {\n getByPath: (path) => {\n // Clone to protect against side effects on internal value\n return cloneJSON(getPath(this.#rootValue, path));\n },\n setByPath: (path, value) => {\n if (!isSupportedValue(value)) {\n throw new Error(\n ERROR_IDS.INVALID_VALUE,\n `The value is not supported by ${this.#label}.`\n );\n }\n\n // Clone to protect against side effects on original value\n value = cloneJSON(value);\n\n // Rewrite root object if path is empty.\n if (path.length === 0) {\n if (!isObject(value)) {\n throw new Error(\n ERROR_IDS.INVALID_VALUE,\n \"The root value must be a plain object.\"\n );\n }\n this.#rootValue = value;\n } else {\n setPath(this.#rootValue, path, value);\n }\n\n this.#triggerSave();\n }\n };\n return new StorageNamespaceImpl([], storageAccess);\n }\n}\n\ninterface StorageAccess {\n getByPath(path: string[]): unknown;\n setByPath(path: string[], value: unknown): void;\n}\n\nclass StorageNamespaceImpl implements StorageNamespace {\n #path: string[];\n #access: StorageAccess;\n\n constructor(path: string[], access: StorageAccess) {\n this.#path = path;\n this.#access = access;\n }\n\n get(key: string): unknown {\n return this.#access.getByPath([...this.#path, key]);\n }\n\n set(key: string, value: unknown): void {\n this.#access.setByPath([...this.#path, key], value);\n }\n\n remove(key: string): void {\n this.#access.setByPath([...this.#path, key], undefined);\n }\n\n removeAll(): void {\n this.#access.setByPath(this.#path, {});\n }\n\n getNamespace(key: string): StorageNamespaceImpl {\n const existingValue = this.get(key);\n if (existingValue === undefined) {\n this.set(key, {});\n } else if (!isObject(existingValue)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot use '${key}' as a namespace because it is not associated with an object.`\n );\n }\n\n return new StorageNamespaceImpl(this.#path.concat([key]), this.#access);\n }\n}\n\n/**\n * Retrieves the property at `path` from the nested `object`.\n * Returns `object` if path is empty.\n */\nfunction getPath(object: Record<string, unknown>, path: string[]): unknown {\n let current: unknown = object;\n for (const p of path) {\n if (!isObject(current)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot get nested property '${p}' because the parent is no object.`\n );\n }\n current = current[p];\n }\n return current;\n}\n\n/**\n * Sets the property at `path` in the nested `object` to `value`.\n * Throws an error if the path is empty.\n */\nfunction setPath(object: Record<string, unknown>, path: string[], value: unknown): void {\n if (!path.length) {\n throw new Error(ERROR_IDS.INTERNAL, \"Path must not be empty.\");\n }\n\n let current = object;\n for (let i = 0, n = path.length - 1; i < n; ++i) {\n // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion\n const p = path[i]!;\n\n const next = current[p];\n if (!isObject(next)) {\n throw new Error(\n ERROR_IDS.INVALID_PATH,\n `Cannot set property on '${p}' because it is no object.`\n );\n }\n current = next;\n }\n\n // oxlint-disable-next-line @typescript-eslint/no-non-null-assertion\n const prop = path[path.length - 1]!;\n current[prop] = value;\n}\n\n/**\n * Returns true if `object` is a plain object (or record).\n */\nfunction isObject(object: unknown): object is Record<string, unknown> {\n return !!(object && typeof object === \"object\" && !Array.isArray(object));\n}\n\n/**\n * Returns true if `value` looks like a JSON value.\n */\nfunction isSupportedValue(value: unknown) {\n const type = typeof value;\n return (\n type === \"boolean\" ||\n type === \"number\" ||\n type === \"string\" ||\n type === \"undefined\" ||\n value === null ||\n Array.isArray(value) ||\n isObject(value)\n );\n}\n\nfunction getRootKey(properties: Partial<StorageProperties>, log: Logger): string {\n const storageId = properties.storageId;\n if (!storageId || typeof storageId !== \"string\") {\n log.warn(\n `The 'storageId' property of the 'local-storage' package should be set to a valid string to avoid collisions with other applications.` +\n ` Defaulting to '${DEFAULT_KEY}'.`\n );\n return DEFAULT_KEY;\n }\n return storageId;\n}\n\nfunction cloneJSON(value: unknown): unknown {\n if (value != null) {\n value = JSON.parse(JSON.stringify(value));\n }\n return value;\n}\n"],"names":[],"mappings":"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"}
|
package/_virtual/source-info.js
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
const sourceId = "@open-pioneer/local-storage/LocalStorageServiceImpl";
|
|
1
|
+
const sourceId$1 = "@open-pioneer/local-storage/LocalStorageServiceImpl";
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
const sourceId = "@open-pioneer/local-storage/SessionStorageServiceImpl";
|
|
4
|
+
|
|
5
|
+
export { sourceId$1 as sourceId, sourceId as sourceId$1 };
|
|
4
6
|
//# sourceMappingURL=source-info.js.map
|
package/api.d.ts
CHANGED
|
@@ -1,28 +1,49 @@
|
|
|
1
1
|
import { DeclaredService } from "@open-pioneer/runtime";
|
|
2
2
|
/**
|
|
3
|
-
* Provides access to the browser's local storage
|
|
3
|
+
* Provides access to the browser's [local storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
|
|
4
|
+
* for Open Pioneer Trails packages through a convenient API.
|
|
5
|
+
*
|
|
6
|
+
* Values are persistent and shared between all tabs of the same origin.
|
|
7
|
+
*
|
|
4
8
|
* Use the interface name `"local-storage.LocalStorageService"` to inject an instance of this interface.
|
|
5
9
|
*/
|
|
6
|
-
export interface LocalStorageService extends
|
|
10
|
+
export interface LocalStorageService extends StorageService, DeclaredService<"local-storage.LocalStorageService"> {
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Provides access to the browser's [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
|
|
14
|
+
* for Open Pioneer Trails packages through a convenient API.
|
|
15
|
+
*
|
|
16
|
+
* Values are scoped to the current browser tab and are discarded when it is closed.
|
|
17
|
+
*
|
|
18
|
+
* Use the interface name `"local-storage.SessionStorageService"` to inject an instance of this interface.
|
|
19
|
+
*/
|
|
20
|
+
export interface SessionStorageService extends StorageService, DeclaredService<"local-storage.SessionStorageService"> {
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The common interface implemented by {@link LocalStorageService} and {@link SessionStorageService}.
|
|
24
|
+
*
|
|
25
|
+
* Use this type to write code that works with either kind of storage.
|
|
26
|
+
*/
|
|
27
|
+
export interface StorageService extends StorageAPI {
|
|
7
28
|
/**
|
|
8
|
-
* Whether
|
|
29
|
+
* Whether the underlying browser storage is supported by the current environment.
|
|
9
30
|
*
|
|
10
|
-
* Getters and setters working on
|
|
31
|
+
* Getters and setters working on the storage will throw if this value is `false`.
|
|
11
32
|
*/
|
|
12
33
|
readonly isSupported: boolean;
|
|
13
34
|
}
|
|
14
35
|
/**
|
|
15
|
-
* A namespace provides access to the properties of an object in
|
|
36
|
+
* A namespace provides access to the properties of an object in the browser's storage.
|
|
16
37
|
* This can be used to manage groups of related values under a common name.
|
|
17
38
|
*/
|
|
18
|
-
export type
|
|
39
|
+
export type StorageNamespace = StorageAPI;
|
|
19
40
|
/**
|
|
20
|
-
* Provides basic operations to interact with the browser's
|
|
41
|
+
* Provides basic operations to interact with the browser's storage.
|
|
21
42
|
*
|
|
22
|
-
* The operations provided by this interface always act on an object in
|
|
43
|
+
* The operations provided by this interface always act on an object in the storage:
|
|
23
44
|
* either the root value or a nested object.
|
|
24
45
|
*/
|
|
25
|
-
export interface
|
|
46
|
+
export interface StorageAPI {
|
|
26
47
|
/**
|
|
27
48
|
* Returns the value associated with the given `key`, or `undefined` if
|
|
28
49
|
* no such value exists.
|
|
@@ -57,8 +78,8 @@ export interface LocalStorageAPI {
|
|
|
57
78
|
* `key` should either be associated with an object or it's value should be undefined.
|
|
58
79
|
* If `key` is not associated with a value, a new empty object will be created.
|
|
59
80
|
*
|
|
60
|
-
* Namespaces allow you to treat an object in
|
|
61
|
-
* Getting (or setting) a key using a {@link
|
|
81
|
+
* Namespaces allow you to treat an object in the storage as a group of properties.
|
|
82
|
+
* Getting (or setting) a key using a {@link StorageNamespace | Namespace} object
|
|
62
83
|
* will simply read (or update) properties on the managed object instead.
|
|
63
84
|
*
|
|
64
85
|
* If `key` has already been set to something that is _not_ an object, you will receive an error
|
|
@@ -80,10 +101,30 @@ export interface LocalStorageAPI {
|
|
|
80
101
|
* console.log(backingObject);
|
|
81
102
|
* ```
|
|
82
103
|
*/
|
|
83
|
-
getNamespace(key: string):
|
|
104
|
+
getNamespace(key: string): StorageNamespace;
|
|
84
105
|
}
|
|
85
106
|
/** Package properties of the `"local-storage"` package. */
|
|
86
|
-
export interface
|
|
87
|
-
/**
|
|
107
|
+
export interface StorageProperties {
|
|
108
|
+
/**
|
|
109
|
+
* The root storage key used to store application state.
|
|
110
|
+
* Both services use this key, each in its own storage area.
|
|
111
|
+
*/
|
|
88
112
|
storageId: string | null;
|
|
89
113
|
}
|
|
114
|
+
/**
|
|
115
|
+
* Kept for compatibility.
|
|
116
|
+
* @deprecated Use {@link StorageAPI} instead.
|
|
117
|
+
*/
|
|
118
|
+
export interface LocalStorageAPI extends StorageAPI {
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Kept for compatibility.
|
|
122
|
+
* @deprecated Use {@link StorageNamespace} instead.
|
|
123
|
+
*/
|
|
124
|
+
export type LocalStorageNamespace = StorageNamespace;
|
|
125
|
+
/**
|
|
126
|
+
* Kept for compatibility.
|
|
127
|
+
* @deprecated Use {@link StorageProperties} instead.
|
|
128
|
+
*/
|
|
129
|
+
export interface LocalStorageProperties extends StorageProperties {
|
|
130
|
+
}
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"type": "module",
|
|
3
3
|
"name": "@open-pioneer/local-storage",
|
|
4
|
-
"version": "4.
|
|
5
|
-
"description": "Provides access to the browser's local storage.",
|
|
4
|
+
"version": "4.9.0-dev.20260930055642",
|
|
5
|
+
"description": "Provides access to the browser's local storage and session storage.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"open-pioneer-trails"
|
|
8
8
|
],
|
|
@@ -14,8 +14,8 @@
|
|
|
14
14
|
"directory": "src/packages/local-storage"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
17
|
-
"@open-pioneer/core": "4.
|
|
18
|
-
"@open-pioneer/runtime": "4.
|
|
17
|
+
"@open-pioneer/core": "4.9.0-dev.20260930055642",
|
|
18
|
+
"@open-pioneer/runtime": "4.9.0-dev.20260930055642"
|
|
19
19
|
},
|
|
20
20
|
"publishConfig": {
|
|
21
21
|
"directory": "dist",
|
|
@@ -42,6 +42,15 @@
|
|
|
42
42
|
}
|
|
43
43
|
],
|
|
44
44
|
"references": []
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
"serviceName": "SessionStorageServiceImpl",
|
|
48
|
+
"provides": [
|
|
49
|
+
{
|
|
50
|
+
"interfaceName": "local-storage.SessionStorageService"
|
|
51
|
+
}
|
|
52
|
+
],
|
|
53
|
+
"references": []
|
|
45
54
|
}
|
|
46
55
|
],
|
|
47
56
|
"servicesModule": "./services",
|
package/services.d.ts
CHANGED
package/services.js
CHANGED
package/services.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"services.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
|
|
1
|
+
{"version":3,"file":"services.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
|