ts-runtime-typecheck - npm Package Compare versions

Comparing version 2.3.0 to 2.4.0

cjs/index.js

@@ -11,2 +11,3 @@ 'use strict';
 var asInstance = require('./type-cast/as-instance.js');
+var asLiteral = require('./type-cast/as-literal.js');
 var isJson = require('./type-check/is-json.js');
@@ -18,6 +19,10 @@ var isPrimitive = require('./type-check/is-primitive.js');
 var isInstance = require('./type-check/is-instance.js');
-var makePrimative = require('./type-coerce/make-primative.js');
+var isLiteral = require('./type-check/is-literal.js');
+var makePrimitive = require('./type-coerce/make-primitive.js');
 var makeStrictPartial = require('./type-coerce/make-strict-partial.js');
 var assertDefined = require('./type-assert/assert-defined.js');
+var assertJson = require('./type-assert/assert-json.js');
+var assertPrimitive = require('./type-assert/assert-primitive.js');
 var TypeAssertion = require('./TypeAssertion.js');
+var invariant = require('./invariant.js');
 
@@ -47,3 +52,5 @@
 exports.asOptNumber = asPrimitive.asOptNumber;
+exports.asOptPrimitive = asPrimitive.asOptPrimitive;
 exports.asOptString = asPrimitive.asOptString;
+exports.asPrimitive = asPrimitive.asPrimitive;
 exports.asString = asPrimitive.asString;
@@ -60,2 +67,4 @@ exports.asOptStruct = asStruct.asOptStruct;
 exports.asOptInstance = asInstance.asOptInstance;
+exports.asLiteral = asLiteral.asLiteral;
+exports.asOptLiteral = asLiteral.asOptLiteral;
 exports.isJSONArray = isJson.isJSONArray;
@@ -83,3 +92,5 @@ exports.isJSONObject = isJson.isJSONObject;
 exports.isOptNumber = isPrimitive.isOptNumber;
+exports.isOptPrimitive = isPrimitive.isOptPrimitive;
 exports.isOptString = isPrimitive.isOptString;
+exports.isPrimitive = isPrimitive.isPrimitive;
 exports.isString = isPrimitive.isString;
@@ -97,7 +108,35 @@ exports.isUndefined = isPrimitive.isUndefined;
 exports.isOptInstance = isInstance.isOptInstance;
-exports.makeBoolean = makePrimative.makeBoolean;
-exports.makeNumber = makePrimative.makeNumber;
-exports.makeString = makePrimative.makeString;
+exports.isLiteral = isLiteral.isLiteral;
+exports.isOptLiteral = isLiteral.isOptLiteral;
+exports.literalTypeName = isLiteral.literalTypeName;
+exports.makeBoolean = makePrimitive.makeBoolean;
+exports.makeNumber = makePrimitive.makeNumber;
+exports.makeString = makePrimitive.makeString;
 exports.makeStrictPartial = makeStrictPartial.makeStrictPartial;
 exports.assertDefined = assertDefined.assertDefined;
+exports.assertJSONArray = assertJson.assertJSONArray;
+exports.assertJSONObject = assertJson.assertJSONObject;
+exports.assertJSONValue = assertJson.assertJSONValue;
+exports.assertOptJSONArray = assertJson.assertOptJSONArray;
+exports.assertOptJSONObject = assertJson.assertOptJSONObject;
+exports.assertOptJSONValue = assertJson.assertOptJSONValue;
+exports.assertArray = assertPrimitive.assertArray;
+exports.assertBoolean = assertPrimitive.assertBoolean;
+exports.assertDictionary = assertPrimitive.assertDictionary;
+exports.assertFunction = assertPrimitive.assertFunction;
+exports.assertIndex = assertPrimitive.assertIndex;
+exports.assertIndexable = assertPrimitive.assertIndexable;
+exports.assertNumber = assertPrimitive.assertNumber;
+exports.assertOptArray = assertPrimitive.assertOptArray;
+exports.assertOptBoolean = assertPrimitive.assertOptBoolean;
+exports.assertOptDictionary = assertPrimitive.assertOptDictionary;
+exports.assertOptFunction = assertPrimitive.assertOptFunction;
+exports.assertOptIndex = assertPrimitive.assertOptIndex;
+exports.assertOptIndexable = assertPrimitive.assertOptIndexable;
+exports.assertOptNumber = assertPrimitive.assertOptNumber;
+exports.assertOptPrimitive = assertPrimitive.assertOptPrimitive;
+exports.assertOptString = assertPrimitive.assertOptString;
+exports.assertPrimitive = assertPrimitive.assertPrimitive;
+exports.assertString = assertPrimitive.assertString;
 exports.TypeAssertion = TypeAssertion.TypeAssertion;
