3.x changes and more

.eslintrc.js

@@ -6,8 +6,12 @@ module.exports = {
     node: true
   },
   extends: [
-    'digitalbazaar'
+    'digitalbazaar',
+    'digitalbazaar/jsdoc'
   ],
+  rules: {
+    'jsdoc/require-description-complete-sentence': 'off'
+  },
   ignorePatterns: [
     'test-suites'
   ]

.github/workflows/main.yml

@@ -8,11 +8,11 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install
@@ -23,11 +23,11 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        node-version: [16.x, 18.x]
+        node-version: [16.x, 18.x, 20.x]
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - name: Install
@@ -41,12 +41,12 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
         bundler: [webpack, browserify]
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - name: Install
@@ -63,11 +63,11 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        node-version: [18.x]
+        node-version: [20.x]
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - name: Install
@@ -77,7 +77,7 @@ jobs:
     - name: Generate coverage report
       run: npm run coverage-ci
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      uses: codecov/codecov-action@v3
       with:
         file: ./coverage/lcov.info
         fail_ci_if_error: true

CHANGELOG.md

@@ -4,14 +4,38 @@
 
 ### Added
 - Test with karma.
+- Test with Node.js 20.x.
+- Add `inputFormat` option. Use "application/n-quads" for a N-Quads string that
+  will be parsed. Omit option for a JSON dataset or legacy dataset. This can
+  simplify a common case of using the internal parser to generate a dataset.
+  - **NOTE**: The `inputFormat` option was previously ignored and is now used.
+    Any calling code that was passing in an incorrect value needs to be fixed.
 
 ### Changed
