@ubercode/dcmtk 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/{DicomInstance-DGWB2mfD.d.ts → DicomInstance-A11-CkGx.d.ts}

@@ -460,10 +460,28 @@ interface FileIOOptions {
 }
 /** Options for opening a DICOM file. Extends FileIOOptions with read-specific settings. */
 interface DicomOpenOptions extends FileIOOptions {
-    /** Assume the specified character set when SpecificCharacterSet (0008,0005) is absent. Maps to dcm2xml `+Ca`. */
+    /** Assume the specified character set when SpecificCharacterSet (0008,0005) is absent. Accepts DICOM defined terms ('ISO_IR 100') or DCMTK-style aliases ('latin-1'). */
     readonly charsetAssume?: string | undefined;
-    /** Fallback charset to retry with when UTF-8 conversion fails due to illegal byte sequences. Maps to dcm2xml `+Ca`. When set, a charset conversion failure triggers an automatic retry with this charset assumed. `'Latin1'` is recommended — it maps every byte 0x00-0xFF to a valid character, so conversion never fails. */
+    /** Fallback charset to decode with when the file's character set is unsupported or conversion fails. `'latin-1'` is recommended — it maps every byte 0x00-0xFF to a valid character, so decoding never fails. */
     readonly charsetFallback?: string | undefined;
+    /**
+     * Decode values detected as mislabeled UTF-8 (high bytes forming valid UTF-8 under a single-byte declared charset)
+     * as UTF-8 instead of the declared charset. A `possible UTF-8 mislabel` warning is surfaced either way via
+     * `DicomInstance.warnings`. JS engine only. Defaults to false.
+     */
+    readonly utf8MislabelPromote?: boolean | undefined;
+    /**
+     * Bounded head-read: for files above ~8 MB, read only the metadata and skip bulk value bytes.
+     * Output is identical; peak memory scales with metadata instead of file size. JS engine only.
+     * Defaults to true.
+     */
+    readonly boundedRead?: boolean | undefined;
+    /**
+     * Parse engine. `'js'` (default) parses in-process via {@link dicom2json}
+     * and automatically falls back to the DCMTK binaries when the JS parser
+     * fails; `'dcmtk'` uses the deprecated dcm2json binary path exclusively.
+     */
+    readonly engine?: 'js' | 'dcmtk' | undefined;
 }
 
 /**
@@ -499,7 +517,10 @@ declare class DicomInstance {
     private readonly changeSet;
     private readonly filepath;
     private readonly meta;
+    private readonly warningList;
     private constructor();
+    /** Creates a copy with the given fields replaced. */
+    private derive;
     /**
      * Opens a DICOM file and creates a DicomInstance.
      *
@@ -524,6 +545,13 @@ declare class DicomInstance {
     get hasUnsavedChanges(): boolean;
     /** The file path, or undefined if this instance has no associated file. */
     get filePath(): string | undefined;
+    /**
+     * Non-fatal parser warnings from opening the file (e.g. `possible UTF-8 mislabel: <tag>`).
+     *
+     * Empty for instances created via {@link DicomInstance.fromDataset} or opened with
+     * `engine: 'dcmtk'`. Preserved across fluent modifications.
+     */
+    get warnings(): readonly string[];
     /** Patient's Name (0010,0010). */
     get patientName(): string;
     /** Patient ID (0010,0020). */

package/dist/{DicomInstance-BGXtON9T.d.cts → DicomInstance-Ce4mcUT9.d.cts}

@@ -460,10 +460,28 @@ interface FileIOOptions {
 }
 /** Options for opening a DICOM file. Extends FileIOOptions with read-specific settings. */
 interface DicomOpenOptions extends FileIOOptions {
-    /** Assume the specified character set when SpecificCharacterSet (0008,0005) is absent. Maps to dcm2xml `+Ca`. */
+    /** Assume the specified character set when SpecificCharacterSet (0008,0005) is absent. Accepts DICOM defined terms ('ISO_IR 100') or DCMTK-style aliases ('latin-1'). */
     readonly charsetAssume?: string | undefined;
-    /** Fallback charset to retry with when UTF-8 conversion fails due to illegal byte sequences. Maps to dcm2xml `+Ca`. When set, a charset conversion failure triggers an automatic retry with this charset assumed. `'Latin1'` is recommended — it maps every byte 0x00-0xFF to a valid character, so conversion never fails. */
+    /** Fallback charset to decode with when the file's character set is unsupported or conversion fails. `'latin-1'` is recommended — it maps every byte 0x00-0xFF to a valid character, so decoding never fails. */
     readonly charsetFallback?: string | undefined;
+    /**
+     * Decode values detected as mislabeled UTF-8 (high bytes forming valid UTF-8 under a single-byte declared charset)
+     * as UTF-8 instead of the declared charset. A `possible UTF-8 mislabel` warning is surfaced either way via
+     * `DicomInstance.warnings`. JS engine only. Defaults to false.
+     */
+    readonly utf8MislabelPromote?: boolean | undefined;
+    /**
+     * Bounded head-read: for files above ~8 MB, read only the metadata and skip bulk value bytes.
+     * Output is identical; peak memory scales with metadata instead of file size. JS engine only.
+     * Defaults to true.
+     */
+    readonly boundedRead?: boolean | undefined;
+    /**
+     * Parse engine. `'js'` (default) parses in-process via {@link dicom2json}
+     * and automatically falls back to the DCMTK binaries when the JS parser
+     * fails; `'dcmtk'` uses the deprecated dcm2json binary path exclusively.
+     */
+    readonly engine?: 'js' | 'dcmtk' | undefined;
 }
 
 /**
@@ -499,7 +517,10 @@ declare class DicomInstance {
     private readonly changeSet;
     private readonly filepath;
     private readonly meta;
+    private readonly warningList;
     private constructor();
+    /** Creates a copy with the given fields replaced. */
+    private derive;
     /**
      * Opens a DICOM file and creates a DicomInstance.
      *
@@ -524,6 +545,13 @@ declare class DicomInstance {
     get hasUnsavedChanges(): boolean;
     /** The file path, or undefined if this instance has no associated file. */
     get filePath(): string | undefined;
+    /**
+     * Non-fatal parser warnings from opening the file (e.g. `possible UTF-8 mislabel: <tag>`).
+     *
+     * Empty for instances created via {@link DicomInstance.fromDataset} or opened with
+     * `engine: 'dcmtk'`. Preserved across fluent modifications.
+     */
+    get warnings(): readonly string[];
     /** Patient's Name (0010,0010). */
     get patientName(): string;
     /** Patient ID (0010,0020). */