@ldo/jsonld-dataset-proxy 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 (166) hide show
  1. package/LICENSE.txt +21 -0
  2. package/README.md +830 -0
  3. package/dist/ContextUtil.d.ts +17 -0
  4. package/dist/ContextUtil.js +108 -0
  5. package/dist/ContextUtil.js.map +1 -0
  6. package/dist/JsonldDatasetProxyBuilder.d.ts +16 -0
  7. package/dist/JsonldDatasetProxyBuilder.js +41 -0
  8. package/dist/JsonldDatasetProxyBuilder.js.map +1 -0
  9. package/dist/LdoJsonldContext.d.ts +8 -0
  10. package/dist/LdoJsonldContext.js +3 -0
  11. package/dist/LdoJsonldContext.js.map +1 -0
  12. package/dist/ProxyContext.d.ts +31 -0
  13. package/dist/ProxyContext.js +63 -0
  14. package/dist/ProxyContext.js.map +1 -0
  15. package/dist/arrayProxy/ArrayProxy.d.ts +12 -0
  16. package/dist/arrayProxy/ArrayProxy.js +3 -0
  17. package/dist/arrayProxy/ArrayProxy.js.map +1 -0
  18. package/dist/arrayProxy/arrayMethods.d.ts +17 -0
  19. package/dist/arrayProxy/arrayMethods.js +161 -0
  20. package/dist/arrayProxy/arrayMethods.js.map +1 -0
  21. package/dist/arrayProxy/createArrayHandler.d.ts +9 -0
  22. package/dist/arrayProxy/createArrayHandler.js +140 -0
  23. package/dist/arrayProxy/createArrayHandler.js.map +1 -0
  24. package/dist/arrayProxy/isArrayProxy.d.ts +2 -0
  25. package/dist/arrayProxy/isArrayProxy.js +17 -0
  26. package/dist/arrayProxy/isArrayProxy.js.map +1 -0
  27. package/dist/arrayProxy/modifyArray.d.ts +12 -0
  28. package/dist/arrayProxy/modifyArray.js +73 -0
  29. package/dist/arrayProxy/modifyArray.js.map +1 -0
  30. package/dist/graphOf.d.ts +4 -0
  31. package/dist/graphOf.js +25 -0
  32. package/dist/graphOf.js.map +1 -0
  33. package/dist/index.d.ts +34 -0
  34. package/dist/index.js +51 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/jsonldDatasetProxy.d.ts +5 -0
  37. package/dist/jsonldDatasetProxy.js +19 -0
  38. package/dist/jsonldDatasetProxy.js.map +1 -0
  39. package/dist/language/languageMapProxy.d.ts +4 -0
  40. package/dist/language/languageMapProxy.js +55 -0
  41. package/dist/language/languageMapProxy.js.map +1 -0
  42. package/dist/language/languageSet.d.ts +23 -0
  43. package/dist/language/languageSet.js +75 -0
  44. package/dist/language/languageSet.js.map +1 -0
  45. package/dist/language/languageTypes.d.ts +2 -0
  46. package/dist/language/languageTypes.js +3 -0
  47. package/dist/language/languageTypes.js.map +1 -0
  48. package/dist/language/languageUtils.d.ts +14 -0
  49. package/dist/language/languageUtils.js +73 -0
  50. package/dist/language/languageUtils.js.map +1 -0
  51. package/dist/language/languagesOf.d.ts +13 -0
  52. package/dist/language/languagesOf.js +17 -0
  53. package/dist/language/languagesOf.js.map +1 -0
  54. package/dist/setLanguagePreferences.d.ts +3 -0
  55. package/dist/setLanguagePreferences.js +9 -0
  56. package/dist/setLanguagePreferences.js.map +1 -0
  57. package/dist/setProxy/ObjectSetProxy.d.ts +17 -0
  58. package/dist/setProxy/ObjectSetProxy.js +31 -0
  59. package/dist/setProxy/ObjectSetProxy.js.map +1 -0
  60. package/dist/setProxy/SetProxy.d.ts +29 -0
  61. package/dist/setProxy/SetProxy.js +72 -0
  62. package/dist/setProxy/SetProxy.js.map +1 -0
  63. package/dist/setProxy/SubjectSetProxy.d.ts +15 -0
  64. package/dist/setProxy/SubjectSetProxy.js +38 -0
  65. package/dist/setProxy/SubjectSetProxy.js.map +1 -0
  66. package/dist/setProxy/WildcardObjectSetProxy.d.ts +20 -0
  67. package/dist/setProxy/WildcardObjectSetProxy.js +49 -0
  68. package/dist/setProxy/WildcardObjectSetProxy.js.map +1 -0
  69. package/dist/setProxy/WildcardSubjectSetProxy.d.ts +19 -0
  70. package/dist/setProxy/WildcardSubjectSetProxy.js +31 -0
  71. package/dist/setProxy/WildcardSubjectSetProxy.js.map +1 -0
  72. package/dist/setProxy/createNewSetProxy.d.ts +5 -0
  73. package/dist/setProxy/createNewSetProxy.js +27 -0
  74. package/dist/setProxy/createNewSetProxy.js.map +1 -0
  75. package/dist/setProxy/isSetProxy.d.ts +2 -0
  76. package/dist/setProxy/isSetProxy.js +13 -0
  77. package/dist/setProxy/isSetProxy.js.map +1 -0
  78. package/dist/setProxy/ldSet/BasicLdSet.d.ts +36 -0
  79. package/dist/setProxy/ldSet/BasicLdSet.js +193 -0
  80. package/dist/setProxy/ldSet/BasicLdSet.js.map +1 -0
  81. package/dist/setProxy/ldSet/LdSet.d.ts +30 -0
  82. package/dist/setProxy/ldSet/LdSet.js +3 -0
  83. package/dist/setProxy/ldSet/LdSet.js.map +1 -0
  84. package/dist/setProxy/set.d.ts +2 -0
  85. package/dist/setProxy/set.js +9 -0
  86. package/dist/setProxy/set.js.map +1 -0
  87. package/dist/subjectProxy/SubjectProxy.d.ts +14 -0
  88. package/dist/subjectProxy/SubjectProxy.js +3 -0
  89. package/dist/subjectProxy/SubjectProxy.js.map +1 -0
  90. package/dist/subjectProxy/createSubjectHandler.d.ts +6 -0
  91. package/dist/subjectProxy/createSubjectHandler.js +75 -0
  92. package/dist/subjectProxy/createSubjectHandler.js.map +1 -0
  93. package/dist/subjectProxy/deleteFromDataset.d.ts +3 -0
  94. package/dist/subjectProxy/deleteFromDataset.js +25 -0
  95. package/dist/subjectProxy/deleteFromDataset.js.map +1 -0
  96. package/dist/subjectProxy/getValueForKey.d.ts +5 -0
  97. package/dist/subjectProxy/getValueForKey.js +41 -0
  98. package/dist/subjectProxy/getValueForKey.js.map +1 -0
  99. package/dist/subjectProxy/isSubjectProxy.d.ts +4 -0
  100. package/dist/subjectProxy/isSubjectProxy.js +25 -0
  101. package/dist/subjectProxy/isSubjectProxy.js.map +1 -0
  102. package/dist/types.d.ts +9 -0
  103. package/dist/types.js +11 -0
  104. package/dist/types.js.map +1 -0
  105. package/dist/util/NodeSet.d.ts +9 -0
  106. package/dist/util/NodeSet.js +35 -0
  107. package/dist/util/NodeSet.js.map +1 -0
  108. package/dist/util/RawObject.d.ts +9 -0
  109. package/dist/util/RawObject.js +3 -0
  110. package/dist/util/RawObject.js.map +1 -0
  111. package/dist/util/addObjectToDataset.d.ts +8 -0
  112. package/dist/util/addObjectToDataset.js +83 -0
  113. package/dist/util/addObjectToDataset.js.map +1 -0
  114. package/dist/util/createInteractOptions.d.ts +6 -0
  115. package/dist/util/createInteractOptions.js +37 -0
  116. package/dist/util/createInteractOptions.js.map +1 -0
  117. package/dist/util/getNodeFromRaw.d.ts +6 -0
  118. package/dist/util/getNodeFromRaw.js +47 -0
  119. package/dist/util/getNodeFromRaw.js.map +1 -0
  120. package/dist/util/isProxy.d.ts +6 -0
  121. package/dist/util/isProxy.js +17 -0
  122. package/dist/util/isProxy.js.map +1 -0
  123. package/dist/util/nodeToJsonldRepresentation.d.ts +7 -0
  124. package/dist/util/nodeToJsonldRepresentation.js +75 -0
  125. package/dist/util/nodeToJsonldRepresentation.js.map +1 -0
  126. package/dist/write.d.ts +3 -0
  127. package/dist/write.js +9 -0
  128. package/dist/write.js.map +1 -0
  129. package/package.json +53 -0
  130. package/src/ContextUtil.ts +173 -0
  131. package/src/JsonldDatasetProxyBuilder.ts +107 -0
  132. package/src/LdoJsonldContext.ts +14 -0
  133. package/src/ProxyContext.ts +118 -0
  134. package/src/graphOf.ts +52 -0
  135. package/src/index.ts +39 -0
  136. package/src/jsonldDatasetProxy.ts +28 -0
  137. package/src/language/languageMapProxy.ts +75 -0
  138. package/src/language/languageSet.ts +129 -0
  139. package/src/language/languageTypes.ts +3 -0
  140. package/src/language/languageUtils.ts +159 -0
  141. package/src/language/languagesOf.ts +65 -0
  142. package/src/setLanguagePreferences.ts +14 -0
  143. package/src/setProxy/ObjectSetProxy.ts +66 -0
  144. package/src/setProxy/SetProxy.ts +141 -0
  145. package/src/setProxy/SubjectSetProxy.ts +85 -0
  146. package/src/setProxy/WildcardObjectSetProxy.ts +89 -0
  147. package/src/setProxy/WildcardSubjectSetProxy.ts +58 -0
  148. package/src/setProxy/createNewSetProxy.ts +47 -0
  149. package/src/setProxy/isSetProxy.ts +7 -0
  150. package/src/setProxy/ldSet/BasicLdSet.ts +266 -0
  151. package/src/setProxy/ldSet/LdSet.ts +189 -0
  152. package/src/setProxy/set.ts +14 -0
  153. package/src/subjectProxy/SubjectProxy.ts +20 -0
  154. package/src/subjectProxy/createSubjectHandler.ts +115 -0
  155. package/src/subjectProxy/deleteFromDataset.ts +33 -0
  156. package/src/subjectProxy/getValueForKey.ts +62 -0
  157. package/src/subjectProxy/isSubjectProxy.ts +30 -0
  158. package/src/types.ts +11 -0
  159. package/src/util/NodeSet.ts +35 -0
  160. package/src/util/RawObject.ts +21 -0
  161. package/src/util/addObjectToDataset.ts +147 -0
  162. package/src/util/createInteractOptions.ts +55 -0
  163. package/src/util/getNodeFromRaw.ts +54 -0
  164. package/src/util/isProxy.ts +21 -0
  165. package/src/util/nodeToJsonldRepresentation.ts +78 -0
  166. package/src/write.ts +12 -0
