hhvm/type-assert

Convert untyped data to typed data

Wednesday, May 9, 2018
by fredemmott
Repository
5 Watchers
11 Stars
14,510 Installations

Hack
15 Dependents
0 Suggesters
4 Forks
5 Open issues
17 Versions
60 % Grown

The README.md

TypeAssert

, _(*1)

Hack library for converting untyped data to typed data., _(*2)

Warning for `TypeAssert\matches_type_structure()`

TypeStructure<T>, type_structure(), and ReflectionTypeAlias::getTypeStructures() are experimental features of HHVM, and not supported by Facebook or the HHVM team. This means that matches_type_structure() may need to be removed in a future release without warning., _(*3)

We strongly recommend moving to TypeAssert\matches<T>() and TypeCoerce\match<T>() instead., _(*4)

Installation

composer require hhvm/type-assert

Usage

TypeAssert provides functions that take a mixed input, and will either return it unmodified (but with type data) or throw an exception; for example:, _(*5)

<?hh // strict
use namespace Facebook\TypeAssert;
function needs_string(string $bar): void {
}

function main(): void {
  needs_string(TypeAssert\string('foo')); // type-safe and works fine
  needs_string(TypeAssert\string(123)); // type-safe, but throws
}

These include: - string(mixed): string - int(mixed): int - float(mixed): float - bool(mixed): bool - resource(mixed): resource - num(mixed): num - arraykey(mixed): arraykey - not_null<T>(?T): T - instance_of<T>(classname<T>, mixed): T - classname_of<T>(classname<T>, mixed): classname<T> - matches<T>(mixed): T - matches_type_structure<T>(TypeStructure<T>, mixed): T, _(*6)

Coercion

TypeAssert also contains the Facebook\TypeCoerce namespace, which includes a similar set of functions:, _(*7)

string(mixed): string
int(mixed): int
float(mixed): float
bool(mixed): bool
resource(mixed): resource
num(mixed): num
arraykey(mixed): arraykey
match<T>(mixed): T
match_type_structure<T>(TypeStructure<T>, mixed): T

These will do 'safe' transformations, such as int-ish strings to int, ints to strings, arrays to vecs, arrays to dicts, and so on., _(*8)

TypeSpec

You can also assert/coerce complex types (except for shapes and tuples) without a type_structure:, _(*9)

<?hh

use namespace Facebook\TypeSpec;

$spec = TypeSpec\dict(
  TypeSpec\string(),
  TypeSpec\int(),
);
$x = $spec->assertType(dict['foo' => 123]); // passes: $x is a dict<string, int>
$x = $spec->assertType(dict['foo' => '123']); // fails
$x = $spec->assertType(dict[123 => 456]); // fails
$x = $spec->assertType(dict[123 => 456]); // fails

$x = $spec->coerceType(dict[123 => '456']); // passes: $x is dict['123' => 456];

Shapes and tuples are not supported, as they can not be expressed generically., _(*10)

`matches_type_structure<T>(TypeStructure<T>, mixed): T`

Asserts that a variable matches the given type structure; these can be arbitrary nested shapes. This is particular useful for dealing with JSON responses., _(*11)

<?hh // strict

use namespace Facebook\TypeAssert;

class Foo {
  const type TAPIResponse = shape(
    'id' => int,
    'user' => string,
    'data' => shape(
      /* ... */
    ),
  );

  public static function getAPIResponse(): self::TAPIResponse {
    $json_string = file_get_contents('https://api.example.com');
    $array = json_decode($json_string, /* associative = */ true);
    return TypeAssert\matches_type_structure(
      type_structure(self::class, 'TAPIResponse'),
      $array,
    );
  }
}

You can use type_structure() to get a TypeStructure<T> for a type constant, or ReflectionTypeAlias::getTypeStructure() for top-level type aliases., _(*12)

`not_null<T>(?T): T`

Throws if it's null, and refines the type otherwise - for example:, _(*13)

<?hh // strict
use namespace \Facebook\TypeAssert;

function needs_string(string $foo): void {}
function needs_int(int $bar): void {}

function main(?string $foo, ?int bar): void {
  needs_string(TypeAssert\not_null($foo)); // ?string => string
  needs_int(TypeAssert\not_null($bar)); // ?int => int
}

`is_instance_of<T>(classname<T>, mixed): T`

Asserts that the input is an object of the given type; for example:, _(*14)

<?hh
use namespace Facebook\TypeAssert;

class Foo {}

function needs_foo(Foo $foo): void {}

function main(mixed $foo): void {
  needs_foo(TypeAssert::is_instance_of(Foo::class, $foo));
}

main(new Foo());

`is_classname_of<T>(classname<T>, mixed): classname<T>`

Asserts that the input is the name of a child of the specified class, or implements the specified interface., _(*15)

<?hh // strict
use namespace Facebook\TypeAssert;

class Foo {
  public static function doStuff(): void {}
}
class Bar extends Foo {
  <<__Override>>
  public static function doStuff(): void {
    // specialize here
  }
}

function needs_foo_class(classname<Foo> $foo): void {
  $foo::doStuff();
}

function main(mixed $class): void {
  needs_foo_class(TypeAssert::is_classname_of(Foo::class, $class));
}

main(Bar::class);

Credit

This library is a reimplementation of ideas from:, _(*16)

@admdikramr
@ahupp
@dlreeves
@periodic1236
@schrockn

Security Issues

We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue., _(*17)

Facebook has a bounty program for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue., _(*18)

License

Type-Assert is MIT-licensed., _(*19)

The Versions

09/05 2018

dev-master

9999999-dev

Convert untyped data to typed data

library type-assert

Convert untyped data to typed data

hhvm/type-assert

The README.md

TypeAssert

Warning for TypeAssert\matches_type_structure()

Installation

Usage

Coercion

TypeSpec

matches_type_structure<T>(TypeStructure<T>, mixed): T

not_null<T>(?T): T

is_instance_of<T>(classname<T>, mixed): T

is_classname_of<T>(classname<T>, mixed): classname<T>

Credit

Security Issues

License

The Versions

dev-master

The Requires

The Development Requires

v3.2.2

The Requires

The Development Requires

v3.2.1

The Requires

The Development Requires

v3.2.0

The Requires

The Development Requires

v3.1.0

The Requires

The Development Requires

v3.0.x-dev

The Requires

The Development Requires

v3.0.4

The Requires

The Development Requires

v3.0.3

The Requires

The Development Requires

v3.0.2

The Requires

The Development Requires

v3.0.1

The Requires

The Development Requires

v3.0

The Requires

The Development Requires

v2.0

The Requires

The Development Requires

v1.1.1

The Requires

The Development Requires

v1.1

The Requires

The Development Requires

v1.0

The Requires

The Development Requires

v0.2

The Requires

The Development Requires

v0.1

The Requires

The Development Requires

Warning for `TypeAssert\matches_type_structure()`

`matches_type_structure<T>(TypeStructure<T>, mixed): T`

`not_null<T>(?T): T`

`is_instance_of<T>(classname<T>, mixed): T`

`is_classname_of<T>(classname<T>, mixed): classname<T>`