# json-filter

> Match an object against a filter

Latest version **0.0.2** (published 2014-02-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install json-filter
pnpm add json-filter
yarn add json-filter
bun add json-filter
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2014-02-13 |
| First published | 2013-03-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Matt McKegg |
| Maintainers | mmckegg |
| Keywords | json, filter, query, validation |

## Links

- npm: https://www.npmjs.com/package/json-filter
- Repository: https://github.com/mmckegg/json-filter
- Issues: https://github.com/mmckegg/json-filter/issues
- npm.io page: https://npm.io/package/json-filter

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.0.2 (latest) — 2014-02-13
- 0.0.1 — 2013-12-13
- 0.0.0 — 2013-03-11

## README

JSON Filter
===

Match JSON objects against filters - used internally by [JSON Context](https://github.com/mmckegg/json-context), [Realtime Templates](https://github.com/mmckegg/realtime-templates) and [ContextDB](https://github.com/mmckegg/contextdb).

## Installation

```shell
$ npm install json-filter
```

## Filters

Filters are just object that have the keys and values you want your final object to have. e.g. if you wanted to require that the field `type` was always `person` your filter would be `{type: 'person'}`. 

If things aren't so black and white, the following conditionals are available:

#### $present

Specify that the value must not be null or false (i.e. 'truthy'). 

```js
{
  name: {$present: true}
}
```

#### $any

Specify that the value can be anything. Useful when matching all keys.

```js
{
  description: {$any: true}
}
```

#### $contains

For matching against an array. The array must contain all of the values specified.

```js
{
  tags: {$contains: ['cat', 'animal']}
}
```

#### $excludes

For matching against an array. The array cannot contain any of the values specified.

```js
{
  permissions: {$excludes: ['admin', 'mod']}
}
```

#### $only

The value can only be one of the ones specified.

```js
{
  gender: {$only: ['male', 'female', 'unknown']}
}
```

#### $not

The value can be anything except one of the ones specified.

```js
{
  browser: {$not: ['IE', 'Fifefox']}
}
```

#### $matchAny

Allows a filter to branch into multiple filters when at least one must match.

```js
{
  $matchAny: [
    { type: "Post"
      state: {$only: ['draft', 'published']}
    },
    { type: "Comment"
      state: {$only: ['pending', 'approved', 'spam']}
    }
  ]
}
```

#### $query

Specify a query to get the value to match. Uses `options.queryHandler`.

```js
{
  type: 'item',
  user_id: {$query: 'user.id'}
}
```

#### $optional

A shortcut for specifying a lot of $any filters at the same time.

```js
{
  $optional: ['description', 'color', 'age']
}
```

Is equivelent to:

```js
{
  description: {$any: true},
  color: {$any: true},
  age: {$any: true}
}
```

## API

```js
var checkFilter = require('json-filter')
```

### checkFilter(source, filter, options)

#### options:

- **match**: specify: 'filter', 'source', 'any', 'all'
  - filter: every filter permission must be satisfied (i.e. required fields)
  - source: every source key must be specified in filter
  - any: the keys don't matter, but if there is a match, they must pass
  - all: all keys must be exactly the same, otherwise fails - for finding changed items - no $conditionals work in this mode
- **queryHandler**: Accepts a function(query, localContext) that returns resulting value
- **context**: Object to pass to the query handler

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