@openmrs/esm-framework 6.3.1-pre.3106 → 6.3.1-pre.3124

package/docs/functions/displayName.md

@@ -0,0 +1,21 @@
+[O3 Framework](../API.md) / displayName
+
+# Function: ~~displayName()~~
+
+> **displayName**(`patient`): `string`
+
+Defined in: packages/framework/esm-utils/dist/patient-helpers.d.ts:14
+
+## Parameters
+
+### patient
+
+`Patient`
+
+## Returns
+
+`string`
+
+## Deprecated
+
+Use `getPatientName`

package/docs/functions/evaluate.md

@@ -0,0 +1,84 @@
+[O3 Framework](../API.md) / evaluate
+
+# Function: evaluate()
+
+> **evaluate**(`expression`, `variables`): [`DefaultEvaluateReturnType`](../type-aliases/DefaultEvaluateReturnType.md)
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:97](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L97)
+
+`evaluate()` implements a relatively safe version of `eval()` that is limited to evaluating synchronous
+Javascript expressions. This allows us to safely add features that depend on user-supplied code without
+polluting the global namespace or needing to support `eval()` and the like.
+
+By default it supports any expression that evalutes to a string, number, boolean, Date, null, or undefined.
+Other values will result in an error.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+[`DefaultEvaluateReturnType`](../type-aliases/DefaultEvaluateReturnType.md)
+
+The result of evaluating the expression
+
+## Examples
+
+```ts
+// shouldDisplayOptionalData will be false
+const shouldDisplayOptionalData = evaluate('!isEmpty(array)', {
+ array: [],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+})
+```
+
+Since this only implements the expression lanaguage part of Javascript, there is no support for assigning
+values, creating functions, or creating objects, so the following will throw an error:
+
+```ts
+evaluate('var a = 1; a');
+```
+
+In addition to string expressions, `evaluate()` can use an existing `jsep.Expression`, such as that returned
+from the `compile()` function. The goal here is to support cases where the same expression will be evaluated
+multiple times, possibly with different variables, e.g.,
+
+```ts
+const expr = compile('isEmpty(array)');
+
+// then we use it like
+evaluate(expr, {
+ array: [],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+));
+
+evaluate(expr, {
+ array: ['value'],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+));
+```
+
+This saves the overhead of parsing the expression everytime and simply allows us to evaluate it.
+
+The `variables` parameter should be used to supply any variables or functions that should be in-scope for
+the evaluation. A very limited number of global objects, like NaN and Infinity are always available, but
+any non-global values will need to be passed as a variable. Note that expressions do not have any access to
+the variables in the scope in which they were defined unless they are supplied here.

package/docs/functions/evaluateAsBoolean.md

@@ -0,0 +1,31 @@
+[O3 Framework](../API.md) / evaluateAsBoolean
+
+# Function: evaluateAsBoolean()
+
+> **evaluateAsBoolean**(`expression`, `variables`): `boolean`
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:180](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L180)
+
+`evaluateAsBoolean()` is a variant of [()](evaluate.md) which only supports boolean results. Useful
+if valid expression must return boolean values.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+`boolean`
+
+The result of evaluating the expression

package/docs/functions/evaluateAsBooleanAsync.md

@@ -0,0 +1,31 @@
+[O3 Framework](../API.md) / evaluateAsBooleanAsync
+
+# Function: evaluateAsBooleanAsync()
+
+> **evaluateAsBooleanAsync**(`expression`, `variables`): `Promise`\<`boolean`\>
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:193](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L193)
+
+`evaluateAsBooleanAsync()` is a variant of [()](evaluateAsync.md) which only supports boolean results. Useful
+if valid expression must return boolean values.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+The result of evaluating the expression

package/docs/functions/evaluateAsNumber.md

@@ -0,0 +1,31 @@
+[O3 Framework](../API.md) / evaluateAsNumber
+
+# Function: evaluateAsNumber()
+
+> **evaluateAsNumber**(`expression`, `variables`): `number`
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:206](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L206)
+
+`evaluateAsNumber()` is a variant of [()](evaluate.md) which only supports number results. Useful
+if valid expression must return numeric values.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+`number`
+
+The result of evaluating the expression

