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/README.md CHANGED
@@ -1,10 +1,39 @@
1
1
  # MD-LD
2
2
 
3
- **Markdown-Linked Data (MD-LD)** — a deterministic, streaming-friendly RDF authoring format that extends Markdown with explicit `{...}` annotations.
3
+ **Markdown-Linked Data** — Human-friendly knowledge graph authoring.
4
+
5
+ Write semantic data in natural Markdown, parse to RDF quads, build deterministic state machines.
4
6
 
5
7
  [![NPM](https://img.shields.io/npm/v/mdld-parse)](https://www.npmjs.com/package/mdld-parse)
6
8
 
7
- [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
9
+ [Demo](https://mdld.js.org) | [Repository](https://github.com/davay42/mdld-parse)
10
+
11
+ ## 🎯 What is MD-LD?
12
+
13
+ MD-LD is not just another RDF syntax. It's a **universal semantic writing interface** that removes the intermediary between human text and machine-readable graphs.
14
+
15
+ Traditional systems require:
16
+ ```
17
+ Human → UI → App Logic → Hidden Database → APIs → Exports
18
+ ```
19
+
20
+ MD-LD enables:
21
+ ```
22
+ Human text → Graph immediately
23
+ ```
24
+
25
+ **Core value:** Author and maintain knowledge graphs as plain text with deterministic round-trip safety. No platforms, databases, or proprietary SaaS mediation required.
26
+
27
+ ```markdown
28
+ [ex] <http://example.org/>
29
+
30
+ # Document {=ex:doc .Article label}
31
+
32
+ [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
33
+ [Smith] {ex:lastName}
34
+ ```
35
+
36
+ **Generates RDF quads** that work with n3.js, rdflib, and any RDF/JS-compatible library.
8
37
 
9
38
  ## 🚀 Quick Start
10
39
 
@@ -13,66 +42,106 @@ pnpm install mdld-parse
13
42
  ```
14
43
 
15
44
  ```javascript
16
- import { parse } from 'mdld-parse';
45
+ import { parse, generate, merge } from 'mdld-parse';
17
46
 
18
- const result = parse(`
19
- [ex] <http://example.org/>
47
+ // Parse MDLD to RDF quads
48
+ const result = parse({ text: mdldString });
49
+ console.log(result.quads); // RDF/JS quads
50
+ console.log(result.primary); // Primary metadata (subject, type, label, comment)
51
+ console.log(result.statements); // Elevated statements
52
+ console.log(result.origin); // Provenance tracking
20
53
 
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".
54
+ // Generate MDLD from quads
55
+ const { text } = generate({ quads: result.quads });
56
+
57
+ // Merge multiple documents (CRDT-style)
58
+ const merged = merge([doc1, doc2, doc3]);
40
59
  ```
41
60
 
42
- ## 📚 Documentation Hub
61
+ ## 💡 Why MD-LD?
43
62
 
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
63
+ ### The Problem with Current Systems
47
64
 
48
- ## ✨ Core Features
65
+ Most software today uses graphs internally but hides them behind UIs:
66
+ - **Notion, Slack, Google Docs** — Human interfaces over hidden graphs
67
+ - **CRMs, task apps, note apps** — Proprietary data silos
68
+ - **Social networks** — Platform-controlled knowledge prisons
69
+
70
+ Users cannot access the graph directly. Semantics are hidden. Data is locked in products.
49
71
 
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
72
+ ### The MD-LD Solution
61
73
 
62
- ## 🌟 What is MD-LD?
74
+ MD-LD removes the intermediary. Writing becomes publishing. Publishing becomes graph construction.
63
75
 
64
- MD-LD allows you to author RDF graphs directly in Markdown using explicit `{...}` annotations:
76
+ **Key benefits:**
77
+ - **Graph sovereignty** — You own text, graph, provenance, execution, history
78
+ - **No central platform required** — Works offline, in browsers, on servers
79
+ - **Universal semantic substrate** — Agents can read, reason, write, execute, validate
80
+ - **Continuous semantic narrative** — Unifies chat, tasks, notes, emails, calendar, files
81
+ - **Native time dimension** — Every action, statement, correction becomes part of the graph
82
+ - **Decentralized authority** — RFC 4151 tag: URIs enable self-sovereign identity without central registries
65
83
 
84
+ ### Real-World Applications
85
+
86
+ #### Personal Knowledge Management
66
87
  ```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.
88
+ [alice] <tag:alice@example.com,2026:>
89
+
90
+ # Meeting Notes {=alice:meeting-2024-01-15 .alice:Meeting}
91
+
92
+ Attendees:
93
+ - **Alice** {+alice:alice ?alice:attendee label}
94
+ - **Bob** {+alice:bob ?alice:attendee label}
95
+
96
+ Action items:
97
+ - **Review proposal** {+alice:task-1 ?alice:actionItem label}
73
98
  ```
74
99
 
75
- Generates valid RDF triples with complete provenance tracking.
100
+ #### Developer Documentation
101
+ ```markdown
102
+ # API Endpoint {=api:/users/:id .api:Endpoint}
103
+
104
+ [GET] {api:method}
105
+ [/users/:id] {api:path}
106
+ ```
107
+
108
+ #### Academic Research
109
+ ```markdown
110
+ # Paper {=alice:paper-semantic-markdown .alice:ScholarlyArticle}
111
+
112
+ [Semantic Web] {label}
113
+ [Alice Johnson] {=alice:alice-johnson ?alice:author}
114
+ [2024-01] {alice:datePublished ^^xsd:gYear}
115
+ ```
116
+
117
+ #### Content Management
118
+ ```markdown
119
+ # Understanding MD-LD {=blog:post-mdld .blog:Post}
120
+
121
+ [MD-LD] {blog:emphasized label} allows you to embed RDF directly in Markdown.
122
+ ```
123
+
124
+ ## 📚 Documentation Hub
125
+
126
+ - **📖 [Documentation](./docs/index.md)** — Complete documentation with guides and references
127
+ - **🎯 [Examples](./examples/index.md)** — Real-world MD-LD examples and use cases
128
+ - **📋 [Specification](./spec/index.md)** — Formal specification and test suite
129
+ - **🔄 [Diff Generation](./docs/diff.md)** — Automatic diff document generation for CRDT workflows
130
+
131
+ ## ✨ Core Features
132
+
133
+ - **🔗 Prefix folding** — Build hierarchical namespaces with CURIE-based IRI authoring
134
+ - **📍 Subject declarations** — `{=IRI}` and `{=#fragment}` for context setting
135
+ - **🎯 Object IRIs** — `{+IRI}` and `{+#fragment}` for temporary object declarations
136
+ - **🔄 Three predicate forms** — `p` (S→L), `?p` (S→O), `!p` (O→S)
137
+ - **🏷️ Type declarations** — `.Class` for rdf:type triples
138
+ - **📅 Datatypes & language** — `^^xsd:date` and `@en` support
139
+ - **🧩 Fragments** — Document structuring with `{=#fragment}`
140
+ - **⚡ Polarity system** — Sophisticated diff authoring with `+` and `-` prefixes
141
+ - **📍 Origin tracking** — Complete provenance with lean quad-to-source mapping
142
+ - **🎯 Elevated statements** — Automatic rdf:Statement pattern detection
143
+ - **🏷️ Primary metadata quartet** — Subject, type, label, comment for document identity
144
+ - **🔄 Round-trip safety** — Deterministic parse ↔ generate cycles
76
145
 
77
146
  ## 📦 Installation
78
147
 
@@ -83,20 +152,19 @@ pnpm install mdld-parse
83
152
  ```
84
153
 
85
154
  ```javascript
86
- import { parse } from 'mdld-parse';
155
+ import { parse, generate, merge } from 'mdld-parse';
87
156
 
88
- const markdown = `[ex] <tag:alice@example.org,2026:>
89
-
90
- # Demo document {=ex:example/doc .prov:Entity label}
157
+ const mdld = `[ex] <http://example.org/>
91
158
 
92
- > A demo document for MD-LD {comment}
93
- [Alice] {+ex:alice ?ex:author .prov:Person label}
94
- `;
159
+ # Document {=ex:doc .Article label}
95
160
 
96
- const result = parse({ text: markdown });
161
+ [Alice] {=ex:alice ?ex:author .prov:Person ex:firstName label}
162
+ [Smith] {ex:lastName}`;
97
163
 
98
- console.log(result.quads);
99
- // RDF/JS quads ready for n3.js, rdflib, etc.
164
+ const result = parse({ text: mdld });
165
+ console.log(result.quads); // RDF/JS quads
166
+ console.log(result.primary); // { subject, type, label, comment }
167
+ console.log(result.statements); // Elevated statements
100
168
  ```
101
169
 
102
170
  ### Browser (ES Modules)
@@ -104,11 +172,12 @@ console.log(result.quads);
104
172
  ```html
105
173
  <script type="module">
106
174
  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}');
175
+ const result = parse('[ex] <http://example.org/>\n\n# Hello {=ex:hello label}');
109
176
  </script>
110
177
  ```
111
178
 
179
+ **Bundle size:** 84KB unminified, 19KB gzipped
180
+
112
181
  ## 🧠 Semantic Model
113
182
 
114
183
  MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
@@ -117,7 +186,7 @@ MD-LD encodes a directed labeled multigraph where three nodes may be in scope:
117
186
  - **O** — object resource (IRI from link/image)
118
187
  - **L** — literal value (string + optional datatype/language)
119
188
 
120
- ### Predicate Routing (§8.1)
189
+ ### Predicate Routing
121
190
 
122
191
  Each predicate form determines the graph edge:
123
192
 
@@ -127,23 +196,6 @@ Each predicate form determines the graph edge:
127
196
  | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
128
197
  | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
129
198
 
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
199
  ## 🎨 Syntax Quick Reference
148
200
 
149
201
  ### Subject Declaration
@@ -152,19 +204,10 @@ Set current subject (emits no quads):
152
204
  ## Apollo 11 {=ex:apollo11}
153
205
  ```
154
206
 
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
207
  ### Type Declaration
165
208
  Emit `rdf:type` triple:
166
209
  ```markdown
167
- ## Apollo 11 {=ex:apollo11 .ex:SpaceMission .ex:Event}
210
+ ## Apollo 11 {=ex:apollo11 .SpaceMission .Event}
168
211
  ```
169
212
 
170
213
  ### Literal Properties
@@ -184,50 +227,47 @@ Links create relationships (use `?` prefix):
184
227
  ```
185
228
 
186
229
  ### Resource Declaration
187
- Declare resources inline with `{=iri}`:
230
+ Declare resources inline with `{+iri}`:
188
231
  ```markdown
189
232
  # Mission {=ex:apollo11}
190
- [Neil Armstrong] {=ex:armstrong ?ex:commander .prov:Person}
233
+ [Neil Armstrong] {+ex:armstrong ?ex:commander .Person}
234
+ ```
235
+
236
+ ### Diff Authoring (Polarity)
237
+ Use `+` and `-` for retractions:
238
+ ```markdown
239
+ # Update value
240
+ [Person] {=ex:person}
241
+ [Alice] {-ex:name}
242
+ [Bob] {ex:name}
243
+
244
+ # Remove triple
245
+ [Person] {=ex:person}
246
+ [Alice] {-ex:friend}
191
247
  ```
192
248
 
193
249
  ## 🔧 API Reference
194
250
 
195
251
  ### `parse({ text, context, dataFactory, graph })`
196
252
 
197
- Parse MD-LD markdown and return RDF quads with lean origin tracking.
253
+ Parse MDLD to RDF quads with lean origin tracking.
198
254
 
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 }`)
255
+ **Parameters:**
256
+ - `text` (string, required) — MDLD formatted text
257
+ - `context` (object, optional) — Prefix mappings
202
258
  - `dataFactory` (object, optional) — Custom RDF/JS DataFactory
203
259
  - `graph` (string, optional) — Named graph IRI
204
260
 
205
261
  **Returns:** `{ quads, remove, statements, origin, context, primarySubject, primary, md }`
206
262
 
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)
263
+ - `quads` — RDF/JS Quads (final resolved graph state)
264
+ - `remove` — RDF/JS Quads (external retractions for diff workflows)
265
+ - `statements` — Elevated SPO quads from rdf:Statement patterns
266
+ - `origin` — Lean origin tracking for UI navigation
267
+ - `context` — Final context with prefixes
212
268
  - `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
- ```
269
+ - `primary` — Primary metadata quartet: `{ subject, type, label, comment }`
270
+ - `md` — Clean Markdown with annotations stripped
231
271
 
232
272
  ### `merge(docs, options)`
233
273
 
@@ -236,265 +276,137 @@ Merge multiple MDLD documents with diff polarity resolution.
236
276
  **Parameters:**
237
277
  - `docs` (array) — Array of markdown strings or ParseResult objects
238
278
  - `options` (object, optional):
239
- - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
279
+ - `context` (object) — Prefix mappings
240
280
 
241
- **Returns:** `{ quads, remove, origin, context, primarySubjects, primary }`
281
+ **Returns:** `{ quads, remove, statements, origin, context, primarySubjects, primary }`
242
282
 
243
- - `quads` — Array of RDF/JS Quads (final resolved graph state)
244
- - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
283
+ - `quads` — RDF/JS Quads (final resolved graph state)
284
+ - `remove` — RDF/JS Quads (external retractions)
285
+ - `statements` — Elevated statements from all documents
245
286
  - `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.
287
+ - `context` — Final context with prefixes
288
+ - `primarySubjects` — Array of string IRIs (canonical identities)
289
+ - `primary` — Array of primary metadata objects
273
290
 
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/>
291
+ **Use case:** CRDT-style state management with append-only documents.
316
292
 
317
- # Article {=ex:article .ex:Article}
293
+ ### `generate({ quads, context, primarySubject, compactInline, renderReverse, remove })`
318
294
 
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
- ```
295
+ Generate deterministic MDLD from RDF quads.
352
296
 
353
297
  **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';
298
+ - `quads` (array, required) — RDF/JS Quads to convert
299
+ - `context` (object, optional) — Prefix mappings
300
+ - `primarySubject` (string, optional) — IRI to place first in output
301
+ - `compactInline` (boolean, optional) — Inline type/label compaction (default: `false`)
302
+ - `renderReverse` (boolean, optional) — Reverse connections as `!p` (default: `false`)
303
+ - `remove` (array, optional) — RDF/JS Quads to retract (for diff generation)
380
304
 
381
- // Pattern 1: parse → generate (semantic extraction)
382
- const canonical = generate({ ...parse({ text, context }) });
383
- // text → quads → canonical MDLD (deterministic, visual styling applied)
305
+ **Returns:** `{ text, context, compactStats }`
384
306
 
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)
307
+ - `text` — Generated MDLD text
308
+ - `context` — Full context with prefixes
309
+ - `compactStats` — Compaction metrics
388
310
 
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:
311
+ **Features:** Visual styling, label-in-heading, round-trip safe, diff generation.
403
312
 
404
- ```javascript
405
- const result = parse({
406
- text: `# Document {=ex:doc .Article}\n[Content] {ex:content}`,
407
- context: { ex: 'http://example.org/' }
408
- });
313
+ ### `generateNode({ quads, focusIRI, context, compactInline, renderReverse })`
409
314
 
