ts-runtime-typecheck - npm Package Compare versions

Comparing version 1.1.0 to 1.1.1

cjs/TypeCast.type.d.ts

@@ -1,3 +0,2 @@
-import type { Optional } from './Optional.type';
 export declare type TypeCast<Output, Input = unknown> = (value: Input, fallback?: Output) => Output;
-export declare type OptionalTypeCast<Output, Input = unknown> = (value: Input) => Optional<Output>;
+export declare type OptionalTypeCast<Output, Input = unknown> = (value: Input) => Output | undefined;

mjs/TypeCast.type.d.ts

@@ -1,3 +0,2 @@
-import type { Optional } from './Optional.type';
 export declare type TypeCast<Output, Input = unknown> = (value: Input, fallback?: Output) => Output;
-export declare type OptionalTypeCast<Output, Input = unknown> = (value: Input) => Optional<Output>;
+export declare type OptionalTypeCast<Output, Input = unknown> = (value: Input) => Output | undefined;

package.json

 {
   "name": "ts-runtime-typecheck",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "A collection of common types for TypeScript along with dynamic type cast methods.",
@@ -5,0 +5,0 @@ "main": "cjs/index.js",

README.md

@@ -24,2 +24,3 @@ # ts-runtime-typecheck
   - [v1.1.0](#v110)
+  - [v1.1.1](#v111)
 
@@ -36,3 +37,3 @@ ## Installation
 
-Type casts take an unknown object as an argument, and return a typed object as the result. These functions take the form `as{TYPE}`, for example `asNumber`. If the input object does not match the required type the function will throw. This does not perform any coercion on the value, passing a string of a number to asNumber will cause it to throw.
+**Type Casts** take an `unknown` object as an argument, and return a typed object as the result. These functions take the form [`as{TYPE}`](#reference-type-casts), for example [`asNumber`](#asNumber). If the input object does not match the required type the function will throw. This does not perform any coercion on the value, passing a `string` of a number to [`asNumber`](#asNumber) will cause it to throw.
 
@@ -55,7 +56,7 @@ ```typescript
 
-These functions are meant to primarily validate questionable values that are expected to be in a well defined structure. Such as network responses, interfacing with untyped javascript or reading data back from a file. If you are looking to validate a type, without throwing an error then take a look at Type Checks.
+**Type Casts** are meant to primarily validate questionable values that are expected to be in a well defined structure. Such as network responses, interfacing with untyped JavaScript or reading data back from a file. If you are looking to validate a type, without throwing an error then take a look at [Type Checks](#type-checks).
 
 ### Fallback values
 
-The standard type cast functions take a second optional parameter, which is a _fallback_ value. In the situation that the input is *nullish* ( `undefined | null` ) and the fallback parameter has been defined the function will return the fallback parameter instead of throwing. This is very helpful for validating the input of an optional value, and providing a default value.
+The standard type cast functions take a second optional parameter, which is a _fallback_ value. In the situation that the input is [`Nullish`](#nullish) and the fallback parameter has been defined the function will return the fallback parameter instead of throwing. This is very helpful for validating the input of an optional value, and providing a default value.
 
@@ -78,7 +79,7 @@ ```typescript
 
-In the situation you want to preserve the optionally of a value, but still validate the type there exists an alternate function for each type cast. These take the form `asOpt{TYPE}`. Unlike the standard methods they do not take an optional fallback value, but when a nullish value is passed in they will always emit `undefined`. If the input is not nullish, then it behaves the same as the standard type casts. If the type condition is met then it emit the value, otherwise it will throw.
+In the situation you want to preserve the optionally of a value, but still validate the type there exists an alternate function for each type cast. These take the form [`asOpt{TYPE}`](#reference-optional-type-casts). Unlike the standard methods they do not take an optional fallback value, but when a [`Nullish`](#nullish) value is passed in they will always emit `undefined`. If the input is not [`Nullish`](#nullish), then it behaves the same as the standard type casts. If the type condition is met then it emits the value, otherwise it will throw.
 
 ### Special case: asDefined
 
-Another common situation is that you have an optional value, with a well defined type, but it *shouldn't* be optional at that time. TypeScript will allow you to cast the value to a non-optional type using `!`, but this is often discouraged in style guides as it can hide real errors. This is solved by the `asDefined` function, which removes the optionality from a type union. As with the other type casts this can take a fallback value, and will throw if the condition is not met. However, the output type matches the input type with nullish subtracted.
+Another common situation is that you have an [`Optional`](#optional) value, with a well defined type, but it *shouldn't* be [`Optional`](#optional) at that time. TypeScript will allow you to cast the value to a non-optional type using `!`, but this is often discouraged in style guides as it can hide real errors. This is solved by the [`asDefined`](#asdefined) function, which removes the optionality from a type union. As with the other type casts this can take a fallback value, and will throw if the condition is not met. However, the output type matches the input type with [`Nullish`](#nullish) subtracted.
 
@@ -101,3 +102,3 @@ ```typescript
 
-Validating that a value is an array or object is easy enough, but how about the contents? `asArrayRecursive` and `asObjectRecursive` allow for deep type casting through a user specified element cast. For example, to cast to an array of strings:
+Validating that a value is an array or object is easy enough, but how about the contents? [`asArrayRecursive`](#asarrayrecursive) and [`asObjectRecursive`](#asobjectrecursive) allow for deep type casting through a user specified element cast. For example, to cast to `Array<string>`:
 
@@ -114,3 +115,3 @@ ```typescript
 
-Or an array of numeric dictionaries:
+Or `Array<Dictionary<number>>`:
 
@@ -124,3 +125,3 @@ ```typescript
 
-  const arr: string[] = asArrayOfNumericRecords([
+  const arr = asArrayOfNumericRecords([
     {
@@ -142,3 +143,3 @@ a: 12,
 
-Type checks take an unknown object as an argument, and return a boolean indicating if the given value matches the required type. These functions take the form `is{TYPE}` In the correct situation TypeScript is capable of refining the type of a value through the use of these functions and flow analysis.
+Type checks take an unknown object as an argument, and return a boolean indicating if the given value matches the required type. These functions take the form [`is{TYPE}`](#reference-type-checks) In the correct situation TypeScript is capable of refining the type of a value through the use of these functions and flow analysis.
 
@@ -164,5 +165,5 @@ ```typescript
 
-Type coercion functions take an unknown object as an argument, and convert it into a specific type. These functions take the format `make{TYPE}`. Unlike the other functions this only works for small subset of types: number, string and boolean. They make a best effort to convert the type, but if the input is not suitable then they will throw. For instance passing a non-numeric string to `makeNumber` will cause it to throw, as will passing a string that is not `"true" | "false"` to `makeBoolean`. While these functions will take any input value, this is to allow the input of values that have not been validated, actually the only valid input types for all 3 functions are `number | string | boolean`. The intention here is to allow useful conversion, but prevent accidentally passing complex types.
+Type coercion functions take an unknown object as an argument, and convert it into a specific type. These functions take the format [`make{TYPE}`](#reference-type-coerce). Unlike the other functions this only works for small subset of types: number, string and boolean. They make a best effort to convert the type, but if the input is not suitable then they will throw. For instance passing a non-numeric string to [`makeNumber`](#make-number) will cause it to throw, as will passing a string that is not `"true" | "false"` to [`makeBoolean`](#make-boolean). While these functions will take any input value, this is to allow the input of values that have not been validated, actually the only valid input types for all 3 functions are `number | string | boolean`. The intention here is to allow useful conversion, but prevent accidentally passing complex types.
 
-There is an argument that `makeString` could support using the `toString` method of an `object`, but the default `toString` method returns the useless `[object Object]` string. It is possible to detect if an object has implemented it's own `toString` method, but is it correct to use it in this situation? That depends on the intention of the programmer. In the absence of a clear answer the line has been drawn at only accepting primitives.
+There is an argument that [`makeString`](#makestring) could support using the `toString` method of an `object`, but the default `toString` method returns the useless `[object Object]` string. It is possible to detect if an object has implemented it's own `toString` method, but is it correct to use it in this situation? That depends on the intention of the programmer. In the absence of a clear answer the line has been drawn at only accepting primitives.
 
@@ -187,3 +188,3 @@ ```typescript
 
-Dealing with validating JSON objects can often be frustrating, so to make it a little easier JSON specific types and checks are provided. Using the `JSONValue` type in your code will ensure that TS statically analyses any literal values as serializable to JSON.
+Dealing with validating JSON objects can often be frustrating, so to make it a little easier JSON specific types and checks are provided. Using the [`JSONValue`](#jsonvalue) type in your code will ensure that TS statically analyses any literal values as serializable to JSON.
 
@@ -206,5 +207,5 @@ ```typescript
 
-For dynamic data `isJSONValue` and `asJSONValue` provide recursive type validation on a value.
+For dynamic data [`isJSONValue`](#isjsonvalue) and [`asJSONValue`](#asjsonvalue) provide recursive type validation on a value.
 
-Type checks and casts are provided for `JSONArray`s and `JSONObject`s, with the caveat that they only accept `JSONValue`s. This is to avoid needing to recursively validate the object.
+Type checks and casts are provided for [`JSONArray`](#jsonarray)s and [`JSONObject`](#jsonobject)s, with the caveat that they only accept [`JSONValue`](#jsonvalue)s. This is to avoid needing to recursively validate the object.
 
@@ -230,3 +231,3 @@ ```typescript
 
-One other caveat of `JSONValue` is that it does not guarantee that the value is not cyclic. It is not possible to serialize cyclic object with JSON, but they are otherwise valid. Using `isJSONValue` or `asJSONValue` on a cyclic object *will fail*.
+One other caveat of [`JSONValue`](#jsonvalue) is that it does not guarantee that the value is not cyclic. It is not possible to serialize cyclic object with JSON, but they are otherwise valid. Using [`isJSONValue`](#isjsonvalue) or [`asJSONValue`](#asjsonvalue) on a cyclic object *will fail*.
 
@@ -284,3 +285,3 @@ ```typescript
 
-  Cast [`Type | Nullish`](#nullish) to `Type`, where `Type` is a generic parameter. Does *not* accept a fallback value.
+  Cast [`Type | Nullish`](#nullish) to `Type`, where `Type` is a generic parameter. Accepts an optional fallback value that is emitted if the value is nullish and fallback is defined.
 
@@ -485,1 +486,6 @@ - ### asJSONValue
 - Change: Optional type now also includes `null` in the type union.
+
+### v1.1.1
+
+- Change: return type of `asOpt{TYPE}` is now `TYPE | undefined` instead of `Optional<TYPE>` ( removes null from union )
+- Documentation corrections.

No alert changes

Improved metrics

Total package byte prevSize

52216

increased by1.15%

Number of lines in readme file

478

increased by1.27%

Worsened metrics

Lines of code

692

decreased by-0.29%

No dependency changes