@ldo/subscribable-dataset 0.0.1-1.0.0-alpha.1.0

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.
Files changed (43) hide show
  1. package/LICENSE.txt +21 -0
  2. package/Readme.md +298 -0
  3. package/dist/SubscribableDataset.d.ts +37 -0
  4. package/dist/SubscribableDataset.js +180 -0
  5. package/dist/SubscribableDataset.js.map +1 -0
  6. package/dist/SubscribableDatasetFactory.d.ts +9 -0
  7. package/dist/SubscribableDatasetFactory.js +15 -0
  8. package/dist/SubscribableDatasetFactory.js.map +1 -0
  9. package/dist/TransactionDataset.d.ts +25 -0
  10. package/dist/TransactionDataset.js +124 -0
  11. package/dist/TransactionDataset.js.map +1 -0
  12. package/dist/TransactionDatasetFactory.d.ts +9 -0
  13. package/dist/TransactionDatasetFactory.js +15 -0
  14. package/dist/TransactionDatasetFactory.js.map +1 -0
  15. package/dist/createSubscribableDataset.d.ts +5 -0
  16. package/dist/createSubscribableDataset.js +25 -0
  17. package/dist/createSubscribableDataset.js.map +1 -0
  18. package/dist/createSubscribableDatasetFromSerializedInput.d.ts +4 -0
  19. package/dist/createSubscribableDatasetFromSerializedInput.js +11 -0
  20. package/dist/createSubscribableDatasetFromSerializedInput.js.map +1 -0
  21. package/dist/index.d.ts +9 -0
  22. package/dist/index.js +28 -0
  23. package/dist/index.js.map +1 -0
  24. package/dist/mergeDatasetChanges.d.ts +3 -0
  25. package/dist/mergeDatasetChanges.js +39 -0
  26. package/dist/mergeDatasetChanges.js.map +1 -0
  27. package/dist/types.d.ts +35 -0
  28. package/dist/types.js +3 -0
  29. package/dist/types.js.map +1 -0
  30. package/dist/util.d.ts +3 -0
  31. package/dist/util.js +20 -0
  32. package/dist/util.js.map +1 -0
  33. package/package.json +47 -0
  34. package/src/SubscribableDataset.ts +424 -0
  35. package/src/SubscribableDatasetFactory.ts +31 -0
  36. package/src/TransactionDataset.ts +284 -0
  37. package/src/TransactionDatasetFactory.ts +27 -0
  38. package/src/createSubscribableDataset.ts +46 -0
  39. package/src/createSubscribableDatasetFromSerializedInput.ts +28 -0
  40. package/src/index.ts +9 -0
  41. package/src/mergeDatasetChanges.ts +53 -0
  42. package/src/types.ts +167 -0
  43. package/src/util.ts +27 -0
