@niscorp/vex 0.2.3 → 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.
Files changed (40) hide show
  1. package/CHANGELOG.md +79 -0
  2. package/DESIGN.md +26 -11
  3. package/DOCS.md +39 -9
  4. package/dist/adapters/express/index.cjs +6 -24
  5. package/dist/adapters/express/index.cjs.map +1 -1
  6. package/dist/adapters/express/index.d.cts +2 -2
  7. package/dist/adapters/express/index.d.ts +2 -2
  8. package/dist/adapters/express/index.js +2 -2
  9. package/dist/adapters/express/index.js.map +1 -1
  10. package/dist/adapters/hono/index.cjs +6 -24
  11. package/dist/adapters/hono/index.cjs.map +1 -1
  12. package/dist/adapters/hono/index.d.cts +2 -2
  13. package/dist/adapters/hono/index.d.ts +2 -2
  14. package/dist/adapters/hono/index.js +2 -2
  15. package/dist/adapters/hono/index.js.map +1 -1
  16. package/dist/adapters/pglite/index.cjs.map +1 -1
  17. package/dist/adapters/pglite/index.js.map +1 -1
  18. package/dist/agent/index.cjs +5 -11
  19. package/dist/agent/index.cjs.map +1 -1
  20. package/dist/agent/index.d.cts +1 -1
  21. package/dist/agent/index.d.ts +1 -1
  22. package/dist/agent/index.js +3 -6
  23. package/dist/agent/index.js.map +1 -1
  24. package/dist/{chunk-IQM4SQE2.js → chunk-3HORTMZ7.js} +6 -21
  25. package/dist/chunk-3HORTMZ7.js.map +1 -0
  26. package/dist/{chunk-H4BHW76Q.js → chunk-J7JYKCUA.js} +5 -8
  27. package/dist/chunk-J7JYKCUA.js.map +1 -0
  28. package/dist/{handler-CMrjTXNx.d.cts → handler-B4NAi4k_.d.cts} +1 -1
  29. package/dist/{handler-BGCL6_Si.d.ts → handler-BRVhWuNk.d.ts} +1 -1
  30. package/dist/index.cjs +23 -79
  31. package/dist/index.cjs.map +1 -1
  32. package/dist/index.d.cts +14 -62
  33. package/dist/index.d.ts +14 -62
  34. package/dist/index.js +21 -59
  35. package/dist/index.js.map +1 -1
  36. package/dist/{types-Bi-Lg86b.d.cts → types-DUJp5B3o.d.cts} +9 -124
  37. package/dist/{types-Bi-Lg86b.d.ts → types-DUJp5B3o.d.ts} +9 -124
  38. package/package.json +7 -7
  39. package/dist/chunk-H4BHW76Q.js.map +0 -1
  40. package/dist/chunk-IQM4SQE2.js.map +0 -1
package/dist/index.d.cts CHANGED
@@ -1,8 +1,8 @@
1
- import { Q as QueryEngineConfig, a as QueryEngine, b as Query, D as DatabaseSchema, R as ResolvedQuery, A as AnalysisConfig, c as AnalysisResult, C as CompiledQuery, d as ContextMeta, e as DatabaseAdapter, f as Row, F as FieldSchema, P as ParamSlot, g as ResolvedExists, h as FieldOrValue, i as Filter, j as QueryErrorCode, S as ScopePolicy, k as CacheBackend, l as CacheEntry, m as Refresh, M as MutationDefinition, n as ContextContract } from './types-Bi-Lg86b.cjs';
2
- export { o as AdapterCapabilities, p as AggregateExpression, q as AggregateExpressionSchema, B as BoundParams, r as ComputeExpression, s as ComputeExpressionSchema, t as ContextRef, u as CoreMutation, E as EntitySchema, v as ExecuteOptions, w as FilterSchema, G as GenerateDsl, x as GenerationCaller, I as IndexSchema, y as IntrospectOptions, z as ItemRef, L as LiveRowsConfig, H as LiveRowsStats, J as LookupValue, K as MapToShape, N as Mutation, O as MutationCacheEntry, T as MutationDefinitionSchema, U as MutationSchema, V as MutationValue, W as NamedScopeBehaviors, X as NormalizedType, Y as OkCacheEntry, Z as QueryErrorResponse, _ as QueryRequest, $ as QueryRequestSchema, a0 as QueryResponse, a1 as QuerySchema, a2 as REFRESH_MODES, a3 as RelationSchema, a4 as ResolvedField, a5 as ResolvedFilter, a6 as ResolvedJoin, a7 as ResolvedMutation, a8 as ResolvedOnConflict, a9 as ResolvedSemantic, aa as ResolvedSource, ab as ReturnedRef, ac as SCOPE_VERBS, ad as ScopeBehaviors, ae as ScopeBinding, af as ScopeEntityRule, ag as ScopeMatch, ah as ScopeRef, ai as ScopeRule, aj as ScopeRules, ak as ScopeSet, al as ScopeValues, am as SortEntry, an as Source, ao as TestResult, ap as UnsatisfiableCacheEntry, aq as VexEvent, ar as VexEventHandler, as as createScopePolicy, at as isRefresh, au as mergeScopePolicies, av as scopeBindings, aw as scopeGrants, ax as scopeProfiles } from './types-Bi-Lg86b.cjs';
1
+ import { Q as QueryEngineConfig, a as QueryEngine, b as Query, D as DatabaseSchema, R as ResolvedQuery, A as AnalysisConfig, c as AnalysisResult, C as CompiledQuery, d as ContextMeta, e as DatabaseAdapter, f as Row, F as FieldSchema, P as ParamSlot, g as ResolvedExists, h as FieldOrValue, i as Filter, j as QueryErrorCode, S as ScopePolicy, k as CacheBackend, l as CacheEntry, m as Refresh, M as MutationDefinition, n as ContextContract } from './types-DUJp5B3o.cjs';
2
+ export { o as AdapterCapabilities, p as AggregateExpression, q as AggregateExpressionSchema, B as BoundParams, r as ComputeExpression, s as ComputeExpressionSchema, t as ContextRef, u as CoreMutation, E as EntitySchema, v as ExecuteOptions, w as FilterSchema, G as GenerateDsl, x as GenerationCaller, I as IndexSchema, y as IntrospectOptions, z as ItemRef, L as LiveRowsConfig, H as LiveRowsStats, J as LookupValue, K as MapToShape, N as Mutation, O as MutationCacheEntry, T as MutationDefinitionSchema, U as MutationSchema, V as MutationValue, W as NamedScopeBehaviors, X as NormalizedType, Y as OkCacheEntry, Z as QueryErrorResponse, _ as QueryRequest, $ as QueryRequestSchema, a0 as QueryResponse, a1 as QuerySchema, a2 as REFRESH_MODES, a3 as RelationSchema, a4 as ResolvedField, a5 as ResolvedFilter, a6 as ResolvedJoin, a7 as ResolvedMutation, a8 as ResolvedOnConflict, a9 as ResolvedSemantic, aa as ResolvedSource, ab as ReturnedRef, ac as SCOPE_VERBS, ad as ScopeBehaviors, ae as ScopeBinding, af as ScopeEntityRule, ag as ScopeMatch, ah as ScopeRef, ai as ScopeRule, aj as ScopeRules, ak as ScopeSet, al as ScopeValues, am as SortEntry, an as Source, ao as TestResult, ap as UnsatisfiableCacheEntry, aq as VexEvent, ar as VexEventHandler, as as createScopePolicy, at as isRefresh, au as mergeScopePolicies, av as scopeBindings, aw as scopeGrants, ax as scopeProfiles } from './types-DUJp5B3o.cjs';
3
3
  import { P as PgPool } from './introspect-D3OaXHBc.cjs';