410
- console.log(result.md);
411
- // # Document\nContent
315
+ Generate node-centric MDLD for a specific IRI.
412
316
 
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
- ```
317
+ **Parameters:**
318
+ - `quads` (array, required) — RDF/JS Quads to search
319
+ - `focusIRI` (string, required) — IRI to center view on
320
+ - `context` (object, optional) — Prefix mappings
321
+ - `compactInline` (boolean, optional) — Inline compaction (default: `true`)
322
+ - `renderReverse` (boolean, optional) — Reverse connections (default: `true`)
417
323
 
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
324
+ **Returns:** `{ text, context, compactStats }`
425
325
 
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
326
+ **Safety:** Returns empty text if focusIRI not found (prevents accidental full database rendering).
431
327
 
432
- ### `locate(quad, origin)`
328
+ ### `updateValue({ text, quad, value, origin })`
433
329
 
434
- Locate the origin entry for a quad using the lean origin system.
330
+ Update carrier text of a literal quad in MDLD text.
435
331
 
436
332
  **Parameters:**
437
- - `quad` (object) — The quad to locate (subject, predicate, object)
438
- - `origin` (object) — Origin object containing quadIndex
333
+ - `text` (string) — Original MDLD text
334
+ - `quad` (object) — Quad to update
335
+ - `value` (string) — New carrier text
336
+ - `origin` (object, optional) — ParseResult.origin
439
337
 
440
- **Returns:** `{ blockId, range, valueRange, carrierType, subject, predicate, context, value, polarity }` or `null`
338
+ **Returns:** Updated MDLD text (fail-safe)
441
339
 
442
- - `range`: Full character range including carrier markers (e.g., `[`, `]`, `{`, `}`)
443
- - `valueRange`: Character range excluding carrier markers (null if not available)
340
+ **Use case:** Editor applications updating literal values.
444
341
 
445
- ### `render(quads, options)`
446
-
447
- Render RDF quads as HTML+RDFa for web display.
342
+ ### `locate(quad, origin)`
448
343
 
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
344
+ Locate quad origin entry for UI navigation.
454
345
 
455
- **Returns:** `{ html, context }`
346
+ **Returns:** `{ blockId, range, valueRange, carrierType, ... }` or `null`
456
347
 
457
348
  ### Utility Functions
458
349
 
459
350
  ```javascript
