https://github.com/treecg/ldes-announcements
https://github.com/treecg/ldes-announcements
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/treecg/ldes-announcements
- Owner: TREEcg
- Created: 2021-11-10T16:07:57.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2021-12-23T16:52:58.000Z (over 3 years ago)
- Last Synced: 2025-02-03T08:36:47.203Z (3 months ago)
- Language: TypeScript
- Size: 46.9 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# LDES-Announcements
[](https://www.npmjs.com/package/@treecg/ldes-announcements)
This library handles parsing and creating LDES announcements.
Such announcements can be sent to a [Solid](https://solidproject.org/TR/protocol) inbox (like [https://tree.linkeddatafragments.org/announcements/](https://tree.linkeddatafragments.org/inbox/)), where they can be curated.
## How to extract (parse) announcements
```javascript
const LDESannouncements = require('@treecg/ldes-announcements');
const rdfParser = require("rdf-parse").default;
const streamifyString = require('streamify-string');
const storeStream = require("rdf-store-stream").storeStream;
const announcementText = `
@prefix : .
@prefix as: .
@prefix dct: .
@prefix ldes: .
@prefix rdf: .
@prefix rdfs: .
@prefix tree: .
@prefix xsd: .
tree:view :view .
:announcement rdf:type as:Announce ;
as:actor ;
as:object :view .
:bucketizerConfiguration rdf:type ldes:BucketizerConfiguration ;
ldes:bucketizer ldes:SubstringBucketizer ;
ldes:pageSize "100"^^xsd:positiveInteger ;
tree:path rdfs:label .
:view dct:issued "2021-10-15T00:00:00.000Z"^^xsd:dateTime ;
dct:isVersionOf ;
rdf:type tree:Node ;
ldes:configuration :bucketizerConfiguration .
`
// convert string (text/turtle) into N3 Store
const textStream = streamifyString(announcementText);
const quadStream = rdfParser.parse(textStream,{contentType: 'text/turtle'});
const store = await storeStream(quadStream);
// use extractAnnouncementsMetadata to parse the announcement
const announcements = await LDESannouncements.extractAnnouncementsMetadata(store);
```
The variable `announcements` contains four Maps where the announcements Map (`announcements.announcements`) contains the announcement and in this case the views map will contain the view corresponding to the announcement.
```javascript
// Extract announcement and view, which are objects from the interfaces defined in src/util/Interfaces.ts
const announcement = announcements.announcements.get('https://tree.linkeddatafragments.org/announcements/1636985640000/ExampleViewAnnouncement.ttl#announcement');
const view = announcements.views.get('https://tree.linkeddatafragments.org/announcements/1636985640000/ExampleViewAnnouncement.ttl#view');
// print out the view (in JSON-LD representation)
console.log(JSON.stringify(view));
```
import { extractAnnouncementsMetadata } from './lib/Extraction';
import { fetchAllAnnouncements, postAnnouncement } from './lib/LDPCommunication';
import { AnnouncementConfig, createViewAnnouncement } from './lib/Writer';
### Parsing from URI
It is easier when the document is hosted, because then no parsing to a store is required
```javascript
const LDESannouncements = require('@treecg/ldes-announcements');
const rdfRetrieval = require('@dexagod/rdf-retrieval');
const store = await rdfRetrieval.getResourceAsStore('https://tree.linkeddatafragments.org/announcements/1636985640000/ExampleViewAnnouncement.ttl');
const announcements = await LDESannouncements.extractAnnouncementsMetadata(store);
// Extract announcement and view, which are objects from the interfaces defined in src/util/Interfaces.ts
const announcement = announcements.announcements.get('https://tree.linkeddatafragments.org/announcements/1636985640000/ExampleViewAnnouncement.ttl#announcement');
const view = announcements.views.get('https://tree.linkeddatafragments.org/announcements/1636985640000/ExampleViewAnnouncement.ttl#view');
// print out the view (in JSON-LD representation)
console.log(JSON.stringify(view));
```
### Parsing from an announcement LDES containing multiple announcements
```javascript
const LDESannouncements = require('@treecg/ldes-announcements');
const store = await LDESannouncements.fetchAllAnnouncements('https://tree.linkeddatafragments.org/announcements/');
const announcements = await LDESannouncements.extractAnnouncementsMetadata(store);
// print all ids, time created and original LDES from the view announcements
announcements.views.forEach(value => {
console.log(`View ID: ${value['@id']} | Created at: ${value['dct:issued']['@value']}`);
console.log(`Original LDES: ${value['@reverse'].view['@id']}`);
});
```
## How to create announcements
```javascript
const LDESannouncements = require('@treecg/ldes-announcements');
const rdfParser = require("rdf-parse").default;
const streamifyString = require('streamify-string');
const storeStream = require("rdf-store-stream").storeStream;
// The root string MUST contain all the information of a root node according to the TREE Hypermedia specification (https://w3id.org/tree/specification)
// It can also contain information of a retention policy as defined in the Linked Data Event Streams specification (https://w3id.org/ldes/specification)
const root = `
a .
`;
const announcementConfig = {
bucketizer: 'substring',
creatorName: 'woutslabbinck',
creatorURL: 'https://github.com/woutslabbinck',
originalLDESURL: 'https://smartdata.dev-vlaanderen.be/base/gemeente',
pageSize: "100",
propertyPath: 'http://www.w3.org/2000/01/rdf-schema#label',
viewId: 'https://example.org/output/root.ttl'
};
// convert string (text/turtle) into N3 Store
const textStream = streamifyString(root);
const quadStream = rdfParser.parse(textStream,{contentType: 'text/turtle'});
const store = await storeStream(quadStream);
// Create an announcement with a view using the store and the announcement configuration
const announcement = await LDESannouncements.createViewAnnouncement(store, announcementConfig);
console.log(JSON.stringify(announcement));
```
### Sending announcements to an inbox
```javascript
const LDESannouncements = require('@treecg/ldes-announcements');
const rdfParser = require("rdf-parse").default;
const streamifyString = require('streamify-string');
const storeStream = require("rdf-store-stream").storeStream;
// The root string MUST contain all the information of a root node according to the TREE Hypermedia specification (https://w3id.org/tree/specification)
// It can also contain information of a retention policy as defined in the Linked Data Event Streams specification (https://w3id.org/ldes/specification)
const root = `
a .
`;
const announcementConfig = {
bucketizer: 'substring',
creatorName: 'woutslabbinck',
creatorURL: 'https://github.com/woutslabbinck',
originalLDESURL: 'https://smartdata.dev-vlaanderen.be/base/gemeente',
pageSize: "100",
propertyPath: 'http://www.w3.org/2000/01/rdf-schema#label',
viewId: 'https://example.org/output/root.ttl'
};
// convert string (text/turtle) into N3 Store
const textStream = streamifyString(root);
const quadStream = rdfParser.parse(textStream,{contentType: 'text/turtle'});
const store = await storeStream(quadStream);
// Create an announcement with a view using the store and the announcement configuration
const announcement = await LDESannouncements.createViewAnnouncement(store, announcementConfig);
// The URL of the root container of an LDES in LDP (Linked Data Platform, see https://www.w3.org/TR/ldp/)
const announcementInbox = 'https://tree.linkeddatafragments.org/announcements/'
// Using the protocol shown in the figure, POST to the LDP Container
const response = await LDESannouncements.postAnnouncement(announcement, announcementInbox);
```