@niscorp/vex 0.1.0
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/DESIGN.md +881 -0
- package/DOCS.md +1295 -0
- package/LICENSE +202 -0
- package/README.md +97 -0
- package/dist/adapters/express/index.cjs +1406 -0
- package/dist/adapters/express/index.cjs.map +1 -0
- package/dist/adapters/express/index.d.cts +25 -0
- package/dist/adapters/express/index.d.ts +25 -0
- package/dist/adapters/express/index.js +60 -0
- package/dist/adapters/express/index.js.map +1 -0
- package/dist/adapters/hono/index.cjs +1426 -0
- package/dist/adapters/hono/index.cjs.map +1 -0
- package/dist/adapters/hono/index.d.cts +25 -0
- package/dist/adapters/hono/index.d.ts +25 -0
- package/dist/adapters/hono/index.js +78 -0
- package/dist/adapters/hono/index.js.map +1 -0
- package/dist/adapters/pglite/index.cjs +17 -0
- package/dist/adapters/pglite/index.cjs.map +1 -0
- package/dist/adapters/pglite/index.d.cts +21 -0
- package/dist/adapters/pglite/index.d.ts +21 -0
- package/dist/adapters/pglite/index.js +14 -0
- package/dist/adapters/pglite/index.js.map +1 -0
- package/dist/agent/index.cjs +478 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +29 -0
- package/dist/agent/index.d.ts +29 -0
- package/dist/agent/index.js +313 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/chunk-FPKW4TRX.js +1528 -0
- package/dist/chunk-FPKW4TRX.js.map +1 -0
- package/dist/chunk-HF25Q53I.js +165 -0
- package/dist/chunk-HF25Q53I.js.map +1 -0
- package/dist/handler-Cql8SJ3F.d.cts +133 -0
- package/dist/handler-mICf9ins.d.ts +133 -0
- package/dist/index.cjs +4078 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +199 -0
- package/dist/index.d.ts +199 -0
- package/dist/index.js +2340 -0
- package/dist/index.js.map +1 -0
- package/dist/introspect-D3OaXHBc.d.cts +16 -0
- package/dist/introspect-D3OaXHBc.d.ts +16 -0
- package/dist/types-BRvMB6IM.d.cts +1491 -0
- package/dist/types-BRvMB6IM.d.ts +1491 -0
- package/package.json +125 -0
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
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-BRvMB6IM.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 SCOPE_VERBS, ac as ScopeBehaviors, ad as ScopeBinding, ae as ScopeEntityRule, af as ScopeMatch, ag as ScopeRef, ah as ScopeRule, ai as ScopeRules, aj as ScopeSet, ak as ScopeValues, al as SortEntry, am as Source, an as TestResult, ao as UnsatisfiableCacheEntry, ap as VexEvent, aq as VexEventHandler, ar as createScopePolicy, as as isRefresh, at as mergeScopePolicies, au as scopeBindings, av as scopeGrants, aw as scopeProfiles } from './types-BRvMB6IM.cjs';
|
|
3
|
+
import { P as PgPool } from './introspect-D3OaXHBc.cjs';
|
|
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 requiredContextKeys, t as tablesChangedBy } from './handler-Cql8SJ3F.cjs';
|
|
6
|
+
import 'zod';
|
|
7
|
+
import '@niscorp/prism';
|
|
8
|
+
|
|
9
|
+
declare const createQueryEngine: (engineConfig: QueryEngineConfig) => QueryEngine;
|
|
10
|
+
|
|
11
|
+
declare const resolve: (dsl: Query, schema: DatabaseSchema) => ResolvedQuery;
|
|
12
|
+
|
|
13
|
+
declare const analyze: (resolved: ResolvedQuery, config: AnalysisConfig) => AnalysisResult;
|
|
14
|
+
|
|
15
|
+
declare const executeQuery: (compiled: CompiledQuery, context: Record<string, unknown>, scope: Record<string, unknown>, adapter: DatabaseAdapter, embed?: (text: string, dimensions?: number) => Promise<number[]>) => Promise<Row[]>;
|
|
16
|
+
declare const buildContextContract: (compiled: CompiledQuery, optionalKeys?: readonly string[]) => Record<string, ContextMeta>;
|
|
17
|
+
declare const findMissingContext: (compiled: CompiledQuery, context: Record<string, unknown>) => string[];
|
|
18
|
+
|
|
19
|
+
/** Every optional key mentioned anywhere in a query, in declaration order. */
|
|
20
|
+
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. */
|
|
44
|
+
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". */
|
|
51
|
+
declare const pruneOptional: (dsl: Query, present: ReadonlySet<string> | "all") => Query;
|
|
52
|
+
|
|
53
|
+
type PostgresAdapterConfig = {
|
|
54
|
+
pool: PgPool;
|
|
55
|
+
schema?: string;
|
|
56
|
+
exclude?: string[];
|
|
57
|
+
};
|
|
58
|
+
declare const createPostgresAdapter: (config: PostgresAdapterConfig) => DatabaseAdapter;
|
|
59
|
+
|
|
60
|
+
type PathResolution = {
|
|
61
|
+
alias: string;
|
|
62
|
+
column: string;
|
|
63
|
+
schema: FieldSchema;
|
|
64
|
+
};
|
|
65
|
+
type CompilationContext = {
|
|
66
|
+
resolvedPaths: Map<string, PathResolution>;
|
|
67
|
+
aliasMap: Map<string, string>;
|
|
68
|
+
paramSlots: ParamSlot[];
|
|
69
|
+
paramCounter: {
|
|
70
|
+
value: number;
|
|
71
|
+
};
|
|
72
|
+
existsMap?: Map<object, ResolvedExists>;
|
|
73
|
+
};
|
|
74
|
+
declare const compileFieldOrValue: (fov: FieldOrValue, ctx: CompilationContext) => string;
|
|
75
|
+
declare const compileFilter: (filter: Filter, ctx: CompilationContext) => string;
|
|
76
|
+
|
|
77
|
+
declare const vexGuide: () => string;
|
|
78
|
+
|
|
79
|
+
declare const discoverEntities: (dsl: Query) => Set<string>;
|
|
80
|
+
|
|
81
|
+
declare class VexError extends Error {
|
|
82
|
+
readonly code: QueryErrorCode;
|
|
83
|
+
readonly details?: Record<string, unknown>;
|
|
84
|
+
constructor(code: QueryErrorCode, message: string, details?: Record<string, unknown>);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
declare class VexScopeError extends VexError {
|
|
88
|
+
readonly entity: string;
|
|
89
|
+
constructor(entity: string, message: string);
|
|
90
|
+
}
|
|
91
|
+
declare const checkScope: (entities: Set<string>, policy: ScopePolicy) => void;
|
|
92
|
+
declare const scopeResolved: (resolved: ResolvedQuery, policy: ScopePolicy) => ResolvedQuery;
|
|
93
|
+
declare const applyScope: (dsl: Query, entities: Set<string>, policy: ScopePolicy) => Query;
|
|
94
|
+
|
|
95
|
+
declare const createMemoryCache: () => CacheBackend;
|
|
96
|
+
|
|
97
|
+
type PostgresCacheConfig = {
|
|
98
|
+
/** A pg Pool (or anything matching its query shape). The caller owns its lifecycle. */
|
|
99
|
+
pool: PgPool;
|
|
100
|
+
/** Schema to place the cache table in. Default: 'public'. */
|
|
101
|
+
schema?: string;
|
|
102
|
+
/** Table name. Default: 'vex_cache'. */
|
|
103
|
+
table?: string;
|
|
104
|
+
/** Called on rejected writes and evicted-on-read invalid rows. */
|
|
105
|
+
onError?: (err: unknown) => void;
|
|
106
|
+
};
|
|
107
|
+
type PostgresCache = CacheBackend & {
|
|
108
|
+
init: () => Promise<void>;
|
|
109
|
+
sequence: Sequence;
|
|
110
|
+
entries: () => Promise<Array<{
|
|
111
|
+
key: string;
|
|
112
|
+
entry: CacheEntry;
|
|
113
|
+
}>>;
|
|
114
|
+
};
|
|
115
|
+
declare const createPostgresCache: (config: PostgresCacheConfig) => PostgresCache;
|
|
116
|
+
|
|
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
|
+
| {
|
|
124
|
+
mode: 'partial';
|
|
125
|
+
fingerprints: string[];
|
|
126
|
+
};
|
|
127
|
+
type TieredCacheConfig = {
|
|
128
|
+
/** Fast, volatile tier (e.g. createMemoryCache()). */
|
|
129
|
+
l1: CacheBackend;
|
|
130
|
+
/** Durable source of truth (e.g. createPostgresCache(...)). */
|
|
131
|
+
l2: CacheBackend;
|
|
132
|
+
/** Warm-up strategy run by init(). Default: 'full'. */
|
|
133
|
+
warmup?: WarmupMode;
|
|
134
|
+
/** Called on background failures (async L2 writes) and dropped invalid entries. */
|
|
135
|
+
onError?: (err: unknown) => void;
|
|
136
|
+
};
|
|
137
|
+
type TieredCache = CacheBackend & {
|
|
138
|
+
init: () => Promise<void>;
|
|
139
|
+
};
|
|
140
|
+
declare const createTieredCache: (config: TieredCacheConfig) => TieredCache;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Returns `null` if the entry is valid, or a human-readable reason
|
|
144
|
+
* string if it is not.
|
|
145
|
+
*/
|
|
146
|
+
declare const validateEntry: (entry: CacheEntry) => string | null;
|
|
147
|
+
|
|
148
|
+
declare const normalizeShape: (shape: unknown) => unknown;
|
|
149
|
+
declare const mintFingerprint: () => string;
|
|
150
|
+
declare const computeRequestHash: (request: {
|
|
151
|
+
intent?: string;
|
|
152
|
+
shape?: unknown;
|
|
153
|
+
context?: Record<string, unknown>;
|
|
154
|
+
}) => string;
|
|
155
|
+
declare const computeSchemaFingerprint: (schema: DatabaseSchema) => string;
|
|
156
|
+
|
|
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
|
+
declare const sweepCache: (cache: {
|
|
165
|
+
entries?: () => Promise<Array<{
|
|
166
|
+
key: string;
|
|
167
|
+
entry: CacheEntry;
|
|
168
|
+
}>>;
|
|
169
|
+
keys: () => Promise<string[]>;
|
|
170
|
+
get: (key: string) => Promise<CacheEntry | undefined>;
|
|
171
|
+
delete: (key: string) => Promise<void>;
|
|
172
|
+
}, options: {
|
|
173
|
+
maxIdleMs: number;
|
|
174
|
+
}) => Promise<number>;
|
|
175
|
+
|
|
176
|
+
type SeedEntry = {
|
|
177
|
+
fingerprint: string;
|
|
178
|
+
intent?: string;
|
|
179
|
+
shape?: unknown;
|
|
180
|
+
dsl: Query;
|
|
181
|
+
mapping?: unknown;
|
|
182
|
+
/** The reach this read requires whatever the caller holds — see `OkCacheEntry.reach`. */
|
|
183
|
+
reach?: string;
|
|
184
|
+
/** When this read's answer is refreshed — see `Refresh`. Absent means 'snapshot'. */
|
|
185
|
+
refresh?: Refresh;
|
|
186
|
+
};
|
|
187
|
+
type SeedMutation = {
|
|
188
|
+
fingerprint: string;
|
|
189
|
+
intent?: string;
|
|
190
|
+
mutation: MutationDefinition;
|
|
191
|
+
/** The reach this write requires whatever the caller holds — see `MutationCacheEntry.reach`. */
|
|
192
|
+
reach?: string;
|
|
193
|
+
};
|
|
194
|
+
declare const seedCache: (cache: CacheBackend, entries: readonly (SeedEntry | SeedMutation)[]) => Promise<void>;
|
|
195
|
+
|
|
196
|
+
declare const buildValidationContext: (contract: ContextContract) => Record<string, unknown>;
|
|
197
|
+
declare const resolveParams: (slots: ParamSlot[], context: Record<string, unknown>, scope: Record<string, unknown>, embed?: (text: string, dimensions?: number) => Promise<number[]>) => Promise<unknown[]>;
|
|
198
|
+
|
|
199
|
+
export { AnalysisConfig, AnalysisResult, CacheBackend, CacheEntry, type CompilationContext, CompiledQuery, ContextMeta, DatabaseAdapter, DatabaseSchema, FieldOrValue, FieldSchema, Filter, MutationDefinition, ParamSlot, PgPool, type PostgresAdapterConfig, type PostgresCache, type PostgresCacheConfig, Query, QueryEngine, QueryEngineConfig, QueryErrorCode, Refresh, ResolvedQuery, Row, ScopePolicy, type SeedEntry, type SeedMutation, type TieredCache, type TieredCacheConfig, VexError, VexScopeError, type WarmupMode, analyze, applyScope, buildContextContract, buildValidationContext, checkScope, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, createMemoryCache, createPostgresAdapter, createPostgresCache, createQueryEngine, createTieredCache, discoverEntities, executeQuery, findMissingContext, mintFingerprint, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, resolve, resolveParams, scopeResolved, seedCache, sweepCache, validateEntry, vexGuide };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
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-BRvMB6IM.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 SCOPE_VERBS, ac as ScopeBehaviors, ad as ScopeBinding, ae as ScopeEntityRule, af as ScopeMatch, ag as ScopeRef, ah as ScopeRule, ai as ScopeRules, aj as ScopeSet, ak as ScopeValues, al as SortEntry, am as Source, an as TestResult, ao as UnsatisfiableCacheEntry, ap as VexEvent, aq as VexEventHandler, ar as createScopePolicy, as as isRefresh, at as mergeScopePolicies, au as scopeBindings, av as scopeGrants, aw as scopeProfiles } from './types-BRvMB6IM.js';
|
|
3
|
+
import { P as PgPool } from './introspect-D3OaXHBc.js';
|
|
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 requiredContextKeys, t as tablesChangedBy } from './handler-mICf9ins.js';
|
|
6
|
+
import 'zod';
|
|
7
|
+
import '@niscorp/prism';
|
|
8
|
+
|
|
9
|
+
declare const createQueryEngine: (engineConfig: QueryEngineConfig) => QueryEngine;
|
|
10
|
+
|
|
11
|
+
declare const resolve: (dsl: Query, schema: DatabaseSchema) => ResolvedQuery;
|
|
12
|
+
|
|
13
|
+
declare const analyze: (resolved: ResolvedQuery, config: AnalysisConfig) => AnalysisResult;
|
|
14
|
+
|
|
15
|
+
declare const executeQuery: (compiled: CompiledQuery, context: Record<string, unknown>, scope: Record<string, unknown>, adapter: DatabaseAdapter, embed?: (text: string, dimensions?: number) => Promise<number[]>) => Promise<Row[]>;
|
|
16
|
+
declare const buildContextContract: (compiled: CompiledQuery, optionalKeys?: readonly string[]) => Record<string, ContextMeta>;
|
|
17
|
+
declare const findMissingContext: (compiled: CompiledQuery, context: Record<string, unknown>) => string[];
|
|
18
|
+
|
|
19
|
+
/** Every optional key mentioned anywhere in a query, in declaration order. */
|
|
20
|
+
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. */
|
|
44
|
+
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". */
|
|
51
|
+
declare const pruneOptional: (dsl: Query, present: ReadonlySet<string> | "all") => Query;
|
|
52
|
+
|
|
53
|
+
type PostgresAdapterConfig = {
|
|
54
|
+
pool: PgPool;
|
|
55
|
+
schema?: string;
|
|
56
|
+
exclude?: string[];
|
|
57
|
+
};
|
|
58
|
+
declare const createPostgresAdapter: (config: PostgresAdapterConfig) => DatabaseAdapter;
|
|
59
|
+
|
|
60
|
+
type PathResolution = {
|
|
61
|
+
alias: string;
|
|
62
|
+
column: string;
|
|
63
|
+
schema: FieldSchema;
|
|
64
|
+
};
|
|
65
|
+
type CompilationContext = {
|
|
66
|
+
resolvedPaths: Map<string, PathResolution>;
|
|
67
|
+
aliasMap: Map<string, string>;
|
|
68
|
+
paramSlots: ParamSlot[];
|
|
69
|
+
paramCounter: {
|
|
70
|
+
value: number;
|
|
71
|
+
};
|
|
72
|
+
existsMap?: Map<object, ResolvedExists>;
|
|
73
|
+
};
|
|
74
|
+
declare const compileFieldOrValue: (fov: FieldOrValue, ctx: CompilationContext) => string;
|
|
75
|
+
declare const compileFilter: (filter: Filter, ctx: CompilationContext) => string;
|
|
76
|
+
|
|
77
|
+
declare const vexGuide: () => string;
|
|
78
|
+
|
|
79
|
+
declare const discoverEntities: (dsl: Query) => Set<string>;
|
|
80
|
+
|
|
81
|
+
declare class VexError extends Error {
|
|
82
|
+
readonly code: QueryErrorCode;
|
|
83
|
+
readonly details?: Record<string, unknown>;
|
|
84
|
+
constructor(code: QueryErrorCode, message: string, details?: Record<string, unknown>);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
declare class VexScopeError extends VexError {
|
|
88
|
+
readonly entity: string;
|
|
89
|
+
constructor(entity: string, message: string);
|
|
90
|
+
}
|
|
91
|
+
declare const checkScope: (entities: Set<string>, policy: ScopePolicy) => void;
|
|
92
|
+
declare const scopeResolved: (resolved: ResolvedQuery, policy: ScopePolicy) => ResolvedQuery;
|
|
93
|
+
declare const applyScope: (dsl: Query, entities: Set<string>, policy: ScopePolicy) => Query;
|
|
94
|
+
|
|
95
|
+
declare const createMemoryCache: () => CacheBackend;
|
|
96
|
+
|
|
97
|
+
type PostgresCacheConfig = {
|
|
98
|
+
/** A pg Pool (or anything matching its query shape). The caller owns its lifecycle. */
|
|
99
|
+
pool: PgPool;
|
|
100
|
+
/** Schema to place the cache table in. Default: 'public'. */
|
|
101
|
+
schema?: string;
|
|
102
|
+
/** Table name. Default: 'vex_cache'. */
|
|
103
|
+
table?: string;
|
|
104
|
+
/** Called on rejected writes and evicted-on-read invalid rows. */
|
|
105
|
+
onError?: (err: unknown) => void;
|
|
106
|
+
};
|
|
107
|
+
type PostgresCache = CacheBackend & {
|
|
108
|
+
init: () => Promise<void>;
|
|
109
|
+
sequence: Sequence;
|
|
110
|
+
entries: () => Promise<Array<{
|
|
111
|
+
key: string;
|
|
112
|
+
entry: CacheEntry;
|
|
113
|
+
}>>;
|
|
114
|
+
};
|
|
115
|
+
declare const createPostgresCache: (config: PostgresCacheConfig) => PostgresCache;
|
|
116
|
+
|
|
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
|
+
| {
|
|
124
|
+
mode: 'partial';
|
|
125
|
+
fingerprints: string[];
|
|
126
|
+
};
|
|
127
|
+
type TieredCacheConfig = {
|
|
128
|
+
/** Fast, volatile tier (e.g. createMemoryCache()). */
|
|
129
|
+
l1: CacheBackend;
|
|
130
|
+
/** Durable source of truth (e.g. createPostgresCache(...)). */
|
|
131
|
+
l2: CacheBackend;
|
|
132
|
+
/** Warm-up strategy run by init(). Default: 'full'. */
|
|
133
|
+
warmup?: WarmupMode;
|
|
134
|
+
/** Called on background failures (async L2 writes) and dropped invalid entries. */
|
|
135
|
+
onError?: (err: unknown) => void;
|
|
136
|
+
};
|
|
137
|
+
type TieredCache = CacheBackend & {
|
|
138
|
+
init: () => Promise<void>;
|
|
139
|
+
};
|
|
140
|
+
declare const createTieredCache: (config: TieredCacheConfig) => TieredCache;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Returns `null` if the entry is valid, or a human-readable reason
|
|
144
|
+
* string if it is not.
|
|
145
|
+
*/
|
|
146
|
+
declare const validateEntry: (entry: CacheEntry) => string | null;
|
|
147
|
+
|
|
148
|
+
declare const normalizeShape: (shape: unknown) => unknown;
|
|
149
|
+
declare const mintFingerprint: () => string;
|
|
150
|
+
declare const computeRequestHash: (request: {
|
|
151
|
+
intent?: string;
|
|
152
|
+
shape?: unknown;
|
|
153
|
+
context?: Record<string, unknown>;
|
|
154
|
+
}) => string;
|
|
155
|
+
declare const computeSchemaFingerprint: (schema: DatabaseSchema) => string;
|
|
156
|
+
|
|
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
|
+
declare const sweepCache: (cache: {
|
|
165
|
+
entries?: () => Promise<Array<{
|
|
166
|
+
key: string;
|
|
167
|
+
entry: CacheEntry;
|
|
168
|
+
}>>;
|
|
169
|
+
keys: () => Promise<string[]>;
|
|
170
|
+
get: (key: string) => Promise<CacheEntry | undefined>;
|
|
171
|
+
delete: (key: string) => Promise<void>;
|
|
172
|
+
}, options: {
|
|
173
|
+
maxIdleMs: number;
|
|
174
|
+
}) => Promise<number>;
|
|
175
|
+
|
|
176
|
+
type SeedEntry = {
|
|
177
|
+
fingerprint: string;
|
|
178
|
+
intent?: string;
|
|
179
|
+
shape?: unknown;
|
|
180
|
+
dsl: Query;
|
|
181
|
+
mapping?: unknown;
|
|
182
|
+
/** The reach this read requires whatever the caller holds — see `OkCacheEntry.reach`. */
|
|
183
|
+
reach?: string;
|
|
184
|
+
/** When this read's answer is refreshed — see `Refresh`. Absent means 'snapshot'. */
|
|
185
|
+
refresh?: Refresh;
|
|
186
|
+
};
|
|
187
|
+
type SeedMutation = {
|
|
188
|
+
fingerprint: string;
|
|
189
|
+
intent?: string;
|
|
190
|
+
mutation: MutationDefinition;
|
|
191
|
+
/** The reach this write requires whatever the caller holds — see `MutationCacheEntry.reach`. */
|
|
192
|
+
reach?: string;
|
|
193
|
+
};
|
|
194
|
+
declare const seedCache: (cache: CacheBackend, entries: readonly (SeedEntry | SeedMutation)[]) => Promise<void>;
|
|
195
|
+
|
|
196
|
+
declare const buildValidationContext: (contract: ContextContract) => Record<string, unknown>;
|
|
197
|
+
declare const resolveParams: (slots: ParamSlot[], context: Record<string, unknown>, scope: Record<string, unknown>, embed?: (text: string, dimensions?: number) => Promise<number[]>) => Promise<unknown[]>;
|
|
198
|
+
|
|
199
|
+
export { AnalysisConfig, AnalysisResult, CacheBackend, CacheEntry, type CompilationContext, CompiledQuery, ContextMeta, DatabaseAdapter, DatabaseSchema, FieldOrValue, FieldSchema, Filter, MutationDefinition, ParamSlot, PgPool, type PostgresAdapterConfig, type PostgresCache, type PostgresCacheConfig, Query, QueryEngine, QueryEngineConfig, QueryErrorCode, Refresh, ResolvedQuery, Row, ScopePolicy, type SeedEntry, type SeedMutation, type TieredCache, type TieredCacheConfig, VexError, VexScopeError, type WarmupMode, analyze, applyScope, buildContextContract, buildValidationContext, checkScope, compileFieldOrValue, compileFilter, computeRequestHash, computeSchemaFingerprint, createMemoryCache, createPostgresAdapter, createPostgresCache, createQueryEngine, createTieredCache, discoverEntities, executeQuery, findMissingContext, mintFingerprint, normalizeShape, optionalKeysOf, presenceOf, pruneOptional, resolve, resolveParams, scopeResolved, seedCache, sweepCache, validateEntry, vexGuide };
|