rc3.0.0

.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish
+
+on: 
+  workflow_run:
+    workflows: [Run Tests]
+    types: [completed]
+    branches: [master, main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: 'https://registry.npmjs.org'
+      - uses: ButlerLogic/[email protected]
+        with:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          tag_prefix: "v"
+        id: create_tag
+      # - run: echo ${{ steps.create_tag.outputs.tagname }}
+      # - run: echo ${{ steps.create_tag.outputs.version }}
+      - name: Check if a new tag is created
+        run: "[[ '${{ steps.create_tag.outputs.tagname }}' ]]"
+      - name: get major-minor version
+        id: docver
+        run: echo "DOCVER=${TAGNAME%.*}" >> $GITHUB_ENV 
+        env:
+          TAGNAME: ${{ steps.create_tag.outputs.tagname }}
+      - run: npm ci
+      - run: npm run build-docs
+      - name: Deploy docs to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs
+          target-folder: docs/${{ env.DOCVER }}
+          single-commit: true
+      - name: Publish package on NPM
+        run: npm publish --access public

.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Run tests
+
+on: 
+  push:
+    branches:
+    - master
+    - main
+
+jobs:  
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [16, 18]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm ci && npm test

.gitignore

@@ -64,5 +64,5 @@ typings/
 .idea
 .vscode
 
-# JSDoc generated documentation
+# generated api documentation
 docs/

README.md

@@ -1,15 +1,136 @@
-# ro-crate : Research Object Crate (RO-Crate) utilities 
+# Research Object Crate (RO-Crate) JavaScript Library
 
-This is a javascript library to support Research Object Crate ([RO-Crate]https://researchobject.github.io/ro-crate/)).
+This is a JavaScript library to create and manipulate [Research Object Crate](https://www.researchobject.org/ro-crate/).
 
-## Install
-Install the library:
 
-`npm install rocrate`
+## Install
 
-## HTML Renderingv -- DEPRECATED
+Install the library:
 
-THIS FEATURE HAS BEEN REMOVED. Use the [RO-Crate-HTML](https://www.npmjs.com/package/ro-crate-html-js) library instead.
+    npm install rocrate
+
+
+## Usage
+
+Import the `ROCrate` class and create a new empty crate with default configurations:
+
+```js
+const {ROCrate} = require('ro-crate');
+const crate = new ROCrate();
+```
+
+The `ROCrate` constructor accepts two optional arguments:
+
+```js
+const fs = require('fs');
+
+// load existing metadata
+const data = JSON.parse(fs.readFileSync('ro-crate-metadata.json', 'utf8'));
+
+// create a crate using the existing data and
+// configure the crate to return a property of an Entity as an array and resolve linked entity as nested object
+const crate = new ROCrate(data, { array: true, link: true });
+```
+
+To add an Entity to the crate:
+
+```js
+// A license
+const license = {
+    '@id': 'https://creativecommons.org/licenses/by/4.0/',
+    '@type': 'CreativeWork',
+    'description': 'Attribution 4.0 International (CC BY 4.0) ...',
+    'name': 'CC BY 4.0'
+};
+// add the license as an unconnected Entity
+crate.addEntity(license);
+
+// add the license to the root dataset
+crate.rootDataset.license = {'@id': license['@id']};
+// or alternatively, add a new entity directly into a property of other entity :
+crate.rootDataset.license = license;
+```
+
+Use an entity just like a normal object:
+
+```js
+let lic = create.getEntity(license['@id']);
+console.log(lic.name); // prints 'CC BY 4.0';
+// set a property directly
+lic.name = 'CC BY 4.0 dummy';
+// or with the setProperty method
+crate.setProperty(license['@id'], 'name', 'CC BY 4.0 dummy');
+
+console.log(lic.name); // prints 'CC BY 4.0 dummy';
+```
+
+Modifying an array of values in the property is not supported yet:
+
+```js
+lic.test = [1,2,3];
+lic.test.push(4); // this does not work
+console.log(lic.test); // prints '[1,2,3]';
+// use this instead
+lic.test = lic.test.concat(4);
+// or this
+crate.addValues(license['@id'], 'test', 4);
+```
+
+Root Dataset is a special entity that is mandated by the standard:
+
+```js
+const rootDataset = crate.rootDataset;
+rootDataset.name = 'Tutorial Crate';
+rootDataset.description = 'This is an example crate for educational purposes.'
+const today = new Date().toISOString().split('T')[0]
+rootDataset.datePublished = today;
+```
+
+The value of the returned property can be set to be always as an array:
+
+```js
+const crate1 = new ROCrate();
+const crate2 = new ROCrate({array: true});
+crate1.rootDataset.name = 'Tutorial Crate';
+crate1.rootDataset.test = ['test1', 'test2'];
+crate2.rootDataset.name = 'Tutorial Crate';
+crate2.rootDataset.test = ['test1', 'test2'];
+console.log(crate1.rootDataset.name); // return 'Tutorial Crate'
+console.log(crate1.rootDataset.name); // return ['test1', 'test2']
+console.log(crate2.rootDataset.name); // return ['Tutorial Crate']
+console.log(crate2.rootDataset.name); // return ['test1', 'test2']
+```
+
+Linked entities can be automatically resolved as nested objects:
+
+```js
+const crate1 = new ROCrate();
+const crate2 = new ROCrate({link: true});
+const crate3 = new ROCrate({link: true, array: true});
+crate1.rootDataset.license = license;
+crate2.rootDataset.license = license;
+crate3.rootDataset.license = license;
+console.log(crate1.rootDataset.license.name); // return undefined
+console.log(crate1.rootDataset.license); // return {'@id': 'https://creativecommons.org/licenses/by/4.0/'}
+console.log(crate2.rootDataset.license.name); // return 'CC BY 4.0'
+console.log(crate3.rootDataset.license.name); // return undefined, property license is a array
+console.log(crate3.rootDataset.license[0].name); // return 'CC BY 4.0'
+```
+
+To save the rocrate data to a file, use `JSON.stringify`:
+
+```js
+// Write pretty-printed JSONLD into the directory
+fs.writeFileSync('ro-crate-metadata.json', JSON.stringify(crate, null, 2));
+```
+
+For more details, refer to the full [API documentation](https://arkisto-platform.github.io/ro-crate-js/).   
+For more usage examples, see the test files under the [test directory](test).
+
+
+## HTML Rendering
+
+Use the [RO-Crate-HTML](https://www.npmjs.com/package/ro-crate-html-js) to generate a HTML preview from the RO-Crate Metadata File `ro-crate-metadata.json`.
 
 ## Simple crate checker
 
@@ -21,15 +142,3 @@ Check a crate:
 
 This is produce a simple report.
 
-## Programming
-
-For instructions on how to use this module, see the [tutorials github repository](https://github.com/UTS-eResearch/ro-crate-js-tutorials).
-
-
-
-
-
-
-
-
-

index.js

@@ -1,6 +1,20 @@
+const {ROCrate} = require('./lib/rocrate.js');
+const {Checker} = require('./lib/checker.js');
+const {Utils} = require('./lib/utils.js');
+const Defaults = require('./lib/defaults.js');
+/**
+ * @exports ROCrate/RawEntity
+ */
 module.exports = {
-  ROCrate: require('./lib/rocrate.js'),
-  Checker: require('./lib/checker.js'),
-  Utils: require('./lib/utils.js'),
-  Defaults: require('./lib/defaults.js')
-}
+  ROCrate,
+  Checker,
+  Utils,
+  Defaults,
+};
+
+// module.exports = {
+//   ROCrate: require('./lib/rocrate.js'),
+//   Checker: require('./lib/checker.js'),
+//   Utils: require('./lib/utils.js'),
+//   Defaults: require('./lib/defaults.js')
+// }

index.mjs

@@ -0,0 +1,3 @@
+export * from './index.js'; 
+import {ROCrate} from './index.js';
+export default ROCrate;

index.ts

@@ -0,0 +1,5 @@
+export * from './lib/types';
+export {ROCrate} from './lib/rocrate'; 
+export {Checker, CheckItem} from './lib/checker'; 
+export {Utils} from './lib/utils'; 
+//export * as Defaults from './lib/defaults';