@wavehouse/sdk 0.0.0-dev.h7d02b5f9a5e4 → 0.0.0-dev.h97a11a9f5a0e

package/dist/index.d.cts

@@ -97,9 +97,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>;
@@ -396,6 +423,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 +442,42 @@ 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. */
+    /**
+     * 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 +523,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

@@ -97,9 +97,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>;
@@ -396,6 +423,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 +442,42 @@ 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. */
+    /**
+     * 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 +523,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) {
@@ -745,11 +746,11 @@ var QueryBuilder = class _QueryBuilder {
     if (error) return err(error);
     const rows = data;
     const hasMore = effectiveLimit != null && rows.length >= effectiveLimit;
-    if (hasMore) {
+    if (hasMore && this._state.orderBy.length > 0) {
       const nextFn = () => this._fetchNext(rows, effectiveLimit, opts);
       return okPage(rows, true, nextFn);
     }
-    return okPage(rows, false);
+    return okPage(rows, hasMore);
   }
   stream(opts) {
     const raw = this._createStream(this._state.table, opts);
@@ -792,27 +793,23 @@ var QueryBuilder = class _QueryBuilder {
     if (this._state.aggregations.length > 0) 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;
-    } else if (effectiveLimit != null && this._state.aggregations.length === 0) {
-      ast.order_by = [{ column: "received_timestamp", dir: "desc" }];
-    }
+    if (this._state.orderBy.length > 0) ast.order_by = this._state.orderBy;
     if (effectiveLimit != null) ast.limit = effectiveLimit;
     if (this._state.timeRange) ast.time_range = this._state.timeRange;
     return ast;
   }
   async _fetchNext(prevRows, _limit, opts) {
-    const orderCol = this._state.orderBy[0]?.column ?? "received_timestamp";
-    const orderDir = this._state.orderBy[0]?.dir ?? "desc";
+    const cursor = this._state.orderBy[0];
+    if (cursor == null) return okPage([], false);
+    const { column: orderCol, dir: orderDir } = cursor;
     const lastRow = prevRows[prevRows.length - 1];
     const lastValue = lastRow?.[orderCol];
     if (lastValue === void 0) return okPage([], false);
     const cursorOp = orderDir === "desc" ? "lt" : "gt";
     const cursorFilter = { column: orderCol, op: cursorOp, value: lastValue };
-    const orderBy = this._state.orderBy.length > 0 ? this._state.orderBy : [{ column: orderCol, dir: orderDir }];
     const nextBuilder = this._clone({
       filters: [...this._state.filters, cursorFilter],
-      orderBy
+      orderBy: this._state.orderBy
     });
     return nextBuilder.fetch(opts);
   }
@@ -903,6 +900,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;
@@ -931,22 +934,26 @@ var TableRef = class {
       this._createStream
     );
   }
-  /** Insert one or more rows into this table. */
+  /**
+   * 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",
@@ -959,6 +966,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, {