@openmrs/esm-utils 8.0.1-pre.3783 → 8.0.1-pre.3786

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 12 files with swc (196.23ms)
+[0] Successfully compiled: 12 files with swc (146.23ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/dates/date-util.d.ts

@@ -11,8 +11,10 @@ export type DateInput = string | number | Date;
  */
 export declare function isOmrsDateStrict(omrsPayloadString: string): boolean;
 /**
+ * Checks if the provided date is today.
  *
- * @param date Checks if the provided date is today.
+ * @param date The date to check.
+ * @returns `true` if the date is today, `false` otherwise.
  */
 export declare function isOmrsDateToday(date: DateInput): boolean;
 /**
@@ -101,6 +103,10 @@ export type FormatDateOptions = {
  * 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.
+ *
+ * @param dateString The date string to parse and format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string, or `null` if the input cannot be parsed.
  */
 export declare function formatPartialDate(dateString: string, options?: Partial<FormatDateOptions>): string | null;
 /**
@@ -121,11 +127,18 @@ export declare function formatPartialDate(dateString: string, options?: Partial<
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string.
  */
 export declare function formatDate(date: Date, options?: Partial<FormatDateOptions>): string;
 /**
  * Formats the input as a time, according to the current locale.
  * 12-hour or 24-hour clock depends on locale.
+ *
+ * @param date The date whose time portion should be formatted.
+ * @returns The formatted time string (e.g., "2:30 PM" or "14:30").
  */
 export declare function formatTime(date: Date): string;
 /**
@@ -136,6 +149,10 @@ export declare function formatTime(date: Date): string;
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options (same as formatDate, except time is always included).
+ * @returns The formatted date and time string.
  */
 export declare function formatDatetime(date: Date, options?: Partial<Omit<FormatDateOptions, 'time'>>): string;
 /**

package/dist/dates/date-util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-util.d.ts","sourceRoot":"","sources":["../../src/dates/date-util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAGnB,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAMpG,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAI/C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAuBnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAE9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,UAAQ,GAAG,MAAM,CAQtE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,QAE3C;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,QAEnF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,kCAI1E;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;IACjC,wCAAwC;IACxC,GAAG,EAAE,OAAO,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAWF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,iBAuC7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,UAkE1E;AAiBD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,UAKpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,UAE5F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,GAAG,gBAAgB,GAAG,aAAa,EACrD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,mDAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,qBAAqB,UAGtF"}
+{"version":3,"file":"date-util.d.ts","sourceRoot":"","sources":["../../src/dates/date-util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAGnB,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAMpG,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAI/C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAuBnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAE9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,UAAQ,GAAG,MAAM,CAQtE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,QAE3C;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,QAEnF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,kCAI1E;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;IACjC,wCAAwC;IACxC,GAAG,EAAE,OAAO,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,iBAuC7F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,UAkE1E;AAiBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,UAKpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,UAE5F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,GAAG,gBAAgB,GAAG,aAAa,EACrD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,mDAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,qBAAqB,UAGtF"}

package/dist/dates/date-util.js

@@ -63,8 +63,10 @@ const isoFormat = 'YYYY-MM-DDTHH:mm:ss.SSSZZ';
     return dayjs(omrsPayloadString, isoFormat).isValid();
 }
 /**
+ * Checks if the provided date is today.
  *
- * @param date Checks if the provided date is today.
+ * @param date The date to check.
+ * @returns `true` if the date is today, `false` otherwise.
  */ export function isOmrsDateToday(date) {
     return dayjs(date).isToday();
 }
@@ -175,6 +177,10 @@ const defaultOptions = {
  * 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.
+ *
+ * @param dateString The date string to parse and format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string, or `null` if the input cannot be parsed.
  */ // TODO: Shouldn't throw on null input
 export function formatPartialDate(dateString, options = {}) {
     const locale = getLocale();
@@ -229,6 +235,10 @@ export function formatPartialDate(dateString, options = {}) {
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string.
  */ // TODO: Shouldn't throw on null input
 export function formatDate(date, options) {
     let locale = options?.locale ?? getLocale();
@@ -306,6 +316,9 @@ const formatParts = (separator)=>{
 /**
  * Formats the input as a time, according to the current locale.
  * 12-hour or 24-hour clock depends on locale.
+ *
+ * @param date The date whose time portion should be formatted.
+ * @returns The formatted time string (e.g., "2:30 PM" or "14:30").
  */ export function formatTime(date) {
     return date.toLocaleTimeString(getLocale(), {
         hour: '2-digit',
@@ -320,6 +333,10 @@ const formatParts = (separator)=>{
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options (same as formatDate, except time is always included).
+ * @returns The formatted date and time string.
  */ export function formatDatetime(date, options) {
     return formatDate(date, {
         ...options,

package/dist/is-online.d.ts

@@ -1,2 +1,14 @@
+/**
+ * Determines if the application should behave as if it is online.
+ * When offline mode is enabled (`window.offlineEnabled`), this returns the
+ * provided `online` parameter or falls back to `navigator.onLine`.
+ * When offline mode is disabled, this always returns `true`.
+ *
+ * @param online Optional override for the online status. If provided and offline
+ *   mode is enabled, this value is returned directly.
+ * @returns `true` if the application should behave as online, `false` otherwise.
+ *
+ * @category Utility
+ */
 export declare function isOnline(online?: boolean): boolean;
 //# sourceMappingURL=is-online.d.ts.map

package/dist/is-online.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-online.d.ts","sourceRoot":"","sources":["../src/is-online.ts"],"names":[],"mappings":"AAEA,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,WAExC"}
+{"version":3,"file":"is-online.d.ts","sourceRoot":"","sources":["../src/is-online.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,WAExC"}

package/dist/is-online.js

@@ -1,3 +1,14 @@
-export function isOnline(online) {
+/**
+ * Determines if the application should behave as if it is online.
+ * When offline mode is enabled (`window.offlineEnabled`), this returns the
+ * provided `online` parameter or falls back to `navigator.onLine`.
+ * When offline mode is disabled, this always returns `true`.
+ *
+ * @param online Optional override for the online status. If provided and offline
+ *   mode is enabled, this value is returned directly.
+ * @returns `true` if the application should behave as online, `false` otherwise.
+ *
+ * @category Utility
+ */ export function isOnline(online) {
     return window.offlineEnabled ? online ?? navigator.onLine : true;
 }

package/dist/patient-helpers.d.ts

@@ -26,17 +26,20 @@ export declare function formattedName(name: fhir.HumanName | undefined): string;
  * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
  * A name with no usage specified is treated as the 'usual' name.
  *
- * The chosen name will be selected according to the priority order of `preferredNames`,
- * @example
- * // normal use case; prefer usual name, fallback to official name
- * displayNameByUsage(patient, 'usual', 'official')
- * @example
- * // prefer usual name over nickname, fallback to official name
- * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ * The chosen name will be selected according to the priority order of `preferredNames`.
  *
  * @param patient The patient from whom a name will be selected.
  * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
- * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ * @returns The preferred name for the patient, or undefined if no acceptable name could be found.
+ *
+ * @example
+ * ```ts
+ * // normal use case; prefer usual name, fallback to official name
+ * selectPreferredName(patient, 'usual', 'official')
+ *
+ * // prefer usual name over nickname, fallback to official name
+ * selectPreferredName(patient, 'usual', 'nickname', 'official')
+ * ```
  */
 export declare function selectPreferredName(patient: fhir.Patient, ...preferredNames: NameUse[]): fhir.HumanName | undefined;
 //# sourceMappingURL=patient-helpers.d.ts.map

package/dist/patient-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patient-helpers.d.ts","sourceRoot":"","sources":["../src/patient-helpers.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAEhC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAG5D;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,GAAG,SAAS,GAAG,MAAM,CAG1E;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,GAAG,SAAS,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,SAAS,CAWnH"}
+{"version":3,"file":"patient-helpers.d.ts","sourceRoot":"","sources":["../src/patient-helpers.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAEhC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAG5D;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,GAAG,SAAS,GAAG,MAAM,CAG1E;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,GAAG,SAAS,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,SAAS,CAWnH"}

package/dist/patient-helpers.js

@@ -30,17 +30,20 @@
  * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
  * A name with no usage specified is treated as the 'usual' name.
  *
- * The chosen name will be selected according to the priority order of `preferredNames`,
- * @example
- * // normal use case; prefer usual name, fallback to official name
- * displayNameByUsage(patient, 'usual', 'official')
- * @example
- * // prefer usual name over nickname, fallback to official name
- * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ * The chosen name will be selected according to the priority order of `preferredNames`.
  *
  * @param patient The patient from whom a name will be selected.
  * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
- * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ * @returns The preferred name for the patient, or undefined if no acceptable name could be found.
+ *
+ * @example
+ * ```ts
+ * // normal use case; prefer usual name, fallback to official name
+ * selectPreferredName(patient, 'usual', 'official')
+ *
+ * // prefer usual name over nickname, fallback to official name
+ * selectPreferredName(patient, 'usual', 'nickname', 'official')
+ * ```
  */ export function selectPreferredName(patient, ...preferredNames) {
     if (preferredNames.length == 0) {
         preferredNames = [

package/dist/version.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Checks if an installed version satisfies a required version range using
+ * semver comparison. Handles prerelease versions and normalizes version strings.
+ *
+ * @param requiredVersion A semver range string (e.g., "^1.0.0", ">=2.0.0").
+ * @param installedVersion The installed version string to check against the range.
+ * @returns `true` if the installed version satisfies the required version range.
+ *
+ */
 export declare function isVersionSatisfied(requiredVersion: string, installedVersion: string): boolean;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAqBA,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,WAMnF"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAqBA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,WAMnF"}

package/dist/version.js

@@ -13,7 +13,15 @@ function normalizeFullVersion(version) {
     }
     return normalizeOnlyVersion(version);
 }
-export function isVersionSatisfied(requiredVersion, installedVersion) {
+/**
+ * Checks if an installed version satisfies a required version range using
+ * semver comparison. Handles prerelease versions and normalizes version strings.
+ *
+ * @param requiredVersion A semver range string (e.g., "^1.0.0", ">=2.0.0").
+ * @param installedVersion The installed version string to check against the range.
+ * @returns `true` if the installed version satisfies the required version range.
+ *
+ */ export function isVersionSatisfied(requiredVersion, installedVersion) {
     const version = normalizeFullVersion(installedVersion);
     return semver.satisfies(version, requiredVersion, {
         includePrerelease: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "8.0.1-pre.3783",
+  "version": "8.0.1-pre.3786",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "type": "module",
@@ -59,7 +59,7 @@
     "rxjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "8.0.1-pre.3783",
+    "@openmrs/esm-globals": "8.0.1-pre.3786",
     "@swc/cli": "^0.7.7",
     "@swc/core": "^1.11.29",
     "@types/lodash-es": "^4.17.12",

package/src/dates/date-util.ts

@@ -58,8 +58,10 @@ export function isOmrsDateStrict(omrsPayloadString: string): boolean {
 }
 
 /**
+ * Checks if the provided date is today.
  *
- * @param date Checks if the provided date is today.
+ * @param date The date to check.
+ * @returns `true` if the date is today, `false` otherwise.
  */
 export function isOmrsDateToday(date: DateInput) {
   return dayjs(date).isToday();
@@ -232,6 +234,10 @@ const defaultOptions: FormatDateOptions = {
  * 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.
+ *
+ * @param dateString The date string to parse and format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string, or `null` if the input cannot be parsed.
  */
 // TODO: Shouldn't throw on null input
 export function formatPartialDate(dateString: string, options: Partial<FormatDateOptions> = {}) {
@@ -293,6 +299,10 @@ export function formatPartialDate(dateString: string, options: Partial<FormatDat
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options.
+ * @returns The formatted date string.
  */
 // TODO: Shouldn't throw on null input
 export function formatDate(date: Date, options?: Partial<FormatDateOptions>) {
@@ -381,6 +391,9 @@ const formatParts = (separator: string) => {
 /**
  * Formats the input as a time, according to the current locale.
  * 12-hour or 24-hour clock depends on locale.
+ *
+ * @param date The date whose time portion should be formatted.
+ * @returns The formatted time string (e.g., "2:30 PM" or "14:30").
  */
 export function formatTime(date: Date) {
   return date.toLocaleTimeString(getLocale(), {
@@ -397,6 +410,10 @@ export function formatTime(date: Date) {
  * 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.
+ *
+ * @param date The date to format.
+ * @param options Optional formatting options (same as formatDate, except time is always included).
+ * @returns The formatted date and time string.
  */
 export function formatDatetime(date: Date, options?: Partial<Omit<FormatDateOptions, 'time'>>) {
   return formatDate(date, { ...options, time: true });

package/src/is-online.ts

@@ -1,5 +1,17 @@
 import type {} from '@openmrs/esm-globals';
 
+/**
+ * Determines if the application should behave as if it is online.
+ * When offline mode is enabled (`window.offlineEnabled`), this returns the
+ * provided `online` parameter or falls back to `navigator.onLine`.
+ * When offline mode is disabled, this always returns `true`.
+ *
+ * @param online Optional override for the online status. If provided and offline
+ *   mode is enabled, this value is returned directly.
+ * @returns `true` if the application should behave as online, `false` otherwise.
+ *
+ * @category Utility
+ */
 export function isOnline(online?: boolean) {
   return window.offlineEnabled ? online ?? navigator.onLine : true;
 }

package/src/patient-helpers.ts

@@ -42,17 +42,20 @@ export function formattedName(name: fhir.HumanName | undefined): string {
  * Names may be specified with a usage such as 'usual', 'official', 'nickname', 'maiden', etc.
  * A name with no usage specified is treated as the 'usual' name.
  *
- * The chosen name will be selected according to the priority order of `preferredNames`,
- * @example
- * // normal use case; prefer usual name, fallback to official name
- * displayNameByUsage(patient, 'usual', 'official')
- * @example
- * // prefer usual name over nickname, fallback to official name
- * displayNameByUsage(patient, 'usual', 'nickname', 'official')
+ * The chosen name will be selected according to the priority order of `preferredNames`.
  *
  * @param patient The patient from whom a name will be selected.
  * @param preferredNames Optional ordered sequence of preferred name usages; defaults to 'usual' if not specified.
- * @return the preferred name for the patient, or undefined if no acceptable name could be found.
+ * @returns The preferred name for the patient, or undefined if no acceptable name could be found.
+ *
+ * @example
+ * ```ts
+ * // normal use case; prefer usual name, fallback to official name
+ * selectPreferredName(patient, 'usual', 'official')
+ *
+ * // prefer usual name over nickname, fallback to official name
+ * selectPreferredName(patient, 'usual', 'nickname', 'official')
+ * ```
  */
 export function selectPreferredName(patient: fhir.Patient, ...preferredNames: NameUse[]): fhir.HumanName | undefined {
   if (preferredNames.length == 0) {

package/src/version.ts

@@ -19,6 +19,15 @@ function normalizeFullVersion(version: string) {
   return normalizeOnlyVersion(version);
 }
 
+/**
+ * Checks if an installed version satisfies a required version range using
+ * semver comparison. Handles prerelease versions and normalizes version strings.
+ *
+ * @param requiredVersion A semver range string (e.g., "^1.0.0", ">=2.0.0").
+ * @param installedVersion The installed version string to check against the range.
+ * @returns `true` if the installed version satisfies the required version range.
+ *
+ */
 export function isVersionSatisfied(requiredVersion: string, installedVersion: string) {
   const version = normalizeFullVersion(installedVersion);