@ubercode/dcmtk 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -61,7 +61,7 @@ function mapResult(result, fn) {
 
 // src/patterns.ts
 var DICOM_TAG_PATTERN = /^\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)$/;
-var AE_TITLE_PATTERN = /^[A-Za-z0-9 -]+$/;
+var AE_TITLE_PATTERN = /^[\x20-\x5b\x5d-\x7e]+$/;
 var UID_PATTERN = /^[0-9]+(\.[0-9]+)*$/;
 var TAG_PATH_SEGMENT = /\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\])?/;
 var DICOM_TAG_PATH_PATTERN = new RegExp(`^${TAG_PATH_SEGMENT.source}(\\.${TAG_PATH_SEGMENT.source})*$`);
@@ -94,7 +94,7 @@ function createAETitle(input) {
     return err(new Error(`Invalid AE Title: "${input}". Must be ${AE_TITLE_MIN_LENGTH}-${AE_TITLE_MAX_LENGTH} characters`));
   }
   if (!AE_TITLE_PATTERN.test(input)) {
-    return err(new Error(`Invalid AE Title: "${input}". Only letters, digits, spaces, and hyphens are allowed`));
+    return err(new Error(`Invalid AE Title: "${input}". Only printable ASCII characters (no backslash) are allowed`));
   }
   return ok(input);
 }
@@ -36017,6 +36017,532 @@ function delay(ms) {
   });
 }
 
