Add packages/common for shared utilities

Create new @reviq/common package with environment-agnostic utilities:
- Date formatting: formatDate, formatDateTime, formatLongDate,
  formatRelativeDate, formatRelativeTime
- User utilities: getUserInitials, formatRole

Consolidate date formatting from publisher-dashboard into shared package.
All utilities include comprehensive test coverage with bun:test.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
igm
2026-01-11 12:34:10 +08:00
parent 7358129802
commit b1d07626f3
25 changed files with 639 additions and 300 deletions

134
packages/common/README.md Normal file
View File

@@ -0,0 +1,134 @@
# @reviq/common
Shared utilities for all RevIQ applications. This package contains environment-agnostic code that works in browsers, Node.js, Bun, and other JavaScript runtimes.
## 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