package/docs/functions/evaluateAsNumberAsync.md

@@ -0,0 +1,31 @@
+[O3 Framework](../API.md) / evaluateAsNumberAsync
+
+# Function: evaluateAsNumberAsync()
+
+> **evaluateAsNumberAsync**(`expression`, `variables`): `Promise`\<`number`\>
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:219](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L219)
+
+`evaluateAsNumberAsync()` is a variant of [()](evaluateAsync.md) which only supports number results. Useful
+if valid expression must return numeric values.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+`Promise`\<`number`\>
+
+The result of evaluating the expression

package/docs/functions/evaluateAsType.md

@@ -0,0 +1,46 @@
+[O3 Framework](../API.md) / evaluateAsType
+
+# Function: evaluateAsType()
+
+> **evaluateAsType**\<`T`\>(`expression`, `variables`, `typePredicate`): `T`
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:236](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L236)
+
+`evaluateAsType()` is a type-safe version of [()](evaluate.md) which returns a result if the result
+passes a custom type predicate. The main use-case for this is to narrow the return types allowed based on
+context, e.g., if the expected result should be a number or boolean, you can supply a custom type-guard
+to ensure that only number or boolean results are returned.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+### typePredicate
+
+(`result`) => `result is T`
+
+A [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates)
+ which asserts that the result value matches one of the expected results.
+
+## Returns
+
+`T`
+
+The result of evaluating the expression

package/docs/functions/evaluateAsTypeAsync.md

@@ -0,0 +1,46 @@
+[O3 Framework](../API.md) / evaluateAsTypeAsync
+
+# Function: evaluateAsTypeAsync()
+
+> **evaluateAsTypeAsync**\<`T`\>(`expression`, `variables`, `typePredicate`): `Promise`\<`T`\>
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:278](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L278)
+
+`evaluateAsTypeAsync()` is a type-safe version of [()](evaluateAsync.md) which returns a result if the result
+passes a custom type predicate. The main use-case for this is to narrow the return types allowed based on
+context, e.g., if the expected result should be a number or boolean, you can supply a custom type-guard
+to ensure that only number or boolean results are returned.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+### typePredicate
+
+(`result`) => `result is T`
+
+A [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates)
+ which asserts that the result value matches one of the expected results.
+
+## Returns
+
+`Promise`\<`T`\>
+
+The result of evaluating the expression

package/docs/functions/evaluateAsync.md

