@wavehouse/sdk 0.0.0-dev.h825a5d7fa405 → 0.0.0-dev.hab0797ca5a74

package/dist/index.d.cts

@@ -59,7 +59,19 @@ interface ClientOptions {
     maxRetries?: number;
 }
 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 +109,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>;
@@ -339,6 +378,7 @@ declare class LiveQuery<T = Record<string, unknown>> {
 interface QueryState {
     table: string;
     columns: string[];
+    selectAll?: boolean;
     aggregations: Aggregation[];
     filters: QueryFilter[];
     groupBy: string[];
@@ -361,6 +401,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>;
@@ -396,6 +443,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.
@@ -409,10 +462,48 @@ declare class TableRef<Row = Record<string, unknown>> {
     fetch(opts?: FetchOptions): 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 +549,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 FetchOptions, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, 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 };

package/dist/index.d.ts

@@ -59,7 +59,19 @@ interface ClientOptions {
     maxRetries?: number;
 }
 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 +109,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>;
@@ -339,6 +378,7 @@ declare class LiveQuery<T = Record<string, unknown>> {
 interface QueryState {
     table: string;
     columns: string[];
+    selectAll?: boolean;
     aggregations: Aggregation[];
     filters: QueryFilter[];
     groupBy: string[];
@@ -361,6 +401,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>;
@@ -396,6 +443,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.
@@ -409,10 +462,48 @@ declare class TableRef<Row = Record<string, unknown>> {
     fetch(opts?: FetchOptions): 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 +549,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 FetchOptions, type FilterOp, type InsertRecordResult, type InsertResult, LiveQuery, type NDJSONSource, 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 };

package/dist/index.js

@@ -39,9 +39,10 @@ function err(error) {
 async function request(ctx, opts) {
   const url = buildURL(ctx.baseURL, opts.path, opts.params);
   const headers = {
-    "Content-Type": "application/json",
+    "Content-Type": opts.contentType ?? "application/json",
     Accept: "application/json"
   };
+  const requestBody = opts.rawBody !== void 0 ? opts.rawBody : opts.body !== void 0 ? JSON.stringify(opts.body) : void 0;
   if (ctx.auth) {
     const token = await ctx.auth();
     if (token) {
@@ -55,7 +56,7 @@ async function request(ctx, opts) {
       const res = await fetch(url, {
         method: opts.method,
         headers,
-        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0,
+        body: requestBody,
         signal: opts.signal
       });
       if (res.ok) {
@@ -690,6 +691,15 @@ var QueryBuilder = class _QueryBuilder {
   select(...columns) {
     return this._clone({ columns: [...this._state.columns, ...columns] });
   }
+  /**
+   * 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() {
+    return this._clone({ selectAll: true });
+  }
   where(column, op, value) {
     const filter = { column, op: OP_MAP[op], value };
     return this._clone({ filters: [...this._state.filters, filter] });
@@ -788,8 +798,16 @@ var QueryBuilder = class _QueryBuilder {
   }
   _buildAST(effectiveLimit) {
     const ast = {};
-    if (this._state.columns.length > 0) ast.columns = this._state.columns;
-    if (this._state.aggregations.length > 0) ast.aggregations = this._state.aggregations;
+    const hasColumns = this._state.columns.length > 0;
+    const hasAggs = this._state.aggregations.length > 0;
+    if (this._state.selectAll) {
+      ast.select_all = true;
+    } else if (hasColumns) {
+      ast.columns = this._state.columns;
+    } else if (!hasAggs) {
+      ast.select_all = true;
+    }
+    if (hasAggs) ast.aggregations = this._state.aggregations;
     if (this._state.filters.length > 0) ast.filters = this._state.filters;
     if (this._state.groupBy.length > 0) ast.group_by = this._state.groupBy;
     if (this._state.orderBy.length > 0) ast.order_by = this._state.orderBy;
@@ -899,6 +917,12 @@ function projectColumns(row, columns) {
 }
 
 // src/table.ts
+var NDJSON_CONTENT_TYPE = "application/x-ndjson";
+async function ndjsonSourceToString(source) {
+  if (typeof source === "string") return source;
+  if (source instanceof Uint8Array) return new TextDecoder().decode(source);
+  return new Response(source).text();
+}
 var TableRef = class {
   _ctx;
   _table;
@@ -927,22 +951,34 @@ var TableRef = class {
       this._createStream
     );
   }
-  /** 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() {
+    return this.select().selectAll();
+  }
+  /**
+   * 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}.
+   */
   async insert(data, opts) {
     if (Array.isArray(data)) {
-      const promises = data.map(
-        (row) => request(this._ctx, {
-          method: "POST",
-          path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
-          body: row,
-          signal: opts?.signal
-        })
-      );
-      const results = await Promise.all(promises);
-      for (const res2 of results) {
-        if (res2.error) return err(res2.error);
+      if (data.length === 0) {
+        return ok({ ok: true, total: 0, succeeded: 0, failed: 0, duplicates: 0, results: [] });
       }
-      return ok({ ok: true });
+      const ndjson = data.map((row) => JSON.stringify(row)).join("\n");
+      return this._sendNDJSON(ndjson, opts);
     }
     const { data: res, error } = await request(this._ctx, {
       method: "POST",
@@ -955,6 +991,46 @@ var TableRef = class {
     if (res?.duplicate != null) result.duplicate = res.duplicate;
     return ok(result);
   }
+  /**
+   * 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`.
+   */
+  async insertNDJSON(source, opts) {
+    const ndjson = await ndjsonSourceToString(source);
+    return this._sendNDJSON(ndjson, opts);
+  }
+  /**
+   * @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`.
+   */
+  async _sendNDJSON(ndjson, opts) {
+    const { data, error } = await request(this._ctx, {
+      method: "POST",
+      path: `/v1/ingest?table=${encodeURIComponent(this._table)}`,
+      rawBody: ndjson,
+      contentType: NDJSON_CONTENT_TYPE,
+      signal: opts?.signal
+    });
+    if (error) return err(error);
+    const r = data ?? { total: 0, succeeded: 0, failed: 0, duplicates: 0 };
+    const result = {
+      ok: r.failed === 0,
+      total: r.total,
+      succeeded: r.succeeded,
+      failed: r.failed,
+      duplicates: r.duplicates
+    };
+    if (r.results && r.results.length > 0) result.results = r.results;
+    return ok(result);
+  }
   /** Fetch the schema for this table. */
   async schema(opts) {
     const { data, error } = await request(this._ctx, {