@openmrs/esm-utils 3.1.10-pre.97 → 3.1.11-pre.595

package/docs/API.md

@@ -4,14 +4,23 @@
 
 ## Table of contents
 
+### Interfaces
+
+- [RetryOptions](interfaces/RetryOptions.md)
+
 ### Type aliases
 
 - [DateInput](API.md#dateinput)
 
 ### Functions
 
+- [age](API.md#age)
+- [daysIntoYear](API.md#daysintoyear)
 - [isOmrsDateStrict](API.md#isomrsdatestrict)
 - [isOmrsDateToday](API.md#isomrsdatetoday)
+- [isSameDay](API.md#issameday)
+- [isVersionSatisfied](API.md#isversionsatisfied)
+- [retry](API.md#retry)
 - [toDateObjectStrict](API.md#todateobjectstrict)
 - [toOmrsDateFormat](API.md#toomrsdateformat)
 - [toOmrsDayDateFormat](API.md#toomrsdaydateformat)
@@ -19,174 +28,367 @@
 - [toOmrsTimeString](API.md#toomrstimestring)
 - [toOmrsTimeString24](API.md#toomrstimestring24)
 - [toOmrsYearlessDateFormat](API.md#toomrsyearlessdateformat)
+- [translateFrom](API.md#translatefrom)
 
 ## Type aliases
 
 ### DateInput
 
-Ƭ **DateInput**: *string* \| *number* \| Date
+Ƭ **DateInput**: `string` \| `number` \| `Date`
+
+#### Defined in
 
-Defined in: [omrs-dates.ts:8](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L8)
+[omrs-dates.ts:8](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L8)
 
 ## Functions
 
+### age
+
+▸ **age**(`dateString`): `string`
+
+Gets a human readable age represention of the provided date string.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `dateString` | `string` | The stringified date. |
+
+#### Returns
+
+`string`
+
+A human-readable string version of the age.
+
+#### Defined in
+
+[age-helpers.tsx:37](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/age-helpers.tsx#L37)
+
+___
+
+### daysIntoYear
+
+▸ **daysIntoYear**(`date`): `number`
+
+Gets the number of days in the year of the given date.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `date` | `Date` | The date to compute the days within the year. |
+
+#### Returns
+
+`number`
+
+The number of days.
+
+#### Defined in
+
+[age-helpers.tsx:6](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/age-helpers.tsx#L6)
+
+___
+
 ### isOmrsDateStrict
 
-▸ **isOmrsDateStrict**(`omrsPayloadString`: *string*): *boolean*
+▸ **isOmrsDateStrict**(`omrsPayloadString`): `boolean`
 
 This function is STRICT on checking whether a date string is the openmrs format.
 The format should be YYYY-MM-DDTHH:mm:ss.SSSZZ
 
-#### Parameters:
+#### Parameters
 
-Name | Type |
-:------ | :------ |
-`omrsPayloadString` | *string* |
+| Name | Type |
+| :------ | :------ |
+| `omrsPayloadString` | `string` |
 
-**Returns:** *boolean*
+#### Returns
 
-Defined in: [omrs-dates.ts:16](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L16)
+`boolean`
+
+#### Defined in
+
+[omrs-dates.ts:16](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L16)
 
 ___
 
 ### isOmrsDateToday
 
-▸ **isOmrsDateToday**(`date`: [*DateInput*](API.md#dateinput)): *boolean*
+▸ **isOmrsDateToday**(`date`): `boolean`
+
+#### Parameters
 
-#### Parameters:
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | Checks if the provided date is today. |
 
-Name | Type | Description |
-:------ | :------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) | Checks if the provided date is today.    |
+#### Returns
 
-**Returns:** *boolean*
+`boolean`
 
-Defined in: [omrs-dates.ts:53](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L53)
+#### Defined in
+
+[omrs-dates.ts:53](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L53)
+
+___
+
+### isSameDay
+
+▸ **isSameDay**(`firstDate`, `secondDate`): `boolean`
+
+Checks if two dates are representing the same day.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `firstDate` | `Date` | The first date. |
+| `secondDate` | `Date` | The second date. |
+
+#### Returns
+
+`boolean`
+
+True if both are located on the same day.
+
+#### Defined in
+
+[age-helpers.tsx:23](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/age-helpers.tsx#L23)
+
+___
+
+### isVersionSatisfied
+
+▸ **isVersionSatisfied**(`requiredVersion`, `installedVersion`): `boolean`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `requiredVersion` | `string` |
+| `installedVersion` | `string` |
+
+#### Returns
+
+`boolean`
+
+#### Defined in
+
+[version.ts:21](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/version.ts#L21)
+
+___
+
+### retry
+
+▸ **retry**<`T`\>(`fn`, `options?`): `Promise`<`T`\>
+
+Executes the specified function and retries executing on failure with a custom backoff strategy
+defined by the options.
+
+If not configured otherwise, this function uses the following default options:
+* Retries 5 times beyond the initial attempt.
+* Uses an exponential backoff starting with an initial delay of 1000ms.
+
+**`throws`** Rethrows the final error of running `fn` when the function stops retrying.
+
+#### Type parameters
+
+| Name |
+| :------ |
+| `T` |
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `fn` | () => `Promise`<`T`\> | The function to be executed and retried on failure. |
+| `options` | [`RetryOptions`](interfaces/RetryOptions.md) | Additional options which configure the retry behavior. |
+
+#### Returns
+
+`Promise`<`T`\>
+
+The result of successfully executing `fn`.
+
+#### Defined in
+
+[retry.ts:38](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/retry.ts#L38)
 
 ___
 
 ### toDateObjectStrict
 
-▸ **toDateObjectStrict**(`omrsDateString`: *string*): Date \| *null*
+▸ **toDateObjectStrict**(`omrsDateString`): `Date` \| ``null``
 
 Converts the object to a date object if it is a valid ISO date time string.
 
-#### Parameters:
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `omrsDateString` | `string` |
 
-Name | Type |
-:------ | :------ |
-`omrsDateString` | *string* |
+#### Returns
 
-**Returns:** Date \| *null*
+`Date` \| ``null``
 
-Defined in: [omrs-dates.ts:60](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L60)
+#### Defined in
+
+[omrs-dates.ts:60](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L60)
 
 ___
 
 ### toOmrsDateFormat
 
-▸ **toOmrsDateFormat**(`date`: [*DateInput*](API.md#dateinput), `format?`: *string*): *string*
+▸ **toOmrsDateFormat**(`date`, `format?`): `string`
 
 Formats the input as a date string. By default the format "YYYY-MMM-DD" is used.
 
-#### Parameters:
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | `undefined` |
+| `format` | `string` | `"YYYY-MMM-DD"` |
+
+#### Returns
 
-Name | Type | Default value |
-:------ | :------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) | - |
-`format` | *string* | "YYYY-MMM-DD" |
+`string`
 
-**Returns:** *string*
+#### Defined in
 
-Defined in: [omrs-dates.ts:112](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L112)
+[omrs-dates.ts:112](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L112)
 
 ___
 
 ### toOmrsDayDateFormat
 
-▸ **toOmrsDayDateFormat**(`date`: [*DateInput*](API.md#dateinput)): *string*
+▸ **toOmrsDayDateFormat**(`date`): `string`
 
 Formats the input as a date string using the format "DD - MMM - YYYY".
 
-#### Parameters:
+#### Parameters
 
-Name | Type |
-:------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) |
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
 
-**Returns:** *string*
+#### Returns
 
-Defined in: [omrs-dates.ts:98](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L98)
+`string`
+
+#### Defined in
+
+[omrs-dates.ts:98](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L98)
 
 ___
 
 ### toOmrsIsoString
 
-▸ **toOmrsIsoString**(`date`: [*DateInput*](API.md#dateinput), `toUTC?`: *boolean*): *string*
+▸ **toOmrsIsoString**(`date`, `toUTC?`): `string`
 
 Formats the input as a date time string using the format "YYYY-MM-DDTHH:mm:ss.SSSZZ".
 
-#### Parameters:
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | `undefined` |
+| `toUTC` | `boolean` | `false` |
 
-Name | Type | Default value |
-:------ | :------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) | - |
-`toUTC` | *boolean* | false |
+#### Returns
 
-**Returns:** *string*
+`string`
 
-Defined in: [omrs-dates.ts:71](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L71)
+#### Defined in
+
+[omrs-dates.ts:71](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L71)
 
 ___
 
 ### toOmrsTimeString
 
-▸ **toOmrsTimeString**(`date`: [*DateInput*](API.md#dateinput)): *string*
+▸ **toOmrsTimeString**(`date`): `string`
 
 Formats the input as a time string using the format "HH:mm A".
 
-#### Parameters:
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
+
+#### Returns
 
-Name | Type |
-:------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) |
+`string`
 
-**Returns:** *string*
+#### Defined in
 
-Defined in: [omrs-dates.ts:91](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L91)
+[omrs-dates.ts:91](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L91)
 
 ___
 
 ### toOmrsTimeString24
 
-▸ **toOmrsTimeString24**(`date`: [*DateInput*](API.md#dateinput)): *string*
+▸ **toOmrsTimeString24**(`date`): `string`
 
 Formats the input as a time string using the format "HH:mm".
 
-#### Parameters:
+#### Parameters
 
-Name | Type |
-:------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) |
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
 
-**Returns:** *string*
+#### Returns
 
-Defined in: [omrs-dates.ts:84](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L84)
+`string`
+
+#### Defined in
+
+[omrs-dates.ts:84](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L84)
 
 ___
 
 ### toOmrsYearlessDateFormat
 
-▸ **toOmrsYearlessDateFormat**(`date`: [*DateInput*](API.md#dateinput)): *string*
+▸ **toOmrsYearlessDateFormat**(`date`): `string`
 
 Formats the input as a date string using the format "DD-MMM".
 
-#### Parameters:
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[omrs-dates.ts:105](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/omrs-dates.ts#L105)
+
+___
+
+### translateFrom
+
+▸ **translateFrom**(`moduleName`, `key`, `fallback?`): `string`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `moduleName` | `string` |
+| `key` | `string` |
+| `fallback?` | `string` |
+
+#### Returns
 
-Name | Type |
-:------ | :------ |
-`date` | [*DateInput*](API.md#dateinput) |
+`string`
 
-**Returns:** *string*
+#### Defined in
 
-Defined in: [omrs-dates.ts:105](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/esm-utils/src/omrs-dates.ts#L105)
+[translate.ts:3](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/translate.ts#L3)

package/docs/interfaces/RetryOptions.md

@@ -0,0 +1,83 @@
+[@openmrs/esm-utils](../API.md) / RetryOptions
+
+# Interface: RetryOptions
+
+Options for configuring the behavior of the [retry](../API.md#retry) function.
+
+## Table of contents
+
+### Methods
+
+- [getDelay](RetryOptions.md#getdelay)
+- [onError](RetryOptions.md#onerror)
+- [shouldRetry](RetryOptions.md#shouldretry)
+
+## Methods
+
+### getDelay
+
+▸ `Optional` **getDelay**(`attempt`): `number`
+
+Calculates the next delay (in milliseconds) before a retry attempt.
+Returning a value for the inital attempt (`0`) delays the initial function invocation.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `attempt` | `number` | The current (zero-based) retry attempt. `0` indicates the initial attempt. |
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[retry.ts:16](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/retry.ts#L16)
+
+___
+
+### onError
+
+▸ `Optional` **onError**(`e`, `attempt`): `void`
+
+Called when invoking the function resulted in an error.
+Allows running side-effects on errors, e.g. logging.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `e` | `any` | The error thrown by the function. |
+| `attempt` | `number` | The current (zero-based) retry attempt. `0` indicates the initial attempt. |
+
+#### Returns
+
+`void`
+
+#### Defined in
+
+[retry.ts:23](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/retry.ts#L23)
+
+___
+
+### shouldRetry
+
+▸ `Optional` **shouldRetry**(`attempt`): `any`
+
+Determines whether the retry function should retry executing the function after it failed
+with an error on the current attempt.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `attempt` | `number` | The current (zero-based) retry attempt. `0` indicates the initial attempt. |
+
+#### Returns
+
+`any`
+
+#### Defined in
+
+[retry.ts:10](https://github.com/openmrs/openmrs-esm-core/blob/master/packages/framework/esm-utils/src/retry.ts#L10)

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "3.1.10-pre.97",
+  "version": "3.1.11-pre.595",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "browser": "dist/openmrs-esm-utils.js",
   "main": "src/index.ts",
   "source": true,
+  "sideEffects": false,
   "scripts": {
-    "document": "../../document.sh esm-utils",
+    "document": "../../../document.sh esm-utils",
     "test": "jest --config jest.config.js --passWithNoTests",
     "build": "webpack --mode=production",
     "analyze": "webpack --mode=production --env.analyze=true",
     "typescript": "tsc",
-    "lint": "eslint src --ext ts,tsx",
-    "format": "prettier --write src/**"
+    "lint": "eslint src --ext ts,tsx"
   },
   "keywords": [
     "openmrs",
@@ -38,13 +38,16 @@
     "access": "public"
   },
   "devDependencies": {
-    "dayjs": "^1.10.4"
+    "@types/semver": "^7.3.4",
+    "dayjs": "^1.10.4",
+    "rxjs": "^6.5.3"
   },
   "peerDependencies": {
-    "dayjs": "1.x"
+    "dayjs": "1.x",
+    "rxjs": "6.x"
   },
   "dependencies": {
-    "systemjs-webpack-interop": "^2.1.2"
+    "semver": "^7.3.2"
   },
-  "gitHead": "23be3c2711bccfde941c0fa823544c72ac6dfc08"
+  "gitHead": "c2141b8223409e20051338ee5109eb4e40cd19f0"
 }

package/src/age-helpers.tsx

@@ -0,0 +1,88 @@
+/**
+ * Gets the number of days in the year of the given date.
+ * @param date The date to compute the days within the year.
+ * @returns The number of days.
+ */
+export function daysIntoYear(date: Date) {
+  return (
+    (Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()) -
+      Date.UTC(date.getUTCFullYear(), 0, 0)) /
+    24 /
+    60 /
+    60 /
+    1000
+  );
+}
+
+/**
+ * Checks if two dates are representing the same day.
+ * @param firstDate The first date.
+ * @param secondDate The second date.
+ * @returns True if both are located on the same day.
+ */
+export function isSameDay(firstDate: Date, secondDate: Date) {
+  const firstISO = firstDate.toISOString();
+  const secondISO = secondDate.toISOString();
+  return (
+    firstISO.slice(0, firstISO.indexOf("T")) ===
+    secondISO.slice(0, secondISO.indexOf("T"))
+  );
+}
+
+/**
+ * Gets a human readable age represention of the provided date string.
+ * @param dateString The stringified date.
+ * @returns A human-readable string version of the age.
+ */
+export function age(dateString: string): string {
+  // Based on http://www.gregoryschmidt.ca/writing/patient-age-display-ehr-conventions,
+  // which is different from npm packages such as https://www.npmjs.com/package/timeago
+
+  // First calculate the age in years
+  const today = new Date();
+  const birthDate = new Date(dateString);
+  const monthDifference = today.getUTCMonth() - birthDate.getUTCMonth();
+  const dateDifference = today.getUTCDate() - birthDate.getUTCDate();
+  let age = today.getUTCFullYear() - birthDate.getUTCFullYear();
+  if (monthDifference < 0 || (monthDifference === 0 && dateDifference < 0)) {
+    age--;
+  }
+
+  // Now calculate the number of months in addition to the year's age
+  let monthsAgo = monthDifference >= 0 ? monthDifference : monthDifference + 12;
+  if (dateDifference < 0) {
+    monthsAgo--;
+  }
+  const monthsAgoStr = monthsAgo > 0 ? `${monthsAgo} mo` : "";
+
+  // For patients less than a year old, we calculate the number of days/weeks they have been alive
+  let totalDaysAgo = daysIntoYear(today) - daysIntoYear(birthDate);
+  if (totalDaysAgo < 0) {
+    totalDaysAgo += 365;
+  }
+  const weeksAgo = Math.floor(totalDaysAgo / 7);
+
+  // The "remainder" number of days after the weeksAgo number of weeks
+  const remainderDaysInWeek = totalDaysAgo - weeksAgo * 7;
+
+  // Depending on their age, return a different representation of their age.
+  if (age === 0) {
+    if (isSameDay(today, birthDate)) {
+      return `Today`;
+    } else if (weeksAgo < 4) {
+      return `${totalDaysAgo} day`;
+    } else if (weeksAgo === 0) {
+      return `${totalDaysAgo} day`;
+    } else if (remainderDaysInWeek > 0) {
+      return `${weeksAgo} wk ${remainderDaysInWeek} d`;
+    } else {
+      return `${weeksAgo} week`;
+    }
+  } else if (age < 2) {
+    return `${monthsAgoStr} ${age} yr`.trim();
+  } else if (age < 18) {
+    return `${age} yr ${monthsAgoStr}`.trim();
+  } else {
+    return `${age} years`;
+  }
+}

package/src/index.ts

@@ -1 +1,5 @@
+export * from "./age-helpers";
 export * from "./omrs-dates";
+export * from "./translate";
+export * from "./version";
+export * from "./retry";