+exports.invariant = invariant.invariant;

cjs/type-assert/assert-defined.js

@@ -5,11 +5,9 @@ 'use strict';
 
+var invariant = require('../invariant.js');
 var isPrimitive = require('../type-check/is-primitive.js');
-var TypeAssertion = require('../TypeAssertion.js');
 
 function assertDefined(value, label = 'value') {
-    if (!isPrimitive.isDefined(value)) {
-        throw new TypeAssertion.TypeAssertion(`${label} is not defined`);
-    }
+    invariant.invariant(isPrimitive.isDefined(value), `${label} is not defined`);
 }
 
 exports.assertDefined = assertDefined;

cjs/type-cast/as-json.js

@@ -9,9 +9,9 @@ 'use strict';
 const asJSONValue = typeCast.typeCast(isJson.isJSONValue);
-const __isJSONArray = isJson.isJSONArray;
-const __isJSONObject = isJson.isJSONObject;
-const asJSONArray = typeCast.typeCast(__isJSONArray);
-const asJSONObject = typeCast.typeCast(__isJSONObject);
+const unsafeIsJSONArray = isJson.isJSONArray;
+const unsafeIsJSONObject = isJson.isJSONObject;
+const asJSONArray = typeCast.typeCast(unsafeIsJSONArray);
+const asJSONObject = typeCast.typeCast(unsafeIsJSONObject);
 const asOptJSONValue = typeCast.optTypeCast(isJson.isJSONValue);
-const asOptJSONArray = typeCast.optTypeCast(__isJSONArray);
-const asOptJSONObject = typeCast.optTypeCast(__isJSONObject);
+const asOptJSONArray = typeCast.optTypeCast(unsafeIsJSONArray);
+const asOptJSONObject = typeCast.optTypeCast(unsafeIsJSONObject);
 
@@ -18,0 +18,0 @@ exports.asJSONArray = asJSONArray;

cjs/type-cast/as-primitive.js

@@ -12,2 +12,3 @@ 'use strict';
 const asIndexable = typeCast.typeCast(isPrimitive.isIndexable);
+const asPrimitive = typeCast.typeCast(isPrimitive.isPrimitive);
 const asBoolean = typeCast.typeCast(isPrimitive.isBoolean);
@@ -30,2 +31,3 @@ const asArray = typeCast.typeCast(isPrimitive.isArray);
 const asOptIndexable = typeCast.optTypeCast(isPrimitive.isIndexable);
+const asOptPrimitive = typeCast.optTypeCast(isPrimitive.isPrimitive);
 const asOptBoolean = typeCast.optTypeCast(isPrimitive.isBoolean);
@@ -51,3 +53,5 @@ const asOptArray = typeCast.optTypeCast(isPrimitive.isArray);
 exports.asOptNumber = asOptNumber;
+exports.asOptPrimitive = asOptPrimitive;
 exports.asOptString = asOptString;
+exports.asPrimitive = asPrimitive;
 exports.asString = asString;

cjs/type-check/is-primitive.js

@@ -53,2 +53,10 @@ 'use strict';
 isOptIndex.TYPE_NAME = 'Optional<Index>';
