type-plus 4.3.1 → 4.4.1

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`.
@@ -496,6 +432,7 @@ So you may encounter some weird behavior if your logic is complex.
 - `required(...)`: merge options and removing `Partial<T>`. From [`unpartial`](https://github.com/unional/unpartial)
 - `requiredDeep(...)`: merge options deeply and removing `Partial<T>`. From [`unpartial`](https://github.com/unional/unpartial)
 - `split(target, ...splitters)`: split one object into multiple objects.
+- `stub<T>(value)`: stub a particular type `T`.
 - `typeOverrideIncompatible<T>()`: override only the incompatible portion between two types.
 
 ```ts
@@ -516,6 +453,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/index.d.ts

@@ -13,5 +13,6 @@ export * from './object';
 export * from './predicates';
 export type { PrimitiveTypes } from './PrimitiveTypes';
 export * from './promise';
+export * from './testing';
 export type { UnionKeys } from './UnionKeys';
 export * from './utils';

package/cjs/index.js

@@ -31,6 +31,7 @@ __exportStar(require("./nominal-types"), exports);
 __exportStar(require("./object"), exports);
 __exportStar(require("./predicates"), exports);
 __exportStar(require("./promise"), exports);
+__exportStar(require("./testing"), exports);
 __exportStar(require("./utils"), exports);
 // export { types, types as T }
 //# sourceMappingURL=index.js.map

package/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAAmC;AACnC,uCAAkD;AAAzC,qGAAA,QAAQ,OAAA;AAAE,yGAAA,YAAY,OAAA;AAC/B,0CAAuB;AACvB,8CAA2B;AAC3B,0CAAuB;AAEvB,6CAA0B;AAC1B,+CAA4B;AAC5B,8CAA2B;AAC3B,yCAAsB;AACtB,2CAAwB;AACxB,kDAA+B;AAC/B,2CAAwB;AACxB,+CAA4B;AAE5B,4CAAyB;AAIzB,0CAAuB;AACvB,+BAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAAmC;AACnC,uCAAkD;AAAzC,qGAAA,QAAQ,OAAA;AAAE,yGAAA,YAAY,OAAA;AAC/B,0CAAuB;AACvB,8CAA2B;AAC3B,0CAAuB;AAEvB,6CAA0B;AAC1B,+CAA4B;AAC5B,8CAA2B;AAC3B,yCAAsB;AACtB,2CAAwB;AACxB,kDAA+B;AAC/B,2CAAwB;AACxB,+CAA4B;AAE5B,4CAAyB;AACzB,4CAAyB;AAIzB,0CAAuB;AACvB,+BAA+B"}

package/cjs/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './stub';

package/cjs/testing/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./stub"), exports);
+//# sourceMappingURL=index.js.map

package/cjs/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../ts/testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAsB"}

package/cjs/testing/stub.d.ts

@@ -0,0 +1,4 @@
+import { AnyFunction } from '../function';
+import { RecursivePartial } from '../object';
+export declare type Stub<T> = T extends AnyFunction ? T : RecursivePartial<T>;
+export declare function stub<T>(stub?: Stub<T>): T;

package/cjs/testing/stub.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stub = void 0;
+function stub(stub) {
+    return stub;
+}
+exports.stub = stub;
+//# sourceMappingURL=stub.js.map

package/cjs/testing/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../ts/testing/stub.ts"],"names":[],"mappings":";;;AAKA,SAAgB,IAAI,CAAI,IAAc;IACpC,OAAO,IAAS,CAAA;AAClB,CAAC;AAFD,oBAEC"}

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/index.js

@@ -12,6 +12,7 @@ export * from './nominal-types';
 export * from './object';
 export * from './predicates';
 export * from './promise';
+export * from './testing';
 export * from './utils';
 // export { types, types as T }
 //# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAClD,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AAEvB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAE5B,cAAc,WAAW,CAAA;AAIzB,cAAc,SAAS,CAAA;AACvB,+BAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAClD,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AAEvB,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAE5B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AAIzB,cAAc,SAAS,CAAA;AACvB,+BAA+B"}

package/esm/testing/index.js

@@ -0,0 +1,2 @@
+export * from './stub';
+//# sourceMappingURL=index.js.map

package/esm/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../ts/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA"}

package/esm/testing/stub.js

@@ -0,0 +1,4 @@
+export function stub(stub) {
+    return stub;
+}
+//# sourceMappingURL=stub.js.map

package/esm/testing/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../ts/testing/stub.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,IAAI,CAAI,IAAc;IACpC,OAAO,IAAS,CAAA;AAClB,CAAC"}

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.4.1",
   "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/index.ts

@@ -14,6 +14,7 @@ export * from './object'
 export * from './predicates'
 export type { PrimitiveTypes } from './PrimitiveTypes'
 export * from './promise'
+export * from './testing'
 // export * from './types/optional'
 // export * from './types/required'
 export type { UnionKeys } from './UnionKeys'

package/ts/testing/index.ts

@@ -0,0 +1 @@
+export * from './stub'

package/ts/testing/stub.spec.ts

@@ -0,0 +1,38 @@
+import { isType, stub } from '..'
+
+test('stub is a partial of the actual object', () => {
+  const real = { a: 1, b: { c: 2 }, d: 3 }
+
+  const a = stub<typeof real>({ a: 2 })
+  expect(a.a).toBe(2)
+  isType.equal<true, typeof a, typeof real>()
+})
+
+test('stub function retains param types', () => {
+  function real(a: string, b: number): boolean { return a === String(b) }
+
+  const a = stub<typeof real>((_a, _b) => {
+    isType.equal<true, string, typeof _a>()
+    isType.equal<true, number, typeof _b>()
+    return false
+  })
+
+  expect(a('1', 1)).toBe(false)
+  isType.equal<true, typeof a, typeof real>()
+})
+
+test('stub function params can be omitted', () => {
+  function real(a: string, b: number): boolean { return a === String(b) }
+
+  const a = stub<typeof real>(() => false)
+
+  expect(a('1', 1)).toBe(false)
+  isType.equal<true, typeof a, typeof real>()
+})
+
+test('stub input can be omitted', () => {
+  const real = { a: 1, b: { c: 2 }, d: 3 }
+
+  const a = stub<typeof real>()
+  isType.equal<true, typeof a, typeof real>()
+})

package/ts/testing/stub.ts

@@ -0,0 +1,8 @@
+import { AnyFunction } from '../function'
+import { RecursivePartial } from '../object'
+
+export type Stub<T> = T extends AnyFunction ? T : RecursivePartial<T>
+
+export function stub<T>(stub?: Stub<T>) {
+  return stub as T
+}

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
+}