postgres-query-box 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/LICENSE +21 -0
- package/README.md +178 -2
- package/dist/chunk-VMCU5JEN.js +1196 -0
- package/dist/chunk-VMCU5JEN.js.map +1 -0
- package/dist/core.cjs +1235 -0
- package/dist/core.cjs.map +1 -0
- package/dist/core.d.cts +84 -0
- package/dist/core.d.ts +84 -0
- package/dist/core.js +45 -0
- package/dist/core.js.map +1 -0
- package/dist/index.cjs +2555 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +42 -0
- package/dist/index.d.ts +42 -0
- package/dist/index.js +1357 -0
- package/dist/index.js.map +1 -0
- package/dist/styles.css +313 -0
- package/package.json +83 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First version.
|
|
6
|
+
|
|
7
|
+
- Query box with suggestions for fields, operators and values, and coloured chips for methods and status codes.
|
|
8
|
+
- Mistakes are highlighted where they happen, with a plain message and one-click fixes.
|
|
9
|
+
- Long queries are laid out one condition per line while editing.
|
|
10
|
+
- Advanced filter for building queries visually.
|
|
11
|
+
- Saved queries driven by your callbacks: a Save popover, pinning, Edit and Create alert on each row, and a delete confirmation.
|
|
12
|
+
- Engine available on its own from `postgres-query-box/core`.
|
|
13
|
+
- `toSql` turns a query into a Postgres `WHERE` condition for a JSONB column, with `COUNT()` returned separately.
|
|
14
|
+
- Regex is checked against Postgres rules, with a fix from `\b` to `\y`. Text with a NUL character is an error.
|
|
15
|
+
- Suggestions: regex example and syntax cards, threshold examples for status codes, ports and latency, latency `BETWEEN`, operators grouped like the Advanced filter, more one-click fixes.
|
|
16
|
+
- Advanced filter: list values suggest as you type, and changing an operator keeps the existing value.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Darshan R
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,179 @@
|
|
|
1
|
-
#
|
|
1
|
+
# postgres-query-box
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A React search box for API transaction logs. People type a query such as `data.response.statusCode >= 500 AND data.request.verb == "POST"` and the box helps them as they go: it suggests fields, operators and values, explains mistakes and offers one-click fixes, and has an Advanced filter for building the same query visually. Saved queries are built in.
|
|
4
|
+
|
|
5
|
+
The box only handles the query. Your app keeps the results table, the API calls and everything else, and the box tells you when someone runs a query or changes a saved one.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
The package is not on npm yet. Install it from the folder or from your git host:
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
npm install ../postgres-query-box
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
It needs React 18 or newer.
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
```jsx
|
|
20
|
+
import { PostgresQueryBox, schemaFromFields } from 'postgres-query-box'
|
|
21
|
+
import 'postgres-query-box/styles.css'
|
|
22
|
+
|
|
23
|
+
const schema = schemaFromFields([
|
|
24
|
+
{ path: 'data.request.verb', type: 'string' },
|
|
25
|
+
{ path: 'data.request.path', type: 'string' },
|
|
26
|
+
{ path: 'data.response.statusCode', type: 'numtext' },
|
|
27
|
+
{ path: 'data.request.port', type: 'number' },
|
|
28
|
+
{ path: 'metadata.clientIp', type: 'ip' }
|
|
29
|
+
])
|
|
30
|
+
|
|
31
|
+
export function Search() {
|
|
32
|
+
return <PostgresQueryBox schema={schema} onRun={(text, ast) => loadResults(text)} />
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Telling the box about your fields
|
|
37
|
+
|
|
38
|
+
The box needs the list of fields people can search. You have two options:
|
|
39
|
+
|
|
40
|
+
- `schemaFromFields(fields)` when you already have a list of indexed fields. Each field has a `path` and a `type`. Optional: `group` (the heading it shows under), `count`, and `segs`.
|
|
41
|
+
- `buildSchema(rows)` to work the fields out from a sample of records shaped like `{ data, metadata }`.
|
|
42
|
+
|
|
43
|
+
Field types:
|
|
44
|
+
|
|
45
|
+
| Type | Use it for |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `string` | text |
|
|
48
|
+
| `numtext` | numbers stored as text, such as status codes |
|
|
49
|
+
| `number` | real numbers, such as ports |
|
|
50
|
+
| `boolean` | true or false |
|
|
51
|
+
| `ip` | IP addresses, enables `IP IN_RANGE` |
|
|
52
|
+
|
|
53
|
+
Some keys contain dots, for example `host.ip` under `metadata.additionalMetadata`. Pass `segs` for those so the box knows where the key starts: `{ path: 'metadata.additionalMetadata.host.ip', segs: ['metadata', 'additionalMetadata', 'host.ip'], type: 'ip' }`. If your field list escapes dots (`host\.ip`), unescape them first.
|
|
54
|
+
|
|
55
|
+
## Props
|
|
56
|
+
|
|
57
|
+
| Prop | What it does |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `schema` | The fields, from `schemaFromFields` or `buildSchema`. Required. |
|
|
60
|
+
| `value`, `onChange` | Control the text yourself. Leave them out and the box keeps its own text. |
|
|
61
|
+
| `defaultValue` | Starting text when you do not pass `value`. |
|
|
62
|
+
| `onRun(text, ast)` | Called when someone runs a valid query with Enter, Cmd or Ctrl and Enter, or the Run button. Nothing is called while the query has mistakes. |
|
|
63
|
+
| `placeholder`, `runLabel` | Text for the empty box and the Run button. |
|
|
64
|
+
| `tools` | Extra buttons shown inside the box, next to Queries. |
|
|
65
|
+
| `className` | Added to the outer element. |
|
|
66
|
+
|
|
67
|
+
The box also has a ref with `focus()`, `run()`, `setText(text)` and `getText()`.
|
|
68
|
+
|
|
69
|
+
## Saved queries
|
|
70
|
+
|
|
71
|
+
Pass `saved` and the box shows a Queries button with a panel: search, pinned queries first, then the rest. Each action appears only when you pass its callback. The box never calls an API itself. You save, pin, edit or delete, then pass the new list back in.
|
|
72
|
+
|
|
73
|
+
While the box is focused, Save and Create alert sit under the Queries button. They are enabled only when the query is valid. Save opens a "Save query as" popover with the name filled in and a pin checkbox. If the query is already saved and you pass `onUpdateSaved`, the popover updates that saved query instead.
|
|
74
|
+
|
|
75
|
+
```jsx
|
|
76
|
+
<PostgresQueryBox
|
|
77
|
+
schema={schema}
|
|
78
|
+
onRun={run}
|
|
79
|
+
saved={saved}
|
|
80
|
+
savedCount={total}
|
|
81
|
+
savedLoading={loading}
|
|
82
|
+
onSelectSaved={(s) => track(s.id)}
|
|
83
|
+
onPinSaved={(s, pinned) => api.pin(s.id, pinned).then(reload)}
|
|
84
|
+
onSaveQuery={({ name, query }) => api.create(name, query).then(reload)}
|
|
85
|
+
onDeleteSaved={(s) => api.remove(s.id).then(reload)}
|
|
86
|
+
onUpdateSaved={(s, changes) => api.update(s.id, changes).then(reload)}
|
|
87
|
+
onSavedSearch={(text) => setSearch(text)}
|
|
88
|
+
onCreateAlert={(query) => openAlertForm(query)}
|
|
89
|
+
/>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
A saved query is `{ id, name, query, pinned }`. Clicking one loads it into the box and runs it. Each row also has Pin, Create alert, Edit (name and query, checked as you type, with the same fixes as the box) and Delete (asks first).
|
|
93
|
+
|
|
94
|
+
`onUpdateSaved` gets `{ name, query }` from Edit and `{ name, pinned }` from the Save popover.
|
|
95
|
+
|
|
96
|
+
## The query language
|
|
97
|
+
|
|
98
|
+
| What you want | Example |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| Exact match | `data.request.verb == "GET"`, `data.response.statusCode != "404"` |
|
|
101
|
+
| Compare numbers | `data.response.statusCode >= 500`, `data.request.port < 1024` |
|
|
102
|
+
| Range | `data.response.statusCode BETWEEN 400 AND 499` |
|
|
103
|
+
| Any of a list | `data.request.verb ANYONE ["PUT", "PATCH"]`, `... NONEOF ["GET"]` |
|
|
104
|
+
| Text | `data.request.path CONTAINS "/health"`, `... NOT CONTAINS "/ping"` |
|
|
105
|
+
| Pattern | `data.request.path ~ "^/api/v1/.*"`, `~*` ignores case, `!~` and `!~*` negate |
|
|
106
|
+
| Field exists | `data.request.headerParams.x-apikey PRESENT`, `... ABSENT` |
|
|
107
|
+
| Latency in ms | `(metadata.responseTimestamp - metadata.requestTimestamp) > 2000` |
|
|
108
|
+
| IP address | `metadata.clientIp IP IN_RANGE "10.0.0.0/8"`, `... NOT_IN_RANGE ["10.0.0.0/8", "192.168.0.0/16"]` |
|
|
109
|
+
| Count | `data.response.statusCode == "401" AND COUNT() > 20 WITHIN 5m GROUP BY metadata.clientIp` |
|
|
110
|
+
|
|
111
|
+
Join conditions with `AND`, `OR` and `NOT`, and group them with brackets. `AND` binds tighter than `OR`, as in SQL. `COUNT()` goes last.
|
|
112
|
+
|
|
113
|
+
## What the box gives you, and what it does not
|
|
114
|
+
|
|
115
|
+
`onRun` hands you the query text in a tidy one-line form, plus a parsed tree (`ast`). Send the text, turn the tree into SQL with `toSql`, or build your own request from the tree.
|
|
116
|
+
|
|
117
|
+
## Turning a query into SQL
|
|
118
|
+
|
|
119
|
+
`toSql` turns the tree into a Postgres `WHERE` condition for a table that keeps each log as one JSONB document:
|
|
120
|
+
|
|
121
|
+
```js
|
|
122
|
+
import { parse, toSql } from 'postgres-query-box/core'
|
|
123
|
+
|
|
124
|
+
const { where, count } = toSql(parse(text, schema).ast, schema)
|
|
125
|
+
// where: "(NULLIF(data -> 'data' -> 'request' -> 'verb', 'null'::jsonb) = to_jsonb('GET'::text) AND ...)"
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- Fields are read from a JSONB column called `data`.
|
|
129
|
+
- `where` is one bracketed condition, ready to follow `AND` or `WHERE`. It is an empty string when the query has no conditions.
|
|
130
|
+
- Values are written into the SQL as quoted literals, so `where` can be added to a statement with no extra parameters. Quotes in values are escaped. This relies on `standard_conforming_strings`, which is on by default in Postgres.
|
|
131
|
+
- `?` only appears inside quoted text, so the SQL can go through JDBC and other drivers that treat `?` as a placeholder.
|
|
132
|
+
- A row that does not fit a condition is left out instead of failing the whole query. For example, a text value in a number field, or something that is not an IP address in an IP field.
|
|
133
|
+
|
|
134
|
+
The box checks everything Postgres would reject, so a query it accepts does not fail when it runs:
|
|
135
|
+
|
|
136
|
+
- Regex follows Postgres rules. The box shows an error for patterns Postgres rejects, such as named groups `(?<name>...)`, `\p{L}`, `[^]`, repeats over 255 or patterns too large to compile. It also flags patterns Postgres reads differently from JavaScript. For example, `\b` is a backspace in Postgres, so the box offers `\y` for a word boundary.
|
|
137
|
+
- Text with a hidden NUL character shows an error, because Postgres text cannot hold one. `toSql` throws if it is given one.
|
|
138
|
+
- Very long numbers are passed through as typed, so they never overflow.
|
|
139
|
+
- `COUNT()` cannot go into a `WHERE`, so it comes back as data for your server to apply. When the query has one, `count` holds `op` (`=`, `>`, `>=`, `<` or `<=`), `value`, `window` (the `WITHIN` window in milliseconds, 0 when there is none) and `by` (the `GROUP BY` field as a list of keys, or `null`). Without `COUNT()`, `count` is `null`. The rows a server should return are the ones in each group and window whose count passes, which is what `evaluate` does.
|
|
140
|
+
|
|
141
|
+
`toSql` and `evaluate` give the same rows. `test/sqlcheck.mjs` checks this against a real Postgres, and also checks that 5,000 random regexes the box accepts all compile there. It needs `psql` on your path and the usual `PG*` connection settings, and it only creates a temporary table.
|
|
142
|
+
|
|
143
|
+
Escaping makes the SQL safe for the query it was made from. A server that takes SQL text from the browser still runs whatever it is sent, so build the SQL on the server when you can.
|
|
144
|
+
|
|
145
|
+
## Using the engine on its own
|
|
146
|
+
|
|
147
|
+
Everything the box uses is also available without React, for example to check a saved query on a form or to format text:
|
|
148
|
+
|
|
149
|
+
```js
|
|
150
|
+
import { parse, format, validate, schemaFromFields } from 'postgres-query-box/core'
|
|
151
|
+
|
|
152
|
+
validate('(data.request.verb == "GET"', schema)
|
|
153
|
+
format(parse(text, schema).ast)
|
|
154
|
+
format(parse(text, schema).ast, null, true)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`validate` returns the first problem in plain words, or an empty string. `format(ast, null, true)` gives the one-condition-per-line layout the box shows while you edit.
|
|
158
|
+
|
|
159
|
+
## Styling
|
|
160
|
+
|
|
161
|
+
Import `postgres-query-box/styles.css` once. Every rule is scoped under the box's `.pqb` class, so it does not touch the rest of your page and your page's classes do not leak in. The box uses Inter and Roboto Mono when they are available and falls back to system fonts. It does not load any fonts itself.
|
|
162
|
+
|
|
163
|
+
## Working on the package
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
npm install
|
|
167
|
+
npm test # query rules and component tests
|
|
168
|
+
node test/sqlcheck.mjs # toSql against a real Postgres
|
|
169
|
+
npm run css # regenerates src/styles.css
|
|
170
|
+
npm run build # writes dist/
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`test/qcheck.mjs` covers the language: every example query, every error message and its fix, and what is suggested at each step. Run the tests after changing `src/core/engine.js`. `dist/` is committed so the package can be installed straight from git, so rebuild before committing.
|
|
174
|
+
|
|
175
|
+
`src/styles.css` is generated, so do not edit it by hand. `npm run css` reads the design system's Tailwind output in `scripts/tailwind.css`, keeps only the rules for classes used in `src`, scopes them under `.pqb` and writes the result. Run it whenever you add, remove or rename a class in a component. A class that is missing from `scripts/tailwind.css` is not styled. The script lists unknown class-like names at the end of its output. To use a newer Tailwind build, pass its path: `npm run css -- path/to/tailwind.css`. Colour names that start with `mds-` are renamed to `base-` as it reads them. Every rule matches elements inside `.pqb`, so a class on the element that carries `pqb` itself is not styled. Put layout classes on an inner element.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT
|