-
-
Notifications
You must be signed in to change notification settings - Fork 9
/
ItemList.ts
328 lines (293 loc) · 9.58 KB
/
ItemList.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
import isObject from './isObject';
export interface IItemObject<T> {
content: T;
itemName: string;
priority: number;
}
class Item<T> {
content: T;
priority: number;
constructor(content: T, priority: number) {
this.content = content;
this.priority = priority;
}
}
/**
* The `ItemList` class collects items and then arranges them into an array
* by priority.
*/
export default class ItemList<T> {
/**
* The items in the list.
*/
protected _items: Record<string, Item<T>> = {};
// TODO: [Flarum 2.0] Remove `.items` getter.
/**
* A **read-only copy** of items in the list.
*
* We don't allow adding new items to the ItemList via setting new properties,
* nor do we allow modifying existing items directly.
*
* @deprecated Use {@link ItemList.toObject} instead.
*/
get items(): DeepReadonly<Record<string, Item<T>>> {
return new Proxy(this._items, {
set() {
console.warn('Modifying `ItemList.items` is not allowed.');
return false;
},
});
}
/**
* Check whether the list is empty.
*/
isEmpty(): boolean {
return Object.keys(this._items).length === 0;
}
/**
* Check whether an item is present in the list.
*/
has(key: string): boolean {
return Object.keys(this._items).includes(key);
}
/**
* Get the content of an item.
*/
get(key: string): T {
return this._items[key].content;
}
/**
* Get the priority of an item.
*/
getPriority(key: string): number {
return this._items[key].priority;
}
/**
* Add an item to the list.
*
* @param key A unique key for the item.
* @param content The item's content.
* @param priority The priority of the item. Items with a higher priority
* will be positioned before items with a lower priority.
*/
add(key: string, content: T, priority: number = 0): this {
this._items[key] = new Item(content, priority);
return this;
}
// TODO: [Flarum 2.0] Remove deprecated `.replace()` method.
/**
* Replace an item and/or priority in the list, only if it is already present.
*
* If `content` or `priority` are `null`, these values will not be replaced.
*
* If the provided `key` is not present, nothing will happen.
*
* @deprecated Please use the {@link ItemList.setContent} and {@link ItemList.setPriority}
* methods to replace items and their priorities. This method will be removed in Flarum 2.0.
*
* @param key The key of the item in the list
* @param content The item's new content
* @param priority The item's new priority
*
* @example <caption>Replace priority and not content.</caption>
* items.replace('myItem', null, 10);
*
* @example <caption>Replace content and not priority.</caption>
* items.replace('myItem', <p>My new value.</p>);
*
* @example <caption>Replace content and priority.</caption>
* items.replace('myItem', <p>My new value.</p>, 10);
*/
replace(key: string, content: T | null = null, priority: number | null = null): this {
if (!this.has(key)) return this;
if (content !== null) {
this._items[key].content = content;
}
if (priority !== null) {
this._items[key].priority = priority;
}
return this;
}
/**
* Replaces an item's content, if the provided item key exists.
*
* If the provided `key` is not present, an error will be thrown.
*
* @param key The key of the item in the list
* @param content The item's new content
*
* @example <caption>Replace item content.</caption>
* items.setContent('myItem', <p>My new value.</p>);
*
* @example <caption>Replace item content and priority.</caption>
* items
* .setContent('myItem', <p>My new value.</p>)
* .setPriority('myItem', 10);
*
* @throws If the provided `key` is not present in the ItemList.
*/
setContent(key: string, content: T): this {
if (!this.has(key)) {
throw new Error(`[ItemList] Cannot set content of Item. Key \`${key}\` is not present.`);
}
// Saves on bundle size to call the deprecated method internally
return this.replace(key, content);
}
/**
* Replaces an item's priority, if the provided item key exists.
*
* If the provided `key` is not present, an error will be thrown.
*
* @param key The key of the item in the list
* @param priority The item's new priority
*
* @example <caption>Replace item priority.</caption>
* items.setPriority('myItem', 10);
*
* @example <caption>Replace item priority and content.</caption>
* items
* .setPriority('myItem', 10)
* .setContent('myItem', <p>My new value.</p>);
*
* @throws If the provided `key` is not present in the ItemList.
*/
setPriority(key: string, priority: number): this {
if (!this.has(key)) {
throw new Error(`[ItemList] Cannot set priority of Item. Key \`${key}\` is not present.`);
}
this._items[key].priority = priority;
return this;
}
/**
* Remove an item from the list.
*
* If the provided `key` is not present, nothing will happen.
*/
remove(key: string): this {
delete this._items[key];
return this;
}
/**
* Merge another list's items into this one.
*
* The list passed to this function will overwrite items which already exist
* with the same key.
*/
merge(otherList: ItemList<T>): ItemList<T> {
Object.keys(otherList._items).forEach((key) => {
const val = otherList._items[key];
if (val instanceof Item) {
this._items[key] = val;
}
});
return this;
}
/**
* Convert the list into an array of item content arranged by priority.
*
* This **does not** preserve the original types of primitives and proxies
* all content values to make `itemName` accessible on them.
*
* **NOTE:** If your ItemList holds primitive types (such as numbers, booleans
* or strings), these will be converted to their object counterparts if you do
* not provide `true` to this function.
*
* **NOTE:** Modifying any objects in the final array may also update the
* content of the original ItemList.
*
* @param keepPrimitives Converts item content to objects and sets the
* `itemName` property on them.
*
* @see https://github.com/flarum/core/issues/3030
*/
toArray(keepPrimitives?: false): (T & { itemName: string })[];
/**
* Convert the list into an array of item content arranged by priority.
*
* Content values that are already objects will be proxied and have
* `itemName` accessible on them. Primitive values will not have the
* `itemName` property accessible.
*
* **NOTE:** Modifying any objects in the final array may also update the
* content of the original ItemList.
*
* @param keepPrimitives Converts item content to objects and sets the
* `itemName` property on them.
*/
toArray(keepPrimitives: true): (T extends object ? T & Readonly<{ itemName: string }> : T)[];
toArray(keepPrimitives: boolean = false): T[] | (T & Readonly<{ itemName: string }>)[] {
const items: Item<T>[] = Object.keys(this._items).map((key, i) => {
const item = this._items[key];
if (!keepPrimitives || isObject(item.content)) {
// Convert content to object, then proxy it
return {
...item,
content: this.createItemContentProxy(isObject(item.content) ? item.content : Object(item.content), key),
};
} else {
// ...otherwise just return a clone of the item.
return { ...item };
}
});
return items.sort((a, b) => b.priority - a.priority).map((item) => item.content);
}
/**
* A read-only map of all keys to their respective items in no particular order.
*
* We don't allow adding new items to the ItemList via setting new properties,
* nor do we allow modifying existing items directly. You should use the
* {@link ItemList.add}, {@link ItemList.setContent} and
* {@link ItemList.setPriority} methods instead.
*
* To match the old behaviour of the `ItemList.items` property, call
* `Object.values(ItemList.toObject())`.
*
* @example
* const items = new ItemList();
* items.add('b', 'My cool value', 20);
* items.add('a', 'My value', 10);
* items.toObject();
* // {
* // a: { content: 'My value', priority: 10, itemName: 'a' },
* // b: { content: 'My cool value', priority: 20, itemName: 'b' },
* // }
*/
toObject(): DeepReadonly<Record<string, IItemObject<T>>> {
return Object.keys(this._items).reduce((map, key) => {
const obj = {
content: this.get(key),
itemName: key,
priority: this.getPriority(key),
};
map[key] = obj;
return map;
}, {} as Record<string, IItemObject<T>>);
}
/**
* Proxies an item's content, adding the `itemName` readonly property to it.
*
* @example
* createItemContentProxy({ foo: 'bar' }, 'myItem');
* // { foo: 'bar', itemName: 'myItem' }
*
* @param content The item's content (objects only)
* @param key The item's key
* @return Proxied content
*
* @internal
*/
private createItemContentProxy<C extends object>(content: C, key: string): Readonly<C & { itemName: string }> {
return new Proxy(content, {
get(target, property, receiver) {
if (property === 'itemName') return key;
return Reflect.get(target, property, receiver);
},
set(target, property, value, receiver) {
if (key !== null && property === 'itemName') {
throw new Error('`itemName` property is read-only');
}
return Reflect.set(target, property, value, receiver);
},
}) as C & { itemName: string };
}
}