@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 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 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
 
@@ -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 (cast to the column's type from the
1025
- schema); every other value — literal, `$context`, `$lookup`, `$returned`,
1026
- engine-injected `$scope` — is constant across rows. Compiles to a single
1027
- `INSERT … SELECT … FROM jsonb_array_elements($items)`, so "one row per ticked
1028
- weekday" is one authored statement, not a code loop:
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` — 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()`.
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`), 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.
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 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
  }
@@ -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 entity = findEntity(m.table, schema);
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
- const nt = entity?.fields.find((f) => f.name === col)?.normalizedType ?? "string";
1126
- if (nt === "json") return `(item.value->${quoteLiteral(v.$item)})`;
1127
- const cast = ITEM_CAST[nt];
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 source = `jsonb_array_elements($${ctx.paramCounter.value}::jsonb) AS item`;
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
- return JSON.stringify(value);
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 });