package/README.md ADDED
@@ -0,0 +1,830 @@
1
+ # JSONLD Dataset Proxy
2
+
3
+ Edit RDFJS Dataset just like regular JavaScript Object Literals.
4
+
5
+ Just a few lines of familiar code:
6
+ ```typescript
7
+ const personNode = namedNode("http://example.com/Person1");
8
+ const person = jsonldDatasetProxy(
9
+ dataset,
10
+ PersonContext
11
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
12
+ person.age = 23;
13
+ person.name.add("John");
14
+ ```
15
+
16
+ are equivalent to:
17
+ ```typescript
18
+ dataset.deleteMatches(
19
+ namedNode("http://example.com/Person1"),
20
+ namedNode("http://xmlns.com/foaf/0.1/age")
21
+ );
22
+ dataset.add(
23
+ quad(
24
+ namedNode("http://example.com/Person1"),
25
+ namedNode("http://xmlns.com/foaf/0.1/age"),
26
+ literal("23", "http://www.w3.org/2001/XMLSchema#integer")
27
+ )
28
+ );
29
+ dataset.add(
30
+ quad(
31
+ namedNode("http://example.com/Person1"),
32
+ namedNode("http://xmlns.com/foaf/0.1/name"),
33
+ literal("John", "http://www.w3.org/2001/XMLSchema#string")
34
+ )
35
+ );
36
+ ```
37
+
38
+ Plus, you get IntelliSense typescript suggestions to help you write your code!
39
+
40
+ ![Intellisense Example](./readme-images/Intellisense.png)
41
+
42
+
43
+ ## Installation
44
+ ```bash
45
+ npm install @ldo/jsonld-dataset-proxy
46
+ ```
47
+
48
+ ## Simple Example
49
+ ```typescript
50
+ import jsonldDatasetProxy, { write, LdSet } from "jsonld-dataset-proxy";
51
+ import { ContextDefinition } from "jsonld";
52
+ import { serializedToDataset } from "@ldo/dataset";
53
+ import { namedNode } from "@rdfjs/data-model";
54
+
55
+ async function start() {
56
+ // Define initial data
57
+ const initialData = `
58
+ @prefix example: <http://example.com/> .
59
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
60
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
61
+
62
+ example:Person1
63
+ foaf:name "Johnathan"^^xsd:string;
64
+ foaf:age "22"^^xsd:integer.
65
+ `;
66
+ // Create a dataset loaded with initial data
67
+ const dataset = await serializedToDataset(initialData);
68
+ // Make a JSONLD Dataset Proxy
69
+ const person = jsonldDatasetProxy(
70
+ dataset,
71
+ PersonContext
72
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
73
+ // Make Modifications
74
+ person.age = 23;
75
+ person.name.add("John");
76
+ write(namedNode("http://example.com/otherGraph")).using(person);
77
+ person.name.add("Smith");
78
+
79
+ console.log(dataset.toString());
80
+ // Logs:
81
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Johnathan" .
82
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "John" .
83
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/age> "23"^^<http://www.w3.org/2001/XMLSchema#integer> .
84
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Smith" <http://example.com/otherGraph> .
85
+ }
86
+
87
+ // Person Typescript Typing
88
+ interface IPerson {
89
+ name: LdSet<string>;
90
+ age: number;
91
+ }
92
+
93
+ // Person JSONLD Context
94
+ const PersonContext: ContextDefinition = {
95
+ name: {
96
+ "@id": "http://xmlns.com/foaf/0.1/name",
97
+ "@type": "http://www.w3.org/2001/XMLSchema#string",
98
+ "@container": "@set",
99
+ },
100
+ age: {
101
+ "@id": "http://xmlns.com/foaf/0.1/age",
102
+ "@type": "http://www.w3.org/2001/XMLSchema#integer",
103
+ },
104
+ };
105
+
106
+ start();
107
+ ```
108
+
109
+ ## Full Usage
110
+
111
+ - [Defining a Context and Type](#defining-a-context-and-type)
112
+ - [Getting a Jsonld DatasetProxy](#getting-a-jsonld-dataset-proxy)
113
+ - [`.fromSubject<T>(entryNode)`](#fromsubjecttentrynode)
114
+ - [`.matchSubject<T>(predicate?, object?, graph?)`](#matchsubjecttpredicate-object-graph)
115
+ - [`.matchObject<T>(subject?, predicate?, graph?)`](#matchobjecttsubject-predicate-object)
116
+ - [`.fromJson<T>(inputData)`](#fromjsontinputdata)
117
+ - [Getting Field Values and Traversing](#getting-field-values-and-traversing)
118
+ - [Setting a Primitive](#setting-a-primitive)
119
+ - [Setting an Object](#setting-an-object)
120
+ - [Set Methods](#set-methods)
121
+ - [Overwriting an Object](#overwriting-an-object)
122
+ - [Changing an Object's Id](#changing-an-objects-id)
123
+ - [Removing an Object Connection](#removing-an-object-connection)
124
+ - [Deleting an Entire Object](#deleting-an-entire-object)
125
+ - [Using Blank Nodes](#using-blank-nodes)
126
+ - [Writing Information to a Specific Graph](#writing-information-to-a-specific-graph)
127
+ - [`jsonldDatasetProxy(...).write(...graphs)`](#jsonlddatasetproxywritegraphs)
128
+ - [`write(...graphs).using(...jsonldDatasetProxies)`](#writegraphsusingjsonlddatasetproxies)
129
+ - [`write(...graphs).usingCopy(...jsonldDatasetProxies)`](#writegraphsusingcopyjsonlddatasetproxies)
130
+ - [Detecting a the graph of specific information](#detecting-a-the-graph-of-specific-information)
131
+
132
+ For the most part, you can think of a JSONLD Dataset Proxy as a JavaScript Object Literal with "Sets" instead of arrays.
133
+
134
+ ### Defining a Context and Type
135
+ The first step to getting a JSONLD Dataset Proxy is defining the JSONLD Context and TypeScript Typings. This can either be done through a [generator](https://ldo.js.org/latest/api/cli/build/) or defining them manually.
136
+
137
+ In this example typescript typing `IPerson` is an interface that represents a person. Notice the `@id` and `@context` fields. Be sure to include them in your interfaces if you wish to use those properties.
138
+
139
+ ```typescript
140
+ import { LdoJsonldContext, LdSet } from "@ldo/jsonld-dataset-proxy";
141
+
142
+ interface IPerson {
143
+ "@id"?: string;
144
+ "@context"?: LdoJsonldContext;
145
+ name?: LdSet<string>;
146
+ age?: number;
147
+ bestFriend?: IPerson;
148
+ knows?: LdSet<IPerson>;
149
+ }
150
+ ```
151
+
152
+ We can make a [JSONLD context](https://w3c.github.io/json-ld-syntax/#the-context) to match this type:
153
+
154
+ ```typescript
155
+ import { ContextDefinition } from "jsonld";
156
+
157
+ const PersonContext: ContextDefinition = {
158
+ name: {
159
+ "@id": "http://xmlns.com/foaf/0.1/name",
160
+ "@type": "http://www.w3.org/2001/XMLSchema#string",
161
+ "@container": "@set",
162
+ },
163
+ age: {
164
+ "@id": "http://xmlns.com/foaf/0.1/age",
165
+ "@type": "http://www.w3.org/2001/XMLSchema#integer",
166
+ },
167
+ bestFriend: {
168
+ "@id": "http://xmlns.com/foaf/0.1/bestFriend",
169
+ "@type": "@id",
170
+ },
171
+ knows: {
172
+ "@id": "http://xmlns.com/foaf/0.1/knows",
173
+ "@type": "@id",
174
+ "@container": "@set",
175
+ },
176
+ };
177
+ ```
178
+
179
+ To do this, create an object that has corresponding fields to your type. Each field is an object that contains the following properties:
180
+ - `@id`: indicates the URI of the corresponding predicate
181
+ - `@type`: If the corresponding type is a pimitive (Like a number or string), use this field to list the RDF Literal type (Most often this is an XMLSchema type). If the corresponding type is an object, list `@id` here.
182
+ - `@container`: If the corresponding type is an array of items, set `@container` to `@set`, if not, do not include the `@container` property.
183
+
184
+ Note that only the features described here work with JSONLD Dataset Proxy. Other features of JSONLD Contexts are not yet supported.
185
+
186
+ ### Getting a Jsonld Dataset Proxy
187
+ Once the Typescript Typings and Context have been defined, we can get the JSONLD Dataset Proxy for a specific dataset.
188
+
189
+ ```typescript
190
+ import jsonldDatasetProxy from "jsonld-dataset-proxy";
191
+ import { createDataset } from "o-dataset-pack";
192
+
193
+ const dataset = await createDataset();
194
+ // Make a JSONLD Dataset Proxy
195
+ const person = jsonldDatasetProxy(
196
+ dataset,
197
+ PersonContext
198
+ ) // ...
199
+ ```
200
+
201
+ The functon `jsonldDatasetProxy` takes in three parameters:
202
+ - `dataset`: The dataset you wish to traverse and manipulate. This can be any dataset that follows the [RDFJS Dataset Interface](https://rdf.js.org/dataset-spec/#dataset-interface). Note that this is not to be confused with the RDFJS Dataset ***Core*** interface. This example uses the "o-dataset-pack", but any implementation of the RDFJS Dataset Interface is acceptable.
203
+ - `context`: The JSONLD context.
204
+
205
+ After defining the `dataset` and `context` there are a few ways to get Jsonld Dataset Proxies:
206
+
207
+ #### `.fromSubject<T>(entryNode)`
208
+ `fromSubject` lets you define a an `entryNode`, the place of entry for the graph. The object returned by `jsonldDatasetProxy` will represent the given node. This parameter accepts both `namedNode`s and `blankNode`s. `fromSubject` takes a generic type representing the typescript type of the given subject.
209
+
210
+ ```typescript
211
+ const person = jsonldDatasetProxy(
212
+ dataset,
213
+ PersonContext
214
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
215
+ ```
216
+
217
+ #### `.matchSubject<T>(predicate?, object?, graph?)`
218
+ `matchSubject` returns a Jsonld Dataset Proxy representing all subjects in the dataset matching the given predicate, object, and graph.
219
+
220
+ ```typescript
221
+ const people = jsonldDatasetProxy(
222
+ dataset,
223
+ PersonContext
224
+ ).matchSubject<IPerson>(
225
+ namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
226
+ namedNode("http://xmlns.com/foaf/0.1/Person")
227
+ );
228
+ people.forEach((person) => {
229
+ console.log(person.name);
230
+ });
231
+ ```
232
+
233
+ #### `.matchObject<T>(subject?, predicate?, object?)`
234
+ `matchObject` returns a Jsonld Dataset Proxy representing all objects in the dataset matching the given subject, predicate, and graph.
235
+
236
+ ```typescript
237
+ const friendsOfPerson1 = jsonldDatasetProxy(
238
+ dataset,
239
+ PersonContext
240
+ ).matchSubject<IPerson>(
241
+ namedNode("http://example.com/Person1"),
242
+ namedNode("http://xmlns.com/foaf/0.1/knows")
243
+ );
244
+ friendsOfPerson1.forEach((person) => {
245
+ console.log(person.name);
246
+ });
247
+ ```
248
+
249
+ #### `.fromJson<T>(inputData)`
250
+ `fromJson` will take any regular Json, add the information to the dataset, and return a Jsonld Dataset Proxy representing the given data.
251
+
252
+ ```typescript
253
+ import { jsonldDatasetProxy, set } from "@ldo/jsonld-dataset-proxy";
254
+
255
+ const person2 = jsonldDatasetProxy(
256
+ dataset,
257
+ PersonContext
258
+ ).fromJson<IPerson>({
259
+ "@id": "http://example.com/Person2",
260
+ name: set("Jane", "Doe"),
261
+ birthdate: "1990/11/03",
262
+ age: 33,
263
+ });
264
+ ```
265
+
266
+ ### Getting Field Values and Traversing
267
+ Getting a field and traversing the object is just as easy as getting data out of a standard JavaScript Object Literal.
268
+
269
+ In all the following example, we will use a dataset loaded with the following data:
270
+
271
+ ```typescript
272
+ const dataset = await serializedToDataset(`
273
+ @prefix example: <http://example.com/> .
274
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
275
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
276
+
277
+ example:Person1
278
+ foaf:name "Johnathan"^^xsd:string, "John"^^xsd:string;
279
+ foaf:age "22"^^xsd:integer;
280
+ foaf:bestFriend example:Person2;
281
+ foaf:friends example:Person2, example:Person3.
282
+
283
+ example:Person2
284
+ foaf:name "Alice"^^xsd:string;
285
+ foaf:age "28"^^xsd:integer.
286
+
287
+ example:Person3
288
+ foaf:name "Dave"^^xsd:string;
289
+ foaf:age "33"^^xsd:integer.
290
+ `);
291
+ const person = jsonldDatasetProxy(
292
+ dataset,
293
+ PersonContext
294
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
295
+ // Get primitives
296
+ console.log(person.age); // 22
297
+ // Get nested primitives
298
+ console.log(person?.bestFriend?.age); // 28
299
+ // All array methods work
300
+ console.log(person.name?.reduce((agg, cur) => agg + cur, "")); // JonathanJohn
301
+ // You can also access array items via their index
302
+ // But this isn't recommened. The library will do its best to maintain the
303
+ // ordering in the array, but as datasets have no concept of order, this is
304
+ // not always accurate.
305
+ console.log(person.name?.toArray()[0]); // John
306
+ // Get the id of the object
307
+ // (If the node is a blankNode the @id will be undefined)
308
+ console.log(person.bestFriend?.["@id"]); // "http://example.com/Person2"
309
+ // Finally, you can retrieve the context
310
+ console.log(person["@context"]); // { "name": { "@id": ... }}
311
+ ```
312
+
313
+
314
+
315
+ ### Setting a Primitive
316
+ Setting a non-array primitive will remove the existing triple from the dataset and add a new triple.
317
+
318
+ ```typescript
319
+ const dataset = createDataset();
320
+ const person = jsonldDatasetProxy(
321
+ dataset,
322
+ PersonContext
323
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"))
324
+ person.age = 23;
325
+ console.log(dataset.toString());
326
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/age> "23"^^<http://www.w3.org/2001/XMLSchema#integer> .
327
+ ```
328
+
329
+ ### Setting an Object
330
+ Setting a field to a JavaScript object literal will recursively add all parts of the object literal to the dataset.
331
+
332
+ ```typescript
333
+ import { set } from "@ldo/jsonld-dataset-pack";
334
+
335
+ const dataset = createDataset();
336
+ const person = jsonldDatasetProxy(
337
+ dataset,
338
+ PersonContext
339
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
340
+ person.bestFriend = {
341
+ "@id": "http://example.com/Person2",
342
+ name: set("Alice"),
343
+ bestFriend: {
344
+ "@id": "http://example.com/Person3",
345
+ name: set("Bob"),
346
+ },
347
+ };
348
+ console.log(dataset.toString());
349
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/Person2> .
350
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/Person3> .
351
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/name> "Alice" .
352
+ // <http://example.com/Person3> <http://xmlns.com/foaf/0.1/name> "Bob" .
353
+ ```
354
+
355
+ ### Set Methods
356
+ Any methods that on a [JavaScript Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) are available.
357
+
358
+
359
+ ```typescript
360
+ const dataset = await serializedToDataset(`
361
+ @prefix example: <http://example.com/> .
362
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
363
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
364
+
365
+ example:Person1
366
+ foaf:name "Garrett"^^xsd:string, "Bobby"^^xsd:string.
367
+ `);
368
+ const person = jsonldDatasetProxy(
369
+ dataset,
370
+ PersonContext
371
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
372
+ person.name?.add("Ferguson");
373
+ console.log(dataset.toString());
374
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Garrett" .
375
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Bobby" .
376
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Ferguson" .
377
+ ```
378
+
379
+ For convenience, some methods commonly used on arrays have been added. The methods available on Sets are defined as follows:
380
+
381
+ ```typescript
382
+ LdSet<T> {
383
+ add(value: T): this;
384
+ clear(): void;
385
+ delete(value: T): boolean;
386
+ has(value: T): boolean;
387
+ readonly size: number;
388
+ [Symbol.iterator](): IterableIterator<T>;
389
+ entries(): IterableIterator<[T, T]>;
390
+ keys(): IterableIterator<T>;
391
+ values(): IterableIterator<T>;
392
+ every<S extends T>(predicate: (value: T, set: LdSet<T>) => value is S, thisArg?: any): this is LdSet<S>;
393
+ every(predicate: (value: T, set: LdSet<T>) => unknown, thisArg?: any): boolean;
394
+ some(predicate: (value: T, set: LdSet<T>) => unknown, thisArg?: any): boolean;
395
+ forEach(callbackfn: (value: T, value2: T, set: LdSet<T>) => void, thisArg?: any): void;
396
+ map<U>(callbackfn: (value: T, set: LdSet<T>) => U, thisArg?: any): U[];
397
+ filter<S extends T>(predicate: (value: T, set: LdSet<T>) => value is S, thisArg?: any): LdSet<S>;
398
+ filter(predicate: (value: T, set: LdSet<T>) => unknown, thisArg?: any): LdSet<T>;
399
+ reduce(callbackfn: (previousValue: T, currentValue: T, set: LdSet<T>) => T): T;
400
+ reduce(callbackfn: (previousValue: T, currentValue: T, set: LdSet<T>) => T, initialValue: T): T;
401
+ reduce<U>(callbackfn: (previousValue: U, currentValue: T, array: LdSet<T>) => U, initialValue: U): U;
402
+ toArray(): T[];
403
+ toJSON(): T[];
404
+ difference(other: Set<T>): LdSet<T>;
405
+ intersection(other: Set<T>): LdSet<T>;
406
+ isDisjointFrom(other: Set<T>): boolean;
407
+ isSubsetOf(other: Set<T>): boolean;
408
+ isSupersetOf(other: Set<T>): boolean;
409
+ symmetricDifference(other: Set<T>): LdSet<T>;
410
+ union(other: Set<T>): LdSet<T>;
411
+ }
412
+ ```
413
+
414
+ ### Overwriting an Object
415
+ If an object literal is set and the id is equivalent to an existing id, that node will be overwritten. All triples from the previous object are removed and replaced with triples from the new object.
416
+
417
+ ```typescript
418
+ const dataset = await serializedToDataset(`
419
+ @prefix example: <http://example.com/> .
420
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
421
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
422
+
423
+ example:Person2
424
+ foaf:name "Alice"^^xsd:string;
425
+ foaf:age "28"^^xsd:integer.
426
+ `);
427
+ const person = jsonldDatasetProxy(
428
+ dataset,
429
+ PersonContext,
430
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
431
+ person.bestFriend = {
432
+ "@id": "http://example.com/Person2",
433
+ name: set("Jane"),
434
+ };
435
+ console.log(dataset.toString());
436
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/name> "Jane" .
437
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/Person2> .
438
+ ```
439
+
440
+ ### Changing an Object's Id
441
+ You can rename an object by setting its `@id` field. This will update all triples that reference the id to the new id. Setting the `@id` field to `undefined` will turn it into a blank node.
442
+
443
+ ```typescript
444
+ const dataset = await serializedToDataset(`
445
+ @prefix example: <http://example.com/> .
446
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
447
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
448
+
449
+ example:Person1
450
+ foaf:name "Alice"^^xsd:string;
451
+ foaf:bestFriend example:Person2.
452
+
453
+ example:Person2
454
+ foaf:bestFriend example:Person1.
455
+ `);
456
+ const person = jsonldDatasetProxy(
457
+ dataset,
458
+ PersonContext
459
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"))
460
+ person["@id"] = "http://example.com/NewPersonId";
461
+ console.log(dataset.toString());
462
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/NewPersonId> .
463
+ // <http://example.com/NewPersonId> <http://xmlns.com/foaf/0.1/name> "Alice" .
464
+ // <http://example.com/NewPersonId> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/Person2> .
465
+ ```
466
+
467
+ ### Removing an Object Connection
468
+ Removing a connection between nodes can be done by setting a field to `undefined` or using the `delete` operator. Values can be removed from a set by using the `delete` method or the `clear` method to remove all connections.
469
+
470
+ ```typescript
471
+ const dataset = await serializedToDataset(`
472
+ @prefix example: <http://example.com/> .
473
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
474
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
475
+
476
+ example:Person1
477
+ foaf:name "Alice"^^xsd:string;
478
+ foaf:bestFriend example:Person2.
479
+
480
+ example:Person2
481
+ foaf:name "Bob"^^xsd:string;
482
+ foaf:bestFriend example:Person1.
483
+ `);
484
+ const person = jsonldDatasetProxy(
485
+ dataset,
486
+ PersonContext
487
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
488
+ perons.bestFriend.name.delete("Bob");
489
+ person.bestFriend = undefined;
490
+ console.log(dataset.toString());
491
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Alice" .
492
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/bestFriend> <http://example.com/Person1> .
493
+ ```
494
+
495
+ ### Deleting an Entire Object
496
+ If you want to delete all triples represented by an object you can call `delete` on the `@id` property.
497
+
498
+ ```typescript
499
+ const dataset = await serializedToDataset(`
500
+ @prefix example: <http://example.com/> .
501
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
502
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
503
+
504
+ example:Person1
505
+ foaf:name "Alice"^^xsd:string;
506
+ foaf:bestFriend example:Person2.
507
+
508
+ example:Person2
509
+ foaf:name "Bob"^^xsd:string;
510
+ foaf:bestFriend example:Person1.
511
+ `);
512
+ const person = jsonldDatasetProxy(
513
+ dataset,
514
+ PersonContext
515
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
516
+ delete person["@id"];
517
+ console.log(dataset.toString());
518
+ // <http://example.com/Person2> <http://xmlns.com/foaf/0.1/name> "Bob" .
519
+ ```
520
+
521
+ ### Using Blank Nodes
522
+ If you want to create an object with a blankNode subject, simply omit the `@id` field when you're making the object.
523
+ ```typescript
524
+ const dataset = await createDataset();
525
+ const person = jsonldDatasetProxy(
526
+ dataset,
527
+ PersonContext
528
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
529
+ person.bestFriend = {
530
+ name: set("Charlie"),
531
+ };
532
+ console.log(dataset.toString());
533
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/bestFriend> _:b1 .
534
+ // _:b1 <http://xmlns.com/foaf/0.1/name> "Charlie" .
535
+ ```
536
+
537
+ If your dataset has blank nodes and you want to assign that blank node as a triple's object, you can retrieve it from the JSONLD Dataset Proxy and assign it.
538
+ ```typescript
539
+ const dataset = await serializedToDataset(`
540
+ @prefix example: <http://example.com/> .
541
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
542
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
543
+
544
+ example:Person1
545
+ foaf:knows [
546
+ foaf:name "Alice"^^xsd:string;
547
+ ].
548
+ `);
549
+ const person = jsonldDatasetProxy(
550
+ dataset,
551
+ PersonContext,
552
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
553
+
554
+ const alice = person.knows?.toArray()[0];
555
+ person.bestFriend = alice;
556
+ console.log(dataset.toString());
557
+ // _:n3-0 <http://xmlns.com/foaf/0.1/name> "Alice" .
558
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/knows> _:n3-0 .
559
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/bestFriend> _:n3-0 .
560
+ ```
561
+
562
+ ### Writing Information to a Specific Graph
563
+ By default, all new quads are added to the default graph, but you can change the graph to which new quads are added in a few different ways:
564
+
565
+ NOTE: These operations only dictate the graph for new triples. Any operations that delete triples will delete triples regardless of their graph.
566
+
567
+ #### `jsonldDatasetProxy(...).write(...graphs)`
568
+ The write graph can be set upon creating a jsonld dataset proxy by using the `write` method. This method takes in any number of graphs.
569
+
570
+ ```typescript
571
+ const person1 = jsonldDatasetProxy(dataset, PersonContext)
572
+ .write(namedNode("http://example.com/ExampleGraph"))
573
+ .fromSubject<IPerson>(namedNode("http://example.com/Person1"));
574
+ person1.name.add("Jack");
575
+ console.log(dataset.toString());
576
+ // Logs:
577
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Jack" <http://example.com/ExampleGraph> .
578
+ ```
579
+
580
+ #### `write(...graphs).using(...jsonldDatasetProxies)`
581
+ The `write(...).using(...)` function lets you define the graphs you wish to write to using specific jsonldDatasetProxies.
582
+
583
+ ```typescript
584
+ import jsonldDatasetProxy, { write } from "jsonld-dataset-proxy";
585
+
586
+ const person1 = jsonldDatasetProxy(
587
+ dataset,
588
+ PersonContext
589
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
590
+ // Now all additions with person1 will be on ExampleGraph1
591
+ write(namedNode("http://example.com/ExampleGraph1")).using(person1);
592
+ person1.name.add("Jack");
593
+ // Now all additions with person1 will be on ExampleGraph2
594
+ write(namedNode("http://example.com/ExampleGraph2")).using(person1);
595
+ person1.name.add("Spicer");
596
+
597
+ console.log(dataset.toString());
598
+ // Logs:
599
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Jack" <http://example.com/ExampleGraph1> .
600
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Spicer" <http://example.com/ExampleGraph2> .
601
+ ```
602
+
603
+ The function also returns an `end` function that will reset the graph to what it was before. This is useful for nesting graph modifications.
604
+
605
+ ```typescript
606
+ const person1 = jsonldDatasetProxy(
607
+ dataset,
608
+ PersonContext
609
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
610
+ person1.name.add("default");
611
+ const end1 = write(namedNode("http://example.com/Graph1")).using(person1);
612
+ person1.name.add("1");
613
+ const end2 = write(namedNode("http://example.com/Graph2")).using(person1);
614
+ person1.name.add("2");
615
+ const end3 = write(namedNode("http://example.com/Graph3")).using(person1);
616
+ person1.name.add("3");
617
+ end3();
618
+ person1.name.add("2 again");
619
+ end2();
620
+ person1.name.add("1 again");
621
+ end1();
622
+ person1.name.add("default again");
623
+ console.log(dataset.toString());
624
+ // Logs:
625
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "default" .
626
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "default again" .
627
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "1" <http://example.com/Graph1> .
628
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "1 again" <http://example.com/Graph1> .
629
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "2" <http://example.com/Graph2> .
630
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "2 again" <http://example.com/Graph2> .
631
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "3" <http://example.com/Graph3> .
632
+ ```
633
+
634
+ #### `write(...graphs).usingCopy(...jsonldDatasetProxies)`
635
+ If you would like a new variable to write to without modifying the original Jsonld Dataset Proxy, you can use `write(...).usingCopy(...)`.
636
+
637
+ ```typescript
638
+ const person1 = jsonldDatasetProxy(
639
+ dataset,
640
+ PersonContext
641
+ ).fromSubject<IPerson>(namedNode("http://example.com/Person1"));
642
+ const [person1WritingToNewGraph] = write(
643
+ namedNode("http://example.com/NewGraph")
644
+ ).usingCopy(person1);
645
+ person1WritingToNewGraph.name.add("Brandon");
646
+ person1.name.add("Sanderson");
647
+ console.log(dataset.toString());
648
+ // Logs:
649
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Brandon" <http://example.com/NewGraph> .
650
+ // <http://example.com/Person1> <http://xmlns.com/foaf/0.1/name> "Sanderson" .
651
+ ```
652
+
653
+ ### Detecting a the graph of specific information
654
+
655
+ The graph of specific information can be detected using the `graphOf(subject, predicate, object)` function. The `graphOf` function takes in two to three arguments.
656
+
657
+ - `subject`: A Jsonld Dataset Proxy that represents the subject of a quad.
658
+ - `predicate`: A string key
659
+ - `object?`: A representation of the direct object of the triple in question. This could be a jsonld-dataset-proxy or simply and object with an `@id` field.
660
+
661
+ ```typescript
662
+ graphOf(person, "name", "Bob"); // returns defaultGraph()
663
+ graphOf(person, "age"); // returns defaultGraph()
664
+ ```
665
+
666
+ ## Managing Language Tags
667
+
668
+ RDF includes a special attribute for string literals called a [language tag](https://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal). Lanugage tags let developers provide string representations for many different translations and JSON-LD Dataset Proxy helps you manage them.
669
+
670
+ To use language tags, RDF requires the datatype of a literal to be `http://www.w3.org/1999/02/22-rdf-syntax-ns#langString`, and LDO's functions will only work on literals of type that type.
671
+
672
+ For the following examples, we'll use this context and dataset, typescript typing and JSON-LD Context. Notice that there is a field called "label" with translations for French and Korean and one language string that doesn't have a language tag. There's also a field called "description" that holds multiple strings per language.
673
+
674
+ ```typescript
675
+ // Define initial data
676
+ const initialData = `
677
+ @prefix example: <http://example.com/> .
678
+ @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
679
+ @prefix ns: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
680
+
681
+ example:Hospital
682
+ rdfs:label "Hospital"^^ns:langString;
683
+ rdfs:label "Hôpital"@fr;
684
+ rdfs:label "병원"@ko;
685
+ rdfs:description "Heals patients"^^ns:langString;
686
+ rdfs:description "Has doctors"^^ns:langString;
687
+ rdfs:description "Guérit les malades"@fr;
688
+ rdfs:description "A des médecins"@fr;
689
+ rdfs:description "환자를 치료하다"@ko;
690
+ rdfs:description "의사 있음"@ko.
691
+ `;
692
+
693
+ // Typescript Typing
694
+ interface IThing {
695
+ label: string;
696
+ description: string[];
697
+ }
698
+
699
+ // Define JSON-LD Context
700
+ const PersonContext: ContextDefinition = {
701
+ label: {
702
+ "@id": "http://www.w3.org/2000/01/rdf-schema#label",
703
+ "@type": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
704
+ },
705
+ description: {
706
+ "@id": "http://www.w3.org/2000/01/rdf-schema#description",
707
+ "@type": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
708
+ "@container": "@set",
709
+ },
710
+ };
711
+ ```
712
+
713
+ ### Language Preferences
714
+ A language preference is an ordered list telling the JSON-LD Dataset Proxy the language you prefer as well as callbacks.
715
+
716
+ Valid values for the language preferences includes any [IETF Language Tag](https://en.wikipedia.org/wiki/IETF_language_tag) as well as the special tags `@none` and `@other`. `@none` represents any language literal that doesn't have a language tag. `@other` represents any language literal that isn't listed among the language preferences.
717
+
718
+ For read operations, the JSON-LD Dataset Proxy will search for values in order of the preference. Write operations will choose the first language in the language preference, unless that language is `@other`, in which case it will choose the next language.
719
+
720
+ ```typescript
721
+ // Read Spansih first, then Korean, then language strings with no language
722
+ // New writes are in Spanish
723
+ ["es", "ko", "@none"]
724
+
725
+ // Read any language other than french, then french
726
+ // New writes are in French
727
+ ["@other", "fr"]
728
+ ```
729
+
730
+ Language preferences can be set when a JSON-LD Dataset Proxy is created using the `setLanguagePreferences` method.
731
+
732
+ ```typescript
733
+ // Create a dataset loaded with initial data
734
+ const dataset = await serializedToDataset(initialData);
735
+ // Make a JSONLD Dataset Proxy
736
+ const hospitalInfo = jsonldDatasetProxy(dataset, PersonContext)
737
+ .setLanguagePreferences("es", "ko", "@none")
738
+ .fromSubject<IThing>(namedNode("http://example.com/Hospital"));
739
+
740
+ console.log(hospitalInfo.label); // Logs "병원"
741
+ console.log(hospitalInfo.description.size); // Logs "2" for the 2 korean entries
742
+ console.log(hospitalInfo.description.toArray()[0]); // Logs "환자를 치료하다"
743
+ console.log(hospitalInfo.description.toArray()[1]); // Logs "의사 있음"
744
+
745
+ // Adds a string to the description in spanish, because spanish if the first
746
+ // language in the language preference
747
+ hospitalInfo.description.add("Cura a las pacientes");
748
+
749
+ // Now that a spanish entry exists, JSON-LD dataset proxy focuses on that
750
+ console.log(hospitalInfo.description.length); // Logs "1" for the 1 spanish entry
751
+ console.log(hospitalInfo.description.toArray()[0]); // Logs "Cura a las pacientes"
752
+ ```
753
+
754
+ ### `setLanguagePreferences(...languagePreferences).using(...jsonldDatasetProxies)`
755
+ The `setLanguagePreferences(...).using(...)` function sets the language preferences for a set of JSON-LD Dataset Proxies. It follows roughly the same paridigms as the `write(...).using(...)` function.
756
+
757
+ ```typescript
758
+ import { setLanguagePreferences } from "jsonld-dataset-proxy";
759
+
760
+ setLanguagePreferences("fr", "ko").using(hospitalInfo);
761
+ console.log(hospitalInfo.label); // Logs "Hôpital"
762
+ setLanguagePreferences("@none").using(hospitalInfo);
763
+ console.log(hospitalInfo.label); // Logs "Hospital"
764
+ ```
765
+
766
+ ### `setLanguagePreferences(...languagePreferences).usingCopy(...jsonldDatasetProxies)`
767
+ The `setLanguagePreferences(...).usingCopy(...)` function returns a copy of the provided JSON-LD Dataset Proxies with the given language preferences. It follows roughly the same paridigms as the `write(...).usingCopy(...)` function.
768
+
769
+ ```typescript
770
+ import { setLanguagePreferences } from "jsonld-dataset-proxy";
771
+
772
+ // ...
773
+
774
+ const [frenchPreference] = setLanguagePreferences("fr").usingCopy(hospitalInfo);
775
+ const [koreanPreference] = setLanguagePreferences("ko").usingCopy(hospitalInfo);
776
+ console.log(frenchPreference.label); // Logs "Hôpital"
777
+ console.log(koreanPreference.label); // Logs "병원"
778
+ ```
779
+
780
+ ### `languageOf(jsonldDatasetProxy, key)`
781
+ The `languageOf` function lets you view and modify the languages more directly. `languageOf` takes two properties:
782
+
783
+ - `jsonldDatasetProxy`: A JSON-LD dataset proxy
784
+ - `key`: A key on the JSON-LD dataset proxy pointing to a language string.
785
+
786
+ It returns a mapping of languages to strings or sets of strings depending on the cardinality of the JSON-LD context.
787
+
788
+ ```typescript
789
+ const labelLanguages = languagesOf(hospitalInfo, "label");
790
+ // labelLanguages: { '@none': 'Hospital', fr: 'Hôpital', ko: '병원' }
791
+ const descriptionLanguages = languagesOf(hospitalInfo, "description");
792
+ // descriptionLanguages:
793
+ // {
794
+ // '@none': Set(2) { 'Heals patients', 'Has doctors' },
795
+ // fr: Set(2) { 'Guérit les malades', 'A des médecins' },
796
+ // ko: Set(2) { '환자를 치료하다', '의사 있음' }
797
+ // }
798
+ ```
799
+
800
+ You can also modify languauages by changing the mappings. Mappings with sets of strings follow the JavaScript [`Set` interface](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).
801
+
802
+ ```typescript
803
+ // Adds a Chinese label
804
+ labelLanguages.zh = "医院";
805
+ // Changes the no-language label from to "Super Hospital"
806
+ labelLanguages["@none"] = "Super Hospital";
807
+ // Removes the French label
808
+ delete labelLanguages.fr;
809
+ // Adds a Hindi description
810
+ descriptionLanguages.hi?.add("रोगियों को ठीक करता है");
811
+ // Checks to see if the korean label contains "의사 있음"
812
+ descriptionLanguages.ko?.has("의사 있음"); // returns true
813
+ // Removes "Has Doctors" from the no-language description
814
+ descriptionLanguages["@none"]?.delete("Has Doctors");
815
+ ```
816
+
817
+ ## Limitations
818
+ - Currently this library only supports the following features of JSON-LD context:
819
+ - "@id",
820
+ - "@type",
821
+ - "@container": "@set"
822
+
823
+ ## Sponsorship
824
+ This project was made possible by a grant from NGI Zero Entrust via nlnet. Learn more on the [NLnet project page](https://nlnet.nl/project/SolidUsableApps/).
825
+
826
+ [<img src="https://nlnet.nl/logo/banner.png" alt="nlnet foundation logo" width="300" />](https://nlnet.nl/)
827
+ [<img src="https://nlnet.nl/image/logos/NGI0Entrust_tag.svg" alt="NGI Zero Entrust Logo" width="300" />](https://nlnet.nl/)
828
+
829
+ ## Liscense
830
+ MIT