Skip to content

README.md

Latest commit

 

History

History
97 lines (67 loc) · 3.16 KB

README.md

File metadata and controls

97 lines (67 loc) · 3.16 KB
Raw

Spine Validation TypeScript - Example Project

A standalone example demonstrating runtime validation of Protobuf messages with Spine Validation constraints.

What This Example Shows

  • ✅ Defining Protobuf messages with Spine Validation options.
  • ✅ Validating messages at runtime and formatting violations.
  • ✅ Programmatically handling validation violations.
  • ✅ Required values, patterns, ranges, distinct collections, nested messages, known Any payloads, and Spine Time (when) checks.

For public API details and option-by-option behavior, read the package guide.

Domain IDs

The account, catalog, and category identifiers use UserId, ProductId, and CategoryId messages. A domain message keeps an ID connected to what it names and leaves room for future ID details. Set an ID with its value, such as { value: "user-ada" }, { value: "prod-1" }, or { value: "cat-keyboards" }.

Quick Start

Install dependencies

From the repository root, use the Node.js version in .node-version:

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 locked packages.

Run the example

corepack pnpm example

This generates TypeScript from .proto files, builds the validation package and example, then prints the runnable scenarios.

Run the example tests

corepack pnpm build
corepack pnpm test:example

This clean-checkout-safe sequence builds validation dist, generates example schemas, and runs the example’s Vitest tests.

Scenarios

The console shows messages with missing user values, duplicate tags, an invalid email pattern, accepted and rejected timestamp (when) constraints, a product at its exact minimum price, nested category leaf violations, and known google.protobuf.Any payload leaf violations.

The runnable schemas are in proto/, scenarios are in src/scenarios.ts, and assertions are in tests/scenarios.test.ts.

proto/testing/invalid_configuration.proto is tests-only. It demonstrates a configuration error and is not a console scenario or runnable example schema.

Time Options

proto/user.proto imports spine/time_options.proto and applies (when) to two google.protobuf.Timestamp fields:

// Stores the account issuance time.
google.protobuf.Timestamp issued_at = 6 [(when).in = PAST];

// Stores the account expiration time.
google.protobuf.Timestamp expires_at = 7 [(when).in = FUTURE];

The example includes one message that satisfies both rules and one that violates both. See the validation contract for supported Spine Time message types and conversion details.

Next Steps

License

Apache License 2.0.