# @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:

```bash
# 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.

```typescript
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.

```typescript
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.

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

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

#### `formatRelativeDate(date, options?)`

Format a date as a relative time string.

```typescript
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.

```typescript
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.

```typescript
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).

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

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

## Development

```bash
# 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