@synanetics/fhir-sort
v1.0.0
Published
A package for sorting fhir resources
Downloads
80
Maintainers
Keywords
Readme
@synanetics/fhir-sort
This package provides an implementation of in memory sorting of FHIR Resources.
Features
- FHIR STU3 and R4.
- Sorting FHIR Bundles and arrays of FHIR resources.
- Custom SearchParameters can be provided in addition to, or replacement of, default SearchParameters
- Specialised sorting on most FHIR complex data types (e.g FHIR.HumanName)
- Chained sort terms, to a single depth
- Sort term validation
Limitations
- The sorter can only sort resources of the same resource type
- A bundles "matches" have the same resource type
- A resources array's values must have the same resource type
- Included resources, whether in a Bundle or includedResources array, can be of any type
- For Bundles, the sorter is designed to just support the searchset type
- The sorter does not follow resource orders that are prescribed in Bundle types
- E.G The message Bundle type which requires MessageHeader in entry[0]
- Note: that such Bundles likely have different resource types, and thus are not supported at all
Example Usage
const {
FhirSorter
} = require('@synanetics/fhir-sort');
// or
import {
FhirSorter
} from '@synanetics/fhir-sort';
const r4Sorter = new FhirSorter('r4');
const stu3Sorter = new FhirSorter('stu3');
const unsortedBundle: Bundle = {
resourceType: 'Bundle',
type: 'searchset',
total: 3,
entry: [
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Mark'],
family: 'South',
}],
},
},
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Rex'],
family: 'Ford',
}],
},
},
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Adam'],
family: 'Ford',
}],
},
},
]
}
const sortedBundle: Bundle = r4Sorter.sortBundle(unsortedBundle, ['name'], 'Patient');
// Expected output
const sortedBundle: Bundle = {
resourceType: 'Bundle',
type: 'searchset',
total: 3,
entry: [
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Adam'],
family: 'Ford',
}],
},
},
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Rex'],
family: 'Ford',
}],
},
},
{
resource: {
resourceType: 'Patient',
name: [{
given: ['Mark'],
family: 'South',
}],
},
},
]
}
FhirSorter Constructor
const sorter = new FhirSorter(fhirVersion, customSearchParameters, fhirModel);
Arguments
fhirVersion
- String, either 'stu3 or 'r4'
- Used to determine default SearchParameters and FHIR model
customSearchParameters
- This is an optional argument if it is not provided the default SearchParameters for the selected FHIR version will be used
- Object containing fields mode and searchParameters
- mode: String, either 'replace' or 'concat'
- searchParameters: an array of FHIR SearchParameter resources
- When mode = replace, the provided SearchParameters will be used instead of the default SearchParameters
- When mode = concat, the provided SearchParameters will be used in addition to the SearchParameters
fhirModel
- FhirModels are defined in the fhirpath npm package
- See: https://www.npmjs.com/package/fhirpath
- It is utilised by the package to determine the type of an evaluated value
- Example Patient.name = FHIR.HumanName
- This is an optional argument if it is not provided the default FhirModel for the selected FHIR version will be used
- This package supports custom FhirModels, but does not support combining custom and default FhirModels
- It is intended that future versions of this package will not rely on user knowledge of this third party interface
FhirSorter.sortArray
const sorted = sorter.sortArray(resources, sortTerms, resourceType, allowChainedSort, includedResources);
Arguments
resources
- An unsorted array of FHIR resources to be sorted
sortTerms
- An array of strings where each string is SearchParameter code
- e.g ['name', '_lastUpdated']
- By default the sort order is ascending
- A sort term can be prefixed with - to make the sort order descending
- e.g ['-name', '-_lastUpdated']
- If a SearchParameter related to a sort term cannot be found, an error will be thrown
resourceType
- A string which is the resourceType that is to be sorted
- e.g 'Patient'
allowChainedSort
- allowChainedSort is a boolean that defaults to false
- If it is true then sorting on chained sort terms is allowed
includedResources
- This is an optional argument that is only required for chained sorts
- includedResources is an array of FHIR resources that would be 'included' in the Bundle response of a FHIR search query
Return value
- This function returns a sorted array of FHIR resources
FhirSorter.sortBundle
const sorted = sorter.sortBundle(bundle, sortTerms, resourceType, allowChainedSort);
Arguments
bundle
- An unsorted FHIR Bundle resources
- The entries to be sorted are expected to have search.mode = match
sortTerms
- An array of strings where each string is SearchParameter code
- e.g ['name', '_lastUpdated']
- By default the sort order is ascending
- A sort term can be prefixed with - to make the sort order descending
- e.g ['-name', '-_lastUpdated']
- If a SearchParameter related to a sor term cannot be found, an error will be thrown
resourceType
- A string which is the resourceType that is to be sorted
- e.g 'Patient'
allowChainedSort
- allowChainedSort is a boolean that defaults to false
- If it is true then sorting on chained sort terms is allowed
Return value
- This function the input bundle with its matched entries sorted
Chained Sorting
- Chained sorting is not part of the default FHIR specification however it is supported here to a single depth
- To perform a chained sort, pass in a chained sort term, and set allowChainedSort to true
- e.g chained sort term for Patient resource: 'general-practitioner.name'
- With this example sort term, the sorter would sort Patients based on their general practitioner's name
- Note that a general practitioner could be a Practitioner, Organization or PractitionerRole
- A sort term that is valid for one may not be valid for others. E.G 'family' is only a valid sort term for Practitioner
- The sorter will allow any chained sort term as long as it is valid at least one of of the possible resource types
- The sorter will attempt to resolve the sort using resources "included" in the input Bundle for sortBundle, or the includedResources array for sortArray
- For the sorter to find the appropriate included resource, it must be referenced in the base resource with a relative reference
- e.g 'Practitioner/12345'
- If a chained sort term is passed in, and the allowChainedSort argument is false, an error will be thrown
- If a chained sort term with depth > 1 is passed in an error will be thrown
- e.g 'general-practitioner.partof.name'
How Values Are Sorted
Multiple Values
- If a given field has multiple possible values, such as Patient.family, the most 'favourable' value is taken
- e.g when sorting if a patient had three names with family values: 'Banana', 'Pear' and 'Apple:
- 'Apple' would be used in the final sort when sorting ascending.
- 'Pear' would be used in the final sort when sorting descending.
Undefined values
- Undefined values will always appear at the end of the sort regardless of sort order
Normalising DataTypes
All data types are normalised before sorting, and then sorted based upon their sort order