mdld-parse 0.9.9 → 1.0.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 (55) hide show
  1. package/README.md +242 -330
  2. package/dist/index.js +1793 -1336
  3. package/package.json +4 -4
  4. package/dist/.nojekyll +0 -0
  5. package/dist/CNAME +0 -1
  6. package/dist/README.md +0 -500
  7. package/dist/docs/API.md +0 -435
  8. package/dist/docs/Architecture.md +0 -190
  9. package/dist/docs/Guide.md +0 -816
  10. package/dist/docs/LLM-MDLD-Inducer.md +0 -550
  11. package/dist/docs/LiterateRDF.md +0 -472
  12. package/dist/docs/Parser.md +0 -720
  13. package/dist/docs/Performance.md +0 -238
  14. package/dist/docs/Spec-render.md +0 -1439
  15. package/dist/docs/Subject.md +0 -180
  16. package/dist/docs/Syntax.md +0 -463
  17. package/dist/docs/TodoList.md +0 -215
  18. package/dist/docs/Use-Cases.md +0 -354
  19. package/dist/docs/guide-m.md +0 -56
  20. package/dist/docs/index.html +0 -108
  21. package/dist/docs/index.md +0 -56
  22. package/dist/docs/one-page.md +0 -322
  23. package/dist/docs/origin.md +0 -460
  24. package/dist/docs/polarity.md +0 -586
  25. package/dist/docs/primary-subject.md +0 -326
  26. package/dist/docs/statements.md +0 -226
  27. package/dist/docs/tokenization-performance-report.md +0 -164
  28. package/dist/examples/Cookbook.md +0 -32
  29. package/dist/examples/Status-SHACL.md +0 -31
  30. package/dist/examples/demo/index.md +0 -35
  31. package/dist/examples/demo/journal.md +0 -58
  32. package/dist/examples/demo/minimal.md +0 -23
  33. package/dist/examples/demo/project.md +0 -84
  34. package/dist/examples/demo/prov.md +0 -107
  35. package/dist/examples/demo/rdf.md +0 -69
  36. package/dist/examples/demo/recipe.md +0 -50
  37. package/dist/examples/demo/research.md +0 -84
  38. package/dist/examples/demo/shacl.md +0 -161
  39. package/dist/examples/demo/space-mission.md +0 -58
  40. package/dist/examples/demo/tasks.md +0 -175
  41. package/dist/examples/demo/xsd.md +0 -91
  42. package/dist/examples/dogfood.md +0 -288
  43. package/dist/examples/few-shot.md +0 -309
  44. package/dist/examples/graph/rdf-graph.html +0 -473
  45. package/dist/examples/graph/rdf_force_graph_web_component.html +0 -506
  46. package/dist/examples/index.md +0 -45
  47. package/dist/examples/llm-time-workflow.md +0 -173
  48. package/dist/examples/statements.md +0 -43
  49. package/dist/examples/workflow.md +0 -150
  50. package/dist/index.html +0 -3049
  51. package/dist/logo.svg +0 -7
  52. package/dist/spec/Spec-compact.md +0 -368
  53. package/dist/spec/Spec-ultra.md +0 -232
  54. package/dist/spec/Spec.md +0 -1116
  55. package/dist/spec/index.md +0 -46
package/package.json CHANGED
@@ -1,20 +1,20 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "0.9.9",
3
+ "version": "1.0.0",
4
4
  "description": "A standards-compliant parser for **MD-LD (Markdown-Linked Data)** — a human-friendly RDF authoring format that extends Markdown with semantic annotations.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@10.33.4+sha512.1c67b3b359b2d408119ba1ed289f34b8fc3c6873412bec6fd264fbdc82489e510fcbecb9ce9d22dae7f3b76269d8441046014bdca53b9979cd7a561ad631b800",
7
- "main": "index.js",
7
+ "main": "./dist/index.js",
8
8
  "exports": {
9
9
  ".": "./dist/index.js"
10
10
  },
11
11
  "files": [
12
- "dist"
12
+ "dist/index.js"
13
13
  ],
