@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

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)

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)

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

# 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

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

• 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:

npm install @pensoft/article-models

Step 2: Import Types

Replace local type definitions with imports:

// 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: 61x faster than Zod, compile-time generation
• Works seamlessly with these type definitions

Example with Typia:

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 file for details