typescript-is - npm Package Compare versions

Comparing version 0.11.1 to 0.12.0

index.d.ts

 /**
- * Checks if the given argument matches the given type-argument.
+ * Checks if the given argument is assignable to the given type-argument.
  * 
  * @param object object whose type needs to be checked.
- * @returns `true` if `object` matches `T`, false otherwise.
+ * @returns `true` if `object` is assignable to `T`, false otherwise.
  * @example
@@ -29,5 +29,35 @@ ```
 /**
- * Asserts the given argument to be of the given type-argument.
- * If the given argument does not match the given type-argument, an error will be thrown.
+ * Checks if the given argument is assignable to the given type-argument and vice versa.
+ * Superfluous properties will cause the validation to fail.
  * 
+ * @param object object whose type needs to be checked.
+ * @returns `true` if `object` is assignable to `T` and if `T` is "assignable" to `object`, false otherwise.
+ * @example
+   ```
+   is<{ foo: string }>({}); // -> false
+   is<{ foo: string }>({ foo: 'bar' }); // -> true
+   is<{ foo: string }>({ foo: 'bar', baz: 'qux' }); // -> false
+   ```
+ */
+export function equals<T>(object: any): object is T;
+
+/**
+ * Creates a function similar to `equals<T>` that can be invoked at a later point.
+ * 
+ * This is useful, for example, if you want to re-use the function multiple times.
+ * 
+ * @example
+   ```
+   const checkObject = createEquals<{ foo: string }>();
+   checkObject({}); // -> false
+   checkObject({ foo: 'bar' }); // -> true
+   checkObject({ foo: 'bar', baz: 'qux' }); // -> false
+   ```
+ */
+export function createEquals<T>(): (object: any) => object is T;
+
+/**
+ * Asserts the given argument to be assignable to the given type-argument.
+ * If the given argument is not assignable to the given type-argument, an error will be thrown.
+ * 
  * @param object object whose type will be asserted.
@@ -58,2 +88,32 @@ * @returns the given `object`, or an error is thrown if validation failed.
 /**
+ * Asserts the given argument to be assignable to the given type-argument and vice versa.
+ * If the given argument is not assignable to the given type-argument, an error will be thrown.
+ * If the given type-argument is not assignable to the given argument, an error will be thrown.
+ * Superfluous properties will cause the validation to fail.
+ * 
+ * @param object object whose type will be asserted.
+ * @returns the given `object`, or an error is thrown if validation failed.
+ * @example
+   ```
+   const safeObject = assertEquals<{ foo: string }>({ foo: 'bar' }); // safeObject === { foo: 'bar' }, code continues
+   assertEquals<{ foo: string }>({ foo: 'bar', baz: 'qux' }); // throws an error
+   ```
+ */
+export function assertEquals<T>(object: any): T;
+
+/**
+ * Creates a function similar to `assertEquals<T>` that can be invoked at a later point.
+ * 
+ * This is useful, for example, if you want to re-use the function multiple times.
+ * 
+ * @example
+   ```
+   const assertObject = createAssertEquals<{ foo: string }>();
+   const safeObject = assertObject({ foo: 'bar' }); // safeObject === { foo: 'bar' }, code continues
+   assertObject({ foo: 'bar', baz: 'qux' }); // throws an error
+   ```
+ */
+export function createAssertEquals<T>(): (object: any) => T;
+
+/**
  * Options for the `AssertType` decorator.
@@ -60,0 +120,0 @@ */

index.js

@@ -72,2 +72,14 @@ function checkGetErrorMessage(getErrorMessage) {
 
-module.exports = { is, assertType, createIs, createAssertType, AssertType, ValidateClass, TypeGuardError };
+module.exports = {
+    is,
+    assertType,
+    createIs,
+    createAssertType,
+    equals: is,
+    createEquals: createIs,
+    assertEquals: assertType,
+    createAssertEquals: createAssertType,
+    AssertType,
+    ValidateClass,
+    TypeGuardError
+};

lib/transform-inline/transform-node.js

@@ -56,5 +56,7 @@ "use strict";
             && node.typeArguments.length === 1) {
+            const name = visitorContext.checker.getTypeAtLocation(signature.declaration).symbol.name;
+            const isEquals = name === 'equals' || name === 'createEquals' || name === 'assertEquals' || name === 'createAssertEquals';
             const typeArgument = node.typeArguments[0];
             const type = visitorContext.checker.getTypeFromTypeNode(typeArgument);
-            const arrowFunction = createArrowFunction(type, false, visitorContext);
+            const arrowFunction = createArrowFunction(type, false, Object.assign({}, visitorContext, { options: Object.assign({}, visitorContext.options, { disallowSuperfluousObjectProperties: isEquals || visitorContext.options.disallowSuperfluousObjectProperties }) }));
             return ts.updateCall(node, node.expression, node.typeArguments, [
@@ -61,0 +63,0 @@ ...node.arguments,

package.json

 {
   "name": "typescript-is",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "engines": {
@@ -5,0 +5,0 @@ "node": ">=6.14.4"

README.md

@@ -219,2 +219,18 @@ # typescript-is
 
+## Strict equality (`equals`, `createEquals`, `assertEquals`, `createAssertEquals`)
+
+This family of functions check not only whether the passed object is assignable to the specified type, but also checks that the passed object does not contain any more than is necessary. In other words: the type is also "assignable" to the object. This functionality is equivalent to specifying `disallowSuperfluousObjectProperties` in the options, the difference is that this will apply only to the specific function call. For example:
+
+```typescript
+import { equals } from 'typescript-is';
+
+interface X {
+    x: string;
+}
+
+equals<X>({}); // false, because `x` is missing
+equals<X>({ x: 'value' }); // true
+equals<X>({ x: 'value', y: 'another value' }); // false, because `y` is superfluous
+```
+
 To see the declarations of the functions and more examples, please check out [index.d.ts](https://github.com/woutervh-/typescript-is/blob/master/index.d.ts).
@@ -221,0 +237,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

216808

increased by1.86%

Lines of code

2607

increased by2.76%

Number of lines in readme file

300

increased by5.63%

No dependency changes