holos-wasm-node 0.16.0 → 0.17.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.
package/README.md CHANGED
@@ -30,18 +30,49 @@ const holos = require('./pkg-node/holos_wasm.js');
30
30
  const store = new holos.Store();
31
31
  store.loadTurtle('<urn:a> <urn:p> "x" .', undefined);
32
32
 
33
- store.query('ASK { ?s ?p ?o }', undefined); // boolean
34
- store.query('SELECT ?s WHERE { ?s ?p ?o }', undefined); // [{ s: '<urn:a>' }]
33
+ store.query('ASK { ?s ?p ?o }', undefined); // true
34
+ store.query('SELECT ?s WHERE { ?s ?p ?o }', undefined); // [{ s: { termType: 'NamedNode',
35
+ // value: 'urn:a' } }]
35
36
  store.query('CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }', undefined);
36
- // ['<urn:a> <urn:p> "x"']
37
+ // ['<urn:a> <urn:p> "x"']
38
+ store.queryRdf('CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }', 'turtle', undefined);
39
+ // '<urn:a> <urn:p> "x" .
40
+ '
41
+ store.update('INSERT DATA { <urn:b> <urn:p> "y" }', undefined);
42
+ // { inserted: 1, deleted: 0, graphsCreated: 0, … }
43
+ store.dump('nquads'); // everything the store holds
37
44
  ```
38
45
 
39
- A CONSTRUCT comes back as N-Triples strings, one per triple, with no trailing separator.
40
- That is the same mapping `holos-python` uses, and N-Triples specifically because it is the
41
- one serialisation every RDF library in JS can parse without first agreeing on a term model.
46
+ | What you get back | From |
47
+ |---|---|
48
+ | `true` / `false` | ASK |
49
+ | terms in rdf-js shape — `{termType, value}`, plus `language` and `datatype` on a literal | SELECT |
50
+ | N-Triples strings, one per triple, no trailing separator | CONSTRUCT, DESCRIBE |
51
+ | a document in the format you asked for | `queryRdf` |
52
+ | `{inserted, deleted, graphsCreated, graphsDropped}` | `update` |
53
+
54
+ **SELECT returns terms, not strings, since 0.17.0.** They used to be N-Triples strings,
55
+ which made every consumer parse term syntax to reach a value, and no RDF library in JS
56
+ accepts a bare term string as input. `{termType, value}` is what rdf-js specifies and what
57
+ oxigraph returns, so a term can go straight to n3 or be compared field by field. A blank
58
+ node's `value` is the bare label, without `_:` — and it is this engine's label, not the one
59
+ in whatever document was loaded, because a parser may rename blank nodes and this one does.
60
+
61
+ CONSTRUCT stays N-Triples strings deliberately: it is the one serialisation every RDF
62
+ library in JS parses without first agreeing on a term model, and a graph is usually wanted
63
+ as a graph. `queryRdf` is there when a *document* is wanted instead — a preview pane showing
64
+ Turtle, or a payload for something that parses RDF but does not speak these shapes.
65
+
42
66
  An unbound variable is left *off* a SELECT row rather than set to `null`: RDF has no null,
43
67
  and "no value here" is a different fact from "the value null".
44
68
 
69
+ `dump` is a document rather than a quad iterator, because crossing the boundary once with a
70
+ document beats crossing it once per quad and every JS RDF library can parse what comes back.
71
+ Use `nquads` or `trig` for a store with named graphs: Turtle and N-Triples have nowhere to
72
+ put a graph name, and the serialiser **refuses** such a quad rather than writing it into the
73
+ default graph. That is the right choice — flattening would move data between graphs while
74
+ reporting success — and the error names the formats that work.
75
+
45
76
  ## What this build cannot do
46
77
 
47
78
  Each of these is a property of the host, not of the engine. None is a stripped-down
package/holos_wasm.d.ts CHANGED
@@ -7,6 +7,20 @@
7
7
  export class Store {
8
8
  free(): void;
9
9
  [Symbol.dispose](): void;
10
+ /**
11
+ * Everything the store holds, serialised in `format`.
12
+ *
13
+ * Use N-Quads or TriG for a store with named graphs. Turtle and N-Triples have nowhere
14
+ * to put a graph name, and the serialiser **refuses** such a quad rather than writing
15
+ * it into the default graph — measured, and the right behaviour: flattening would move
16
+ * data between graphs while reporting success. The error says which formats can carry
17
+ * it. A store with only a default graph serialises to any of the four.
18
+ *
19
+ * This is how a caller enumerates the store: there is no quad iterator on this binding,
20
+ * because crossing the boundary once with a document beats crossing it once per quad,
21
+ * and every JS RDF library can parse what comes back.
22
+ */
23
+ dump(format: string): string;
10
24
  /**
11
25
  * Load Turtle, which is the common case.
12
26
  */
@@ -22,18 +36,44 @@ export class Store {
22
36
  * A new, empty store.
23
37
  */
24
38
  constructor();
39
+ /**
40
+ * Run a CONSTRUCT or DESCRIBE and return the graph serialised in `format`.
41
+ *
42
+ * For when a caller wants a *document* rather than terms: a preview pane showing
43
+ * Turtle, or a payload to hand to something that parses RDF but does not speak this
44
+ * binding's shapes. `query` remains the way to get the triples themselves.
45
+ *
46
+ * A SELECT or ASK is refused rather than serialised, because neither produces a graph
47
+ * and "here is an empty document" would be the wrong way to say so.
48
+ */
49
+ queryRdf(query: string, format: string, base?: string | null): string;
25
50
  /**
26
51
  * Run a SPARQL 1.2 query.
27
52
  *
28
53
  * Returns a boolean for ASK, an array of N-Triples strings for CONSTRUCT and DESCRIBE,
29
- * and an array of objects keyed by variable name for SELECT — the same mapping the
30
- * Python bindings use. N-Triples specifically, because it is the one serialisation
31
- * every RDF library in JS can parse without first agreeing on a term model.
54
+ * and for SELECT an array of objects keyed by variable name whose values are terms in
55
+ * RDF/JS shape — `{termType, value}`, plus `language` and `datatype` on a literal.
56
+ *
57
+ * **Terms rather than strings, since 0.17.0.** They were rendered as N-Triples strings,
58
+ * which made every consumer parse term syntax to get at a value, and no RDF library in
59
+ * JS accepts a bare term string as input. `{termType, value}` is what rdf-js specifies
60
+ * and what oxigraph returns, so a caller can hand these straight to n3 or compare them
61
+ * field by field. `queryRdf` is there for when a *document* is wanted instead.
32
62
  *
33
- * A returned triple carries no trailing separator, which also matches the Python
34
- * bindings; a caller reassembling a document adds one.
63
+ * CONSTRUCT stays N-Triples strings, deliberately: it is one serialisation every RDF
64
+ * library in JS can parse without first agreeing on a term model, and a graph is
65
+ * usually wanted as a graph. A returned triple carries no trailing separator, matching
66
+ * the Python bindings; a caller reassembling a document adds one.
35
67
  */
36
68
  query(query: string, base?: string | null): any;
69
+ /**
70
+ * Apply a SPARQL 1.1 Update, returning what changed:
71
+ * `{inserted, deleted, graphsCreated, graphsDropped}`.
72
+ *
73
+ * **All-or-nothing.** If any operation fails the store is left exactly as it was, so a
74
+ * refused write cannot leave half an update behind.
75
+ */
76
+ update(update: string, base?: string | null): any;
37
77
  /**
38
78
  * Distinct terms in the dictionary.
39
79
  *
package/holos_wasm.js CHANGED
@@ -25,6 +25,41 @@ class Store {
25
25
  const ret = wasm.store_dictionarySize(this.__wbg_ptr);
26
26
  return ret >>> 0;
27
27
  }
28
+ /**
29
+ * Everything the store holds, serialised in `format`.
30
+ *
31
+ * Use N-Quads or TriG for a store with named graphs. Turtle and N-Triples have nowhere
32
+ * to put a graph name, and the serialiser **refuses** such a quad rather than writing
33
+ * it into the default graph — measured, and the right behaviour: flattening would move
34
+ * data between graphs while reporting success. The error says which formats can carry
35
+ * it. A store with only a default graph serialises to any of the four.
36
+ *
37
+ * This is how a caller enumerates the store: there is no quad iterator on this binding,
38
+ * because crossing the boundary once with a document beats crossing it once per quad,
39
+ * and every JS RDF library can parse what comes back.
40
+ * @param {string} format
41
+ * @returns {string}
42
+ */
43
+ dump(format) {
44
+ let deferred3_0;
45
+ let deferred3_1;
46
+ try {
47
+ const ptr0 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
48
+ const len0 = WASM_VECTOR_LEN;
49
+ const ret = wasm.store_dump(this.__wbg_ptr, ptr0, len0);
50
+ var ptr2 = ret[0];
51
+ var len2 = ret[1];
52
+ if (ret[3]) {
53
+ ptr2 = 0; len2 = 0;
54
+ throw takeFromExternrefTable0(ret[2]);
55
+ }
56
+ deferred3_0 = ptr2;
57
+ deferred3_1 = len2;
58
+ return getStringFromWasm0(ptr2, len2);
59
+ } finally {
60
+ wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
61
+ }
62
+ }
28
63
  /**
29
64
  * Load Turtle, which is the common case.
30
65
  * @param {string} text
@@ -74,16 +109,61 @@ class Store {
74
109
  StoreFinalization.register(this, this.__wbg_ptr, this);
75
110
  return this;
76
111
  }
112
+ /**
113
+ * Run a CONSTRUCT or DESCRIBE and return the graph serialised in `format`.
114
+ *
115
+ * For when a caller wants a *document* rather than terms: a preview pane showing
116
+ * Turtle, or a payload to hand to something that parses RDF but does not speak this
117
+ * binding's shapes. `query` remains the way to get the triples themselves.
118
+ *
119
+ * A SELECT or ASK is refused rather than serialised, because neither produces a graph
120
+ * and "here is an empty document" would be the wrong way to say so.
121
+ * @param {string} query
122
+ * @param {string} format
123
+ * @param {string | null} [base]
124
+ * @returns {string}
125
+ */
126
+ queryRdf(query, format, base) {
127
+ let deferred5_0;
128
+ let deferred5_1;
129
+ try {
130
+ const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
131
+ const len0 = WASM_VECTOR_LEN;
132
+ const ptr1 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
133
+ const len1 = WASM_VECTOR_LEN;
134
+ var ptr2 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
135
+ var len2 = WASM_VECTOR_LEN;
136
+ const ret = wasm.store_queryRdf(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
137
+ var ptr4 = ret[0];
138
+ var len4 = ret[1];
139
+ if (ret[3]) {
140
+ ptr4 = 0; len4 = 0;
141
+ throw takeFromExternrefTable0(ret[2]);
142
+ }
143
+ deferred5_0 = ptr4;
144
+ deferred5_1 = len4;
145
+ return getStringFromWasm0(ptr4, len4);
146
+ } finally {
147
+ wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
148
+ }
149
+ }
77
150
  /**
78
151
  * Run a SPARQL 1.2 query.
79
152
  *
80
153
  * Returns a boolean for ASK, an array of N-Triples strings for CONSTRUCT and DESCRIBE,
81
- * and an array of objects keyed by variable name for SELECT — the same mapping the
82
- * Python bindings use. N-Triples specifically, because it is the one serialisation
83
- * every RDF library in JS can parse without first agreeing on a term model.
154
+ * and for SELECT an array of objects keyed by variable name whose values are terms in
155
+ * RDF/JS shape — `{termType, value}`, plus `language` and `datatype` on a literal.
156
+ *
157
+ * **Terms rather than strings, since 0.17.0.** They were rendered as N-Triples strings,
158
+ * which made every consumer parse term syntax to get at a value, and no RDF library in
159
+ * JS accepts a bare term string as input. `{termType, value}` is what rdf-js specifies
160
+ * and what oxigraph returns, so a caller can hand these straight to n3 or compare them
161
+ * field by field. `queryRdf` is there for when a *document* is wanted instead.
84
162
  *
85
- * A returned triple carries no trailing separator, which also matches the Python
86
- * bindings; a caller reassembling a document adds one.
163
+ * CONSTRUCT stays N-Triples strings, deliberately: it is one serialisation every RDF
164
+ * library in JS can parse without first agreeing on a term model, and a graph is
165
+ * usually wanted as a graph. A returned triple carries no trailing separator, matching
166
+ * the Python bindings; a caller reassembling a document adds one.
87
167
  * @param {string} query
88
168
  * @param {string | null} [base]
89
169
  * @returns {any}
@@ -107,6 +187,27 @@ class Store {
107
187
  const ret = wasm.store_size(this.__wbg_ptr);
108
188
  return ret >>> 0;
109
189
  }
190
+ /**
191
+ * Apply a SPARQL 1.1 Update, returning what changed:
192
+ * `{inserted, deleted, graphsCreated, graphsDropped}`.
193
+ *
194
+ * **All-or-nothing.** If any operation fails the store is left exactly as it was, so a
195
+ * refused write cannot leave half an update behind.
196
+ * @param {string} update
197
+ * @param {string | null} [base]
198
+ * @returns {any}
199
+ */
200
+ update(update, base) {
201
+ const ptr0 = passStringToWasm0(update, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
202
+ const len0 = WASM_VECTOR_LEN;
203
+ var ptr1 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
204
+ var len1 = WASM_VECTOR_LEN;
205
+ const ret = wasm.store_update(this.__wbg_ptr, ptr0, len0, ptr1, len1);
206
+ if (ret[2]) {
207
+ throw takeFromExternrefTable0(ret[1]);
208
+ }
209
+ return takeFromExternrefTable0(ret[0]);
210
+ }
110
211
  }
111
212
  if (Symbol.dispose) Store.prototype[Symbol.dispose] = Store.prototype.free;
112
213
  exports.Store = Store;
@@ -173,7 +274,12 @@ function __wbg_get_imports() {
173
274
  getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
174
275
  getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
175
276
  },
176
- __wbindgen_generic_0000000000000001: function(arg0, arg1) {
277
+ __wbindgen_generic_0000000000000001: function(arg0) {
278
+ // Cast intrinsic for `F64 -> Externref`.
279
+ const ret = arg0;
280
+ return ret;
281
+ },
282
+ __wbindgen_generic_0000000000000002: function(arg0, arg1) {
177
283
  // Cast intrinsic for `Ref(String) -> Externref`.
178
284
  const ret = getStringFromWasm0(arg0, arg1);
179
285
  return ret;
Binary file
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "holos-wasm-node",
3
3
  "description": "WebAssembly bindings for the HOLOS RDF 1.2 store and SPARQL 1.2 engine (CommonJS, for Node and require())",
4
- "version": "0.16.0",
4
+ "version": "0.17.0",
5
5
  "license": "MIT OR Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",