holos-wasm 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_bg.js CHANGED
@@ -23,6 +23,41 @@ export class Store {
23
23
  const ret = wasm.store_dictionarySize(this.__wbg_ptr);
24
24
  return ret >>> 0;
25
25
  }
26
+ /**
27
+ * Everything the store holds, serialised in `format`.
28
+ *
29
+ * Use N-Quads or TriG for a store with named graphs. Turtle and N-Triples have nowhere
30
+ * to put a graph name, and the serialiser **refuses** such a quad rather than writing
31
+ * it into the default graph — measured, and the right behaviour: flattening would move
32
+ * data between graphs while reporting success. The error says which formats can carry
33
+ * it. A store with only a default graph serialises to any of the four.
34
+ *
35
+ * This is how a caller enumerates the store: there is no quad iterator on this binding,
36
+ * because crossing the boundary once with a document beats crossing it once per quad,
37
+ * and every JS RDF library can parse what comes back.
38
+ * @param {string} format
39
+ * @returns {string}
40
+ */
41
+ dump(format) {
42
+ let deferred3_0;
43
+ let deferred3_1;
44
+ try {
45
+ const ptr0 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
46
+ const len0 = WASM_VECTOR_LEN;
47
+ const ret = wasm.store_dump(this.__wbg_ptr, ptr0, len0);
48
+ var ptr2 = ret[0];
49
+ var len2 = ret[1];
50
+ if (ret[3]) {
51
+ ptr2 = 0; len2 = 0;
52
+ throw takeFromExternrefTable0(ret[2]);
53
+ }
54
+ deferred3_0 = ptr2;
55
+ deferred3_1 = len2;
56
+ return getStringFromWasm0(ptr2, len2);
57
+ } finally {
58
+ wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
59
+ }
60
+ }
26
61
  /**
27
62
  * Load Turtle, which is the common case.
28
63
  * @param {string} text
@@ -72,16 +107,61 @@ export class Store {
72
107
  StoreFinalization.register(this, this.__wbg_ptr, this);
73
108
  return this;
74
109
  }
110
+ /**
111
+ * Run a CONSTRUCT or DESCRIBE and return the graph serialised in `format`.
112
+ *
113
+ * For when a caller wants a *document* rather than terms: a preview pane showing
114
+ * Turtle, or a payload to hand to something that parses RDF but does not speak this
115
+ * binding's shapes. `query` remains the way to get the triples themselves.
116
+ *
117
+ * A SELECT or ASK is refused rather than serialised, because neither produces a graph
118
+ * and "here is an empty document" would be the wrong way to say so.
119
+ * @param {string} query
120
+ * @param {string} format
121
+ * @param {string | null} [base]
122
+ * @returns {string}
123
+ */
124
+ queryRdf(query, format, base) {
125
+ let deferred5_0;
126
+ let deferred5_1;
127
+ try {
128
+ const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
129
+ const len0 = WASM_VECTOR_LEN;
130
+ const ptr1 = passStringToWasm0(format, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
131
+ const len1 = WASM_VECTOR_LEN;
132
+ var ptr2 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
133
+ var len2 = WASM_VECTOR_LEN;
134
+ const ret = wasm.store_queryRdf(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
135
+ var ptr4 = ret[0];
136
+ var len4 = ret[1];
137
+ if (ret[3]) {
138
+ ptr4 = 0; len4 = 0;
139
+ throw takeFromExternrefTable0(ret[2]);
140
+ }
141
+ deferred5_0 = ptr4;
142
+ deferred5_1 = len4;
143
+ return getStringFromWasm0(ptr4, len4);
144
+ } finally {
145
+ wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
146
+ }
147
+ }
75
148
  /**
76
149
  * Run a SPARQL 1.2 query.
77
150
  *
78
151
  * Returns a boolean for ASK, an array of N-Triples strings for CONSTRUCT and DESCRIBE,
79
- * and an array of objects keyed by variable name for SELECT — the same mapping the
80
- * Python bindings use. N-Triples specifically, because it is the one serialisation
81
- * every RDF library in JS can parse without first agreeing on a term model.
152
+ * and for SELECT an array of objects keyed by variable name whose values are terms in
153
+ * RDF/JS shape — `{termType, value}`, plus `language` and `datatype` on a literal.
82
154
  *
83
- * A returned triple carries no trailing separator, which also matches the Python
84
- * bindings; a caller reassembling a document adds one.
155
+ * **Terms rather than strings, since 0.17.0.** They were rendered as N-Triples strings,
156
+ * which made every consumer parse term syntax to get at a value, and no RDF library in
157
+ * JS accepts a bare term string as input. `{termType, value}` is what rdf-js specifies
158
+ * and what oxigraph returns, so a caller can hand these straight to n3 or compare them
159
+ * field by field. `queryRdf` is there for when a *document* is wanted instead.
160
+ *
161
+ * CONSTRUCT stays N-Triples strings, deliberately: it is one serialisation every RDF
162
+ * library in JS can parse without first agreeing on a term model, and a graph is
163
+ * usually wanted as a graph. A returned triple carries no trailing separator, matching
164
+ * the Python bindings; a caller reassembling a document adds one.
85
165
  * @param {string} query
86
166
  * @param {string | null} [base]
87
167
  * @returns {any}
@@ -105,6 +185,27 @@ export class Store {
105
185
  const ret = wasm.store_size(this.__wbg_ptr);
106
186
  return ret >>> 0;
107
187
  }
188
+ /**
189
+ * Apply a SPARQL 1.1 Update, returning what changed:
190
+ * `{inserted, deleted, graphsCreated, graphsDropped}`.
191
+ *
192
+ * **All-or-nothing.** If any operation fails the store is left exactly as it was, so a
193
+ * refused write cannot leave half an update behind.
194
+ * @param {string} update
195
+ * @param {string | null} [base]
196
+ * @returns {any}
197
+ */
198
+ update(update, base) {
199
+ const ptr0 = passStringToWasm0(update, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
200
+ const len0 = WASM_VECTOR_LEN;
201
+ var ptr1 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
202
+ var len1 = WASM_VECTOR_LEN;
203
+ const ret = wasm.store_update(this.__wbg_ptr, ptr0, len0, ptr1, len1);
204
+ if (ret[2]) {
205
+ throw takeFromExternrefTable0(ret[1]);
206
+ }
207
+ return takeFromExternrefTable0(ret[0]);
208
+ }
108
209
  }
109
210
  if (Symbol.dispose) Store.prototype[Symbol.dispose] = Store.prototype.free;
110
211
 
@@ -166,7 +267,12 @@ export function __wbg_stack_3b0d974bbf31e44f(arg0, arg1) {
166
267
  getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
167
268
  getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
168
269
  }
169
- export function __wbindgen_generic_0000000000000001(arg0, arg1) {
270
+ export function __wbindgen_generic_0000000000000001(arg0) {
271
+ // Cast intrinsic for `F64 -> Externref`.
272
+ const ret = arg0;
273
+ return ret;
274
+ }
275
+ export function __wbindgen_generic_0000000000000002(arg0, arg1) {
170
276
  // Cast intrinsic for `Ref(String) -> Externref`.
171
277
  const ret = getStringFromWasm0(arg0, arg1);
172
278
  return ret;
Binary file
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "holos-wasm",
3
3
  "type": "module",
4
4
  "description": "WebAssembly bindings for the HOLOS RDF 1.2 store and SPARQL 1.2 engine (ESM, for bundlers)",
5
- "version": "0.16.0",
5
+ "version": "0.17.0",
6
6
  "license": "MIT OR Apache-2.0",
7
7
  "repository": {
8
8
  "type": "git",