@wavehouse/sdk 0.0.0-dev.0f8826c → 0.0.0-dev.h04a85f20bb96

package/dist/index.d.cts

@@ -1,7 +1,9 @@
 /** User-provided database schema mapping table names to row types. */
 type Database = Record<string, Record<string, unknown>>;
 /**
- * Discriminated union for all async SDK operations. Never throws.
+ * Discriminated union for all async SDK operations. Never throws for anything
+ * the server returns — caller and environment errors (a non-absolute `baseURL`,
+ * a missing `EventSource`, a rejecting `auth` callback) do throw.
  *
  * Discriminated on `ok`: `if (result.ok)` narrows to the success arm (and tells
  * the compiler `data` is present), while `error` is always available for
@@ -47,19 +49,117 @@ interface StreamSubscriber<T = Record<string, unknown>> {
     error?: (err: WaveHouseError) => void;
 }
 interface ClientConfig<_DB extends Database = Database> {
-    /** Base URL of the WaveHouse server (e.g. "http://localhost:8080"). */
+    /**
+     * Base URL of the WaveHouse server (e.g. "http://localhost:8080"). May include
+     * a path prefix ("https://app.example.com/api/warehouse") for a WaveHouse
+     * behind a backend-for-frontend (BFF), app-server route, or path-routed
+     * ingress; request paths are appended to it. The proxy in front must strip
+     * the prefix before forwarding.
+     *
+     * Must be **absolute** — scheme and host included. The transports report a
+     * relative value such as "/api/warehouse" differently: a REST call rejects
+     * with a `TypeError` instead of returning a `Result`, while a stream reports
+     * `SSE_CONNECT_ERROR` to the subscriber's `error` callback. Build an absolute
+     * one: `` `${location.origin}/api/warehouse` ``.
+     */
     baseURL: string;
     /** Auth token provider. Omit for public/unauthenticated access. */
     auth?: () => Promise<string> | string;
     /** Additional client options. */
     options?: ClientOptions;
 }
