454 refactored Encoding/Decoding logic to expose DICOM encoding mappings for consumption

.jshintrc

@@ -1,3 +1,3 @@
 {
-  "esversion": 6
+  "esversion": 11
 }

docs/BreakingChanges.md

@@ -0,0 +1,55 @@
+# Migration Guide for Breaking Changes
+
+## v 0.50.1 to higher
+
+After version 0.50.1, we introduced a breaking change to `WriteBufferStream` and `ReadBufferStream`.
+
+### What Changed
+
+- `ReadBufferStream`: Constructor signature changed from
+```js
+constructor(
+        buffer,
+        littleEndian = false,
+        options = {
+            start: null,
+            stop: null,
+            noCopy: false
+        },
+        encoding = defaultDICOMEncoding
+    )
+```
+to 
+```js
+constructor(
+    buffer,
+    options = {
+        start: null,
+        stop: null,
+        encoding: defaultDICOMEncoding,
+        noCopy: false,
+        littleEndian: true
+    }
+)
+```
+
+- `WriteBufferStream`: Constructor signature changed from
+```js
+constructor(defaultSize, options = null)
+```
+to
+```js
+constructor(options = null)
+```
+
+### Notes
+
+Essentially, the options that used to be separate parameters were moved into the flexible `options` object.
+
+For reading situations, the `littleEndian` and `encoding` options are now in that options object. Moving forward, any 
+new parameters will be introduced as options here.
+
+For writing situations, the `defaultSize` parameter was moved into the options object. 
+
+In all situations, the legacy usage of the constructor will fire a warning reminding you of the change to prompt you to 
+update your usage of the library.

src/AsyncDicomReader.js

@@ -7,16 +7,17 @@ import {
     VM_DELIMITER,
     UNDEFINED_LENGTH,
     TagHex,
-    encodingMapping,
     UNDEFINED_LENGTH_FIX,
     VALID_VRS,
+    singleVRs,
     isVideoTransferSyntax
 } from "./constants/dicom";
+import { encodingMapping } from "./constants/encodings";
 import { Tag } from "./Tag";
-import { DicomMessage, singleVRs } from "./DicomMessage";
+import { DicomMessage } from "./DicomMessage";
 import { DicomMetaDictionary } from "./DicomMetaDictionary";
 import { DicomMetadataListener } from "./utilities/DicomMetadataListener.js";
-import { log } from "./log.js";
+import { log } from "./utilities/log.js";
 
 const readLog = log.getLogger("AsyncDicomReader");
 
