npm package: @recoverysky/common
Description: Shared TypeScript library for RecoverySky recovery meeting management - includes data models, schema generation pipeline, and That70sDateTime utilities
Latest version: 1.1.11

# @recoverysky/common

Shared TypeScript library for RecoverySky recovery meeting management system.

## Features

- **Data Models**: Type-safe models for meetings and schedules (AA, NA recovery meetings)
- **Runtime Validation**: Comprehensive Zod validation with 40+ rules (automatic in `update()`)
- **Schema Generation Pipeline**: TypeScript → JSON Schema → RxDB → Drizzle ORM
- **That70sDateTime**: Custom datetime utility for managing recurring meeting times
- **RxDB Integration**: Offline-first database schemas for client-side sync
- **Drizzle ORM**: PostgreSQL schemas for server-side persistence
- **Decorators**: Custom decorators for model integration and function injection

## Installation

```bash
npm install @recoverysky/common
# or
pnpm add @recoverysky/common
```

## Documentation

**[API Documentation](./docs/index.html)** - Complete TypeDoc-generated API documentation

To generate documentation locally:
```bash
pnpm docs              # Generate docs to ./docs
pnpm docs:watch        # Generate docs and watch for changes
pnpm docs:serve        # Generate and serve docs on http://localhost:8080
```

## Usage

### Basic Models

```typescript
import { Meeting, Schedule } from '@recoverysky/common';

// Create a new meeting
const result = Meeting.create();
if (result.ok) {
  const meeting = result.value;
  meeting.name = 'Monday Night Big Book';
  meeting.fellowship = 'AA';
  meeting.startDateTime = 1234567890;
  meeting.duration = 3600000; // 1 hour in ms

  // Automatic validation happens in update()
  const updateResult = await meeting.update();
  if (updateResult.ok) {
    console.log('Meeting validated and updated:', meeting.sha256);
  } else {
    console.error('Validation failed:', updateResult.error.message);
  }
}

// Create a schedule
const scheduleResult = Schedule.create();
if (scheduleResult.ok) {
  const schedule = scheduleResult.value;
  schedule.name = 'Weekly Meetings';
}
```

### Runtime Validation

```typescript
import { meetingZodSchema, Meeting } from '@recoverysky/common';

// Automatic validation (recommended)
const meeting = Meeting.create().unwrap();
meeting.name = 'AA Meeting';
meeting.zid = '123456789';

const result = await meeting.update(); // Validates automatically
if (!result.ok) {
  console.error('Validation failed:', result.error.message);
}

// Standalone validation
const validation = meetingZodSchema.safeParse(meeting);
if (!validation.success) {
  console.error('Errors:', validation.error.format());
}
```

**See**: [Validation Guide](./content/VALIDATION.md) for comprehensive validation documentation.

### That70sDateTime

Normalize recurring meeting times to the first week of 1970 (epoch week) for storage:

```typescript
import { makeThat70sDateTime, hydrateSeventies } from '@recoverysky/common';

// Convert current datetime to 70s equivalent
const seventiesTime = makeThat70sDateTime({
  DateTime: luxonDateTime,
  millis: Date.now()
});

// Convert back to current week
const currentTime = hydrateSeventies(seventiesTime, timezone);
```

### RxDB Schemas

```typescript
import { meetingRxDBSchema } from '@recoverysky/common/lib/models/rxdb/meeting.rxdb';

// Use in RxDB collection
const collections = {
  meetings: {
    schema: meetingRxDBSchema
  }
};
```

### Drizzle Schemas

```typescript
import { meetings } from '@recoverysky/common/lib/models/drizzle/meetings.drizzle';

// Use with Drizzle ORM
const allMeetings = await db.select().from(meetings);
```

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Generate schemas
pnpm ts:schema     # TypeScript schemas
pnpm json:schema   # JSON schemas
pnpm rxdb:schema   # RxDB schemas
pnpm drizzle:schema # Drizzle schemas

# Full build pipeline
pnpm make
```

## Schema Generation Pipeline

The library uses a multi-step transformation pipeline:

1. **Source Models** (`src/models/*.ts`) - Plain TypeScript classes
2. **TypeScript Schemas** (`src/models/schema/*.schema.ts`) - Generated type schemas
3. **JSON Schemas** (`src/models/json/*.json`) - Standard JSON Schema format
4. **RxDB Schemas** (`src/models/rxdb/*.rxdb.ts`) - Client-side database schemas
5. **Drizzle Schemas** (`src/models/drizzle/*.drizzle.ts`) - PostgreSQL table definitions

Run `pnpm make` to regenerate the entire pipeline after modifying models.

## Architecture

```
src/
├── classes/          # Business logic classes
│   ├── Meeting/     # Meeting class with methods
│   ├── Schedule/    # Schedule class
│   └── That70sDateTime/ # Custom datetime utility
├── models/          # Data models and generated schemas
│   ├── meeting.ts   # Base meeting model
│   ├── schedule.ts  # Base schedule model
│   ├── schema/      # Generated TS schemas
│   ├── json/        # Generated JSON schemas
│   ├── rxdb/        # Generated RxDB schemas
│   └── drizzle/     # Generated Drizzle schemas
├── decorators/      # Custom decorators
├── enums/           # Enumerations
├── types/           # TypeScript type definitions
├── utils/           # Utility functions
└── constants/       # Static constants
```

## License

MIT

## Repository

https://github.com/recoverysky-org/recoverysky-common