@iserve/shared-types

Shared TypeScript types, validation schemas, and utilities for the iServe ecosystem. This package centralizes common data structures to ensure consistency and type safety across different projects (e.g., frontend, backend, microservices).

🚀 About The Project

In a distributed system like iServe, it's crucial that all services and applications speak the same language. This repository acts as the single source of truth for our data models. By sharing types and schemas, we reduce code duplication, minimize integration errors, and make development more efficient.

Key Features

• TypeScript Types: Statically typed interfaces for robust compile-time checking.
• Validation Schemas: Runtime data validation using Joi.
• Mongoose Schemas: Ready-to-use schemas for MongoDB models, designed to work with the types.
• ESM & CJS Support: Dual-module package that works seamlessly with both import and require.
• Lightweight: No heavy dependencies, keeping your project's footprint small.

📂 File Structure

The project is organized to be simple and maintainable.

.
├── dist/              # Compiled output (JavaScript, CJS, and type declarations)
├── src/               # Source files (all your work goes here)
|   |   inerfaces/     
│   ├── schemas/       # Joi and Mongoose schemas
│   ├── types/         # TypeScript interfaces and types
│   └── index.ts       # Main export file for the library
├── .github/           # (Optional) GitHub-specific files like workflows
├── .gitignore
├── package.json       # Project manifest
├── README.md          # This file
└── tsconfig.json      # TypeScript compiler options

🏁 Getting Started

Prerequisites

To use this package, you will need:

• Node.js (v18 or higher recommended)
• npm or any other package manager
• mongoose as a peer dependency in your project if you intend to use the Mongoose schemas.

Installation

Install the package in your project using npm:

npm install @iserve/shared-types mongoose

💡 Usage

You can import types, schemas, and utilities directly from the package.

Using TypeScript Types

// In your application's code
import type { IUser } from '@iserve/shared-types';

const user: IUser = {
  username: 'terrence',
  email: '[email protected]',
  // ... other properties
};

function processUser(user: IUser) {
  console.log(user.email);
}

Using Joi Validation Schemas

// In your validation logic (e.g., in an Express route)
import { userJoiSchema } from '@iserve/shared-types';

const newUserPayload = req.body;

const { error, value } = userJoiSchema.validate(newUserPayload);

if (error) {
  return res.status(400).json({ message: error.details.message });
}

// 'value' is the validated and potentially coerced user data
// Proceed to create the user...

Using Mongoose Schemas

// In your Mongoose model definition
import { Schema } from 'mongoose';
import { userMongooseSchema, IUser } from '@iserve/shared-types';

// The schema is pre-defined, you just need to create the model
const UserSchema = new Schema<IUser>(userMongooseSchema, { timestamps: true });

export const UserModel = mongoose.model<IUser>('User', UserSchema);

🛠️ Development & Contribution

We welcome contributions! See PROJECT_RULES.md for developer dos and don'ts. Please follow these steps to set up the development environment and make changes.

1. Setup the Repository

1. Fork & Clone: Fork the repository to your GitHub account and clone it to your local machine.

   git clone https://github.com/AFROB-X-OSTech/iserve-shared-types.git
   cd iserve-shared-types

2. Install Dependencies:

   npm install

2. Available Scripts

• npm run dev: Starts tsup in watch mode for continuous compilation as you make changes.
• npm run build: Cleans the dist folder and performs a production build.
• npm run lint: Lints all files in the src directory using ESLint.
• npm run typecheck: Runs the TypeScript compiler to check for type errors without emitting files.

3. Contribution Workflow

1. Create a Branch: Create a new branch for your feature or bugfix. Use a descriptive name following conventional patterns.

   • For a new feature: git checkout -b feat/add-product-schema
   • For a bug fix: git checkout -b fix/correct-user-validation

2. Make Changes: Add or modify types, schemas, or utilities in the src directory. Remember to export any new additions from src/index.ts.

3. Validate Your Work: Before committing, ensure your changes haven't introduced any issues.

   npm run lint
   npm run typecheck

4. Commit Your Changes: We follow the Conventional Commits specification. This helps in automating versioning and generating changelogs.

   • feat: A new feature (e.g., feat: Add Order schema and types).
   • fix: A bug fix (e.g., fix: Allow null values for user middleName).
   • docs: Changes to documentation (e.g., docs: Update README with usage examples).
   • chore: Build process or tooling changes (e.g., chore: Upgrade tsup to latest version).
   • refactor: A code change that neither fixes a bug nor adds a feature.

   git add .
   git commit -m "feat: Add comprehensive Product schema with Joi validation"

5. Create a Pull Request: Push your branch to your fork and open a Pull Request against the main branch of the original repository. Provide a clear description of the changes you've made.

📦 Publishing to NPM (For Maintainers)

Publishing is handled by project maintainers to ensure stability.

Versioning Best Practices

This project adheres to Semantic Versioning (SemVer). The npm version command is used to correctly increment the version number, create a git tag, and commit the change.

• Patch Release (npm version patch): For backward-compatible bug fixes.

  npm version patch -m "chore(release): %s"

• Minor Release (npm version minor): For new, backward-compatible features.

  npm version minor -m "chore(release): %s"

• Major Release (npm version major): For breaking changes.

  npm version major -m "chore(release): %s"

Publishing Procedure

1. Ensure Main Branch is Up-to-Date:

   git checkout main
   git pull origin main

2. Run Final Checks: The prepublishOnly script automatically runs build and typecheck, but it's good practice to run them manually one last time.

   npm run lint
   npm run prepublishOnly

3. Bump the Version: Use the npm version command as described above. This will update package.json and create a tag.

4. Push Changes and Tags:

   git push origin main
   git push --tags

5. Publish to npm:

   npm publish

   The publishConfig.access in package.json is set to public, so it will be published as a public package.

📜 License

This project is licensed under the ISC License. See the LICENSE file for details.

📧 Contact

Terrence Mashego – [email protected]

Project Link: https://github.com/AFROB-X-OSTech/iserve-shared-types