@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 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 Postgres cache backend |
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` rules whose column the conflict target already pins are inherently
929
- satisfied (the inserted, scope-pinned value must equal the existing row's
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` — the
1223
- PGlite pool has one; a bare `pg.Pool` needs a wrapper that checks a client out
1224
- per transaction (see `PgPool`). A host that migrates several owners in one run
1225
- collects `l2.sequence` (`nisc.vex.cache`) instead of calling `init()`.
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`), and `RAW_DATE_PARSERS`, which returns `DATE`/`TIMESTAMPTZ`
1319
- columns as raw strings. Pass the parsers to the adapter's pool; give the
1320
- Postgres cache a pool without them — it reads its own timestamp columns as
1321
- `Date`s.
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 has one). |
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 if (!conflict.target.includes(r.match)) {
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
  }