@lunora/bindings 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/r2sql/index.d.ts

@@ -1,7 +1,8 @@
+import { LunoraError } from '@lunora/errors';
 /**
-* A composed SQL fragment. Carries the finished `text`; `toString()` returns it
-* so a fragment can be dropped straight into a template or `String(...)`.
-*/
+ * A composed SQL fragment. Carries the finished `text`; `toString()` returns it
+ * so a fragment can be dropped straight into a template or `String(...)`.
+ */
 declare class Sql {
   readonly text: string;
   constructor(text: string);
@@ -10,32 +11,32 @@ declare class Sql {
 /** True when `value` is a {@link Sql} fragment (an already-trusted, pre-escaped span). */
 declare const isSql: (value: unknown) => value is Sql;
 /**
-* Wrap an already-trusted string as a {@link Sql} fragment so {@link sql}
-* splices it **verbatim** (no escaping). Use ONLY for SQL you constructed
-* yourself (identifiers, keywords, sub-fragments) — never for user input.
-*/
+ * Wrap an already-trusted string as a {@link Sql} fragment so {@link sql}
+ * splices it **verbatim** (no escaping). Use ONLY for SQL you constructed
+ * yourself (identifiers, keywords, sub-fragments) — never for user input.
+ */
 declare const raw: (text: string) => Sql;
 /** Resolve a `string | Sql` to its raw text. A bare string is taken as trusted SQL (callers pass identifiers/fragments here). */
 declare const toText: (value: Sql | string) => string;
 /**
-* Render a JS value as an R2 SQL literal:
-*
-* - `null` / `undefined` → `NULL`
-* - `boolean` → `true` / `false`
-* - finite `number` / `bigint` → the numeric text (non-finite throws — `NaN`/`Infinity` have no SQL literal)
-* - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form)
-* - `string` → a single-quoted, escaped literal
-* - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
-*
-* Anything else (object, symbol, function) throws — there is no safe SQL literal
-* for it, and silently coercing would risk a malformed or injectable statement.
-*/
+ * Render a JS value as an R2 SQL literal:
+ *
+ * - `null` / `undefined` → `NULL`
+ * - `boolean` → `true` / `false`
+ * - finite `number` / `bigint` → the numeric text (non-finite throws — `NaN`/`Infinity` have no SQL literal)
+ * - `Date` → an RFC3339 string literal (R2 SQL's `timestamp` form)
+ * - `string` → a single-quoted, escaped literal
+ * - `Array` → a parenthesised, comma-separated list of literals (for `IN (...)`)
+ *
+ * Anything else (object, symbol, function) throws — there is no safe SQL literal
+ * for it, and silently coercing would risk a malformed or injectable statement.
+ */
 declare const lit: (value: unknown) => string;
 /**
-* Tagged template producing a safe {@link Sql} fragment. Each interpolation is
-* escaped with {@link lit} unless it is already a {@link Sql} (spliced
-* verbatim), so user values can never break out of their literal.
-*/
+ * Tagged template producing a safe {@link Sql} fragment. Each interpolation is
+ * escaped with {@link lit} unless it is already a {@link Sql} (spliced
+ * verbatim), so user values can never break out of their literal.
+ */
 declare const sql: (strings: TemplateStringsArray, ...values: unknown[]) => Sql;
 /** Join SQL fragments/strings with `separator` into one {@link Sql} (e.g. `AND`-ed conditions). */
 declare const joinSql: (parts: ReadonlyArray<Sql | string>, separator: string) => Sql;
@@ -51,29 +52,29 @@ declare const desc: (expr: Sql | string) => OrderTerm;
 /** Render one {@link OrderTerm} to SQL. */
 declare const renderOrderTerm: (term: OrderTerm) => string;
 /**
-* Public types for `@lunora/bindings/r2sql`.
-*
-* R2 SQL is Cloudflare's serverless, distributed query engine over **Apache
-* Iceberg** tables in [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/).
-* It has **no Workers binding** — every query is an HTTPS round-trip to the REST
-* endpoint (`POST …/r2-sql/query/{bucket}`). So, like Hyperdrive's `ctx.sql`, the
-* client is **non-deterministic external I/O**: it is wired onto `ActionCtx`
-* only (see the `r2sql_outside_action` advisor lint) and its reads are NOT
-* tracked by Lunora live queries.
-*
-* Everything here is deliberately structural (no hard dependency on
-* `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
-* and never touch the network — mirroring `AnalyticsSqlConfig` in
-* `@lunora/bindings/analytics`.
-*/
+ * Public types for `@lunora/bindings/r2sql`.
+ *
+ * R2 SQL is Cloudflare's serverless, distributed query engine over **Apache
+ * Iceberg** tables in [R2 Data Catalog](https://developers.cloudflare.com/r2/data-catalog/).
+ * It has **no Workers binding** — every query is an HTTPS round-trip to the REST
+ * endpoint (`POST …/r2-sql/query/{bucket}`). So, like Hyperdrive's `ctx.sql`, the
+ * client is **non-deterministic external I/O**: it is wired onto `ActionCtx`
+ * only (see the `r2sql_outside_action` advisor lint) and its reads are NOT
+ * tracked by Lunora live queries.
+ *
+ * Everything here is deliberately structural (no hard dependency on
+ * `@cloudflare/workers-types`) so unit tests can inject a plain `fetch` double
+ * and never touch the network — mirroring `AnalyticsSqlConfig` in
+ * `@lunora/bindings/analytics`.
+ */
 /**
-* Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.
-*
-* `apiToken` is a **secret** — a Cloudflare API token scoped to R2 SQL (read),
-* R2 Data Catalog, and R2 storage. It is never a binding and must never be
-* auto-scaffolded with a real value; the caller provides it from
-* env/`.dev.vars`.
-*/
+ * Configuration for a {@link import("./client").R2SqlClient | R2SqlClient}.
+ *
+ * `apiToken` is a **secret** — a Cloudflare API token scoped to R2 SQL (read),
+ * R2 Data Catalog, and R2 storage. It is never a binding and must never be
+ * auto-scaffolded with a real value; the caller provides it from
+ * env/`.dev.vars`.
+ */
 interface R2SqlConfig {
   /** Cloudflare account id that owns the bucket/catalog. */
   accountId: string;
@@ -82,36 +83,36 @@ interface R2SqlConfig {
   /** The R2 bucket (warehouse) whose Data Catalog the queries run against. */
   bucket: string;
   /**
-  * Override the REST base URL. Defaults to Cloudflare's public R2 SQL host
-  * (`https://api.sql.cloudflarestorage.com/api/v1/accounts`). Injected in
-  * tests, or pointed at a regional/preview host.
-  */
+   * Override the REST base URL. Defaults to Cloudflare's public R2 SQL host
+   * (`https://api.sql.cloudflarestorage.com/api/v1/accounts`). Injected in
+   * tests, or pointed at a regional/preview host.
+   */
   endpoint?: string;
   /**
-  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
-  * so a query never touches the network.
-  */
+   * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+   * so a query never touches the network.
+   */
   fetch?: typeof globalThis.fetch;
 }
 /**
-* One column descriptor in a result's schema: the column `name` and, when the
-* engine reports it, the Iceberg storage `type` (`integer`, `string`,
-* `timestamp`, …). R2 SQL does not always echo a schema block, so `type` is
-* optional and `columns` may be derived from the first row's keys.
-*/
+ * One column descriptor in a result's schema: the column `name` and, when the
+ * engine reports it, the Iceberg storage `type` (`integer`, `string`,
+ * `timestamp`, …). R2 SQL does not always echo a schema block, so `type` is
+ * optional and `columns` may be derived from the first row's keys.
+ */
 interface R2SqlColumn {
   name: string;
   type?: string;
 }
 /**
-* A parsed R2 SQL result. R2 SQL returns a Cloudflare envelope
-* (`{ success, result, errors }`); we surface the `rows` (the `result` array of
-* column→value records), the inferred/echoed `columns`, and the `rowCount`.
-*
-* `Row` defaults to an open record; supply it (`from&lt;MyRow>(…)` /
-* `query&lt;MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
-* not `defineSchema`, so the row type is caller-declared rather than inferred.
-*/
+ * A parsed R2 SQL result. R2 SQL returns a Cloudflare envelope
+ * (`{ success, result, errors }`); we surface the `rows` (the `result` array of
+ * column→value records), the inferred/echoed `columns`, and the `rowCount`.
+ *
+ * `Row` defaults to an open record; supply it (`from<MyRow>(…)` /
+ * `query<MyRow>(…)`) to get typed result fields — R2 SQL tables live in Iceberg,
+ * not `defineSchema`, so the row type is caller-declared rather than inferred.
+ */
 interface R2SqlResult<Row = Record<string, unknown>> {
   /** Column descriptors, echoed by the engine or inferred from the first row. */
   columns: R2SqlColumn[];
@@ -123,25 +124,25 @@ interface R2SqlResult<Row = Record<string, unknown>> {
 /** Options for {@link import("./client").R2SqlClient.explain | explain}. */
 interface R2SqlExplainOptions {
   /**
-  * `"json"` runs `EXPLAIN FORMAT JSON` (structured plan); `"text"` (default)
-  * runs a plain `EXPLAIN`.
-  */
+   * `"json"` runs `EXPLAIN FORMAT JSON` (structured plan); `"text"` (default)
+   * runs a plain `EXPLAIN`.
+   */
   format?: "json" | "text";
 }
 /**
-* Executes a finished SQL string against R2 SQL and returns the parsed result.
-* Deliberately non-generic (the row type is a caller-side concern) — the typed
-* `run()` / `query()` boundaries cast the open result to the declared row.
-*/
+ * Executes a finished SQL string against R2 SQL and returns the parsed result.
+ * Deliberately non-generic (the row type is a caller-side concern) — the typed
+ * `run()` / `query()` boundaries cast the open result to the declared row.
+ */
 type QueryExecutor = (statement: string) => Promise<R2SqlResult>;
 /** Anything that compiles to a statement and can run — a {@link import("./builder").SelectBuilder | SelectBuilder} or {@link import("./set-operation").SetOperation | SetOperation}. */
 interface Queryable<Row = Record<string, unknown>> {
   /**
-  * True when this query carries its own `ORDER BY`/`LIMIT`, so a set
-  * operation must parenthesise it (R2 SQL rejects a bare `LIMIT` before a set
-  * operator). Read structurally by the set-operation renderer to avoid an
-  * import cycle.
-  */
+   * True when this query carries its own `ORDER BY`/`LIMIT`, so a set
+   * operation must parenthesise it (R2 SQL rejects a bare `LIMIT` before a set
+   * operator). Read structurally by the set-operation renderer to avoid an
+   * import cycle.
+   */
   readonly needsWrapForSetOperation?: boolean;
   run: () => Promise<R2SqlResult<Row>>;
   toSQL: () => string;
@@ -154,16 +155,16 @@ interface SetMember {
   query: Queryable<unknown>;
 }
 /**
-* A composition of queries via set operations. Chain more operations, or apply a
-* single `ORDER BY` / `LIMIT` to the combined result.
-*/
+ * A composition of queries via set operations. Chain more operations, or apply a
+ * single `ORDER BY` / `LIMIT` to the combined result.
+ */
 declare class SetOperation<Row = Record<string, unknown>> implements Queryable<Row> {
   /**
-  * Always `true`: a nested set operation must be parenthesised when it is a
-  * member of another set operation, or mixed operators mis-associate — e.g.
-  * `a.union(b.except(c))` must render `a UNION (b EXCEPT c)`, not the flat
-  * `a UNION b EXCEPT c`.
-  */
+   * Always `true`: a nested set operation must be parenthesised when it is a
+   * member of another set operation, or mixed operators mis-associate — e.g.
+   * `a.union(b.except(c))` must render `a UNION (b EXCEPT c)`, not the flat
+   * `a UNION b EXCEPT c`.
+   */
   readonly needsWrapForSetOperation = true;
   private readonly exec;
   private readonly members;
@@ -191,9 +192,9 @@ declare class SetOperation<Row = Record<string, unknown>> implements Queryable<R
   private add;
 }
 /**
-* A fluent `SELECT` over one Iceberg table (`namespace.table`), generic over the
-* caller-declared `Row` result type.
-*/
+ * A fluent `SELECT` over one Iceberg table (`namespace.table`), generic over the
+ * caller-declared `Row` result type.
+ */
 declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<Row> {
   private readonly exec;
   private readonly table;
@@ -231,9 +232,9 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
   /** Add `HAVING` condition(s) over aggregates; multiple are `AND`-ed. */
   having(...conditions: Condition[]): this;
   /**
-  * `QUALIFY` — filter on a window function without a subquery, e.g.
-  * `.qualify(fn.rowNumber().over({ partitionBy: "region", orderBy: desc("total") }).lte(3))`.
-  */
+   * `QUALIFY` — filter on a window function without a subquery, e.g.
+   * `.qualify(fn.rowNumber().over({ partitionBy: "region", orderBy: desc("total") }).lte(3))`.
+   */
   qualify(condition: Condition): this;
   /** `ORDER BY` term(s) — bare strings (ASC) or {@link import("./order").asc | asc}/{@link import("./order").desc | desc} tags. */
   orderBy(...terms: OrderTerm[]): this;
@@ -261,19 +262,18 @@ declare class SelectBuilder<Row = Record<string, unknown>> implements Queryable<
   private setOperation;
 }
 /**
-* Thrown when R2 SQL responds with a non-2xx status, an `success: false`
-* envelope, or an unparseable body; carries the HTTP `status` and the raw body
-* for the caller to surface.
-*/
-declare class R2SqlError extends Error {
-  readonly status: number;
+ * Thrown when R2 SQL responds with a non-2xx status, an `success: false`
+ * envelope, or an unparseable body; carries the HTTP `status` and the raw body
+ * for the caller to surface.
+ */
+declare class R2SqlError extends LunoraError {
   constructor(status: number, body: string);
 }
 /**
-* The typed R2 SQL surface bound to `ctx.r2sql` on **`ActionCtx` only**. This is
-* the exact type the generated ctx imports as
-* `import("@lunora/bindings/r2sql").R2SqlClient` — keep the name and shape stable.
-*/
+ * The typed R2 SQL surface bound to `ctx.r2sql` on **`ActionCtx` only**. This is
+ * the exact type the generated ctx imports as
+ * `import("@lunora/bindings/r2sql").R2SqlClient` — keep the name and shape stable.
+ */
 interface R2SqlClient {
   /** Run `DESCRIBE namespace.table` — column names and Iceberg types. */
   describe: (table: string) => Promise<R2SqlResult>;
@@ -289,16 +289,16 @@ interface R2SqlClient {
   showTables: (namespace: string) => Promise<R2SqlResult>;
 }
 /**
-* Build an {@link R2SqlClient}. Each query POSTs to the bucket's
-* `r2-sql/query/{bucket}` endpoint with the bearer token, then normalises the
-* envelope into {@link R2SqlResult}.
-*/
+ * Build an {@link R2SqlClient}. Each query POSTs to the bucket's
+ * `r2-sql/query/{bucket}` endpoint with the bearer token, then normalises the
+ * envelope into {@link R2SqlResult}.
+ */
 declare const createR2Sql: (config: R2SqlConfig) => R2SqlClient;
 /**
-* A windowed expression. Extends {@link Sql}, so it is usable anywhere a raw
-* fragment is; `.as(alias)` makes a `SELECT` item, and the comparison helpers
-* (`.lte`, `.gt`, `.between`, …) make `QUALIFY` conditions.
-*/
+ * A windowed expression. Extends {@link Sql}, so it is usable anywhere a raw
+ * fragment is; `.as(alias)` makes a `SELECT` item, and the comparison helpers
+ * (`.lte`, `.gt`, `.between`, …) make `QUALIFY` conditions.
+ */
 declare class WindowExpression extends Sql {
   /** Alias the expression — `... AS alias` — for use in a `SELECT` list. */
   as(alias: string): Sql;
@@ -310,18 +310,18 @@ declare class WindowExpression extends Sql {
   gt(value: unknown): Sql;
   /** `expr >= value`. */
   gte(value: unknown): Sql;
-  /** `expr &lt; value`. */
+  /** `expr < value`. */
   lt(value: unknown): Sql;
-  /** `expr &lt;= value`. */
+  /** `expr <= value`. */
   lte(value: unknown): Sql;
   private compare;
 }
 /** The `OVER (...)` window specification. */
 interface OverSpec {
   /**
-  * A raw frame clause, e.g. `"ROWS BETWEEN 2 PRECEDING AND CURRENT ROW"`.
-  * Spliced verbatim — it is keyword-only SQL, not a value.
-  */
+   * A raw frame clause, e.g. `"ROWS BETWEEN 2 PRECEDING AND CURRENT ROW"`.
+   * Spliced verbatim — it is keyword-only SQL, not a value.
+   */
   frame?: string;
   /** `ORDER BY` term(s) within the window. */
   orderBy?: OrderTerm | OrderTerm[];
@@ -329,9 +329,9 @@ interface OverSpec {
   partitionBy?: Sql | string | (Sql | string)[];
 }
 /**
-* A window function awaiting its `OVER (...)`. Call {@link WindowFunction.over |
-* .over} to bind a window and get a {@link WindowExpression}.
-*/
+ * A window function awaiting its `OVER (...)`. Call {@link WindowFunction.over |
+ * .over} to bind a window and get a {@link WindowExpression}.
+ */
 declare class WindowFunction {
   private readonly callText;
   constructor(callText: string);
@@ -339,13 +339,13 @@ declare class WindowFunction {
   over(spec?: OverSpec): WindowExpression;
 }
 /**
-* Window-function builders. Each returns a {@link WindowFunction}; chain
-* `.over(...)` to bind the window.
-*
-* Ranking: `rowNumber`, `rank`, `denseRank`, `percentRank`, `cumeDist`,
-* `ntile`. Offset/value: `lag`, `lead`, `firstValue`, `lastValue`, `nthValue`.
-* Aggregates used as windows: `sum`, `avg`, `count`, `min`, `max`.
-*/
+ * Window-function builders. Each returns a {@link WindowFunction}; chain
+ * `.over(...)` to bind the window.
+ *
+ * Ranking: `rowNumber`, `rank`, `denseRank`, `percentRank`, `cumeDist`,
+ * `ntile`. Offset/value: `lag`, `lead`, `firstValue`, `lastValue`, `nthValue`.
+ * Aggregates used as windows: `sum`, `avg`, `count`, `min`, `max`.
+ */
 declare const fn: {
   /** `AVG(column) OVER (...)`. */
   avg: (column: Sql | string) => WindowFunction;

package/dist/r2sql/index.mjs

@@ -1,7 +1 @@
-export { default as SelectBuilder } from '../packem_shared/SelectBuilder-DHaXZwn_.mjs';
-export { R2SqlError, createR2Sql } from '../packem_shared/R2SqlError-DlDd_SrE.mjs';
-export { asc, desc, renderOrderTerm } from '../packem_shared/asc-Cur-xO8v.mjs';
-export { default as SetOperation } from '../packem_shared/SetOperation-RDHcxccj.mjs';
-export { Sql, isSql, joinSql, lit, raw, sql, toText } from '../packem_shared/Sql-DceGtcUd.mjs';
-export { WindowFunction, fn } from '../packem_shared/WindowFunction-DA3pGC3N.mjs';
-export { default as WindowExpression } from '../packem_shared/WindowExpression-Cg9s2xcr.mjs';
+import{default as o}from"../packem_shared/SelectBuilder-WMBQ2b4q.mjs";import{R2SqlError as l,createR2Sql as f}from"../packem_shared/R2SqlError-Uaz0RJTR.mjs";import{asc as d,desc as i,renderOrderTerm as n}from"../packem_shared/asc-BsbdtIQU.mjs";import{default as s}from"../packem_shared/SetOperation-BrzMB1Tb.mjs";import{Sql as m,isSql as S,joinSql as q,lit as c,raw as u,sql as w,toText as E}from"../packem_shared/Sql-CwhZl1Q5.mjs";import{WindowFunction as R,fn as T}from"../packem_shared/WindowFunction-rzl4CzYE.mjs";import{default as j}from"../packem_shared/WindowExpression-CxCuEy8V.mjs";export{l as R2SqlError,o as SelectBuilder,s as SetOperation,m as Sql,j as WindowExpression,R as WindowFunction,d as asc,f as createR2Sql,i as desc,T as fn,S as isSql,q as joinSql,c as lit,u as raw,n as renderOrderTerm,w as sql,E as toText};