Value Object Lib

Small TypeScript library for creating immutable, validated Value Objects (strings, numbers, emails, UUIDs, dates, enums, phone numbers, and more). Designed for domain usage (DDD) or any layer where you want centralized validation and invariants.

Contents

• Exports a set of ready-to-use Value Objects: StringValueObject, NonEmptyStringValueObject, NumberValueObject, PositiveNumberValueObject, NonNegativeNumberValueObject, BooleanValueObject, DateValueObject, EmailValueObject, PhoneNumberValueObject, UUIDValueObject, EnumValueObject.

Installation

Install from npm (once published):

npm install value-object-lib
# or
yarn add value-object-lib

Usage

Example (ESM / TypeScript):

import { NonEmptyStringValueObject, EmailValueObject } from 'value-object-lib';

const name = new NonEmptyStringValueObject('Edgar');
const email = new EmailValueObject('[email protected]');

console.log(name.value); // 'Edgar'
console.log(email.toString());

Example (CommonJS):

const { UUIDValueObject } = require('value-object-lib');

const id = new UUIDValueObject('3f2504e0-4f89-11d3-9a0c-0305e82c3301');
console.log(id.value);

Error handling:

import { EmailValueObject } from 'value-object-lib';

try {
	new EmailValueObject('not-an-email');
} catch (err) {
	// err is a ValueObjectValidationError with a message explaining the reason
	console.error(err.message);
}

API / Exports

The package exports the value objects from the package root. Import only what you need:

import { StringValueObject, PositiveNumberValueObject, PhoneNumberValueObject } from 'value-object-lib';

Check the source (src/value-objects/) to see validations and available methods (value, toString(), toJSON(), equals()).

Useful scripts (development & publishing)

# clean and build
npm run build

# run tests
npm test

# preview what will be published
npm pack --dry-run

# publish (make sure you are logged in with `npm login`)
npm publish --access public

Note: the prepare script runs the build, so npm publish will trigger the build if dist/ is missing.

Best practices and recommendations

• Document public Value Objects and usage examples in the README (already included above).
• Include a LICENSE file (e.g., MIT) and populate package.json with repository, bugs, and homepage fields.
• Follow SemVer for releases (use npm version patch|minor|major).
• Publish only dist/ (the files field is already configured). Make sure .d.ts files are published.
• Add CI that runs npm test and npm run build before publishing.

Contributing

1. Fork the repo and create a descriptive branch.
2. Add tests for new behavior or features.
3. Open a pull request describing the change and motivation.

License

This repository includes a license file MIT.