460
351
  import {
461
352
  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
353
+ DataFactory, // RDF/JS DataFactory
354
+ hash, // String hashing
355
+ expandIRI, // IRI expansion
356
+ shortenIRI, // IRI shortening
357
+ parseSemanticBlock // Semantic block parsing
467
358
  } from 'mdld-parse';
468
359
  ```
469
360
 
470
361
  ## 🏗️ Architecture
471
362
 
472
363
  ### Design Principles
473
- - **Zero dependencies** — Pure JavaScript, ~15KB minified
364
+ - **Zero dependencies** — Pure JavaScript, 84KB unminified (19KB gzipped)
474
365
  - **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
366
+ - **Character-based tokenization** — 20-28% faster than regex-based approaches
367
+ - **Standards-compliant** — RDF/JS data model, W3C CURIE 1.0 syntax
368
+ - **Deterministic** — Same input always produces same output
477
369
  - **Explicit semantics** — No guessing, inference, or heuristics
478
370
 
371
+ ### Performance Characteristics
372
+ - **Real-time (60fps):** Up to 4,527 quads per frame
373
+ - **Batch processing:** Up to 225,059 quads per second
374
+ - **Memory efficient:** ~640 bytes per quad retained after GC
375
+ - **Streaming-friendly:** Full document never in memory
376
+
479
377
  ### RDF/JS Compatibility
480
- Quads are compatible with:
378
+ Quads work with:
481
379
  - [`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
