dicom-curate 0.34.0 → 0.36.0

package/README.md

@@ -113,6 +113,31 @@ It is also possible to use S3-compatible buckets as input or output locations.
 Consult `OrganizeOptions` for further details. Please note that this feature is only
 available if you have the `@aws-sdk/client-s3` package installed.
 
+### Matching S3 ETags across uploaders
+
+When uploading to S3, you can set `uploadPartSize` on the output S3
+options to control the ETag S3 assigns to the written object:
+
+```ts
+const options: OrganizeOptions = {
+  // other options are skipped
+  outputEndpoint: {
+    bucketName: 'my-bucket',
+    region: 'us-east-1',
+    // Bodies <= 5 MB: single PUT, S3 returns a plain-MD5 ETag.
+    // Bodies  > 5 MB: multipart, S3 returns a composite "<md5>-<N>" ETag.
+    uploadPartSize: 5 * 1024 * 1024,
+  },
+}
+```
+
+This matches the ETag convention produced by any S3 client that uses
+`@aws-sdk/lib-storage` at the same `partSize`, making cross-bucket
+"equal bytes ⇒ equal ETag" comparisons well-defined.
+
+When `uploadPartSize` is omitted, all uploads go through a single PUT
+regardless of body size and S3 always returns a plain-MD5 ETag.
+
 This library can now automatically skip writing (or uploading) mapped files if the provided
 "previous" input file attributes match the record you pass in the `fileInfoIndex` property:
 
@@ -287,6 +312,64 @@ export function sampleBatchCurationSpecification(): TCurationSpecification {
 }
 ```
 
+## Excluding files with preExclude and postExclude
+
+The curation specification supports two optional exclusion functions that let you skip files at different stages of processing. Both return **`true` to exclude** the file; returning `false` (or omitting the function entirely) lets the file through.
+
+### preExclude — skip before mapping
+
+`preExclude` receives a `parser` with access to the **original, unmapped DICOM tags**. Return `true` to skip the file entirely — it will not be mapped, written, or uploaded.
+
+```ts
+export function myCurationSpec(): TCurationSpecification {
+  return {
+    // ... other fields ...
+
+    // Exclude files whose PatientID doesn't match the expected study format.
+    preExclude(parser) {
+      return !/^AB\d{2}-\d{3}$/.test(parser.getDicom('PatientID'))
+    },
+  }
+}
+```
+
+### postExclude — skip after mapping
+
+`postExclude` receives a `parser` whose `getDicom()` returns **de-identified tag values** (PS315E de-identification has already run at this point), and exposes the computed output path as `parser.outputFilePath`. Return `true` to skip writing or uploading the mapped file.
+
+Note: `parser.getFilePathComp()` still returns **input** path components inside `postExclude`, the same as in `preExclude`. Only `parser.outputFilePath` reflects the post-mapping location, as a full string.
+
+```ts
+export function myCurationSpec(): TCurationSpecification {
+  return {
+    // ... other fields ...
+
+    // Exclude structured reports and files routed to an 'exclude' output folder.
+    postExclude(parser) {
+      if (parser.getDicom('Modality') === 'SR') return true
+      if (parser.outputFilePath.includes('/exclude/')) return true
+      return false
+    },
+  }
+}
+```
+
+### Behaviour notes
+
+- **Exclusions are re-evaluated on every run.** When a `preExclude` or `postExclude` is configured, the "unchanged source bytes" short-circuit is disabled so an exclusion added in a later run takes effect even if the file itself didn't change.
+- **Composition across multiple specs is OR.** When `composeSpecs` merges specs that each define `preExclude` / `postExclude`, the composed function excludes a file if **any** spec's function returns `true`. Evaluation short-circuits on the first `true`.
+- **Exceptions are fail-safe.** If an exclusion function throws, the file is treated as **included** and the error message is appended to `mapResults.errors`.
+
+### Result shape
+
+When a file is excluded, `curateOne` / `curateMany` still returns a result object for it. The `excluded` field indicates which function rejected it:
+
+```ts
+// 'pre'  — excluded by preExclude (file was never mapped)
+// 'post' — excluded by postExclude (file was mapped but not written)
+result.excluded // => 'pre' | 'post' | undefined
+```
+
 ## DICOM Conformance Notes
 
 dicom-curate