@cosyte/dicom 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -2794,7 +2794,11 @@ declare class DicomValueError extends Error {
  *   carries an offset that is not zero and names no Directory Record the
  *   `Dataset` holds, or is not one 32-bit unsigned integer (never written stale
  *   or as zero), or `DIRECTORY_OFFSET_DEFLATED` when a DICOMDIR under Deflated
- *   Explicit VR LE carries a non-zero offset. Nothing is returned on a throw.
+ *   Explicit VR LE carries a non-zero offset, or `VALUE_TOO_LONG_FOR_VR` when a
+ *   Private Creator Data Element under an Explicit VR syntax, or a File Meta
+ *   Information element under any, has a value past 65,534 bytes in a VR with a
+ *   16-bit Value Length Field (PS3.5 2026c section 6.2.2 forbids the `UN` such a
+ *   value is otherwise written as). Nothing is returned on a throw.
  *
  * @example
  * ```ts
@@ -2849,6 +2853,13 @@ declare function serializeDicom(ds: Dataset): Buffer;
  *     not one 32-bit unsigned integer). A position inside a deflated stream
  *     names no Item a reader can seek to, so no offset can be written for it.
  *     A Deflated DICOMDIR whose offsets are all zero is written.
+ *   - `VALUE_TOO_LONG_FOR_VR` - a Private Creator Data Element `(gggg,00xx)`
+ *     under an Explicit VR Transfer Syntax, or a File Meta Information element
+ *     `(0002,xxxx)` under any, carries a value longer than 65,534 bytes in a VR
+ *     whose Explicit VR Value Length Field is 16 bits. PS3.5 2026c section 6.2.2
+ *     has such a value written with VR `UN`, which the writer does for every
+ *     other element, but says the `UN` VR "shall not be used" for these two, so
+ *     the value has no encoding and nothing is written.
  *
  * The message is built only from structural constants (never a decoded
  * attribute value, a Transfer Syntax UID, or a length or byte read from the
@@ -2872,6 +2883,7 @@ declare const SERIALIZE_ERROR_CODES: {
     readonly INVALID_ENCAPSULATED_PIXEL_DATA: "INVALID_ENCAPSULATED_PIXEL_DATA";
     readonly DIRECTORY_OFFSET_UNRESOLVED: "DIRECTORY_OFFSET_UNRESOLVED";
     readonly DIRECTORY_OFFSET_DEFLATED: "DIRECTORY_OFFSET_DEFLATED";
+    readonly VALUE_TOO_LONG_FOR_VR: "VALUE_TOO_LONG_FOR_VR";
 };
 /**
  * Discriminant for {@link DicomSerializeError.code}, enabling exhaustive
@@ -2892,6 +2904,8 @@ declare const SERIALIZE_ERROR_CODES: {
  *       return "a DICOMDIR offset names no Directory Record the dataset holds";
  *     case "DIRECTORY_OFFSET_DEFLATED":
  *       return "a Deflated DICOMDIR carries a non-zero Directory Record offset";
+ *     case "VALUE_TOO_LONG_FOR_VR":
+ *       return "a Private Creator or File Meta value is too long for its VR";
  *   }
  * }
  * ```
@@ -2920,6 +2934,9 @@ type SerializeErrorCode = (typeof SERIALIZE_ERROR_CODES)[keyof typeof SERIALIZE_
  *   if (err instanceof DicomSerializeError && err.code === "DIRECTORY_OFFSET_UNRESOLVED") {
  *     // a DICOMDIR offset the writer cannot tie to a Directory Record
  *   }
+ *   if (err instanceof DicomSerializeError && err.code === "VALUE_TOO_LONG_FOR_VR") {
+ *     // a Private Creator or File Meta value past 65,534 bytes, which UN may not carry
+ *   }
  * }
  * ```
  */
@@ -4679,6 +4696,13 @@ declare class DeidentifyError extends Error {
  * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option,
  *   for both PS3.15 §E.3.6 temporal Options in one call, or for a malformed
  *   `uidRoot`.
+ * @throws `DicomSerializeError` (`VALUE_TOO_LONG_FOR_VR`) when the run
+ *   re-encodes a Sequence Item, under an Explicit VR syntax, that keeps a Private
+ *   Creator Data Element whose value is longer than 65,534 bytes. Only a
+ *   `RetainSafePrivate` run whose `Profile` names a creator that long keeps one;
+ *   PS3.5 2026c section 6.2.2 forbids the `UN` such a value is otherwise written
+ *   as, so the Item has no encoding. The same element at the root is returned,
+ *   and `serializeDicom` refuses it with the same code.
  *
  * @example
  * ```ts

package/dist/index.d.ts

@@ -2794,7 +2794,11 @@ declare class DicomValueError extends Error {
  *   carries an offset that is not zero and names no Directory Record the
  *   `Dataset` holds, or is not one 32-bit unsigned integer (never written stale
  *   or as zero), or `DIRECTORY_OFFSET_DEFLATED` when a DICOMDIR under Deflated
- *   Explicit VR LE carries a non-zero offset. Nothing is returned on a throw.
+ *   Explicit VR LE carries a non-zero offset, or `VALUE_TOO_LONG_FOR_VR` when a
+ *   Private Creator Data Element under an Explicit VR syntax, or a File Meta
+ *   Information element under any, has a value past 65,534 bytes in a VR with a
+ *   16-bit Value Length Field (PS3.5 2026c section 6.2.2 forbids the `UN` such a
+ *   value is otherwise written as). Nothing is returned on a throw.
  *
  * @example
  * ```ts
@@ -2849,6 +2853,13 @@ declare function serializeDicom(ds: Dataset): Buffer;
  *     not one 32-bit unsigned integer). A position inside a deflated stream
  *     names no Item a reader can seek to, so no offset can be written for it.
  *     A Deflated DICOMDIR whose offsets are all zero is written.
+ *   - `VALUE_TOO_LONG_FOR_VR` - a Private Creator Data Element `(gggg,00xx)`
+ *     under an Explicit VR Transfer Syntax, or a File Meta Information element
+ *     `(0002,xxxx)` under any, carries a value longer than 65,534 bytes in a VR
+ *     whose Explicit VR Value Length Field is 16 bits. PS3.5 2026c section 6.2.2
+ *     has such a value written with VR `UN`, which the writer does for every
+ *     other element, but says the `UN` VR "shall not be used" for these two, so
+ *     the value has no encoding and nothing is written.
  *
  * The message is built only from structural constants (never a decoded
  * attribute value, a Transfer Syntax UID, or a length or byte read from the
@@ -2872,6 +2883,7 @@ declare const SERIALIZE_ERROR_CODES: {
     readonly INVALID_ENCAPSULATED_PIXEL_DATA: "INVALID_ENCAPSULATED_PIXEL_DATA";
     readonly DIRECTORY_OFFSET_UNRESOLVED: "DIRECTORY_OFFSET_UNRESOLVED";
     readonly DIRECTORY_OFFSET_DEFLATED: "DIRECTORY_OFFSET_DEFLATED";
+    readonly VALUE_TOO_LONG_FOR_VR: "VALUE_TOO_LONG_FOR_VR";
 };
 /**
  * Discriminant for {@link DicomSerializeError.code}, enabling exhaustive
@@ -2892,6 +2904,8 @@ declare const SERIALIZE_ERROR_CODES: {
  *       return "a DICOMDIR offset names no Directory Record the dataset holds";
  *     case "DIRECTORY_OFFSET_DEFLATED":
  *       return "a Deflated DICOMDIR carries a non-zero Directory Record offset";
+ *     case "VALUE_TOO_LONG_FOR_VR":
+ *       return "a Private Creator or File Meta value is too long for its VR";
  *   }
  * }
  * ```
@@ -2920,6 +2934,9 @@ type SerializeErrorCode = (typeof SERIALIZE_ERROR_CODES)[keyof typeof SERIALIZE_
  *   if (err instanceof DicomSerializeError && err.code === "DIRECTORY_OFFSET_UNRESOLVED") {
  *     // a DICOMDIR offset the writer cannot tie to a Directory Record
  *   }
+ *   if (err instanceof DicomSerializeError && err.code === "VALUE_TOO_LONG_FOR_VR") {
+ *     // a Private Creator or File Meta value past 65,534 bytes, which UN may not carry
+ *   }
  * }
  * ```
  */
@@ -4679,6 +4696,13 @@ declare class DeidentifyError extends Error {
  * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option,
  *   for both PS3.15 §E.3.6 temporal Options in one call, or for a malformed
  *   `uidRoot`.
+ * @throws `DicomSerializeError` (`VALUE_TOO_LONG_FOR_VR`) when the run
+ *   re-encodes a Sequence Item, under an Explicit VR syntax, that keeps a Private
+ *   Creator Data Element whose value is longer than 65,534 bytes. Only a
+ *   `RetainSafePrivate` run whose `Profile` names a creator that long keeps one;
+ *   PS3.5 2026c section 6.2.2 forbids the `UN` such a value is otherwise written
+ *   as, so the Item has no encoding. The same element at the root is returned,
+ *   and `serializeDicom` refuses it with the same code.
  *
  * @example
  * ```ts

package/dist/index.mjs

@@ -9,7 +9,7 @@ var __export = (target, all) => {
 };
 
 // src/version.ts
-var VERSION = "0.1.5";
+var VERSION = "0.1.7";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -11139,8 +11139,24 @@ function directoryRecords(source) {
 }
 function csValues(el) {
   if (el === void 0) return void 0;
-  const text = el.rawBytes.toString("latin1").replace(/[\0 ]+$/u, "");
-  return Object.freeze(text === "" ? [] : text.split("\\").map((v) => v.replace(/^ +| +$/gu, "")));
+  const text = stripTrailingPad(el.rawBytes.toString("latin1"));
+  return Object.freeze(text === "" ? [] : text.split("\\").map(trimSpaces));
+}
+function stripTrailingPad(text) {
+  let end = text.length;
+  while (end > 0) {
+    const code = text.charCodeAt(end - 1);
+    if (code !== 0 && code !== 32) break;
+    end--;
+  }
+  return text.slice(0, end);
+}
+function trimSpaces(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value.charCodeAt(start) === 32) start++;
+  while (end > start && value.charCodeAt(end - 1) === 32) end--;
+  return value.slice(start, end);
 }
 function analyzeDirectory(source) {
   if (!isDicomdir(source.fileMeta)) return void 0;
@@ -13799,7 +13815,7 @@ function stripPad(bytes, tag, vr, position, warnings) {
   }
   return bytes.subarray(0, end);
 }
-function trimSpaces(value) {
+function trimSpaces2(value) {
   let start = 0;
   let end = value.length;
   while (start < end && value.charCodeAt(start) === SPACE2) start++;
@@ -13858,7 +13874,7 @@ function decodeElementValue(element) {
   }
   if (vr === "LO" || vr === "SH" || vr === "UC") {
     const text = decodeCharsetString(trimmed, tag, vr, charset, position, warnings);
-    const values = text.split("\\").map(trimSpaces);
+    const values = text.split("\\").map(trimSpaces2);
     return attachWarnings({ kind: "strings", values }, warnings);
   }
   if (vr === "LT" || vr === "ST" || vr === "UT") {
@@ -13871,7 +13887,7 @@ function decodeElementValue(element) {
   }
   if (vr === "AE" || vr === "CS" || vr === "AS" || vr === "UI") {
     const text = decodeAsciiString(trimmed, tag, vr, position, warnings);
-    const values = text.split("\\").map(trimSpaces);
+    const values = text.split("\\").map(trimSpaces2);
     return attachWarnings({ kind: "strings", values }, warnings);
   }
   if (vr === "DS") {
@@ -14940,8 +14956,43 @@ function toDate(value, options) {
   const instant = new Date(utc.getTime() - offsetMinutes * 6e4);
   return Number.isNaN(instant.getTime()) ? void 0 : instant;
 }
+
+// src/serialize/errors.ts
+var SERIALIZE_ERROR_CODES = {
+  MISSING_TRANSFER_SYNTAX: "MISSING_TRANSFER_SYNTAX",
+  UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX",
+  INVALID_ENCAPSULATED_PIXEL_DATA: "INVALID_ENCAPSULATED_PIXEL_DATA",
+  DIRECTORY_OFFSET_UNRESOLVED: "DIRECTORY_OFFSET_UNRESOLVED",
+  DIRECTORY_OFFSET_DEFLATED: "DIRECTORY_OFFSET_DEFLATED",
+  VALUE_TOO_LONG_FOR_VR: "VALUE_TOO_LONG_FOR_VR"
+};
+var DicomSerializeError = class extends Error {
+  code;
+  /**
+   * Construct a new `DicomSerializeError`. The `message` MUST be built only
+   * from structural facts (never a decoded attribute value) so the error is
+   * always safe to log.
+   *
+   * @internal
+   */
+  constructor(code, message) {
+    super(`[${code}] ${message}`);
+    this.name = "DicomSerializeError";
+    this.code = code;
+  }
+};
+
+// src/serialize/element.ts
 var UNDEFINED_LENGTH4 = 4294967295;
 var MAX_SHORT_FORM_LENGTH = 65534;
+var PRIVATE_CREATOR_TOO_LONG_MESSAGE = "A Private Creator Data Element carries a value longer than 65,534 bytes under an Explicit VR Transfer Syntax, in a VR whose Value Length Field is 16 bits. PS3.5 section 6.2.2 has such a value written with VR UN, but says UN shall not be used for a Private Creator Data Element, so the value has no encoding and nothing is written.";
+var FILE_META_TOO_LONG_MESSAGE = "A File Meta Information element carries a value longer than 65,534 bytes in a VR whose Explicit VR Value Length Field is 16 bits. PS3.5 section 6.2.2 has such a value written with VR UN, but says UN shall not be used for a File Meta Information element, so the value has no encoding and nothing is written.";
+function refuseTooLongForVr(kind) {
+  throw new DicomSerializeError(
+    SERIALIZE_ERROR_CODES.VALUE_TOO_LONG_FOR_VR,
+    kind === "privateCreator" ? PRIVATE_CREATOR_TOO_LONG_MESSAGE : FILE_META_TOO_LONG_MESSAGE
+  );
+}
 var NULL_PAD_VRS = /* @__PURE__ */ new Set(["UI", "OB", "OW", "OF", "OD", "OL", "OV", "UN"]);
 function padValue(value, vr) {
   if (value.length % 2 === 0) return Buffer.from(value);
@@ -15004,7 +15055,9 @@ function encodeDatasetElement(el, encoding, rawBytes = el.rawBytes) {
       value
     ]);
   }
-  if (value.length > MAX_SHORT_FORM_LENGTH && !isPrivateCreator(group, element)) {
+  if (value.length > MAX_SHORT_FORM_LENGTH) {
+    if (isPrivateCreator(group, element)) refuseTooLongForVr("privateCreator");
+    if (group === 2) refuseTooLongForVr("fileMeta");
     return Buffer.concat([
       uint16(group, littleEndian),
       uint16(element, littleEndian),
@@ -15023,30 +15076,6 @@ function encodeDatasetElement(el, encoding, rawBytes = el.rawBytes) {
     value
   ]);
 }
-
-// src/serialize/errors.ts
-var SERIALIZE_ERROR_CODES = {
-  MISSING_TRANSFER_SYNTAX: "MISSING_TRANSFER_SYNTAX",
-  UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX",
-  INVALID_ENCAPSULATED_PIXEL_DATA: "INVALID_ENCAPSULATED_PIXEL_DATA",
-  DIRECTORY_OFFSET_UNRESOLVED: "DIRECTORY_OFFSET_UNRESOLVED",
-  DIRECTORY_OFFSET_DEFLATED: "DIRECTORY_OFFSET_DEFLATED"
-};
-var DicomSerializeError = class extends Error {
-  code;
-  /**
-   * Construct a new `DicomSerializeError`. The `message` MUST be built only
-   * from structural facts (never a decoded attribute value) so the error is
-   * always safe to log.
-   *
-   * @internal
-   */
-  constructor(code, message) {
-    super(`[${code}] ${message}`);
-    this.name = "DicomSerializeError";
-    this.code = code;
-  }
-};
 var UNDEFINED_LENGTH5 = 4294967295;
 var ITEM2 = 4294893568;
 var ITEM_DELIMITATION = 4294893581;
@@ -15491,6 +15520,7 @@ function encodeMetaElement(tag, vr, rawValue) {
       value
     ]);
   }
+  if (value.length > MAX_SHORT_FORM_LENGTH) refuseTooLongForVr("fileMeta");
   const lengthBuf = Buffer.alloc(2);
   lengthBuf.writeUInt16LE(value.length, 0);
   return Buffer.concat([groupBuf, elementBuf, vrBuf, lengthBuf, value]);
@@ -16764,14 +16794,19 @@ function dummyBytes(vr) {
   const buf = Buffer.from(text, "latin1");
   return buf.length % 2 === 0 ? buf : Buffer.concat([buf, Buffer.from([32])]);
 }
+function stripTrailingNulls(text) {
+  let end = text.length;
+  while (end > 0 && text.charCodeAt(end - 1) === 0) end--;
+  return text.slice(0, end);
+}
 function remapUidBytes(rawBytes, remap) {
-  const raw = rawBytes.toString("latin1").replace(/\0+$/, "");
+  const raw = stripTrailingNulls(rawBytes.toString("latin1"));
   const remapped = raw.split("\\").map((uid2) => remap(uid2.trim())).join("\\");
   const buf = Buffer.from(remapped, "latin1");
   return buf.length % 2 === 0 ? buf : Buffer.concat([buf, Buffer.from([0])]);
 }
 function uidValueMultiplicity(rawBytes) {
-  const raw = rawBytes.toString("latin1").replace(/\0+$/, "");
+  const raw = stripTrailingNulls(rawBytes.toString("latin1"));
   if (raw.length === 0) return 0;
   return raw.split("\\").length;
 }
@@ -17173,7 +17208,7 @@ function insertedSequence(tag, items, encoding) {
   });
 }
 function decodeCreator(el) {
-  return el.rawBytes.toString("latin1").replace(/[\0 ]+$/, "").trim();
+  return trimTrailingPad(el.rawBytes).toString("latin1").trim();
 }
 function isPrivateCreatorElement(tag) {
   const { element } = splitTag(tag);
@@ -17301,7 +17336,7 @@ function declarationKey(group, creator) {
   return `${String(group)}:${creator}`;
 }
 function decodeEnumerated(el) {
-  return el.rawBytes.toString("latin1").replace(/[\0 ]+$/, "").trim();
+  return trimTrailingPad(el.rawBytes).toString("latin1").trim();
 }
 function readUnsignedShorts(el) {
   const values = [];
@@ -17738,7 +17773,7 @@ function hasUncleanedBurnedIn(ds) {
   if (!ds.has(TAG_PIXEL_DATA)) return false;
   const flag = ds.get(TAG_BURNED_IN_ANNOTATION);
   if (flag === void 0) return true;
-  return flag.rawBytes.toString("latin1").replace(/[\0 ]+$/, "").trim().toUpperCase() !== "NO";
+  return trimTrailingPad(flag.rawBytes).toString("latin1").trim().toUpperCase() !== "NO";
 }
 function deidentify(ds, options = {}) {
   if (isRefusedTransferSyntax(ds.fileMeta?.transferSyntaxUID)) {