smart-value-objects

smart-value-objects

TypeScript library of smart Value Objects for Domain-Driven Design — catalog types, shared validation core, and constraints for UI binding.

Install

npm install smart-value-objects@^4.0.0

Requires Node.js 20+.

Five-minute start

import { EmailAddress, Title, validateRecord } from 'smart-value-objects';

// Single field
const emailResult = EmailAddress.tryCreate('user@example.com', 'email');
if (emailResult.ok) {
  console.log(emailResult.value.getDomain()); // example.com
}

// Multi-field (aggregated errors)
const validation = validateRecord(
  { title: 'Hello', email: 'bad' },
  { title: Title.tryCreate, email: EmailAddress.tryCreate },
);

if (!validation.isValid) {
  console.log(validation.errors); // all field errors at once
}

// UI max length — never hard-code
const maxTitle = Title.constraints.maxLength; // 120

Catalog (v2)

Type	Use for
Title	Titles, headings (max 120)
PersonName	Display names (max 80)
EmailAddress	Email addresses
Uuid	RFC 4122 identifiers

Each VO exposes create, tryCreate, and static constraints.

Core API

Export	Purpose
validateRecord	Multi-field validation, all errors returned
requireRecordObject	Guard unknown JSON body
ValidationResult / FieldError	Typed error aggregation
FieldConstraints	min/max/trim/pattern metadata
BaseValueObject	Extend for custom VOs

Documentation

Doc	Topic
docs/field-standards.md	Official limits per type
docs/validation-guide.md	tryCreate, validateRecord, HTTP 400
docs/cross-layer-guide.md	Same VO in front and back
docs/zod-coexistence.md	Zod at the wire, VO in domain
docs/migration-v1-v2.md	Upgrade from v1
docs/adoption-poc.md	POC — form + API same rules (G1/G2)
MIGRATION.md	Breaking changes summary

Examples

Path	Description
examples/consumer-form-api/	Shared schema for form + API
examples/ddd-demo/	Full DDD demo (not in npm export)

Cursor agent skill

Copy the consumer skill after install:

cp -r node_modules/smart-value-objects/skills/smart-value-objects-consumer .cursor/skills/

See docs/agent-ergonomics.md.

Development

git clone https://github.com/rtsarakaki/smart-value-objects.git
cd smart-value-objects
npm install
npm run quality   # type-check, lint, format, tests
npm run build

Migrating from v1

Install ^4.0.0 — npm latest. Versions 2.x/3.x are legacy value-objects releases. See MIGRATION.md.

License

MIT