380
+ - [`rdflib.js`](https://github.com/linkeddata/rdflib.js) — RDF stores
483
381
  - [`sparqljs`](https://github.com/RubenVerborgh/SPARQL.js) — SPARQL queries
484
- - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — Extended RDF utilities
382
+ - [`rdf-ext`](https://github.com/rdf-ext/rdf-ext) — RDF utilities
485
383
 
486
- ## 🧪 Testing
384
+ ### Standards Compliance
385
+ - **RDF 1.1** — Core RDF concepts
386
+ - **RDFS** — Schema vocabulary
387
+ - **PROV-O** — Provenance ontology
388
+ - **SHACL** — Constraint validation
389
+ - **W3C CURIE 1.0** — Compact URI syntax
487
390
 
488
- The parser includes comprehensive tests covering all spec requirements:
391
+ ## 🧪 Testing
489
392
 
490
393
  ```bash
491
394
  pnpm test
492
395
  ```
493
396
 
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
397
+ Comprehensive test suite covering:
398
+ - Syntax parsing and tokenization
399
+ - Context management and prefix folding
400
+ - Polarity system and retractions
401
+ - Elevated statements detection
402
+ - Primary metadata extraction
403
+ - Round-trip parse/generate cycles
404
+ - Origin tracking and provenance
405
+
406
+ ## 📚 Additional Resources
407
+
408
+ - **[Documentation](./docs/index.md)** — Complete guides and references
409
+ - **[Specification](./spec/index.md)** — Formal specification
410
+ - **[Examples](./examples/index.md)** — Real-world examples
411
+ - **[Grammar](./grammar/mdld.ebnf)** — EBNF grammar specification
412
+ - **[VS Code Extension](https://marketplace.visualstudio.com/)** — Syntax highlighting (coming soon)