@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

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

Documentation

API Documentation - Complete TypeDoc-generated API documentation

To generate documentation locally:

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

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

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 for comprehensive validation documentation.

That70sDateTime

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

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

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

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

Drizzle Schemas

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

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

Development

# 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