publisher-dashboard/packages/common/README.md

@reviq/common

Shared utilities for frontend and backend. This package contains environment-agnostic code that works in browsers, Node.js, Bun, and Cloudflare Workers.

Use this package for utilities that need to work in both the publisher dashboard and the API server.

Installation

This package is used internally within the monorepo:

# Add to your app's package.json
"dependencies": {
  "@reviq/common": "workspace:*"
}

Date Formatting

Consistent date formatting utilities for displaying dates across the application.

Functions

formatDate(date)

Format a date for display in tables and lists.

import { formatDate } from "@reviq/common";

formatDate("2024-01-15"); // "Jan 15, 2024"
formatDate(new Date());   // "Jan 15, 2024"

formatDateTime(date)

Format a date with time for detailed views.

import { formatDateTime } from "@reviq/common";

formatDateTime("2024-01-15T15:30:00"); // "Jan 15, 2024, 3:30 PM"

formatLongDate(date)

Format a date in long form.

import { formatLongDate } from "@reviq/common";

formatLongDate("2024-01-15"); // "January 15, 2024"

formatRelativeDate(date, options?)

Format a date as a relative time string.

import { formatRelativeDate } from "@reviq/common";

formatRelativeDate("2024-01-15"); // "Today" (if today is Jan 15)
formatRelativeDate("2024-01-14"); // "Yesterday"
formatRelativeDate("2024-01-10"); // "5 days ago"
formatRelativeDate("2024-01-01"); // "2 weeks ago"
formatRelativeDate("2023-06-15"); // "Jun 15, 2023"

// With custom reference date
formatRelativeDate("2024-01-10", { now: new Date("2024-01-15") });

formatRelativeTime(date, options?)

Same as formatRelativeDate, but returns "Never" for null/undefined values. Useful for "last used" timestamps.

import { formatRelativeTime } from "@reviq/common";

formatRelativeTime("2024-01-15"); // "Today"
formatRelativeTime(null);         // "Never"
formatRelativeTime(undefined);    // "Never"

User Utilities

Helper functions for working with user data.

Functions

getUserInitials(user)

Generate initials from a user's display name or email.

import { getUserInitials } from "@reviq/common";

getUserInitials({ displayName: "John Doe", email: "john@example.com" }); // "JD"
getUserInitials({ displayName: "John", email: "john@example.com" });     // "JO"
getUserInitials({ email: "john@example.com" });                          // "JO"
getUserInitials(null);                                                   // "??"

formatRole(role)

Format a role string for display (capitalizes first letter).

import { formatRole } from "@reviq/common";

formatRole("admin");  // "Admin"
formatRole("member"); // "Member"
formatRole("owner");  // "Owner"

Development

# Run tests
bun test

# Build
bun run build

# Type check
bun run typecheck

Adding New Utilities

When adding new utilities to this package:

1. Create a new file in src/ (e.g., src/my-utility.ts)
2. Add comprehensive tests in src/my-utility.test.ts
3. Export from src/index.ts
4. Run bun test to verify tests pass
5. Run bun run build to compile