@niscorp/vex 0.4.1 → 0.4.3
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 +21 -0
- package/DESIGN.md +3 -1
- package/DOCS.md +51 -19
- package/README.md +2 -2
- package/dist/adapters/express/index.cjs +17 -17
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.js +1 -1
- package/dist/adapters/hono/index.cjs +17 -17
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.js +1 -1
- package/dist/adapters/pg/index.cjs +44 -0
- package/dist/adapters/pg/index.cjs.map +1 -0
- package/dist/adapters/pg/index.d.cts +28 -0
- package/dist/adapters/pg/index.d.ts +28 -0
- package/dist/adapters/pg/index.js +31 -0
- package/dist/adapters/pg/index.js.map +1 -0
- package/dist/adapters/pglite/index.cjs +3 -1
- package/dist/adapters/pglite/index.cjs.map +1 -1
- package/dist/adapters/pglite/index.d.cts +5 -4
- package/dist/adapters/pglite/index.d.ts +5 -4
- package/dist/adapters/pglite/index.js +3 -3
- package/dist/adapters/pglite/index.js.map +1 -1
- package/dist/chunk-DFWYYBJU.js +7 -0
- package/dist/chunk-DFWYYBJU.js.map +1 -0
- package/dist/{chunk-AKR6HU34.js → chunk-W5MYFJKT.js} +19 -19
- package/dist/chunk-W5MYFJKT.js.map +1 -0
- package/dist/date-parsers-BaUuE_ax.d.cts +4 -0
- package/dist/date-parsers-BaUuE_ax.d.ts +4 -0
- package/dist/index.cjs +17 -17
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +2 -2
- package/package.json +13 -1
- package/dist/chunk-AKR6HU34.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,26 @@
|
|
|
1
1
|
# @niscorp/vex
|
|
2
2
|
|
|
3
|
+
## 0.4.3
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- c5f8e64: `insertEach` converts each `{ $item }` value by its column's own type, as Postgres converts an `insert`'s value. It cast through a fixed list of five types before, so Postgres refused every other column type (`column is of type … but expression is of type text`).
|
|
8
|
+
- **Columns it now writes:** `time`, enums, `inet`, `interval`, arrays (an item is a JSON array) and pgvector `vector`, also when the extension lives in another schema. A vector item is a JSON array of numbers (`[0.1, 0.2]`) or the pgvector text form (`"[0.1,0.2]"`), so a list of embeddings goes in one statement.
|
|
9
|
+
- **A `timestamp` (without time zone) is stored as `insert` stores it.** It was read as `timestamptz`, so with the session's time zone at Europe/Vienna, `2026-10-26T09:30:00Z` landed as 10:30; it now lands as 09:30.
|
|
10
|
+
- **A fraction for an integer column is refused, as `insert` refuses it.** It was rounded: 7.5 stored 8.
|
|
11
|
+
|
|
12
|
+
**What to change:** an app that sends fractions to an integer column through `insertEach` rounds them itself. An app whose database sessions are not on UTC and that wrote a zoned value into a `timestamp` column through `insertEach` has shifted rows from before; new rows are not shifted.
|
|
13
|
+
|
|
14
|
+
## 0.4.2
|
|
15
|
+
|
|
16
|
+
### Patch Changes
|
|
17
|
+
|
|
18
|
+
- 2a6f8d6: An insert's `onConflict.set` is held to every `match` rule of the update phase, one on a column of the conflict target included: each becomes a WHERE on the DO UPDATE half, so a conflict with a row the caller may not update writes nothing and returns no row.
|
|
19
|
+
|
|
20
|
+
Before, a `match` on a conflict-target column was left out, on the reasoning that the insert pins that column from scope. Where the policy's insert phase does not pin it — no insert rule for that column, or two merged roles of which one may insert anywhere — an entry that takes that column's value from the caller let them overwrite, and read back, a row their update rule excludes.
|
|
21
|
+
|
|
22
|
+
- 915efe6: `@niscorp/vex/pg` exports `createPgPool(pool, parsers?)`, which shapes a node-postgres `pg.Pool` as the `PgPool` the Postgres adapter and cache take, with a `transaction` that checks one client out of the pool and runs `BEGIN`/`COMMIT` (`ROLLBACK` when the callback throws) on it — what the cache's `init()`, batch mutations and per-read statement timeouts need. It also exports `RAW_DATE_PARSERS`, the same constant as `@niscorp/vex/pglite`'s. `pg` is now listed as an optional peer.
|
|
23
|
+
|
|
3
24
|
## 0.4.1
|
|
4
25
|
|
|
5
26
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -691,7 +691,9 @@ src/
|
|
|
691
691
|
compile.ts ResolvedQuery → parameterized SQL
|
|
692
692
|
operators.ts per-operator SQL generation
|
|
693
693
|
statement-timeout.ts how a read's time limit is enforced
|
|
694
|
+
date-parsers.ts RAW_DATE_PARSERS, shared by the two pool shims
|
|
694
695
|
pglite/index.ts createPglitePool (@niscorp/vex/pglite)
|
|
696
|
+
pg/index.ts createPgPool (@niscorp/vex/pg)
|
|
695
697
|
hono/index.ts vex() Hono app (@niscorp/vex/hono)
|
|
696
698
|
express/index.ts vex() Express handler (@niscorp/vex/express)
|
|
697
699
|
index.ts adapter barrel
|
|
@@ -733,7 +735,7 @@ scripts/ Dev-only: docker, seed, dev server, fixtures
|
|
|
733
735
|
| Package | Relationship | Purpose |
|
|
734
736
|
|---------|--------------|---------|
|
|
735
737
|
| `zod` | peer (required) | Schema validation + JSON Schema generation |
|
|
736
|
-
| `pg` | peer (optional) | Postgres adapter and
|
|
738
|
+
| `pg` | peer (optional) | A Postgres pool for the adapter and the cache; `@niscorp/vex/pg` imports it |
|
|
737
739
|
| `hono` | peer (optional) | Hono framework adapter |
|
|
738
740
|
| `express` | peer (optional) | Express framework adapter |
|
|
739
741
|
| `@niscorp/cortex` | peer (optional) | Reference query agent (`defineAgent`/`defineTool`, standalone runtime) |
|
package/DOCS.md
CHANGED
|
@@ -185,7 +185,10 @@ type QueryEngineConfig = {
|
|
|
185
185
|
set up at `introspect()`. A database that cannot enforce it (PGlite) runs
|
|
186
186
|
reads unbounded and the engine warns each time `introspect()` runs. A `PgPool`
|
|
187
187
|
declares such a database with `statementTimeouts: false`, as the pool from
|
|
188
|
-
`createPglitePool` does.
|
|
188
|
+
`createPglitePool` does. When the server's own `statement_timeout` is not
|
|
189
|
+
already within the limit, a pool with `transaction` (`createPgPool`'s) runs
|
|
190
|
+
each read in a transaction that sets it first; a bare `pg.Pool` runs it
|
|
191
|
+
unbounded.
|
|
189
192
|
- `config.maxPresenceVariants` is not a limit on what runs: past it, a response
|
|
190
193
|
carries a warning that the entry has compiled that many distinct
|
|
191
194
|
optional-key combinations.
|
|
@@ -924,11 +927,9 @@ Two guarantees, both enforced before any SQL runs:
|
|
|
924
927
|
unique column sets in the message — never a runtime surprise.
|
|
925
928
|
- **DO UPDATE is an update and is governed like one.** Declaring `set`
|
|
926
929
|
requires the update (or `write` umbrella) phase — an insert-only grant
|
|
927
|
-
refuses it. Update-phase `set` rules stamp identity into the DO UPDATE SET
|
|
928
|
-
`match`
|
|
929
|
-
|
|
930
|
-
for a conflict to arise), and any other `match` compiles to a WHERE on the
|
|
931
|
-
DO UPDATE half — the RLS boundary, again. `mutationEffect` declares the
|
|
930
|
+
refuses it. Update-phase `set` rules stamp identity into the DO UPDATE SET,
|
|
931
|
+
and every update-phase `match` compiles to a WHERE on the DO UPDATE half —
|
|
932
|
+
the RLS boundary, again. `mutationEffect` declares the
|
|
932
933
|
entry as the insert-plus-update it really is, so discovery visibility
|
|
933
934
|
follows the same rule.
|
|
934
935
|
|
|
@@ -1021,11 +1022,15 @@ Two things to know when using it:
|
|
|
1021
1022
|
### `insertEach` — one statement for a caller-sized list
|
|
1022
1023
|
|
|
1023
1024
|
`items` names a context key holding an array of objects; `{ $item: "key" }`
|
|
1024
|
-
values read from the current element
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1025
|
+
values read from the current element; every other value — literal,
|
|
1026
|
+
`$context`, `$lookup`, `$returned`, engine-injected `$scope` — is constant
|
|
1027
|
+
across rows. vex binds each element under the column names its `$item`s fill
|
|
1028
|
+
(a key no `$item` names is dropped) and compiles to a single
|
|
1029
|
+
`INSERT … SELECT … FROM jsonb_to_recordset($items) AS item(<column> <type>, …)`,
|
|
1030
|
+
each type the column's own from the introspected schema. Postgres converts
|
|
1031
|
+
every item as it converts an `insert`'s value, a column the statement does not
|
|
1032
|
+
write takes its default, and "one row per ticked weekday" is one authored
|
|
1033
|
+
statement, not a code loop:
|
|
1029
1034
|
|
|
1030
1035
|
```ts
|
|
1031
1036
|
{ op: 'insertEach', table: 'class_templates', items: { $context: 'slots' },
|
|
@@ -1039,6 +1044,10 @@ and `set`/`match` rules pin their columns identically on every row. A
|
|
|
1039
1044
|
non-array `items` value is refused loudly before any SQL runs; an empty array
|
|
1040
1045
|
inserts nothing and returns no rows.
|
|
1041
1046
|
|
|
1047
|
+
An array column's item is a JSON array, a `jsonb` column's any JSON value, and
|
|
1048
|
+
a pgvector `vector` column's a JSON array of numbers (`[0.1, 0.2]`) or the
|
|
1049
|
+
pgvector text form (`"[0.1,0.2]"`).
|
|
1050
|
+
|
|
1042
1051
|
### Replay
|
|
1043
1052
|
|
|
1044
1053
|
The handler dispatches by the entry's kind — one wire shape:
|
|
@@ -1219,10 +1228,21 @@ const l2 = createPostgresCache({
|
|
|
1219
1228
|
await l2.init(); // applies l2.sequence through strata's ledger — once, recorded
|
|
1220
1229
|
```
|
|
1221
1230
|
|
|
1222
|
-
`init()` runs a strata migration, so the pool must expose `transaction
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1231
|
+
`init()` runs a strata migration, so the pool must expose `transaction`. A bare
|
|
1232
|
+
`pg.Pool` does not; `createPgPool` from `@niscorp/vex/pg` gives it one that
|
|
1233
|
+
checks one client out per transaction (the PGlite pool has one too):
|
|
1234
|
+
|
|
1235
|
+
```typescript
|
|
1236
|
+
import pg from 'pg';
|
|
1237
|
+
import { createPgPool } from '@niscorp/vex/pg';
|
|
1238
|
+
|
|
1239
|
+
const pool = createPgPool(new pg.Pool({ connectionString: process.env.DATABASE_URL }));
|
|
1240
|
+
const l2 = createPostgresCache({ pool });
|
|
1241
|
+
await l2.init();
|
|
1242
|
+
```
|
|
1243
|
+
|
|
1244
|
+
A host that migrates several owners in one run collects `l2.sequence`
|
|
1245
|
+
(`nisc.vex.cache`) instead of calling `init()`.
|
|
1226
1246
|
|
|
1227
1247
|
**Tiered** — L1 (memory) + L2 (durable), read-through/write-through. Reads hit
|
|
1228
1248
|
L1; on an L1 miss it promotes a validated L2 entry into L1. Writes go to L1
|
|
@@ -1315,10 +1335,22 @@ await seedCache(engine.cache, [ordersRecent, taskSetDone]);
|
|
|
1315
1335
|
|
|
1316
1336
|
`@niscorp/vex/pglite` exports `createPglitePool(db, parsers?)`, which shapes a
|
|
1317
1337
|
PGlite database as the `PgPool` the Postgres adapter and cache take (with
|
|
1318
|
-
`transaction`)
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
`
|
|
1338
|
+
`transaction`). `@niscorp/vex/pg` exports `createPgPool(pool, parsers?)`, the
|
|
1339
|
+
same for a node-postgres `pg.Pool`: its `transaction` checks one client out of
|
|
1340
|
+
the pool, runs `BEGIN`, the callback and `COMMIT` on it (`ROLLBACK` and rethrow
|
|
1341
|
+
when the callback throws), and releases it. Both export `RAW_DATE_PARSERS`,
|
|
1342
|
+
which returns `DATE`/`TIMESTAMPTZ` columns as raw strings. Pass the parsers to
|
|
1343
|
+
the adapter's pool; give the Postgres cache a pool without them — it reads its
|
|
1344
|
+
own timestamp columns as `Date`s:
|
|
1345
|
+
|
|
1346
|
+
```typescript
|
|
1347
|
+
import pg from 'pg';
|
|
1348
|
+
import { createPgPool, RAW_DATE_PARSERS } from '@niscorp/vex/pg';
|
|
1349
|
+
|
|
1350
|
+
const db = new pg.Pool({ connectionString: process.env.DATABASE_URL });
|
|
1351
|
+
const adapter = createPostgresAdapter({ pool: createPgPool(db, RAW_DATE_PARSERS) });
|
|
1352
|
+
const cache = createPostgresCache({ pool: createPgPool(db) });
|
|
1353
|
+
```
|
|
1322
1354
|
|
|
1323
1355
|
`@niscorp/vex` and `@niscorp/vex/pglite` import no Node built-in, so a bundler
|
|
1324
1356
|
builds them for a page with no alias and no polyfill. Vex's hashes are the same
|
package/README.md
CHANGED
|
@@ -87,14 +87,14 @@ engine.cache; // CacheBackend — the live cache
|
|
|
87
87
|
|
|
88
88
|
| Area | Provided |
|
|
89
89
|
|------|----------|
|
|
90
|
-
| Database adapters | PostgreSQL (`createPostgresAdapter`) — pluggable `DatabaseAdapter` interface for others. `createPglitePool` (`@niscorp/vex/pglite`) shapes a PGlite database as the pool it takes |
|
|
90
|
+
| Database adapters | PostgreSQL (`createPostgresAdapter`) — pluggable `DatabaseAdapter` interface for others. `createPglitePool` (`@niscorp/vex/pglite`) shapes a PGlite database as the pool it takes, `createPgPool` (`@niscorp/vex/pg`) a node-postgres `pg.Pool` |
|
|
91
91
|
| Cache backends | In-memory, Postgres (durable), tiered L1/L2 with warm-up |
|
|
92
92
|
| Framework adapters | Hono (`@niscorp/vex/hono`), Express (`@niscorp/vex/express`) — discovery + query endpoints |
|
|
93
93
|
| LLM integration | `generateDsl` / `mapToShape` hooks; reference agents built on `@niscorp/cortex` (`@niscorp/vex/agent`: `createQueryDsl`, `createShapeMapper`) |
|
|
94
94
|
| Writes | Mutation entries in the same cache — a closed grammar, replay-only by fingerprint, never generated; `lintMutation` checks a statement at seed |
|
|
95
95
|
| Seeding and freshness | `seedCache` turns authored `SeedEntry` / `SeedMutation` rows into protected cache entries; an entry's `refresh` is `'snapshot'` or `'reactive'` |
|
|
96
96
|
| Safety | Server-side scope policies, query analyzer (cartesian/nesting/index checks), parameterized SQL only |
|
|
97
|
-
| Its own table | The Postgres cache's table is a [strata](../strata/README.md) sequence (`cache.sequence`, `nisc.vex.cache`): `cache.init()` applies it through the ledger once, instead of `IF NOT EXISTS` on every boot. Requires a pool with `transaction` (the PGlite pool
|
|
97
|
+
| Its own table | The Postgres cache's table is a [strata](../strata/README.md) sequence (`cache.sequence`, `nisc.vex.cache`): `cache.init()` applies it through the ledger once, instead of `IF NOT EXISTS` on every boot. Requires a pool with `transaction` (the PGlite pool and `createPgPool`'s have one; a bare `pg.Pool` does not). |
|
|
98
98
|
|
|
99
99
|
## License
|
|
100
100
|
|
|
@@ -1017,7 +1017,7 @@ var scopeInsertParts = (table, rawValues, rawConflict, policy) => {
|
|
|
1017
1017
|
for (const r of [...gate.rule.write ?? [], ...gate.rule.update ?? []]) {
|
|
1018
1018
|
if ("set" in r) {
|
|
1019
1019
|
conflict = { ...conflict, set: { ...conflict.set ?? {}, [r.set]: { $scope: r.to } } };
|
|
1020
|
-
} else
|
|
1020
|
+
} else {
|
|
1021
1021
|
const boundary = boundaryOf(table, r);
|
|
1022
1022
|
conflict = { ...conflict, where: conflict.where === void 0 ? boundary : { and: [conflict.where, boundary] } };
|
|
1023
1023
|
}
|
|
@@ -1055,6 +1055,10 @@ var scopeMutation = (m, policy) => {
|
|
|
1055
1055
|
}
|
|
1056
1056
|
return { op: "delete", table: m.table, where };
|
|
1057
1057
|
};
|
|
1058
|
+
var itemRow = (element, itemKeys) => {
|
|
1059
|
+
const fields = element !== null && typeof element === "object" && !Array.isArray(element) ? element : {};
|
|
1060
|
+
return Object.fromEntries(Object.entries(itemKeys).map(([column, key]) => [column, fields[key]]));
|
|
1061
|
+
};
|
|
1058
1062
|
var newCtx = () => ({
|
|
1059
1063
|
resolvedPaths: /* @__PURE__ */ new Map(),
|
|
1060
1064
|
aliasMap: /* @__PURE__ */ new Map(),
|
|
@@ -1101,13 +1105,6 @@ var compileConflict = (m, ctx, schema) => {
|
|
|
1101
1105
|
}
|
|
1102
1106
|
return ` ON CONFLICT (${c.target.join(", ")}) DO UPDATE SET ${sets.join(", ")}${where}`;
|
|
1103
1107
|
};
|
|
1104
|
-
var ITEM_CAST = {
|
|
1105
|
-
number: "numeric",
|
|
1106
|
-
boolean: "boolean",
|
|
1107
|
-
date: "date",
|
|
1108
|
-
timestamp: "timestamptz",
|
|
1109
|
-
uuid: "uuid"
|
|
1110
|
-
};
|
|
1111
1108
|
var compileMutation = (m, schema) => {
|
|
1112
1109
|
const ctx = newCtx();
|
|
1113
1110
|
if (m.op === "insert") {
|
|
@@ -1117,26 +1114,28 @@ var compileMutation = (m, schema) => {
|
|
|
1117
1114
|
return { sql: `INSERT INTO ${m.table} (${cols.join(", ")}) VALUES (${vals.join(", ")})${compileConflict(m, ctx, schema)} RETURNING *`, slots: ctx.paramSlots, returned: ctx.returned };
|
|
1118
1115
|
}
|
|
1119
1116
|
if (m.op === "insertEach") {
|
|
1120
|
-
const
|
|
1117
|
+
const types = new Map(findEntity(m.table, schema)?.fields.map((f) => [f.name, f.type]));
|
|
1121
1118
|
const entries = Object.entries(m.values);
|
|
1122
1119
|
const cols = entries.map(([c]) => c);
|
|
1120
|
+
const itemKeys = {};
|
|
1121
|
+
const itemColumns = [];
|
|
1123
1122
|
const exprs = entries.map(([col, v]) => {
|
|
1124
1123
|
if (isItemRef(v)) {
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
const raw = `(item.value->>${quoteLiteral(v.$item)})`;
|
|
1129
|
-
return cast === void 0 ? raw : `${raw}::${cast}`;
|
|
1124
|
+
itemKeys[col] = v.$item;
|
|
1125
|
+
itemColumns.push(`${col} ${String(types.get(col))}`);
|
|
1126
|
+
return `item.${col}`;
|
|
1130
1127
|
}
|
|
1131
1128
|
return isReturned(v) ? compileColumnValue(m.table, col, v, ctx, schema) : compileValue(v, ctx);
|
|
1132
1129
|
});
|
|
1133
1130
|
ctx.paramCounter.value += 1;
|
|
1134
1131
|
ctx.paramSlots.push({ key: m.items.$context, kind: "context", type: "json" });
|
|
1135
|
-
const
|
|
1132
|
+
const items = `$${ctx.paramCounter.value}::jsonb`;
|
|
1133
|
+
const source = itemColumns.length === 0 ? `jsonb_array_elements(${items}) AS item` : `jsonb_to_recordset(${items}) AS item(${itemColumns.join(", ")})`;
|
|
1136
1134
|
return {
|
|
1137
1135
|
sql: `INSERT INTO ${m.table} (${cols.join(", ")}) SELECT ${exprs.join(", ")} FROM ${source}${compileConflict(m, ctx, schema)} RETURNING *`,
|
|
1138
1136
|
slots: ctx.paramSlots,
|
|
1139
|
-
returned: ctx.returned
|
|
1137
|
+
returned: ctx.returned,
|
|
1138
|
+
itemKeys
|
|
1140
1139
|
};
|
|
1141
1140
|
}
|
|
1142
1141
|
if (m.op === "update") {
|
|
@@ -1209,7 +1208,8 @@ var executeWrites = async (client, def, mctx) => {
|
|
|
1209
1208
|
if (!Array.isArray(value)) {
|
|
1210
1209
|
throw new VexError("invalid_request", `"${c.slots[i]?.key ?? ""}" must be an array of objects (one inserted row per element).`);
|
|
1211
1210
|
}
|
|
1212
|
-
|
|
1211
|
+
const { itemKeys } = c;
|
|
1212
|
+
return JSON.stringify(itemKeys === void 0 ? value : value.map((element) => itemRow(element, itemKeys)));
|
|
1213
1213
|
});
|
|
1214
1214
|
const res = await q.query(c.sql, bound);
|
|
1215
1215
|
results.push({ table: c.table, op: c.op, rows: res.rows });
|