@niscorp/vex 0.3.0 → 0.3.1
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 +28 -0
- package/DESIGN.md +26 -11
- package/DOCS.md +39 -9
- package/dist/adapters/express/index.cjs +6 -24
- package/dist/adapters/express/index.cjs.map +1 -1
- package/dist/adapters/express/index.d.cts +2 -2
- package/dist/adapters/express/index.d.ts +2 -2
- package/dist/adapters/express/index.js +2 -2
- package/dist/adapters/express/index.js.map +1 -1
- package/dist/adapters/hono/index.cjs +6 -24
- package/dist/adapters/hono/index.cjs.map +1 -1
- package/dist/adapters/hono/index.d.cts +2 -2
- package/dist/adapters/hono/index.d.ts +2 -2
- package/dist/adapters/hono/index.js +2 -2
- package/dist/adapters/hono/index.js.map +1 -1
- package/dist/adapters/pglite/index.cjs.map +1 -1
- package/dist/adapters/pglite/index.js.map +1 -1
- package/dist/agent/index.cjs +5 -11
- package/dist/agent/index.cjs.map +1 -1
- package/dist/agent/index.d.cts +1 -1
- package/dist/agent/index.d.ts +1 -1
- package/dist/agent/index.js +3 -6
- package/dist/agent/index.js.map +1 -1
- package/dist/{chunk-IQM4SQE2.js → chunk-3HORTMZ7.js} +6 -21
- package/dist/chunk-3HORTMZ7.js.map +1 -0
- package/dist/{chunk-H4BHW76Q.js → chunk-J7JYKCUA.js} +5 -8
- package/dist/chunk-J7JYKCUA.js.map +1 -0
- package/dist/{handler-CMrjTXNx.d.cts → handler-B4NAi4k_.d.cts} +1 -1
- package/dist/{handler-BGCL6_Si.d.ts → handler-BRVhWuNk.d.ts} +1 -1
- package/dist/index.cjs +23 -79
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +14 -62
- package/dist/index.d.ts +14 -62
- package/dist/index.js +21 -59
- package/dist/index.js.map +1 -1
- package/dist/{types-Bi-Lg86b.d.cts → types-DUJp5B3o.d.cts} +9 -124
- package/dist/{types-Bi-Lg86b.d.ts → types-DUJp5B3o.d.ts} +9 -124
- package/package.json +7 -7
- package/dist/chunk-H4BHW76Q.js.map +0 -1
- package/dist/chunk-IQM4SQE2.js.map +0 -1
|
@@ -864,36 +864,11 @@ type Refresh = (typeof REFRESH_MODES)[number];
|
|
|
864
864
|
declare const isRefresh: (value: unknown) => value is Refresh;
|
|
865
865
|
type CacheEntryMeta = {
|
|
866
866
|
createdAt: number;
|
|
867
|
-
/**
|
|
868
|
-
* Touch-on-read timestamp. Lifetime is usage: a GC sweep evicts
|
|
869
|
-
* entries unused for a configured window; protected entries never
|
|
870
|
-
* sweep. Replaces the provisional/permanent distinction entirely.
|
|
871
|
-
*/
|
|
872
867
|
lastUsedAt?: number;
|
|
873
868
|
expiresAt?: number;
|
|
874
|
-
/**
|
|
875
|
-
* Protected entries refuse replacement: a fingerprint request whose
|
|
876
|
-
* intent/shape differ from the stored ones errors instead of
|
|
877
|
-
* regenerating. Written ONLY by the seed path and an explicit PATCH —
|
|
878
|
-
* never by query execution.
|
|
879
|
-
*/
|
|
880
869
|
protected?: boolean;
|
|
881
|
-
/**
|
|
882
|
-
* Identity of the request that produced this entry (intent + normalized
|
|
883
|
-
* shape + context key names). A fingerprint request with a matching
|
|
884
|
-
* hash is a hit; a differing one regenerates (or 409s when protected).
|
|
885
|
-
*/
|
|
886
870
|
requestHash?: string;
|
|
887
|
-
/**
|
|
888
|
-
* Fingerprint of the database schema at write time. When it no longer
|
|
889
|
-
* matches the current schema, the entry is stale (its DSL may
|
|
890
|
-
* reference columns that have since changed) and is treated as a miss.
|
|
891
|
-
*/
|
|
892
871
|
schemaFingerprint?: string;
|
|
893
|
-
/**
|
|
894
|
-
* The originating request's intent and shape — descriptive metadata
|
|
895
|
-
* for inspection and the GET overview. Never part of identity.
|
|
896
|
-
*/
|
|
897
872
|
intent?: string;
|
|
898
873
|
shape?: unknown;
|
|
899
874
|
};
|
|
@@ -902,24 +877,11 @@ type OkCacheEntry = CacheEntryMeta & {
|
|
|
902
877
|
dsl: Query;
|
|
903
878
|
prismIr?: CompiledIr;
|
|
904
879
|
/**
|
|
905
|
-
*
|
|
906
|
-
*
|
|
907
|
-
*
|
|
908
|
-
* to every table they touch. That is right for a read whose answer legitimately
|
|
909
|
-
* widens with the reader — a roster, a schedule, a members list.
|
|
910
|
-
*
|
|
911
|
-
* It is wrong for a read that means "mine". A principal may hold several roles
|
|
912
|
-
* and the compiled policies merge to the WIDEST reach any of them grants, so an
|
|
913
|
-
* instructor who also trains at the studio reads `bookings` studio-wide — and
|
|
914
|
-
* "the classes you have booked" then answers with the whole studio's.
|
|
915
|
-
*
|
|
916
|
-
* An entry naming a reach is served at that profile instead, with the caller's
|
|
917
|
-
* own grants unchanged. It can only narrow: a read the caller holds no verb for
|
|
918
|
-
* is still refused. If the profile cannot be compiled, the read is refused
|
|
919
|
-
* rather than served wide.
|
|
880
|
+
* The scope profile this read is served at, whatever the caller's roles say:
|
|
881
|
+
* roles merge to the widest reach any of them grants, which is wrong for a
|
|
882
|
+
* read that means "mine". A reach the host cannot compile refuses the read.
|
|
920
883
|
*/
|
|
921
884
|
reach?: string;
|
|
922
|
-
/** When this read's answer is refreshed. Absent means 'snapshot'. */
|
|
923
885
|
refresh?: Refresh;
|
|
924
886
|
};
|
|
925
887
|
type UnsatisfiableCacheEntry = CacheEntryMeta & {
|
|
@@ -929,20 +891,6 @@ type UnsatisfiableCacheEntry = CacheEntryMeta & {
|
|
|
929
891
|
type MutationCacheEntry = CacheEntryMeta & {
|
|
930
892
|
kind: 'mutation';
|
|
931
893
|
mutation: MutationDefinition;
|
|
932
|
-
/**
|
|
933
|
-
* THE REACH THIS WRITE REQUIRES — the same word reads use, and it belongs
|
|
934
|
-
* here for a sharper reason.
|
|
935
|
-
*
|
|
936
|
-
* A read served too wide shows somebody too much. A write served too wide
|
|
937
|
-
* CHANGES somebody else's row: `me/cancel` is "cancel MY booking", and its
|
|
938
|
-
* whole safety is that the policy's update rules pin the row to the caller.
|
|
939
|
-
* Take a principal who holds two roles and the merge widens those rules to
|
|
940
|
-
* the broadest either grants — so the same fingerprint, replayed by somebody
|
|
941
|
-
* who is a member AND something else, could reach a booking that is not
|
|
942
|
-
* theirs.
|
|
943
|
-
*
|
|
944
|
-
* Declaring it here means the write is compiled at that profile whoever asks.
|
|
945
|
-
*/
|
|
946
894
|
reach?: string;
|
|
947
895
|
};
|
|
948
896
|
type CacheEntry = OkCacheEntry | UnsatisfiableCacheEntry | MutationCacheEntry;
|
|
@@ -1364,15 +1312,11 @@ type VexEvent = {
|
|
|
1364
1312
|
type VexEventHandler = (event: VexEvent) => void;
|
|
1365
1313
|
|
|
1366
1314
|
type LiveRowsConfig = {
|
|
1367
|
-
/** How long stored rows are trusted, and how often a followed read is re-checked when nothing wrote. Default 60 000. */
|
|
1368
1315
|
ttlMs?: number;
|
|
1369
|
-
/** Most stored results. Default 5 000. */
|
|
1370
1316
|
maxEntries?: number;
|
|
1371
|
-
/**
|
|
1317
|
+
/** Measured as the length of each result's JSON. */
|
|
1372
1318
|
maxBytes?: number;
|
|
1373
|
-
/** Largest single result worth storing; bigger ones are refetched every time. Default a tenth of `maxBytes`. */
|
|
1374
1319
|
maxEntryBytes?: number;
|
|
1375
|
-
/** How long a burst of writes is gathered before followed reads refetch. Default 10. */
|
|
1376
1320
|
debounceMs?: number;
|
|
1377
1321
|
};
|
|
1378
1322
|
type LiveRowsStats = {
|
|
@@ -1398,91 +1342,44 @@ type ScopeRules = {
|
|
|
1398
1342
|
};
|
|
1399
1343
|
type NamedScopeBehaviors = Record<string, ScopeRules>;
|
|
1400
1344
|
type ScopeBehaviors = Record<string, ScopeRules | NamedScopeBehaviors>;
|
|
1401
|
-
/**
|
|
1402
|
-
* The columns the behaviors bind to scope keys, on the given tables, for the
|
|
1403
|
-
* keys present in `scope` — sorted, one per (table, column, key).
|
|
1404
|
-
*/
|
|
1405
1345
|
declare const scopeBindings: (behaviors: ScopeBehaviors, tables: readonly string[], scope: ScopeValues) => ScopeBinding[];
|
|
1406
|
-
/** Every profile name any table declares. A profile nobody declares is a typo. */
|
|
1407
1346
|
declare const scopeProfiles: (behaviors: ScopeBehaviors) => ReadonlySet<string>;
|
|
1408
1347
|
declare const createScopePolicy: (grants: ReadonlySet<string>, behaviors?: ScopeBehaviors, scoping?: string) => ScopePolicy;
|
|
1409
|
-
/** The union of several compiled policies: anything any of them permits. */
|
|
1410
1348
|
declare const mergeScopePolicies: (policies: readonly ScopePolicy[]) => ScopePolicy;
|
|
1411
1349
|
|
|
1412
|
-
/**
|
|
1413
|
-
* Who a generation is for, as a capability rather than an identity. `read` runs
|
|
1414
|
-
* a DSL through the engine's own pipeline under the caller's policy and scope
|
|
1415
|
-
* values — `$context` slots bind NULL, because a probe asks whether a query
|
|
1416
|
-
* runs, not what it answers. It is the only door a generator has to the
|
|
1417
|
-
* database: it sees what the person asking would see, and nothing else.
|
|
1418
|
-
*/
|
|
1419
1350
|
type GenerationCaller = {
|
|
1420
1351
|
read: (dsl: Query) => Promise<{
|
|
1421
1352
|
rows: Row[];
|
|
1422
1353
|
sql: string;
|
|
1423
1354
|
warnings: string[];
|
|
1424
1355
|
}>;
|
|
1425
|
-
/**
|
|
1426
|
-
* WHO "ME" IS, as columns: every column the host's behaviors bind to a scope
|
|
1427
|
-
* key this caller actually carries, on a table they may read — the keys and
|
|
1428
|
-
* the columns, never the values. A generator uses them to say "the caller"
|
|
1429
|
-
* or "theirs": filter the column with `{ $scope: key }`, and the engine binds
|
|
1430
|
-
* the caller's own value. Empty when nothing identifies the caller (no
|
|
1431
|
-
* behaviors given, or a caller carrying none of the keys they bind).
|
|
1432
|
-
*/
|
|
1433
1356
|
bindings: ScopeBinding[];
|
|
1434
1357
|
};
|
|
1435
|
-
/** One column a scope key is bound to by the host's behaviors. */
|
|
1436
1358
|
type ScopeBinding = {
|
|
1437
1359
|
entity: string;
|
|
1438
1360
|
field: string;
|
|
1439
1361
|
key: string;
|
|
1440
1362
|
};
|
|
1441
|
-
/**
|
|
1442
|
-
* DSL generation from intent + shape. Wire to a Cortex agent (see agent/).
|
|
1443
|
-
* `schema` holds only the tables the caller's policy lets them read.
|
|
1444
|
-
*/
|
|
1445
1363
|
type GenerateDsl = (request: QueryRequest, schema: DatabaseSchema, caller: GenerationCaller) => Promise<Query>;
|
|
1446
|
-
/**
|
|
1447
|
-
* Result mapping from the raw row set to the requested shape. The mapping runs
|
|
1448
|
-
* ONCE over `{ result }` — the rows for an array shape, the single (first) row
|
|
1449
|
-
* for an object shape — so `transformed` is whatever it produced: an array, a
|
|
1450
|
-
* single object, or a scalar. Wire to Prism's mapping agent.
|
|
1451
|
-
*/
|
|
1364
|
+
/** The IR is replayed against an envelope whose `result` is the rows for an array shape, the first row for any other. */
|
|
1452
1365
|
type MapToShape = (rows: Row[], shape: unknown) => Promise<{
|
|
1453
1366
|
ir: CompiledIr;
|
|
1454
1367
|
transformed: JsonValue;
|
|
1455
1368
|
}>;
|
|
1456
1369
|
type QueryEngineConfig = {
|
|
1457
1370
|
adapter: DatabaseAdapter;
|
|
1458
|
-
/**
|
|
1459
|
-
* Turns text into a vector at parameter-binding time, for `semantic`
|
|
1460
|
-
* filters. An injected provider (wire it to Signal), not a database
|
|
1461
|
-
* concern — the adapter only generates the vector-distance SQL.
|
|
1462
|
-
* Required only if the schema has vector columns you search over.
|
|
1463
|
-
*/
|
|
1464
1371
|
embed?: (text: string, dimensions?: number) => Promise<number[]>;
|
|
1465
1372
|
scope?: ScopePolicy;
|
|
1466
1373
|
cache?: CacheBackend;
|
|
1467
1374
|
onEvent?: VexEventHandler;
|
|
1468
|
-
/** Optional LLM-backed query generation (cache misses fail without it). */
|
|
1469
1375
|
generateDsl?: GenerateDsl;
|
|
1470
1376
|
/**
|
|
1471
|
-
*
|
|
1472
|
-
*
|
|
1473
|
-
*
|
|
1474
|
-
* schema's own terms (GenerationCaller.bindings). A compiled policy cannot
|
|
1475
|
-
* say it — it keeps only the phases a caller is granted, and the rule that
|
|
1476
|
-
* stamps a member's id lives on a write a reader does not hold. Checked at
|
|
1477
|
-
* `introspect`: every rule names a table and a column that exist.
|
|
1377
|
+
* Read for one thing: which columns a scope key is bound to, so a generation
|
|
1378
|
+
* can be told who its caller is (GenerationCaller.bindings). A compiled
|
|
1379
|
+
* policy cannot say it: it keeps only the phases a caller is granted.
|
|
1478
1380
|
*/
|
|
1479
1381
|
behaviors?: ScopeBehaviors;
|
|
1480
|
-
/** Optional LLM-backed result mapping (raw rows used as-is without it). */
|
|
1481
1382
|
mapToShape?: MapToShape;
|
|
1482
|
-
/**
|
|
1483
|
-
* The rows cache behind `refresh: 'reactive'` entries — its age, size and
|
|
1484
|
-
* burst window. Held in this process's memory; nothing else is cached.
|
|
1485
|
-
*/
|
|
1486
1383
|
rows?: LiveRowsConfig;
|
|
1487
1384
|
config?: {
|
|
1488
1385
|
maxNestingDepth?: number;
|
|
@@ -1506,14 +1403,7 @@ type QueryEngine = {
|
|
|
1506
1403
|
getDslSchema: () => object;
|
|
1507
1404
|
getSchema: () => DatabaseSchema | undefined;
|
|
1508
1405
|
cache: CacheBackend;
|
|
1509
|
-
/**
|
|
1510
|
-
* These tables were written. Every reactive read over any of them is
|
|
1511
|
-
* refetched (once per burst) and its followers told if their answer changed.
|
|
1512
|
-
* The vex handler calls this after every committed mutation; a host calls
|
|
1513
|
-
* it for writes vex did not make.
|
|
1514
|
-
*/
|
|
1515
1406
|
invalidate: (tables: readonly string[]) => void;
|
|
1516
|
-
/** The reactive rows cache: what it holds and how it is doing. */
|
|
1517
1407
|
rows: {
|
|
1518
1408
|
stats: () => LiveRowsStats;
|
|
1519
1409
|
stop: () => void;
|
|
@@ -1524,12 +1414,7 @@ type ExecuteOptions = {
|
|
|
1524
1414
|
entities?: string[];
|
|
1525
1415
|
locked?: boolean;
|
|
1526
1416
|
scopePolicy?: ScopePolicy;
|
|
1527
|
-
/**
|
|
1528
|
-
* FOLLOW THE ANSWER. For an entry with `refresh: 'reactive'`, every later
|
|
1529
|
-
* answer that differs from the last one is handed to `onChange` — after
|
|
1530
|
-
* writes to the tables the query reads — until `signal` aborts. Both or
|
|
1531
|
-
* neither; ignored for a snapshot read.
|
|
1532
|
-
*/
|
|
1417
|
+
/** `signal` and `onChange` go together; both are ignored for a snapshot read. */
|
|
1533
1418
|
signal?: AbortSignal;
|
|
1534
1419
|
onChange?: (response: QueryResponse) => void;
|
|
1535
1420
|
};
|
|
@@ -864,36 +864,11 @@ type Refresh = (typeof REFRESH_MODES)[number];
|
|
|
864
864
|
declare const isRefresh: (value: unknown) => value is Refresh;
|
|
865
865
|
type CacheEntryMeta = {
|
|
866
866
|
createdAt: number;
|
|
867
|
-
/**
|
|
868
|
-
* Touch-on-read timestamp. Lifetime is usage: a GC sweep evicts
|
|
869
|
-
* entries unused for a configured window; protected entries never
|
|
870
|
-
* sweep. Replaces the provisional/permanent distinction entirely.
|
|
871
|
-
*/
|
|
872
867
|
lastUsedAt?: number;
|
|
873
868
|
expiresAt?: number;
|
|
874
|
-
/**
|
|
875
|
-
* Protected entries refuse replacement: a fingerprint request whose
|
|
876
|
-
* intent/shape differ from the stored ones errors instead of
|
|
877
|
-
* regenerating. Written ONLY by the seed path and an explicit PATCH —
|
|
878
|
-
* never by query execution.
|
|
879
|
-
*/
|
|
880
869
|
protected?: boolean;
|
|
881
|
-
/**
|
|
882
|
-
* Identity of the request that produced this entry (intent + normalized
|
|
883
|
-
* shape + context key names). A fingerprint request with a matching
|
|
884
|
-
* hash is a hit; a differing one regenerates (or 409s when protected).
|
|
885
|
-
*/
|
|
886
870
|
requestHash?: string;
|
|
887
|
-
/**
|
|
888
|
-
* Fingerprint of the database schema at write time. When it no longer
|
|
889
|
-
* matches the current schema, the entry is stale (its DSL may
|
|
890
|
-
* reference columns that have since changed) and is treated as a miss.
|
|
891
|
-
*/
|
|
892
871
|
schemaFingerprint?: string;
|
|
893
|
-
/**
|
|
894
|
-
* The originating request's intent and shape — descriptive metadata
|
|
895
|
-
* for inspection and the GET overview. Never part of identity.
|
|
896
|
-
*/
|
|
897
872
|
intent?: string;
|
|
898
873
|
shape?: unknown;
|
|
899
874
|
};
|
|
@@ -902,24 +877,11 @@ type OkCacheEntry = CacheEntryMeta & {
|
|
|
902
877
|
dsl: Query;
|
|
903
878
|
prismIr?: CompiledIr;
|
|
904
879
|
/**
|
|
905
|
-
*
|
|
906
|
-
*
|
|
907
|
-
*
|
|
908
|
-
* to every table they touch. That is right for a read whose answer legitimately
|
|
909
|
-
* widens with the reader — a roster, a schedule, a members list.
|
|
910
|
-
*
|
|
911
|
-
* It is wrong for a read that means "mine". A principal may hold several roles
|
|
912
|
-
* and the compiled policies merge to the WIDEST reach any of them grants, so an
|
|
913
|
-
* instructor who also trains at the studio reads `bookings` studio-wide — and
|
|
914
|
-
* "the classes you have booked" then answers with the whole studio's.
|
|
915
|
-
*
|
|
916
|
-
* An entry naming a reach is served at that profile instead, with the caller's
|
|
917
|
-
* own grants unchanged. It can only narrow: a read the caller holds no verb for
|
|
918
|
-
* is still refused. If the profile cannot be compiled, the read is refused
|
|
919
|
-
* rather than served wide.
|
|
880
|
+
* The scope profile this read is served at, whatever the caller's roles say:
|
|
881
|
+
* roles merge to the widest reach any of them grants, which is wrong for a
|
|
882
|
+
* read that means "mine". A reach the host cannot compile refuses the read.
|
|
920
883
|
*/
|
|
921
884
|
reach?: string;
|
|
922
|
-
/** When this read's answer is refreshed. Absent means 'snapshot'. */
|
|
923
885
|
refresh?: Refresh;
|
|
924
886
|
};
|
|
925
887
|
type UnsatisfiableCacheEntry = CacheEntryMeta & {
|
|
@@ -929,20 +891,6 @@ type UnsatisfiableCacheEntry = CacheEntryMeta & {
|
|
|
929
891
|
type MutationCacheEntry = CacheEntryMeta & {
|
|
930
892
|
kind: 'mutation';
|
|
931
893
|
mutation: MutationDefinition;
|
|
932
|
-
/**
|
|
933
|
-
* THE REACH THIS WRITE REQUIRES — the same word reads use, and it belongs
|
|
934
|
-
* here for a sharper reason.
|
|
935
|
-
*
|
|
936
|
-
* A read served too wide shows somebody too much. A write served too wide
|
|
937
|
-
* CHANGES somebody else's row: `me/cancel` is "cancel MY booking", and its
|
|
938
|
-
* whole safety is that the policy's update rules pin the row to the caller.
|
|
939
|
-
* Take a principal who holds two roles and the merge widens those rules to
|
|
940
|
-
* the broadest either grants — so the same fingerprint, replayed by somebody
|
|
941
|
-
* who is a member AND something else, could reach a booking that is not
|
|
942
|
-
* theirs.
|
|
943
|
-
*
|
|
944
|
-
* Declaring it here means the write is compiled at that profile whoever asks.
|
|
945
|
-
*/
|
|
946
894
|
reach?: string;
|
|
947
895
|
};
|
|
948
896
|
type CacheEntry = OkCacheEntry | UnsatisfiableCacheEntry | MutationCacheEntry;
|
|
@@ -1364,15 +1312,11 @@ type VexEvent = {
|
|
|
1364
1312
|
type VexEventHandler = (event: VexEvent) => void;
|
|
1365
1313
|
|
|
1366
1314
|
type LiveRowsConfig = {
|
|
1367
|
-
/** How long stored rows are trusted, and how often a followed read is re-checked when nothing wrote. Default 60 000. */
|
|
1368
1315
|
ttlMs?: number;
|
|
1369
|
-
/** Most stored results. Default 5 000. */
|
|
1370
1316
|
maxEntries?: number;
|
|
1371
|
-
/**
|
|
1317
|
+
/** Measured as the length of each result's JSON. */
|
|
1372
1318
|
maxBytes?: number;
|
|
1373
|
-
/** Largest single result worth storing; bigger ones are refetched every time. Default a tenth of `maxBytes`. */
|
|
1374
1319
|
maxEntryBytes?: number;
|
|
1375
|
-
/** How long a burst of writes is gathered before followed reads refetch. Default 10. */
|
|
1376
1320
|
debounceMs?: number;
|
|
1377
1321
|
};
|
|
1378
1322
|
type LiveRowsStats = {
|
|
@@ -1398,91 +1342,44 @@ type ScopeRules = {
|
|
|
1398
1342
|
};
|
|
1399
1343
|
type NamedScopeBehaviors = Record<string, ScopeRules>;
|
|
1400
1344
|
type ScopeBehaviors = Record<string, ScopeRules | NamedScopeBehaviors>;
|
|
1401
|
-
/**
|
|
1402
|
-
* The columns the behaviors bind to scope keys, on the given tables, for the
|
|
1403
|
-
* keys present in `scope` — sorted, one per (table, column, key).
|
|
1404
|
-
*/
|
|
1405
1345
|
declare const scopeBindings: (behaviors: ScopeBehaviors, tables: readonly string[], scope: ScopeValues) => ScopeBinding[];
|
|
1406
|
-
/** Every profile name any table declares. A profile nobody declares is a typo. */
|
|
1407
1346
|
declare const scopeProfiles: (behaviors: ScopeBehaviors) => ReadonlySet<string>;
|
|
1408
1347
|
declare const createScopePolicy: (grants: ReadonlySet<string>, behaviors?: ScopeBehaviors, scoping?: string) => ScopePolicy;
|
|
1409
|
-
/** The union of several compiled policies: anything any of them permits. */
|
|
1410
1348
|
declare const mergeScopePolicies: (policies: readonly ScopePolicy[]) => ScopePolicy;
|
|
1411
1349
|
|
|
1412
|
-
/**
|
|
1413
|
-
* Who a generation is for, as a capability rather than an identity. `read` runs
|
|
1414
|
-
* a DSL through the engine's own pipeline under the caller's policy and scope
|
|
1415
|
-
* values — `$context` slots bind NULL, because a probe asks whether a query
|
|
1416
|
-
* runs, not what it answers. It is the only door a generator has to the
|
|
1417
|
-
* database: it sees what the person asking would see, and nothing else.
|
|
1418
|
-
*/
|
|
1419
1350
|
type GenerationCaller = {
|
|
1420
1351
|
read: (dsl: Query) => Promise<{
|
|
1421
1352
|
rows: Row[];
|
|
1422
1353
|
sql: string;
|
|
1423
1354
|
warnings: string[];
|
|
1424
1355
|
}>;
|
|
1425
|
-
/**
|
|
1426
|
-
* WHO "ME" IS, as columns: every column the host's behaviors bind to a scope
|
|
1427
|
-
* key this caller actually carries, on a table they may read — the keys and
|
|
1428
|
-
* the columns, never the values. A generator uses them to say "the caller"
|
|
1429
|
-
* or "theirs": filter the column with `{ $scope: key }`, and the engine binds
|
|
1430
|
-
* the caller's own value. Empty when nothing identifies the caller (no
|
|
1431
|
-
* behaviors given, or a caller carrying none of the keys they bind).
|
|
1432
|
-
*/
|
|
1433
1356
|
bindings: ScopeBinding[];
|
|
1434
1357
|
};
|
|
1435
|
-
/** One column a scope key is bound to by the host's behaviors. */
|
|
1436
1358
|
type ScopeBinding = {
|
|
1437
1359
|
entity: string;
|
|
1438
1360
|
field: string;
|
|
1439
1361
|
key: string;
|
|
1440
1362
|
};
|
|
1441
|
-
/**
|
|
1442
|
-
* DSL generation from intent + shape. Wire to a Cortex agent (see agent/).
|
|
1443
|
-
* `schema` holds only the tables the caller's policy lets them read.
|
|
1444
|
-
*/
|
|
1445
1363
|
type GenerateDsl = (request: QueryRequest, schema: DatabaseSchema, caller: GenerationCaller) => Promise<Query>;
|
|
1446
|
-
/**
|
|
1447
|
-
* Result mapping from the raw row set to the requested shape. The mapping runs
|
|
1448
|
-
* ONCE over `{ result }` — the rows for an array shape, the single (first) row
|
|
1449
|
-
* for an object shape — so `transformed` is whatever it produced: an array, a
|
|
1450
|
-
* single object, or a scalar. Wire to Prism's mapping agent.
|
|
1451
|
-
*/
|
|
1364
|
+
/** The IR is replayed against an envelope whose `result` is the rows for an array shape, the first row for any other. */
|
|
1452
1365
|
type MapToShape = (rows: Row[], shape: unknown) => Promise<{
|
|
1453
1366
|
ir: CompiledIr;
|
|
1454
1367
|
transformed: JsonValue;
|
|
1455
1368
|
}>;
|
|
1456
1369
|
type QueryEngineConfig = {
|
|
1457
1370
|
adapter: DatabaseAdapter;
|
|
1458
|
-
/**
|
|
1459
|
-
* Turns text into a vector at parameter-binding time, for `semantic`
|
|
1460
|
-
* filters. An injected provider (wire it to Signal), not a database
|
|
1461
|
-
* concern — the adapter only generates the vector-distance SQL.
|
|
1462
|
-
* Required only if the schema has vector columns you search over.
|
|
1463
|
-
*/
|
|
1464
1371
|
embed?: (text: string, dimensions?: number) => Promise<number[]>;
|
|
1465
1372
|
scope?: ScopePolicy;
|
|
1466
1373
|
cache?: CacheBackend;
|
|
1467
1374
|
onEvent?: VexEventHandler;
|
|
1468
|
-
/** Optional LLM-backed query generation (cache misses fail without it). */
|
|
1469
1375
|
generateDsl?: GenerateDsl;
|
|
1470
1376
|
/**
|
|
1471
|
-
*
|
|
1472
|
-
*
|
|
1473
|
-
*
|
|
1474
|
-
* schema's own terms (GenerationCaller.bindings). A compiled policy cannot
|
|
1475
|
-
* say it — it keeps only the phases a caller is granted, and the rule that
|
|
1476
|
-
* stamps a member's id lives on a write a reader does not hold. Checked at
|
|
1477
|
-
* `introspect`: every rule names a table and a column that exist.
|
|
1377
|
+
* Read for one thing: which columns a scope key is bound to, so a generation
|
|
1378
|
+
* can be told who its caller is (GenerationCaller.bindings). A compiled
|
|
1379
|
+
* policy cannot say it: it keeps only the phases a caller is granted.
|
|
1478
1380
|
*/
|
|
1479
1381
|
behaviors?: ScopeBehaviors;
|
|
1480
|
-
/** Optional LLM-backed result mapping (raw rows used as-is without it). */
|
|
1481
1382
|
mapToShape?: MapToShape;
|
|
1482
|
-
/**
|
|
1483
|
-
* The rows cache behind `refresh: 'reactive'` entries — its age, size and
|
|
1484
|
-
* burst window. Held in this process's memory; nothing else is cached.
|
|
1485
|
-
*/
|
|
1486
1383
|
rows?: LiveRowsConfig;
|
|
1487
1384
|
config?: {
|
|
1488
1385
|
maxNestingDepth?: number;
|
|
@@ -1506,14 +1403,7 @@ type QueryEngine = {
|
|
|
1506
1403
|
getDslSchema: () => object;
|
|
1507
1404
|
getSchema: () => DatabaseSchema | undefined;
|
|
1508
1405
|
cache: CacheBackend;
|
|
1509
|
-
/**
|
|
1510
|
-
* These tables were written. Every reactive read over any of them is
|
|
1511
|
-
* refetched (once per burst) and its followers told if their answer changed.
|
|
1512
|
-
* The vex handler calls this after every committed mutation; a host calls
|
|
1513
|
-
* it for writes vex did not make.
|
|
1514
|
-
*/
|
|
1515
1406
|
invalidate: (tables: readonly string[]) => void;
|
|
1516
|
-
/** The reactive rows cache: what it holds and how it is doing. */
|
|
1517
1407
|
rows: {
|
|
1518
1408
|
stats: () => LiveRowsStats;
|
|
1519
1409
|
stop: () => void;
|
|
@@ -1524,12 +1414,7 @@ type ExecuteOptions = {
|
|
|
1524
1414
|
entities?: string[];
|
|
1525
1415
|
locked?: boolean;
|
|
1526
1416
|
scopePolicy?: ScopePolicy;
|
|
1527
|
-
/**
|
|
1528
|
-
* FOLLOW THE ANSWER. For an entry with `refresh: 'reactive'`, every later
|
|
1529
|
-
* answer that differs from the last one is handed to `onChange` — after
|
|
1530
|
-
* writes to the tables the query reads — until `signal` aborts. Both or
|
|
1531
|
-
* neither; ignored for a snapshot read.
|
|
1532
|
-
*/
|
|
1417
|
+
/** `signal` and `onChange` go together; both are ignored for a snapshot read. */
|
|
1533
1418
|
signal?: AbortSignal;
|
|
1534
1419
|
onChange?: (response: QueryResponse) => void;
|
|
1535
1420
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niscorp/vex",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "Declarative query synthesis — intent to SQL with caching and scope policies",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -77,9 +77,9 @@
|
|
|
77
77
|
"peerDependencies": {
|
|
78
78
|
"hono": "^4",
|
|
79
79
|
"zod": "^4.2.0",
|
|
80
|
-
"@niscorp/cortex": "^0.1.
|
|
81
|
-
"@niscorp/prism": "^0.3.
|
|
82
|
-
"@niscorp/strata": "^0.1.
|
|
80
|
+
"@niscorp/cortex": "^0.1.4",
|
|
81
|
+
"@niscorp/prism": "^0.3.1",
|
|
82
|
+
"@niscorp/strata": "^0.1.7"
|
|
83
83
|
},
|
|
84
84
|
"devDependencies": {
|
|
85
85
|
"@electric-sql/pglite": "^0.5.1",
|
|
@@ -92,9 +92,9 @@
|
|
|
92
92
|
"tsx": "^4.20.3",
|
|
93
93
|
"vitest": "^4.1.2",
|
|
94
94
|
"zod": "^4.6.5",
|
|
95
|
-
"@niscorp/
|
|
96
|
-
"@niscorp/
|
|
97
|
-
"@niscorp/
|
|
95
|
+
"@niscorp/cortex": "^0.1.4",
|
|
96
|
+
"@niscorp/prism": "^0.3.1",
|
|
97
|
+
"@niscorp/strata": "^0.1.7"
|
|
98
98
|
},
|
|
99
99
|
"peerDependenciesMeta": {
|
|
100
100
|
"@niscorp/cortex": {
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/schemas/value.schema.ts","../src/schemas/identifier.schema.ts","../src/schemas/filter.schema.ts","../src/schemas/compute.schema.ts","../src/schemas/aggregate.schema.ts","../src/schemas/query.schema.ts","../src/errors.ts"],"names":["z"],"mappings":"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","file":"chunk-H4BHW76Q.js","sourcesContent":["import { z } from 'zod';\n\nexport const ContextRefSchema = z\n .object({\n $context: z.string().describe('Key to look up in the request context object'),\n })\n .strict()\n .describe('Reference to a caller-provided context value');\n\nexport const ScopeRefSchema = z\n .object({\n $scope: z.string().describe('Key to look up in the server-side scope values'),\n })\n .strict()\n .describe('Reference to a server-injected scope value (access control)');\n\nexport const FieldOrValueSchema = z\n .union([\n z.string().describe('A field path (entity.field format) or a literal string'),\n z.number().describe('A literal number'),\n z.boolean().describe('A literal boolean'),\n z.null().describe('A literal null'),\n ContextRefSchema,\n ScopeRefSchema,\n ])\n .describe('A field path, literal value, or dynamic reference');\n\nexport type ContextRef = z.infer<typeof ContextRefSchema>;\nexport type ScopeRef = z.infer<typeof ScopeRefSchema>;\nexport type FieldOrValue = z.infer<typeof FieldOrValueSchema>;\n","import { z } from 'zod';\n\n// ═══════════════════════════════════════════════════════════════\n// THE NAMES A QUERY MAY SAY — and the one rule for telling them apart.\n//\n// Every string an author (a person, a seed, a model) puts in a NAME position\n// ends up in SQL text: a column reference, an output alias, a subquery alias.\n// Values never do — they bind as parameters or are quoted as literals. So a\n// name is the only place authored text meets the statement, and it is held to\n// a grammar that cannot carry anything but a name: letters, digits and\n// underscores, not starting with a digit.\n//\n// This is the parse-time half. The resolver checks the same predicates again,\n// because `engine.compile()` and `engine.test()` take a DSL that never went\n// through Zod, and the compiler refuses to emit a field position that did not\n// resolve against the introspected schema. Three layers, one grammar.\n//\n// `isFieldPathShape` is also what decides, in a value position, whether a\n// string is a column or a literal. It used to be \"contains a dot\", which made\n// every email address an unknown entity and every string with a dot a column\n// reference — so a literal like \"u1@x.com\" threw, and a string that merely\n// looked dotted went to SQL as a name. Now a column is exactly `ident.ident`,\n// and everything else is a literal.\n// ═══════════════════════════════════════════════════════════════\n\nconst IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\nconst FIELD_PATH = /^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$/;\n\nexport const isIdentifier = (value: string): boolean => IDENTIFIER.test(value);\n\nexport const isFieldPathShape = (value: unknown): value is string => typeof value === 'string' && FIELD_PATH.test(value);\n\nexport const IdentifierSchema = z\n .string()\n .regex(IDENTIFIER, 'A name is letters, digits and underscores, not starting with a digit');\n\nexport const FieldPathSchema = z\n .string()\n .regex(FIELD_PATH, 'A field path is entity.field — each part letters, digits and underscores, not starting with a digit');\n","import { z } from 'zod';\nimport { ContextRefSchema, ScopeRefSchema, FieldOrValueSchema } from './value.schema.js';\nimport { FieldPathSchema } from './identifier.schema.js';\nimport type { ContextRef, ScopeRef, FieldOrValue } from './value.schema.js';\n\n// EXISTS — \"is there a row over there that points back at this one\".\n//\n// It is the same `{ from, filter }` a query already is, and deliberately no\n// more than that: no fields, no sort, no limit, nothing to select. EXISTS asks\n// whether a row is there, so anything that shapes output would be noise the\n// planner discards, and refusing it is what keeps this an operator rather than\n// an invitation to nest arbitrary SQL.\n//\n// The CORRELATION needs no new vocabulary. A dotted string on either side of a\n// comparison is already a field path, so pointing the inner table at the outer\n// one is an ordinary `eq` between two columns:\n//\n// { exists: { from: ['tasks'], filter: { eq: ['tasks.issue_id', 'issues.id'] } } }\n//\n// and `not` composes for NOT EXISTS. Whoever writes SQL writes this on the\n// first try, which is the entire design goal.\nexport type ExistsQuery = {\n from: string[];\n filter?: Filter;\n};\n\nexport type Filter =\n | { exists: ExistsQuery }\n | { eq: [FieldOrValue, FieldOrValue] }\n | { neq: [FieldOrValue, FieldOrValue] }\n | { gt: [FieldOrValue, FieldOrValue] }\n | { gte: [FieldOrValue, FieldOrValue] }\n | { lt: [FieldOrValue, FieldOrValue] }\n | { lte: [FieldOrValue, FieldOrValue] }\n | { in: [string, FieldOrValue[] | ContextRef | ScopeRef] }\n | { notIn: [string, FieldOrValue[] | ContextRef | ScopeRef] }\n | { like: [string, FieldOrValue] }\n | { ilike: [string, FieldOrValue] }\n | { isNull: string }\n | { isNotNull: string }\n | { and: Filter[] }\n | { or: Filter[] }\n | { not: Filter }\n | { semantic: { field: string; query: ContextRef | ScopeRef; minScore?: number } }\n | { fuzzy: { field: string; query: ContextRef | ScopeRef; maxDistance?: number } }\n | { optional: { key: string | string[]; then: Filter } };\n\nconst comparisonPair = z\n .tuple([FieldOrValueSchema, FieldOrValueSchema])\n .describe('[left, right] — both can be field paths, literals, or references');\n\nconst fieldString = FieldPathSchema.describe('Field path in entity.field format');\n\nconst collectionTarget = z\n .union([\n z.array(FieldOrValueSchema).min(1).describe('Array of literal values or references'),\n ContextRefSchema,\n ScopeRefSchema,\n ])\n .describe('A set of values or a reference that resolves to an array');\n\nconst ExistsSchema: z.ZodType<ExistsQuery> = z.lazy(() =>\n z\n .object({\n from: z.array(z.string()).min(1).describe('Entities the subquery reads. Joined by foreign key like any other from.'),\n filter: FilterSchema.optional().describe('The correlation, and any extra condition. Reference the outer query by its own entity path: { eq: [\"<inner>.<fk>\", \"<outer>.id\"] }.'),\n })\n .strict(),\n);\n\nexport const FilterSchema: z.ZodType<Filter> = z.lazy(() =>\n z.union([\n z.object({ exists: ExistsSchema }).strict().describe('EXISTS: true when the subquery matches at least one row. Wrap in `not` for NOT EXISTS.'),\n z.object({ eq: comparisonPair }).strict().describe('Equals: tests equality between two values'),\n z.object({ neq: comparisonPair }).strict().describe('Not equals'),\n z.object({ gt: comparisonPair }).strict().describe('Greater than'),\n z.object({ gte: comparisonPair }).strict().describe('Greater than or equal'),\n z.object({ lt: comparisonPair }).strict().describe('Less than'),\n z.object({ lte: comparisonPair }).strict().describe('Less than or equal'),\n z.object({ in: z.tuple([fieldString, collectionTarget]) }).strict().describe('Field value is in a set'),\n z.object({ notIn: z.tuple([fieldString, collectionTarget]) }).strict().describe('Field value is not in a set'),\n z.object({ like: z.tuple([fieldString, FieldOrValueSchema]) }).strict().describe('Case-sensitive LIKE pattern match (use % as wildcard)'),\n z.object({ ilike: z.tuple([fieldString, FieldOrValueSchema]) }).strict().describe('Case-insensitive ILIKE pattern match (use % as wildcard)'),\n z.object({ isNull: fieldString }).strict().describe('Field value is NULL'),\n z.object({ isNotNull: fieldString }).strict().describe('Field value is NOT NULL'),\n z.object({ and: z.array(FilterSchema).min(2) }).strict().describe('Logical AND: all conditions must be true'),\n z.object({ or: z.array(FilterSchema).min(2) }).strict().describe('Logical OR: at least one condition must be true'),\n z.object({ not: FilterSchema }).strict().describe('Logical NOT: negates the condition'),\n z.object({\n semantic: z.object({\n field: FieldPathSchema.describe('Vector column field path (entity.field)'),\n query: z.union([ContextRefSchema, ScopeRefSchema]).describe('Text to embed and compare'),\n minScore: z.number().min(0).max(1).optional().describe('Minimum cosine similarity (0–1)'),\n }).strict(),\n }).strict().describe('Semantic vector similarity search'),\n z.object({\n fuzzy: z.object({\n field: FieldPathSchema.describe('String field path'),\n query: z.union([ContextRefSchema, ScopeRefSchema]).describe('Text to fuzzy-match'),\n maxDistance: z.number().int().nonnegative().optional().describe('Maximum Levenshtein edit distance'),\n }).strict(),\n }).strict().describe('Fuzzy string match'),\n z.object({\n optional: z.object({\n key: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)])\n .describe('The context key this condition depends on, or EVERY key it depends on. A condition referencing two keys must name both — gating on one leaves the other conditionally required, which surfaces as an empty result rather than as a condition that did not apply.'),\n // BARE, never `.describe()`d. That call CLONES the schema, and zod\n // detects a recursive reference by instance identity — a clone is a\n // different instance, so `to-json-schema` stops seeing the cycle and\n // expands the filter union into itself until the stack goes. Every\n // other recursive slot here (`not`, `and`, `or`) uses it bare for the\n // same reason; the description belongs on the wrapper below.\n then: FilterSchema,\n }).strict(),\n }).strict().describe(\n 'A condition the caller turns on by supplying context keys. When any named key is absent the condition is REMOVED from the query before it compiles — it does not match everything, it is not there. Absent means missing, undefined or null; \"\" is a value and keeps the condition. Direction follows position: under `and` supplying the key NARROWS, under `or` it WIDENS. Either way an absent key reads exactly as if the condition had never been written, and scope is injected afterwards regardless. Reads only: a mutation may not contain one, and neither may the inside of an `exists` (its correlation must be unconditional).',\n ),\n ]),\n);\n","import { z } from 'zod';\nimport { FieldOrValueSchema } from './value.schema.js';\nimport { FilterSchema } from './filter.schema.js';\n\nconst CaseWhenSchema = z\n .object({\n condition: FilterSchema,\n then: FieldOrValueSchema.describe('Value when condition is true'),\n })\n .strict();\n\nexport const ComputeExpressionSchema = z\n .union([\n z.object({ add: z.tuple([FieldOrValueSchema, FieldOrValueSchema]) }).strict().describe('Addition: a + b'),\n z.object({ subtract: z.tuple([FieldOrValueSchema, FieldOrValueSchema]) }).strict().describe('Subtraction: a - b'),\n z.object({ multiply: z.tuple([FieldOrValueSchema, FieldOrValueSchema]) }).strict().describe('Multiplication: a * b'),\n z.object({ divide: z.tuple([FieldOrValueSchema, FieldOrValueSchema]) }).strict().describe('Division: a / b'),\n z.object({ concat: z.array(FieldOrValueSchema).min(2) }).strict().describe('String concatenation'),\n z.object({ coalesce: z.array(FieldOrValueSchema).min(2) }).strict().describe('Returns first non-null value'),\n z.object({\n case: z\n .object({\n when: z.array(CaseWhenSchema).min(1).describe('Condition/result pairs evaluated in order'),\n else: FieldOrValueSchema.describe('Default value when no condition matches'),\n })\n .strict(),\n }).strict().describe('CASE WHEN conditional expression'),\n ])\n .describe('Computed expression: arithmetic, string, or conditional');\n\nexport type ComputeExpression = z.infer<typeof ComputeExpressionSchema>;\n","import { z } from 'zod';\nimport { ComputeExpressionSchema } from './compute.schema.js';\nimport { FieldPathSchema } from './identifier.schema.js';\n\nconst fieldPath = FieldPathSchema.describe('Field path in entity.field format');\n\n// SUM/AVG/MIN/MAX take either a field path or a compute expression — so the\n// argument can be a derived value (e.g. SUM(value * win_probability / 100)),\n// not just a column. A bare string stays valid (non-breaking).\nconst fieldOrExpr = z.union([fieldPath, ComputeExpressionSchema]).describe('A field path or a compute expression');\n\nexport const AggregateExpressionSchema = z\n .union([\n z.object({ count: z.union([FieldPathSchema, z.literal('*')]).describe('Field path or \"*\" for COUNT(*)') }).strict().describe('COUNT'),\n z.object({ countDistinct: FieldPathSchema.describe('Field path whose distinct non-null values are counted') }).strict().describe('COUNT(DISTINCT field)'),\n z.object({ sum: fieldOrExpr }).strict().describe('SUM'),\n z.object({ avg: fieldOrExpr }).strict().describe('AVG'),\n z.object({ min: fieldOrExpr }).strict().describe('MIN'),\n z.object({ max: fieldOrExpr }).strict().describe('MAX'),\n ])\n .describe('Aggregate function applied to a field or expression');\n\nexport type AggregateExpression = z.infer<typeof AggregateExpressionSchema>;\n","import { z } from 'zod';\nimport { FilterSchema } from './filter.schema.js';\nimport { ComputeExpressionSchema } from './compute.schema.js';\nimport { AggregateExpressionSchema } from './aggregate.schema.js';\nimport { FieldPathSchema, IdentifierSchema } from './identifier.schema.js';\nimport type { Filter } from './filter.schema.js';\nimport type { ComputeExpression } from './compute.schema.js';\nimport type { AggregateExpression } from './aggregate.schema.js';\n\nexport const SortEntrySchema = z\n .object({\n field: z.union([FieldPathSchema, IdentifierSchema]).describe('Field path (entity.field), computed field name, or aggregate alias'),\n dir: z.enum(['asc', 'desc']).default('asc').describe('Sort direction'),\n })\n .strict()\n .describe('Sort specification');\n\nexport type SortEntry = z.infer<typeof SortEntrySchema>;\n\nexport type Source = string | { as: string; query: Query };\n\n// A selected field: a bare `entity.field` path, or an aliased one whose output\n// key is `as` (so joined columns that would collide — three `name`s — get\n// distinct keys without a compute hack).\nexport type FieldRef = string | { field: string; as: string };\n\nexport type Query = {\n from: Source[];\n // Optional: a query may select only aggregates (e.g. a bare `COUNT(*)`); the\n // schema requires at least one of `fields` / `aggregate`.\n fields?: FieldRef[];\n filter?: Filter;\n compute?: Record<string, ComputeExpression>;\n aggregate?: Record<string, AggregateExpression>;\n groupBy?: string[];\n sort?: SortEntry[];\n limit?: number;\n distinct?: boolean;\n};\n\nconst SubquerySourceSchema = z\n .object({\n as: IdentifierSchema.describe('Alias for subquery results — use as prefix in field paths'),\n query: z.lazy((): z.ZodType<Query> => QuerySchema).describe('A nested query'),\n })\n .strict()\n .describe('Subquery data source: a nested query read as a table under `as`, its columns referenced as `<as>.<field>` anywhere in the outer query. Joined by foreign key like an entity when one links them; otherwise every outer row is paired with every subquery row (a cross join), so a one-row subquery puts its values beside each outer row.');\n\nconst SourceSchema = z\n .union([\n z.string().describe('Entity name from the database schema'),\n SubquerySourceSchema,\n ])\n .describe('Data source: entity name or subquery');\n\nconst FieldRefSchema = z\n .union([\n FieldPathSchema.describe('A column in entity.field format'),\n z\n .object({\n field: FieldPathSchema.describe('A column in entity.field format'),\n as: IdentifierSchema.describe('Output key for this column'),\n })\n .strict()\n .describe('An aliased column: output under `as` instead of the column name'),\n ])\n .describe('A selected field — a bare `entity.field`, or `{ field, as }` to alias the output key');\n\nexport const QuerySchema: z.ZodType<Query> = z.lazy(() =>\n z\n .object({\n from: z.array(SourceSchema).min(1).describe('Data sources — entity names or subqueries. Every entity used anywhere in the query must be listed here. Listed entities are JOINED FOR YOU along their foreign keys — a nullable key as a LEFT JOIN, so a row whose key is empty is kept, with the joined columns null. Never restate a join as a filter comparing the two keys: that throws those rows away.'),\n fields: z.array(FieldRefSchema).optional().describe('Raw columns to select — each `entity.field`, or `{ field, as }` to alias the output key (no SELECT *). Optional: omit it for an aggregate-only query (e.g. a bare COUNT). Do not list compute or aggregate aliases here — those are added automatically.'),\n filter: FilterSchema.optional().describe('Filter conditions'),\n compute: z.record(IdentifierSchema, ComputeExpressionSchema).optional().describe('Computed fields — key is output alias, value is the expression'),\n aggregate: z.record(IdentifierSchema, AggregateExpressionSchema).optional().describe('Aggregate functions — key is output alias, value is the function'),\n groupBy: z.array(FieldPathSchema).optional().describe('Fields to group by for aggregation'),\n sort: z.array(SortEntrySchema).optional().describe('Sort order'),\n limit: z.number().int().positive().optional().describe('Maximum rows to return'),\n distinct: z.boolean().optional().describe('Eliminate duplicate rows'),\n })\n .strict()\n .refine(\n (q) => (q.fields?.length ?? 0) > 0 || Object.keys(q.aggregate ?? {}).length > 0,\n { message: 'A query must select at least one of `fields` or `aggregate`.' },\n ),\n);\n\nexport { SubquerySourceSchema, SourceSchema };\n","import type { QueryErrorCode } from './schemas/request.schema.js';\n\n// ONE CLASS, SEVERAL COPIES. The CommonJS build gives each entry point\n// (`@niscorp/vex`, `/hono`, `/express`, `/agent`) its own copy of this class,\n// and an app can load the ESM and CommonJS builds side by side — so an error\n// thrown by an engine from one entry is not an `instanceof` the VexError\n// another entry holds. Every copy puts the same mark on its prototype, under a\n// key the whole process shares, and `isVexError` reads the mark. Wherever vex\n// itself asks \"is this one of ours\", it asks that, never `instanceof`.\nconst VEX_ERROR = Symbol.for('@niscorp/vex:VexError');\n\nexport class VexError extends Error {\n readonly code: QueryErrorCode;\n readonly details?: Record<string, unknown>;\n\n constructor(code: QueryErrorCode, message: string, details?: Record<string, unknown>) {\n super(message);\n this.name = 'VexError';\n this.code = code;\n this.details = details;\n }\n}\n\n// On the prototype, not the instance: a subclass inherits it, and nothing an\n// app prints, serializes or enumerates on an error changes.\nObject.defineProperty(VexError.prototype, VEX_ERROR, { value: true });\n\nexport const isVexError = (err: unknown): err is VexError =>\n err instanceof VexError || (err instanceof Error && Reflect.get(err, VEX_ERROR) === true);\n"]}
|