@@ -0,0 +1,424 @@
1
+ import { EventEmitter } from "events";
2
+ import { quadMatchToString, stringToQuadMatch } from "@ldo/rdf-utils";
3
+ import type {
4
+ DatasetChanges,
5
+ QuadMatch,
6
+ SubjectNode,
7
+ PredicateNode,
8
+ ObjectNode,
9
+ GraphNode,
10
+ } from "@ldo/rdf-utils";
11
+ import type { Dataset, BaseQuad, Term, DatasetFactory } from "@rdfjs/types";
12
+ import type {
13
+ nodeEventListener,
14
+ ISubscribableDataset,
15
+ ITransactionDataset,
16
+ ITransactionDatasetFactory,
17
+ } from "./types";
18
+ import { ExtendedDataset } from "@ldo/dataset";
19
+
20
+ /**
21
+ * A wrapper for a dataset that allows subscriptions to be made on nodes to
22
+ * be triggered whenever a quad containing that added or removed.
23
+ */
24
+ export class SubscribableDataset<InAndOutQuad extends BaseQuad = BaseQuad>
25
+ extends ExtendedDataset<InAndOutQuad>
26
+ implements ISubscribableDataset<InAndOutQuad>
27
+ {
28
+ /**
29
+ * DatasetFactory for creating new datasets
30
+ */
31
+ protected datasetFactory: DatasetFactory<InAndOutQuad>;
32
+
33
+ /**
34
+ * The underlying event emitter
35
+ */
36
+ protected eventEmitter: EventEmitter;
37
+ /**
38
+ * The underlying dataset factory for creating transaction datasets
39
+ */
40
+ protected transactionDatasetFactory: ITransactionDatasetFactory<InAndOutQuad>;
41
+ /**
42
+ * Helps find all the events for a given listener
43
+ */
44
+ private listenerHashMap: Map<nodeEventListener<InAndOutQuad>, Set<string>> =
45
+ new Map();
46
+
47
+ /**
48
+ * @param datasetFactory A RDF/JS Dataset Factory
49
+ * @param initialDataset An RDF/JS Dataset with initial Quads
50
+ */
51
+ constructor(
52
+ datasetFactory: DatasetFactory<InAndOutQuad, InAndOutQuad>,
53
+ transactionDatasetFactory: ITransactionDatasetFactory<InAndOutQuad>,
54
+ initialDataset?: Dataset<InAndOutQuad, InAndOutQuad>,
55
+ ) {
56
+ super(initialDataset || datasetFactory.dataset(), datasetFactory);
57
+ this.transactionDatasetFactory = transactionDatasetFactory;
58
+ this.eventEmitter = new EventEmitter();
59
+ this.datasetFactory = datasetFactory;
60
+ }
61
+
62
+ /**
63
+ * ==================================================================
64
+ * DATASET METHODS
65
+ * ==================================================================
66
+ */
67
+
68
+ /**
69
+ * A helper method that mimics what the super of addAll would be
70
+ */
71
+ private superAddAll(
72
+ quads: Dataset<InAndOutQuad, InAndOutQuad> | InAndOutQuad[],
73
+ ): this {
74
+ for (const quad of quads) {
75
+ super.add(quad);
76
+ }
77
+ return this;
78
+ }
79
+
80
+ /**
81
+ * Imports the quads into this dataset.
82
+ * This method differs from Dataset.union in that it adds all quads to the current instance, rather than combining quads and the current instance to create a new instance.
83
+ * @param quads
84
+ * @returns the dataset instance it was called on.
85
+ */
86
+ public addAll(
87
+ quads: Dataset<InAndOutQuad, InAndOutQuad> | InAndOutQuad[],
88
+ ): this {
89
+ this.superAddAll(quads);
90
+ this.triggerSubscriptionForQuads({
91
+ added: this.datasetFactory.dataset(quads),
92
+ });
93
+ return this;
94
+ }
95
+
96
+ /**
97
+ * Bulk add and remove triples
98
+ * @param changed
99
+ */
100
+ public bulk(changed: DatasetChanges<InAndOutQuad>): this {
101
+ if (changed.added) {
102
+ this.superAddAll(changed.added);
103
+ }
104
+ if (changed.removed) {
105
+ changed.removed.forEach((quad) => {
106
+ super.delete(quad);
107
+ });
108
+ }
109
+ this.triggerSubscriptionForQuads(changed);
110
+ return this;
111
+ }
112
+
113
+ /**
114
+ * This method removes the quads in the current instance that match the given arguments. The logic described in Quad Matching is applied for each quad in this dataset to select the quads which will be deleted.
115
+ * @param subject
116
+ * @param predicate
117
+ * @param object
118
+ * @param graph
119
+ * @returns the dataset instance it was called on.
120
+ */
121
+ public deleteMatches(
122
+ subject?: Term,
123
+ predicate?: Term,
124
+ object?: Term,
125
+ graph?: Term,
126
+ ): this {
127
+ const matching = super.match(subject, predicate, object, graph);
128
+ for (const quad of matching) {
129
+ super.delete(quad);
130
+ }
131
+ this.triggerSubscriptionForQuads({ removed: matching });
132
+ return this;
133
+ }
134
+
135
+ /**
136
+ * Adds the specified quad to the dataset.
137
+ * Existing quads, as defined in Quad.equals, will be ignored.
138
+ * @param quad
139
+ * @returns the dataset instance it was called on.
140
+ */
141
+ public add(quad: InAndOutQuad): this {
142
+ super.add(quad);
143
+ this.triggerSubscriptionForQuads({
144
+ added: this.datasetFactory.dataset([quad]),
145
+ });
146
+ return this;
147
+ }
148
+
149
+ /**
150
+ * Removes the specified quad from the dataset.
151
+ * This method returns the dataset instance it was called on.
152
+ * @param quad
153
+ */
154
+ public delete(quad: InAndOutQuad): this {
155
+ super.delete(quad);
156
+ this.triggerSubscriptionForQuads({
157
+ removed: this.datasetFactory.dataset([quad]),
158
+ });
159
+ return this;
160
+ }
161
+
162
+ /**
163
+ * ==================================================================
164
+ * EVENTEMITTER METHODS
165
+ * ==================================================================
166
+ */
167
+
168
+ /**
169
+ * Triggers all subscriptions based on an updated quads
170
+ * @param changed The changed triples of the transaction
171
+ */
172
+ private triggerSubscriptionForQuads(
173
+ changed: DatasetChanges<InAndOutQuad>,
174
+ ): void {
175
+ // A mapping of serialized QuadMatches to the changed quads
176
+ const matchingDatasetChanges: Record<
177
+ string,
178
+ DatasetChanges<InAndOutQuad>
179
+ > = {};
180
+
181
+ // Population MatchingDatasetChanges
182
+ const populateMatchingDatasetChanges = (
183
+ changeType: "added" | "removed",
184
+ ) => {
185
+ const changedQuads = changed[changeType];
186
+ changedQuads?.forEach((changedQuad) => {
187
+ // Cast the input because RDFJS types assume RDF 1.2 where a Subject can
188
+ // be a Quad
189
+ const quad = changedQuad as {
190
+ subject: SubjectNode;
191
+ predicate: PredicateNode;
192
+ object: ObjectNode;
193
+ graph: GraphNode;
194
+ };
195
+ // All possible matches that could match with this triple
196
+ const quadMatches: QuadMatch[] = [
197
+ [null, null, null, null],
198
+ [quad.subject, null, null, null],
199
+ [quad.subject, quad.predicate, null, null],
200
+ [quad.subject, null, quad.object, null],
201
+ [null, quad.predicate, null, null],
202
+ [null, quad.predicate, quad.object, null],
203
+ [null, null, quad.object, null],
204
+ [quad.subject, quad.predicate, quad.object, null],
205
+ [null, null, null, quad.graph],
206
+ [quad.subject, null, null, quad.graph],
207
+ [quad.subject, quad.predicate, null, quad.graph],
208
+ [quad.subject, null, quad.object, quad.graph],
209
+ [null, quad.predicate, null, quad.graph],
210
+ [null, quad.predicate, quad.object, quad.graph],
211
+ [null, null, quad.object, quad.graph],
212
+ [quad.subject, quad.predicate, quad.object, quad.graph],
213
+ ];
214
+ quadMatches.forEach((quadMatch) => {
215
+ const eventName = quadMatchToString(quadMatch);
216
+ // Only add to the map if there's actually a listener for this
217
+ if (this.eventEmitter.listenerCount(eventName) > 0) {
218
+ // Set matchingDatasetChanges to include data to emit
219
+ if (!matchingDatasetChanges[eventName]) {
220
+ matchingDatasetChanges[eventName] = {};
221
+ }
222
+ if (!matchingDatasetChanges[eventName][changeType]) {
223
+ matchingDatasetChanges[eventName][changeType] =
224
+ this.datasetFactory.dataset();
225
+ }
226
+ matchingDatasetChanges[eventName][changeType]?.add(changedQuad);
227
+ }
228
+ });
229
+ });
230
+ };
231
+ populateMatchingDatasetChanges("added");
232
+ populateMatchingDatasetChanges("removed");
233
+
234
+ // Alert all listeners
235
+ Object.entries(matchingDatasetChanges).forEach(
236
+ ([quadMatchString, changes]) => {
237
+ this.eventEmitter.emit(quadMatchString, changes);
238
+ },
239
+ );
240
+ }
241
+
242
+ /**
243
+ * Alias for emitter.on(eventName, listener).
244
+ * @param eventName
245
+ * @param listener
246
+ * @returns
247
+ */
248
+ public addListener(
249
+ eventName: QuadMatch,
250
+ listener: nodeEventListener<InAndOutQuad>,
251
+ ): this {
252
+ return this.on(eventName, listener);
253
+ }
254
+
255
+ /**
256
+ * Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.
257
+ * @param eventName
258
+ * @param dataset
259
+ * @param datasetChanges
260
+ * @returns true if the event had listeners, false otherwise.
261
+ */
262
+ public emit(
263
+ eventName: QuadMatch,
264
+ changes: DatasetChanges<InAndOutQuad>,
265
+ ): boolean {
266
+ return this.eventEmitter.emit(quadMatchToString(eventName), changes);
267
+ }
268
+
269
+ /**
270
+ * Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.
271
+ */
272
+ public eventNames(): QuadMatch[] {
273
+ return this.eventEmitter
274
+ .eventNames()
275
+ .map((eventName) => stringToQuadMatch(eventName as string));
276
+ }
277
+
278
+ /**
279
+ * Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to events.defaultMaxListeners.
280
+ */
281
+ public getMaxListeners(): number {
282
+ return this.eventEmitter.getMaxListeners();
283
+ }
284
+
285
+ /**
286
+ * Returns the number of listeners listening to the event named eventName.
287
+ */
288
+ public listenerCount(eventName: QuadMatch): number {
289
+ return this.eventEmitter.listenerCount(quadMatchToString(eventName));
290
+ }
291
+
292
+ /**
293
+ * Returns a copy of the array of listeners for the event named eventName.
294
+ */
295
+ public listeners(eventName: QuadMatch): nodeEventListener<InAndOutQuad>[] {
296
+ return this.eventEmitter.listeners(
297
+ quadMatchToString(eventName),
298
+ ) as nodeEventListener<InAndOutQuad>[];
299
+ }
300
+
301
+ /**
302
+ * Alias for emitter.removeListener()
303
+ */
304
+ public off(
305
+ eventName: QuadMatch,
306
+ listener: nodeEventListener<InAndOutQuad>,
307
+ ): void {
308
+ this.removeListener(eventName, listener);
309
+ }
310
+
311
+ /**
312
+ * Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.
313
+ */
314
+ public on(
315
+ eventName: QuadMatch,
316
+ listener: nodeEventListener<InAndOutQuad>,
317
+ ): this {
318
+ const eventString = quadMatchToString(eventName);
319
+ if (!this.listenerHashMap.has(listener)) {
320
+ this.listenerHashMap.set(listener, new Set());
321
+ }
322
+ this.listenerHashMap.get(listener)?.add(eventString);
323
+ this.eventEmitter.on(eventString, listener);
324
+ return this;
325
+ }
326
+
327
+ /**
328
+ * Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.
329
+ */
330
+ public once(
331
+ eventName: QuadMatch,
332
+ listener: nodeEventListener<InAndOutQuad>,
333
+ ): this {
334
+ this.eventEmitter.once(quadMatchToString(eventName), listener);
335
+ return this;
336
+ }
337
+
338
+ /**
339
+ * Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.
340
+ */
341
+ public prependListener(
342
+ eventName: QuadMatch,
343
+ listener: nodeEventListener<InAndOutQuad>,
344
+ ): this {
345
+ this.eventEmitter.prependListener(quadMatchToString(eventName), listener);
346
+ return this;
347
+ }
348
+
349
+ /**
350
+ * Adds a one-time listener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.
351
+ */
352
+ public prependOnceListener(
353
+ eventName: QuadMatch,
354
+ listener: nodeEventListener<InAndOutQuad>,
355
+ ): this {
356
+ this.eventEmitter.prependOnceListener(
357
+ quadMatchToString(eventName),
358
+ listener,
359
+ );
360
+ return this;
361
+ }
362
+
363
+ /**
364
+ * Removes all listeners, or those of the specified eventName.
365
+ */
366
+ public removeAllListeners(eventName: QuadMatch): this {
367
+ this.eventEmitter.removeAllListeners(quadMatchToString(eventName));
368
+ return this;
369
+ }
370
+
371
+ /**
372
+ * Removes the specified listener from the listener array for the event named eventName.
373
+ */
374
+ public removeListener(
375
+ eventName: QuadMatch,
376
+ listener: nodeEventListener<InAndOutQuad>,
377
+ ): this {
378
+ this.eventEmitter.removeListener(quadMatchToString(eventName), listener);
379
+ return this;
380
+ }
381
+
382
+ /**
383
+ * Removes the specified listener from the listener array for the event named eventName.
384
+ */
385
+ removeListenerFromAllEvents(listener: nodeEventListener<InAndOutQuad>): this {
386
+ const eventStringSet = this.listenerHashMap.get(listener);
387
+ if (eventStringSet) {
388
+ eventStringSet.forEach((eventString) => {
389
+ this.eventEmitter.off(eventString, listener);
390
+ });
391
+ }
392
+ return this;
393
+ }
394
+
395
+ /**
396
+ * By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.
397
+ */
398
+ public setMaxListeners(n: number): this {
399
+ this.eventEmitter.setMaxListeners(n);
400
+ return this;
401
+ }
402
+
403
+ /**
404
+ * Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).
405
+ */
406
+ public rawListeners(eventName: QuadMatch): nodeEventListener<InAndOutQuad>[] {
407
+ return this.eventEmitter.rawListeners(
408
+ quadMatchToString(eventName),
409
+ ) as nodeEventListener[];
410
+ }
411
+
412
+ /**
413
+ * ==================================================================
414
+ * TRANSACTION METHODS
415
+ * ==================================================================
416
+ */
417
+
418
+ /**
419
+ * Returns a transactional dataset that will update this dataset when its transaction is committed.
420
+ */
421
+ public startTransaction(): ITransactionDataset<InAndOutQuad> {
422
+ return this.transactionDatasetFactory.transactionDataset(this);
423
+ }
424
+ }
@@ -0,0 +1,31 @@
1
+ import type { DatasetFactory, BaseQuad, Dataset } from "@rdfjs/types";
2
+ import type { ITransactionDatasetFactory } from "./types";
3
+ import { SubscribableDataset } from "./SubscribableDataset";
4
+
5
+ /**
6
+ * A DatasetFactory that returns a SubscribableDataset given a generic DatasetFactory.
7
+ */
8
+ export class SubscribableDatasetFactory<
9
+ InAndOutQuad extends BaseQuad = BaseQuad,
10
+ > implements DatasetFactory<InAndOutQuad, InAndOutQuad>
11
+ {
12
+ protected datasetFactory: DatasetFactory<InAndOutQuad, InAndOutQuad>;
13
+ protected transactionDatasetFactory: ITransactionDatasetFactory<InAndOutQuad>;
14
+ constructor(
15
+ datasetFactory: DatasetFactory<InAndOutQuad, InAndOutQuad>,
16
+ transactionDatasetFactory: ITransactionDatasetFactory<InAndOutQuad>,
17
+ ) {
18
+ this.datasetFactory = datasetFactory;
19
+ this.transactionDatasetFactory = transactionDatasetFactory;
20
+ }
21
+
22
+ dataset(
23
+ quads?: Dataset<InAndOutQuad, InAndOutQuad> | InAndOutQuad[],
24
+ ): SubscribableDataset<InAndOutQuad> {
25
+ return new SubscribableDataset(
26
+ this.datasetFactory,
27
+ this.transactionDatasetFactory,
28
+ quads ? this.datasetFactory.dataset(quads) : undefined,
29
+ );
30
+ }
31
+ }