@repo/utils

@repo/utils provides shared non-React utility functions. Code is organized into subpath exports: @repo/utils/time (timestamp formatting and date helpers using date-fns and @internationalized/date), @repo/utils/constants, @repo/utils/labels (human-readable labels), @repo/utils/objects, and @repo/utils/async.

Dependencies

graph TD
  utils["@repo/utils"] --> db["@repo/db"]
  utils --> errors["@repo/errors"]
  utils -.-> typescript_config["@repo/typescript-config"]
  utils -.-> vitest_config["@repo/vitest-config"]

Usage

@repo/utils/time — timestamp formatting and date helpers

formatTimestamp

Formats a date/timestamp into a string using named format keys. Returns a placeholder ("—" by default) when the value is falsy or invalid.

import { formatTimestamp } from "@repo/utils/time";

formatTimestamp(new Date());
// => "2026-03-05 12:00:00"  (default: SQL_DATETIME)

formatTimestamp(new Date(), { format: "DISPLAY_DATE_LONG" });
// => "March 5, 2026"

formatTimestamp(new Date(), { format: "DISPLAY_DATETIME_SHORT" });
// => "Mar 5, 2026, 12:00 PM"

formatTimestamp(new Date(), { format: "FEED_DATETIME" });
// => "Mar 5 at 12:00 PM"
Copy

Handling missing values:

formatTimestamp(undefined);
// => "—"  (EMPTY_VALUE_LABEL)

formatTimestamp(null, { placeholder: "No date" });
// => "No date"

formatTimestamp(null, { placeholder: null });
// => null  (useful for conditional rendering)
Copy

Available format keys:

dateStringToCalendarDate / dateValueToString

Convert between ISO date strings and @internationalized/date CalendarDate objects:

import { dateStringToCalendarDate, dateValueToString } from "@repo/utils/time";

const calendarDate = dateStringToCalendarDate("2026-03-05");
// => CalendarDate { year: 2026, month: 3, day: 5 }

const isoString = dateValueToString({ year: 2026, month: 3, day: 5 });
// => "2026-03-05"
Copy

@repo/utils/labels — human-readable labels

getPersonLabel

Builds a display name from person data. Accepts camelCase objects, snake_case objects, or positional arguments:

import { getPersonLabel } from "@repo/utils/labels";

getPersonLabel({ firstName: "Jane", lastName: "Doe" });
// => "Jane Doe"

getPersonLabel({ first_name: "Jane", last_name: "Doe" });
// => "Jane Doe"  (snake_case works too)

getPersonLabel("Jane", "Doe", "MD");
// => "Jane Doe, MD"

getPersonLabel({ firstName: "Jane", lastName: undefined });
// => "Jane"

getPersonLabel(undefined, undefined);
// => null
Copy

capitalize

import { capitalize } from "@repo/utils/labels";

capitalize("hello");
// => "Hello"
Copy

@repo/utils/objects/* — object helpers

compactObject

Removes falsy values from an object (useful for building query params or optional payloads):

import { compactObject } from "@repo/utils/objects/compactObject";

compactObject({ name: "Jane", email: "", phone: undefined, active: true });
// => { name: "Jane", active: true }
Copy

@repo/utils/async/* — async helpers

wait

Promise-based delay:

import { wait } from "@repo/utils/async/wait";

await wait(1000); // pause for 1 second
Copy

@repo/utils/constants — shared constants

Placeholder strings for consistent UI rendering when values are missing:

import { EMPTY_VALUE_LABEL, UNKNOWN_VALUE_LABEL, N_A_VALUE_LABEL } from "@repo/utils/constants";

EMPTY_VALUE_LABEL;   // "—"
UNKNOWN_VALUE_LABEL; // "Unknown"
N_A_VALUE_LABEL;     // "N/A"
Copy

EMPTY_VALUE_LABEL is the default placeholder used by formatTimestamp when a value is falsy.

Scripts