Value Object JS – Documentation

1.Installation #

Yes No

2.API Documentation #

Yes No

2.1.Definition #

object ValueObject.define(string name, function|object definition);
A value object can be defined with either a validate function as second argument or an object representing the definition.

Using a definition object allows you to set more options. Only the validate method is required and the definition will fail if the method is not found.

The object is returned when defining it, but is also stored in the ValueObject library were it can be accessed by name at any time.

Yes No

2.1.1.Validate input #

bool validate(mixed value);

The validate method is the only required property of the definition. It will test the input value for validity; returning true will allow the object to exists, returning false will throw an InvalidArgumentException (or a custom exception if defined).

Yes No

2.1.2.Parse input #

mixed parse(mixed value);

parse method allows you to alter the input value before validating it. This might be useful when a proper value could be presented in different forms.

Yes No

2.1.3.Throw custom exception #

void throwException();

Custom exceptions might help you to understand errors in your application. In this method you can throw your own exception, which will be preferred to the default InvalidArgumentException when the validate method returns false.

Yes No

2.1.4.Extend #

string extend

Custom value objects might actually be based on simple data types like String or Number. Being able to use the native methods on those types (like substr, match, split, toFixed, etc.) improves the usability of the value object. With this property you can define the native data type, or even another value object, that methods will be inherited from.

Yes No

2.1.5.Custom methods and properties #

mixed *any

Improving the usability of value objects can be done easily by adding custom methods that help you to work with the actual value. Any property you define (function or otherwise) will be passed as-is to the value object.

Yes No

2.2.Usage #

Yes No

2.2.1.Instantiation #

Value objects are constructors and can be instantiated using the new keyword, passing the value as an argument. If the value is invalid an InvalidArgumentException (or a custom one, if defined) will be thrown.

Yes No

2.2.2.Type casting #

Value objects can be used in any operation. If the object represents a numerical value it can be used in calculations and when it represents a string value it can be concatenated to any other string. This is done using the native valueOf and toString methods.

Yes No

2.2.3.Comparison #

Comparing objects has always been kind of an issue in JavaScript. But with value objects it is possible:

Yes No

2.2.4.Type checking #

Value objects can be tested on type using instanceof in the same way as you are used to with native data types. And similar to native data types, when not using the literal notation, using the typeof operator will result in ‘object’.

Yes No

2.2.5.External validation #

Sometimes you do not want to try to create a value object, because it might result in an exception. It is possible to use the validate function on the value object constructor to test a value, making sure you have your validation code only in one place.

Please notice! The passed value will not be parsed with the parse method when you use the validate function like this.

Yes No

2.3.Advanced #

Yes No

2.3.1.Multiple arguments #

Sometimes it might seem convenient to pass more than 1 argument to a value object. This can be done, but it requires some special handling in the parse method. Multiple arguments will be received in value as an array and can be returned from the method in any way you want. But keep in mind that this might affect type casting.

Yes No

2.3.2.Immutability #

One of the basic properties of value objects is that they are immutable. This means the value can not be changed once it is initialized. This is the case for this library, but there is a weak spot. Objects and arrays (also objects) are passed by reference and are therefor a bit tricky to use as the main value of a value object. Even though you can not override the value property you can still access its value and alter that (in case of objects). Also if you pass a variable to the constructor and alter that later it will still be a reference.

Yes No