mdld-parse 0.7.6 → 0.7.8

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
@@ -123,13 +123,13 @@ Each predicate form determines the graph edge:
123
123
  | `?p` | S → O | `[NASA] {=ex:nasa ?org}` | object property |
124
124
  | `!p` | O → S | `[Parent] {=ex:p !hasPart}` | reverse object |
125
125
 
126
- ## � Elevated Statements
126
+ ## 📍 Elevated Statements
127
127
 
128
- MD-LD automatically detects `rdf:Statement` patterns during parsing and extracts elevated SPO quads for convenient consumption by applications.
128
+ MD-LD supports `rdf:Statement` patterns for elevating certain facts from the semantic data. Use the `extractStatements()` function to extract elevated SPO quads from any quad set.
129
129
 
130
130
  ### Pattern Detection
131
131
 
132
- 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:
132
+ When a document contains a complete `rdf:Statement` pattern with `rdf:subject`, `rdf:predicate`, and `rdf:object`, you can extract the corresponding SPO quad:
133
133
 
134
134
  ```markdown
135
135
  [ex] <http://example.org/>
@@ -137,10 +137,21 @@ When the parser encounters a complete `rdf:Statement` pattern with `rdf:subject`
137
137
  ## Elevated statement {=ex:stmt1 .rdf:Statement}
138
138
  **Alice** {+ex:alice ?rdf:subject} *knows* {+ex:knows ?rdf:predicate} **Bob** {+ex:bob ?rdf:object}
139
139
 
140
- Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
141
- ``
140
+ Direct statement:**Alice** {=ex:alice} knows **Bob** {?ex:knows +ex:bob}
141
+ ```
142
+
143
+ ### Extracting Statements
144
+
145
+ ```javascript
146
+ import { parse, extractStatements } from 'mdld-parse';
147
+
148
+ const result = parse(markdown);
149
+ const statements = extractStatements(result.quads);
142
150
 
143
- ## �🎨 Syntax Quick Reference
151
+ // statements contains elevated SPO quads from rdf:Statement patterns
152
+ ```
153
+
154
+ ## 🎨 Syntax Quick Reference
144
155
 
145
156
  ### Subject Declaration
146
157
  Set current subject (emits no quads):
@@ -198,13 +209,13 @@ Parse MD-LD markdown and return RDF quads with lean origin tracking.
198
209
  - `context` (object) — Prefix mappings (default: `{ '@vocab': 'http://www.w3.org/2000/01/rdf-schema#', rdf, rdfs, xsd, sh, prov }`)
199
210
  - `dataFactory` (object) — Custom RDF/JS DataFactory
200
211
 
201
- **Returns:** `{ quads, remove, statements, origin, context }`
212
+ **Returns:** `{ quads, remove, origin, context, primarySubject }`
202
213
 
203
214
  - `quads` — Array of RDF/JS Quads (final resolved graph state)
204
215
  - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
205
- - `statements` — Array of elevated RDF/JS Quads extracted from rdf:Statement patterns
206
216
  - `origin` — Lean origin tracking object with quadIndex for UI navigation
207
217
  - `context` — Final context used (includes prefixes)
218
+ - `primarySubject` — String IRI or null (first non-fragment subject declaration)
208
219
 
209
220
  ### `merge(docs, options)`
210
221
 
@@ -215,18 +226,45 @@ Merge multiple MDLD documents with diff polarity resolution.
215
226
  - `options` (object, optional):
216
227
  - `context` (object) — Prefix mappings (merged with DEFAULT_CONTEXT)
217
228
 
218
- **Returns:** `{ quads, remove, origin, context }`
229
+ **Returns:** `{ quads, remove, origin, context, primarySubjects }`
230
+
231
+ - `quads` — Array of RDF/JS Quads (final resolved graph state)
232
+ - `remove` — Array of RDF/JS Quads (external retractions targeting prior state)
233
+ - `origin` — Merge origin tracking with document index and polarity
234
+ - `context` — Final merged context
235
+ - `primarySubjects` — Array of string IRIs (primary subjects from each document, in merge order)
219
236
 
220
- ### `generate(quads, context)`
237
+ ### `generate(quads, context, primarySubject)`
221
238
 
222
239
  Generate deterministic MDLD from RDF quads.
223
240
 
224
241
  **Parameters:**
225
242
  - `quads` (array) — Array of RDF/JS Quads to convert
