@askdb/core 1.0.0-beta.41 → 1.0.0-beta.43
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/README.md +44 -4
- package/dist/ask.d.ts +129 -2
- package/dist/ask.d.ts.map +1 -1
- package/dist/ask.js +391 -15
- package/dist/ask.js.map +1 -1
- package/dist/errors.d.ts +87 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +29 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +8 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -2
- package/dist/index.js.map +1 -1
- package/dist/logging/log-events.d.ts +13 -0
- package/dist/logging/log-events.d.ts.map +1 -1
- package/dist/logging/log-events.js +13 -0
- package/dist/logging/log-events.js.map +1 -1
- package/dist/schema/v2/index.d.ts +1 -1
- package/dist/schema/v2/index.d.ts.map +1 -1
- package/dist/schema/v2/loader.d.ts +9 -1
- package/dist/schema/v2/loader.d.ts.map +1 -1
- package/dist/schema/v2/loader.js +171 -49
- package/dist/schema/v2/loader.js.map +1 -1
- package/dist/schema/v2/normalized.d.ts +33 -0
- package/dist/schema/v2/normalized.d.ts.map +1 -1
- package/dist/schema/v2/parser.d.ts +9 -0
- package/dist/schema/v2/parser.d.ts.map +1 -1
- package/dist/schema/v2/parser.js +18 -2
- package/dist/schema/v2/parser.js.map +1 -1
- package/dist/schema/v2/tenant-policy-loader.d.ts.map +1 -1
- package/dist/schema/v2/tenant-policy-loader.js +7 -3
- package/dist/schema/v2/tenant-policy-loader.js.map +1 -1
- package/dist/schema/v2/tenant-policy.d.ts +28 -21
- package/dist/schema/v2/tenant-policy.d.ts.map +1 -1
- package/dist/schema/v2/tenant-policy.js +67 -11
- package/dist/schema/v2/tenant-policy.js.map +1 -1
- package/dist/sql/bind.d.ts +102 -0
- package/dist/sql/bind.d.ts.map +1 -0
- package/dist/sql/bind.js +422 -0
- package/dist/sql/bind.js.map +1 -0
- package/dist/sql/dialect-spec.d.ts +24 -1
- package/dist/sql/dialect-spec.d.ts.map +1 -1
- package/dist/sql/dialect-spec.js +82 -3
- package/dist/sql/dialect-spec.js.map +1 -1
- package/dist/sql/extract-sql.d.ts +8 -1
- package/dist/sql/extract-sql.d.ts.map +1 -1
- package/dist/sql/extract-sql.js +27 -4
- package/dist/sql/extract-sql.js.map +1 -1
- package/dist/sql/generate.d.ts +22 -0
- package/dist/sql/generate.d.ts.map +1 -1
- package/dist/sql/generate.js +92 -16
- package/dist/sql/generate.js.map +1 -1
- package/dist/sql/index.d.ts +4 -2
- package/dist/sql/index.d.ts.map +1 -1
- package/dist/sql/index.js +4 -2
- package/dist/sql/index.js.map +1 -1
- package/dist/sql/lexer.d.ts +114 -0
- package/dist/sql/lexer.d.ts.map +1 -0
- package/dist/sql/lexer.js +397 -0
- package/dist/sql/lexer.js.map +1 -0
- package/dist/sql/parameter-manifest.d.ts +34 -0
- package/dist/sql/parameter-manifest.d.ts.map +1 -0
- package/dist/sql/parameter-manifest.js +150 -0
- package/dist/sql/parameter-manifest.js.map +1 -0
- package/dist/sql/prompt.d.ts +7 -1
- package/dist/sql/prompt.d.ts.map +1 -1
- package/dist/sql/prompt.js +24 -1
- package/dist/sql/prompt.js.map +1 -1
- package/dist/sql/sensitive-guardrail.d.ts +62 -0
- package/dist/sql/sensitive-guardrail.d.ts.map +1 -0
- package/dist/sql/sensitive-guardrail.js +876 -0
- package/dist/sql/sensitive-guardrail.js.map +1 -0
- package/dist/sql/tenant-guardrail.d.ts +70 -8
- package/dist/sql/tenant-guardrail.d.ts.map +1 -1
- package/dist/sql/tenant-guardrail.js +799 -52
- package/dist/sql/tenant-guardrail.js.map +1 -1
- package/dist/sql/tenant-hierarchy.d.ts +19 -0
- package/dist/sql/tenant-hierarchy.d.ts.map +1 -0
- package/dist/sql/tenant-hierarchy.js +53 -0
- package/dist/sql/tenant-hierarchy.js.map +1 -0
- package/dist/sql/tenant-placeholders.d.ts +60 -9
- package/dist/sql/tenant-placeholders.d.ts.map +1 -1
- package/dist/sql/tenant-placeholders.js +237 -63
- package/dist/sql/tenant-placeholders.js.map +1 -1
- package/dist/sql/tenant-prompt.d.ts +4 -0
- package/dist/sql/tenant-prompt.d.ts.map +1 -1
- package/dist/sql/tenant-prompt.js +79 -11
- package/dist/sql/tenant-prompt.js.map +1 -1
- package/dist/sql/tenant-scope-validate.d.ts +3 -1
- package/dist/sql/tenant-scope-validate.d.ts.map +1 -1
- package/dist/sql/tenant-scope-validate.js +5 -2
- package/dist/sql/tenant-scope-validate.js.map +1 -1
- package/dist/sql/validate.d.ts +24 -4
- package/dist/sql/validate.d.ts.map +1 -1
- package/dist/sql/validate.js +123 -83
- package/dist/sql/validate.js.map +1 -1
- package/package.json +9 -7
- package/dist/exec/postgres.d.ts +0 -6
- package/dist/exec/postgres.d.ts.map +0 -1
- package/dist/exec/postgres.js +0 -30
- package/dist/exec/postgres.js.map +0 -1
- package/dist/modes/post-execute-log.d.ts +0 -9
- package/dist/modes/post-execute-log.d.ts.map +0 -1
- package/dist/modes/post-execute-log.js +0 -26
- package/dist/modes/post-execute-log.js.map +0 -1
package/README.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
Dialect-agnostic NL→SQL pipeline for AskDB. Provides `ask()` orchestration, schema/IR types, modes, logging, and retrieval input. Bring your own dialect adapter (e.g. `@askdb/postgres`) and your own model.
|
|
4
4
|
|
|
5
|
-
> **Status:** pre-1.0. `0.3.0` moved the Postgres dialect and `@askdb/core/postgres` to `@askdb/postgres`. Runtime AI provider construction lives in `@askdb/ai`; core remains BYO-model and does not read `process.env`. See [`docs/adrs/0002-integration-package-layout.md`](
|
|
5
|
+
> **Status:** pre-1.0. `0.3.0` moved the Postgres dialect and `@askdb/core/postgres` to `@askdb/postgres`. Runtime AI provider construction lives in `@askdb/ai`; core remains BYO-model and does not read `process.env`. See [`docs/adrs/0002-integration-package-layout.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0002-integration-package-layout.md), [`docs/adrs/0005-askdb-config-and-env-bootstrap.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0005-askdb-config-and-env-bootstrap.md), and [`docs/adrs/0006-ai-provider-integration-strategy.md`](https://github.com/Ygilany/AskDB/blob/main/docs/adrs/0006-ai-provider-integration-strategy.md).
|
|
6
|
+
|
|
7
|
+
> **Security model:** `ask()` returns SQL and never executes it. Its SQL checks (single `SELECT`/`WITH` statement (with a SQL Server caveat), no comments, no write/DDL keywords, no known side-effecting functions, and the tenant and sensitive-column checks) are heuristic defense in depth that catch common model mistakes. The read-only and sensitive-column checks use a dialect-aware lexer; the tenant check uses a simpler scanner of its own ([#342](https://github.com/Ygilany/AskDB/issues/342)). They are not a SQL parser and not a security boundary. Run generated SQL under a read-only, least-privilege database role and enforce tenant isolation in the database. See [Safety boundaries](https://askdb.tools/concepts/safety-boundaries/).
|
|
6
8
|
|
|
7
9
|
## Install
|
|
8
10
|
|
|
@@ -19,11 +21,11 @@ pnpm add @askdb/ai-openai
|
|
|
19
21
|
|
|
20
22
|
`@askdb/core` itself does not depend on `pg`. The optional `pg` peer lives on `@askdb/postgres` for live Postgres introspection.
|
|
21
23
|
|
|
22
|
-
Runtime AI configuration helpers live in `@askdb/ai` and provider adapters such as `@askdb/ai-openai`. If you use [`@askdb/config`](
|
|
24
|
+
Runtime AI configuration helpers live in `@askdb/ai` and provider adapters such as `@askdb/ai-openai`. If you use [`@askdb/config`](https://github.com/Ygilany/AskDB/blob/main/packages/config/README.md), call `bootstrapAskDbEnv()`, create an AI registry, then pass **`getAskDbRuntimeConfig().ai.aiEnv`** to `registry.createLanguageModelFromEnv(...)`.
|
|
23
25
|
|
|
24
26
|
## Schema format
|
|
25
27
|
|
|
26
|
-
`@askdb/core` uses **Schema v2** — a split artifact designed for business-context enrichment and RAG chunking. See [`docs/contracts/schema-v2.md`](
|
|
28
|
+
`@askdb/core` uses **Schema v2** — a split artifact designed for business-context enrichment and RAG chunking. See [`docs/contracts/schema-v2.md`](https://github.com/Ygilany/AskDB/blob/main/docs/contracts/schema-v2.md) for the full contract.
|
|
27
29
|
|
|
28
30
|
### Directory layout
|
|
29
31
|
|
|
@@ -61,9 +63,47 @@ const { sql } = await ask({
|
|
|
61
63
|
});
|
|
62
64
|
```
|
|
63
65
|
|
|
66
|
+
## Parameterized output (default on)
|
|
67
|
+
|
|
68
|
+
By default `ask()` also asks the model for an unbound form of the same SQL plus a small JSON parameter manifest. Every call is still **exactly one model call** — `parameterize` does not add or remove one, and nothing here lets a caller skip the model. The question is sent unchanged (values included); this is not a redaction feature.
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { ask, bindPreparedQuery, loadSchema } from "@askdb/core";
|
|
72
|
+
|
|
73
|
+
const result = await ask({
|
|
74
|
+
question: "How many cities does Colorado have?",
|
|
75
|
+
schema,
|
|
76
|
+
model: openai("gpt-4o"),
|
|
77
|
+
dialect: "postgres",
|
|
78
|
+
tenantScope,
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
// Execute either form.
|
|
82
|
+
await pool.query(result.sql); // ready to run
|
|
83
|
+
await pool.query(result.unboundSql!, result.params); // driver binding
|
|
84
|
+
|
|
85
|
+
// Render a form from result.parameters, then rebind locally — no model call.
|
|
86
|
+
const rebound = bindPreparedQuery(result.preparedQuery!, {
|
|
87
|
+
state_name: "Utah",
|
|
88
|
+
":tenant_agency_ids": authorizedAgencyIds,
|
|
89
|
+
});
|
|
90
|
+
await pool.query(rebound.sql);
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Key rules:
|
|
94
|
+
|
|
95
|
+
- `parameterize` defaults to **true**. Set `parameterize: false` when the extra output tokens are not worth it.
|
|
96
|
+
- If the model's extra blocks are missing or inconsistent, the extras are omitted and `result.sql` is unaffected. No new error reaches a caller who does not call `bindPreparedQuery()`.
|
|
97
|
+
- The model decides what to parameterize, so a mistake changes the *form*, not the query. Constrain form inputs using returned `type` and `description`.
|
|
98
|
+
- `bindPreparedQuery()` is mechanical: it checks names, types, and cardinality, and **does not authorize tenant IDs**. Authorization is the host's, exactly as when building `tenantScope`.
|
|
99
|
+
- Callers using the new fields must execute with `params`, not `tenantParams`.
|
|
100
|
+
- List parameters are arity-stable in `unboundSql` only on PostgreSQL/CockroachDB (`= ANY($n)`); elsewhere a changed list length changes the marker count — rebind through `bindPreparedQuery()` rather than swapping the array.
|
|
101
|
+
- Markers: `$N` (Postgres/CockroachDB), `?` (MySQL/MariaDB/SQLite), `@pN` (SQL Server, 0-based). Map values via `parameters[].markers` for SQL Server.
|
|
102
|
+
|
|
64
103
|
## What you get
|
|
65
104
|
|
|
66
|
-
- `ask({ question, schema, model, dialect })` — generate
|
|
105
|
+
- `ask({ question, schema, model, dialect })` — generate checked SQL (plus optional `unboundSql` / `params` / `parameters` / `preparedQuery`).
|
|
106
|
+
- `bindPreparedQuery(prepared, values)` — pure local rebind of a `PreparedQuery` (no model call).
|
|
67
107
|
- `AskDbLanguageModel` — AskDB's public name for the AI SDK language model contract.
|
|
68
108
|
- `AskDialect` — the dialect adapter contract. `@askdb/postgres` exports a ready-made one.
|
|
69
109
|
- `loadSchema(path)` — load a Schema v2 directory, bundled JSON, or `schema.json` path.
|
package/dist/ask.d.ts
CHANGED
|
@@ -7,6 +7,8 @@ import type { Retriever } from "./retrieval/types.js";
|
|
|
7
7
|
import type { TenantScope } from "./schema/v2/tenant-policy.js";
|
|
8
8
|
import { type BuiltInDialectId, type DialectSpec } from "./sql/dialect-spec.js";
|
|
9
9
|
import { type TenantSqlOutputMode, type TenantBinding } from "./sql/tenant-placeholders.js";
|
|
10
|
+
import { type SensitiveGuardrailMode, type SensitiveGuardrailResult } from "./sql/sensitive-guardrail.js";
|
|
11
|
+
import { type PreparedQuery, type QueryParameterBinding, type QueryParamSlot } from "./sql/bind.js";
|
|
10
12
|
/** Options forwarded to a dialect's generator. Stable across dialects. */
|
|
11
13
|
export type AskDialectGenerateOptions = {
|
|
12
14
|
logger?: AskDbLogger;
|
|
@@ -17,6 +19,11 @@ export type AskDialectGenerateOptions = {
|
|
|
17
19
|
prebuiltDdl?: string;
|
|
18
20
|
tenantPolicy?: import("./schema/v2/tenant-policy.js").NormalizedTenantPolicy;
|
|
19
21
|
tenantScope?: TenantScope;
|
|
22
|
+
/**
|
|
23
|
+
* When true, ask the model for unbound SQL + a parameter manifest.
|
|
24
|
+
* Inert for custom {@link AskDialect} implementations.
|
|
25
|
+
*/
|
|
26
|
+
parameterize?: boolean;
|
|
20
27
|
};
|
|
21
28
|
/** Token usage for a single `ask()` call (LLM generation only; excludes RAG embedding tokens). */
|
|
22
29
|
export type AskUsage = {
|
|
@@ -24,12 +31,20 @@ export type AskUsage = {
|
|
|
24
31
|
completionTokens: number | null;
|
|
25
32
|
totalTokens: number | null;
|
|
26
33
|
};
|
|
27
|
-
/** Output of a dialect's generator:
|
|
34
|
+
/** Output of a dialect's generator: the generated SQL plus optional dialect-specific explain metadata. */
|
|
28
35
|
export type AskDialectGenerateResult = {
|
|
29
36
|
sql: string;
|
|
30
37
|
explain?: unknown;
|
|
38
|
+
/**
|
|
39
|
+
* Optional tenant guardrail result from a custom generator. When the schema has a
|
|
40
|
+
* tenant policy, `ask()` merges its warnings into its own check of `sql` and
|
|
41
|
+
* `unboundNamedSql` (before tenant rendering); it can add failures but never replace
|
|
42
|
+
* or relax that check.
|
|
43
|
+
*/
|
|
31
44
|
tenantGuardrail?: import("./sql/tenant-guardrail.js").TenantGuardrailResult;
|
|
32
45
|
usage?: AskUsage;
|
|
46
|
+
unboundNamedSql?: string;
|
|
47
|
+
parameterManifest?: import("./sql/parameter-manifest.js").ParameterManifest;
|
|
33
48
|
};
|
|
34
49
|
/**
|
|
35
50
|
* Escape-hatch interface for fully custom NL→SQL generators (agentic flows,
|
|
@@ -39,6 +54,19 @@ export type AskDialectGenerateResult = {
|
|
|
39
54
|
* a {@link DialectSpec} to `ask({ dialect })` and let the centralized pipeline
|
|
40
55
|
* handle prompt assembly + validation. Implement `AskDialect` only when those
|
|
41
56
|
* defaults won't fit.
|
|
57
|
+
*
|
|
58
|
+
* Safety responsibilities:
|
|
59
|
+
* - **Read-only validation is yours.** `ask()` does not run the SELECT-only
|
|
60
|
+
* validator on SQL returned by a custom dialect (custom dialects may target
|
|
61
|
+
* non-SELECT statements on purpose). If your generator should only emit
|
|
62
|
+
* read-only SQL, call the exported `validateSelectSql(spec, sql)` yourself
|
|
63
|
+
* before returning.
|
|
64
|
+
* - **Tenant enforcement is not yours to skip.** When the schema has a tenant
|
|
65
|
+
* policy, `ask()` runs the tenant guardrail on the returned `sql` (and
|
|
66
|
+
* `unboundNamedSql`), with its `:tenant_<root>_ids` placeholders still in place,
|
|
67
|
+
* then substitutes them, regardless of dialect; `strict` policies throw
|
|
68
|
+
* `TenantGuardrailError`. A `tenantGuardrail` your
|
|
69
|
+
* generator returns is merged into that result, never used in place of it.
|
|
42
70
|
*/
|
|
43
71
|
export type AskDialect = {
|
|
44
72
|
generate(question: string, schema: AnyNormalizedSchema, model: AskDbLanguageModel, options?: AskDialectGenerateOptions): Promise<AskDialectGenerateResult>;
|
|
@@ -62,6 +90,28 @@ export type AskGenerateDeps = {
|
|
|
62
90
|
*/
|
|
63
91
|
providerOptions?: Record<string, unknown>;
|
|
64
92
|
};
|
|
93
|
+
/**
|
|
94
|
+
* A subtree's IDs grouped by tenant root: each key is a root table id from the
|
|
95
|
+
* tenant policy (`"table:public.clients"`), and its value holds IDs of that root's
|
|
96
|
+
* own `tenantIdColumn`, never IDs of another root.
|
|
97
|
+
*
|
|
98
|
+
* Root tables have separate ID spaces, so client `5` and agency `5` are different
|
|
99
|
+
* tenants. Keying the IDs by root lets `ask()` bind each root's IDs to that root's
|
|
100
|
+
* own `:tenant_<label>_ids` placeholder.
|
|
101
|
+
*/
|
|
102
|
+
export type TenantIdsByRoot = Readonly<Record<string, readonly string[]>>;
|
|
103
|
+
/**
|
|
104
|
+
* Host callback that expands a `subtree` tenant scope. Given the tenant root id and
|
|
105
|
+
* the seed IDs, return the subtree's IDs grouped by root ({@link TenantIdsByRoot}):
|
|
106
|
+
*
|
|
107
|
+
* - under `tenantRoot`: the seeds and any same-table descendants (e.g. child
|
|
108
|
+
* agencies through `agencies.parent_agency_id`);
|
|
109
|
+
* - under each descendant root the policy declares (`roots[].parent` or
|
|
110
|
+
* `hierarchy[]`): that root's IDs in the subtree.
|
|
111
|
+
*
|
|
112
|
+
* Pass it to `ask()` as {@link AskPipelineOptions.resolveTenantDescendants}.
|
|
113
|
+
*/
|
|
114
|
+
export type ResolveTenantDescendants = (tenantRoot: string, seedIds: readonly string[]) => Promise<TenantIdsByRoot> | TenantIdsByRoot;
|
|
65
115
|
export type AskPipelineOptions = {
|
|
66
116
|
question: string;
|
|
67
117
|
schema: AnyNormalizedSchema;
|
|
@@ -121,14 +171,91 @@ export type AskPipelineOptions = {
|
|
|
121
171
|
tenantScope?: TenantScope;
|
|
122
172
|
/**
|
|
123
173
|
* SQL output mode for tenant placeholders. Default `"sql-only"` inlines
|
|
124
|
-
* literal values
|
|
174
|
+
* escaped literal values. `"sql-params"` replaces them with the dialect's
|
|
175
|
+
* driver markers (`$N` for Postgres/CockroachDB and custom `AskDialect`s, `?`
|
|
176
|
+
* for MySQL/MariaDB/SQLite, `@pN` for SQL Server): run `sql` with
|
|
177
|
+
* `tenantParams`, or `unboundSql` with `params`.
|
|
125
178
|
*/
|
|
126
179
|
tenantSqlMode?: TenantSqlOutputMode;
|
|
180
|
+
/**
|
|
181
|
+
* Expands a `subtree` tenant scope into IDs per tenant root.
|
|
182
|
+
*
|
|
183
|
+
* Called with the tenant root id and the seed IDs from
|
|
184
|
+
* `tenantScope.access.rootIds`; returns the subtree's IDs keyed by root table id
|
|
185
|
+
* ({@link TenantIdsByRoot}). `ask()` unions the seeds into the `tenantRoot` entry
|
|
186
|
+
* and turns the result into a `multi_root` scope (an `ids` scope when only
|
|
187
|
+
* `tenantRoot` has IDs), so each root's IDs bind only to that root's placeholder.
|
|
188
|
+
* The host is the right place for this: it already knows its own hierarchy, can
|
|
189
|
+
* cache the closure, and can apply its own authorization rules.
|
|
190
|
+
*
|
|
191
|
+
* Required when `tenantScope.access.kind === "subtree"` — AskDB never opens a
|
|
192
|
+
* database connection of its own. Without it, or when it returns a flat array,
|
|
193
|
+
* a key that isn't a root in the subtree, a value that isn't an array of
|
|
194
|
+
* non-empty strings, or no IDs at all, `ask()` throws `TenantScopeError`
|
|
195
|
+
* (`SUBTREE_NOT_RESOLVABLE`) before calling the model.
|
|
196
|
+
*/
|
|
197
|
+
resolveTenantDescendants?: ResolveTenantDescendants;
|
|
198
|
+
/**
|
|
199
|
+
* Ask the model to also return the SQL in unbound form plus a JSON manifest
|
|
200
|
+
* of the values it parameterized, populating `unboundSql`, `params`,
|
|
201
|
+
* `parameters`, and `preparedQuery`. Default true. Set false to save the
|
|
202
|
+
* extra output tokens when the host does not use those fields.
|
|
203
|
+
*/
|
|
204
|
+
parameterize?: boolean;
|
|
205
|
+
/**
|
|
206
|
+
* How to treat SQL that references schema identifiers marked `sensitive`.
|
|
207
|
+
* Default `"warn"` — {@link AskPipelineResult.sensitiveGuardrail} is populated and
|
|
208
|
+
* `askdb.pipeline.sensitive_sql_warning` is logged, but `ask()` still resolves.
|
|
209
|
+
* `"strict"` throws {@link SensitiveReferenceError} instead. `"off"` skips the check.
|
|
210
|
+
*
|
|
211
|
+
* This only covers SQL produced by *this* call. Hosts that cache or replay SQL
|
|
212
|
+
* should call `validateSensitiveReferences` on every execution path.
|
|
213
|
+
*/
|
|
214
|
+
sensitiveGuardrailMode?: SensitiveGuardrailMode | "off";
|
|
127
215
|
};
|
|
128
216
|
export type AskPipelineResult = {
|
|
217
|
+
/**
|
|
218
|
+
* The model's bound SQL: business values inlined as literals. Tenant IDs are
|
|
219
|
+
* inlined literals (`tenantSqlMode: "sql-only"`) or driver markers numbered from
|
|
220
|
+
* the first slot (`"sql-params"`) — then execute it with `tenantParams`.
|
|
221
|
+
*/
|
|
129
222
|
sql: string;
|
|
223
|
+
/**
|
|
224
|
+
* Driver markers for every value (business and, in `"sql-params"` mode, tenant).
|
|
225
|
+
* Execute with `params` — never with `tenantParams`.
|
|
226
|
+
*/
|
|
227
|
+
unboundSql?: string;
|
|
228
|
+
/**
|
|
229
|
+
* Values for `unboundSql`, in driver-marker order (array slots on
|
|
230
|
+
* Postgres/CockroachDB listBinding). In `"sql-params"` mode this already
|
|
231
|
+
* includes the tenant values — for `?` dialects interleaved in source order,
|
|
232
|
+
* otherwise after the business values. Do not concatenate `tenantParams`.
|
|
233
|
+
*/
|
|
234
|
+
params?: QueryParamSlot[];
|
|
235
|
+
/** Named bindings for form UIs (includes runtime values). */
|
|
236
|
+
parameters?: QueryParameterBinding[];
|
|
237
|
+
/** Definitions + template only — no runtime values. */
|
|
238
|
+
preparedQuery?: PreparedQuery;
|
|
130
239
|
explain?: unknown;
|
|
240
|
+
/**
|
|
241
|
+
* Sensitive-identifier guardrail result for `sql`. Present when the schema declares
|
|
242
|
+
* at least one `sensitive` table/column and `sensitiveGuardrailMode` is not `"off"`.
|
|
243
|
+
*/
|
|
244
|
+
sensitiveGuardrail?: SensitiveGuardrailResult;
|
|
245
|
+
/**
|
|
246
|
+
* Tenant guardrail result for the model's SQL, checked before tenant rendering: the
|
|
247
|
+
* bound `sql` and its `sql-unbound` block, with the `:tenant_<root>_ids` placeholders
|
|
248
|
+
* still in place. `sql` and `unboundSql` differ from those only by the substituted
|
|
249
|
+
* tenant IDs or markers. Present whenever the schema has a tenant policy, for every
|
|
250
|
+
* dialect form. In `strict` mode a failure
|
|
251
|
+
* throws `TenantGuardrailError` instead, so a returned result is always `passed`
|
|
252
|
+
* under `strict`.
|
|
253
|
+
*/
|
|
131
254
|
tenantGuardrail?: import("./sql/tenant-guardrail.js").TenantGuardrailResult;
|
|
255
|
+
/**
|
|
256
|
+
* `"sql-params"` mode only: the tenant IDs for the markers in `sql`, in marker
|
|
257
|
+
* order. `sql` + `tenantParams` is an executable pair on its own.
|
|
258
|
+
*/
|
|
132
259
|
tenantParams?: unknown[];
|
|
133
260
|
tenantBindings?: TenantBinding[];
|
|
134
261
|
/** Token usage for the LLM generation call. Absent when the provider does not report usage. */
|
package/dist/ask.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,IAAI,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,IAAI,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAGV,WAAW,EACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAGjB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC9B,MAAM,8BAA8B,CAAC;AAOtC,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,0EAA0E;AAC1E,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yCAAyC,CAAC,EAAE,OAAO,CAAC;IACpD,YAAY,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,8BAA8B,EAAE,sBAAsB,CAAC;IAC7E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,kGAAkG;AAClG,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,0GAA0G;AAC1G,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,2BAA2B,EAAE,qBAAqB,CAAC;IAC5E,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,6BAA6B,EAAE,iBAAiB,CAAC;CAC7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE1E,qGAAqG;AACrG,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,CAAC,EAAE,OAAO,mBAAmB,CAAC;IAC1C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,MAAM,EAAE,KACvB,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,kBAAkB,CAAC;IAC1B;;;OAGG;IACH,OAAO,EAAE,eAAe,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,yCAAyC,CAAC,EAAE,OAAO,CAAC;IACpD,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,wFAAwF;IACxF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;;;;;;;;;;;;OAgBG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IACpD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;CACzD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACrC,uDAAuD;IACvD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,2BAA2B,EAAE,qBAAqB,CAAC;IAC5E;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,+FAA+F;IAC/F,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF,wBAAsB,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+NjF"}
|