# tristate-logic

> Tri-state logic for javascript

Latest version **1.0.4** (published 2017-10-16) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install tristate-logic
pnpm add tristate-logic
yarn add tristate-logic
bun add tristate-logic
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2017-10-16 |
| First published | 2017-10-15 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jonathan Essex |
| Maintainers | softwareplumber |
| Keywords | logic, boolean, tristate, nullable, sql |

## Links

- npm: https://www.npmjs.com/package/tristate-logic
- Repository: https://github.com/softwareplumbers/tristate-logic
- Homepage: https://github.com/softwareplumbers/tristate-logic#readme
- Issues: https://github.com/softwareplumbers/tristate-logic/issues
- npm.io page: https://npm.io/package/tristate-logic

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 1.0.4 (latest) — 2017-10-16
- 1.0.3 — 2017-10-16
- 1.0.2 — 2017-10-15
- 1.0.1 — 2017-10-15

## README

# ![Software Plumbers](http://docs.softwareplumbers.com/common/img/SquareIdent-160.png) Tristate Logic

Library for working with tri-state (true/false/null) logic in javascript

## Rationale

Tri-state logic is occasionally more useful than strict boolean logic, as it handles the real world
case where the truth of some propositions is unknown. Most SQL databases in fact implement a form of 
tri-state logic. For example, the WHERE clause `a = b OR c = d` will return results if a is null so
long as c = d, because 'UKNOWN or TRUE' is deemed TRUE.

Truth tables for classic tri-state logic are below:

### Truth Table for AND(a,b)

|a		|b		| AND	|
|-------|-------|-------|
|TRUE	|TRUE	|TRUE	|
|TRUE	|FALSE	|FALSE	|
|FALSE	|TRUE	|FALSE	|
|FALSE	|FALSE	|FALSE	|
|UNKNOWN|FALSE	|FALSE	|
|UNKNOWN|TRUE	|UNKNOWN|
|FALSE	|UNKNOWN|FALSE	|
|TRUE	|UNKNOWN|UNKNOWN|
|UNKNOWN|UNKNOWN|UNKNOWN|

### Truth Table for OR(a,b)

|a		|b		| OR    |
|-------|-------|-------|
|TRUE	|TRUE	|TRUE	|
|TRUE	|FALSE	|TRUE	|
|FALSE	|TRUE	|TRUE	|
|FALSE	|FALSE	|FALSE	|
|UNKNOWN|FALSE	|UNKNOWN|
|UNKNOWN|TRUE	|TRUE	|
|FALSE	|UNKNOWN|UNKNOWN|
|TRUE	|UNKNOWN|TRUE	|
|UNKNOWN|UNKNOWN|UNKNOWN|


If we map 'UKNOWN' to 'null' in javascript, the behaviour of the standard operators is frustratingly close to the above:

### Comparison of Tristate AND(a,b) with a && b

|a		|b		|a && b	| AND 	|
|-------|-------|-------|-------|
|false	|false	|false	|false	|
|false	|true	|false	|false	|
|true	|false	|false	|false	|
|true	|true	|true	|true	|
|null	|true	|null	|null	|
|null	|false	|_null_	|_false_|
|true	|null	|null	|null	|
|false	|null	|false	|false	|
|null	|null	|null	|null	|

### Comparison of Tristate OR(a,b) with a || b

|a		|b		| js or | OR    |
|-------|-------|-------|-------|
|false	|false	|false	|false	|
|false	|true	|true	|true	|
|true	|false	|true	|true	|
|true	|true	|true	|true	|
|null	|true	|true	|true	|
|null	|false	|_false_|_null_ |
|true	|null	|true	|true	|
|false	|null	|null	|null	|
|null	|null	|null	|null	|

The exceptions (in italics) unfortunately break some important cases; for if we want to iterate over a collection
until some condition is _definitely_ false, being unable to reliably destinguish between 'unknown' and 'false' 
is a problem.

## Example

```javascript
let result1 = and(null, false)
let result2 = or(null, false)
```

and result1 should equal `false` while result2 equals `null`. In other cases `and(a,b) === a && b`.

These simple binary and and or functions have to do some extra checks and comparisons in order to work. Some additional API is defined, which can be (very, very, slightly) more efficient and more explicit.

```javascript
let a = FALSE;
let b = TRUE;
let c = UNKNOWN;

if (a.and(c) === FALSE) console.log('hello'); 
```

will log 'hello'.

For the latest API documentation see [The Software Plumbers Site](http://docs.softwareplumbers.com/tristate-logic/master)

## Project Status

Beta. It seems functional, and the unit tests pass.

---
_Source: https://npm.io/package/tristate-logic · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._