# x-select

> selecting items from JSON using an extended json select language used by x-x.io x-components

Latest version **1.0.1** (published 2017-01-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install x-select
pnpm add x-select
yarn add x-select
bun add x-select
```

## Health

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

Positive: no vulnerabilities.

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

Negative: insecure dependencies; abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2017-01-18 |
| First published | 2014-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | maurice-schoenmakers |
| Keywords | x-x, x-component, traverse, js-traverse, json, select, js-select, JSONSelect, selectors, query, REST |

## Links

- npm: https://www.npmjs.com/package/x-select
- Repository: https://github.com/x-component/x-select
- Issues: https://github.com/x-component/x-select/issues
- npm.io page: https://npm.io/package/x-select

## Dependencies (3)

- [x-log](https://npm.io/package/x-log.md) 1.x.x
- [x-common](https://npm.io/package/x-common.md) 1.x.x
- [js-select](https://npm.io/package/js-select.md) git+https://github.com/MauriceSchoenmakers/js-select.git#e51000ed77

## 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

- 1.0.1 (latest) — 2017-01-18
- 1.0.0 — 2015-12-06
- 0.0.4 — 2014-03-17
- 0.0.3 — 2014-03-12
- 0.0.2 — 2014-02-21
- 0.0.1 — 2014-02-21

## README

# x-select

[Build Status](https://travis-ci.org/x-component/x-select.png?v1.0.1)](https://travis-ci.org/x-component/x-select)

- [./select.js](#selectjs) 

# ./select.js

  - [select](#select)

## select

  x-select
  ========
  
  This module can be used to select elements from nested *JSON data* objects with a css like syntax.
  
  It is based on [js-select](https://github.com/harthur/js-select) and thereby indreclty also on [JSONSelect](http://jsonselect.org/) and [js-traverse](https://github.com/substack/js-traverse)
  
  As an extension to the json selector syntax x-select also supports
  boolean expressions for sets. The sequential binary boolean logic operators 'and', 'or' and the unary 'not' are supported. Brackets`(` `)` can be used to create nested boolean expressions.  True and False are then represented by sets:
  an empty set represents false. A non empty set [true] represents true.
  
  
  Note: Per default the selecting of elments is done case insensitve and the following values are skipped from the result set `undefined`, `null`, `false`, `NaN`
  
  x-select is particularly usefull to handle deeply nested JSON structures as they are often returned by REST Services. (See examples)
  
  
  **usage**
  
  select
  ------
  
```js
  var select = require('x-select');
```

  
```js
  var result = select( object, selector, options );
```

  
  
  
  result.forEach(function(node){...})
  ------------------------------------
  
  You can loop over each found node within the structure
  
```js
  result.forEach(function(node){
      // this defines the context for the found element, see js-traverse documentation
      // you can use p.e. this.remove(); or this.update(new_value);
  });
```

  
  
  result.nodes()
  --------------
  This delivers simply an array of all found nodes
  
  
  result.empty()
  --------------
  returns if the result set is empty
  
  
  result.first()
  -------------
  Deliverse the first result found
  
  
  options.skip
  ------------
  
  options.skip is an array, which contains values to skip from the result set.
  select.skip: contains the default array
  To pass a changed skip array: on can use the default one use the functions `not` and `add` of that array, to modify it as shown
  here:
  
```js
  select(obj, ' .property ' , {skip: select.skip.not(false) } );
  select(obj, ' .property ' , {skip: select.skip.add('x').not(false) } );
```

  
  
  
  **Examples:**
  
  assume we have the following JSON structure:
  
```js
  var o = {
      users: [
          { person : { name: 'joe' , age: 20 , active:true, address: { street: 's1' } } },
          { person : { name: 'mary', age: 35 , active:false, friends : { person: { name: 'bob' } } },
          { person : { name: 'bob' , age: 40 , active:true} }
     ]
  };
```

  
  
```js
  var persons1 = select( o, '.users .person' ).nodes(); // returns 4 nodes {name: ....} also the person: {...} within friends
```

  
```js
  var persons2 = select( o, '.users > .person' ); // returns 0 nodes
```

  
```js
  var persons3 = select( o, '.users > object > .person' ); // returns 3 nodes {name: ....} directly within the objects in the array
```

  
```js
  var person   = select( o, ' .person:has( .age:expr( x < 30 || x >= 40 ) ) ').first(); // get the first person younger then 30 or older then 40
  var name     = select( person,'.name).first(); // joe
  var name2    = select( select(o, ' .person:has( .age:expr( x < 30 || x >= 40 ) ) ').nodes(), '.name' ).first(); // joe
```

  
```js
  var names   = select(o, ' .age:expr( x < 30 || x >= 40 ) ~ .name ').nodes(); // [ 'joe', 'bob' ]
```

  
```js
  var name_has_friend_bob = select(o, ' .person:has( .friends .name:val("bob")) > .name' ).first(); // 'mary'
```

  
```js
  var there_are_users_with_age_40_or_25  = !select(o,'.age:expr(x=40) or .age:expr(x=25)').empty();  // true
  var there_are_users_with_age_40_and_25 = !select(o,'.age:expr(x=40) and .age:expr(x=25)').empty(); // false
  var there_are_users_with_age_40_and_20 = !select(o,'.age:expr(x=40) and .age:expr(x=20)').empty(); // true
```

  
```js
  var active_user_count     = select(o,'.active').nodes().length; // 2, false is skipped per default nodes is [ true, true ]
  var has_active_flag_count = select(o,'.active',{skip:select.skip.not(false)}).nodes().length; // 3, nodes is [ true, false, true ]
```

  
```js
  // joe's age
  var age = select( o, ' .name:val("joe") ~ .age' ).first(); // 20
```

  
```js
  // today is joe's birthday, so increment the age
  select( o, ' .name:val("joe") ~ .age' ).forEach(function(age){
      this.update(age+1);
  });
```

  
```js
  var new_age = select( o, ' .name:val("joe") ~ .age' ).first(); // 21
```

  
  
  
  Notes:
  
  If the `object` is a dom tree node, `select()` will call `object.ownerDocument.defaultView.$` and return the result. In this case css selectors supported by
  the underlying css selector engine are supported.

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