Skip to content

Commit bab2932

Browse files
sciborrudnickisciborrudnicki
committed
docs(README.md): update
1 parent 5f4ce5d commit bab2932

File tree

1 file changed

+101
-36
lines changed

1 file changed

+101
-36
lines changed

‎README.md‎

Lines changed: 101 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -728,17 +728,23 @@ isFunction(() => 5); // true
728728

729729
![update][update]
730730

731-
`4.1.1`: Fixes type variable `Class` default value is set to [`Function`][function] by removing it cause it's always being picked from the `className` parameter.
731+
`4.1.1`:
732732

733-
Use `isInstance()` or `is.instance()` to check if **any** value is an `object` of a generic `Obj` type equal to an `instance` of [`Constructor<Class>`](#constructor) type.
733+
* Change the `Class` type variable to `Obj`.
734+
* Change the `className` parameter name to `constructor`.
735+
* Fixes type variable `Obj` default value is set to [`Function`][function] by removing it cause it's always being picked from the `constructor` parameter.
736+
* Removed unnecessary `Constructor` from the return type.
737+
* Add check `constructor` against the function.
738+
739+
Use `isInstance()` or `is.instance()` to check if **any** value is an `object` of a generic `Obj` type and an instance of [`Constructor`][constructor] type.
734740

735741
```typescript
736742
const isInstance: IsInstance =
737-
<Class = Function>(value: any, className: Constructor<Class>, callback: ResultCallback = resultCallback): value is Constructor<Class> =>
743+
<Obj>(value: any, constructor: Constructor<Obj>, callback: ResultCallback = resultCallback): value is Obj =>
738744
callback(
739-
isObject<Class>(value) ?
740-
isClass(className) ?
741-
value instanceof className === true
745+
isObject<Obj>(value) ?
746+
isClass<Obj>(constructor) || isFunction(constructor) ?
747+
value instanceof constructor === true
742748
: false
743749
: false,
744750
value
@@ -747,32 +753,33 @@ const isInstance: IsInstance =
747753

748754
**Generic type variables:**
749755

750-
| Type | Default value | Description |
751-
| :------ | :------------ | :-------------------------------------------------------------------- |
752-
| `Class` | `Function` | A generic variable to the return type `value` is `Constructor<Class>` |
756+
| Type | Default value | Description |
757+
| :---- | :------------ | :----------------------------------------------------- |
758+
| `Obj` | | A generic variable to the return type `value` is `Obj` |
753759

754760
**Parameters:**
755761

756-
| Name | Type | Description |
757-
| :------- | :-------------------------------------------------------------: | :----------------------------------------- |
758-
| value | `any` | Any `value` to compare with the `instance` |
759-
| instance | [`Constructor<Obj>`](#constructor) | A generic `Obj` [`Constructor<Obj>`](#constructor) type to create an `instance` to compare with the `value` |
760-
| callback | [`ResultCallback`][resultcallback]=[`resultCallback`][callback] | [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
762+
| Name | Type | Description |
763+
| :---------- | :-------------------------------------------------------------: | :------------------------------------------------- |
764+
| value | `any` | Any `value` to be an instance of the `constructor` |
765+
| constructor | [`Constructor<Obj>`][constructor] | A [`class`][ts-classes] or [`function`][ts-function] that specifies the type of the [`Constructor`][constructor] |
766+
| callback | [`ResultCallback`][resultcallback]=[`resultCallback`][callback] | A [`ResultCallback`][resultcallback] function to handle the result before returns eg. to throw an [`Error`][error] |
761767

762768
**Return type:**
763769

764-
| Returns | Type | Description |
765-
| :----------------- | :-------: | :---------------------------------------------------------------- |
766-
| `value` is `Class` | `boolean` | By default `Class` variable is equal to [`Function`][function] and the **return type** is a `boolean` as the result of its statement |
770+
| Returns | Type | Description |
771+
| :--------------- | :-------: | :---------------------------------------------------------------- |
772+
| `value` is `Obj` | `boolean` | The **return type** is a `boolean` as the result of its statement |
767773

768-
The **return value** is a `boolean` indicating whether or not the `value` is an `instance` of a generic `Class`.
774+
The **return value** is a `boolean` indicating whether or not the `value` is an instance of a generic `Obj`.
769775

770776
**Usage:**
771777

772778
```typescript
773779
// Example usage
774780
import { isInstance } from '@angular-package/type';
775781

782+
// Classes.
776783
class Some { x = 127; }
777784
class Two { y = 'Lorem ipsum'; }
778785

@@ -783,6 +790,18 @@ isInstance<Some>(TWO, Some); // false
783790
isInstance<Some>(SOME, Some); // true
784791
isInstance<Some>(TWO, Two); // true and type error
785792

793+
// Function constructor.
794+
function functionConstructor(this: any, ...args: any[]): any {
795+
if (args) {
796+
args.forEach((arg, index: number) => this[index] = arg[index]);
797+
}
798+
return this;
799+
}
800+
801+
const anyInstance: any = new (functionConstructor as any)('First name', 'Sur name', 27);
802+
803+
isInstance(anyInstance, functionConstructor as any); // true
804+
786805
```
787806

788807
[Example usage on playground][is-instance] | [How to detect `constructor` instance][detect-instance]
@@ -2274,7 +2293,7 @@ const guardFunction: GuardFunction = (value: Func, callback?: ResultCallback): v
22742293
| Name | Type | Description |
22752294
| :-------- | :--------------------------------: | :-------------------------------------- |
22762295
| value | [`Func`](#func) | A [`Func`](#func) type `value` to guard |
2277-
| callback? | [`ResultCallback`][resultcallback] | Optional [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
2296+
| callback? | [`ResultCallback`][resultcallback] | An optional [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
22782297

22792298
**Return type:**
22802299

@@ -2296,26 +2315,27 @@ The **return value** is a `boolean` indicating whether or not the `value` is a [
22962315

22972316
`4.1.0`: Fixes the `value` is not guarded by extending generic type `Obj` variable with `object`.
22982317

2299-
Use `guardInstance()` or `guard.is.instance()` to guard the `value` to be an `object` of a generic `Obj` type equal to an `instance` of [`Constructor<Obj>`](#constructor) type.
2318+
Use `guardInstance()` or `guard.is.instance()` to guard the `value` to be an `object` of a generic `Obj` type and an `instance` of [`Constructor`][constructor] type.
23002319

23012320
```typescript
2302-
const guardInstance: GuardInstance = <Obj extends object>(value: Obj, instance: Constructor<Obj>, callback?: ResultCallback): value is Obj =>
2303-
isInstance<Obj>(value, instance, callback);
2321+
const guardInstance: GuardInstance =
2322+
<Obj extends object>(value: Obj, constructor: Constructor<Obj>, callback?: ResultCallback): value is Obj =>
2323+
isInstance<Obj>(value, constructor, callback);
23042324
```
23052325

23062326
**Generic type variables:**
23072327

2308-
| Variable | Default value | Description |
2309-
| :------------ | :--------------- | :-------------------------------------------------------------------- |
2310-
| `Obj` | From the `value` | Guarded with `object`, `Obj` variable from the `value` to the return type `value` is `Obj` |
2328+
| Variable | Default value | Description |
2329+
| :------- | :--------------- | :----------------------------------------------------------------------------------------- |
2330+
| `Obj` | From the `value` | Guarded with `object`, `Obj` variable from the `value` to the return type `value` is `Obj` |
23112331

23122332
**Parameters:**
23132333

2314-
| Name | Type | Description |
2315-
| :-------- | :--------------------------------: | :--------------------------------------------------- |
2316-
| value | `Obj` | An `Obj` type `value` to compare with the `instance` |
2317-
| instance | [`Constructor<Obj>`](#constructor) | A generic `Obj` [`Constructor`](#constructor) type to create an `instance` to compare with the `value` |
2318-
| callback? | [`ResultCallback`][resultcallback] | Optional [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
2334+
| Name | Type | Description |
2335+
| :---------- | :--------------------------------: | :--------------------------------------------------- |
2336+
| value | `Obj` | A generic `Obj` type `value` to be an instance of the `constructor` |
2337+
| constructor | [`Constructor<Obj>`][constructor] | A [`class`][ts-classes] or [`[function]`][ts-function] that specifies the type of the [`constructor`][constructor] |
2338+
| callback? | [`ResultCallback`][resultcallback] | An optional [`ResultCallback`][resultcallback] function to handle the result before returns eg. to throw an [`Error`][error] |
23192339

23202340
**Return type:**
23212341

@@ -2325,6 +2345,46 @@ const guardInstance: GuardInstance = <Obj extends object>(value: Obj, instance:
23252345

23262346
The **return value** is a `boolean` indicating whether or not the `value` is an `instance` of a generic `Obj`.
23272347

2348+
**Usage:**
2349+
2350+
```typescript
2351+
// Usage example.
2352+
import { guardInstance } from '@angular-package/type';
2353+
2354+
// Person interface.
2355+
interface Person {
2356+
firstName?: string;
2357+
surname?: string;
2358+
age?: number;
2359+
sex?: 'male' | 'female';
2360+
}
2361+
2362+
// Class constructor.
2363+
class Persons implements Person {
2364+
firstName = '';
2365+
surname = '';
2366+
age = 15;
2367+
}
2368+
2369+
// Function person constructor.
2370+
function personFunctionConstructor(this: Person, ...args: any[]): Person {
2371+
if (args) {
2372+
this.firstName = args[0];
2373+
this.surname = args[1];
2374+
this.age = args[2];
2375+
this.sex = args[3];
2376+
}
2377+
return this;
2378+
}
2379+
2380+
const personInstance: Person = new (personFunctionConstructor as any)('First name', 'Sur name', 27);
2381+
const personsInstance: Persons = new Persons();
2382+
2383+
guardInstance(personInstance, personFunctionConstructor as any); // true
2384+
guardInstance(personsInstance, Persons); // true
2385+
2386+
```
2387+
23282388
----
23292389

23302390
### guardKey
@@ -2673,7 +2733,7 @@ const guardSymbol: GuardSymbol = (value: symbol, callback?: ResultCallback): val
26732733
| Name | Type | Description |
26742734
| :-------- | :--------------------------------: | :------------------------------- |
26752735
| value | `symbol` | A `symbol` type `value` to guard |
2676-
| callback? | [`ResultCallback`][resultcallback] | Optional [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
2736+
| callback? | [`ResultCallback`][resultcallback] | An optional [`ResultCallback`][resultcallback] function to handle the result before returns eg. to throw an [`Error`][error] |
26772737

26782738
**Return type:**
26792739

@@ -2702,11 +2762,11 @@ const guardType: GuardType = <T extends Type>(value: T, type: Types<T>, callback
27022762

27032763
**Parameters:**
27042764

2705-
| Name | Type | Description |
2706-
| :-------- | :--------------------------------: | :------------------------------------------------- |
2707-
| value | `T` extends [`Type`][type] | A [`Type`][type] `value` to guard with the `type` |
2708-
| type | [`Types<T>`](#types) | A `string` or generic [`Constructor<T>`](#constructor) type from the [`Types`](#types) to check the `value` |
2709-
| callback? | [`ResultCallback`][resultcallback] | Optional [`ResultCallback`][resultcallback] function to handle result before returns eg. to throw an [`Error`][error] |
2765+
| Name | Type | Description |
2766+
| :-------- | :--------------------------------: | :-------------------------------------------------------------------------------------------------------------------- |
2767+
| value | `T` extends [`Type`][type] | A [`Type`][type] `value` to guard with the `type` |
2768+
| type | [`Types<T>`](#types) | A `string` or generic [`Constructor<T>`][constructor] type from the [`Types`](#types) to check the `value` |
2769+
| callback? | [`ResultCallback`][resultcallback] | An optional [`ResultCallback`][resultcallback] function to handle the result before returns eg. to throw an [`Error`][error] |
27102770

27112771
**Return type:**
27122772

@@ -3155,6 +3215,7 @@ MIT © angular-package ([license][license])
31553215

31563216
<!-- Types -->
31573217
[callback]: #callback
3218+
[constructor]: #constructor
31583219
[defined]: #defined
31593220
[resultcallback]: #resultcallback
31603221
[key]: #key
@@ -3194,6 +3255,10 @@ MIT © angular-package ([license][license])
31943255

31953256
[undefined]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
31963257

3258+
<!-- Typescript -->
3259+
[ts-classes]: https://www.typescriptlang.org/docs/handbook/2/classes.html
3260+
[ts-function]: https://www.typescriptlang.org/docs/handbook/2/functions.html
3261+
31973262
<!-- Playground: are -->
31983263
[are-string]: https://www.typescriptlang.org/play?jsx=0#code/C4TwDgpgBAkgzgZWAJwJYDsDmUC8UAUAbgIYA2ArhAFxTHogCUuAfFCRdKnFHChpgG4AUKEhQACmgC2qYKkIRueAOQAjVJgzBlUAD5Q1Ae0OkIdHfuXpyU1RGQWDcELZOPlvNFnfl0AEwgAMwwIP2VhAGNDdF4oLiQvTBp4BP5cAnZKGjpGGkzObk80nFZ8uJjgOgiIQ0CoVKw9fVEaurKcDqc+b0jo2IiACwgIgGt0-BaaSVQZOQU4ABooADpV4mRMOGz6BhpVY1M6FigAbyEoKFNgKGRFclJrvBRKYQurqCkIYAHDP2TEbqCc48ADuskGBBaTDOFwuEWIcGgHkByhon2+v3S8UBAigqluxBGr1hAUCxHuwDRXx+fixAMSuPxZiJwIAvsDAoZkAQohVaBsoLV+ZtocCLrc4BT0uiafh1pgGMSLqg6vgJVKOngyaREaLYbCmYSlVB2RdTTcvuRkOgLZKHsJWb0+esIA1sHh8KtlvKtrQdnsDmYbSUoINhiN8MjEsoll6fYqhEIAPRJqAANXWqGIqlMcCEvNiCAAKgAlGAAOQA4gB9NMAQQAMgBVACi6WUDa5ECkcTAkqkAH5wvm+tdy02ALIAIRbJdrjdb6QATAB2J2xKcAeU3DZbdfL8+bba1ZER6+uTfLABEWwAxCstq+H1vVosAdU36V8pJCfmE70vG973LR9nxbYQRxiEwIGWUhDEwOVbjdfBALvB8n3rI8lmLMsqzApZx2nWd8KgLcdz3A9MNbBhFSgFMoG1RFILgaDYPgxDXUBfAcIrGsqJbbDS14sCaNxejnggZjWLghCXWQni8P4wTcL4hcBNI7dd33ETaPoxjJILaT2LkriFNUrCNPI7SlPqITFLU0S6NTfSgA
31993264

0 commit comments

Comments
 (0)