@ubercode/dcmtk 0.1.1 → 0.2.0

package/dist/dicom.js

@@ -1,11 +1,11 @@
 import { normalize, join } from 'path';
 import { stderr, tryCatch } from 'stderr-lib';
-import { copyFile, unlink, stat } from 'fs/promises';
-import { z } from 'zod';
 import { spawn, execSync } from 'child_process';
 import kill from 'tree-kill';
 import { existsSync } from 'fs';
+import { z } from 'zod';
 import { XMLParser } from 'fast-xml-parser';
+import { copyFile, unlink, stat } from 'fs/promises';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -30123,6 +30123,18 @@ function buildMergedModifications(base, other, erasures) {
   }
   return merged;
 }
+function applyBatchEntries(initial, entries) {
+  const keys = Object.keys(entries);
+  let cs = initial;
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (key === void 0) continue;
+    const value = entries[key];
+    if (value === void 0) continue;
+    cs = cs.setTag(key, value);
+  }
+  return cs;
+}
 var ChangeSet = class _ChangeSet {
   constructor(mods, erasures) {
     __publicField(this, "mods");
@@ -30140,7 +30152,7 @@ var ChangeSet = class _ChangeSet {
    * Control characters (except LF/CR) are stripped from the value.
    * If the tag was previously erased, it is removed from the erasure set.
    *
-   * @param path - The DICOM tag path to set
+   * @param path - The DICOM tag path to set (e.g. `'(0010,0010)'`)
    * @param value - The new value for the tag
    * @returns A new ChangeSet with the modification applied
    * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
@@ -30163,7 +30175,7 @@ var ChangeSet = class _ChangeSet {
    *
    * If the tag was previously set, the modification is removed.
    *
-   * @param path - The DICOM tag path to erase
+   * @param path - The DICOM tag path to erase (e.g. `'(0010,0010)'`)
    * @returns A new ChangeSet with the erasure applied
    * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
    */
@@ -30194,6 +30206,50 @@ var ChangeSet = class _ChangeSet {
     newErasures.add(ERASE_PRIVATE_SENTINEL);
     return new _ChangeSet(new Map(this.mods), newErasures);
   }
+  // -----------------------------------------------------------------------
+  // Convenience setters for common DICOM tags
+  // -----------------------------------------------------------------------
+  /** Sets Patient's Name (0010,0010). */
+  setPatientName(value) {
+    return this.setTag("(0010,0010)", value);
+  }
+  /** Sets Patient ID (0010,0020). */
+  setPatientID(value) {
+    return this.setTag("(0010,0020)", value);
+  }
+  /** Sets Study Date (0008,0020). */
+  setStudyDate(value) {
+    return this.setTag("(0008,0020)", value);
+  }
+  /** Sets Modality (0008,0060). */
+  setModality(value) {
+    return this.setTag("(0008,0060)", value);
+  }
+  /** Sets Accession Number (0008,0050). */
+  setAccessionNumber(value) {
+    return this.setTag("(0008,0050)", value);
+  }
+  /** Sets Study Description (0008,1030). */
+  setStudyDescription(value) {
+    return this.setTag("(0008,1030)", value);
+  }
+  /** Sets Series Description (0008,103E). */
+  setSeriesDescription(value) {
+    return this.setTag("(0008,103E)", value);
+  }
+  /** Sets Institution Name (0008,0080). */
+  setInstitutionName(value) {
+    return this.setTag("(0008,0080)", value);
+  }
+  /**
+   * Sets multiple tags at once, returning a new ChangeSet.
+   *
+   * @param entries - A record of tag path → value pairs
+   * @returns A new ChangeSet with all modifications applied
+   */
+  setBatch(entries) {
+    return applyBatchEntries(this, entries);
+  }
   /** All pending tag modifications as a readonly map of path → value. */
   get modifications() {
     return this.mods;
@@ -30724,7 +30780,8 @@ var DcmodifyOptionsSchema = z.object({
   erasures: z.array(z.string()).optional(),
   erasePrivateTags: z.boolean().optional(),
   noBackup: z.boolean().optional(),
-  insertIfMissing: z.boolean().optional()
+  insertIfMissing: z.boolean().optional(),
+  ignoreMissingTags: z.boolean().optional()
 }).strict().refine((data) => data.modifications.length > 0 || data.erasures !== void 0 && data.erasures.length > 0 || data.erasePrivateTags === true, {
   message: "At least one of modifications, erasures, or erasePrivateTags is required"
 });
@@ -30733,6 +30790,9 @@ function buildArgs(inputPath, options) {
   if (options.noBackup !== false) {
     args.push("-nb");
   }
+  if (options.ignoreMissingTags === true) {
+    args.push("-imt");
+  }
   const flag = options.insertIfMissing === true ? "-i" : "-m";
   const modifications = options.modifications ?? [];
   for (const mod of modifications) {
@@ -30752,7 +30812,7 @@ function buildArgs(inputPath, options) {
 async function dcmodify(inputPath, options) {
   const validation = DcmodifyOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmodify: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmodify", validation.error));
   }
   const binaryResult = resolveBinary("dcmodify");
   if (!binaryResult.ok) {
@@ -30772,16 +30832,16 @@ async function dcmodify(inputPath, options) {
   }
   return ok({ filePath: inputPath });
 }
-
-// src/dicom/DicomFile.ts
 async function applyModifications(filePath, changeset, options) {
   const modifications = changeset.toModifications();
   const erasures = changeset.toErasureArgs();
+  const hasErasures = erasures.length > 0 || changeset.erasePrivate;
   const result = await dcmodify(filePath, {
     modifications: modifications.length > 0 ? modifications : void 0,
     erasures: erasures.length > 0 ? erasures : void 0,
     erasePrivateTags: changeset.erasePrivate || void 0,
     insertIfMissing: true,
+    ignoreMissingTags: hasErasures || void 0,
     timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     signal: options.signal
   });
@@ -30806,24 +30866,28 @@ async function unlinkFile(path) {
     (e) => new Error(`Failed to delete file: ${e.message}`)
   );
 }
-var DicomFile = class _DicomFile {
-  constructor(dataset, filePath, changes) {
-    /** The immutable DICOM dataset read from the file. */
-    __publicField(this, "dataset");
-    /** The branded file path. */
-    __publicField(this, "filePath");
-    /** The accumulated pending changes. */
-    __publicField(this, "changes");
-    this.dataset = dataset;
-    this.filePath = filePath;
-    this.changes = changes;
+
+// src/dicom/DicomInstance.ts
+var DicomInstance = class _DicomInstance {
+  constructor(dataset, changes, filePath, metadata) {
+    __publicField(this, "dicomDataset");
+    __publicField(this, "changeSet");
+    __publicField(this, "filepath");
+    __publicField(this, "meta");
+    this.dicomDataset = dataset;
+    this.changeSet = changes;
+    this.filepath = filePath;
+    this.meta = metadata;
   }
+  // -----------------------------------------------------------------------
+  // Factories
+  // -----------------------------------------------------------------------
   /**
-   * Opens a DICOM file and reads its dataset.
+   * Opens a DICOM file and creates a DicomInstance.
    *
    * @param path - Filesystem path to the DICOM file
    * @param options - Timeout and abort options
-   * @returns A Result containing the DicomFile or an error
+   * @returns A Result containing the DicomInstance or an error
    */
   static async open(path, options) {
     const filePathResult = createDicomFilePath(path);
@@ -30835,64 +30899,250 @@ var DicomFile = class _DicomFile {
     if (!jsonResult.ok) return err(jsonResult.error);
     const datasetResult = DicomDataset.fromJson(jsonResult.value.data);
     if (!datasetResult.ok) return err(datasetResult.error);
-    return ok(new _DicomFile(datasetResult.value, filePathResult.value, ChangeSet.empty()));
+    return ok(new _DicomInstance(datasetResult.value, ChangeSet.empty(), filePathResult.value, /* @__PURE__ */ new Map()));
   }
   /**
-   * Returns a new DicomFile with the given changes merged into the pending changes.
+   * Creates a DicomInstance from an existing DicomDataset.
+   *
+   * @param dataset - The DicomDataset to wrap
+   * @param filePath - Optional file path (e.g. if the dataset came from a file)
+   * @returns A Result containing the DicomInstance
+   */
+  static fromDataset(dataset, filePath) {
+    let fp;
+    if (filePath !== void 0) {
+      const fpResult = createDicomFilePath(filePath);
+      if (!fpResult.ok) return err(fpResult.error);
+      fp = fpResult.value;
+    }
+    return ok(new _DicomInstance(dataset, ChangeSet.empty(), fp, /* @__PURE__ */ new Map()));
+  }
+  // -----------------------------------------------------------------------
+  // Read accessors (delegate to DicomDataset)
+  // -----------------------------------------------------------------------
+  /** The underlying immutable DICOM dataset. */
+  get dataset() {
+    return this.dicomDataset;
+  }
+  /** The pending change set. */
+  get changes() {
+    return this.changeSet;
+  }
+  /** Whether there are unsaved changes. */
+  get hasUnsavedChanges() {
+    return !this.changeSet.isEmpty;
+  }
+  /** The file path, or undefined if this instance has no associated file. */
+  get filePath() {
+    return this.filepath;
+  }
+  /** Patient's Name (0010,0010). */
+  get patientName() {
+    return this.dicomDataset.patientName;
+  }
+  /** Patient ID (0010,0020). */
+  get patientID() {
+    return this.dicomDataset.patientID;
+  }
+  /** Study Date (0008,0020). */
+  get studyDate() {
+    return this.dicomDataset.studyDate;
+  }
+  /** Modality (0008,0060). */
+  get modality() {
+    return this.dicomDataset.modality;
+  }
+  /** Accession Number (0008,0050). */
+  get accession() {
+    return this.dicomDataset.accession;
+  }
+  /** SOP Class UID (0008,0016). */
+  get sopClassUID() {
+    return this.dicomDataset.sopClassUID;
+  }
+  /** Study Instance UID (0020,000D). */
+  get studyInstanceUID() {
+    return this.dicomDataset.studyInstanceUID;
+  }
+  /** Series Instance UID (0020,000E). */
+  get seriesInstanceUID() {
+    return this.dicomDataset.seriesInstanceUID;
+  }
+  /** SOP Instance UID (0008,0018). */
+  get sopInstanceUID() {
+    return this.dicomDataset.sopInstanceUID;
+  }
+  /** Transfer Syntax UID (0002,0010). */
+  get transferSyntaxUID() {
+    return this.dicomDataset.transferSyntaxUID;
+  }
+  /**
+   * Gets a tag value as a string with optional fallback.
+   *
+   * @param tag - A DICOM tag, e.g. `'(0010,0010)'` or `'00100010'`
+   * @param fallback - Value to return if tag is missing (default: `''`)
+   */
+  getString(tag, fallback = "") {
+    return this.dicomDataset.getString(tag, fallback);
+  }
+  /**
+   * Gets a tag value as a number.
+   *
+   * @param tag - A DICOM tag, e.g. `'(0020,0013)'`
+   */
+  getNumber(tag) {
+    return this.dicomDataset.getNumber(tag);
+  }
+  /** Checks whether a tag exists in the dataset. */
+  hasTag(tag) {
+    return this.dicomDataset.hasTag(tag);
+  }
+  /**
+   * Finds all values matching a wildcard path.
+   *
+   * @param path - A DicomTagPath with optional wildcard indices
+   */
+  findValues(path) {
+    return this.dicomDataset.findValues(path);
+  }
+  // -----------------------------------------------------------------------
+  // Write methods (return new instance)
+  // -----------------------------------------------------------------------
+  /**
+   * Sets a tag value, returning a new DicomInstance.
+   *
+   * @param path - The DICOM tag path (e.g. `'(0010,0010)'`)
+   * @param value - The new value
+   */
+  setTag(path, value) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.setTag(path, value), this.filepath, this.meta);
+  }
+  /**
+   * Erases a tag, returning a new DicomInstance.
+   *
+   * @param path - The DICOM tag path to erase
+   */
+  eraseTag(path) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.eraseTag(path), this.filepath, this.meta);
+  }
+  /** Erases all private tags, returning a new DicomInstance. */
+  erasePrivateTags() {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.erasePrivateTags(), this.filepath, this.meta);
+  }
+  /** Sets Patient's Name (0010,0010). */
+  setPatientName(value) {
+    return this.setTag("(0010,0010)", value);
+  }
+  /** Sets Patient ID (0010,0020). */
+  setPatientID(value) {
+    return this.setTag("(0010,0020)", value);
+  }
+  /** Sets Study Date (0008,0020). */
+  setStudyDate(value) {
+    return this.setTag("(0008,0020)", value);
+  }
+  /** Sets Modality (0008,0060). */
+  setModality(value) {
+    return this.setTag("(0008,0060)", value);
+  }
+  /** Sets Accession Number (0008,0050). */
+  setAccessionNumber(value) {
+    return this.setTag("(0008,0050)", value);
+  }
+  /** Sets Study Description (0008,1030). */
+  setStudyDescription(value) {
+    return this.setTag("(0008,1030)", value);
+  }
+  /** Sets Series Description (0008,103E). */
+  setSeriesDescription(value) {
+    return this.setTag("(0008,103E)", value);
+  }
+  /** Sets Institution Name (0008,0080). */
+  setInstitutionName(value) {
+    return this.setTag("(0008,0080)", value);
+  }
+  /**
+   * Transforms a tag value using a function.
+   *
+   * The function receives the current string value (or undefined if tag is missing)
+   * and returns the new value. Returns a new DicomInstance with the modification.
+   *
+   * @param path - The DICOM tag path
+   * @param fn - Transform function receiving the current value
+   */
+  transformTag(path, fn) {
+    const current = this.dicomDataset.getString(path);
+    const newValue = fn(current.length > 0 ? current : void 0);
+    return this.setTag(path, newValue);
+  }
+  /**
+   * Sets multiple tags at once, returning a new DicomInstance.
+   *
+   * @param entries - A record of tag path → value pairs
+   */
+  setBatch(entries) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.setBatch(entries), this.filepath, this.meta);
+  }
+  /**
+   * Returns a new DicomInstance with the given changes merged into pending changes.
    *
    * @param changes - A ChangeSet to merge with existing pending changes
-   * @returns A new DicomFile with accumulated changes
+   * @returns A new DicomInstance with accumulated changes
    */
   withChanges(changes) {
-    return new _DicomFile(this.dataset, this.filePath, this.changes.merge(changes));
+    return new _DicomInstance(this.dicomDataset, this.changeSet.merge(changes), this.filepath, this.meta);
   }
   /**
-   * Returns a new DicomFile with a different file path.
+   * Returns a new DicomInstance pointing to a different file path.
    *
-   * Preserves the dataset and pending changes.
+   * Preserves the dataset, pending changes, and metadata.
    *
-   * @param newPath - The new branded file path
-   * @returns A new DicomFile pointing to the new path
+   * @param newPath - The new filesystem path (validated via createDicomFilePath)
+   * @returns A new DicomInstance with the updated path
+   * @throws If the path is invalid
    */
   withFilePath(newPath) {
-    return new _DicomFile(this.dataset, newPath, this.changes);
+    const result = createDicomFilePath(newPath);
+    if (!result.ok) throw result.error;
+    return new _DicomInstance(this.dicomDataset, this.changeSet, result.value, this.meta);
   }
+  // -----------------------------------------------------------------------
+  // File I/O
+  // -----------------------------------------------------------------------
   /**
-   * Applies pending changes to the file in-place using dcmodify.
+   * Applies pending changes to the file in-place.
    *
-   * If there are no pending changes, this is a no-op that returns success.
-   * After applying, the dataset is NOT refreshed — call {@link DicomFile.open}
-   * again if you need fresh data.
+   * Requires that the instance has an associated file path.
    *
    * @param options - Timeout and abort options
-   * @returns A Result indicating success or failure
    */
   async applyChanges(options) {
-    if (this.changes.isEmpty) return ok(void 0);
-    return applyModifications(this.filePath, this.changes, options ?? {});
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    if (this.changeSet.isEmpty) return ok(void 0);
+    return applyModifications(this.filepath, this.changeSet, options ?? {});
   }
   /**
    * Copies the file to a new path and applies pending changes to the copy.
    *
-   * If there are no pending changes, only the copy is performed.
-   * On dcmodify failure, the copy is cleaned up.
+   * Returns a new DicomInstance pointing to the output path.
    *
    * @param outputPath - Destination filesystem path
    * @param options - Timeout and abort options
-   * @returns A Result containing the branded output path or an error
    */
   async writeAs(outputPath, options) {
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
     const outPathResult = createDicomFilePath(outputPath);
     if (!outPathResult.ok) return err(outPathResult.error);
-    const copyResult = await copyFileSafe(this.filePath, outputPath);
+    const copyResult = await copyFileSafe(this.filepath, outputPath);
     if (!copyResult.ok) return err(copyResult.error);
-    if (this.changes.isEmpty) return ok(outPathResult.value);
-    const applyResult = await applyModifications(outPathResult.value, this.changes, options ?? {});
-    if (!applyResult.ok) {
-      await unlinkFile(outputPath);
-      return err(applyResult.error);
+    if (!this.changeSet.isEmpty) {
+      const applyResult = await applyModifications(outPathResult.value, this.changeSet, options ?? {});
+      if (!applyResult.ok) {
+        await unlinkFile(outputPath);
+        return err(applyResult.error);
+      }
     }
-    return ok(outPathResult.value);
+    return ok(new _DicomInstance(this.dicomDataset, ChangeSet.empty(), outPathResult.value, this.meta));
   }
   /**
    * Gets the file size in bytes.
@@ -30900,15 +31150,43 @@ var DicomFile = class _DicomFile {
    * @returns A Result containing the size or an error
    */
   async fileSize() {
-    return statFileSize(this.filePath);
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    return statFileSize(this.filepath);
   }
   /**
-   * Deletes the file from the filesystem.
+   * Deletes the associated file from the filesystem.
    *
    * @returns A Result indicating success or failure
    */
   async unlink() {
-    return unlinkFile(this.filePath);
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    return unlinkFile(this.filepath);
+  }
+  // -----------------------------------------------------------------------
+  // Metadata (non-DICOM app context)
+  // -----------------------------------------------------------------------
+  /**
+   * Returns a new DicomInstance with application metadata attached.
+   *
+   * Metadata is not stored in the DICOM file — it's for application context
+   * (e.g. tracking source association, processing status, etc.).
+   *
+   * @param key - Metadata key
+   * @param value - Metadata value
+   */
+  withMetadata(key, value) {
+    const newMeta = new Map(this.meta);
+    newMeta.set(key, value);
+    return new _DicomInstance(this.dicomDataset, this.changeSet, this.filepath, newMeta);
+  }
+  /**
+   * Gets application metadata by key.
+   *
+   * @param key - Metadata key
+   * @returns The metadata value or undefined
+   */
+  getMetadata(key) {
+    return this.meta.get(key);
   }
 };
 
@@ -31026,6 +31304,6 @@ function sopClassNameFromUID(uid) {
   return uidToNameMap.get(uid);
 }
 
-export { ChangeSet, DicomDataset, DicomFile, SOP_CLASSES, VR, VR_CATEGORY, VR_CATEGORY_NAME, VR_META, getVRCategory, isBinaryVR, isNumericVR, isStringVR, lookupTag, lookupTagByKeyword, lookupTagByName, segmentsToModifyPath, segmentsToString, sopClassNameFromUID, tagPathToSegments, xmlToJson };
+export { ChangeSet, DicomDataset, DicomInstance, SOP_CLASSES, VR, VR_CATEGORY, VR_CATEGORY_NAME, VR_META, getVRCategory, isBinaryVR, isNumericVR, isStringVR, lookupTag, lookupTagByKeyword, lookupTagByName, segmentsToModifyPath, segmentsToString, sopClassNameFromUID, tagPathToSegments, xmlToJson };
 //# sourceMappingURL=dicom.js.map
 //# sourceMappingURL=dicom.js.map