226
243
  - `context` (object, optional) — Prefix mappings (default: `{}`)
244
+ - `primarySubject` (string, optional) — String IRI to place first in output (ensures round-trip safety)
227
245
 
228
246
  **Returns:** `{ text, context }`
229
247
 
248
+ ### `extractStatements(quads, dataFactory)`
249
+
250
+ Extract elevated statements from a quad set by detecting rdf:Statement patterns.
251
+
252
+ **Parameters:**
253
+ - `quads` (array) — Array of RDF/JS Quads to scan
254
+ - `dataFactory` (object, optional) — Custom RDF/JS DataFactory (defaults to built-in)
255
+
256
+ **Returns:** Array of elevated SPO quads extracted from rdf:Statement patterns
257
+
258
+ **Example:**
259
+ ```javascript
260
+ import { parse, extractStatements } from 'mdld-parse';
261
+
262
+ const result = parse(markdown);
263
+ const statements = extractStatements(result.quads);
264
+
265
+ // statements contains elevated SPO quads from rdf:Statement patterns
266
+ ```
267
+
230
268
  ### `locate(quad, origin)`
231
269
 
232
270
  Locate the origin entry for a quad using the lean origin system.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mdld-parse",
3
- "version": "0.7.6",
3
+ "version": "0.7.8",
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
  "main": "index.js",