+function isPrimitive(obj) {
+    return typeof obj === 'number' || typeof obj === 'string' || typeof obj === 'boolean';
+}
+isPrimitive.TYPE_NAME = 'Primitive';
+function isOptPrimitive(obj) {
+    return isPrimitive(obj) || isNullish(obj);
+}
+isOptPrimitive.TYPE_NAME = 'Optional<Primitive>';
 function isIndexable(obj) {
@@ -99,4 +107,6 @@ return obj !== null && typeof obj === 'object';
 exports.isOptNumber = isOptNumber;
+exports.isOptPrimitive = isOptPrimitive;
 exports.isOptString = isOptString;
+exports.isPrimitive = isPrimitive;
 exports.isString = isString;
 exports.isUndefined = isUndefined;

package.json

 {
   "name": "ts-runtime-typecheck",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A collection of common types for TypeScript along with dynamic type cast methods.",
@@ -20,12 +20,12 @@ "main": "cjs/index.js",
   "devDependencies": {
-    "@types/jest": "^26.0.23",
-    "@typescript-eslint/eslint-plugin": "^4.22.0",
-    "@typescript-eslint/parser": "^4.22.0",
-    "eslint": "^7.25.0",
-    "jest": "^26.6.3",
-    "rollup": "^2.46.0",
-    "rollup-plugin-typescript2": "^0.28.0",
-    "ts-jest": "^26.5.5",
-    "typescript": "^4.2.4"
+    "@types/jest": "^27.0.2",
+    "@typescript-eslint/eslint-plugin": "^5.2.0",
+    "@typescript-eslint/parser": "^5.2.0",
+    "eslint": "^8.1.0",
+    "jest": "^27.3.1",
+    "rollup": "^2.58.3",
+    "rollup-plugin-typescript2": "^0.30.0",
+    "ts-jest": "^27.0.7",
+    "typescript": "^4.4.4"
   }
 }

README.md

@@ -169,4 +169,2 @@ # ts-runtime-typecheck
 
-At the moment only 1 `TypeAssert` function exists which is `assertDefined`. It works in a similar way to `asDefined`, in that it accepts a generic type for its input, which is expected to be a union including null and/or undefined and asserts that the value is NonNullable. This is especially helpful for dealing with optional function arguments, if you want to ensure they exist under a certain situation you can just call `assertDefined`.
-
 ```typescript
@@ -186,2 +184,18 @@ import { assertDefined } from 'ts-runtime-typecheck';
 
+TypeAsserts cannot be based on generic types, due to limits in the TypeScript type system. Hence there is no equivalent to [`isStruct`](#isstruct) and similar [`TypeCheck`](#typecheck). However, there is an alternative. It's possible to utilise an invariant ( or assert) function with a [`TypeCheck`](#typecheck) to get the same effect, and an implementation of [`invariant`](#invariant) is provided for this purpose.
+
+```typescript
+import { invariant, isLiteral } from 'ts-runtime-typecheck';
+
+function main (meaningOfLife: unknown) {
+  meaningOfLife // unknown
+  invariant(isLiteral(42)(meaningOfLife), "Universe is broken, meaning of life isn't 42!");
+  meaningOfLife // 42
+  return 'but what is the question?';
+}
+
+main(42); // 'but what is the question?'
+main(); // TypeAssertion: Universe is broken, meaning of life isn't 42!
+```
+
 ---
@@ -306,3 +320,3 @@
 ```typescript
-import { asStruct, isString, isOptString, isNumber } from 'ts-runtime-typecheck';
+import { asStruct, isString, isNumber } from 'ts-runtime-typecheck';
 
@@ -318,2 +332,3 @@ interface Item {
   const item: Item = asItem(obj);
+
   console.log(`${item.name} = ${item.value}`);
@@ -326,3 +341,4 @@ }
 ```typescript
-import { asStruct, isString, isOptString, isNumber } from 'ts-runtime-typecheck';
+import { asStruct, isStruct, isString, isOptString, isNumber } from 'ts-runtime-typecheck';
+import type { Optional } from 'ts-runtime-typecheck';
 
@@ -334,2 +350,7 @@ interface Declaration {
 
+interface Item {
+  name: string;
+  value: number;
+}
+
 const isItem = isStruct({ name: isString, value: isNumber });
@@ -340,2 +361,3 @@ const asDeclaration = asStruct({ item: isItem, description: isOptString });
   const { item, description } = asDeclaration(obj);
+
   const comment: string = description ? `// ${description}` : '';
@@ -396,2 +418,40 @@ console.log(`${item.name} = ${item.value} ${comment}`);
 
+## Literal types
+
+TypeScript supports value types for [`Primitive`](#primitive)s. For example
+
+```typescript
+let a: 'hello world' = 'hello world';
+
+a = 'goodbye world'; // Type '"goodbye world"' is not assignable to type '"hello world"'
+```
+
+You can use [`asLiteral`](#asliteral) and [`isLiteral`](#isliteral) to construct [`TypeCast`](#typecast)s and [`TypeCheck`](#typecheck)s respectively for these value types. These checks can be particularly useful for discriminated unions.
+
+```typescript
+interface A {
+  type: 'a';
+  value: number;
+}
+
+interface B {
+  type: 'b';
+  value: number;
+}
+
+const isA = isStruct({
+  type: isLiteral('a'),
+  value: isNumber,
+});
+
+function main (n: A | B) {
+  n // A | B
+  if (isA(n)) {
+    n // A
+  } else {
+    n // B
+  }
+}
+```
+
 ## Reference
@@ -413,2 +473,6 @@
 
+- ### asPrimitive
+
+  Cast `unknown` to [`Primitive`](#primitive). Accepts an optional fallback value that is emitted if the value is nullish and fallback is defined.
+
 - ### asIndexable
@@ -466,2 +530,6 @@
 
+- ### asLiteral
+
+  Takes a [Primitive](#primitive) value and returns a new Type Cast for that specific value.
+
 ### Reference: Optional Type Casts
@@ -481,2 +549,6 @@
 
+- ### asOptPrimitive
+
+  Cast `unknown` value to [`Primitive | undefined`](#primitive). If value is [`Nullish`](#nullish) then return `undefined`.
+
 - ### asOptIndexable
@@ -538,2 +610,6 @@
 
+- ### asOptLiteral
+
+  Takes a [Primitive](#primitive) value and returns a new optional Type Cast for that specific value.
+
 ### Reference: Type Checks
@@ -565,2 +641,6 @@
 
+- ### isPrimitive
+
+  Takes an `unknown` value and returns a boolean indicating if the value is of the type [`Primitive`](#primitive).
+
 - ### isIndexable
@@ -618,2 +698,6 @@
 
+- ### isLiteral
+
+  Takes a [Primitive](#primitive) value and returns a new Type Check for that specific value.
+
 ### Reference: Optional Type Checks
@@ -641,2 +725,6 @@
 
+- ### isOptPrimitive
+
+  Takes an `unknown` value and returns a boolean indicating if the value is of the type [`Optional<Primitive>`](#primitive).
+
 - ### isOptIndex
@@ -686,2 +774,6 @@
 
+- ### isOptLiteral
+
+  Takes a [Primitive](#primitive) value and returns a new optional Type Check for that specific value.
+
 ### Reference: Type Coerce
@@ -711,2 +803,114 @@
 
+- ### assertNumber
+
+Assert value of type `unknown` is `number`. Accepts an optional name for the value that is included in the error if the value is not a number.
+
+- ### assertString
+
+Assert value of type `unknown` is `string`. Accepts an optional name for the value that is included in the error if the value is not a `string`.
+
+- ### assertBoolean
+
+Assert value of type `unknown` is `boolean`. Accepts an optional name for the value that is included in the error if the value is not a `boolean`.
+
+- ### assertIndex
+
+Assert value of type `unknown` is `Index`. Accepts an optional name for the value that is included in the error if the value is not a `Index`.
+
+- ### assertPrimitive
+
+Assert value of type `unknown` is `Primitive`. Accepts an optional name for the value that is included in the error if the value is not a `Primitive`.
+
+- ### assertArray
+
+Assert value of type `unknown` is `unknown[]`. Accepts an optional name for the value that is included in the error if the value is not a `unknown[]`.
+
+- ### assertDictionary
+
+Assert value of type `unknown` is `Dictionary`. Accepts an optional name for the value that is included in the error if the value is not a `Dictionary`.
+
+- ### assertIndexable
+
+Assert value of type `unknown` is `Indexable`. Accepts an optional name for the value that is included in the error if the value is not a `Indexable`.
+
+- ### assertFunction
+
+Assert value of type `unknown` is `UnknownFunction`. Accepts an optional name for the value that is included in the error if the value is not a `UnknownFunction`.
+
+- ### assertOptNumber
+
+Assert value of type `unknown` is `Optional<number>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<number>`.
+
+- ### assertOptString
+
+Assert value of type `unknown` is `Optional<string>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<string>`.
+
+- ### assertOptBoolean
+
+Assert value of type `unknown` is `Optional<boolean>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<boolean>`.
+
+- ### assertOptIndex
+
+Assert value of type `unknown` is `Optional<Index>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<Index>`.
+
+- ### assertOptPrimitive
+
+Assert value of type `unknown` is `Optional<Primitive>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<Primitive>`.
+
+- ### assertOptArray
+
+Assert value of type `unknown` is `Optional<unknown[]>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<unknown[]>`.
+
+- ### assertOptDictionary
+
+Assert value of type `unknown` is `Optional<Dictionary>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<Dictionary>`.
+
+- ### assertOptIndexable
+
+Assert value of type `unknown` is `Optional<Indexable>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<Indexable>`.
+
+- ### assertOptFunction
+
+Assert value of type `unknown` is `Optional<UnknownFunction>`. Accepts an optional name for the value that is included in the error if the value is not a `Optional<UnknownFunction>`.
+
+- ### assertJSONValue
+
+Assert value of type `unknown` is `JSONValue`. Accepts an optional name for the value that is included in the error if the value is not a `JSONValue`.
+
+- ### assertJSONArray
+
+Assert value of type `JSONValue` is `JSONArray`. Accepts an optional name for the value that is included in the error if the value is not a `JSONArray`.
+
+- ### assertJSONObject
+
+Assert value of type `JSONValue` is `JSONObject`. Accepts an optional name for the value that is included in the error if the value is not a `JSONObject`.
+
+- ### assertOptJSONValue
+
+Assert value of type `unknown` is `JSONValue | undefined`. Accepts an optional name for the value that is included in the error if the value is not a `JSONValue | undefined`.
+
+- ### assertOptJSONArray
+
+Assert value of type `JSONValue | undefined` is `JSONArray | undefined`. Accepts an optional name for the value that is included in the error if the value is not a `JSONArray | undefined`.
+
+- ### assertOptJSONObject
+
+Assert value of type `JSONValue | undefined` is `JSONObject | undefined`. Accepts an optional name for the value that is included in the error if the value is not a `JSONObject | undefined`.
+
+### Reference: Helper functions
+
+- ### invariant
+
+  An invariant is a logical declaration about a condition which the programmer knows to be true, but the compiler cannot. Many of the patterns in ts-runtime-typecheck are based around this concept, albeit to encourage a stricter and safer environment. This helper accepts a logical condition and a message. If the condition is true nothing happens, if it's false then a [`TypeAssertion`](#typeassertion) is thrown with the given message. If the condition is the result of a [`TypeCheck`](#typecheck) then the type predicate is enforced by the invariant.
+  
+  ```typescript
+  import { invariant, isString } from 'ts-runtime-typecheck';
+
+  function main (username: unknown) {
+    invariant(isString(username), 'Expected username to be a string');
+
+    username // string
+  }
+  ```
+
 ### Reference: Types
@@ -734,2 +938,6 @@
 
+- ### Primitive
+
+  A union of the `number`, `string` and `boolean` types that are the key primitive values in JS.
+
 - ### Indexable
@@ -849,1 +1057,10 @@
 - Change: build target to ES2018 instead of ES3.
+
+### 2.4.0
+
+- Add: `invariant` function to assist type assertion
+- Add: JSON assertion functions
+- Add: Basic type assertion functions
+- Add: Literal type casts and checks
+- Add: Primitive type, casts and checks
+- Documentation: Correct some typos in the `isStruct`/`asStruct` examples

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

Number of lines in readme file

1048

increased by26.11%

Worsened metrics

Total package byte prevSize

100522

decreased by-5.28%

Number of package files

50

decreased by-50.98%

Lines of code

1352

decreased by-11.52%

No dependency changes