@lunora/bindings 1.0.0-alpha.6 → 1.0.0-alpha.60
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/dist/analytics/index.d.mts +81 -85
- package/dist/analytics/index.d.ts +81 -85
- package/dist/analytics/index.mjs +1 -2
- package/dist/images/index.d.mts +159 -174
- package/dist/images/index.d.ts +159 -174
- package/dist/images/index.mjs +1 -3
- package/dist/kv/index.d.mts +74 -151
- package/dist/kv/index.d.ts +74 -151
- package/dist/kv/index.mjs +1 -2
- package/dist/packem_shared/AnalyticsSqlError-CeQ3A5Eb.mjs +1 -0
- package/dist/packem_shared/R2SqlError-ZHgOWClB.mjs +1 -0
- package/dist/packem_shared/SelectBuilder-DJXNSdqC.mjs +1 -0
- package/dist/packem_shared/SetOperation-kiI5Wnlm.mjs +1 -0
- package/dist/packem_shared/Sql-BfnxRway.mjs +1 -0
- package/dist/packem_shared/WindowExpression-VX7EEV3h.mjs +1 -0
- package/dist/packem_shared/WindowFunction-CL4jYy2l.mjs +1 -0
- package/dist/packem_shared/asc-DP_WFiAE.mjs +1 -0
- package/dist/packem_shared/buildImageDeliveryUrl-Brqs-dcZ.mjs +1 -0
- package/dist/packem_shared/buildSignedImageUrl-BV-iSJKA.mjs +4 -0
- package/dist/packem_shared/cap-error-body-YBKO32BF.mjs +1 -0
- package/dist/packem_shared/concurrent-vRmSvRpF.mjs +1 -0
- package/dist/packem_shared/createAnalytics-BXTNc57d.mjs +1 -0
- package/dist/packem_shared/createContextVectors-BcfM30uc.mjs +6 -0
- package/dist/packem_shared/createImages-D7JExfqF.mjs +1 -0
- package/dist/packem_shared/createKv-mAHanD5g.mjs +1 -0
- package/dist/packem_shared/createKvIntrospector-BpRiFRFQ.mjs +1 -0
- package/dist/packem_shared/createPipelines-CIvqrc7E.mjs +1 -0
- package/dist/packem_shared/createVectorAdminIntrospector-Ct8v6PxJ.mjs +1 -0
- package/dist/packem_shared/createVectors-Dzv0ilKE.mjs +1 -0
- package/dist/pipelines/index.d.mts +24 -24
- package/dist/pipelines/index.d.ts +24 -24
- package/dist/pipelines/index.mjs +1 -1
- package/dist/r2sql/index.d.mts +169 -125
- package/dist/r2sql/index.d.ts +169 -125
- package/dist/r2sql/index.mjs +1 -7
- package/dist/vectors/index.d.mts +187 -134
- package/dist/vectors/index.d.ts +187 -134
- package/dist/vectors/index.mjs +1 -3
- package/package.json +3 -2
- package/dist/packem_shared/AnalyticsSqlError-C2nz3jpH.mjs +0 -41
- package/dist/packem_shared/R2SqlError-Boygg3S0.mjs +0 -65
- package/dist/packem_shared/SelectBuilder-DHaXZwn_.mjs +0 -167
- package/dist/packem_shared/SetOperation-RDHcxccj.mjs +0 -80
- package/dist/packem_shared/Sql-DceGtcUd.mjs +0 -68
- package/dist/packem_shared/WindowExpression-Cg9s2xcr.mjs +0 -44
- package/dist/packem_shared/WindowFunction-DA3pGC3N.mjs +0 -82
- package/dist/packem_shared/asc-Cur-xO8v.mjs +0 -16
- package/dist/packem_shared/buildImageDeliveryUrl-B6_QU91n.mjs +0 -33
- package/dist/packem_shared/buildSignedImageUrl-6iibA9v1.mjs +0 -113
- package/dist/packem_shared/concurrent-Dj5sOibv.mjs +0 -23
- package/dist/packem_shared/createAnalytics-CEEI69o9.mjs +0 -57
- package/dist/packem_shared/createContextVectors-BSizpmu5.mjs +0 -140
- package/dist/packem_shared/createImages-BzRnsz3H.mjs +0 -85
- package/dist/packem_shared/createKv-7lNrS1W2.mjs +0 -143
- package/dist/packem_shared/createKvIntrospector-CrAgQp1w.mjs +0 -77
- package/dist/packem_shared/createPipelines-CfyJ6VGu.mjs +0 -10
- package/dist/packem_shared/createVectorAdminIntrospector-C-qTDWA1.mjs +0 -53
- package/dist/packem_shared/createVectors-DqxgEPQb.mjs +0 -95
package/dist/r2sql/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { LunoraError } from '@lunora/errors';
|
|
2
2
|
/**
|
|
3
|
-
* A composed SQL fragment. Carries the finished `text`; `toString()` returns it
|
|
4
|
-
* so a fragment can be dropped straight into a template or `String(...)`.
|
|
5
|
-
*/
|
|
3
|
+
* A composed SQL fragment. Carries the finished `text`; `toString()` returns it
|
|
4
|
+
* so a fragment can be dropped straight into a template or `String(...)`.
|
|
5
|
+
*/
|
|
6
6
|
declare class Sql {
|
|
7
7
|
readonly text: string;
|
|
8
8
|
constructor(text: string);
|
|
@@ -11,32 +11,48 @@ declare class Sql {
|
|
|
11
11
|
/** True when `value` is a {@link Sql} fragment (an already-trusted, pre-escaped span). */
|
|
12
12
|
declare const isSql: (value: unknown) => value is Sql;
|
|
13
13
|
/**
|
|
14
|
-
* Wrap an already-trusted string as a {@link Sql} fragment so {@link sql}
|
|
15
|
-
* splices it **verbatim** (no escaping). Use ONLY for SQL you constructed
|
|
16
|
-
* yourself (identifiers, keywords, sub-fragments) — never for user input.
|
|
17
|
-
*/
|
|
14
|
+
* Wrap an already-trusted string as a {@link Sql} fragment so {@link sql}
|
|
15
|
+
* splices it **verbatim** (no escaping). Use ONLY for SQL you constructed
|
|
16
|
+
* yourself (identifiers, keywords, sub-fragments) — never for user input.
|
|
17
|
+
*/
|
|
18
18
|
declare const raw: (text: string) => Sql;
|
|
19
19
|
/** Resolve a `string | Sql` to its raw text. A bare string is taken as trusted SQL (callers pass identifiers/fragments here). */
|
|
20
20
|
declare const toText: (value: Sql | string) => string;
|
|
21
21
|
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
|
|
22
|
+
* Validate a table/namespace/database identifier that will be spliced into R2 SQL
|
|
23
|
+
* text (which has no parameter binding and no identifier quoting we can rely on).
|
|
24
|
+
* Accepts only dotted `\w` segments and throws otherwise, so a client-supplied
|
|
25
|
+
* `describe`/`showTables` argument can't inject SQL. For a genuinely dynamic
|
|
26
|
+
* identifier you built yourself, wrap it with {@link raw}.
|
|
27
|
+
*/
|
|
28
|
+
declare const ident: (name: string) => string;
|
|
29
|
+
/**
|
|
30
|
+
* Validate a table REFERENCE for a `FROM`/`JOIN` position: a dotted identifier
|
|
31
|
+
* plus an optional `[AS] alias`. Broader than {@link ident} (which forbids the
|
|
32
|
+
* alias) but still an allowlist — no whitespace beyond the single alias, no
|
|
33
|
+
* punctuation — so a caller-supplied table string can't inject SQL. Use
|
|
34
|
+
* {@link raw} for anything more dynamic that you built yourself.
|
|
35
|
+
*/
|
|
36
|
+
declare const tableRef: (ref: string) => string;
|
|
37
|
+
/**
|
|
38
|
+
* Render a JS value as an R2 SQL literal:
|
|
39
|
+
*
|
|
40
|
+
* - `null` / `undefined` → `NULL`
|
|
41
|
+
* - `boolean` → `true` / `false`
|
|
42
|
+
* - finite `number` / `bigint` → the numeric text (non-finite throws — `NaN`/`Infinity` have no SQL literal)
|
|
43
|
+
* - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form; an invalid `Date` throws)
|
|
44
|
+
* - `string` → a single-quoted, escaped literal
|
|
45
|
+
* - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
|
|
46
|
+
*
|
|
47
|
+
* Anything else (object, symbol, function) throws — there is no safe SQL literal
|
|
48
|
+
* for it, and silently coercing would risk a malformed or injectable statement.
|
|
49
|
+
*/
|
|
34
50
|
declare const lit: (value: unknown) => string;
|
|
35
51
|
/**
|
|
36
|
-
* Tagged template producing a safe {@link Sql} fragment. Each interpolation is
|
|
37
|
-
* escaped with {@link lit} unless it is already a {@link Sql} (spliced
|
|
38
|
-
* verbatim), so user values can never break out of their literal.
|
|
39
|
-
*/
|
|
52
|
+
* Tagged template producing a safe {@link Sql} fragment. Each interpolation is
|
|
53
|
+
* escaped with {@link lit} unless it is already a {@link Sql} (spliced
|
|
54
|
+
* verbatim), so user values can never break out of their literal.
|
|
55
|
+
*/
|
|
40
56
|
declare const sql: (strings: TemplateStringsArray, ...values: unknown[]) => Sql;
|
|
41
57
|
/** Join SQL fragments/strings with `separator` into one {@link Sql} (e.g. `AND`-ed conditions). */
|
|
42
58
|
declare const joinSql: (parts: ReadonlyArray<Sql | string>, separator: string) => Sql;
|
|
@@ -52,29 +68,29 @@ declare const desc: (expr: Sql | string) => OrderTerm;
|
|
|
52
68
|
/** Render one {@link OrderTerm} to SQL. */
|
|
53
69
|
declare const renderOrderTerm: (term: OrderTerm) => string;
|
|
54
70
|
/**
|
|
55
|
-
* Public types for `@lunora/bindings/r2sql`.
|
|
56
|
-
*
|
|
57
|
-
* R2 SQL is Cloudflare's serverless, distributed query engine over **Apache
|
|
58
|
-
* Iceberg** tables in [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/).
|
|
59
|
-
* It has **no Workers binding** — every query is an HTTPS round-trip to the REST
|
|
60
|
-
* endpoint (`POST …/r2-sql/query/{bucket}`). So, like Hyperdrive's `ctx.sql`, the
|
|
61
|
-
* client is **non-deterministic external I/O**: it is wired onto `ActionCtx`
|
|
62
|
-
* only (see the `r2sql_outside_action` advisor lint) and its reads are NOT
|
|
63
|
-
* tracked by Lunora live queries.
|
|
64
|
-
*
|
|
65
|
-
* Everything here is deliberately structural (no hard dependency on
|
|
66
|
-
* `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
|
|
67
|
-
* and never touch the network — mirroring `AnalyticsSqlConfig` in
|
|
68
|
-
* `@lunora/bindings/analytics`.
|
|
69
|
-
*/
|
|
71
|
+
* Public types for `@lunora/bindings/r2sql`.
|
|
72
|
+
*
|
|
73
|
+
* R2 SQL is Cloudflare's serverless, distributed query engine over **Apache
|
|
74
|
+
* Iceberg** tables in [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/).
|
|
75
|
+
* It has **no Workers binding** — every query is an HTTPS round-trip to the REST
|
|
76
|
+
* endpoint (`POST …/r2-sql/query/{bucket}`). So, like Hyperdrive's `ctx.sql`, the
|
|
77
|
+
* client is **non-deterministic external I/O**: it is wired onto `ActionCtx`
|
|
78
|
+
* only (see the `r2sql_outside_action` advisor lint) and its reads are NOT
|
|
79
|
+
* tracked by Lunora live queries.
|
|
80
|
+
*
|
|
81
|
+
* Everything here is deliberately structural (no hard dependency on
|
|
82
|
+
* `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
|
|
83
|
+
* and never touch the network — mirroring `AnalyticsSqlConfig` in
|
|
84
|
+
* `@lunora/bindings/analytics`.
|
|
85
|
+
*/
|
|
70
86
|
/**
|
|
71
|
-
* Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.
|
|
72
|
-
*
|
|
73
|
-
* `apiToken` is a **secret** — a Cloudflare API token scoped to R2 SQL (read),
|
|
74
|
-
* R2 Data Catalog, and R2 storage. It is never a binding and must never be
|
|
75
|
-
* auto-scaffolded with a real value; the caller provides it from
|
|
76
|
-
* env/`.dev.vars`.
|
|
77
|
-
*/
|
|
87
|
+
* Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.
|
|
88
|
+
*
|
|
89
|
+
* `apiToken` is a **secret** — a Cloudflare API token scoped to R2 SQL (read),
|
|
90
|
+
* R2 Data Catalog, and R2 storage. It is never a binding and must never be
|
|
91
|
+
* auto-scaffolded with a real value; the caller provides it from
|
|
92
|
+
* env/`.dev.vars`.
|
|
93
|
+
*/
|
|
78
94
|
interface R2SqlConfig {
|
|
79
95
|
/** Cloudflare account id that owns the bucket/catalog. */
|
|
80
96
|
accountId: string;
|
|
@@ -83,36 +99,46 @@ interface R2SqlConfig {
|
|
|
83
99
|
/** The R2 bucket (warehouse) whose Data Catalog the queries run against. */
|
|
84
100
|
bucket: string;
|
|
85
101
|
/**
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
102
|
+
* Override the REST base URL. Defaults to Cloudflare's public R2 SQL host
|
|
103
|
+
* (`https://api.sql.cloudflarestorage.com/api/v1/accounts`). Injected in
|
|
104
|
+
* tests, or pointed at a regional/preview host.
|
|
105
|
+
*/
|
|
90
106
|
endpoint?: string;
|
|
91
107
|
/**
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
108
|
+
* `fetch` implementation. Defaults to the global `fetch`; injected in tests
|
|
109
|
+
* so a query never touches the network.
|
|
110
|
+
*/
|
|
95
111
|
fetch?: typeof globalThis.fetch;
|
|
112
|
+
/**
|
|
113
|
+
* Milliseconds before an in-flight query (the fetch AND its body read) is
|
|
114
|
+
* aborted and surfaced as an `R2SqlError` with status 504. Defaults to
|
|
115
|
+
* 60_000 — analytical scans legitimately run tens of seconds. `undefined`
|
|
116
|
+
* means the default, not unbounded.
|
|
117
|
+
*
|
|
118
|
+
* The deadline is carried by the request's `signal`, so a custom `fetch`
|
|
119
|
+
* (above) that ignores `signal` leaves the query unbounded.
|
|
120
|
+
*/
|
|
121
|
+
timeoutMs?: number;
|
|
96
122
|
}
|
|
97
123
|
/**
|
|
98
|
-
* One column descriptor in a result's schema: the column `name` and, when the
|
|
99
|
-
* engine reports it, the Iceberg storage `type` (`integer`, `string`,
|
|
100
|
-
* `timestamp`, …). R2 SQL does not always echo a schema block, so `type` is
|
|
101
|
-
* optional and `columns` may be derived from the first row's keys.
|
|
102
|
-
*/
|
|
124
|
+
* One column descriptor in a result's schema: the column `name` and, when the
|
|
125
|
+
* engine reports it, the Iceberg storage `type` (`integer`, `string`,
|
|
126
|
+
* `timestamp`, …). R2 SQL does not always echo a schema block, so `type` is
|
|
127
|
+
* optional and `columns` may be derived from the first row's keys.
|
|
128
|
+
*/
|
|
103
129
|
interface R2SqlColumn {
|
|
104
130
|
name: string;
|
|
105
131
|
type?: string;
|
|
106
132
|
}
|
|
107
133
|
/**
|
|
108
|
-
* A parsed R2 SQL result. R2 SQL returns a Cloudflare envelope
|
|
109
|
-
* (`{ success, result, errors }`); we surface the `rows` (the `result` array of
|
|
110
|
-
* column→value records), the inferred/echoed `columns`, and the `rowCount`.
|
|
111
|
-
*
|
|
112
|
-
* `Row` defaults to an open record; supply it (`from
|
|
113
|
-
* `query
|
|
114
|
-
* not `defineSchema`, so the row type is caller-declared rather than inferred.
|
|
115
|
-
*/
|
|
134
|
+
* A parsed R2 SQL result. R2 SQL returns a Cloudflare envelope
|
|
135
|
+
* (`{ success, result, errors }`); we surface the `rows` (the `result` array of
|
|
136
|
+
* column→value records), the inferred/echoed `columns`, and the `rowCount`.
|
|
137
|
+
*
|
|
138
|
+
* `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
|
|
139
|
+
* `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
|
|
140
|
+
* not `defineSchema`, so the row type is caller-declared rather than inferred.
|
|
141
|
+
*/
|
|
116
142
|
interface R2SqlResult<Row = Record<string, unknown>> {
|
|
117
143
|
/** Column descriptors, echoed by the engine or inferred from the first row. */
|
|
118
144
|
columns: R2SqlColumn[];
|
|
@@ -124,25 +150,25 @@ interface R2SqlResult<Row = Record<string, unknown>> {
|
|
|
124
150
|
/** Options for {@link import("./client").R2SqlClient.explain | explain}. */
|
|
125
151
|
interface R2SqlExplainOptions {
|
|
126
152
|
/**
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
153
|
+
* `"json"` runs `EXPLAIN FORMAT JSON` (structured plan); `"text"` (default)
|
|
154
|
+
* runs a plain `EXPLAIN`.
|
|
155
|
+
*/
|
|
130
156
|
format?: "json" | "text";
|
|
131
157
|
}
|
|
132
158
|
/**
|
|
133
|
-
* Executes a finished SQL string against R2 SQL and returns the parsed result.
|
|
134
|
-
* Deliberately non-generic (the row type is a caller-side concern) — the typed
|
|
135
|
-
* `run()` / `query()` boundaries cast the open result to the declared row.
|
|
136
|
-
*/
|
|
159
|
+
* Executes a finished SQL string against R2 SQL and returns the parsed result.
|
|
160
|
+
* Deliberately non-generic (the row type is a caller-side concern) — the typed
|
|
161
|
+
* `run()` / `query()` boundaries cast the open result to the declared row.
|
|
162
|
+
*/
|
|
137
163
|
type QueryExecutor = (statement: string) => Promise<R2SqlResult>;
|
|
138
164
|
/** Anything that compiles to a statement and can run — a {@link import("./builder").SelectBuilder | SelectBuilder} or {@link import("./set-operation").SetOperation | SetOperation}. */
|
|
139
165
|
interface Queryable<Row = Record<string, unknown>> {
|
|
140
166
|
/**
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
167
|
+
* True when this query carries its own `ORDER BY`/`LIMIT`, so a set
|
|
168
|
+
* operation must parenthesise it (R2 SQL rejects a bare `LIMIT` before a set
|
|
169
|
+
* operator). Read structurally by the set-operation renderer to avoid an
|
|
170
|
+
* import cycle.
|
|
171
|
+
*/
|
|
146
172
|
readonly needsWrapForSetOperation?: boolean;
|
|
147
173
|
run: () => Promise<R2SqlResult<Row>>;
|
|
148
174
|
toSQL: () => string;
|
|
@@ -155,16 +181,16 @@ interface SetMember {
|
|
|
155
181
|
query: Queryable<unknown>;
|
|
156
182
|
}
|
|
157
183
|
/**
|
|
158
|
-
* A composition of queries via set operations. Chain more operations, or apply a
|
|
159
|
-
* single `ORDER BY` / `LIMIT` to the combined result.
|
|
160
|
-
*/
|
|
184
|
+
* A composition of queries via set operations. Chain more operations, or apply a
|
|
185
|
+
* single `ORDER BY` / `LIMIT` to the combined result.
|
|
186
|
+
*/
|
|
161
187
|
declare class SetOperation<Row = Record<string, unknown>> implements Queryable<Row> {
|
|
162
188
|
/**
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
189
|
+
* Always `true`: a nested set operation must be parenthesised when it is a
|
|
190
|
+
* member of another set operation, or mixed operators mis-associate — e.g.
|
|
191
|
+
* `a.union(b.except(c))` must render `a UNION (b EXCEPT c)`, not the flat
|
|
192
|
+
* `a UNION b EXCEPT c`.
|
|
193
|
+
*/
|
|
168
194
|
readonly needsWrapForSetOperation = true;
|
|
169
195
|
private readonly exec;
|
|
170
196
|
private readonly members;
|
|
@@ -192,9 +218,9 @@ declare class SetOperation<Row = Record<string, unknown>> implements Queryable<R
|
|
|
192
218
|
private add;
|
|
193
219
|
}
|
|
194
220
|
/**
|
|
195
|
-
* A fluent `SELECT` over one Iceberg table (`namespace.table`), generic over the
|
|
196
|
-
* caller-declared `Row` result type.
|
|
197
|
-
*/
|
|
221
|
+
* A fluent `SELECT` over one Iceberg table (`namespace.table`), generic over the
|
|
222
|
+
* caller-declared `Row` result type.
|
|
223
|
+
*/
|
|
198
224
|
declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<Row> {
|
|
199
225
|
private readonly exec;
|
|
200
226
|
private readonly table;
|
|
@@ -225,16 +251,16 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
|
|
|
225
251
|
fullJoin(table: string, on: Condition): this;
|
|
226
252
|
/** `CROSS JOIN table` (no `ON`). */
|
|
227
253
|
crossJoin(table: string): this;
|
|
228
|
-
/** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed. Bind values with the `sql` tag. */
|
|
254
|
+
/** Add `WHERE` condition(s). Multiple calls (and multiple args) are `AND`-ed, each parenthesised. Bind values with the `sql` tag. */
|
|
229
255
|
where(...conditions: Condition[]): this;
|
|
230
256
|
/** `GROUP BY` column(s)/expression(s). */
|
|
231
257
|
groupBy(...columns: (Sql | string)[]): this;
|
|
232
|
-
/** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed. */
|
|
258
|
+
/** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed, each parenthesised. */
|
|
233
259
|
having(...conditions: Condition[]): this;
|
|
234
260
|
/**
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
261
|
+
* `QUALIFY` — filter on a window function without a subquery, e.g.
|
|
262
|
+
* `.qualify(fn.rowNumber().over({ partitionBy: "region", orderBy: desc("total") }).lte(3))`.
|
|
263
|
+
*/
|
|
238
264
|
qualify(condition: Condition): this;
|
|
239
265
|
/** `ORDER BY` term(s) — bare strings (ASC) or {@link import("./order").asc | asc}/{@link import("./order").desc | desc} tags. */
|
|
240
266
|
orderBy(...terms: OrderTerm[]): this;
|
|
@@ -262,18 +288,21 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
|
|
|
262
288
|
private setOperation;
|
|
263
289
|
}
|
|
264
290
|
/**
|
|
265
|
-
* Thrown when R2 SQL responds with a non-2xx status, an `success: false`
|
|
266
|
-
* envelope, or an unparseable body; carries the HTTP `status` and
|
|
267
|
-
* for the caller to surface
|
|
268
|
-
|
|
291
|
+
* Thrown when R2 SQL responds with a non-2xx status, an `success: false`
|
|
292
|
+
* envelope, or an unparseable body; carries the HTTP `status` and a capped body
|
|
293
|
+
* preview for the caller to surface, with the full body on `cause`.
|
|
294
|
+
*
|
|
295
|
+
* The preview is capped because the engine's SQL error text quotes the query
|
|
296
|
+
* back, and `R2_SQL_ERROR` is non-internal — the message reaches the browser.
|
|
297
|
+
*/
|
|
269
298
|
declare class R2SqlError extends LunoraError {
|
|
270
299
|
constructor(status: number, body: string);
|
|
271
300
|
}
|
|
272
301
|
/**
|
|
273
|
-
* The typed R2 SQL surface bound to `ctx.r2sql` on **`ActionCtx` only**. This is
|
|
274
|
-
* the exact type the generated ctx imports as
|
|
275
|
-
* `import("@lunora/bindings/r2sql").R2SqlClient` — keep the name and shape stable.
|
|
276
|
-
*/
|
|
302
|
+
* The typed R2 SQL surface bound to `ctx.r2sql` on **`ActionCtx` only**. This is
|
|
303
|
+
* the exact type the generated ctx imports as
|
|
304
|
+
* `import("@lunora/bindings/r2sql").R2SqlClient` — keep the name and shape stable.
|
|
305
|
+
*/
|
|
277
306
|
interface R2SqlClient {
|
|
278
307
|
/** Run `DESCRIBE namespace.table` — column names and Iceberg types. */
|
|
279
308
|
describe: (table: string) => Promise<R2SqlResult>;
|
|
@@ -289,16 +318,16 @@ interface R2SqlClient {
|
|
|
289
318
|
showTables: (namespace: string) => Promise<R2SqlResult>;
|
|
290
319
|
}
|
|
291
320
|
/**
|
|
292
|
-
* Build an {@link R2SqlClient}. Each query POSTs to the bucket's
|
|
293
|
-
* `r2-sql/query/{bucket}` endpoint with the bearer token, then normalises the
|
|
294
|
-
* envelope into {@link R2SqlResult}.
|
|
295
|
-
*/
|
|
321
|
+
* Build an {@link R2SqlClient}. Each query POSTs to the bucket's
|
|
322
|
+
* `r2-sql/query/{bucket}` endpoint with the bearer token, then normalises the
|
|
323
|
+
* envelope into {@link R2SqlResult}.
|
|
324
|
+
*/
|
|
296
325
|
declare const createR2Sql: (config: R2SqlConfig) => R2SqlClient;
|
|
297
326
|
/**
|
|
298
|
-
* A windowed expression. Extends {@link Sql}, so it is usable anywhere a raw
|
|
299
|
-
* fragment is; `.as(alias)` makes a `SELECT` item, and the comparison helpers
|
|
300
|
-
* (`.lte`, `.gt`, `.between`, …) make `QUALIFY` conditions.
|
|
301
|
-
*/
|
|
327
|
+
* A windowed expression. Extends {@link Sql}, so it is usable anywhere a raw
|
|
328
|
+
* fragment is; `.as(alias)` makes a `SELECT` item, and the comparison helpers
|
|
329
|
+
* (`.lte`, `.gt`, `.between`, …) make `QUALIFY` conditions.
|
|
330
|
+
*/
|
|
302
331
|
declare class WindowExpression extends Sql {
|
|
303
332
|
/** Alias the expression — `... AS alias` — for use in a `SELECT` list. */
|
|
304
333
|
as(alias: string): Sql;
|
|
@@ -310,18 +339,18 @@ declare class WindowExpression extends Sql {
|
|
|
310
339
|
gt(value: unknown): Sql;
|
|
311
340
|
/** `expr >= value`. */
|
|
312
341
|
gte(value: unknown): Sql;
|
|
313
|
-
/** `expr
|
|
342
|
+
/** `expr < value`. */
|
|
314
343
|
lt(value: unknown): Sql;
|
|
315
|
-
/** `expr
|
|
344
|
+
/** `expr <= value`. */
|
|
316
345
|
lte(value: unknown): Sql;
|
|
317
346
|
private compare;
|
|
318
347
|
}
|
|
319
348
|
/** The `OVER (...)` window specification. */
|
|
320
349
|
interface OverSpec {
|
|
321
350
|
/**
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
351
|
+
* A raw frame clause, e.g. `"ROWS BETWEEN 2 PRECEDING AND CURRENT ROW"`.
|
|
352
|
+
* Spliced verbatim — it is keyword-only SQL, not a value.
|
|
353
|
+
*/
|
|
325
354
|
frame?: string;
|
|
326
355
|
/** `ORDER BY` term(s) within the window. */
|
|
327
356
|
orderBy?: OrderTerm | OrderTerm[];
|
|
@@ -329,9 +358,9 @@ interface OverSpec {
|
|
|
329
358
|
partitionBy?: Sql | string | (Sql | string)[];
|
|
330
359
|
}
|
|
331
360
|
/**
|
|
332
|
-
* A window function awaiting its `OVER (...)`. Call {@link WindowFunction.over |
|
|
333
|
-
* .over} to bind a window and get a {@link WindowExpression}.
|
|
334
|
-
*/
|
|
361
|
+
* A window function awaiting its `OVER (...)`. Call {@link WindowFunction.over |
|
|
362
|
+
* .over} to bind a window and get a {@link WindowExpression}.
|
|
363
|
+
*/
|
|
335
364
|
declare class WindowFunction {
|
|
336
365
|
private readonly callText;
|
|
337
366
|
constructor(callText: string);
|
|
@@ -339,13 +368,13 @@ declare class WindowFunction {
|
|
|
339
368
|
over(spec?: OverSpec): WindowExpression;
|
|
340
369
|
}
|
|
341
370
|
/**
|
|
342
|
-
* Window-function builders. Each returns a {@link WindowFunction}; chain
|
|
343
|
-
* `.over(...)` to bind the window.
|
|
344
|
-
*
|
|
345
|
-
* Ranking: `rowNumber`, `rank`, `denseRank`, `percentRank`, `cumeDist`,
|
|
346
|
-
* `ntile`. Offset/value: `lag`, `lead`, `firstValue`, `lastValue`, `nthValue`.
|
|
347
|
-
* Aggregates used as windows: `sum`, `avg`, `count`, `min`, `max`.
|
|
348
|
-
*/
|
|
371
|
+
* Window-function builders. Each returns a {@link WindowFunction}; chain
|
|
372
|
+
* `.over(...)` to bind the window.
|
|
373
|
+
*
|
|
374
|
+
* Ranking: `rowNumber`, `rank`, `denseRank`, `percentRank`, `cumeDist`,
|
|
375
|
+
* `ntile`. Offset/value: `lag`, `lead`, `firstValue`, `lastValue`, `nthValue`.
|
|
376
|
+
* Aggregates used as windows: `sum`, `avg`, `count`, `min`, `max`.
|
|
377
|
+
*/
|
|
349
378
|
declare const fn: {
|
|
350
379
|
/** `AVG(column) OVER (...)`. */
|
|
351
380
|
avg: (column: Sql | string) => WindowFunction;
|
|
@@ -380,4 +409,19 @@ declare const fn: {
|
|
|
380
409
|
/** `SUM(column) OVER (...)`. */
|
|
381
410
|
sum: (column: Sql | string) => WindowFunction;
|
|
382
411
|
};
|
|
383
|
-
export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult,
|
|
412
|
+
export { type Condition, type OrderTerm, type OverSpec, type QueryExecutor, type Queryable, type R2SqlClient, type R2SqlColumn, type R2SqlConfig, R2SqlError, type R2SqlExplainOptions, type R2SqlResult,
|
|
413
|
+
/**
|
|
414
|
+
* `@lunora/bindings/r2sql` — typed, chainable R2 SQL for Lunora.
|
|
415
|
+
*
|
|
416
|
+
* Query Cloudflare [R2 SQL](https://developers.cloudflare.com/r2-sql/) — the
|
|
417
|
+
* serverless engine over Apache Iceberg tables in R2 Data Catalog — from a
|
|
418
|
+
* Lunora **action** via `ctx.r2sql`. First-class support for the 2026-06-21
|
|
419
|
+
* features: window functions (`fn.rowNumber().over(...)`), `DISTINCT` /
|
|
420
|
+
* `DISTINCT ON`, `QUALIFY`, and set operations (`.union()/.intersect()/.except()`).
|
|
421
|
+
*
|
|
422
|
+
* R2 SQL is non-deterministic external I/O with no Workers binding, so — like
|
|
423
|
+
* `ctx.sql` (Hyperdrive) — it is wired onto `ActionCtx` only and its reads are
|
|
424
|
+
* not tracked by Lunora live queries (see the `r2sql_outside_action` advisor
|
|
425
|
+
* lint). See the README and `createR2Sql` JSDoc.
|
|
426
|
+
*/
|
|
427
|
+
SelectBuilder, SetOperation, Sql, WindowExpression, WindowFunction, asc, createR2Sql, desc, fn, ident, isSql, joinSql, lit, raw, renderOrderTerm, sql, tableRef, toText };
|
package/dist/r2sql/index.mjs
CHANGED
|
@@ -1,7 +1 @@
|
|
|
1
|
-
|
|
2
|
-
export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-Boygg3S0.mjs';
|
|
3
|
-
export { asc, desc, renderOrderTerm } from '../packem_shared/asc-Cur-xO8v.mjs';
|
|
4
|
-
export { default as SetOperation } from '../packem_shared/SetOperation-RDHcxccj.mjs';
|
|
5
|
-
export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-DceGtcUd.mjs';
|
|
6
|
-
export { WindowFunction, fn } from '../packem_shared/WindowFunction-DA3pGC3N.mjs';
|
|
7
|
-
export { default as WindowExpression } from '../packem_shared/WindowExpression-Cg9s2xcr.mjs';
|
|
1
|
+
import{default as o}from"../packem_shared/SelectBuilder-DJXNSdqC.mjs";import{R2SqlError as l,createR2Sql as f}from"../packem_shared/R2SqlError-ZHgOWClB.mjs";import{asc as d,desc as i,renderOrderTerm as n}from"../packem_shared/asc-DP_WFiAE.mjs";import{default as s}from"../packem_shared/SetOperation-kiI5Wnlm.mjs";import{Sql as m,ident as S,isSql as q,joinSql as c,lit as u,raw as w,sql as R,tableRef as E,toText as O}from"../packem_shared/Sql-BfnxRway.mjs";import{WindowFunction as W,fn as b}from"../packem_shared/WindowFunction-CL4jYy2l.mjs";import{default as B}from"../packem_shared/WindowExpression-VX7EEV3h.mjs";export{l as R2SqlError,o as SelectBuilder,s as SetOperation,m as Sql,B as WindowExpression,W as WindowFunction,d as asc,f as createR2Sql,i as desc,b as fn,S as ident,q as isSql,c as joinSql,u as lit,w as raw,n as renderOrderTerm,R as sql,E as tableRef,O as toText};
|