@@ -0,0 +1,62 @@
1
+ import { DataFactory } from './utils.js';
2
+ import { RDF_TYPE, RDF_SUBJECT, RDF_PREDICATE, RDF_OBJECT, RDF_STATEMENT } from './shared.js';
3
+
4
+ /**
5
+ * Extract elevated statements from a quad set by detecting rdf:Statement patterns.
6
+ *
7
+ * This function scans quads for complete rdf:Statement patterns (rdf:type rdf:Statement
8
+ * with rdf:subject, rdf:predicate, and rdf:object) and extracts the corresponding SPO quads.
9
+ *
10
+ * @param {Array} quads - Array of RDF/JS Quads to scan
11
+ * @param {Object} dataFactory - RDF/JS DataFactory instance (defaults to built-in)
12
+ * @returns {Array} Array of elevated SPO quads extracted from rdf:Statement patterns
13
+ */
14
+ export function extractStatements(quads, dataFactory = DataFactory) {
15
+ const statementCandidates = new Map();
16
+ const statements = [];
17
+
18
+ for (const quad of quads) {
19
+ const predicate = quad.predicate.value;
20
+
21
+ // Early filter: only process rdf:Statement related predicates
22
+ if (predicate !== RDF_TYPE &&
23
+ predicate !== RDF_SUBJECT &&
24
+ predicate !== RDF_PREDICATE &&
25
+ predicate !== RDF_OBJECT) {
26
+ continue;
27
+ }
28
+
29
+ // Check if this quad starts a new rdf:Statement pattern
30
+ if (predicate === RDF_TYPE && quad.object.value === RDF_STATEMENT) {
31
+ statementCandidates.set(quad.subject.value, { spo: {} });
32
+ continue;
33
+ }
34
+
35
+ // Check if this quad completes part of an existing rdf:Statement pattern
36
+ const candidate = statementCandidates.get(quad.subject.value);
37
+ if (!candidate) continue;
38
+
39
+ // Direct property assignment for better performance
40
+ if (predicate === RDF_SUBJECT) {
41
+ candidate.spo.subject = quad.object;
42
+ } else if (predicate === RDF_PREDICATE) {
43
+ candidate.spo.predicate = quad.object;
44
+ } else if (predicate === RDF_OBJECT) {
45
+ candidate.spo.object = quad.object;
46
+ }
47
+
48
+ // Check if pattern is complete and create elevated SPO quad
49
+ if (candidate.spo.subject && candidate.spo.predicate && candidate.spo.object) {
50
+ const spoQuad = dataFactory.quad(
51
+ candidate.spo.subject,
52
+ candidate.spo.predicate,
53
+ candidate.spo.object
54
+ );
55
+ statements.push(spoQuad);
56
+ // Clean up candidate to avoid duplicate detection
57
+ statementCandidates.delete(quad.subject.value);
58
+ }
59
+ }
60
+
61
+ return statements;
62
+ }
package/src/generate.js CHANGED
@@ -34,17 +34,17 @@ export function extractLocalName(iri, ctx = {}) {
34
34
  /**
35
35
  * Generate deterministic MDLD from RDF quads
36
36
  * Purpose: TTL→MDLD conversion with canonical structure
37
- * Input: RDF quads + context
37
+ * Input: RDF quads + context + optional primarySubject (string IRI)
38
38
  * Output: MDLD text
39
39
  */
40
- export function generate(quads, context = {}) {
40
+ export function generate(quads, context = {}, primarySubject = null) {
41
41
  const fullContext = { ...DEFAULT_CONTEXT, ...context };
42
42
 
43
43
  const normalizedQuads = normalizeAndSortQuads(quads);
44
44
 
45
45
  const subjectGroups = groupQuadsBySubject(normalizedQuads);
46
46
 
47
- const { text } = buildDeterministicMDLD(subjectGroups, fullContext);
47
+ const { text } = buildDeterministicMDLD(subjectGroups, fullContext, primarySubject);
48
48
 
49
49
  return text;
50
50
  }
@@ -86,7 +86,7 @@ function groupQuadsBySubject(quads) {
86
86
  return groups;
87
87
  }
88
88
 
89
- function buildDeterministicMDLD(subjectGroups, context) {
89
+ function buildDeterministicMDLD(subjectGroups, context, primarySubject = null) {
90
90
  let text = '';
91
91
  const usedPrefixes = collectUsedPrefixes(subjectGroups, context);
92
92
 
@@ -103,10 +103,16 @@ function buildDeterministicMDLD(subjectGroups, context) {
103
103
  text += '\n';
104
104
  }
105
105
 
106
- // Process subjects in deterministic order
106
+ // Process subjects in deterministic order, with primary subject first
107
107
  const sortedSubjects = Array.from(subjectGroups.keys()).sort();
108
+ const primarySubjectIRI = primarySubject; // Already a string IRI
108
109
 
109
- for (const subjectIRI of sortedSubjects) {
110
+ // If primary subject exists, place it first
111
+ const orderedSubjects = primarySubjectIRI
112
+ ? [primarySubjectIRI, ...sortedSubjects.filter(s => s !== primarySubjectIRI)]
113
+ : sortedSubjects;
114
+
115
+ for (const subjectIRI of orderedSubjects) {
110
116
  const subjectQuads = subjectGroups.get(subjectIRI);
111
117
  const shortSubject = shortenIRI(subjectIRI, context);
112
118
 
@@ -119,7 +125,7 @@ function buildDeterministicMDLD(subjectGroups, context) {
119
125
  ? ' ' + types.map(t => '.' + shortenIRI(t.object.value, context)).sort().join(' ')
120
126
  : '';
121
127
 
122
- text += `# ${localSubjectName} {=${shortSubject}${typeAnnotations}}\n`;
128
+ text += `# ${localSubjectName} {=${shortSubject}${typeAnnotations}}\n\n`;
123
129
 
124
130
  // Add literals and objects using shared utilities
125
131
  sortQuadsByPredicate(literals).forEach(quad => {
package/src/index.js CHANGED
@@ -3,6 +3,7 @@ export { merge } from './merge.js';
3
3
  export { generate } from './generate.js';
4
4
  export { locate } from './locate.js';
5
5
  export { render } from './render.js';
6
+ export { extractStatements } from './extract-statements.js';
6
7
  export { DEFAULT_CONTEXT } from './constants.js';
7
8
  export {
8
9
  DataFactory,
package/src/merge.js CHANGED
@@ -33,15 +33,15 @@ function normalizeInput(input, options, docContext) {
33
33
  * Merges multiple MDLD documents with diff polarity resolution
34
34
  * @param {Array<string|ParseResult>} docs
35
35
  * @param {Object} options
36
- * @returns {Object} Merge result with quads, remove, statements, origin, and context
36
+ * @returns {Object} Merge result with quads, remove, origin, and context
37
37
  */
38
38
  export function merge(docs, options = {}) {
39
39
  const sessionBuffer = new Map(); // Use Map instead of Set for proper quad storage
40
40
  const sessionRemoveSet = new Set();
41
41
  const allDocuments = [];
42
42
  const quadIndex = new Map();
43
- const allStatements = []; // Collect statements from all documents
44
43
  const accumulatedContext = new Map(); // Track all unique prefixes across documents
44
+ const primarySubjects = []; // Collect primary subjects from all documents
45
45
 
46
46
  // Process each document in order
47
47
  for (let i = 0; i < docs.length; i++) {
@@ -68,14 +68,13 @@ export function merge(docs, options = {}) {
68
68
  index: i,
69
69
  input: typeof input === 'string' ? 'string' : 'ParseResult',
70
70
  origin: doc.origin,
71
- context: doc.context,
72
- statementsCount: doc.statements?.length || 0 // Track statements count
71
+ context: doc.context
73
72
  };
74
73
  allDocuments.push(documentOrigin);
75
74
 
76
- // Collect statements from this document
77
- if (doc.statements && doc.statements.length > 0) {
78
- allStatements.push(...doc.statements);
75
+ // Collect primary subject from this document (already a string IRI)
76
+ if (doc.primarySubject) {
77
+ primarySubjects.push(doc.primarySubject);
79
78
  }
80
79
 
81
80
  // Fold assertions into session buffer
@@ -142,8 +141,8 @@ export function merge(docs, options = {}) {
142
141
  return {
143
142
  quads: filteredQuads,
144
143
  remove: filteredRemove,
145
- statements: allStatements, // Include all collected statements
146
144
  origin: mergeOrigin,
147
- context: finalContext
145
+ context: finalContext,
146
+ primarySubjects: primarySubjects // Include all collected primary subjects
148
147
  };
149
148
  }
package/src/parse.js CHANGED
@@ -33,11 +33,6 @@ import {
33
33
  determineCarrierType,
34
34
  calcCarrierRanges,
35
35
  extractCleanText,
36
- RDF_TYPE,
37
- RDF_STATEMENT,
38
- RDF_SUBJECT,
39
- RDF_PREDICATE,
40
- RDF_OBJECT,
41
36
  createLeanOriginEntry,
42
37
  resolveSubject,
43
38
  resolveObject,
@@ -49,6 +44,7 @@ export function parse(text, options = {}) {
49
44
  const state = {
50
45
  ctx: { ...DEFAULT_CONTEXT, ...(options.context || {}) },
51
46
  df: options.dataFactory || DataFactory,
47
+ graph: DataFactory.namedNode(options.graph) || DataFactory.defaultGraph(),
52
48
  quads: [],
53
49
  quadBuffer: new Map(),
54
50
  removeSet: new Set(),
@@ -58,10 +54,9 @@ export function parse(text, options = {}) {
58
54
  documentStructure: []
59
55
  },
60
56
  currentSubject: null,
57
+ primarySubject: null,
61
58
  tokens: null,
62
59
  currentTokenIndex: -1,
63
- statements: [],
64
- statementCandidates: new Map(),
65
60
  currentBlock: null,
66
61
  blockStack: []
67
62
  };
@@ -107,7 +102,7 @@ export function parse(text, options = {}) {
107
102
  }
108
103
  }
109
104
 
110
- return { quads: state.quads, remove: filteredRemove, statements: state.statements, origin: state.origin, context: state.ctx };
105
+ return { quads: state.quads, remove: filteredRemove, origin: state.origin, context: state.ctx, primarySubject: state.primarySubject };
111
106
  }
112
107
 
113
108
 
@@ -387,6 +382,11 @@ function processAnnotationWithBlockTracking(carrier, sem, state, options = {}) {
387
382
  const newSubject = resolveSubject(sem, state);
388
383
  const localObject = resolveObject(sem, state);
389
384
 
385
+ // Track primary subject: first non-fragment subject declaration (fixed once detected)
386
+ if (newSubject && !state.primarySubject && !sem.subject.startsWith('=#')) {
387
+ state.primarySubject = newSubject.value; // Store as string IRI
388
+ }
389
+
390
390
  const effectiveSubject = implicitSubject || (newSubject && !preserveGlobalSubject ? newSubject : previousSubject);
391
391
  if (newSubject && !preserveGlobalSubject && !implicitSubject) {
392
392
  state.currentSubject = newSubject;
@@ -435,7 +435,7 @@ function createBlock(subject, types, predicates, range, attrsRange, valueRange,
435
435
  };
436
436
  }
437
437
 
438
- function emitQuad(quads, quadBuffer, removeSet, quadIndex, block, subject, predicate, object, dataFactory, meta = null, statements = null, statementCandidates = null, state = null) {
438
+ function emitQuad(quads, quadBuffer, removeSet, quadIndex, block, subject, predicate, object, dataFactory, meta = null, state = null) {
439
439
  if (!subject || !predicate || !object) return;
440
440
 
441
441
  const quad = dataFactory.quad(subject, predicate, object);
@@ -468,9 +468,6 @@ function emitQuad(quads, quadBuffer, removeSet, quadIndex, block, subject, predi
468
468
  quadBuffer.set(quadKey, quad);
469
469
  quads.push(quad);
470
470
 
471
- // Detect rdf:Statement pattern during single-pass parsing
472
- detectStatementPatternSinglePass(quad, dataFactory, meta, statements, statementCandidates);
473
-
474
471
  // Create lean origin entry using shared utility
475
472
  const originEntry = createLeanOriginEntry(block, subject, predicate, meta);
476
473
 
@@ -486,54 +483,6 @@ function emitQuad(quads, quadBuffer, removeSet, quadIndex, block, subject, predi
486
483
  }
487
484
  }
488
485
 
489
- function detectStatementPatternSinglePass(quad, dataFactory, meta, statements = null, statementCandidates = null) {
490
- // Skip if not called from parse context (for testing compatibility)
491
- if (!statements || !statementCandidates) return;
492
-
493
- const predicate = quad.predicate.value;
494
-
495
- // Early filter: only process rdf:Statement related predicates
496
- if (predicate !== RDF_TYPE &&
497
- predicate !== RDF_SUBJECT &&
498
- predicate !== RDF_PREDICATE &&
499
- predicate !== RDF_OBJECT) {
500
- return;
501
- }
502
-
503
- // Check if this quad starts a new rdf:Statement pattern
504
- if (predicate === RDF_TYPE && quad.object.value === RDF_STATEMENT) {
505
- statementCandidates.set(quad.subject.value, { spo: {} });
506
- return;
507
- }
508
-
509
- // Check if this quad completes part of an existing rdf:Statement pattern
510
- const candidate = statementCandidates.get(quad.subject.value);
511
- if (!candidate) return;
512
-
513
- // Direct property assignment instead of switch for better performance
514
- if (predicate === RDF_SUBJECT) {
515
- candidate.spo.subject = quad.object;
516
- } else if (predicate === RDF_PREDICATE) {
517
- candidate.spo.predicate = quad.object;
518
- } else if (predicate === RDF_OBJECT) {
519
- candidate.spo.object = quad.object;
520
- // Store the original quad for potential literal extraction
521
- candidate.objectQuad = quad;
522
- }
523
-
524
- // Check if pattern is complete and create elevated SPO quad
525
- if (candidate.spo.subject && candidate.spo.predicate && candidate.spo.object) {
526
- // Use the object directly - literal detection happens at parse time
527
- const spoQuad = dataFactory.quad(
528
- candidate.spo.subject,
529
- candidate.spo.predicate,
530
- candidate.spo.object
531
- );
532
- statements.push(spoQuad);
533
- // Clean up candidate to avoid duplicate detection
534
- statementCandidates.delete(quad.subject.value);
535
- }
536
- }
537
486
 
538
487
  const createTypeQuad = (typeIRI, subject, state, block, entryIndex = null) => {
539
488
  const expandedType = expandIRI(typeIRI, state.ctx);
@@ -545,7 +494,6 @@ const createTypeQuad = (typeIRI, subject, state, block, entryIndex = null) => {
545
494
  state.df.namedNode(expandedType),
546
495
  state.df,
547
496
  { kind: 'type', token: `.${typeIRI}`, expandedType, entryIndex: typeInfo.entryIndex, remove: typeInfo.remove },
548
- state.statements, state.statementCandidates,
549
497
  state
550
498
  );
551
499
  };
@@ -590,7 +538,6 @@ function processPredicateAnnotations(sem, newSubject, previousSubject, localObje
590
538
  emitQuad(state.quads, state.quadBuffer, state.removeSet, state.origin.quadIndex, block,
591
539
  role.subject, P, role.object, state.df,
592
540
  { kind: 'pred', token: `${pred.form}${pred.iri}`, form: pred.form, expandedPredicate: P.value, entryIndex: pred.entryIndex, remove: pred.remove || false },
593
- state.statements, state.statementCandidates,
594
541
  state
595
542
  );
596
543
  }