4
4
  import { Sequence } from '@niscorp/strata';
5
- export { C as ContextField, a as ContextSignature, D as DiscoveryFingerprint, b as DiscoveryResponse, E as ExecuteRecord, M as MutationClient, c as MutationContext, d as MutationEffect, e as MutationTx, Q as QueryResult, V as VexHandlerConfig, f as VexLive, W as WriteEvent, g as WriteResult, h as collectMutationContext, i as collectQueryContext, j as executeMutation, k as executeWrites, l as handleDiscovery, m as handleFingerprintDelete, n as handleFingerprintPatch, o as handleQuery, p as lintMutation, q as mutationEffect, r as mutationMisfits, s as requiredContextKeys, t as tablesChangedBy } from './handler-CMrjTXNx.cjs';
5
+ export { C as ContextField, a as ContextSignature, D as DiscoveryFingerprint, b as DiscoveryResponse, E as ExecuteRecord, M as MutationClient, c as MutationContext, d as MutationEffect, e as MutationTx, Q as QueryResult, V as VexHandlerConfig, f as VexLive, W as WriteEvent, g as WriteResult, h as collectMutationContext, i as collectQueryContext, j as executeMutation, k as executeWrites, l as handleDiscovery, m as handleFingerprintDelete, n as handleFingerprintPatch, o as handleQuery, p as lintMutation, q as mutationEffect, r as mutationMisfits, s as requiredContextKeys, t as tablesChangedBy } from './handler-B4NAi4k_.cjs';
6
6
  import 'zod';
7
7
  import '@niscorp/prism';
8
8
 
