@openmrs/esm-utils 3.1.10-pre.92 → 3.1.12-pre.598

package/docs/API.md

@@ -0,0 +1,394 @@
+[Back to README.md](../README.md)
+
+# @openmrs/esm-utils
+
+## 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)
+- [toOmrsIsoString](API.md#toomrsisostring)
+- [toOmrsTimeString](API.md#toomrstimestring)
+- [toOmrsTimeString24](API.md#toomrstimestring24)
+- [toOmrsYearlessDateFormat](API.md#toomrsyearlessdateformat)
+- [translateFrom](API.md#translatefrom)
+
+## Type aliases
+
+### DateInput
+
+Ƭ **DateInput**: `string` \| `number` \| `Date`
+
+#### Defined in
+
+[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`): `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
+
+| Name | Type |
+| :------ | :------ |
+| `omrsPayloadString` | `string` |
+
+#### Returns
+
+`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`): `boolean`
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | Checks if the provided date is today. |
+
+#### Returns
+
+`boolean`
+
+#### 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`): `Date` \| ``null``
+
+Converts the object to a date object if it is a valid ISO date time string.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `omrsDateString` | `string` |
+
+#### Returns
+
+`Date` \| ``null``
+
+#### 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`, `format?`): `string`
+
+Formats the input as a date string. By default the format "YYYY-MMM-DD" is used.
+
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | `undefined` |
+| `format` | `string` | `"YYYY-MMM-DD"` |
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[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`): `string`
+
+Formats the input as a date string using the format "DD - MMM - YYYY".
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
+
+#### Returns
+
+`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`, `toUTC?`): `string`
+
+Formats the input as a date time string using the format "YYYY-MM-DDTHH:mm:ss.SSSZZ".
+
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) | `undefined` |
+| `toUTC` | `boolean` | `false` |
+
+#### Returns
+
+`string`
+
+#### 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`): `string`
+
+Formats the input as a time string using the format "HH:mm A".
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
+
+#### Returns
+
+`string`
+
+#### Defined in
+
+[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`): `string`
+
+Formats the input as a time string using the format "HH:mm".
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `date` | [`DateInput`](API.md#dateinput) |
+
+#### Returns
+
+`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`): `string`
+
+Formats the input as a date string using the format "DD-MMM".
+
+#### 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
+
+`string`
+
+#### Defined in
+
+[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,18 +1,19 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "3.1.10-pre.92",
+  "version": "3.1.12-pre.598",
   "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",
     "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",
@@ -37,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": "dc107e58044bbcf7a4cc919360590928e1db20ff"
+  "gitHead": "ddb157645863df8cc29a26928bb29105b8c19119"
 }

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";

package/src/omrs-dates.test.ts

@@ -1,4 +1,8 @@
-import { toOmrsIsoString } from "./omrs-dates";
+import {
+  toOmrsIsoString,
+  toDateObjectStrict,
+  isOmrsDateStrict,
+} from "./omrs-dates";
 import dayjs from "dayjs";
 
 describe("Openmrs Dates", () => {
@@ -9,4 +13,32 @@ describe("Openmrs Dates", () => {
     ).toDate();
     expect(toOmrsIsoString(date, true)).toEqual("2018-03-18T21:05:03.999+0000");
   });
+
+  it("checks if a string is openmrs date", () => {
+    expect(isOmrsDateStrict("2018-03-19T00:00:00.000+0300")).toEqual(true);
+    expect(isOmrsDateStrict(" 2018-03-19T00:00:00.000+0300 ")).toEqual(true);
+    // the exclusion test cases are important for strictness
+    expect(isOmrsDateStrict("2018-03-19 00:00:00.000+0300")).toEqual(false);
+    expect(isOmrsDateStrict("2018-03-19T00:00:00.000+03:00")).toEqual(false);
+    expect(isOmrsDateStrict("2018-03-19T00:00:00.000 0300")).toEqual(false);
+    expect(isOmrsDateStrict("2018-03-19T00:00:00 000+0300")).toEqual(false);
+    expect(isOmrsDateStrict("2018-03-1")).toEqual(false);
+    expect(isOmrsDateStrict("")).toEqual(false);
+    expect(isOmrsDateStrict(null as any)).toEqual(false);
+    expect(isOmrsDateStrict(undefined as any)).toEqual(false);
+  });
+  it("converts omrs date string version to js Date object", () => {
+    expect(
+      toDateObjectStrict("2018-03-19T00:00:00.000+0300")?.toUTCString()
+    ).toEqual("Sun, 18 Mar 2018 21:00:00 GMT");
+    expect(toDateObjectStrict("2018-03-19")).toEqual(null);
+  });
+
+  it("converts js Date object to omrs date string version", () => {
+    var date = dayjs(
+      "2018-03-19T00:05:03.999+0300",
+      "YYYY-MM-DDTHH:mm:ss.SSSZZ"
+    ).toDate();
+    expect(toOmrsIsoString(date, true)).toEqual("2018-03-18T21:05:03.999+0000");
+  });
 });