@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.
- package/CHANGELOG.md +79 -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
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-
|
|
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-
|
|
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-
|
|
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
|
-
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
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
|
-
/**
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
-
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
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
|
-
/**
|
|
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,
|
|
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-
|
|
3
|
-
import { VexError, QuerySchema, isIdentifier, isFieldPathShape, isVexError } from './chunk-
|
|
4
|
-
export { AggregateExpressionSchema, ComputeExpressionSchema, FilterSchema, QuerySchema, VexError } from './chunk-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1864
|
-
|
|
1865
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
};
|