+/**
+ * A `fetch`-compatible function.
+ *
+ * Spelled out rather than written `typeof fetch`, which resolves differently
+ * depending on whether the consumer's TypeScript `lib` includes DOM — the same
+ * signature either way, but stable across configurations.
+ *
+ * In practice the SDK only ever calls it with a string URL, and reads `.ok` and
+ * `.headers` always, `.text()` on success, and `.status`, `.statusText` plus
+ * `.json()` when the response is not `ok`. A rejection becomes a
+ * `NETWORK_ERROR` result and is retried with backoff — except a `DOMException`
+ * named `AbortError` (what the platform `fetch` and undici throw on abort),
+ * which becomes `ABORTED` and is not retried. Implementations that reject with
+ * some other abort error, such as `node-fetch`, are retried instead.
+ *
+ * Implementations shipping their own request/response declarations (undici,
+ * `node-fetch`) need casts on the URL, the init and the return value, since
+ * those types are separate from the ones behind your global `fetch`; the
+ * narrow runtime contract above is what makes them safe.
+ */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface ClientOptions {
     /** Maximum retry attempts for failed requests. Default: 2. */
     maxRetries?: number;
+    /**
+     * HTTP implementation used for every REST request (SSE streams excluded).
+     * Defaults to the global `fetch`.
+     *
+     * Provide one to route through a proxy, attach client certificates, add
+     * middleware (logging, tracing, circuit breaking), or bypass a transport bug
+     * in the runtime's bundled HTTP stack by routing through an implementation
+     * you install yourself — e.g. an undici new enough to be free of
+     * {@link https://github.com/nodejs/undici/issues/5600 | undici #5600}:
+     *
+     * ```ts
+     * import { Agent, fetch as undiciFetch } from "undici"; // npm install undici — 8.10.0+
+     * // Pass the dispatcher explicitly: undici's pool lives on a shared
+     * // globalThis symbol claimed by whichever copy loaded first, so an implied
+     * // dispatcher can still be the runtime's affected one.
+     * const dispatcher = new Agent();
+     * createClient({
+     *   baseURL,
+     *   options: {
+     *     fetch: (url, init) =>
+     *       undiciFetch(url as string, { ...init, dispatcher } as never) as unknown as Promise<Response>,
+     *   },
+     * });
+     * ```
+     *
+     * Only the SSE transport is exempt: the live connection behind `.stream()`
+     * and `.liveQuery()` uses `EventSource`, which this does not replace.
+     * `.liveQuery()`'s initial backfill is an ordinary request and does go
+     * through your function.
+     */
+    fetch?: FetchLike;
+    /**
+     * Headers added to every REST request (SSE streams excluded) — for a
+     * header-gated proxy in front of WaveHouse, such as a Cloudflare Access
+     * service token.
+     *
+     * Matched case-insensitively, as HTTP headers are. Applied underneath the
+     * SDK's own headers: `auth` still owns `Authorization`, and the
+     * `Content-Type` and `Accept` a given request needs are not overridable
+     * here — a global `Content-Type` that outranked the request's own is a
+     * documented way to break uploads.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Extra `RequestInit` fields merged into every REST request — `credentials`
+     * for a cookie-authenticated origin, `mode`, `cache`, `keepalive`, or a
+     * runtime-specific extension such as Next.js's `next: { tags }`.
+     *
+     * Fields the SDK controls (`method`, `headers`, `body`, `signal`) always
+     * win, so this cannot corrupt the request itself. Non-standard fields may
+     * need a cast, since `RequestInit` only declares the standard ones.
+     */
+    fetchOptions?: RequestInit;
 }
 interface StructuredQuery {
+    /**
+     * Explicit columns to project. A literal "*" is a column named "*", not a
+     * wildcard. Omitting columns (with no aggregations and no select_all) selects
+     * nothing — use select_all for a full-row read. Mutually exclusive with
+     * select_all.
+     */
     columns?: string[];
+    /**
+     * Request every column the caller's role may read (the all-columns wildcard,
+     * expanded server-side to the allowed/denied set). Mutually exclusive with a
+     * non-empty columns list.
+     */
+    select_all?: boolean;
     aggregations?: Aggregation[];
     filters?: QueryFilter[];
     group_by?: string[];
@@ -97,9 +197,36 @@ interface TableSchema {
     columns: Column[];
 }
 type Schemas = Record<string, TableSchema>;
+/**
+ * A per-record outcome from a batch (array / NDJSON) insert. Mirrors the
+ * single-object response shape plus the record's position. Exactly one of
+ * `ok` / `duplicate` / `error` is set.
+ */
+interface InsertRecordResult {
+    /** 1-based index of the record within the submitted batch. */
+    index: number;
+    /** Set when the record was validated and published. */
+    ok?: boolean;
+    /** Set when dedup skipped the record. */
+    duplicate?: boolean;
+    /** Set (with `ok`/`duplicate` absent) when the record was rejected. */
+    error?: string;
+}
 interface InsertResult {
+    /** True for a fully successful insert: a single row, or a batch with no rejected records (`failed === 0`). */
     ok: boolean;
+    /** Single insert only: set when dedup skipped the row. */
     duplicate?: boolean;
+    /** Batch insert (array / NDJSON): number of records submitted. */
+    total?: number;
+    /** Batch insert: records validated and published. */
+    succeeded?: number;
+    /** Batch insert: records rejected — see `results`. */
+    failed?: number;
+    /** Batch insert: records skipped by dedup. */
+    duplicates?: number;
+    /** Batch insert: per-record outcomes, each `{index, ok|duplicate|error}` (may be truncated for very large batches; the counts stay authoritative). */
+    results?: InsertRecordResult[];
 }
 interface DLQStats {
     tables: Record<string, number>;
@@ -133,8 +260,22 @@ interface RolePermissions {
     check?: Record<string, PolicyFilter>;
     allowed_aggregations?: string[];
     denied_aggregations?: string[];
+    /** Caps the query result LIMIT. 0 = no limit. */
     max_rows?: number;
-    max_execution_time_ms?: number;
+    /**
+     * Max query execution time, enforced server-side by ClickHouse. Set it as a
+     * duration string ("5s", "500ms") or a number of milliseconds; reads always
+     * return the number of milliseconds.
+     */
+    max_execution_time?: number | string;
+    /** Max rows scanned from storage, enforced server-side by ClickHouse. 0 = no limit. */
+    max_rows_to_read?: number;
+    /**
+     * Max peak query memory, enforced server-side by ClickHouse. Set it as a size
+     * string ("4GiB", "512MiB") or a number of bytes; reads always return the
+     * number of bytes.
+     */
+    max_memory_usage?: number | string;
 }
 interface PolicyFilter {
     _eq?: string;
@@ -146,10 +287,32 @@ interface PolicyFilter {
 interface ValidationResult {
     valid: boolean;
 }
-interface FetchOptions {
+/**
+ * Options for a single call, passed to `.fetch()`.
+ *
+ * Note that `await`ing a builder directly (`await wh.from("t").select("*")`)
+ * takes no options — use the explicit `.fetch({ … })` form for those.
+ */
+interface RequestOptions {
     signal?: AbortSignal;
     limit?: number;
 }
+/**
+ * Options for a single `PipeRef.fetch()` call.
+ *
+ * `limit` is declared `never` rather than simply left out. Omitting it would
+ * still admit a `RequestOptions` value that carries one — excess-property
+ * checking only rejects fresh object literals, so a variable would pass and the
+ * limit would be silently dropped, which is the whole defect this prevents.
+ *
+ * A pipe's row cap belongs in its SQL as a `{{limit}}` parameter, supplied via
+ * `wh.pipe(name, { limit })`.
+ */
+interface PipeRequestOptions {
+    signal?: AbortSignal;
+    /** Not supported on pipes — pass `limit` as a pipe parameter instead. */
+    limit?: never;
+}
 interface StreamOptions {
     since?: string;
     signal?: AbortSignal;
@@ -160,6 +323,9 @@ interface HttpContext {
     auth?: () => Promise<string> | string;
     options: {
         maxRetries: number;
+        fetch?: FetchLike;
+        headers?: Record<string, string>;
+        fetchOptions?: RequestInit;
     };
 }
 
@@ -236,8 +402,15 @@ declare class PipeRef<Row = Record<string, unknown>> implements PromiseLike<Resu
     private readonly _params?;
     private readonly _createStream;
     constructor(ctx: HttpContext, name: string, params: Record<string, unknown> | undefined, createStream: CreateStreamFn$2<Row>);
-    /** Execute the pipe and return results. */
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    /**
+     * Execute the pipe and return results.
+     *
+     * Takes only `signal` — deliberately narrower than the `RequestOptions` the
+     * query builder accepts. The pipes endpoint binds the body as the pipe's
+     * parameters, so there is no row cap to forward; give the pipe a `{{limit}}`
+     * parameter in its SQL and pass it via `wh.pipe(name, { limit })`.
+     */
+    fetch(opts?: PipeRequestOptions): Promise<Result<Row[]>>;
     /** Subscribe to live events from the pipe's underlying query. */
     stream(opts?: StreamOptions): StreamController<Row>;
     then<TResult1 = Result<Row[]>, TResult2 = never>(onfulfilled?: ((value: Result<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
@@ -339,6 +512,7 @@ declare class LiveQuery<T = Record<string, unknown>> {
 interface QueryState {
     table: string;
     columns: string[];
+    selectAll?: boolean;
     aggregations: Aggregation[];
     filters: QueryFilter[];
     groupBy: string[];
@@ -361,6 +535,13 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
     private readonly _createStream;
     constructor(ctx: HttpContext, state: QueryState, createStream: CreateStreamFn$1<Row>);
     select(...columns: string[]): QueryBuilder<Row>;
+    /**
+     * Select every column the caller's role is allowed to read (the all-columns
+     * wildcard). Use this instead of `.select(...)` when you want a full-row read;
+     * a bare `.fetch()` with no `.select()` does this implicitly. Mutually
+     * exclusive with `.select(...)`.
+     */
+    selectAll(): QueryBuilder<Row>;
     where(column: string, op: FilterOp, value: unknown): QueryBuilder<Row>;
     count(column?: string, alias?: string): QueryBuilder<Row>;
     sum(column: string, alias?: string): QueryBuilder<Row>;
@@ -374,9 +555,9 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
     limit(n: number): QueryBuilder<Row>;
     timeRange(column: string, since: string, until?: string): QueryBuilder<Row>;
     cacheTTL(seconds: number): QueryBuilder<Row>;
-    /** Default row limit when none is specified. Matches backend DefaultMaxRows. */
+    /** Default row limit when none is specified — deliberately tighter than the backend's DefaultMaxRows (10000) safety cap. */
     static readonly DEFAULT_LIMIT = 1000;
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    fetch(opts?: RequestOptions): Promise<Result<Row[]>>;
     stream(opts?: StreamOptions): StreamController<Row>;
     /**
      * Start a live query: fetches historical data, then streams live updates.
@@ -396,6 +577,12 @@ declare class QueryBuilder<Row = Record<string, unknown>> implements PromiseLike
 }
 
 type CreateStreamFn<Row> = (table: string, opts?: StreamOptions) => StreamController<Row>;
+/**
+ * Accepted sources for {@link TableRef.insertNDJSON}: a string, raw bytes, a
+ * Blob/File (browser file inputs), or a byte stream. Non-string sources are
+ * read fully before sending.
+ */
+type NDJSONSource = string | Uint8Array | Blob | ReadableStream<Uint8Array>;
 /**
  * Reference to a table. NOT thenable — safe to pass around without triggering requests.
  * Use `.fetch()`, `.select()`, `.insert()`, `.schema()`, or `.stream()` to act on it.
@@ -406,13 +593,51 @@ declare class TableRef<Row = Record<string, unknown>> {
     private readonly _createStream;
     constructor(ctx: HttpContext, table: string, createStream: CreateStreamFn<Row>);
     /** SELECT * shortcut — fetches rows with optional pagination. */
-    fetch(opts?: FetchOptions): Promise<Result<Row[]>>;
+    fetch(opts?: RequestOptions): Promise<Result<Row[]>>;
     /** Start building a typed query. Returns an immutable, PromiseLike QueryBuilder. */
     select(...columns: string[]): QueryBuilder<Row>;
-    /** Insert one or more rows into this table. */
+    /**
+     * Start a query that selects every column the caller's role is allowed to read
+     * (the all-columns wildcard). Use instead of `.select(...)` for an explicit
+     * full-row read; `.fetch()` does this implicitly.
+     */
+    selectAll(): QueryBuilder<Row>;
+    /**
+     * Insert one or more rows into this table.
+     *
+     * A single object is sent as a JSON `POST /v1/ingest`. An **array** is
+     * serialized to NDJSON (one record per line) and sent as a single
+     * `application/x-ndjson` request: a bad record no longer fails or hides the
+     * rest of the batch — per-record outcomes come back in the result
+     * (`failed` / `results`), and `ok` is true only when every record succeeded.
+     *
+     * The array path sends one request regardless of size; bounded-concurrency
+     * chunking of very large arrays is tracked separately (#196). For NDJSON you
+     * already have (a file or stream), use {@link insertNDJSON}.
+     */
     insert(data: Partial<Row> | Partial<Row>[], opts?: {
         signal?: AbortSignal;
     }): Promise<Result<InsertResult>>;
+    /**
+     * Insert pre-formatted NDJSON (newline-delimited JSON, one record per line)
+     * from a string, raw bytes, a Blob/File, or a byte stream — e.g. a `.ndjson`
+     * file or a stream produced by another system. For in-memory rows, prefer
+     * {@link insert}.
+     *
+     * Non-string sources are read fully into memory before sending (the server
+     * streams the parse). Returns the same per-record batch summary as an array
+     * `insert`.
+     */
+    insertNDJSON(source: NDJSONSource, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Result<InsertResult>>;
+    /**
+     * @internal Send an NDJSON body and map the server's batch response onto an
+     * {@link InsertResult}. A transport / whole-request failure surfaces as the
+     * Result error arm; a processed batch (even with rejected records) surfaces
+     * as the success arm with `ok = failed === 0`.
+     */
+    private _sendNDJSON;
     /** Fetch the schema for this table. */
     schema(opts?: {
         signal?: AbortSignal;
@@ -458,4 +683,4 @@ declare class WaveHouseClient<DB extends Database = Database> {
 /** Create a new WaveHouse client instance. */
 declare function createClient<DB extends Database = Database>(config: ClientConfig<DB>): WaveHouseClient<DB>;
 
-export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchOptions, type FilterOp, type InsertResult, LiveQuery, type OrderClause, type ParamDef, type Pipe, PipeRef, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };
+export { type Aggregation, type ClientConfig, type ClientOptions, type Column, DLQNamespace, type DLQStats, type Database, type FetchLike, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, type OrderClause, type ParamDef, type Pipe, PipeRef, type PipeRequestOptions, PipesNamespace, type Policy, type PolicyFilter, PolicyNamespace, QueryBuilder, type QueryFilter, type RequestOptions, type Result, type RolePermissions, SchemaNamespace, type Schemas, StreamController, type StreamEvent, type StreamOptions, type StreamStatus, type StreamSubscriber, type StructuredQuery, SysNamespace, type TablePolicy, TableRef, type TableSchema, type TimeRange, type ValidationResult, WaveHouseClient, type WaveHouseError, createClient };