Skip to content

Commit

Permalink
Merge pull request #4 from wizard04wsu/fewer-keystrokes
Browse files Browse the repository at this point in the history 
Version 4 is not backwards compatible. It has been rewritten to be quicker/easier to type code, avoiding the need for string literals and comparison operators when possible.
  • Loading branch information
@wizard04wsu
wizard04wsu authored Jan 24, 2025
2 parents 769f5a4 + de018f8 commit 11c989f
Show file tree
Hide file tree
Showing 4 changed files with 393 additions and 467 deletions.
172 changes: 58 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,131 +4,75 @@ A robust alternative to JavaScript's built-in type testing.

See the [test page](https://wizard04wsu.github.io/javascript-type-testing/test/test.htm) for examples.

***Version 4 is not backwards compatible.***

---

---

## Type Names

This module uses an expanded set of type names that make no distinction between primitive values and objects.
For example, `5` and `new Number(5)` are both of type "number".
This module uses an expanded set of type names and related descriptors to simplify common tests of values.
Basic types do not distinguish between primitives and objects, but descriptors _primitive_ or _object_
can be used to determine that aspect.
For example, `5` and `new Number(5)` are both _number_, but `5` is _primitive_ and `new Number(5)` is _object_.

| Type Name | Values
| - | -
| array | `Array` objects
| bigint | _bigint_ primitives
| boolean | `false`, `true`, `Boolean` objects
| date | `Date` objects
| error | `Error` objects
| function | `Function` objects
| map | `Map` objects
| nan | `NaN`, `Number` objects with value `NaN`
| null | `null`
| number | _number_ primitives, `Number` objects; excludes `NaN` values
| object | instances of `Object` that don't match another type in this list
| promise | `Promise` objects
| regex | `RegExp` objects
| set | `Set` objects
| string | _string_ primitives, `String` objects
| symbol | _symbol_ primitives
| undefined | `undefined`
| weakmap | `WeakMap` objects
| weakset | `WeakSet` objects


## Determine a Type

The **is()** function returns an object describing the type of its argument.
The **is()** function returns an **IsType** object describing its argument.

Syntax:
> **is**(_value_)
Returned object:
| Property | Description
| - | -
| .**type** | The type name used by this module.
| .**typeof** | The value returned by the `typeof` operator.
| .**toStringTag** | The name used by `Object.prototype.toString()`. `undefined` for primitives.
| .**constructorName** | The name of the argument's constructor. `undefined` for primitives.
| .**isObject** | True if the value is an object.
| .**isPrimitive** | True if the value is a primitive.


## Type Testing

Each of the type-testing methods return a boolean indicating if the argument is of that type.

Syntax:
> is._typeTester_(_value_)
### Basics

| Method | Tests for
| - | -
| is.**function**() | instance of `Function`
| is.**object**() | instance of `Object`
| is.**primitive**() | primitives
| is.**null**() | `null`
| is.**nullish**() | `undefined`, `null`
| is.**undefined**() | `undefined`
| is.**defined**() | not `undefined`

### Booleans
## IsType Object

| Method | Tests for
| Member | Description
| - | -
| is.**boolean**() | `false`, `true`, instance of `Boolean`
| is.**falsy**() | `false`, `undefined`, `null`, `NaN`, `0`, `-0`, `0n`, `""`, [`document.all`](https://developer.mozilla.org/en-US/docs/Web/API/Document/all#conversion_to_boolean)
| is.**truthy**() | not falsy

### Numbers

| Method | Tests for
| - | -
| is.**bigint**() | _bigint_ primitive
| is.**date**() | instance of `Date`
| is.**numberish**() | _number_ primitive, instance of `Number`

_Numberish_ values can be more explicitly tested using the following methods:

| Method | Tests for
| - | -
| is.**real**() | real numbers
| is.**infinite**() | `Infinity`, `-Infinity`
| is.**number**() | real numbers, `Infinity`, `-Infinity`
| is.**nan**() | `NaN`
| .type | The type of _value_ (using this module's type names).
| .of(_class_) | Tests if _value_ was an instance of _class_.
| .all(_...descriptors)_ | Takes a list of descriptor names as arguments. Returns `true` if **all** of them applied to _value_.
| .any(_...descriptors_) | Takes a list of descriptor names as arguments. Returns `true` if **any** of them applied to _value_.
| \[[_descriptor_](#type-names-and-related-descriptors)\] | Descriptors are listed in the table below. Each descriptor property is a boolean that is `true` if it applied to _value_.

Enumerable properties of the **is** function are string values of the name of each descriptor. These can be used
in the `.all()` and `.any()` methods instead of string literals.
For example, <code>is(<i>value</i>).all("number", "object")</code> is equivalent to <code>is(<i>value</i>).all(is.number, is.object)</code>.


## Type Names and Related Descriptors

| Descriptor | Type Name | Primitive Values | Instances Of Classes
| - | - | - | -
| defined | | not undefined | `Object`
| **undefined** | yes | undefined |
| primitive | | not an instance of `Object` |
| **object** | yes | | `Object`
| objectish | | `null` | `Object`
| **null** | yes | `null` |
| nullish | | undefined, `null` |
| **boolean** | yes | `false`, `true` |
| false | | `false` |
| true | | `true` |
| falsy | | undefined, `null`, `false`, `0n`, `NaN`, `0`, `""` |
| truthy | | not _falsy_ | `Object`
| **symbol** | yes | a `Symbol` |
| **bigint** | yes | `0n`, `5n` |
| numberish | | `0`, `5`, `Infinity`, `NaN` | `Number`
| **nan** | yes | `NaN` | `Number` with value `NaN`
| **number** | yes | `0`, `5`, `Infinity` | `Number` excluding those with value `NaN`
| real | | `0`, `5` | `Number` with a real number value
| infinite | | `Infinity` | `Number` with an infinite value
| **string** | yes | `""`, `"foo"` | `String`
| **array** | yes | `[]`, `[1,2]` | `Array`
| **map** | yes | | `Map`
| **set** | yes | | `Set`
| **weakmap** | yes | | `WeakMap`
| **weakset** | yes | | `WeakSet`
| empty | | `""`, `[]` | `String` or `Array` of length == 0, `Map` or `Set` of size == 0
| nonempty | | not _empty_ | `String`, `Array`, `Map`, or `Set` that is not _empty_
| **date** | yes | | `Date`
| **error** | yes | | `Error`
| **function** | yes | | `Function`
| **promise** | yes | | `Promise`
| **regex** | yes | | `Regex`

## Note

Note that JavaScript doesn't always treat mathematical expressions of undefined or indeterminate form as you might expect. For example, `1/0` is an undefined form, but JavaScript evaluates it as `Infinity`.

### Text

| Method | Tests for
| - | -
| is.**regex**() | instance of `RegExp`
| is.**string**() | _string_ primitive, instance of `String`

### Collections

| Method | Tests for
| - | -
| is.**array**() | instance of `Array`
| is.**map**() | instance of `Map`
| is.**set**() | instance of `Set`
| is.**weakmap**() | instance of `WeakMap`
| is.**weakset**() | instance of `WeakSet`

### Other Common Types

| Method | Tests for
| - | -
| is.**error**() | instance of `Error`
| is.**promise**() | instance of `Promise`
| is.**symbol**() | _symbol_ primitive


## Additional Methods

| Method | Description
| - | -
| is.**empty**(_value_) | Tests if an object's `.length` or `.size` property equals zero.
| is.**of**(_value_, _class_) | Tests if _value_ is an instance of _class_. (Same as using the `instanceof` operator.)
Loading

0 comments on commit 11c989f

Please sign in to comment.