@@ -16,38 +16,13 @@ declare const executeQuery: (compiled: CompiledQuery, context: Record<string, un
16
16
  declare const buildContextContract: (compiled: CompiledQuery, optionalKeys?: readonly string[]) => Record<string, ContextMeta>;
17
17
  declare const findMissingContext: (compiled: CompiledQuery, context: Record<string, unknown>) => string[];
18
18
 
19
- /** Every optional key mentioned anywhere in a query, in declaration order. */
20
19
  declare const optionalKeysOf: (dsl: Query) => string[];
21
- /** Which context keys the caller actually supplied.
22
- *
23
- * ABSENT MEANS MISSING, `undefined`, OR `null`. The empty string is a value —
24
- * searching for `''` is a real search — but null is not, for two reasons that
25
- * agree:
26
- *
27
- * · SQL. A bound null in a comparison can never match: `col = NULL` and
28
- * `col ILIKE NULL` are both NULL, never true. So "send null" could only ever
29
- * have meant "I have nothing", and vex already has `isNull`/`isNotNull` for
30
- * the question people actually mean by it. Nothing is lost.
31
- *
32
- * · The wire. JSON has no `undefined`, and a request prism assembles a fixed
33
- * object — it cannot conditionally omit a key. Without null counting as
34
- * absent, every caller with an empty search box would have to bind a
35
- * sentinel again, which is the exact thing this feature removes.
36
- *
37
- * This is deliberately WIDER than `findMissingContext`'s test, which stays on
38
- * `undefined` alone. A required key sent as null still binds null and matches
39
- * nothing; an optional key sent as null drops its condition. That reads like a
40
- * contradiction and is not: the author chose which keys are optional, and for
41
- * those they have already said absence means "this does not apply". A caller
42
- * gains nothing by it either — omitting the key does the same thing, and scope
43
- * is injected after this either way. */
20
+ /** null counts as absent, wider than `findMissingContext`'s `undefined`: JSON
21
+ * has no `undefined`, and a bound null never matches in a comparison anyway.
22
+ * The empty string is a value. */
44
23
  declare const presenceOf: (context: Record<string, unknown>) => ReadonlySet<string>;
45
- /** Resolve every optional condition against the keys a caller supplied.
46
- *
47
- * A query whose filter prunes away entirely comes back with NO filter, which
48
- * is the point: `people/list` with no lens, no search and no cursor is the
49
- * whole roll, and it says so by having nothing to say. Scope is injected
50
- * after this, so "no filter" still never means "every tenant". */
24
+ /** Scope is injected after this, so a filter pruned away entirely still never
25
+ * means every tenant. */
51
26
  declare const pruneOptional: (dsl: Query, present: ReadonlySet<string> | "all") => Query;
52
27
 
53
28
  type PostgresAdapterConfig = {
@@ -90,18 +65,19 @@ declare class VexScopeError extends VexError {
90
65
  }
91
66
  declare const checkScope: (entities: Set<string>, policy: ScopePolicy) => void;
92
67
  declare const scopeResolved: (resolved: ResolvedQuery, policy: ScopePolicy) => ResolvedQuery;
68
+ /**
69
+ * @deprecated Checks access only and returns the query as it came, with no row
70
+ * rule added. Use `checkScope`; row rules are placed by `scopeResolved`, on the
71
+ * resolved query.
72
+ */
93
73
  declare const applyScope: (dsl: Query, entities: Set<string>, policy: ScopePolicy) => Query;
94
74
 
95
75
  declare const createMemoryCache: () => CacheBackend;
96
76
 
97
77
  type PostgresCacheConfig = {
98
- /** A pg Pool (or anything matching its query shape). The caller owns its lifecycle. */
99
78
  pool: PgPool;
100
- /** Schema to place the cache table in. Default: 'public'. */
101
79
  schema?: string;
102
- /** Table name. Default: 'vex_cache'. */
103
80
  table?: string;
104
- /** Called on rejected writes and evicted-on-read invalid rows. */
105
81
  onError?: (err: unknown) => void;
106
82
  };
107
83
  type PostgresCache = CacheBackend & {
@@ -114,24 +90,14 @@ type PostgresCache = CacheBackend & {
114
90
  };
115
91
  declare const createPostgresCache: (config: PostgresCacheConfig) => PostgresCache;
116
92
 
117
- type WarmupMode =
118
- /** Load all of L2 into L1 on init (default). Start fully hot. */
119
- 'full'
120
- /** Don't preload; L1 fills on demand via get→promote. Bounded memory. */
121
- | 'lazy'
122
- /** Preload only these fingerprints; lazy-fill the rest. */
123
- | {
93
+ type WarmupMode = 'full' | 'lazy' | {
124
94
  mode: 'partial';
125
95
  fingerprints: string[];
126
96
  };
127
97
  type TieredCacheConfig = {
128
- /** Fast, volatile tier (e.g. createMemoryCache()). */
129
98
  l1: CacheBackend;
130
- /** Durable source of truth (e.g. createPostgresCache(...)). */
131
99
  l2: CacheBackend;
132
- /** Warm-up strategy run by init(). Default: 'full'. */
133
100
  warmup?: WarmupMode;
134
- /** Called on background failures (async L2 writes) and dropped invalid entries. */
135
101
  onError?: (err: unknown) => void;
136
102
  };
137
103
  type TieredCache = CacheBackend & {
@@ -139,10 +105,6 @@ type TieredCache = CacheBackend & {
139
105
  };
140
106
  declare const createTieredCache: (config: TieredCacheConfig) => TieredCache;
141
107
 
142
- /**
143
- * Returns `null` if the entry is valid, or a human-readable reason
144
- * string if it is not.
145
- */
146
108
  declare const validateEntry: (entry: CacheEntry) => string | null;
147
109
 
148
110
  declare const normalizeShape: (shape: unknown) => unknown;
@@ -154,13 +116,6 @@ declare const computeRequestHash: (request: {
154
116
  }) => string;
155
117
  declare const computeSchemaFingerprint: (schema: DatabaseSchema) => string;
156
118
 
157
- /**
158
- * Lifetime = usage. Evicts unprotected entries that have not been
159
- * replayed within `maxIdleMs` (falling back to createdAt for entries
160
- * never touched). Protected entries never sweep. Run it on whatever
161
- * cadence suits the app (startup, a timer, a cron) — it is hygiene,
162
- * not a correctness requirement: entries are single-digit KB.
163
- */
164
119
  declare const sweepCache: (cache: {
165
120
  entries?: () => Promise<Array<{
166
121
  key: string;
@@ -179,16 +134,13 @@ type SeedEntry = {
179
134
  shape?: unknown;
180
135
  dsl: Query;
181
136
  mapping?: unknown;
182
- /** The reach this read requires whatever the caller holds — see `OkCacheEntry.reach`. */
183
137
  reach?: string;
184
- /** When this read's answer is refreshed — see `Refresh`. Absent means 'snapshot'. */
185
138
  refresh?: Refresh;
186
139
  };
187
140
  type SeedMutation = {
188
141
  fingerprint: string;
189
142
  intent?: string;
190
143
  mutation: MutationDefinition;
191
- /** The reach this write requires whatever the caller holds — see `MutationCacheEntry.reach`. */
192
144
  reach?: string;
193
145
  };
194
146
  declare const seedCache: (cache: CacheBackend, entries: readonly (SeedEntry | SeedMutation)[]) => Promise<void>;
package/dist/index.d.ts CHANGED
@@ -1,8 +1,8 @@
1
- import { Q as QueryEngineConfig, a as QueryEngine, b as Query, D as DatabaseSchema, R as ResolvedQuery, A as AnalysisConfig, c as AnalysisResult, C as CompiledQuery, d as ContextMeta, e as DatabaseAdapter, f as Row, F as FieldSchema, P as ParamSlot, g as ResolvedExists, h as FieldOrValue, i as Filter, j as QueryErrorCode, S as ScopePolicy, k as CacheBackend, l as CacheEntry, m as Refresh, M as MutationDefinition, n as ContextContract } from './types-Bi-Lg86b.js';
2
- export { o as AdapterCapabilities, p as AggregateExpression, q as AggregateExpressionSchema, B as BoundParams, r as ComputeExpression, s as ComputeExpressionSchema, t as ContextRef, u as CoreMutation, E as EntitySchema, v as ExecuteOptions, w as FilterSchema, G as GenerateDsl, x as GenerationCaller, I as IndexSchema, y as IntrospectOptions, z as ItemRef, L as LiveRowsConfig, H as LiveRowsStats, J as LookupValue, K as MapToShape, N as Mutation, O as MutationCacheEntry, T as MutationDefinitionSchema, U as MutationSchema, V as MutationValue, W as NamedScopeBehaviors, X as NormalizedType, Y as OkCacheEntry, Z as QueryErrorResponse, _ as QueryRequest, $ as QueryRequestSchema, a0 as QueryResponse, a1 as QuerySchema, a2 as REFRESH_MODES, a3 as RelationSchema, a4 as ResolvedField, a5 as ResolvedFilter, a6 as ResolvedJoin, a7 as ResolvedMutation, a8 as ResolvedOnConflict, a9 as ResolvedSemantic, aa as ResolvedSource, ab as ReturnedRef, ac as SCOPE_VERBS, ad as ScopeBehaviors, ae as ScopeBinding, af as ScopeEntityRule, ag as ScopeMatch, ah as ScopeRef, ai as ScopeRule, aj as ScopeRules, ak as ScopeSet, al as ScopeValues, am as SortEntry, an as Source, ao as TestResult, ap as UnsatisfiableCacheEntry, aq as VexEvent, ar as VexEventHandler, as as createScopePolicy, at as isRefresh, au as mergeScopePolicies, av as scopeBindings, aw as scopeGrants, ax as scopeProfiles } from './types-Bi-Lg86b.js';
1
+ import { Q as QueryEngineConfig, a as QueryEngine, b as Query, D as DatabaseSchema, R as ResolvedQuery, A as AnalysisConfig, c as AnalysisResult, C as CompiledQuery, d as ContextMeta, e as DatabaseAdapter, f as Row, F as FieldSchema, P as ParamSlot, g as ResolvedExists, h as FieldOrValue, i as Filter, j as QueryErrorCode, S as ScopePolicy, k as CacheBackend, l as CacheEntry, m as Refresh, M as MutationDefinition, n as ContextContract } from './types-DUJp5B3o.js';
2
+ export { o as AdapterCapabilities, p as AggregateExpression, q as AggregateExpressionSchema, B as BoundParams, r as ComputeExpression, s as ComputeExpressionSchema, t as ContextRef, u as CoreMutation, E as EntitySchema, v as ExecuteOptions, w as FilterSchema, G as GenerateDsl, x as GenerationCaller, I as IndexSchema, y as IntrospectOptions, z as ItemRef, L as LiveRowsConfig, H as LiveRowsStats, J as LookupValue, K as MapToShape, N as Mutation, O as MutationCacheEntry, T as MutationDefinitionSchema, U as MutationSchema, V as MutationValue, W as NamedScopeBehaviors, X as NormalizedType, Y as OkCacheEntry, Z as QueryErrorResponse, _ as QueryRequest, $ as QueryRequestSchema, a0 as QueryResponse, a1 as QuerySchema, a2 as REFRESH_MODES, a3 as RelationSchema, a4 as ResolvedField, a5 as ResolvedFilter, a6 as ResolvedJoin, a7 as ResolvedMutation, a8 as ResolvedOnConflict, a9 as ResolvedSemantic, aa as ResolvedSource, ab as ReturnedRef, ac as SCOPE_VERBS, ad as ScopeBehaviors, ae as ScopeBinding, af as ScopeEntityRule, ag as ScopeMatch, ah as ScopeRef, ai as ScopeRule, aj as ScopeRules, ak as ScopeSet, al as ScopeValues, am as SortEntry, an as Source, ao as TestResult, ap as UnsatisfiableCacheEntry, aq as VexEvent, ar as VexEventHandler, as as createScopePolicy, at as isRefresh, au as mergeScopePolicies, av as scopeBindings, aw as scopeGrants, ax as scopeProfiles } from './types-DUJp5B3o.js';
3
3
  import { P as PgPool } from './introspect-D3OaXHBc.js';
4
4
  import { Sequence } from '@niscorp/strata';
5
- export { C as ContextField, a as ContextSignature, D as DiscoveryFingerprint, b as DiscoveryResponse, E as ExecuteRecord, M as MutationClient, c as MutationContext, d as MutationEffect, e as MutationTx, Q as QueryResult, V as VexHandlerConfig, f as VexLive, W as WriteEvent, g as WriteResult, h as collectMutationContext, i as collectQueryContext, j as executeMutation, k as executeWrites, l as handleDiscovery, m as handleFingerprintDelete, n as handleFingerprintPatch, o as handleQuery, p as lintMutation, q as mutationEffect, r as mutationMisfits, s as requiredContextKeys, t as tablesChangedBy } from './handler-BGCL6_Si.js';
5
+ export { C as ContextField, a as ContextSignature, D as DiscoveryFingerprint, b as DiscoveryResponse, E as ExecuteRecord, M as MutationClient, c as MutationContext, d as MutationEffect, e as MutationTx, Q as QueryResult, V as VexHandlerConfig, f as VexLive, W as WriteEvent, g as WriteResult, h as collectMutationContext, i as collectQueryContext, j as executeMutation, k as executeWrites, l as handleDiscovery, m as handleFingerprintDelete, n as handleFingerprintPatch, o as handleQuery, p as lintMutation, q as mutationEffect, r as mutationMisfits, s as requiredContextKeys, t as tablesChangedBy } from './handler-BRVhWuNk.js';
6
6
  import 'zod';
7
7
  import '@niscorp/prism';
8
8
 
@@ -16,38 +16,13 @@ declare const executeQuery: (compiled: CompiledQuery, context: Record<string, un
16
16
  declare const buildContextContract: (compiled: CompiledQuery, optionalKeys?: readonly string[]) => Record<string, ContextMeta>;
17
17
  declare const findMissingContext: (compiled: CompiledQuery, context: Record<string, unknown>) => string[];
18
18
 
19
- /** Every optional key mentioned anywhere in a query, in declaration order. */
20
19
  declare const optionalKeysOf: (dsl: Query) => string[];
21
- /** Which context keys the caller actually supplied.
22
- *
23
- * ABSENT MEANS MISSING, `undefined`, OR `null`. The empty string is a value —
24
- * searching for `''` is a real search — but null is not, for two reasons that
25
- * agree:
26
- *
27
- * · SQL. A bound null in a comparison can never match: `col = NULL` and
28
- * `col ILIKE NULL` are both NULL, never true. So "send null" could only ever
29
- * have meant "I have nothing", and vex already has `isNull`/`isNotNull` for
30
- * the question people actually mean by it. Nothing is lost.
31
- *
32
- * · The wire. JSON has no `undefined`, and a request prism assembles a fixed
33
- * object — it cannot conditionally omit a key. Without null counting as
34
- * absent, every caller with an empty search box would have to bind a
35
- * sentinel again, which is the exact thing this feature removes.
36
- *
37
- * This is deliberately WIDER than `findMissingContext`'s test, which stays on
38
- * `undefined` alone. A required key sent as null still binds null and matches
39
- * nothing; an optional key sent as null drops its condition. That reads like a
40
- * contradiction and is not: the author chose which keys are optional, and for
41
- * those they have already said absence means "this does not apply". A caller
42
- * gains nothing by it either — omitting the key does the same thing, and scope
43
- * is injected after this either way. */
20
+ /** null counts as absent, wider than `findMissingContext`'s `undefined`: JSON
21
+ * has no `undefined`, and a bound null never matches in a comparison anyway.
22
+ * The empty string is a value. */
44
23
  declare const presenceOf: (context: Record<string, unknown>) => ReadonlySet<string>;
45
- /** Resolve every optional condition against the keys a caller supplied.
46
- *
47
- * A query whose filter prunes away entirely comes back with NO filter, which
48
- * is the point: `people/list` with no lens, no search and no cursor is the
49
- * whole roll, and it says so by having nothing to say. Scope is injected
50
- * after this, so "no filter" still never means "every tenant". */
24
+ /** Scope is injected after this, so a filter pruned away entirely still never
25
+ * means every tenant. */
51
26
  declare const pruneOptional: (dsl: Query, present: ReadonlySet<string> | "all") => Query;
52
27
 
53
28
  type PostgresAdapterConfig = {
@@ -90,18 +65,19 @@ declare class VexScopeError extends VexError {
90
65
  }
91
66
  declare const checkScope: (entities: Set<string>, policy: ScopePolicy) => void;
92
67
  declare const scopeResolved: (resolved: ResolvedQuery, policy: ScopePolicy) => ResolvedQuery;
68
+ /**
69
+ * @deprecated Checks access only and returns the query as it came, with no row
70
+ * rule added. Use `checkScope`; row rules are placed by `scopeResolved`, on the
71
+ * resolved query.
72
+ */
93
73
  declare const applyScope: (dsl: Query, entities: Set<string>, policy: ScopePolicy) => Query;
94
74
 
95
75
  declare const createMemoryCache: () => CacheBackend;
96
76
 
97
77
  type PostgresCacheConfig = {
98
- /** A pg Pool (or anything matching its query shape). The caller owns its lifecycle. */
99
78
  pool: PgPool;
100
- /** Schema to place the cache table in. Default: 'public'. */
101
79
  schema?: string;
102
- /** Table name. Default: 'vex_cache'. */
103
80
  table?: string;
104
- /** Called on rejected writes and evicted-on-read invalid rows. */
105
81
  onError?: (err: unknown) => void;
106
82
  };
107
83
  type PostgresCache = CacheBackend & {
@@ -114,24 +90,14 @@ type PostgresCache = CacheBackend & {
114
90
  };
115
91
  declare const createPostgresCache: (config: PostgresCacheConfig) => PostgresCache;
116
92
 
117
- type WarmupMode =
118
- /** Load all of L2 into L1 on init (default). Start fully hot. */
119
- 'full'
120
- /** Don't preload; L1 fills on demand via get→promote. Bounded memory. */
121
- | 'lazy'
122
- /** Preload only these fingerprints; lazy-fill the rest. */
123
- | {
93
+ type WarmupMode = 'full' | 'lazy' | {
124
94
  mode: 'partial';
125
95
  fingerprints: string[];
126
96
  };
127
97
  type TieredCacheConfig = {
128
- /** Fast, volatile tier (e.g. createMemoryCache()). */
129
98
  l1: CacheBackend;
130
- /** Durable source of truth (e.g. createPostgresCache(...)). */
131
99
  l2: CacheBackend;
132
- /** Warm-up strategy run by init(). Default: 'full'. */
133
100
  warmup?: WarmupMode;
134
- /** Called on background failures (async L2 writes) and dropped invalid entries. */
135
101
  onError?: (err: unknown) => void;
136
102
  };
137
103
  type TieredCache = CacheBackend & {
@@ -139,10 +105,6 @@ type TieredCache = CacheBackend & {
139
105
  };
140
106
  declare const createTieredCache: (config: TieredCacheConfig) => TieredCache;
141
107
 
142
- /**
143
- * Returns `null` if the entry is valid, or a human-readable reason
144
- * string if it is not.
145
- */
146
108
  declare const validateEntry: (entry: CacheEntry) => string | null;
147
109
 
148
110
  declare const normalizeShape: (shape: unknown) => unknown;
@@ -154,13 +116,6 @@ declare const computeRequestHash: (request: {
154
116
  }) => string;
155
117
  declare const computeSchemaFingerprint: (schema: DatabaseSchema) => string;
156
118
 
157
- /**
158
- * Lifetime = usage. Evicts unprotected entries that have not been
159
- * replayed within `maxIdleMs` (falling back to createdAt for entries
160
- * never touched). Protected entries never sweep. Run it on whatever
161
- * cadence suits the app (startup, a timer, a cron) — it is hygiene,
162
- * not a correctness requirement: entries are single-digit KB.
163
- */
164
119
  declare const sweepCache: (cache: {
165
120
  entries?: () => Promise<Array<{
166
121
  key: string;
@@ -179,16 +134,13 @@ type SeedEntry = {
179
134
  shape?: unknown;
180
135
  dsl: Query;
181
136
  mapping?: unknown;
182
- /** The reach this read requires whatever the caller holds — see `OkCacheEntry.reach`. */
183
137
  reach?: string;
184
- /** When this read's answer is refreshed — see `Refresh`. Absent means 'snapshot'. */
185
138
  refresh?: Refresh;
186
139
  };
187
140
  type SeedMutation = {
188
141
  fingerprint: string;
189
142
  intent?: string;
190
143
  mutation: MutationDefinition;
191
- /** The reach this write requires whatever the caller holds — see `MutationCacheEntry.reach`. */
192
144
  reach?: string;
193
145
  };
194
146
  declare const seedCache: (cache: CacheBackend, entries: readonly (SeedEntry | SeedMutation)[]) => Promise<void>;
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
- import { MutationDefinitionSchema, lintMutation, computeSchemaFingerprint, pruneOptional, buildValidationContext, requireScope, executeQuery, QueryRequestSchema, computeRequestHash, computePolicyKey, presenceOf, presenceSignature, findMissingContext, buildContextContract, optionalKeysOf, resolveParams, canonicalHash, fireAndForget, isSetMatch, refuseOptional, canonicalText, quoteIdent, compileCompute, compileAggregate, compileJoinPairs, compileFilter, checkScope, scopeResolved, mintFingerprint, isEntryFresh, canReadTable, hashText, isTouchDue } from './chunk-IQM4SQE2.js';
2
- export { MutationDefinitionSchema, MutationSchema, QueryRequestSchema, VexScopeError, applyScope, buildContextContract, buildValidationContext, checkScope, collectMutationContext, collectQueryContext, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, executeMutation, executeQuery, executeWrites, findMissingContext, handleDiscovery, handleFingerprintDelete, handleFingerprintPatch, handleQuery, lintMutation, mintFingerprint, mutationEffect, mutationMisfits, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, requiredContextKeys, resolveParams, scopeResolved, sweepCache, tablesChangedBy } from './chunk-IQM4SQE2.js';
3
- import { VexError, QuerySchema, isIdentifier, isFieldPathShape, isVexError } from './chunk-H4BHW76Q.js';
4
- export { AggregateExpressionSchema, ComputeExpressionSchema, FilterSchema, QuerySchema, VexError } from './chunk-H4BHW76Q.js';
1
+ import { MutationDefinitionSchema, lintMutation, computeSchemaFingerprint, pruneOptional, buildValidationContext, requireScope, executeQuery, QueryRequestSchema, computeRequestHash, computePolicyKey, presenceOf, presenceSignature, findMissingContext, buildContextContract, optionalKeysOf, resolveParams, canonicalHash, fireAndForget, isSetMatch, refuseOptional, canonicalText, checkScope, scopeResolved, mintFingerprint, isEntryFresh, canReadTable, hashText, quoteIdent, compileCompute, compileAggregate, compileJoinPairs, compileFilter, isTouchDue } from './chunk-3HORTMZ7.js';
2
+ export { MutationDefinitionSchema, MutationSchema, QueryRequestSchema, VexScopeError, applyScope, buildContextContract, buildValidationContext, checkScope, collectMutationContext, collectQueryContext, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, executeMutation, executeQuery, executeWrites, findMissingContext, handleDiscovery, handleFingerprintDelete, handleFingerprintPatch, handleQuery, lintMutation, mintFingerprint, mutationEffect, mutationMisfits, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, requiredContextKeys, resolveParams, scopeResolved, sweepCache, tablesChangedBy } from './chunk-3HORTMZ7.js';
3
+ import { VexError, QuerySchema, isIdentifier, isFieldPathShape, isVexError } from './chunk-J7JYKCUA.js';
4
+ export { AggregateExpressionSchema, ComputeExpressionSchema, FilterSchema, QuerySchema, VexError } from './chunk-J7JYKCUA.js';
5
5
  import { z } from 'zod';
6
6
  import { exceedsDepth, depthRefusal } from '@niscorp/strata';
7
7
  import { compile, execute } from '@niscorp/prism';
@@ -1766,7 +1766,14 @@ var mapIndexType = (pgType) => {
1766
1766
  // src/adapters/postgres/compile.ts
1767
1767
  var compileQuery = (resolved) => {
1768
1768
  const paramSlots = [];
1769
- const paramCounter = { value: 0 };
1769
+ const sql = compileLevel(resolved, paramSlots, { value: 0 });
1770
+ const contextContract = {};
1771
+ for (const slot of paramSlots) {
1772
+ contextContract[slot.key] = { type: slot.type, kind: slot.kind };
1773
+ }
1774
+ return { sql, paramSlots, contextContract };
1775
+ };
1776
+ var compileLevel = (resolved, paramSlots, paramCounter) => {
1770
1777
  const ctx = {
1771
1778
  resolvedPaths: resolved.filter?.resolvedPaths ?? /* @__PURE__ */ new Map(),
1772
1779
  aliasMap: resolved.aliasMap,
@@ -1790,15 +1797,7 @@ var compileQuery = (resolved) => {
1790
1797
  const expr = compileAggregate(a.expression, ctx);
1791
1798
  return `${expr} AS ${quoteIdent(a.name)}`;
1792
1799
  });
1793
- const semanticColumns = [];
1794
- if (resolved.semantic !== void 0) {
1795
- const col = `${resolved.semantic.field.alias}.${resolved.semantic.field.column}`;
1796
- const semanticParamIndex = findSemanticParamIndex(paramSlots);
1797
- if (semanticParamIndex !== void 0) {
1798
- semanticColumns.push(`1 - (${col} <=> $${semanticParamIndex}) AS "$score"`);
1799
- }
1800
- }
1801
- const allColumns = [...fieldColumns, ...computeColumns, ...aggregateColumns, ...semanticColumns];
1800
+ const allColumns = [...fieldColumns, ...computeColumns, ...aggregateColumns];
1802
1801
  if (selectParts.length > 0) {
1803
1802
  sqlParts.push(`SELECT ${selectParts.join(" ")} ${allColumns.join(", ")}`);
1804
1803
  } else {
@@ -1807,9 +1806,7 @@ var compileQuery = (resolved) => {
1807
1806
  const firstSource = resolved.sources[0];
1808
1807
  if (firstSource !== void 0) {
1809
1808
  if (firstSource.subquery !== void 0) {
1810
- const subSql = compileQuery(firstSource.subquery);
1811
- mergeSubqueryParams(subSql, paramSlots, paramCounter);
1812
- sqlParts.push(`FROM (${subSql.sql}) AS ${firstSource.alias}`);
1809
+ sqlParts.push(`FROM (${compileLevel(firstSource.subquery, paramSlots, paramCounter)}) AS ${firstSource.alias}`);
1813
1810
  } else if (firstSource.table !== void 0) {
1814
1811
  sqlParts.push(`FROM ${firstSource.table} AS ${firstSource.alias}`);
1815
1812
  }
@@ -1824,9 +1821,7 @@ var compileQuery = (resolved) => {
1824
1821
  ];
1825
1822
  const on = conditions.join(" AND ");
1826
1823
  if (joinSource.subquery !== void 0) {
1827
- const subSql = compileQuery(joinSource.subquery);
1828
- mergeSubqueryParams(subSql, paramSlots, paramCounter);
1829
- sqlParts.push(`${keyword} (${subSql.sql}) AS ${join.toAlias} ON ${on}`);
1824
+ sqlParts.push(`${keyword} (${compileLevel(joinSource.subquery, paramSlots, paramCounter)}) AS ${join.toAlias} ON ${on}`);
1830
1825
  } else {
1831
1826
  sqlParts.push(`${keyword} ${join.toTable} AS ${join.toAlias} ON ${on}`);
1832
1827
  }
@@ -1836,9 +1831,7 @@ var compileQuery = (resolved) => {
1836
1831
  for (const source of resolved.sources) {
1837
1832
  if (source.alias === firstSource?.alias || joinedAliases.has(source.alias)) continue;
1838
1833
  if (source.subquery !== void 0) {
1839
- const subSql = compileQuery(source.subquery);
1840
- mergeSubqueryParams(subSql, paramSlots, paramCounter);
1841
- sqlParts.push(`CROSS JOIN (${subSql.sql}) AS ${source.alias}`);
1834
+ sqlParts.push(`CROSS JOIN (${compileLevel(source.subquery, paramSlots, paramCounter)}) AS ${source.alias}`);
1842
1835
  } else if (source.table !== void 0) {
1843
1836
  sqlParts.push(`CROSS JOIN ${source.table} AS ${source.alias}`);
1844
1837
  }
@@ -1860,11 +1853,9 @@ var compileQuery = (resolved) => {
1860
1853
  });
1861
1854
  sqlParts.push(`ORDER BY ${orderByParts.join(", ")}`);
1862
1855
  } else if (resolved.semantic !== void 0) {
1863
- const semanticIdx = findSemanticParamIndex(paramSlots);
1864
- if (semanticIdx !== void 0) {
1865
- const col = `${resolved.semantic.field.alias}.${resolved.semantic.field.column}`;
1866
- sqlParts.push(`ORDER BY ${col} <=> $${semanticIdx} ASC`);
1867
- }
1856
+ const { field, contextPath } = resolved.semantic;
1857
+ const position = paramSlots.findIndex((slot) => slot.kind === "semantic" && slot.key === contextPath) + 1;
1858
+ if (position > 0) sqlParts.push(`ORDER BY ${field.alias}.${field.column} <=> $${position} ASC`);
1868
1859
  }
1869
1860
  if (resolved.limit !== void 0) {
1870
1861
  if (!Number.isInteger(resolved.limit) || resolved.limit < 1) {
@@ -1872,30 +1863,7 @@ var compileQuery = (resolved) => {
1872
1863
  }
1873
1864
  sqlParts.push(`LIMIT ${resolved.limit}`);
1874
1865
  }
1875
- const contextContract = {};
1876
- for (const slot of paramSlots) {
1877
- contextContract[slot.key] = { type: slot.type, kind: slot.kind };
1878
- }
1879
- return {
1880
- sql: sqlParts.join(" "),
1881
- paramSlots,
1882
- contextContract
1883
- };
1884
- };
1885
- var findSemanticParamIndex = (slots) => {
1886
- for (let i = 0; i < slots.length; i++) {
1887
- const slot = slots[i];
1888
- if (slot !== void 0 && slot.kind === "semantic") {
1889
- return i + 1;
1890
- }
1891
- }
1892
- return void 0;
1893
- };
1894
- var mergeSubqueryParams = (subCompiled, parentSlots, parentCounter) => {
1895
- for (const slot of subCompiled.paramSlots) {
1896
- parentCounter.value += 1;
1897
- parentSlots.push(slot);
1898
- }
1866
+ return sqlParts.join(" ");
1899
1867
  };
1900
1868
 
1901
1869
  // src/adapters/postgres/statement-timeout.ts
@@ -1945,7 +1913,7 @@ var createPostgresAdapter = (config) => {
1945
1913
  const capabilities = {
1946
1914
  vectorSearch: true,
1947
1915
  fuzzyMatch: false,
1948
- // Requires pg_trgm extension, not guaranteed
1916
+ // needs the pg_trgm extension, which may not be installed
1949
1917
  jsonFields: true,
1950
1918
  fullTextSearch: true,
1951
1919
  returningClause: true,
@@ -2084,13 +2052,7 @@ var rowToEntry = (row) => {
2084
2052
  kind: "ok",
2085
2053
  dsl: row["dsl"],
2086
2054
  ...row["prism_ir"] != null ? { prismIr: row["prism_ir"] } : {},
2087
- // A DECLARED REACH IS PART OF THE ENTRY, so it has to survive the round
2088
- // trip. Dropping it here would not fail loudly — the read would simply be
2089
- // served at the caller's own, wider reach, which is the exact thing the
2090
- // field exists to prevent.
2091
2055
  ...row["reach"] != null ? { reach: row["reach"] } : {},
2092
- // So must the refresh mode: dropped, a reactive read would quietly answer
2093
- // once and never again.
2094
2056
  ...isRefresh(row["refresh"]) ? { refresh: row["refresh"] } : {},
2095
2057
  ...meta
2096
2058
  };