+- **BREAKING**: Change algorithm name from "URDNA2015" to "RDFC-1.0" to match
+  spec changes. Use of "URDNA2015" is now deprecated and an alias for
+  "RDFC-1.0". An API option `rejectURDNA2015` is available to disable
+  "URDNA2015" support. A global `RDF_CANONIZE_TRACE_URDNA2015` is available to
+  developers to trace calls that use "URDNA2015". See the README for important
+  compatibility notes and API details.
+- **BREAKING**: Use latest [rdf-canon][] N-Quads canonical form. This can
+  change the canonical output! There is an expanded set of literal string
+  control characters that are escaped as an `ECHAR` or `UCHAR` instead of using
+  a native representation.
+  - Previously: the canonical N-Quads form used here was encoding `\u000A`
+    (`\n`), `\u000D` (`\r`), `\u0022` (`"`), and `\u005C` (`\`) as `ECHARs`:
+    `\n`, `\r`, `\"`, and `\\`, All other characters were represented as native
+    Unicode.
+  - Now: the output also encodes `\u0008` (`\b`), `\u0009` (`\t`), `\u000C`
+    (`\f`) as `ECHARs` `\b`, `\t`, and `\f`, and encodes the "control"
+    characters in the range of `\u0000-\u001F` and `\u007F` as `UCHARs`
+    `\u00xx`. All other characters are represented as native Unicode.
 - **BREAKING**: Use `globalThis` to access `crypto` in browsers. Use a polyfill
   if your environment doesn't support `globalThis`.
 - Update tooling.
 - Update for latest [rdf-canon][] changes: test suite location, README, links,
   and identifiers.
-- More closly align test code with the version in [jsonld.js][].
+- More closely align test code with the version in [jsonld.js][].
   - Use combined test/benchmark system.
   - Support running multiple test jobs in parallel.
 - Refactor `MessageDigest-browser.js` to `MessageDigest-webcrypto.js` so it can
@@ -22,17 +46,23 @@
   - Node.js using the improved browser algorithm can be ~4-9% faster overall.
   - Node.js native `Buffer` conversion can be ~5-12% faster overall.
 - Optimize a N-Quads serialization call.
-- Optimize N-Quads escape/unescape:
+- Optimize N-Quads escape/unescape calling replace:
   - Run regex test before doing a replace call.
   - Performance difference depends on data and how often escape/unescape would
     need to be called. A benchmark test data showed ~3-5% overall improvement.
+- Optimize N-Quads escape replacement:
+  - Use a pre-computed map of replacement values.
+  - Performance difference depends on the number of replacements. The
+    [rdf-canon][] escaping test showed up to 15% improvement.
 
 ### Fixed
 - Disable native lib tests in a browser.
 - Disable sync tests in a browser. The sync code attempts to use the async
   webcrypto calls and produces invalid results. It is an error that this
   doesn't fail, but sync code is currently only for testing.
 - Fix various testing and benchmark bugs.
+- Escape and unescape all data.
+- Support 8 hex char Unicode values.
 
 ### Removed
 - **BREAKING**: Remove URGNA2012 support. [rdf-canon][] no longer supports or
@@ -45,6 +75,15 @@
 - Remove `benchmark/benchmark.js` tool in favor of combined test system and
   benchmarking control via environment vars.
 
+## 3.4.0 - 2023-05-19
+
+### Added
+- Allow `canonicalIdMap` to be passed to `canonize` which will be populated by
+  the canonical identifier issuer with the bnode identifier mapping generated
+  by the canonicalization algorithm. This feature is particularly useful when
+  the resulting bnode labels need to be changed for use cases such as selective
+  disclosure.
+
 ## 3.3.0 - 2022-09-17
 
 ### Added
@@ -159,7 +198,7 @@
 ### Changed
 - Improve N-Quads parsing.
   - Unescape literals.
-  - Handle unicode escapes.
+  - Handle Unicode escapes.
 - N-Quad serialization optimization.
   - Varies based on input by roughly ~1-2x.
 - **BREAKING**: Remove `rdf-canonize-native` as a dependency. The native

README.md

@@ -3,12 +3,14 @@
 [![Build status](https://img.shields.io/github/actions/workflow/status/digitalbazaar/rdf-canonize/main.yml)](https://github.com/digitalbazaar/rdf-canonize/actions/workflows/main.yml)
 [![Coverage status](https://img.shields.io/codecov/c/github/digitalbazaar/rdf-canonize)](https://codecov.io/gh/digitalbazaar/rdf-canonize)
 
-An implementation of the [RDF Dataset Canonicalization Algorithm][] in JavaScript.
+An implementation of the [RDF Dataset Canonicalization][] specification in
+JavaScript.
 
 Introduction
 ------------
 
-...
+See the [RDF Dataset Canonicalization][] specification for details on the
+specification and algorithm this library implements.
 
 Installation
 ------------
@@ -60,16 +62,50 @@ const dataset = {
 };
 
 // canonize a data set with a particular algorithm with async/await
-const canonical = await canonize.canonize(dataset, {algorithm: 'URDNA2015'});
+const canonical = await canonize.canonize(dataset, {algorithm: 'RDFC-1.0'});
 
 // canonize a data set with a particular algorithm and force use of the
 // native implementation
 const canonical = await canonize.canonize(dataset, {
-  algorithm: 'URDNA2015',
+  algorithm: 'RDFC-1.0',
   useNative: true
 });
 ```
 
+Algorithm Support
+-----------------
+
+* "[RDFC-1.0][]": Supported.
+  * Primary algorithm in the [RDF Dataset Canonicalization][] specification.
+* "[URDNA2015][]": Deprecated and supported as an alias for "RDFC-1.0".
+  * Former algorithm name that evolved into "RDFC-1.0".
+  * **NOTE**: There are minor differences in the [canonical N-Quads
+    form](https://w3c.github.io/rdf-canon/spec/#canonical-quads) that *could*
+    cause canonical output differences in some cases. See the 4.0.0 changelog
+    or code for details. If strict "URDNA2015" support is required, use a 3.x
+    version of this library.
+  * See the migration section below if you have code that uses the "URDNA2015"
+    algorithm name.
+* "[URGNA2012][]": No longer supported.
+  * Older algorithm with significant differences from newer algorithms.
+  * Use older versions versions of this library if support is needed.
+
+URDNA2015 Migration
+-------------------
+
+* The deprecated "URDNA2015" algorithm name is currently supported as an alias
+  for "RDFC-1.0".
+* There is a minor difference that could cause compatibilty issues. It is
+  considered an edge case that will not be an issue in practice. See above for
+  details.
+* Two tools are currently provided to help transition to "RDFC-1.0":
+  * If the API option `rejectURDNA2015` is truthy, it will cause an error to be
+    thrown if "URDNA2015" is used.
+  * If the global `RDF_CANONIZE_TRACE_URDNA2015` is truthy, it will cause
+    `console.trace()` to be called when "URDNA2015" is used. This is designed
+    for *development use only* to find where "URDNA2015" is being used. It
+    could be *very* verbose.
+
 Related Modules
 ---------------
 
@@ -127,6 +163,9 @@ Commercial support for this library is available upon request from
 
 [Digital Bazaar]: https://digitalbazaar.com/
 [JSON-LD]: https://json-ld.org/
-[RDF Dataset Canonicalization Algorithm]: https://w3c.github.io/rdf-canon/spec/
+[RDF Dataset Canonicalization]: https://w3c.github.io/rdf-canon/spec/
+[RDFC-1.0]: https://w3c.github.io/rdf-canon/spec/
+[URDNA2015]: https://w3c.github.io/rdf-canon/spec/#urdna2015
+[URGNA2012]: https://w3c.github.io/rdf-canon/spec/#urgna2012
 [jsonld.js]: https://github.com/digitalbazaar/jsonld.js
 [rdf-canonize-native]: https://github.com/digitalbazaar/rdf-canonize-native

bench-nsolid.js

@@ -75,7 +75,7 @@ const KEYS = ['subject', 'predicate', 'object', 'graph'];
     //const count = 1000000; // ~30 secs
     for(let i = 0; i < count; ++i) {
       /*const result = */await canonize(quads, {
-        algorithm: 'URDNA2015',
+        algorithm: 'RDFC-1.0',
         usePureJavaScript: true
       });
       //console.log(result);

karma.conf.js

@@ -26,7 +26,7 @@ module.exports = function(config) {
     preprocessors.push(bundler);
     preprocessors.push('sourcemap');
   } else {
-    throw Error('Unknown bundler');
+    throw new Error('Unknown bundler');
   }
 
   config.set({

lib/IdentifierIssuer.js

@@ -8,9 +8,9 @@ module.exports = class IdentifierIssuer {
    * Creates a new IdentifierIssuer. A IdentifierIssuer issues unique
    * identifiers, keeping track of any previously issued identifiers.
    *
-   * @param prefix the prefix to use ('<prefix><counter>').
-   * @param existing an existing Map to use.
-   * @param counter the counter to use.
+   * @param {string} prefix - The prefix to use ('<prefix><counter>').
+   * @param {Map} [existing] - An existing Map to use.
+   * @param {number} [counter] - The counter to use.
    */
   constructor(prefix, existing = new Map(), counter = 0) {
     this.prefix = prefix;
@@ -21,7 +21,7 @@ module.exports = class IdentifierIssuer {
   /**
    * Copies this IdentifierIssuer.
    *
-   * @return a copy of this IdentifierIssuer.
+   * @returns {object} - A copy of this IdentifierIssuer.
    */
   clone() {
     const {prefix, _existing, counter} = this;
@@ -32,9 +32,9 @@ module.exports = class IdentifierIssuer {
    * Gets the new identifier for the given old identifier, where if no old
    * identifier is given a new identifier will be generated.
    *
-   * @param [old] the old identifier to get the new identifier for.
+   * @param {string} [old] - The old identifier to get the new identifier for.
    *
-   * @return the new identifier.
+   * @returns {string} - The new identifier.
    */
   getId(old) {
     // return existing old identifier
@@ -59,10 +59,10 @@ module.exports = class IdentifierIssuer {
    * Returns true if the given old identifer has already been assigned a new
    * identifier.
    *
-   * @param old the old identifier to check.
+   * @param {string} old - The old identifier to check.
    *
-   * @return true if the old identifier has been assigned a new identifier,
-   *   false if not.
+   * @returns {boolean} - True if the old identifier has been assigned a new
+   *   identifier, false if not.
    */
   hasId(old) {
     return this._existing.has(old);
@@ -72,7 +72,8 @@ module.exports = class IdentifierIssuer {
    * Returns all of the IDs that have been issued new IDs in the order in
    * which they were issued new IDs.
    *
-   * @return the list of old IDs that has been issued new IDs in order.
+   * @returns {Array} - The list of old IDs that has been issued new IDs in
+   *   order.
    */
   getOldIds() {
     return [...this._existing.keys()];

lib/MessageDigest-webcrypto.js

@@ -9,7 +9,7 @@ module.exports = class MessageDigest {
   /**
    * Creates a new WebCrypto API MessageDigest.
    *
-   * @param algorithm the algorithm to use.
+   * @param {string} algorithm - The algorithm to use.
    */
   constructor(algorithm) {
     // check if crypto.subtle is available

lib/MessageDigest.js

@@ -9,7 +9,7 @@ module.exports = class MessageDigest {
   /**
    * Creates a new MessageDigest.
    *
-   * @param algorithm the algorithm to use.
+   * @param {string} algorithm - The algorithm to use.
    */
   constructor(algorithm) {
     this.md = crypto.createHash(algorithm);