Skip to main content

$safe

$safe(function?) -> function
Compact type signature<f-:f>

If function is omitted, the current context value is used.

Browse categories
Functions That Use Other FunctionsDiagnostics And Errors
Execution
Works with async supplied functions

Source: FUME

Availability​

Community v3.2.0+
Enterprise v3.2.0+

Documentation​

$safe() wraps a function and returns another function that never throws to the expression author.

The returned function preserves the original call style, forwards its received arguments exactly once, and works with built-in functions, inline functions, saved mappings, and async functions.

  • On success, the result includes ok: true and result.
  • On failure, the result includes ok: false and error.

error is sanitized before it is exposed. When those fields are available, the public error object can include code, message, sourceMessage, sourceErrorCode, status, request, and operationOutcome.

sourceMessage and sourceErrorCode are most useful when FUME catches an error from another layer and wraps it in a FUME error. In that case, code and message describe the public FUME error, while sourceErrorCode and sourceMessage preserve the original details from the underlying error.

The examples below show both cases. The saved-mapping example shows different values, while the no-match example shows a case where the public and preserved details happen to be the same.

Examples​

Wrap a FHIR lookup and keep the result shape explicit​

Input

This example uses the patient-summary example input. The expression wraps $searchSingle() once, then returns a structured success result instead of throwing.

Example input

JSON
{
  "patientId": "pat-0001",
  "name": {
    "given": "Avery",
    "family": "Reed",
    "display": "Avery Reed"
  },
  "birthDate": "1990-06-12",
  "sex": "female",
  "primaryCareTeam": {
    "organization": "ExampleCare",
    "facility": "ExampleCare Clinic",
    "practitioner": {
      "practitionerId": "prac-4001",
      "display": "Jordan Kim"
    }
  },
  "identifiers": {
    "memberId": "mbr-3001",
    "recordNumber": "rec-5001"
  },
  "tags": [
    "demo",
    "fictional"
  ],
  "_xmlTagName": "patientSummary"
}

Expression

(
  $safeSearchSingle := $searchSingle.$safe();
  $safeSearchSingle(
    "Patient",
    {"identifier": "http://fhir.acme.health/identifier/member-id|" & identifiers.memberId}
  )
)

Result

{
  "ok": true,
  "result": {
    "resourceType": "Patient",
    "id": "pat-0001"
  }
}

Wrap a FHIR lookup that returns no matches​

Input

This example uses the same patient-summary example input, but changes the searched identifier so the lookup returns no matches.

Example input

JSON
{
  "patientId": "pat-0001",
  "name": {
    "given": "Avery",
    "family": "Reed",
    "display": "Avery Reed"
  },
  "birthDate": "1990-06-12",
  "sex": "female",
  "primaryCareTeam": {
    "organization": "ExampleCare",
    "facility": "ExampleCare Clinic",
    "practitioner": {
      "practitionerId": "prac-4001",
      "display": "Jordan Kim"
    }
  },
  "identifiers": {
    "memberId": "mbr-3001",
    "recordNumber": "rec-5001"
  },
  "tags": [
    "demo",
    "fictional"
  ],
  "_xmlTagName": "patientSummary"
}

Expression

(
  $safeSearchSingle := $searchSingle.$safe();
  $safeSearchSingle(
    "Patient",
    {"identifier": "http://fhir.acme.health/identifier/member-id|" & identifiers.memberId & "-missing"}
  )
)

Result

{
  "ok": false,
  "error": {
    "code": "F5211",
    "message": "Search for \"Patient\" with parameters \"{\\\"identifier\\\":\\\"http://fhir.acme.health/identifier/member-id|mbr-3001-missing\\\"}\" returned no results",
    "sourceMessage": "Search for \"Patient\" with parameters \"{\\\"identifier\\\":\\\"http://fhir.acme.health/identifier/member-id|mbr-3001-missing\\\"}\" returned no results",
    "sourceErrorCode": "F5211"
  }
}

Wrap a saved mapping that fails to parse​

In this example, invalidMapping is a saved mapping whose expression contains a syntax error. $safe() still returns a normal result object, and this time the public and preserved error fields are different.

Expression

$safe($invalidMapping)("hello")

Result

{
  "ok": false,
  "error": {
    "code": "F3002",
    "message": "Failed to parse mapping \"invalidMapping\": Syntax error: symbol \"+\" used in a place where it is not allowed",
    "sourceMessage": "Syntax error: symbol \"+\" used in a place where it is not allowed",
    "sourceErrorCode": "S0211"
  }
}

Here, code and message describe the public FUME error for the saved mapping, while sourceErrorCode and sourceMessage preserve the original parser failure that caused it.