@niscorp/vex 0.4.1 → 0.4.2
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 +10 -0
- package/DESIGN.md +3 -1
- package/DOCS.md +38 -14
- package/README.md +2 -2
- package/dist/adapters/express/index.cjs +1 -1
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.js +1 -1
- package/dist/adapters/hono/index.cjs +1 -1
- 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-RGJRUOGQ.js} +3 -3
- package/dist/chunk-RGJRUOGQ.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 +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +2 -2
- package/package.json +12 -1
- package/dist/chunk-AKR6HU34.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# @niscorp/vex
|
|
2
2
|
|
|
3
|
+
## 0.4.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 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.
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
|
|
11
|
+
- 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.
|
|
12
|
+
|
|
3
13
|
## 0.4.1
|
|
4
14
|
|
|
5
15
|
### 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
|
|
|
@@ -1219,10 +1220,21 @@ const l2 = createPostgresCache({
|
|
|
1219
1220
|
await l2.init(); // applies l2.sequence through strata's ledger — once, recorded
|
|
1220
1221
|
```
|
|
1221
1222
|
|
|
1222
|
-
`init()` runs a strata migration, so the pool must expose `transaction
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1223
|
+
`init()` runs a strata migration, so the pool must expose `transaction`. A bare
|
|
1224
|
+
`pg.Pool` does not; `createPgPool` from `@niscorp/vex/pg` gives it one that
|
|
1225
|
+
checks one client out per transaction (the PGlite pool has one too):
|
|
1226
|
+
|
|
1227
|
+
```typescript
|
|
1228
|
+
import pg from 'pg';
|
|
1229
|
+
import { createPgPool } from '@niscorp/vex/pg';
|
|
1230
|
+
|
|
1231
|
+
const pool = createPgPool(new pg.Pool({ connectionString: process.env.DATABASE_URL }));
|
|
1232
|
+
const l2 = createPostgresCache({ pool });
|
|
1233
|
+
await l2.init();
|
|
1234
|
+
```
|
|
1235
|
+
|
|
1236
|
+
A host that migrates several owners in one run collects `l2.sequence`
|
|
1237
|
+
(`nisc.vex.cache`) instead of calling `init()`.
|
|
1226
1238
|
|
|
1227
1239
|
**Tiered** — L1 (memory) + L2 (durable), read-through/write-through. Reads hit
|
|
1228
1240
|
L1; on an L1 miss it promotes a validated L2 entry into L1. Writes go to L1
|
|
@@ -1315,10 +1327,22 @@ await seedCache(engine.cache, [ordersRecent, taskSetDone]);
|
|
|
1315
1327
|
|
|
1316
1328
|
`@niscorp/vex/pglite` exports `createPglitePool(db, parsers?)`, which shapes a
|
|
1317
1329
|
PGlite database as the `PgPool` the Postgres adapter and cache take (with
|
|
1318
|
-
`transaction`)
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
`
|
|
1330
|
+
`transaction`). `@niscorp/vex/pg` exports `createPgPool(pool, parsers?)`, the
|
|
1331
|
+
same for a node-postgres `pg.Pool`: its `transaction` checks one client out of
|
|
1332
|
+
the pool, runs `BEGIN`, the callback and `COMMIT` on it (`ROLLBACK` and rethrow
|
|
1333
|
+
when the callback throws), and releases it. Both export `RAW_DATE_PARSERS`,
|
|
1334
|
+
which returns `DATE`/`TIMESTAMPTZ` columns as raw strings. Pass the parsers to
|
|
1335
|
+
the adapter's pool; give the Postgres cache a pool without them — it reads its
|
|
1336
|
+
own timestamp columns as `Date`s:
|
|
1337
|
+
|
|
1338
|
+
```typescript
|
|
1339
|
+
import pg from 'pg';
|
|
1340
|
+
import { createPgPool, RAW_DATE_PARSERS } from '@niscorp/vex/pg';
|
|
1341
|
+
|
|
1342
|
+
const db = new pg.Pool({ connectionString: process.env.DATABASE_URL });
|
|
1343
|
+
const adapter = createPostgresAdapter({ pool: createPgPool(db, RAW_DATE_PARSERS) });
|
|
1344
|
+
const cache = createPostgresCache({ pool: createPgPool(db) });
|
|
1345
|
+
```
|
|
1322
1346
|
|
|
1323
1347
|
`@niscorp/vex` and `@niscorp/vex/pglite` import no Node built-in, so a bundler
|
|
1324
1348
|
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
|
}
|