@cosyte/dicom 0.1.6 → 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.6";
+var VERSION = "0.1.7";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -14956,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);
@@ -15020,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),
@@ -15039,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;
@@ -15507,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]);