@ubercode/dcmtk 0.1.1 → 0.2.0

package/dist/index-DX4C3zbo.d.cts

@@ -1,826 +0,0 @@
-import { R as Result } from './types-zHhxS7d2.cjs';
-import { b as DicomJsonElement, T as TagModification } from './dcmodify-CTXBWKU9.cjs';
-
-/**
- * Branded types for domain primitives.
- *
- * Branded types use TypeScript's structural type system to prevent accidental
- * mixing of semantically different values that share the same underlying type.
- * A `DicomTag` cannot be used where an `AETitle` is expected, even though both
- * are strings at runtime.
- *
- * @module brands
- */
-
-declare const __brand: unique symbol;
-/** Intersects a base type with a phantom brand property for nominal typing. */
-type Brand<T, TBrand extends string> = T & {
-    readonly [__brand]: TBrand;
-};
-/**
- * A validated DICOM tag string, e.g. `"(0010,0010)"`.
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createDicomTag} to obtain a branded value from a raw string.
- */
-type DicomTag = Brand<string, 'DicomTag'>;
-/**
- * A validated AE Title (1-16 chars: uppercase letters, digits, spaces, hyphens).
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createAETitle} to obtain a branded value from a raw string.
- */
-type AETitle = Brand<string, 'AETitle'>;
-/**
- * A validated DICOM tag path, e.g. `"(0040,A730)[0].(0010,0010)"`.
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createDicomTagPath} to obtain a branded value from a raw string.
- */
-type DicomTagPath = Brand<string, 'DicomTagPath'>;
-/**
- * A validated SOP Class UID (dotted numeric OID, 1-64 chars).
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createSOPClassUID} to obtain a branded value from a raw string.
- */
-type SOPClassUID = Brand<string, 'SOPClassUID'>;
-/**
- * A validated Transfer Syntax UID (dotted numeric OID, 1-64 chars).
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createTransferSyntaxUID} to obtain a branded value from a raw string.
- */
-type TransferSyntaxUID = Brand<string, 'TransferSyntaxUID'>;
-/**
- * A validated filesystem path to a DICOM file.
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createDicomFilePath} to obtain a branded value from a raw string.
- */
-type DicomFilePath = Brand<string, 'DicomFilePath'>;
-/**
- * A validated network port number (1-65535).
- *
- * @remarks
- * Branded types enforce type safety when passing values between functions.
- * They are not required for direct API calls (which validate internally via Zod).
- * Use {@link createPort} to obtain a branded value from a raw number.
- */
-type Port = Brand<number, 'Port'>;
-/**
- * Creates a validated DicomTag from a raw string.
- *
- * @param input - A string expected to be in format `(XXXX,XXXX)` where X is a hex digit
- * @returns A Result containing the branded DicomTag or an error
- */
-declare function createDicomTag(input: string): Result<DicomTag>;
-/**
- * Creates a validated AETitle from a raw string.
- *
- * @param input - A string expected to be 1-16 chars of letters, digits, spaces, or hyphens
- * @returns A Result containing the branded AETitle or an error
- */
-declare function createAETitle(input: string): Result<AETitle>;
-/**
- * Creates a validated DicomTagPath from a raw string.
- *
- * @param input - A dot-separated path of DICOM tags with optional array indices
- * @returns A Result containing the branded DicomTagPath or an error
- */
-declare function createDicomTagPath(input: string): Result<DicomTagPath>;
-/**
- * Creates a validated SOPClassUID from a raw string.
- *
- * @param input - A dotted numeric OID string, 1-64 characters
- * @returns A Result containing the branded SOPClassUID or an error
- */
-declare function createSOPClassUID(input: string): Result<SOPClassUID>;
-/**
- * Creates a validated TransferSyntaxUID from a raw string.
- *
- * @param input - A dotted numeric OID string, 1-64 characters
- * @returns A Result containing the branded TransferSyntaxUID or an error
- */
-declare function createTransferSyntaxUID(input: string): Result<TransferSyntaxUID>;
-/**
- * Creates a branded DicomFilePath from a raw string.
- * Validates that the path is non-empty and does not contain path traversal sequences.
- *
- * @param input - A filesystem path string
- * @returns A Result containing the branded DicomFilePath or an error
- */
-declare function createDicomFilePath(input: string): Result<DicomFilePath>;
-/**
- * Creates a validated Port from a raw number.
- *
- * @param input - A number expected to be an integer between 1 and 65535
- * @returns A Result containing the branded Port or an error
- */
-declare function createPort(input: number): Result<Port>;
-
-/**
- * DICOM Value Representation (VR) definitions, categories, and metadata.
- *
- * Provides a complete catalogue of all 34 standard DICOM VRs with their
- * constraints (max length, padding, fixed-length) and category classification.
- *
- * @module dicom/vr
- */
-/**
- * All 34 standard DICOM Value Representation codes.
- *
- * @see DICOM PS3.5 Section 6.2
- */
-declare const VR: {
-    /** Application Entity — 16 bytes max, leading/trailing spaces significant */
-    readonly AE: "AE";
-    /** Age String — 4 bytes fixed, e.g. "032Y" */
-    readonly AS: "AS";
-    /** Attribute Tag — 4 bytes fixed */
-    readonly AT: "AT";
-    /** Code String — 16 bytes max */
-    readonly CS: "CS";
-    /** Date — 8 bytes fixed, YYYYMMDD */
-    readonly DA: "DA";
-    /** Decimal String — 16 bytes max per value */
-    readonly DS: "DS";
-    /** Date Time — 26 bytes max */
-    readonly DT: "DT";
-    /** Floating Point Double — 8 bytes fixed */
-    readonly FD: "FD";
-    /** Floating Point Single — 4 bytes fixed */
-    readonly FL: "FL";
-    /** Integer String — 12 bytes max */
-    readonly IS: "IS";
-    /** Long String — 64 chars max */
-    readonly LO: "LO";
-    /** Long Text — 10240 chars max */
-    readonly LT: "LT";
-    /** Other Byte — no max */
-    readonly OB: "OB";
-    /** Other Double — no max */
-    readonly OD: "OD";
-    /** Other Float — no max */
-    readonly OF: "OF";
-    /** Other Long — no max */
-    readonly OL: "OL";
-    /** Other 64-bit Very Long — no max */
-    readonly OV: "OV";
-    /** Other Word — no max */
-    readonly OW: "OW";
-    /** Person Name — 64 chars max per component group */
-    readonly PN: "PN";
-    /** Short String — 16 chars max */
-    readonly SH: "SH";
-    /** Signed Long — 4 bytes fixed */
-    readonly SL: "SL";
-    /** Sequence of Items — no max */
-    readonly SQ: "SQ";
-    /** Signed Short — 2 bytes fixed */
-    readonly SS: "SS";
-    /** Short Text — 1024 chars max */
-    readonly ST: "ST";
-    /** Signed 64-bit Very Long — 8 bytes fixed */
-    readonly SV: "SV";
-    /** Time — 14 bytes max */
-    readonly TM: "TM";
-    /** Unlimited Characters — no max */
-    readonly UC: "UC";
-    /** Unique Identifier (UID) — 64 bytes max */
-    readonly UI: "UI";
-    /** Unsigned Long — 4 bytes fixed */
-    readonly UL: "UL";
-    /** Unknown — no max */
-    readonly UN: "UN";
-    /** Universal Resource Identifier/Locator — no max */
-    readonly UR: "UR";
-    /** Unsigned Short — 2 bytes fixed */
-    readonly US: "US";
-    /** Unlimited Text — no max */
-    readonly UT: "UT";
-    /** Unsigned 64-bit Very Long — 8 bytes fixed */
-    readonly UV: "UV";
-};
-/** A valid DICOM Value Representation code. */
-type VRValue = (typeof VR)[keyof typeof VR];
-/** Names for the five VR categories. */
-declare const VR_CATEGORY_NAME: {
-    readonly STRING: "STRING";
-    readonly NUMERIC: "NUMERIC";
-    readonly BINARY: "BINARY";
-    readonly SEQUENCE: "SEQUENCE";
-    readonly TAG: "TAG";
-};
-/** A VR category name. */
-type VRCategoryName = (typeof VR_CATEGORY_NAME)[keyof typeof VR_CATEGORY_NAME];
-/**
- * VR codes grouped by category.
- *
- * - STRING: text-based VRs that hold character data
- * - NUMERIC: VRs that hold numeric data (integer or float)
- * - BINARY: VRs that hold raw binary/byte data
- * - SEQUENCE: the SQ VR for nested datasets
- * - TAG: the AT VR for attribute tag references
- */
-declare const VR_CATEGORY: {
-    readonly STRING: readonly ["AE", "AS", "CS", "DA", "DS", "DT", "IS", "LO", "LT", "PN", "SH", "ST", "TM", "UC", "UI", "UR", "UT"];
-    readonly NUMERIC: readonly ["FD", "FL", "SL", "SS", "SV", "UL", "US", "UV"];
-    readonly BINARY: readonly ["OB", "OD", "OF", "OL", "OV", "OW", "UN"];
-    readonly SEQUENCE: readonly ["SQ"];
-    readonly TAG: readonly ["AT"];
-};
-/** Metadata describing the constraints of a single VR. */
-interface VRMetadata {
-    /** Maximum value length in bytes/chars, or null if unlimited. */
-    readonly maxLength: number | null;
-    /** Character used for padding to even length, or null if no padding. */
-    readonly paddingChar: ' ' | '\0' | null;
-    /** Whether this VR has a fixed (non-variable) length. */
-    readonly fixed: boolean;
-    /** The category this VR belongs to. */
-    readonly category: VRCategoryName;
-}
-/**
- * Complete metadata for all 34 standard DICOM VRs.
- *
- * @see DICOM PS3.5 Table 6.2-1
- */
-declare const VR_META: Readonly<Record<VRValue, VRMetadata>>;
-/**
- * Type guard: checks whether a string is a valid DICOM VR code.
- *
- * @param vr - The string to check
- * @returns True if `vr` is one of the 34 standard VR codes
- */
-declare function isStringVR(vr: string): vr is VRValue;
-/**
- * Checks whether a VR code represents a numeric value representation.
- *
- * @param vr - The VR code to check
- * @returns True if the VR is FD, FL, SL, SS, SV, UL, US, or UV
- */
-declare function isNumericVR(vr: string): boolean;
-/**
- * Checks whether a VR code represents a binary value representation.
- *
- * @param vr - The VR code to check
- * @returns True if the VR is OB, OD, OF, OL, OV, OW, or UN
- */
-declare function isBinaryVR(vr: string): boolean;
-/**
- * Returns the category name for a given VR code.
- *
- * @param vr - A valid VR code
- * @returns The category name (STRING, NUMERIC, BINARY, SEQUENCE, or TAG)
- */
-declare function getVRCategory(vr: VRValue): VRCategoryName;
-
-/**
- * DICOM tag dictionary with O(1) lookup by tag and lazy reverse lookup by name.
- *
- * Uses the shipped `src/data/dictionary.json` generated from `_configs/dicom.dic.json`.
- *
- * @module dicom/dictionary
- */
-
-/** A single entry from the DICOM data dictionary. */
-interface DictionaryEntry {
-    /** The Value Representation code (e.g. "PN", "LO", "US"). */
-    readonly vr: VRValue;
-    /** The standard keyword name (e.g. "PatientName"). */
-    readonly name: string;
-    /** Value multiplicity as [min, max], where max is null if unbounded. */
-    readonly vm: readonly [number, number | null];
-    /** Whether this tag is retired in the current DICOM standard. */
-    readonly retired: boolean;
-}
-/**
- * Looks up a DICOM tag in the data dictionary.
- *
- * Accepts tags in either branded `DicomTag` format `"(0010,0010)"` or
- * raw 8-char hex format `"00100010"`.
- *
- * @param tag - A DicomTag or 8-char hex string
- * @returns The dictionary entry, or undefined if the tag is not in the dictionary
- */
-declare function lookupTag(tag: DicomTag | string): DictionaryEntry | undefined;
-/**
- * Looks up a DICOM tag by its standard keyword name.
- *
- * @param name - The standard keyword (e.g. "PatientName", "Modality")
- * @returns An object with the 8-char hex tag and dictionary entry, or undefined
- */
-declare function lookupTagByName(name: string): {
-    readonly tag: string;
-    readonly entry: DictionaryEntry;
-} | undefined;
-/**
- * Looks up a DICOM tag by its standard keyword, returning just the branded DicomTag.
- *
- * @param keyword - The standard keyword (e.g. "PatientName")
- * @returns The DicomTag in `(XXXX,XXXX)` format, or undefined if not found
- */
-declare function lookupTagByKeyword(keyword: string): DicomTag | undefined;
-
-/**
- * Curated list of common DICOM SOP Class UIDs.
- *
- * This is not exhaustive — DICOM defines hundreds of SOP classes.
- * This file covers the ~70 most commonly encountered SOP classes
- * in clinical and research imaging workflows.
- *
- * @see DICOM PS3.4 Annex B — SOP Class definitions
- * @module data/sopClasses
- */
-/**
- * Common DICOM SOP Class UIDs.
- *
- * Keys are PascalCase names matching the DICOM standard keyword.
- * Values are the dotted-numeric UID strings.
- */
-declare const SOP_CLASSES: {
-    readonly Verification: "1.2.840.10008.1.1";
-    readonly ComputedRadiographyImageStorage: "1.2.840.10008.5.1.4.1.1.1";
-    readonly DigitalXRayImageStorageForPresentation: "1.2.840.10008.5.1.4.1.1.1.1";
-    readonly DigitalXRayImageStorageForProcessing: "1.2.840.10008.5.1.4.1.1.1.1.1";
-    readonly DigitalMammographyXRayImageStorageForPresentation: "1.2.840.10008.5.1.4.1.1.1.2";
-    readonly DigitalMammographyXRayImageStorageForProcessing: "1.2.840.10008.5.1.4.1.1.1.2.1";
-    readonly CTImageStorage: "1.2.840.10008.5.1.4.1.1.2";
-    readonly EnhancedCTImageStorage: "1.2.840.10008.5.1.4.1.1.2.1";
-    readonly UltrasoundMultiFrameImageStorage: "1.2.840.10008.5.1.4.1.1.3.1";
-    readonly MRImageStorage: "1.2.840.10008.5.1.4.1.1.4";
-    readonly EnhancedMRImageStorage: "1.2.840.10008.5.1.4.1.1.4.1";
-    readonly MRSpectroscopyStorage: "1.2.840.10008.5.1.4.1.1.4.2";
-    readonly EnhancedMRColorImageStorage: "1.2.840.10008.5.1.4.1.1.4.3";
-    readonly UltrasoundImageStorage: "1.2.840.10008.5.1.4.1.1.6.1";
-    readonly EnhancedUSVolumeStorage: "1.2.840.10008.5.1.4.1.1.6.2";
-    readonly SecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7";
-    readonly MultiFrameSingleBitSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.1";
-    readonly MultiFrameGrayscaleByteSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.2";
-    readonly MultiFrameGrayscaleWordSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.3";
-    readonly MultiFrameTrueColorSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.4";
-    readonly XRayAngiographicImageStorage: "1.2.840.10008.5.1.4.1.1.12.1";
-    readonly EnhancedXAImageStorage: "1.2.840.10008.5.1.4.1.1.12.1.1";
-    readonly XRayRadiofluoroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.12.2";
-    readonly EnhancedXRFImageStorage: "1.2.840.10008.5.1.4.1.1.12.2.1";
-    readonly NuclearMedicineImageStorage: "1.2.840.10008.5.1.4.1.1.20";
-    readonly VLEndoscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.1";
-    readonly VLMicroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.2";
-    readonly VLSlideCoordinatesMicroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.3";
-    readonly VLPhotographicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.4";
-    readonly OphthalmicPhotography8BitImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.5.1";
-    readonly OphthalmicPhotography16BitImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.5.2";
-    readonly VLWholeSlideMicroscopyImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.6";
-    readonly PositronEmissionTomographyImageStorage: "1.2.840.10008.5.1.4.1.1.128";
-    readonly EnhancedPETImageStorage: "1.2.840.10008.5.1.4.1.1.130";
-    readonly RTImageStorage: "1.2.840.10008.5.1.4.1.1.481.1";
-    readonly RTDoseStorage: "1.2.840.10008.5.1.4.1.1.481.2";
-    readonly RTStructureSetStorage: "1.2.840.10008.5.1.4.1.1.481.3";
-    readonly RTBeamsTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.4";
-    readonly RTPlanStorage: "1.2.840.10008.5.1.4.1.1.481.5";
-    readonly RTBrachyTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.6";
-    readonly RTTreatmentSummaryRecordStorage: "1.2.840.10008.5.1.4.1.1.481.7";
-    readonly RTIonPlanStorage: "1.2.840.10008.5.1.4.1.1.481.8";
-    readonly RTIonBeamsTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.9";
-    readonly BasicTextSRStorage: "1.2.840.10008.5.1.4.1.1.88.11";
-    readonly EnhancedSRStorage: "1.2.840.10008.5.1.4.1.1.88.22";
-    readonly ComprehensiveSRStorage: "1.2.840.10008.5.1.4.1.1.88.33";
-    readonly Comprehensive3DSRStorage: "1.2.840.10008.5.1.4.1.1.88.34";
-    readonly KeyObjectSelectionDocumentStorage: "1.2.840.10008.5.1.4.1.1.88.59";
-    readonly GrayscaleSoftcopyPresentationStateStorage: "1.2.840.10008.5.1.4.1.1.11.1";
-    readonly ColorSoftcopyPresentationStateStorage: "1.2.840.10008.5.1.4.1.1.11.2";
-    readonly EncapsulatedPDFStorage: "1.2.840.10008.5.1.4.1.1.104.1";
-    readonly EncapsulatedCDAStorage: "1.2.840.10008.5.1.4.1.1.104.2";
-    readonly RawDataStorage: "1.2.840.10008.5.1.4.1.1.66";
-    readonly SpatialRegistrationStorage: "1.2.840.10008.5.1.4.1.1.66.1";
-    readonly SpatialFiducialsStorage: "1.2.840.10008.5.1.4.1.1.66.2";
-    readonly DeformableSpatialRegistrationStorage: "1.2.840.10008.5.1.4.1.1.66.3";
-    readonly SegmentationStorage: "1.2.840.10008.5.1.4.1.1.66.4";
-    readonly SurfaceSegmentationStorage: "1.2.840.10008.5.1.4.1.1.66.5";
-    readonly TwelveLeadECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.1";
-    readonly GeneralECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.2";
-    readonly AmbulatoryECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.3";
-    readonly HemodynamicWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.2.1";
-    readonly BasicVoiceAudioWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.4.1";
-    readonly PatientRootQueryRetrieveInformationModelFind: "1.2.840.10008.5.1.4.1.2.1.1";
-    readonly PatientRootQueryRetrieveInformationModelMove: "1.2.840.10008.5.1.4.1.2.1.2";
-    readonly PatientRootQueryRetrieveInformationModelGet: "1.2.840.10008.5.1.4.1.2.1.3";
-    readonly StudyRootQueryRetrieveInformationModelFind: "1.2.840.10008.5.1.4.1.2.2.1";
-    readonly StudyRootQueryRetrieveInformationModelMove: "1.2.840.10008.5.1.4.1.2.2.2";
-    readonly StudyRootQueryRetrieveInformationModelGet: "1.2.840.10008.5.1.4.1.2.2.3";
-    readonly ModalityWorklistInformationModelFind: "1.2.840.10008.5.1.4.31";
-    readonly StorageCommitmentPushModel: "1.2.840.10008.1.20.1";
-};
-/** A SOP class name key from the curated list. */
-type SOPClassName = keyof typeof SOP_CLASSES;
-/**
- * Looks up the SOP class name for a given UID string.
- *
- * @param uid - A DICOM SOP Class UID string
- * @returns The SOP class name, or undefined if not in the curated list
- */
-declare function sopClassNameFromUID(uid: string): SOPClassName | undefined;
-
-/**
- * DICOM tag path parser and serializer.
- *
- * Provides iterative (no recursion) parsing of DICOM tag paths like
- * `(0040,A730)[0].(0040,A160)` into structured segments, and conversion
- * back to dcmodify-compatible strings.
- *
- * Supports wildcard indices `[*]` for use with DicomDataset.findValues.
- *
- * @module dicom/tagPath
- */
-
-/** A single segment of a parsed DICOM tag path. */
-interface TagSegment {
-    /** The DICOM tag for this segment. */
-    readonly tag: DicomTag;
-    /** The array index for sequence items, or undefined for non-sequence tags. */
-    readonly index?: number | undefined;
-    /** Whether this segment uses a wildcard index `[*]`. */
-    readonly isWildcard?: boolean | undefined;
-}
-/**
- * Parses a DICOM tag path into an array of segments.
- *
- * Uses iterative parsing with bounded loop (Rule 8.2: no recursion).
- *
- * @param path - A branded DicomTagPath string
- * @returns An array of TagSegment objects
- * @throws Error if the path is malformed or exceeds MAX_TRAVERSAL_DEPTH
- *
- * @example
- * ```ts
- * tagPathToSegments('(0040,A730)[0].(0040,A160)' as DicomTagPath)
- * // => [
- * //   { tag: '(0040,A730)' as DicomTag, index: 0 },
- * //   { tag: '(0040,A160)' as DicomTag }
- * // ]
- * ```
- */
-declare function tagPathToSegments(path: DicomTagPath): ReadonlyArray<TagSegment>;
-/**
- * Converts tag segments back to a dcmodify-compatible path string.
- *
- * Format: `(0040,A730)[0].(0040,A160)`
- *
- * @param segments - An array of TagSegment objects
- * @returns A dcmodify-compatible path string
- */
-declare function segmentsToModifyPath(segments: ReadonlyArray<TagSegment>): string;
-/**
- * Converts tag segments to a canonical display string.
- *
- * Same format as dcmodify path: `(0040,A730)[0].(0040,A160)`
- *
- * @param segments - An array of TagSegment objects
- * @returns A human-readable path string
- */
-declare function segmentsToString(segments: ReadonlyArray<TagSegment>): string;
-
-/**
- * Immutable DICOM dataset wrapper with type-safe accessors.
- *
- * Wraps DICOM JSON Model data (PS3.18 F.2) from dcm2json/dcm2xml with
- * convenient read-only accessors. No setters — mutations go through ChangeSet.
- *
- * @module dicom/DicomDataset
- */
-
-/**
- * Immutable wrapper around DICOM JSON Model data.
- *
- * Provides type-safe read-only accessors for DICOM tag values.
- * Construct via the static {@link DicomDataset.fromJson} factory.
- *
- * @example
- * ```ts
- * const result = DicomDataset.fromJson(jsonData);
- * if (result.ok) {
- *     const ds = result.value;
- *     console.log(ds.patientName);
- *     console.log(ds.modality);
- * }
- * ```
- */
-declare class DicomDataset {
-    private readonly data;
-    private constructor();
-    /**
-     * Creates a DicomDataset from a DICOM JSON Model object.
-     *
-     * Performs structural validation only — verifies the input is a non-null object.
-     *
-     * @param json - A DICOM JSON Model object (typically from dcm2json)
-     * @returns A Result containing the DicomDataset or an error
-     */
-    static fromJson(json: unknown): Result<DicomDataset>;
-    /**
-     * Gets the full DICOM JSON element for a tag.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns Result containing the element or an error if not found
-     */
-    getElement(tag: DicomTag | string): Result<DicomJsonElement>;
-    /**
-     * Gets the Value array for a tag.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns Result containing the readonly Value array or an error
-     */
-    getValue(tag: DicomTag | string): Result<ReadonlyArray<unknown>>;
-    /**
-     * Gets the first element of the Value array for a tag.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns Result containing the first value or an error
-     */
-    getFirstValue(tag: DicomTag | string): Result<unknown>;
-    /**
-     * Gets a tag value as a string with optional fallback.
-     *
-     * Returns the fallback (default empty string) if the tag is missing or has no value.
-     * Handles PN (PersonName) values by extracting the Alphabetic component.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @param fallback - Value to return if tag is missing (default: `''`)
-     * @returns The string value or the fallback
-     */
-    getString(tag: DicomTag | string, fallback?: string): string;
-    /**
-     * Gets a tag value as a validated number.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns Result containing the number or an error
-     */
-    getNumber(tag: DicomTag | string): Result<number>;
-    /**
-     * Gets all values of a tag as strings.
-     *
-     * Useful for multi-valued tags like CS (Code String).
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns Result containing the readonly string array or an error
-     */
-    getStrings(tag: DicomTag | string): Result<ReadonlyArray<string>>;
-    /**
-     * Checks whether a tag exists in the dataset.
-     *
-     * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
-     * @returns `true` if the tag is present
-     */
-    hasTag(tag: DicomTag | string): boolean;
-    /**
-     * Gets an element by traversing a dotted tag path through sequences.
-     *
-     * @param path - A branded DicomTagPath, e.g. `(0040,A730)[0].(0040,A160)`
-     * @returns Result containing the element at the path or an error
-     */
-    getElementAtPath(path: DicomTagPath): Result<DicomJsonElement>;
-    /**
-     * Finds all values matching a path with wildcard `[*]` indices.
-     *
-     * Traverses all items in wildcard sequence positions using an iterative BFS queue.
-     * The traversal is bounded to {@link MAX_TRAVERSAL_DEPTH} * 100 iterations (5 000).
-     * For extremely large datasets this may truncate results silently; callers
-     * needing completeness guarantees should verify dataset size independently.
-     *
-     * @param path - A branded DicomTagPath, e.g. `(0040,A730)[*].(0040,A160)`
-     * @returns A readonly array of all matching values (may be empty)
-     */
-    findValues(path: DicomTagPath): ReadonlyArray<unknown>;
-    /** Accession Number (0008,0050). */
-    get accession(): string;
-    /** Patient's Name (0010,0010). */
-    get patientName(): string;
-    /** Patient ID (0010,0020). */
-    get patientID(): string;
-    /** Study Date (0008,0020). */
-    get studyDate(): string;
-    /** Modality (0008,0060). */
-    get modality(): string;
-    /** SOP Class UID (0008,0016) as a branded SOPClassUID, or undefined if missing/invalid. */
-    get sopClassUID(): SOPClassUID | undefined;
-    /** Study Instance UID (0020,000D). */
-    get studyInstanceUID(): string;
-    /** Series Instance UID (0020,000E). */
-    get seriesInstanceUID(): string;
-    /** SOP Instance UID (0008,0018). */
-    get sopInstanceUID(): string;
-    /** Transfer Syntax UID (0002,0010). */
-    get transferSyntaxUID(): string;
-}
-
-/**
- * Immutable mutation tracking for DICOM datasets.
- *
- * Every mutation method returns a new ChangeSet instance, preserving immutability.
- * Bridge methods produce dcmodify-compatible arguments for applying changes to files.
- *
- * @module dicom/ChangeSet
- */
-
-/**
- * Immutable mutation tracker for DICOM datasets.
- *
- * Every mutation method returns a **new** ChangeSet — the original is never modified.
- * Use {@link ChangeSet.toModifications} and {@link ChangeSet.toErasureArgs} to bridge
- * to the dcmodify tool wrapper.
- *
- * @example
- * ```ts
- * const cs = ChangeSet.empty()
- *     .setTag('(0010,0010)' as DicomTagPath, 'Anonymous')
- *     .eraseTag('(0010,0020)' as DicomTagPath)
- *     .erasePrivateTags();
- * ```
- */
-declare class ChangeSet {
-    private readonly mods;
-    private readonly erased;
-    private constructor();
-    /** Creates an empty ChangeSet with no modifications or erasures. */
-    static empty(): ChangeSet;
-    /**
-     * Sets a tag value, returning a new 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 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
-     */
-    setTag(path: DicomTagPath, value: string): ChangeSet;
-    /**
-     * Marks a tag for erasure, returning a new ChangeSet.
-     *
-     * If the tag was previously set, the modification is removed.
-     *
-     * @param path - The DICOM tag path to erase
-     * @returns A new ChangeSet with the erasure applied
-     * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
-     */
-    eraseTag(path: DicomTagPath): ChangeSet;
-    /**
-     * Marks all private tags for erasure, returning a new ChangeSet.
-     *
-     * @returns A new ChangeSet with the erase-private flag set
-     * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
-     */
-    erasePrivateTags(): ChangeSet;
-    /** All pending tag modifications as a readonly map of path → value. */
-    get modifications(): ReadonlyMap<string, string>;
-    /** All pending tag erasures as a readonly set of paths. */
-    get erasures(): ReadonlySet<string>;
-    /** Total number of operations (modifications + erasures) in this ChangeSet. */
-    get operationCount(): number;
-    /** Whether the ChangeSet has no modifications and no erasures. */
-    get isEmpty(): boolean;
-    /** Whether the erase-all-private-tags flag is set. */
-    get erasePrivate(): boolean;
-    /**
-     * Merges another ChangeSet into this one, returning a new ChangeSet.
-     *
-     * The `other` ChangeSet wins on conflicts: if the same tag is modified in both,
-     * `other`'s value is used. Erasures from both sets are unioned. An erasure in
-     * `other` removes a modification from `base`.
-     *
-     * @param other - The ChangeSet to merge in
-     * @returns A new ChangeSet with merged modifications and erasures
-     */
-    merge(other: ChangeSet): ChangeSet;
-    /**
-     * Converts modifications to dcmodify-compatible TagModification array.
-     *
-     * @returns A readonly array of TagModification objects
-     */
-    toModifications(): ReadonlyArray<TagModification>;
-    /**
-     * Converts erasures to dcmodify-compatible argument strings.
-     *
-     * The erase-private sentinel is excluded — use {@link erasePrivate} to check
-     * whether `-ep` should be passed.
-     *
-     * @returns A readonly array of tag path strings for `-e` arguments
-     */
-    toErasureArgs(): ReadonlyArray<string>;
-}
-
-/**
- * DICOM file I/O combining DicomDataset + ChangeSet + file path.
- *
- * Provides a high-level API for reading, modifying, and saving DICOM files.
- * All mutations are tracked immutably via ChangeSet and applied through dcmodify.
- *
- * @module dicom/DicomFile
- */
-
-/** Options for DicomFile I/O operations. */
-interface DicomFileOptions {
-    /** Timeout in milliseconds. Defaults to DEFAULT_TIMEOUT_MS. */
-    readonly timeoutMs?: number | undefined;
-    /** AbortSignal for external cancellation. */
-    readonly signal?: AbortSignal | undefined;
-}
-/**
- * High-level DICOM file wrapper combining dataset, change tracking, and file I/O.
- *
- * Create via {@link DicomFile.open}. Accumulate changes with {@link withChanges},
- * then apply with {@link applyChanges} or write to a new path with {@link writeAs}.
- *
- * @example
- * ```ts
- * const file = await DicomFile.open('/path/to/study.dcm');
- * if (file.ok) {
- *     const modified = file.value
- *         .withChanges(ChangeSet.empty().setTag(tag, 'Anonymous'));
- *     await modified.applyChanges();
- * }
- * ```
- */
-declare class DicomFile {
-    /** The immutable DICOM dataset read from the file. */
-    readonly dataset: DicomDataset;
-    /** The branded file path. */
-    readonly filePath: DicomFilePath;
-    /** The accumulated pending changes. */
-    readonly changes: ChangeSet;
-    private constructor();
-    /**
-     * Opens a DICOM file and reads its dataset.
-     *
-     * @param path - Filesystem path to the DICOM file
-     * @param options - Timeout and abort options
-     * @returns A Result containing the DicomFile or an error
-     */
-    static open(path: string, options?: DicomFileOptions): Promise<Result<DicomFile>>;
-    /**
-     * Returns a new DicomFile with the given changes merged into the pending changes.
-     *
-     * @param changes - A ChangeSet to merge with existing pending changes
-     * @returns A new DicomFile with accumulated changes
-     */
-    withChanges(changes: ChangeSet): DicomFile;
-    /**
-     * Returns a new DicomFile with a different file path.
-     *
-     * Preserves the dataset and pending changes.
-     *
-     * @param newPath - The new branded file path
-     * @returns A new DicomFile pointing to the new path
-     */
-    withFilePath(newPath: DicomFilePath): DicomFile;
-    /**
-     * Applies pending changes to the file in-place using dcmodify.
-     *
-     * 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.
-     *
-     * @param options - Timeout and abort options
-     * @returns A Result indicating success or failure
-     */
-    applyChanges(options?: DicomFileOptions): Promise<Result<void>>;
-    /**
-     * 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.
-     *
-     * @param outputPath - Destination filesystem path
-     * @param options - Timeout and abort options
-     * @returns A Result containing the branded output path or an error
-     */
-    writeAs(outputPath: string, options?: DicomFileOptions): Promise<Result<DicomFilePath>>;
-    /**
-     * Gets the file size in bytes.
-     *
-     * @returns A Result containing the size or an error
-     */
-    fileSize(): Promise<Result<number>>;
-    /**
-     * Deletes the file from the filesystem.
-     *
-     * @returns A Result indicating success or failure
-     */
-    unlink(): Promise<Result<void>>;
-}
-
-export { type AETitle as A, type Brand as B, ChangeSet as C, type DicomTag as D, lookupTag as E, lookupTagByKeyword as F, lookupTagByName as G, segmentsToModifyPath as H, segmentsToString as I, sopClassNameFromUID as J, tagPathToSegments as K, type Port as P, type SOPClassUID as S, type TransferSyntaxUID as T, VR as V, type DicomTagPath as a, DicomDataset as b, DicomFile as c, type DicomFileOptions as d, type DicomFilePath as e, type DictionaryEntry as f, type SOPClassName as g, SOP_CLASSES as h, type TagSegment as i, type VRCategoryName as j, type VRMetadata as k, type VRValue as l, VR_CATEGORY as m, VR_CATEGORY_NAME as n, VR_META as o, createAETitle as p, createDicomFilePath as q, createDicomTag as r, createDicomTagPath as s, createPort as t, createSOPClassUID as u, createTransferSyntaxUID as v, getVRCategory as w, isBinaryVR as x, isNumericVR as y, isStringVR as z };