14
14
  "scripts": {
15
15
  "test": "node tests/index.js",
16
16
  "dev": "vite dev",
17
- "build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
17
+ "build": "vite build && vite build --config vite.config.lib.js && cp -r docs/ dist/docs/ && cp -r examples/ dist/examples/ && cp -r grammar/ dist/grammar/ && cp -r ontologies/ dist/ontologies/ && cp -r spec/ dist/spec/ && cp -r README.md dist/README.md"
18
18
  },
19
19
  "keywords": [
20
20
  "mdld",
package/dist/.nojekyll DELETED
File without changes
package/dist/CNAME DELETED
@@ -1 +0,0 @@
1
- mdld.js.org
package/dist/README.md DELETED
@@ -1,500 +0,0 @@
1
- # MD-LD
2
-
3
- **Markdown-Linked Data (MD-LD)** — a deterministic, streaming-friendly RDF authoring format that extends Markdown with explicit `{...}` annotations.
4
-
5
- [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
6
-
7
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
8
-
9
- ## 🚀 Quick Start
10
-
11
- ```bash
12
- pnpm install mdld-parse
13
- ```
14
-
15
- ```javascript
16
- import { parse } from 'mdld-parse';
17
-
18
- const result = parse(`
19
- [ex] <http://example.org/>
20
-
21
- # Document {=ex:doc .ex:Article label}
22
-
23
- [Alice] {?ex:author =ex:alice .prov:Person ex:firstName label}
24
- [Smith] {ex:lastName}`);
25
-
26
- console.log(result.quads);
27
- // RDF/JS quads ready for n3.js, rdflib, etc.
28
- // @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
29
- // @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
30
- // @prefix prov: <http://www.w3.org/ns/prov#>.
31
- // @prefix ex: <http://example.org/>.
32
-
33
- // ex:doc a ex:Article;
34
- // rdfs:label "Document";
35
- // ex:author ex:alice.
36
- // ex:alice a prov:Person;
37
- // rdfs:label "Alice";
38
- // ex:firstName "Alice";
39
- // ex:lastName "Smith".
40
- ```
41
-
42
- ## 📚 Documentation Hub
43
-
44
- - **📖 [Documentation](./docs/index.md)** - Complete documentation with guides and references
45
- - **🎯 [Examples](./examples/index.md)** - Real-world MD-LD examples and use cases
46
- - **📋 [Specification](./spec/index.md)** - Formal specification and test suite
47
-
48
- ## ✨ Core Features
49
-
50
- - **🔗 Prefix folding** - Build hierarchical namespaces with lightweight IRI authoring
51
- - **📍 Subject declarations** - `{=IRI}` and `{=#fragment}` for context setting
52
- - **🎯 Object IRIs** - `{+IRI}` and `{+#fragment}` for temporary object declarations
53
- - **🔄 Three predicate forms** - `p` (S→L), `?p` (S→O), `!p` (O→S)
54
- - **🏷️ Type declarations** - `.Class` for rdf:type triples
55
- - **📅 Datatypes & language** - `^^xsd:date` and `@en` support
56
- - **🧩 Fragments** - Document structuring with `{=#fragment}`
57
- - **⚡ Polarity system** - Sophisticated diff authoring with `+` and `-` prefixes
58
- - **📍 Origin tracking** - Complete provenance with lean quad-to-source mapping
59
- - **🎯 Elevated statements** - Automatic rdf:Statement pattern detection for "golden" graph extraction
60
- - **🏷️ Primary metadata** - Structured primary object with subject, type, and label for document identity
61
-
62
- ## 🌟 What is MD-LD?
63
-
64
- MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
65
-
66
- ```markdown
67
- [my] <tag:alice@example.com,2026:>
68
- # 2024-07-18 {=my:journal-2024-07-18 .my:Event my:date ^^xsd:date}
69
- ## A good day {label}
70
- Mood: [Happy] {my:mood}
71
- Energy level: [8] {my:energyLevel ^^xsd:integer}
72
- Met [Sam] {+my:sam .my:Person ?my:attendee} on my regular walk at [Central Park] {+my:central-park ?my:location .my:Place label @en} and talked about [Sunny] {my:weather} weather.
73
- ```
74
-
75
- Generates valid RDF triples with complete provenance tracking.
76
-
77
- ## 📦 Installation
78
-
79
- ### Node.js
80
-
81
- ```bash
82
- pnpm install mdld-parse
83
- ```
84
-
85
- ```javascript
86
- import { parse } from 'mdld-parse';
87
-
88
- const markdown = `[ex] <tag:alice@example.org,2026:>
89
-
90
- # Demo document {=ex:example/doc .prov:Entity label}
91
-
92
- > A demo document for MD-LD {comment}
93
- [Alice] {+ex:alice ?ex:author .prov:Person label}
94
- `;
95
-
96
- const result = parse({ text: markdown });
97
-
98
- console.log(result.quads);
99
- // RDF/JS quads ready for n3.js, rdflib, etc.
100
- ```
101
-
102
- ### Browser (ES Modules)
103
-
104
- ```html
105
- <script type="module">
106
- import { parse } from 'https://cdn.jsdelivr.net/npm/mdld-parse/+esm';
107
-
108
- const result = parse('[ex] <tag:alice@example.org,2026:>\n\n# Hello {=ex:hello label}');
109
- </script>
110
- ```
111
-
112
- ## 🧠 Semantic Model
113
-
114
- MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
115
-
116
- - **S** — current subject (IRI)
117
- - **O** — object resource (IRI from link/image)
118
- - **L** — literal value (string + optional datatype/language)
119
-
120
- ### Predicate Routing (§8.1)
121
-
122
- Each predicate form determines the graph edge:
123
-
124
- | Form | Edge | Example | Meaning |
125
- |-------|---------|------------------------------|------------------|
126
- | `p` | S → L | `[Alice] {label}` | literal property |
127
- | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
128
- | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
129
-
130
- ## 📍 Elevated Statements
131
-
132
- MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
133
-
134
- ### Pattern Detection
135
-
136
- When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, it automatically adds the corresponding SPO quad to the `statements` array:
137
-
138
- ```markdown
139
- [ex] <http://example.org/>
140
-
141
- ## Elevated statement {=ex:stmt1 .rdf:Statement}
142
- **Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
143
-
144
- Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
145
- ```
146
-
147
- ## 🎨 Syntax Quick Reference
148
-
149
- ### Subject Declaration
150
- Set current subject (emits no quads):
151
- ```markdown
152
- ## Apollo 11 {=ex:apollo11}
153
- ```
154
-
155
- ### Fragment Syntax
156
- Create fragment IRIs relative to current subject:
157
- ```markdown
158
- # Document {=ex:document}
159
- {=#summary}
160
- [Content] {label}
161
- ```
162
- Fragments replace any existing fragment and require a current subject.
163
-
164
- ### Type Declaration
165
- Emit `rdf:type` triple:
166
- ```markdown
167
- ## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
168
- ```
169
-
170
- ### Literal Properties
171
- Inline value carriers emit literal properties:
172
- ```markdown
173
- # Mission {=ex:apollo11}
174
- [Neil Armstrong] {ex:commander}
175
- [1969] {ex:year ^^xsd:gYear}
176
- [Historic mission] {ex:description @en}
177
- ```
178
-
179
- ### Object Properties
180
- Links create relationships (use `?` prefix):
181
- ```markdown
182
- # Mission {=ex:apollo11}
183
- [NASA] {=ex:nasa ?ex:organizer}
184
- ```
185
-
186
- ### Resource Declaration
187
- Declare resources inline with `{=iri}`:
188
- ```markdown
189
- # Mission {=ex:apollo11}
190
- [Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
191
- ```
192
-
193
- ## 🔧 API Reference
194
-
195
- ### `parse({ text, context, dataFactory, graph })`
196
-
197
- Parse MD-LD markdown and return RDF quads with lean origin tracking.
198
-
199
- **Parameters (named object):**
200
- - `text` (string, required) — MD-LD formatted text
201
- - `context` (object, optional) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
202
- - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
203
- - `graph` (string, optional) — Named graph IRI
204
-
205
- **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
206
-
207
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
208
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
209
- - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
210
- - `origin` — Lean origin tracking object with quadIndex for UI navigation
211
- - `context` — Final context used (includes prefixes)
212
- - `primarySubject` — String IRI or null (canonical append identity)
213
- - `primary` — Object containing primary metadata (semantic surface descriptor)
214
- - `md` — Clean Markdown with all MD-LD annotations stripped (round-trip safe)
215
-
216
- **Dual-Layer Architecture:**
217
-
218
- | Layer | Field | Purpose | Use Cases |
219
- |-------|-------|---------|-----------|
220
- | **Canonical Identity** | `primarySubject` | Append routing, storage, synchronization | `append()`, file placement, authority validation |
221
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Dashboards, search, previews, timelines |
222
-
223
- **Primary Object Structure:**
224
- ```javascript
225
- primary: {
226
- subject: string | null, // First non-fragment subject declaration
227
- type: string | null, // First rdf:type declaration
228
- label: string | null // First rdfs:label literal
229
- }
230
- ```
231
-
232
- ### `merge(docs, options)`
233
-
234
- Merge multiple MDLD documents with diff polarity resolution.
235
-
236
- **Parameters:**
237
- - `docs` (array) — Array of markdown strings or ParseResult objects
238
- - `options` (object, optional):
239
- - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
240
-
241
- **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
242
-
243
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
244
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
245
- - `origin` — Merge origin with document tracking
246
- - `context` — Final context used (includes prefixes)
247
- - `primarySubjects` — Array of string IRIs (canonical append identities, ordered by merge)
248
- - `primary` — Array of primary objects (semantic surface descriptors, ordered by merge)
249
-
250
- **Dual-Layer Architecture:**
251
-
252
- | Layer | Field | Purpose | Use Cases |
253
- |-------|-------|---------|-----------|
254
- | **Canonical Identity** | `primarySubjects` | Append routing, storage, synchronization | Multi-document append, file organization |
255
- | **Semantic Surface** | `primary` | UI, indexing, navigation, agent orientation | Vault indexing, document discovery, search |
256
-
257
- **Primary Object Array Structure:**
258
- ```javascript
259
- primary: [
260
- {
261
- subject: string | null, // First non-fragment subject declaration
262
- type: string | null, // First rdf:type declaration
263
- label: string | null // First rdfs:label literal
264
- },
265
- // ... one object per document
266
- ]
267
- ```
268
-
269
-
270
- ### `generate({ quads, context, primarySubject })`
271
-
272
- Generate deterministic MDLD from RDF quads with visual styling.
273
-
274
- **Parameters (named object):**
275
- - `quads` (array, required) — Array of RDF/JS Quads to convert
276
- - `context` (object, optional) — Prefix mappings (default: `{}`)
277
- - `primarySubject` (string, optional) — String IRI to place first in output (ensures round-trip safety). If not provided, falls back to the first subject from quads.
278
-
279
- **Returns:** `{ text, context }`
280
-
281
- **Features:**
282
- - Visual carrier styles based on datatype (code spans for numbers, bold booleans, etc.)
283
- - Label-in-heading: Uses `rdfs:label` in subject headings when available
284
- - Multiple labels: First label in heading, additional labels rendered as literals
285
- - Round-trip safe: All data preserved through parse → generate → parse
286
- - Composable: `generate(parse(text))` extracts semantics; `parse(generate({quads}))` normalizes quads
287
-
288
- ### `generateNode({ quads, focusIRI, context })`
289
-
290
- Generate node-centric MDLD showing all quads where a specific IRI appears in any position.
291
-
292
- **Parameters (named object):**
293
- - `quads` (array, required) — Array of RDF/JS Quads to search
294
- - `focusIRI` (string, required) — The IRI to center the view on
295
- - `context` (object, optional) — Prefix mappings (default: `{}`)
296
-
297
- **Returns:** `{ text, context }`
298
-
299
- **Behavior (Safety-First):**
300
- - If `focusIRI` is null/undefined: Returns empty text
301
- - If `focusIRI` not in graph: Returns empty text (never falls back to all data)
302
- - If `quads` is empty: Returns empty text
303
-
304
- **Safety rationale:** Prevents accidental rendering of entire databases on misspelled IRIs—critical for production use with LLM cost per token. Explicit emptiness signals "not found" to the caller.
305
-
306
- **Use case:** Perfect for exploring a specific node and all its relationships—where it appears as subject, object, predicate, type, or datatype. Creates an exhaustive view of everything related to the focus IRI. Ideal for node-centric knowledge graph explorers.
307
-
308
- ### `updateValue()` — Update Quad Carrier Text in Source Text
309
-
310
- Update the carrier text of a literal quad in MDLD text. Only the carrier content is replaced — datatype (`^^xsd:integer`) and language (`@en`) annotations inside the `{…}` block are preserved as-is, since they are part of the annotation, not the carrier.
311
-
312
- ```javascript
313
- import { parse, updateValue } from 'mdld-parse';
314
-
315
- const mdld = `[ex] <http://example.org/>
316
-
317
- # Article {=ex:article .ex:Article}
318
-
319
- [Alice Smith] {ex:author}`;
320
-
321
- const result = parse({ text: mdld });
322
- const authorQuad = result.quads.find(q =>
323
- q.subject.value === 'http://example.org/article' &&
324
- q.predicate.value === 'http://example.org/author'
325
- );
326
-
327
- const updatedText = updateValue({
328
- text: mdld,
329
- quad: authorQuad,
330
- value: 'Bob Johnson',
331
- origin: result.origin // optional (auto-parses if not provided)
332
- });
333
-
334
- console.log(updatedText);
335
- // [ex] <http://example.org/>
336
- //
337
- // # Article {=ex:article .ex:Article}
338
- //
339
- // [Bob Johnson] {ex:author}
340
- ```
341
-
342
- **Annotation annotations are preserved:**
343
- ```javascript
344
- // Original: > 25 {ex:age ^^xsd:integer}
345
- updateValue({ text, quad, value: '30' });
346
- // Result: > 30 {ex:age ^^xsd:integer} ← datatype preserved
347
-
348
- // Original: > Hello {ex:greeting @en}
349
- updateValue({ text, quad, value: 'Good morning' });
350
- // Result: > Good morning {ex:greeting @en} ← language tag preserved
351
- ```
352
-
353
- **Parameters:**
354
- - `text` (string) — The original MDLD text
355
- - `quad` (object) — The quad to update (subject, predicate, object)
356
- - `value` (string) — The new carrier text to set
357
- - `origin` (object, optional) — ParseResult.origin (auto-parses if not provided)
358
-
359
- **Returns:** Updated MDLD text, or original text if update fails (fail-safe)
360
-
361
- **How it works:**
362
- - Uses `locate()` to find the quad's position in the source text
363
- - Uses `valueRange` to replace only the carrier text (excluding carrier markers like `[`, `]`)
364
- - Annotation block `{…}` with predicate, datatype, language is untouched
365
- - Auto-parses if result not provided (convenient but less efficient)
366
-
367
- **Fail-safe behavior:**
368
- - Returns original text if quad cannot be located
369
- - Returns original text if valueRange is not available
370
- - Never corrupts the source text
371
-
372
- **Use case:** Perfect for editor applications that need to update literal values while preserving carrier syntax, datatype annotations, and language tags.
373
-
374
- ### Composition Patterns
375
-
376
- With the unified named parameter API, `parse()` and `generate()` compose seamlessly through object spreading:
377
-
378
- ```javascript
379
- import { parse, generate, generateNode } from 'mdld-parse';
380
-
381
- // Pattern 1: parse → generate (semantic extraction)
382
- const canonical = generate({ ...parse({ text, context }) });
383
- // text → quads → canonical MDLD (deterministic, visual styling applied)
384
-
385
- // Pattern 2: generate → parse (normalize external RDF)
386
- const normalized = parse({ ...generate({ quads: externalQuads, context }) });
387
- // external quads → MDLD → validated quads (DataFactory-safe, no blank nodes)
388
-
389
- // Pattern 3: parse → generateNode (node-centric exploration)
390
- const nodeView = generateNode({ ...parse({ text }), focusIRI: 'http://example.org/alice' });
391
- // full graph → isolated node view (safe: returns empty if IRI not found)
392
- ```
393
-
394
- **Why this works:**
395
- - `parse()` returns `{ quads, context, primarySubject, md, ... }`
396
- - `generate()` accepts `{ quads, context, primarySubject }`
397
- - `generateNode()` accepts `{ quads, context, focusIRI }` (with focusIRI override)
398
- - Perfect shape alignment enables elegant `{ ...spread }` composition
399
-
400
- ### The `md` Field — Clean Markdown Extraction
401
-
402
- Every `parse()` result includes a `md` field containing the original Markdown with all MD-LD annotations stripped:
403
-
404
- ```javascript
405
- const result = parse({
406
- text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
407
- context: { ex: 'http://example.org/' }
408
- });
409
-
410
- console.log(result.md);
411
- // # Document\nContent
412
-
413
- // Round-trip safety: re-parsing clean MD produces zero quads
414
- const reparsed = parse({ text: result.md });
415
- console.log(reparsed.quads.length); // 0
416
- ```
417
-
418
- **Behavior:**
419
- - Valid MD-LD annotations (`{=...}`, `{+...}`, `{...}`) are completely removed
420
- - Content from value carriers (`[text]`, `**bold**`, `` `code` ``) is preserved
421
- - Invalid syntax (annotations not at end-of-line) is preserved as visible markers
422
- - Headings, lists, blockquotes, code blocks maintain their structure
423
- - Prefix declarations at start of line are stripped
424
- - Standalone subject declarations (`{=ex:subject}`) are stripped
425
-
426
- **Use cases:**
427
- - **Content extraction** — Get readable Markdown without semantic markup
428
- - **Syntax validation** — Remaining `{...}` patterns indicate invalid MD-LD syntax
429
- - **Round-trip testing** — `parse(md).md` should parse to zero quads
430
- - **Preview generation** — Show clean document before publishing
431
-
432
- ### `locate(quad, origin)`
433
-
434
- Locate the origin entry for a quad using the lean origin system.
435
-
436
- **Parameters:**
437
- - `quad` (object) — The quad to locate (subject, predicate, object)
438
- - `origin` (object) — Origin object containing quadIndex
439
-
440
- **Returns:** `{ blockId, range, valueRange, carrierType, subject, predicate, context, value, polarity }` or `null`
441
-
442
- - `range`: Full character range including carrier markers (e.g., `[`, `]`, `{`, `}`)
443
- - `valueRange`: Character range excluding carrier markers (null if not available)
444
-
445
- ### `render(quads, options)`
446
-
447
- Render RDF quads as HTML+RDFa for web display.
448
-
449
- **Parameters:**
450
- - `quads` (array) — Array of RDF/JS Quads to render
451
- - `options` (object, optional):
452
- - `context` (object) — Prefix mappings for CURIE shortening
453
- - `baseIRI` (string) — Base IRI for resolving relative references
454
-
455
- **Returns:** `{ html, context }`
456
-
457
- ### Utility Functions
458
-
459
- ```javascript
460
- import {
461
- DEFAULT_CONTEXT, // Default prefix mappings
462
- DataFactory, // RDF/JS DataFactory instance
463
- hash, // String hashing function
464
- expandIRI, // IRI expansion with context
465
- shortenIRI, // IRI shortening with context
466
- parseSemanticBlock // Parse semantic block syntax
467
- } from 'mdld-parse';
468
- ```
469
-
470
- ## 🏗️ Architecture
471
-
472
- ### Design Principles
473
- - **Zero dependencies** — Pure JavaScript, ~15KB minified
474
- - **Streaming-first** — Single-pass parsing, O(n) complexity
475
- - **Standards-compliant** — RDF/JS data model
476
- - **Origin tracking** — Full round-trip support with source maps
477
- - **Explicit semantics** — No guessing, inference, or heuristics
478
-
479
- ### RDF/JS Compatibility
480
- Quads are compatible with:
481
- - [`n3.js`](https://github.com/rdfjs/N3.js) — Turtle/N-Triples serialization
482
- - [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF store and reasoning
483
- - [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
484
- - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — Extended RDF utilities
485
-
486
- ## 🧪 Testing
487
-
488
- The parser includes comprehensive tests covering all spec requirements:
489
-
490
- ```bash
491
- pnpm test
492
- ```
493
-
494
- Tests validate:
495
- - Subject declaration and context
496
- - All predicate forms (p, ?p, !p)
497
- - Datatypes and language tags
498
- - Explicit list item annotations
499
- - Code blocks and blockquotes
500
- - Round-trip serialization