npm package: @pensoft/article-models
Description: Shared TypeScript type definitions for Pensoft article-editor and related Node.js services
Author: Pensoft
Latest version: 0.1.1

# @pensoft/article-models

Shared TypeScript type definitions for Pensoft article-editor (frontend) and article-storage (backend). This package ensures type consistency and prevents type drift between services.

## Installation

```bash
npm install @pensoft/article-models
```

## Purpose

This package solves the problem of duplicate type definitions drifting between frontend and backend services by providing a single source of truth for all data contracts.

### Benefits

- **Type Consistency**: Guaranteed identical types across services
- **No Drift**: Impossible for frontend/backend types to diverge
- **Single Source of Truth**: Update once, propagate everywhere
- **Type Safety**: Full TypeScript support with IntelliSense
- **Semantic Versioning**: Clear contract evolution tracking

## Usage

### In Frontend (article-editor)

```typescript
import { Article, Author } from '@pensoft/article-models';

function createArticle(data: Article): void {
  // TypeScript knows the exact structure
  console.log(data.title, data.author.name);
}
```

### In Backend (article-storage)

```typescript
import { Article, Author } from '@pensoft/article-models';

function saveArticle(article: Article): Promise<void> {
  // Same types as frontend - guaranteed!
  return database.save(article);
}
```

## Available Types

Currently includes example models:

- `Article`: Article data structure
- `Author`: Author information

More models will be added as the architecture evolves.

## Development

### Setup

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Clean build output
npm run clean
```

### Project Structure

```
@pensoft/article-models/
├── src/
│   ├── index.ts              # Main export file
│   └── example.models.ts     # Example type definitions
├── dist/                      # Compiled output (generated)
│   ├── index.js
│   ├── index.d.ts
│   └── ...
├── package.json
├── tsconfig.json
└── README.md
```

### Build Process

The package uses TypeScript compiler to generate:
- Compiled JavaScript (CommonJS) in `dist/`
- Type declaration files (`.d.ts`) in `dist/`
- Source maps for debugging

### Publishing

The package is published to the official npm registry with public access.

#### Automated Publishing (GitLab CI/CD)

Publishing is automated via GitLab CI/CD with the following workflow:

**Branch Strategy:**
- `develop` branch: Builds automatically on push/MR (no publishing)
- `main` branch: Builds automatically on merge, publishing available via manual trigger

**Release Workflow:**

1. **Prepare Release** (recommended):
   - Create a release branch from `develop` (e.g., `release/v1.0.0`)
   - Update version in `package.json` following semantic versioning
   - Create Merge Request: `release/v1.0.0` → `main`

2. **Merge to Main**:
   - Merge the MR to `main` branch
   - GitLab CI automatically builds the package

3. **Publish to npm**:
   - Go to GitLab CI/CD → Pipelines
   - Manually trigger the `publish` job (requires manual approval for safety)
   - The package will be published to npm registry

**Alternative Workflow** (direct from develop):
- Create MR: `develop` → `main`
- Merge → build runs automatically
- Manually trigger publish job

**Note**: Publishing only happens from `main` branch and requires manual trigger. The `develop` branch is used for development and testing builds only.

#### Manual Publishing

```bash
# Build the package
npm run build

# Login to npm (using provided credentials)
npm login

# Publish to npm
npm publish --access public
```

#### NPM Credentials

Use the following npm account for publishing:
- Username: `pensoft`
- Password: `Ub_2sn$w@hoiYrJ`

**Note**: For GitLab CI, configure `NPM_TOKEN` as a masked CI/CD variable in the repository settings.

## Versioning

This package follows [Semantic Versioning](https://semver.org/):

- **MAJOR**: Breaking changes (incompatible API changes)
- **MINOR**: New features (backward-compatible)
- **PATCH**: Bug fixes (backward-compatible)

Current version: `0.1.0` (pre-release)

## Integration Guide

### Step 1: Install Package

In both `article-editor` and `article-storage`:

```bash
npm install @pensoft/article-models
```

### Step 2: Import Types

Replace local type definitions with imports:

```typescript
// Before (local definition)
interface Article {
  id: string;
  title: string;
  // ...
}

// After (shared package)
import { Article } from '@pensoft/article-models';
```

### Step 3: Remove Duplicates

Remove duplicate type definitions from both projects. The shared package is now the single source of truth.

### Step 4: Update on Changes

When types change:

1. Update types in `@pensoft/article-models`
2. Publish new version
3. Update package in both `article-editor` and `article-storage`
4. TypeScript will enforce the new contract at compile time

## Migration Strategy

1. **Phase 1**: Install package in both services (non-breaking)
2. **Phase 2**: Shadow import (import but don't use yet)
3. **Phase 3**: Gradually replace local types with imports
4. **Phase 4**: Remove all duplicate definitions
5. **Phase 5**: Enforce via code review/linting

## Contributing

When adding new type definitions:

1. Create model file in `src/` (e.g., `src/article.models.ts`)
2. Export from `src/index.ts`
3. Document with JSDoc comments
4. Build and test locally
5. Update version in `package.json`
6. Create merge request

## Runtime Validation

This package provides TypeScript type definitions. For runtime validation, consider using:

- [Typia](https://github.com/samchon/typia): 61x faster than Zod, compile-time generation
- Works seamlessly with these type definitions

Example with Typia:

```typescript
import typia from 'typia';
import { Article } from '@pensoft/article-models';

// Validate at runtime
const result = typia.validate<Article>(data);
if (result.success) {
  // Type-safe access
  console.log(result.data.title);
}
```

## Support

For issues or questions:
- Create an issue in the GitLab repository
- Contact the Pensoft development team

## License

MIT - see [LICENSE](LICENSE) file for details