+// src/senders/types.ts
+var SenderMode = {
+  /** One association at a time, queued FIFO. */
+  SINGLE: "single",
+  /** Up to N concurrent associations, each send() gets its own. */
+  MULTIPLE: "multiple",
+  /** Files accumulated into buckets, each bucket = one association. */
+  BUCKET: "bucket"
+};
+var SenderHealth = {
+  /** All associations succeeding normally. */
+  HEALTHY: "healthy",
+  /** Recent failures detected; effective concurrency reduced. */
+  DEGRADED: "degraded",
+  /** Remote endpoint appears down; minimal concurrency. */
+  DOWN: "down"
+};
+
+// src/senders/DicomSender.ts
+var DEFAULT_MAX_ASSOCIATIONS = 4;
+var DEFAULT_MAX_QUEUE_LENGTH = 1e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_DELAY_MS = 1e3;
+var DEFAULT_BUCKET_FLUSH_MS = 5e3;
+var DEFAULT_MAX_BUCKET_SIZE = 50;
+var MAX_ASSOCIATIONS_LIMIT = 64;
+var DEGRADE_THRESHOLD = 3;
+var DOWN_THRESHOLD = 10;
+var RECOVERY_THRESHOLD = 3;
+var DicomSenderOptionsSchema = zod.z.object({
+  host: zod.z.string().min(1),
+  port: zod.z.number().int().min(1).max(65535),
+  calledAETitle: zod.z.string().min(1).max(16).refine(isValidAETitle, { message: "AE Title contains invalid characters" }).optional(),
+  callingAETitle: zod.z.string().min(1).max(16).refine(isValidAETitle, { message: "AE Title contains invalid characters" }).optional(),
+  mode: zod.z.enum(["single", "multiple", "bucket"]).optional(),
+  maxAssociations: zod.z.number().int().min(1).max(MAX_ASSOCIATIONS_LIMIT).optional(),
+  proposedTransferSyntax: zod.z.enum([
+    "uncompressed",
+    "littleEndian",
+    "bigEndian",
+    "implicitVR",
+    "jpegLossless",
+    "jpeg8Bit",
+    "jpeg12Bit",
+    "j2kLossless",
+    "j2kLossy",
+    "jlsLossless",
+    "jlsLossy"
+  ]).optional(),
+  maxQueueLength: zod.z.number().int().min(1).optional(),
+  timeoutMs: zod.z.number().int().positive().optional(),
+  maxRetries: zod.z.number().int().min(0).optional(),
+  retryDelayMs: zod.z.number().int().min(0).optional(),
+  bucketFlushMs: zod.z.number().int().positive().optional(),
+  maxBucketSize: zod.z.number().int().min(1).optional(),
+  signal: zod.z.instanceof(AbortSignal).optional()
+}).strict();
+function resolveConfig(options) {
+  const mode = options.mode ?? "multiple";
+  const rawMax = options.maxAssociations ?? DEFAULT_MAX_ASSOCIATIONS;
+  return {
+    mode,
+    configuredMaxAssociations: mode === "single" ? 1 : rawMax,
+    maxQueueLength: options.maxQueueLength ?? DEFAULT_MAX_QUEUE_LENGTH,
+    defaultTimeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    defaultMaxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+    retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+    bucketFlushMs: options.bucketFlushMs ?? DEFAULT_BUCKET_FLUSH_MS,
+    maxBucketSize: options.maxBucketSize ?? DEFAULT_MAX_BUCKET_SIZE
+  };
+}
+var DicomSender = class _DicomSender extends events.EventEmitter {
+  constructor(options) {
+    super();
+    __publicField(this, "options");
+    __publicField(this, "mode");
+    __publicField(this, "configuredMaxAssociations");
+    __publicField(this, "maxQueueLength");
+    __publicField(this, "defaultTimeoutMs");
+    __publicField(this, "defaultMaxRetries");
+    __publicField(this, "retryDelayMs");
+    __publicField(this, "bucketFlushMs");
+    __publicField(this, "maxBucketSize");
+    // Queue and concurrency state
+    __publicField(this, "queue", []);
+    __publicField(this, "activeAssociations", 0);
+    __publicField(this, "isStopped", false);
+    // Backpressure state
+    __publicField(this, "health", SenderHealth.HEALTHY);
+    __publicField(this, "effectiveMaxAssociations");
+    __publicField(this, "consecutiveFailures", 0);
+    __publicField(this, "consecutiveSuccesses", 0);
+    // Bucket state (bucket mode only)
+    __publicField(this, "currentBucket", []);
+    __publicField(this, "bucketTimer");
+    // AbortSignal
+    __publicField(this, "abortHandler");
+    this.setMaxListeners(20);
+    this.on("error", () => {
+    });
+    this.options = options;
+    const cfg = resolveConfig(options);
+    this.mode = cfg.mode;
+    this.configuredMaxAssociations = cfg.configuredMaxAssociations;
+    this.effectiveMaxAssociations = cfg.configuredMaxAssociations;
+    this.maxQueueLength = cfg.maxQueueLength;
+    this.defaultTimeoutMs = cfg.defaultTimeoutMs;
+    this.defaultMaxRetries = cfg.defaultMaxRetries;
+    this.retryDelayMs = cfg.retryDelayMs;
+    this.bucketFlushMs = cfg.bucketFlushMs;
+    this.maxBucketSize = cfg.maxBucketSize;
+    if (options.signal !== void 0) {
+      this.wireAbortSignal(options.signal);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /**
+   * Creates a new DicomSender instance.
+   *
+   * @param options - Configuration options
+   * @returns A Result containing the instance or a validation error
+   */
+  static create(options) {
+    const validation = DicomSenderOptionsSchema.safeParse(options);
+    if (!validation.success) {
+      return err(createValidationError("DicomSender", validation.error));
+    }
+    return ok(new _DicomSender(options));
+  }
+  /**
+   * Sends one or more DICOM files to the remote endpoint.
+   *
+   * In single/multiple mode, files are sent as one storescu call.
+   * In bucket mode, files are accumulated into a bucket and flushed
+   * when the bucket reaches maxBucketSize or the flush timer fires.
+   *
+   * The returned promise resolves when the files are actually sent
+   * (not just queued). Callers can await for confirmation or
+   * fire-and-forget with `void sender.send(files)`.
+   *
+   * @param files - One or more DICOM file paths
+   * @param options - Per-send overrides
+   * @returns A Result containing the send result or an error
+   */
+  send(files, options) {
+    if (this.isStopped) {
+      return Promise.resolve(err(new Error("DicomSender: sender is stopped")));
+    }
+    if (files.length === 0) {
+      return Promise.resolve(err(new Error("DicomSender: no files provided")));
+    }
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const maxRetries = options?.maxRetries ?? this.defaultMaxRetries;
+    switch (this.mode) {
+      case "single":
+      case "multiple":
+        return this.enqueueSend(files, timeoutMs, maxRetries);
+      case "bucket":
+        return this.enqueueBucket(files, timeoutMs, maxRetries);
+      default:
+        assertUnreachable(this.mode);
+    }
+  }
+  /**
+   * Flushes the current bucket immediately (bucket mode only).
+   * In single/multiple mode this is a no-op.
+   */
+  flush() {
+    if (this.mode !== "bucket") return;
+    if (this.currentBucket.length === 0) return;
+    this.clearBucketTimer();
+    this.flushBucketInternal("timer");
+  }
+  /**
+   * Gracefully stops the sender. Rejects all queued items and
+   * waits for active associations to complete.
+   */
+  async stop() {
+    if (this.isStopped) return;
+    this.isStopped = true;
+    if (this.options.signal !== void 0 && this.abortHandler !== void 0) {
+      this.options.signal.removeEventListener("abort", this.abortHandler);
+    }
+    this.clearBucketTimer();
+    this.rejectBucket("DicomSender: sender stopped");
+    this.rejectQueue("DicomSender: sender stopped");
+    await this.waitForActive();
+  }
+  /** Current sender status. */
+  get status() {
+    return {
+      health: this.health,
+      activeAssociations: this.activeAssociations,
+      effectiveMaxAssociations: this.effectiveMaxAssociations,
+      queueLength: this.queue.length,
+      consecutiveFailures: this.consecutiveFailures,
+      consecutiveSuccesses: this.consecutiveSuccesses,
+      stopped: this.isStopped
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Typed event listener convenience methods
+  // -----------------------------------------------------------------------
+  /**
+   * Registers a typed listener for a DicomSender-specific event.
+   *
+   * @param event - The event name from DicomSenderEventMap
+   * @param listener - Callback receiving typed event data
+   * @returns this for chaining
+   */
+  onEvent(event, listener) {
+    return this.on(event, listener);
+  }
+  /**
+   * Registers a listener for successful sends.
+   *
+   * @param listener - Callback receiving send complete data
+   * @returns this for chaining
+   */
+  onSendComplete(listener) {
+    return this.on("SEND_COMPLETE", listener);
+  }
+  /**
+   * Registers a listener for failed sends.
+   *
+   * @param listener - Callback receiving send failed data
+   * @returns this for chaining
+   */
+  onSendFailed(listener) {
+    return this.on("SEND_FAILED", listener);
+  }
+  /**
+   * Registers a listener for health state changes.
+   *
+   * @param listener - Callback receiving health change data
+   * @returns this for chaining
+   */
+  onHealthChanged(listener) {
+    return this.on("HEALTH_CHANGED", listener);
+  }
+  /**
+   * Registers a listener for bucket flushes (bucket mode only).
+   *
+   * @param listener - Callback receiving bucket flush data
+   * @returns this for chaining
+   */
+  onBucketFlushed(listener) {
+    return this.on("BUCKET_FLUSHED", listener);
+  }
+  // -----------------------------------------------------------------------
+  // Single/Multiple mode: queue-based dispatch
+  // -----------------------------------------------------------------------
+  /** Enqueues a send and dispatches immediately if capacity allows. */
+  enqueueSend(files, timeoutMs, maxRetries) {
+    return new Promise((resolve) => {
+      const totalQueued = this.queue.length + this.currentBucket.length;
+      if (totalQueued >= this.maxQueueLength) {
+        resolve(err(new Error("DicomSender: queue full")));
+        return;
+      }
+      const entry = { files, timeoutMs, maxRetries, resolve };
+      if (this.activeAssociations < this.effectiveMaxAssociations) {
+        void this.executeEntry(entry);
+      } else {
+        this.queue.push(entry);
+      }
+    });
+  }
+  /** Drains queued entries up to available capacity. */
+  drainQueue() {
+    while (this.queue.length > 0 && this.activeAssociations < this.effectiveMaxAssociations) {
+      const entry = this.queue.shift();
+      if (entry === void 0) break;
+      void this.executeEntry(entry);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Bucket mode: accumulate-then-flush
+  // -----------------------------------------------------------------------
+  /** Adds files to the current bucket and triggers flush if full. */
+  enqueueBucket(files, timeoutMs, maxRetries) {
+    return new Promise((resolve) => {
+      const totalQueued = this.queue.length + this.currentBucket.length;
+      if (totalQueued >= this.maxQueueLength) {
+        resolve(err(new Error("DicomSender: queue full")));
+        return;
+      }
+      this.currentBucket.push({ files, resolve, timeoutMs, maxRetries });
+      const totalFiles = this.countBucketFiles();
+      if (totalFiles >= this.maxBucketSize) {
+        this.clearBucketTimer();
+        void this.flushBucketInternal("maxSize");
+      } else {
+        this.resetBucketTimer();
+      }
+    });
+  }
+  /** Counts total files in the current bucket. */
+  countBucketFiles() {
+    let count = 0;
+    for (let i = 0; i < this.currentBucket.length; i++) {
+      count += this.currentBucket[i].files.length;
+    }
+    return count;
+  }
+  /** Flushes the current bucket: combines all files, dispatches as one send. */
+  flushBucketInternal(reason) {
+    if (this.currentBucket.length === 0) return;
+    const entries = [...this.currentBucket];
+    this.currentBucket = [];
+    const allFiles = [];
+    for (let i = 0; i < entries.length; i++) {
+      for (let j = 0; j < entries[i].files.length; j++) {
+        allFiles.push(entries[i].files[j]);
+      }
+    }
+    let timeoutMs = 0;
+    let maxRetries = 0;
+    for (let i = 0; i < entries.length; i++) {
+      if (entries[i].timeoutMs > timeoutMs) timeoutMs = entries[i].timeoutMs;
+      if (entries[i].maxRetries > maxRetries) maxRetries = entries[i].maxRetries;
+    }
+    this.emit("BUCKET_FLUSHED", { fileCount: allFiles.length, reason });
+    const bucketEntry = {
+      files: allFiles,
+      timeoutMs,
+      maxRetries,
+      resolve: (result) => {
+        for (let i = 0; i < entries.length; i++) {
+          entries[i].resolve(result);
+        }
+      }
+    };
+    if (this.activeAssociations < this.effectiveMaxAssociations) {
+      void this.executeEntry(bucketEntry);
+    } else {
+      this.queue.push(bucketEntry);
+    }
+  }
+  /** Resets the bucket flush timer. */
+  resetBucketTimer() {
+    this.clearBucketTimer();
+    this.bucketTimer = setTimeout(() => {
+      this.bucketTimer = void 0;
+      void this.flushBucketInternal("timer");
+    }, this.bucketFlushMs);
+  }
+  /** Clears the bucket flush timer. */
+  clearBucketTimer() {
+    if (this.bucketTimer !== void 0) {
+      clearTimeout(this.bucketTimer);
+      this.bucketTimer = void 0;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Core send execution with retry
+  // -----------------------------------------------------------------------
+  /** Executes a single queue entry: calls storescu with retry. */
+  async executeEntry(entry) {
+    this.activeAssociations++;
+    const startMs = Date.now();
+    const maxAttempts = entry.maxRetries + 1;
+    const lastError = await this.attemptSend(entry, maxAttempts, startMs);
+    if (lastError === void 0) return;
+    this.activeAssociations--;
+    this.recordFailure();
+    this.emit("SEND_FAILED", { files: entry.files, error: lastError, attempts: maxAttempts });
+    entry.resolve(err(lastError));
+    this.drainQueue();
+  }
+  /** Attempts storescu up to maxAttempts times. Returns undefined on success, or the last error. */
+  async attemptSend(entry, maxAttempts, startMs) {
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (this.isStopped) {
+        this.activeAssociations--;
+        entry.resolve(err(new Error("DicomSender: sender stopped")));
+        return void 0;
+      }
+      const result = await this.callStorescu(entry);
+      if (result.ok) {
+        this.handleSendSuccess(entry, startMs);
+        return void 0;
+      }
+      lastError = result.error;
+      if (attempt < maxAttempts - 1) {
+        await delay2(this.retryDelayMs * (attempt + 1));
+      }
+    }
+    return lastError ?? new Error("DicomSender: send failed");
+  }
+  /** Calls storescu with the configured options. */
+  callStorescu(entry) {
+    return storescu({
+      host: this.options.host,
+      port: this.options.port,
+      files: [...entry.files],
+      calledAETitle: this.options.calledAETitle,
+      callingAETitle: this.options.callingAETitle,
+      proposedTransferSyntax: this.options.proposedTransferSyntax,
+      timeoutMs: entry.timeoutMs,
+      signal: this.options.signal
+    });
+  }
+  /** Handles a successful send: updates state, emits event, resolves promise. */
+  handleSendSuccess(entry, startMs) {
+    this.activeAssociations--;
+    const durationMs = Date.now() - startMs;
+    this.recordSuccess();
+    this.emit("SEND_COMPLETE", { files: entry.files, fileCount: entry.files.length, durationMs });
+    entry.resolve(ok({ files: entry.files, fileCount: entry.files.length, durationMs }));
+    this.drainQueue();
+  }
+  // -----------------------------------------------------------------------
+  // Backpressure state machine
+  // -----------------------------------------------------------------------
+  /** Records a successful send and adjusts health upward if needed. */
+  recordSuccess() {
+    this.consecutiveFailures = 0;
+    this.consecutiveSuccesses++;
+    if (this.health === SenderHealth.HEALTHY) return;
+    if (this.consecutiveSuccesses >= RECOVERY_THRESHOLD) {
+      this.consecutiveSuccesses = 0;
+      const previousHealth = this.health;
+      if (this.health === SenderHealth.DOWN) {
+        this.health = SenderHealth.DEGRADED;
+      } else {
+        this.effectiveMaxAssociations = Math.min(this.effectiveMaxAssociations * 2, this.configuredMaxAssociations);
+        if (this.effectiveMaxAssociations >= this.configuredMaxAssociations) {
+          this.health = SenderHealth.HEALTHY;
+        }
+      }
+      this.emitHealthChanged(previousHealth);
+      this.drainQueue();
+    }
+  }
+  /** Records a failed send and adjusts health downward if needed. */
+  recordFailure() {
+    this.consecutiveSuccesses = 0;
+    this.consecutiveFailures++;
+    const previousHealth = this.health;
+    if (this.consecutiveFailures >= DOWN_THRESHOLD) {
+      if (this.health !== SenderHealth.DOWN) {
+        this.health = SenderHealth.DOWN;
+        this.effectiveMaxAssociations = 1;
+        this.emitHealthChanged(previousHealth);
+      }
+    } else if (this.consecutiveFailures >= DEGRADE_THRESHOLD && this.consecutiveFailures % DEGRADE_THRESHOLD === 0) {
+      if (this.health === SenderHealth.HEALTHY) {
+        this.health = SenderHealth.DEGRADED;
+        this.effectiveMaxAssociations = Math.max(1, Math.floor(this.configuredMaxAssociations / 2));
+        this.emitHealthChanged(previousHealth);
+      } else if (this.health === SenderHealth.DEGRADED) {
+        const newMax = Math.max(1, Math.floor(this.effectiveMaxAssociations / 2));
+        if (newMax !== this.effectiveMaxAssociations) {
+          this.effectiveMaxAssociations = newMax;
+          this.emitHealthChanged(previousHealth);
+        }
+      }
+    }
+  }
+  /** Emits a HEALTH_CHANGED event. */
+  emitHealthChanged(previousHealth) {
+    this.emit("HEALTH_CHANGED", {
+      previousHealth,
+      newHealth: this.health,
+      effectiveMaxAssociations: this.effectiveMaxAssociations,
+      consecutiveFailures: this.consecutiveFailures
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle helpers
+  // -----------------------------------------------------------------------
+  /** Rejects all queued entries with the given message. */
+  rejectQueue(message) {
+    while (this.queue.length > 0) {
+      const entry = this.queue.shift();
+      if (entry === void 0) break;
+      entry.resolve(err(new Error(message)));
+    }
+  }
+  /** Rejects all bucket entries with the given message. */
+  rejectBucket(message) {
+    while (this.currentBucket.length > 0) {
+      const entry = this.currentBucket.shift();
+      if (entry === void 0) break;
+      entry.resolve(err(new Error(message)));
+    }
+  }
+  /** Waits for all active associations to complete. */
+  waitForActive() {
+    if (this.activeAssociations === 0) return Promise.resolve();
+    return new Promise((resolve) => {
+      const check = () => {
+        if (this.activeAssociations === 0) {
+          resolve();
+        } else {
+          setTimeout(check, 50);
+        }
+      };
+      check();
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Abort signal
+  // -----------------------------------------------------------------------
+  /** Wires an AbortSignal to stop the sender. */
+  wireAbortSignal(signal) {
+    if (signal.aborted) {
+      void this.stop();
+      return;
+    }
+    this.abortHandler = () => {
+      void this.stop();
+    };
+    signal.addEventListener("abort", this.abortHandler, { once: true });
+  }
+};
+function delay2(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
 // src/pacs/types.ts
 var QueryLevel = {
   STUDY: "STUDY",
@@ -36566,7 +37092,7 @@ var DEFAULT_CONFIG = {
   signal: void 0,
   onRetry: void 0
 };
-function resolveConfig(opts) {
+function resolveConfig2(opts) {
   if (!opts) return DEFAULT_CONFIG;
   return {
     ...DEFAULT_CONFIG,
@@ -36611,7 +37137,7 @@ function shouldBreakAfterFailure(attempt, lastError, config) {
   return false;
 }
 async function retry(operation, options) {
-  const config = resolveConfig(options);
+  const config = resolveConfig2(options);
   let lastResult = err(new Error("No attempts executed"));
   for (let attempt = 0; attempt < config.maxAttempts; attempt += 1) {
     lastResult = await operation();
@@ -36659,6 +37185,7 @@ exports.DcmtkProcess = DcmtkProcess;
 exports.DicomDataset = DicomDataset;
 exports.DicomInstance = DicomInstance;
 exports.DicomReceiver = DicomReceiver;
+exports.DicomSender = DicomSender;
 exports.DicomTagPathSchema = DicomTagPathSchema;
 exports.DicomTagSchema = DicomTagSchema;
 exports.FilenameMode = FilenameMode;
@@ -36685,6 +37212,8 @@ exports.RetrieveMode = RetrieveMode;
 exports.SOP_CLASSES = SOP_CLASSES;
 exports.STORESCP_FATAL_EVENTS = STORESCP_FATAL_EVENTS;
 exports.STORESCP_PATTERNS = STORESCP_PATTERNS;
+exports.SenderHealth = SenderHealth;
+exports.SenderMode = SenderMode;
 exports.StorageMode = StorageMode;
 exports.StoreSCP = StoreSCP;
 exports.StoreSCPPreset = StoreSCPPreset;