# ssb-subset-ql

> Utility library to parse, validate, and compare ssb-ql-0 and ssb-ql-1

Latest version **1.0.1** (published 2022-10-17) · LGPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install ssb-subset-ql
pnpm add ssb-subset-ql
yarn add ssb-subset-ql
bun add ssb-subset-ql
```

## 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.1 |
| Published | 2022-10-17 |
| First published | 2021-08-12 |
| Weekly downloads | 0 |
| License | LGPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 32.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Andre 'Staltz' Medeiros |
| Maintainers | staltz, arj03 |

## Links

- npm: https://www.npmjs.com/package/ssb-subset-ql
- Repository: https://github.com/ssb-ngi-pointer/ssb-subset-ql
- Issues: https://github.com/ssb-ngi-pointer/ssb-subset-ql/issues
- npm.io page: https://npm.io/package/ssb-subset-ql

## Dependencies (3)

- [ssb-db2](https://npm.io/package/ssb-db2.md) >=3.0.0
- [ssb-ref](https://npm.io/package/ssb-ref.md) ^2.13.0
- [nano-equal](https://npm.io/package/nano-equal.md) ^2.0.2

## Recent versions

- 1.0.1 (latest) — 2022-10-17
- 1.0.0 — 2022-07-23
- 0.6.4 — 2022-04-13
- 0.6.3 — 2022-03-07
- 0.6.2 — 2021-10-08
- 0.6.1 — 2021-09-13
- 0.6.0 — 2021-09-10
- 0.5.0 — 2021-09-09
- 0.4.0 — 2021-09-08
- 0.3.0 — 2021-09-08
- 0.2.2 — 2021-09-08
- 0.2.1 — 2021-09-08
- 0.2.0 — 2021-08-12
- 0.1.0 — 2021-08-12

## README

<!--
SPDX-FileCopyrightText: 2021 Andre 'Staltz' Medeiros

SPDX-License-Identifier: CC0-1.0
-->

# ssb-subset-ql

Utility library to parse, validate, and compare ssb-ql-0 and ssb-ql-1 queries
needed for [subset replication and index feeds](https://github.com/ssb-ngi-pointer/ssb-subset-replication-spec)
in SSB.

## Installation

**Prerequisites:**

- Requires **Node.js 10** or higher

```
npm install --save ssb-subset-ql
```

To use this library, import its utilities like this:

```js
const { QL0 } = require('ssb-subset-ql')
```

## API

### QL0

#### `validate(query)`

Takes a `query` (string or object) and checks that it satisfies the ssb-ql-0
rules. If something is wrong, it throws an error. Otherwise it returns
undefined.

#### `parse(query)`

Takes a ssb-ql-0 `query` (an object or JSON as a string), validates it, and
parses it (if necessary) to return a query object. If anything went wrong during
validation, returns null.

#### `toOperator(query[, dedicated])`

Takes a ssb-ql-0 `query` (an object or JSON as a string), validates it, parses
it (if necessary) and then converts the query to an [ssb-db2](https://github.com/ssb-ngi-pointer/ssb-db2)
operator which can be inserted inside an ssb-db2 `where()`. If anything went
wrong during validation, it throws an error.

A second optional argument, `dedicated`, is a boolean that indicates whether the
underlying database should use dedicated index files for `type` and `author`. By
default, this is `false`.

#### `stringify(query)`

Takes a ssb-ql-0 `query` (an object), validates it, and stringifies it into a
canonical (stable, unaffected by how the object was created) JSON string.
Returns the JSON string. If anything went wrong during validation, it throws an
error.

#### `isEquals(query1, query2)`

Takes two ssb-ql-0 query objects, parses both of them, and checks that they are
equivalent.

### QL1

#### `validate(query)`

Takes a `query` (string or object) and checks that it satisfies the ssb-ql-1
rules. If something is wrong, it throws an error. Otherwise it returns
undefined.

#### `parse(query)`

Takes a ssb-ql-1 `query` (an object or JSON as a string), and parses it (if
necessary) to return a query object. If anything went wrong during validation,
returns null.

#### `toOperator(query[, dedicated])`

Takes a ssb-ql-1 `query` (an object), and converts it to an [ssb-db2](https://github.com/ssb-ngi-pointer/ssb-db2)
operator which can be inserted inside an ssb-db2 `where()`.

A second optional argument, `dedicated`, is a boolean indicating whether the
underlying database should use dedicated index files. By default, it's `false`.

#### `stringify(query)`

Takes a ssb-ql-1 `query` (an object), and stringifies it as a JSON string.

#### ~~`isEquals(query1, query2)`~~

Not yet supported. Will always throw an error if you use it.

## License

LGPL-3.0

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