Contributing Guide

Code of Conduct

Please be respectful and considerate of others when contributing to this project. We are committed to providing a welcoming and inclusive environment for everyone.

Project Philosophy

unreal-orm is designed to provide a type-safe interface to SurrealDB while staying as close as possible to SurrealDB’s native capabilities.
Key principles include:

Native First: Expose SurrealDB features directly, don’t abstract them away
Type Safety Without Overhead: Use TypeScript for developer experience, not runtime checks
Query Building: Allow direct SurrealQL usage with type safety
Schema Definition: Direct mapping to SurrealDB’s schema capabilities

Development Environment Setup

Prerequisites

Node.js (v18 or higher recommended)
pnpm (v8 or higher)
Bun (for testing)
SurrealDB (for integration tests)

Installation

Fork and clone the repository

git clone https://github.com/jimpex/unreal-orm.git
cd unreal-orm

Install dependencies
Terminal window
```
pnpm install
```
Build the project
Terminal window
```
pnpm run build
```
Run tests (bun required)
Terminal window
```
pnpm run test
```

Project Structure

unreal-orm is organized as a pnpm monorepo:

unreal-orm/
├── apps/                  # Applications
│   └── docs/              # Documentation site (Astro + Starlight)
├── packages/              # Packages
│   └── unreal-orm/        # Main library package
│       ├── src/           # Source code
│       └── tests/         # Tests

Development Workflow

Create a new branch for your feature/fix
Terminal window
```
git checkout -b feature/your-feature-name
```
Make your changes and ensure tests pass
Terminal window
```
pnpm run test
```
Update documentation as needed
Commit your changes with a descriptive message
Terminal window
```
git commit -m "feat: add new feature"
```
Push to your fork and submit a pull request

Pull Request Process

Ensure your PR addresses a specific issue or has a clear purpose
Update relevant documentation
Add or update tests as needed
Follow the coding guidelines
Make sure all tests pass
Request review from maintainers

Commit Message Format

We follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Common types:

feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code changes that neither fix bugs nor add features
test: Adding or updating tests
chore: Changes to the build process or auxiliary tools

Coding Guidelines

Code Style

Use TypeScript for all source files
Follow the established code style (enforced by the project’s linter)
Write clear, descriptive variable and function names
Use JSDoc comments for public APIs

Type Safety

Prioritize type-safety and avoid any types when possible
Use TypeScript’s type inference where appropriate
Document complex types with JSDoc comments

API Design

Follow the project’s Design Principles
Keep APIs consistent with existing patterns
Prioritize developer experience without abstractions

Testing

All new features should include tests
Run tests with pnpm run test
Integration tests should use the embedded SurrealDB instance
Ensure tests are deterministic and don’t rely on external services

Documentation

Update documentation for any changed functionality
Document public APIs with JSDoc comments
Include examples for new features
Keep the Capabilities document up to date

Thank you for contributing to unreal-orm!