@@ -35,7 +36,8 @@ export class AsyncDicomReader {
         this.isLittleEndian = options?.isLittleEndian;
         // Default maxFragmentSize is 128 MB (128 * 1024 * 1024 bytes)
         this.maxFragmentSize = options?.maxFragmentSize ?? 128 * 1024 * 1024;
-        this.stream = new ReadBufferStream(null, this.isLittleEndian, {
+        this.stream = new ReadBufferStream(null, {
+            littleEncoding: this.isLittleEndian,
             clearBuffers: true,
             ...options
         });
@@ -720,13 +722,18 @@ export class AsyncDicomReader {
             }
         } else {
             const value = vr.read(stream, length, syntax)?.value;
-            if (!vr.isBinary() && singleVRs.indexOf(vr.type) == -1) {
+            if (!vr.isBinary() && !singleVRs.has(vr.type)) {
                 values = value;
                 if (typeof value === "string") {
                     const delimiterChar = String.fromCharCode(VM_DELIMITER);
                     values = vr.dropPadByte(value.split(delimiterChar));
                 }
-            } else if (vr.type == "OW" || vr.type == "OB") {
+            } else if (
+                vr.type === "OW" ||
+                vr.type === "OB" ||
+                vr.type === "OD" ||
+                vr.type === "OF"
+            ) {
                 values = value;
             } else {
                 Array.isArray(value) ? (values = value) : values.push(value);
@@ -737,9 +744,8 @@ export class AsyncDicomReader {
             if (values.length > 0) {
                 let [coding] = values;
                 coding = coding.replace(/[_ ]/g, "-").toLowerCase();
-                if (coding in encodingMapping) {
-                    coding = encodingMapping[coding];
-                    this.stream.setDecoder(new TextDecoder(coding));
+                if (encodingMapping.has(coding)) {
+                    this.stream.setEncoding(coding);
                 } else if (options?.ignoreErrors) {
                     log.warn(
                         `Unsupported character set: ${coding}, using default character set`

src/BufferStream.js

@@ -2,11 +2,14 @@ import pako from "pako";
 import SplitDataView from "./SplitDataView";
 import { toFloat } from "./utilities/toFloat";
 import { toInt } from "./utilities/toInt";
+import { DicomTextTranscode } from "./DicomTextTranscode";
+import { defaultDICOMEncoding } from "./constants/encodings";
+import { log } from "./utilities/log";
 
 export class BufferStream {
     offset = 0;
     startOffset = 0;
-    isLittleEndian = false;
+    isLittleEndian = true;
     size = 0;
     view = new SplitDataView();
     /** The available listeners are those waiting for a query response */
@@ -18,12 +21,14 @@ export class BufferStream {
     /** A flag to set to indicate to clear buffers as they get consumed */
     clearBuffers = false;
 
-    encoder = new TextEncoder("utf-8");
+    textTranscoder = new DicomTextTranscode();
 
     constructor(options = null) {
-        this.isLittleEndian = options?.littleEndian || this.isLittleEndian;
+        this.isLittleEndian = options?.littleEndian ?? this.isLittleEndian;
         this.view.defaultSize = options?.defaultSize ?? this.view.defaultSize;
-        this.clearBuffers = options.clearBuffers || false;
+        this.clearBuffers = options?.clearBuffers || false;
+
+        this.setEncoding(options?.encoding || defaultDICOMEncoding);
     }
 
     /**
@@ -68,8 +73,20 @@ export class BufferStream {
         return true;
     }
 
-    setEndian(isLittle) {
-        this.isLittleEndian = isLittle;
+    setEncoding(dicomEncoding, ignoreErrors) {
+        this.textTranscoder.setEncoding(dicomEncoding, ignoreErrors);
+    }
+
+    setEndian(isLittleEndian = true) {
+        this.isLittleEndian = isLittleEndian;
+    }
+
+    setLittleEndian() {
+        this.isLittleEndian = true;
+    }
+
+    setBigEndian() {
+        this.isLittleEndian = false;
     }
 
     slice(start = this.startOffset, end = this.endOffset) {
@@ -175,7 +192,7 @@ export class BufferStream {
     }
 
     writeUTF8String(value) {
-        const encodedString = this.encoder.encode(value);
+        const encodedString = this.textTranscoder.encode(value);
         this.checkSize(encodedString.byteLength);
         this.view.writeBuffer(encodedString, this.offset);
         return this.increment(encodedString.byteLength);
@@ -312,7 +329,7 @@ export class BufferStream {
         const view = new DataView(
             this.slice(this.offset, this.offset + length)
         );
-        const result = this.decoder.decode(view);
+        const result = this.textTranscoder.decode(view);
         this.increment(length);
         return result;
     }
@@ -465,35 +482,49 @@ export class BufferStream {
 export class ReadBufferStream extends BufferStream {
     constructor(
         buffer,
-        littleEndian,
         options = {
             start: null,
             stop: null,
-            noCopy: false
+            encoding: defaultDICOMEncoding,
+            noCopy: false,
+            littleEndian: true
         }
     ) {
-        super({ ...options, littleEndian });
-        this.noCopy = options.noCopy;
-        this.decoder = new TextDecoder("latin1");
+        options instanceof Object
+            ? {}
+            : log.warn(
+                  "The constructor API for ReadBufferStream has changed to include the" +
+                      " littleEndian option as part of the options object. Please, update your usage of the class. We are " +
+                      "using defaults now. See docs/BreakingChanges.md for more details."
+              );
+        const optionsOptions =
+            options instanceof Object
+                ? options
+                : {
+                      start: null,
+                      stop: null,
+                      encoding: defaultDICOMEncoding,
+                      noCopy: false,
+                      littleEndian: options
+                  };
+        super(optionsOptions);
+        this.noCopy = optionsOptions.noCopy;
 
         if (buffer instanceof BufferStream) {
-            this.view.from(buffer.view, options);
+            this.view.from(buffer.view, optionsOptions);
             this.isComplete = true;
         } else if (buffer) {
             this.view.addBuffer(buffer);
             this.isComplete = true;
         }
-        this.offset = options.start ?? buffer?.offset ?? 0;
-        this.size = options.stop || buffer?.size || buffer?.byteLength || 0;
+        this.offset = optionsOptions.start ?? buffer?.offset ?? 0;
+        this.size =
+            optionsOptions.stop || buffer?.size || buffer?.byteLength || 0;
 
         this.startOffset = this.offset;
         this.endOffset = this.size;
     }
 
-    setDecoder(decoder) {
-        this.decoder = decoder;
-    }
-
     reset() {
         this.offset = this.startOffset;
         return this;
@@ -571,13 +602,30 @@ export class DeflatedReadBufferStream extends ReadBufferStream {
         const inflatedBuffer = pako.inflateRaw(
             stream.getBuffer(stream.offset, stream.size)
         );
-        super(inflatedBuffer.buffer, stream.littleEndian, options);
+        super(inflatedBuffer.buffer, {
+            littleEndian: stream.littleEndian,
+            ...options
+        });
     }
 }
 
 export class WriteBufferStream extends BufferStream {
-    constructor(defaultSize, littleEndian) {
-        super({ defaultSize, littleEndian });
+    constructor(options = null) {
+        options instanceof Object
+            ? {}
+            : log.warn(
+                  "The constructor API for WriteBufferStream has changed to include the" +
+                      " littleEndian option as part of the options object. Please, update your usage of the class. We are " +
+                      "using defaults now. See docs/BreakingChanges.md for more details."
+              );
+        const optionsOptions =
+            options instanceof Object
+                ? options
+                : {
+                      encoding: defaultDICOMEncoding,
+                      littleEndian: options
+                  };
+        super(optionsOptions);
         this.size = 0;
     }
 }

src/DicomDict.js

@@ -22,13 +22,24 @@ class DicomDict {
         }
     }
 
-    write(writeOptions = { allowInvalidVRLength: false }) {
-        var metaSyntax = EXPLICIT_LITTLE_ENDIAN;
-        var fileStream = new WriteBufferStream(4096, true);
+    write(
+        writeOptions = {
+            allowInvalidVRLength: false
+        }
+    ) {
+        const metaSyntax = EXPLICIT_LITTLE_ENDIAN;
+        const fileStream = new WriteBufferStream({
+            defaultSize: 4096,
+            littleEndian: writeOptions.littleEndian
+        });
+
         fileStream.writeUint8Repeat(0, 128);
         fileStream.writeAsciiString("DICM");
 
-        var metaStream = new WriteBufferStream(1024);
+        const metaStream = new WriteBufferStream({
+            defaultSize: 1024,
+            littleEndian: writeOptions.littleEndian
+        });
         if (!this.meta[TagHex.TransferSyntaxUID]) {
             this.meta[TagHex.TransferSyntaxUID] = {
                 vr: "UI",
@@ -46,7 +57,7 @@ class DicomDict {
         );
         fileStream.concat(metaStream);
 
-        var useSyntax = this.meta[TagHex.TransferSyntaxUID].Value[0];
+        const useSyntax = this.meta[TagHex.TransferSyntaxUID].Value[0];
         DicomMessage.write(this.dict, fileStream, useSyntax, writeOptions);
         return fileStream.getBuffer();
     }