type-plus 4.3.1 → 4.3.2

package/README.md

@@ -15,9 +15,10 @@ Provides additional types and type adjusted utilities for [TypeScript](https://w
 
 ## Feature Highlights
 
-- [Type assertion](#type-assertion)
-- [Nominal Types](#nominal-type)
+- [Type assertions](#type-assertions)
 - [Type Utilities](#type-utilities)
+- [Nominal Types](#nominal-types)
+- [Functional Types](#functional-types)
 
 ## Installation
 
@@ -27,12 +28,11 @@ npm install type-plus
 yarn add type-plus
 ```
 
-## Type Assertion
+## Type Assertions
 
-Besides the [runtime type checker](#runtime-type-checker),
-`type-plus` also provides a few other ways to do type assertions.
+Type assertion is one of the main features of `type-plus`.
 
-There are actually at least 5 kinds of type assertions:
+There are 5 kinds of type assertions:
 
 - `runtime`: validates during runtime.
 - `immediate`: validates at compile time.
@@ -264,70 +264,6 @@ assertType.isTrue(notA({ a: 1 }))
 notA({ a: '' }) // TypeScript complains
 ```
 
-## Nominal Type
-
-The TypeScript type system is structural.
-
-In some cases, we want to express a type with nominal behavior.
-`type-plus` provides two kinds of nominal types: `Brand` and `Flavor`.
-
-`Brand<B, T>`:
-
-`brand(type, subject?)`:
-
-Branded nominal type is the stronger nominal type of the two.
-It disallows unbranded type assigned to it:
-
-```ts
-const a = brand('a', { a: 1 })
-const b = { a: 1 }
-a = b // error
-```
-
-`subject` can be any type, from primitive to strings to objects.
-
-`brand(type)`:
-
-If you do not provide `subject`, `brand(type)` will return a brand creator,
-so that you can use it to create multiple branded values:
-
-```ts
-const nike = brand('nike')
-const shirt = nike('shirt')
-const socks = nike('socks')
-```
-
-`Flavor<F, T>`:
-
-`flavor(type, subject?)`:
-
-The key difference between `Flavor` and `Brand` is that
-unflavored type can be assigned to `Flavor`:
-
-```ts
-let f = flavor('orange', 'soda')
-f = 'mist' // ok
-```
-
-Also, `Brand` of the same name can be assigned to `Flavor`,
-but `Flavor` of the same name cannot be assigned to `Brand`.
-
-`nominalMatch(a, b)`:
-
-`nominalMatch()` can be used to compare `Brand` or `Flavor`.
-
-```ts
-const b1 = brand('x', 1)
-const b2 = brand('y', 1)
-
-nominalMatch(b1, b2) // false
-```
-
-## Functional Types
-
-- `ChainFn<T>: T`: chain function that returns the input type.
-- `compose(...fns): F`: compose functions
-
 ## Type Utilities
 
 `type-plus` also provides additional type utilities.
@@ -415,7 +351,7 @@ JSONTypes.get<string>(someJson, 'a', 'b', 1, 'c') // miku
 
 - `ANotB<A, B>`: get object with properties in `A` and not in `B`, including properties with a different value type.
 - `BNotA<A, B>`: flip of `ANotB`
-- `as<T>(subject)`: assert `subject` as `T`. Avoid ASI issues such as `;(x as any).abc`
+- `as<T>(subject)`: assert `subject` as `T`. Avoid ASI issues such as `;(x as T).abc`
 - `asAny(subject)`: assert `subject` as `any`. Avoid ASI issue such as `;(x as any).abc`
 - `Except<T, K>`: Deprecated. Same as `Omit<T, K>`.
 - `ExcludePropType<T, U>`: excludes type `U` from properties in `T`.
@@ -516,6 +452,70 @@ const source = {
 overrider(source, { foo: !!source.foo })
 ```
 
+## Nominal Types
+
+The TypeScript type system is structural.
+
+In some cases, we want to express a type with nominal behavior.
+`type-plus` provides two kinds of nominal types: `Brand` and `Flavor`.
+
+`Brand<B, T>`:
+
+`brand(type, subject?)`:
+
+Branded nominal type is the stronger nominal type of the two.
+It disallows unbranded type assigned to it:
+
+```ts
+const a = brand('a', { a: 1 })
+const b = { a: 1 }
+a = b // error
+```
+
+`subject` can be any type, from primitive to strings to objects.
+
+`brand(type)`:
+
+If you do not provide `subject`, `brand(type)` will return a brand creator,
+so that you can use it to create multiple branded values:
+
+```ts
+const nike = brand('nike')
+const shirt = nike('shirt')
+const socks = nike('socks')
+```
+
+`Flavor<F, T>`:
+
+`flavor(type, subject?)`:
+
+The key difference between `Flavor` and `Brand` is that
+unflavored type can be assigned to `Flavor`:
+
+```ts
+let f = flavor('orange', 'soda')
+f = 'mist' // ok
+```
+
+Also, `Brand` of the same name can be assigned to `Flavor`,
+but `Flavor` of the same name cannot be assigned to `Brand`.
+
+`nominalMatch(a, b)`:
+
+`nominalMatch()` can be used to compare `Brand` or `Flavor`.
+
+```ts
+const b1 = brand('x', 1)
+const b2 = brand('y', 1)
+
+nominalMatch(b1, b2) // false
+```
+
+## Functional Types
+
+- `ChainFn<T>: T`: chain function that returns the input type.
+- `compose(...fns): F`: compose functions
+
 ## Attribution
 
 Some of the code in this library is created by other people in the TypeScript community.

package/cjs/utils/as.d.ts

@@ -1,2 +1,2 @@
-export declare function as<T>(subject: unknown): subject is T;
-export declare function asAny(subject: unknown): subject is any;
+export declare function as<T>(subject: unknown): T;
+export declare function asAny(subject: unknown): any;

package/cjs/utils/as.js

@@ -2,11 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.asAny = exports.as = void 0;
 function as(subject) {
-    return true;
+    return subject;
 }
 exports.as = as;
 function asAny(subject) {
-    return true;
+    return subject;
 }
 exports.asAny = asAny;
 //# sourceMappingURL=as.js.map

package/cjs/utils/as.js.map

@@ -1 +1 @@
-{"version":3,"file":"as.js","sourceRoot":"","sources":["../../ts/utils/as.ts"],"names":[],"mappings":";;;AAAA,SAAgB,EAAE,CAAI,OAAgB;IACpC,OAAO,IAAI,CAAA;AACb,CAAC;AAFD,gBAEC;AAED,SAAgB,KAAK,CAAC,OAAgB;IACpC,OAAO,IAAI,CAAA;AACb,CAAC;AAFD,sBAEC"}
+{"version":3,"file":"as.js","sourceRoot":"","sources":["../../ts/utils/as.ts"],"names":[],"mappings":";;;AAAA,SAAgB,EAAE,CAAI,OAAgB;IACpC,OAAO,OAAY,CAAA;AACrB,CAAC;AAFD,gBAEC;AAED,SAAgB,KAAK,CAAC,OAAgB;IACpC,OAAO,OAAO,CAAA;AAChB,CAAC;AAFD,sBAEC"}

package/esm/utils/as.js

@@ -1,7 +1,7 @@
 export function as(subject) {
-    return true;
+    return subject;
 }
 export function asAny(subject) {
-    return true;
+    return subject;
 }
 //# sourceMappingURL=as.js.map

package/esm/utils/as.js.map

@@ -1 +1 @@
-{"version":3,"file":"as.js","sourceRoot":"","sources":["../../ts/utils/as.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,EAAE,CAAI,OAAgB;IACpC,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAgB;IACpC,OAAO,IAAI,CAAA;AACb,CAAC"}
+{"version":3,"file":"as.js","sourceRoot":"","sources":["../../ts/utils/as.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,EAAE,CAAI,OAAgB;IACpC,OAAO,OAAY,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAgB;IACpC,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "type-plus",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "description": "Provides additional types for TypeScript.",
   "homepage": "https://github.com/unional/type-plus",
   "bugs": {
@@ -26,7 +26,7 @@
     "ts"
   ],
   "scripts": {
-    "build": "run-p build:cjs build:esm build:doc",
+    "build": "run-p build:cjs build:esm",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:doc": "typedoc",
@@ -44,12 +44,8 @@
     "test:types": "tsc",
     "verify": "run-p verify:build lint test:types coverage",
     "verify:build": "npm-run-all clean build --parallel dependency-check size-limit",
-    "watch": "jest --watch"
-  },
-  "husky": {
-    "hooks": {
-      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-    }
+    "watch": "jest --watch",
+    "prepare": "husky install"
   },
   "dependencies": {
     "tersify": "^3.8.2",
@@ -72,7 +68,7 @@
     "dependency-check": "^4.1.0",
     "eslint": "^8.11.0",
     "eslint-plugin-harmony": "^6.0.0",
-    "husky": "^7.0.4",
+    "husky": "^7.0.0",
     "jest": "^27.5.1",
     "jest-progress-tracker": "^3.0.3",
     "jest-validate": "^27.5.1",
@@ -85,6 +81,7 @@
     "satisfier": "^5.1.2",
     "size-limit": "^7.0.8",
     "typedoc": "^0.22.13",
+    "typedoc-plugin-extras": "^2.2.3",
     "typescript": "^4.6.2"
   },
   "size-limit": [

package/ts/utils/as.spec.ts

@@ -1,24 +1,33 @@
-import { as, asAny, isType } from '..'
-
-describe('as<T>()', () => {
-  test('defaults subject type to unknown', () => {
-    const s: any = {}
-    if (as(s)) isType.equal<true, unknown, typeof s>()
-  })
-
-  test('cast type to T', () => {
-    const s: any = {}
-    if (as<number>(s)) isType.equal<true, number, typeof s>()
-    if (as<string>(s)) isType.equal<true, string, typeof s>()
-    if (as<{ a: number }>(s)) isType.equal<true, { a: number }, typeof s>()
-    if (as<any>(s)) isType.equal<true, any, typeof s>()
-  })
-})
-
-describe('asAny()', () => {
-  test('cast type to any', () => {
-    const s: unknown = {}
-    if (asAny(s)) isType.equal<true, any, typeof s>()
-  })
-})
-
+import { as, asAny, isType } from '..'
+
+describe('as<T>()', () => {
+  test('defaults subject type to unknown', () => {
+    const s: any = {}
+    const a = as(s)
+    isType.equal<true, unknown, typeof a>()
+  })
+
+  test('cast type to T', () => {
+    const s: any = {}
+    const n = as<number>(s)
+    isType.equal<true, number, typeof n>()
+
+    const str = as<string>(s)
+    isType.equal<true, string, typeof str>()
+
+    const o = as<{ a: number }>(s)
+    isType.equal<true, { a: number }, typeof o>()
+
+    const any = as<any>(s)
+    isType.equal<true, any, typeof any>()
+  })
+})
+
+describe('asAny()', () => {
+  test('cast type to any', () => {
+    const s: unknown = {}
+    const a = asAny(s)
+    isType.equal<true, any, typeof a>()
+  })
+})
+

package/ts/utils/as.ts

@@ -1,7 +1,7 @@
-export function as<T>(subject: unknown): subject is T {
-  return true
-}
-
-export function asAny(subject: unknown): subject is any {
-  return true
-}
+export function as<T>(subject: unknown): T {
+  return subject as T
+}
+
+export function asAny(subject: unknown): any {
+  return subject
+}