@@ -0,0 +1,87 @@
+[O3 Framework](../API.md) / evaluateAsync
+
+# Function: evaluateAsync()
+
+> **evaluateAsync**(`expression`, `variables`): `Promise`\<[`DefaultEvaluateReturnType`](../type-aliases/DefaultEvaluateReturnType.md)\>
+
+Defined in: [packages/framework/esm-expression-evaluator/src/evaluator.ts:167](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/evaluator.ts#L167)
+
+`evaluateAsync()` implements a relatively safe version of `eval()` that can evaluate Javascript expressions
+that use Promises. This allows us to safely add features that depend on user-supplied code without
+polluting the global namespace or needing to support `eval()` and the like.
+
+By default it supports any expression that evalutes to a string, number, boolean, Date, null, or undefined.
+Other values will result in an error.
+
+## Parameters
+
+### expression
+
+The expression to evaluate, either as a string or pre-parsed expression
+
+`string` | `Expression`
+
+### variables
+
+[`VariablesMap`](../type-aliases/VariablesMap.md) = `{}`
+
+Optional object which contains any variables, functions, etc. that will be available to
+ the expression.
+
+## Returns
+
+`Promise`\<[`DefaultEvaluateReturnType`](../type-aliases/DefaultEvaluateReturnType.md)\>
+
+The result of evaluating the expression
+
+## Examples
+
+```ts
+// shouldDisplayOptionalData will be false
+const shouldDisplayOptionalData = await evaluateAsync('Promise.resolve(!isEmpty(array))', {
+ array: [],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+})
+```
+
+Since this only implements the expression lanaguage part of Javascript, there is no support for assigning
+values, creating functions, or creating objects, so the following will throw an error:
+
+```ts
+evaluateAsync('var a = 1; a');
+```
+
+In addition to string expressions, `evaluate()` can use an existing `jsep.Expression`, such as that returned
+from the `compile()` function. The goal here is to support cases where the same expression will be evaluated
+multiple times, possibly with different variables, e.g.,
+
+```ts
+const expr = compile('Promise.resolve(isEmpty(array))');
+
+// then we use it like
+evaluateAsync(expr, {
+ array: [],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+));
+
+evaluateAsync(expr, {
+ array: ['value'],
+ isEmpty(arr: unknown) {
+  return Array.isArray(arr) && arr.length === 0;
+ }
+));
+```
+
+This saves the overhead of parsing the expression everytime and simply allows us to evaluate it.
+
+The `variables` parameter should be used to supply any variables or functions that should be in-scope for
+the evaluation. A very limited number of global objects, like NaN and Infinity are always available, but
+any non-global values will need to be passed as a variable. Note that expressions do not have any access to
+the variables in the scope in which they were defined unless they are supplied here.
+
+**Note:** `evaluateAsync()` currently only supports Promise-based asynchronous flows and does not support
+the `await` keyword.

package/docs/functions/extractVariableNames.md

@@ -0,0 +1,50 @@
+[O3 Framework](../API.md) / extractVariableNames
+
+# Function: extractVariableNames()
+
+> **extractVariableNames**(`expression`): `string`[]
+
+Defined in: [packages/framework/esm-expression-evaluator/src/extractor.ts:44](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-expression-evaluator/src/extractor.ts#L44)
+
+`extractVariableNames()` is a companion function for `evaluate()` and `evaluateAsync()` which extracts the
+names of all unbound identifiers used in the expression. The idea is to be able to extract all of the names
+of variables that will need to be supplied in order to correctly process the expression.
+
+## Parameters
+
+### expression
+
+`string` | `Expression`
+
+## Returns
+
+`string`[]
+
+## Examples
+
+```ts
+// variables will be ['isEmpty', 'array']
+const variables = extractVariableNames('!isEmpty(array)')
+```
+
+An identifier is considered "unbound" if it is not a reference to the property of an object, is not defined
+as a parameter to an inline arrow function, and is not a global value. E.g.,
+
+```ts
+// variables will be ['obj']
+const variables = extractVariableNames('obj.prop()')
+```
+
+```ts
+// variables will be ['arr', 'needle']
+const variables = extractVariableNames('arr.filter(v => v === needle)')
+```
+
+```ts
+// variables will be ['myVar']
+const  variables = extractVariableNames('new String(myVar)')
+```
+
+Note that because this expression evaluator uses a restricted definition of "global" there are some Javascript
+globals that will be reported as a unbound expression. This is expected because the evaluator will still fail
+on these expressions.

package/docs/functions/fetchCurrentPatient.md

@@ -0,0 +1,25 @@
+[O3 Framework](../API.md) / fetchCurrentPatient
+
+# Function: fetchCurrentPatient()
+
+> **fetchCurrentPatient**(`patientUuid`, `fetchInit?`, `includeOfflinePatients?`): `Promise`\<`null` \| `Patient`\>
+
+Defined in: [packages/framework/esm-emr-api/src/current-patient.ts:21](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-emr-api/src/current-patient.ts#L21)
+
+## Parameters
+
+### patientUuid
+
+[`PatientUuid`](../type-aliases/PatientUuid.md)
+
+### fetchInit?
+
+`FetchConfig`
+
+### includeOfflinePatients?
+
+`boolean` = `true`
+
+## Returns
+
+`Promise`\<`null` \| `Patient`\>

package/docs/functions/filterBreadcrumbs.md

@@ -0,0 +1,21 @@
+[O3 Framework](../API.md) / filterBreadcrumbs
+
+# Function: filterBreadcrumbs()
+
+> **filterBreadcrumbs**(`list`, `path`): [`BreadcrumbRegistration`](../interfaces/BreadcrumbRegistration.md)[]
+
+Defined in: [packages/framework/esm-navigation/src/breadcrumbs/filter.ts:34](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-navigation/src/breadcrumbs/filter.ts#L34)
+
+## Parameters
+
+### list
+
+[`BreadcrumbRegistration`](../interfaces/BreadcrumbRegistration.md)[]
+
+### path
+
+`string`
+
+## Returns
+
+[`BreadcrumbRegistration`](../interfaces/BreadcrumbRegistration.md)[]

package/docs/functions/formatDate.md

@@ -0,0 +1,39 @@
+[O3 Framework](../API.md) / formatDate
+
+# Function: formatDate()
+
+> **formatDate**(`date`, `options?`): `string`
+
+Defined in: packages/framework/esm-utils/dist/dates/date-util.d.ts:124
+
+Formats the input date according to the current locale and the
+given options.
+
+Default options:
+ - mode: "standard",
+ - time: "for today",
+ - day: true,
+ - month: true,
+ - year: true
+ - noToday: false
+
+If the date is today then "Today" is produced (in the locale language).
+This behavior can be disabled with `noToday: true`.
+
+When time is included, it is appended with a comma and a space. This
+agrees with the output of `Date.prototype.toLocaleString` for *most*
+locales.
+
+## Parameters
+
+### date
+
+`Date`
+
+### options?
+
+`Partial`\<[`FormatDateOptions`](../type-aliases/FormatDateOptions.md)\>
+
+## Returns
+
+`string`

package/docs/functions/formatDatetime.md

@@ -0,0 +1,29 @@
+[O3 Framework](../API.md) / formatDatetime
+
+# Function: formatDatetime()
+
+> **formatDatetime**(`date`, `options?`): `string`
+
+Defined in: packages/framework/esm-utils/dist/dates/date-util.d.ts:139
+
+Formats the input into a string showing the date and time, according
+to the current locale. The `mode` parameter is as described for
+`formatDate`.
+
+This is created by concatenating the results of `formatDate`
+and `formatTime` with a comma and space. This agrees with the
+output of `Date.prototype.toLocaleString` for *most* locales.
+
+## Parameters
+
+### date
+
+`Date`
+
+### options?
+
+`Partial`\<`Omit`\<[`FormatDateOptions`](../type-aliases/FormatDateOptions.md), `"time"`\>\>
+
+## Returns
+
+`string`

package/docs/functions/formatPartialDate.md

@@ -0,0 +1,39 @@
+[O3 Framework](../API.md) / formatPartialDate
+
+# Function: formatPartialDate()
+
+> **formatPartialDate**(`dateString`, `options?`): `null` \| `string`
+
+Defined in: packages/framework/esm-utils/dist/dates/date-util.d.ts:104
+
+Formats the string representing a date, including partial representations of dates, according to the current
+locale and the given options.
+
+Default options:
+ - mode: "standard",
+ - time: "for today",
+ - day: true,
+ - month: true,
+ - year: true
+ - noToday: false
+
+If the date is today then "Today" is produced (in the locale language).
+This behavior can be disabled with `noToday: true`.
+
+When time is included, it is appended with a comma and a space. This
+agrees with the output of `Date.prototype.toLocaleString` for *most*
+locales.
+
+## Parameters
+
+### dateString
+
+`string`
+
+### options?
+
+`Partial`\<[`FormatDateOptions`](../type-aliases/FormatDateOptions.md)\>
+
+## Returns
+
+`null` \| `string`

package/docs/functions/formatPatientName.md

@@ -0,0 +1,23 @@
+[O3 Framework](../API.md) / formatPatientName
+
+# Function: formatPatientName()
+
+> **formatPatientName**(`name`): `string`
+
+Defined in: packages/framework/esm-utils/dist/patient-helpers.d.ts:20
+
+Get a formatted display string for an FHIR name.
+
+## Parameters
+
+### name
+
+The name to be formatted.
+
+`undefined` | `HumanName`
+
+## Returns
+
+`string`
+
+The formatted display name or an empty string if name is undefined.

package/docs/functions/formatTime.md

@@ -0,0 +1,20 @@
+[O3 Framework](../API.md) / formatTime
+
+# Function: formatTime()
+
+> **formatTime**(`date`): `string`
+
+Defined in: packages/framework/esm-utils/dist/dates/date-util.d.ts:129
+
+Formats the input as a time, according to the current locale.
+12-hour or 24-hour clock depends on locale.
+
+## Parameters
+
+### date
+
+`Date`
+
+## Returns
+
+`string`