Skip to content

README.md

Latest commit

 

History

History
173 lines (122 loc) · 6.7 KB

README.md

File metadata and controls

173 lines (122 loc) · 6.7 KB
Raw

Spine Validation — TypeScript Client Library

Requires Node.js 24 or later; development and CI pin and test Node.js 24.18.0.

A TypeScript validation library for Protobuf messages using Spine Validation options, built on @bufbuild/protobuf (Protobuf-ES v2).

🔧 This library is in its experimental stage, the public API should not be considered stable.

💡 Why Use This?

For Spine Event Engine Users

This library lets you:

  • ✅ Reuse the same validation rules in your frontend that you defined in your backend.
  • ✅ Maintain a single source of truth — validation logic lives in your .proto files.
  • ✅ Keep frontend and backend validation in sync automatically.
  • ✅ Get type-safe validation with full TypeScript support.
  • ✅ Use error-message templates defined by the same Proto options.

For New Users

Even if you're not using Spine Event Engine, this library provides a way to add runtime validation to your Protobuf-based TypeScript applications:

  • ✅ Define validation in .proto files using declarative Spine Validation options.
  • ✅ Type-safe, runtime validation for Protobuf messages.
  • ✅ Clear, customizable error messages for better UX.
  • ✅ Works with Protobuf-ES v2 and modern tooling.

✨ Features

Comprehensive Validation Support

  • (required) — Validate the supported Proto-defined presence targets.
  • (pattern) — Regex validation for strings.
  • (min) / (max) — Numeric bounds with inclusive/exclusive support.
  • (range) — Bounded ranges with bracket notation (min..max].
  • (distinct) — Enforce uniqueness in repeated fields.
  • (validate) — Recursive nested message validation.
  • (goes) — Field dependency constraints.
  • (require) — Complex required field combinations with boolean logic.
  • (choice) — Require that a oneof group has at least one field set.
  • (when) — Validate Spine Time values against past/future bounds; copy the official spine/time_options.proto and its required Spine Time Proto files unchanged onto the import path.

Developer Experience

  • 🚀 Full TypeScript type safety.
  • 📝 Custom error messages.
  • 🧪 Comprehensive contract and regression tests.
  • 📚 Extensive documentation.
  • 🎨 Clean, readable error formatting.

⚠️ Known Limitations

  • (set_once) — Not currently supported. This option requires state tracking across multiple validations, which is outside the scope of single-message validation.
  • (pattern) — Uses ECMAScript RegExp; the official Proto documentation uses Java Pattern as its syntax baseline. See the package regular-expression limitation.

🚀 Getting Started

See the package guide, the development reference, the development guide, and the executable example.

@spine-event-engine/validation is not yet available from the public npm registry. See the package guide for the API and release status, or run the executable example from this repository.

📦 What's Included

This repository is structured as a pnpm workspace:

validation-ts/
├── packages/
│   ├── validation/              # 📦 Main validation package
│   │   ├── src/                 # Source code
│   │   ├── tests/               # Contract and regression tests
│   │   ├── proto/               # Official Spine and project Proto files
│   │   ├── docs/                # Repository-only development reference
│   │   └── README.md            # Full package documentation
│   │
│   └── example/                 # 🎯 Example project
│       ├── proto/               # Example proto files
│       ├── src/                 # Example usage code
│       └── README.md            # Example documentation
│
└── README.md                    # You are here

🎓 Documentation

See the package-level README for consumer setup and API details. The development reference contains architecture, exact validation behavior, and local development notes.

🛠️ Development

Setup

# Clone the repository
git clone <repository-url>
cd validation-ts

# Install with the pinned pnpm release without installing a system shim
corepack pnpm install --frozen-lockfile

On a cold host, Corepack may need network access for the pinned pnpm release; a cold pnpm store may then download the packages in the committed lockfile.

Build & Test

# Run the complete local and CI quality gate
corepack pnpm verify

Workspace Scripts

Command Description
corepack pnpm verify Run generation, typechecking, lint, format, coverage, docs, Proto, and package checks
corepack pnpm build Build the package and example
corepack pnpm test Run validation-package and executable-example Vitest tests
corepack pnpm example Run the example project

🤝 Contributing

See the contribution guide for review and delivery practices, and the development guide for local setup, generated inputs, extension workflows, and verification.

📄 License

Apache 2.0.

🔗 Related Projects

  • Protobuf-ES — Protocol Buffers for ECMAScript
  • Buf — Modern Protobuf tooling

Made with ❤️ for the Spine Event Engine ecosystem.

Documentation · Examples · Report Bug

License Protobuf-ES