@functional-systems/lambdadb 0.3.0-dev.2 → 0.3.0-dev.3

package/src/client.ts

@@ -26,15 +26,73 @@ import { collectionsDocsListDocs } from "./funcs/collectionsDocsListDocs.js";
 import { collectionsDocsUpdate } from "./funcs/collectionsDocsUpdate.js";
 import { collectionsDocsUpsert } from "./funcs/collectionsDocsUpsert.js";
 import type { RequestOptions } from "./lib/sdks.js";
+import { unwrapAsync, OK, ERR } from "./types/fp.js";
+import type { Result } from "./types/fp.js";
 import type * as operations from "./models/operations/index.js";
 import type * as models from "./models/index.js";
-import { unwrapAsync } from "./types/fp.js";
+import type {
+  CreateCollectionInput,
+  UpdateCollectionInput,
+  QueryCollectionInput,
+  QueryCollectionResponse,
+  QueryCollectionDoc,
+  ListDocsInput,
+  ListDocsResponse,
+  UpsertDocsInput,
+  UpdateDocsInput,
+  DeleteDocsInput,
+  FetchDocsInput,
+  FetchDocsResponse,
+  FetchDocsDoc,
+  BulkUpsertInput,
+  MessageResponse,
+  ListCollectionsResponse,
+  CreateCollectionResponse,
+  GetCollectionResponse,
+  UpdateCollectionResponse,
+  GetBulkUpsertDocsResponse,
+} from "./types/public.js";
+import type {
+  ListCollectionsError,
+  CreateCollectionError,
+  GetCollectionError,
+  UpdateCollectionError,
+  DeleteCollectionError,
+  QueryCollectionError,
+  ListDocsError,
+  UpsertDocsError,
+  UpdateDocsError,
+  DeleteDocsError,
+  FetchDocsError,
+  GetBulkUpsertDocsError,
+  BulkUpsertDocsError,
+} from "./types/errors.js";
 
 export type { RequestOptions };
 
-// Re-export common types for facade users
+// Re-export public API types (request-body–level inputs and method return types)
+export type * from "./types/public.js";
+
+/**
+ * @deprecated Use types from the package root (e.g. CreateCollectionInput, QueryCollectionResponse, ListDocsInput). Will be removed in the next major version.
+ */
 export type { operations, models };
 
+/**
+ * Fetches documents from a presigned docsUrl. Response must be { docs: [...] }.
+ */
+async function fetchDocsFromUrl<T>(docsUrl: string): Promise<T[]> {
+  const res = await fetch(docsUrl);
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(
+      `Failed to fetch documents from URL: ${res.status} ${res.statusText}${text ? ` - ${text}` : ""}`,
+    );
+  }
+  const json = (await res.json()) as { docs?: T[] };
+  return json.docs ?? [];
+}
+
 /** Default base URL for the LambdaDB API. */
 export const DEFAULT_BASE_URL = "https://api.lambdadb.ai";
 /** Default project name when not specified. */
@@ -103,15 +161,34 @@ export class LambdaDBClient extends LambdaDBCore {
     return unwrapAsync(collectionsList(this, options));
   }
 
+  /**
+   * List all collections (Safe: returns Result instead of throwing).
+   */
+  async listCollectionsSafe(
+    options?: RequestOptions,
+  ): Promise<Result<ListCollectionsResponse, ListCollectionsError>> {
+    return await collectionsList(this, options);
+  }
+
   /**
    * Create a new collection.
    */
   async createCollection(
-    request: operations.CreateCollectionRequest,
+    request: CreateCollectionInput,
     options?: RequestOptions,
   ) {
     return unwrapAsync(collectionsCreate(this, request, options));
   }
+
+  /**
+   * Create a new collection (Safe: returns Result instead of throwing).
+   */
+  async createCollectionSafe(
+    request: CreateCollectionInput,
+    options?: RequestOptions,
+  ): Promise<Result<CreateCollectionResponse, CreateCollectionError>> {
+    return await collectionsCreate(this, request, options);
+  }
 }
 
 /**
@@ -132,11 +209,20 @@ export class CollectionHandle {
     );
   }
 
+  /**
+   * Get metadata of this collection (Safe: returns Result instead of throwing).
+   */
+  async getSafe(
+    options?: RequestOptions,
+  ): Promise<Result<GetCollectionResponse, GetCollectionError>> {
+    return await collectionsGet(this.client, { collectionName: this.collectionName }, options);
+  }
+
   /**
    * Configure (update) this collection.
    */
   async update(
-    requestBody: operations.UpdateCollectionRequestBody,
+    requestBody: UpdateCollectionInput,
     options?: RequestOptions,
   ) {
     return unwrapAsync(
@@ -151,6 +237,20 @@ export class CollectionHandle {
     );
   }
 
+  /**
+   * Configure (update) this collection (Safe: returns Result instead of throwing).
+   */
+  async updateSafe(
+    requestBody: UpdateCollectionInput,
+    options?: RequestOptions,
+  ): Promise<Result<UpdateCollectionResponse, UpdateCollectionError>> {
+    return await collectionsUpdate(
+      this.client,
+      { collectionName: this.collectionName, requestBody },
+      options,
+    );
+  }
+
   /**
    * Delete this collection.
    */
@@ -164,14 +264,29 @@ export class CollectionHandle {
     );
   }
 
+  /**
+   * Delete this collection (Safe: returns Result instead of throwing).
+   */
+  async deleteSafe(
+    options?: RequestOptions,
+  ): Promise<Result<MessageResponse, DeleteCollectionError>> {
+    return await collectionsDelete(
+      this.client,
+      { collectionName: this.collectionName },
+      options,
+    );
+  }
+
   /**
    * Search this collection with a query.
+   * When the API returns docs via docsUrl (isDocsInline false), documents are
+   * fetched from the presigned URL automatically so the response always has docs.
    */
   async query(
-    requestBody: operations.QueryCollectionRequestBody,
+    requestBody: QueryCollectionInput,
     options?: RequestOptions,
-  ) {
-    return unwrapAsync(
+  ): Promise<QueryCollectionResponse> {
+    const result = await unwrapAsync(
       collectionsQuery(
         this.client,
         {
@@ -181,6 +296,38 @@ export class CollectionHandle {
         options,
       ),
     );
+    if (!result.isDocsInline && result.docsUrl) {
+      const docs = await fetchDocsFromUrl<QueryCollectionDoc>(
+        result.docsUrl,
+      );
+      return { ...result, docs, isDocsInline: true };
+    }
+    return result;
+  }
+
+  /**
+   * Search this collection with a query (Safe: returns Result instead of throwing).
+   * When the API returns docs via docsUrl, documents are fetched from the presigned URL automatically.
+   */
+  async querySafe(
+    requestBody: QueryCollectionInput,
+    options?: RequestOptions,
+  ): Promise<Result<QueryCollectionResponse, QueryCollectionError>> {
+    const result = await collectionsQuery(
+      this.client,
+      { collectionName: this.collectionName, requestBody },
+      options,
+    );
+    if (!result.ok) return result;
+    if (!result.value.isDocsInline && result.value.docsUrl) {
+      try {
+        const docs = await fetchDocsFromUrl<QueryCollectionDoc>(result.value.docsUrl);
+        return OK({ ...result.value, docs, isDocsInline: true });
+      } catch (e) {
+        return ERR(e as QueryCollectionError);
+      }
+    }
+    return result;
   }
 
   readonly docs: CollectionDocs = new CollectionDocs(this.client, this.collectionName);
@@ -199,7 +346,7 @@ class CollectionDocs {
    * List documents in the collection.
    */
   async list(
-    params?: { size?: number; pageToken?: string },
+    params?: ListDocsInput,
     options?: RequestOptions,
   ) {
     return unwrapAsync(
@@ -211,13 +358,72 @@ class CollectionDocs {
     );
   }
 
+  /**
+   * List documents in the collection (Safe: returns Result instead of throwing).
+   */
+  async listSafe(
+    params?: ListDocsInput,
+    options?: RequestOptions,
+  ): Promise<Result<ListDocsResponse, ListDocsError>> {
+    return await collectionsDocsListDocs(
+      this.client,
+      { collectionName: this.collectionName, ...params },
+      options,
+    );
+  }
+
+  /**
+   * Iterate over all pages of documents. Yields one page per API response (with docs and nextPageToken).
+   * Use this to process large result sets without loading everything into memory.
+   *
+   * Note: The API limits response size by payload, not by document count. The number of docs per page
+   * may be less than the requested `size` and can vary from page to page.
+   *
+   * @example
+   * for await (const page of collection.docs.listPages({ size: 50 })) {
+   *   console.log(page.docs.length, page.nextPageToken ?? "last page");
+   * }
+   */
+  async *listPages(
+    params?: ListDocsInput,
+    options?: RequestOptions,
+  ): AsyncGenerator<ListDocsResponse> {
+    let pageToken: string | undefined = params?.pageToken;
+    const baseParams: ListDocsInput = { size: params?.size, pageToken };
+    while (true) {
+      const page = await this.list({ ...baseParams, pageToken }, options);
+      yield page;
+      pageToken = page.nextPageToken;
+      if (pageToken == null || pageToken === "") break;
+    }
+  }
+
+  /**
+   * Fetch all documents across pages and return a single list. Uses listPages internally.
+   * For large collections, prefer listPages() to avoid high memory use.
+   *
+   * Note: Page size is constrained by API payload limits, so the number of docs per page may vary.
+   */
+  async listAll(
+    params?: ListDocsInput,
+    options?: RequestOptions,
+  ): Promise<{ docs: Array<Record<string, unknown>>; total: number }> {
+    const docs: Array<Record<string, unknown>> = [];
+    let total = 0;
+    for await (const page of this.listPages(params, options)) {
+      docs.push(...page.docs);
+      total = page.total;
+    }
+    return { docs, total };
+  }
+
   /**
    * Upsert documents. Max payload 6MB.
    */
   async upsert(
-    body: { docs: Array<Record<string, unknown>> },
+    body: UpsertDocsInput,
     options?: RequestOptions,
-  ): Promise<models.MessageResponse> {
+  ): Promise<MessageResponse> {
     return unwrapAsync(
       collectionsDocsUpsert(
         this.client,
@@ -230,13 +436,27 @@ class CollectionDocs {
     );
   }
 
+  /**
+   * Upsert documents (Safe: returns Result instead of throwing). Max payload 6MB.
+   */
+  async upsertSafe(
+    body: UpsertDocsInput,
+    options?: RequestOptions,
+  ): Promise<Result<MessageResponse, UpsertDocsError>> {
+    return await collectionsDocsUpsert(
+      this.client,
+      { collectionName: this.collectionName, requestBody: body },
+      options,
+    );
+  }
+
   /**
    * Update documents (each doc must have id). Max payload 6MB.
    */
   async update(
-    body: { docs: Array<Record<string, unknown>> },
+    body: UpdateDocsInput,
     options?: RequestOptions,
-  ): Promise<models.MessageResponse> {
+  ): Promise<MessageResponse> {
     return unwrapAsync(
       collectionsDocsUpdate(
         this.client,
@@ -249,13 +469,27 @@ class CollectionDocs {
     );
   }
 
+  /**
+   * Update documents (Safe: returns Result instead of throwing). Max payload 6MB.
+   */
+  async updateSafe(
+    body: UpdateDocsInput,
+    options?: RequestOptions,
+  ): Promise<Result<MessageResponse, UpdateDocsError>> {
+    return await collectionsDocsUpdate(
+      this.client,
+      { collectionName: this.collectionName, requestBody: body },
+      options,
+    );
+  }
+
   /**
    * Delete documents by ids and/or filter.
    */
   async delete(
-    body: operations.DeleteDocsRequestBody,
+    body: DeleteDocsInput,
     options?: RequestOptions,
-  ): Promise<models.MessageResponse> {
+  ): Promise<MessageResponse> {
     return unwrapAsync(
       collectionsDocsDelete(
         this.client,
@@ -268,14 +502,30 @@ class CollectionDocs {
     );
   }
 
+  /**
+   * Delete documents by ids and/or filter (Safe: returns Result instead of throwing).
+   */
+  async deleteSafe(
+    body: DeleteDocsInput,
+    options?: RequestOptions,
+  ): Promise<Result<MessageResponse, DeleteDocsError>> {
+    return await collectionsDocsDelete(
+      this.client,
+      { collectionName: this.collectionName, requestBody: body },
+      options,
+    );
+  }
+
   /**
    * Fetch documents by IDs (max 100).
+   * When the API returns docs via docsUrl (isDocsInline false), documents are
+   * fetched from the presigned URL automatically so the response always has docs.
    */
   async fetch(
-    body: operations.FetchDocsRequestBody,
+    body: FetchDocsInput,
     options?: RequestOptions,
-  ) {
-    return unwrapAsync(
+  ): Promise<FetchDocsResponse> {
+    const result = await unwrapAsync(
       collectionsDocsFetch(
         this.client,
         {
@@ -285,6 +535,38 @@ class CollectionDocs {
         options,
       ),
     );
+    if (!result.isDocsInline && result.docsUrl) {
+      const docs = await fetchDocsFromUrl<FetchDocsDoc>(
+        result.docsUrl,
+      );
+      return { ...result, docs, isDocsInline: true };
+    }
+    return result;
+  }
+
+  /**
+   * Fetch documents by IDs (Safe: returns Result instead of throwing).
+   * When the API returns docs via docsUrl, documents are fetched from the presigned URL automatically.
+   */
+  async fetchSafe(
+    body: FetchDocsInput,
+    options?: RequestOptions,
+  ): Promise<Result<FetchDocsResponse, FetchDocsError>> {
+    const result = await collectionsDocsFetch(
+      this.client,
+      { collectionName: this.collectionName, requestBody: body },
+      options,
+    );
+    if (!result.ok) return result;
+    if (!result.value.isDocsInline && result.value.docsUrl) {
+      try {
+        const docs = await fetchDocsFromUrl<FetchDocsDoc>(result.value.docsUrl);
+        return OK({ ...result.value, docs, isDocsInline: true });
+      } catch (e) {
+        return ERR(e as FetchDocsError);
+      }
+    }
+    return result;
   }
 
   /**
@@ -300,13 +582,26 @@ class CollectionDocs {
     );
   }
 
+  /**
+   * Get presigned URL and metadata for bulk upload (Safe: returns Result instead of throwing).
+   */
+  async getBulkUpsertSafe(
+    options?: RequestOptions,
+  ): Promise<Result<GetBulkUpsertDocsResponse, GetBulkUpsertDocsError>> {
+    return await collectionsDocsGetBulkUpsert(
+      this.client,
+      { collectionName: this.collectionName },
+      options,
+    );
+  }
+
   /**
    * Trigger bulk upsert with an object key from getBulkUpsert().
    */
   async bulkUpsert(
-    body: { objectKey: string },
+    body: BulkUpsertInput,
     options?: RequestOptions,
-  ): Promise<models.MessageResponse> {
+  ): Promise<MessageResponse> {
     return unwrapAsync(
       collectionsDocsBulkUpsert(
         this.client,
@@ -318,4 +613,100 @@ class CollectionDocs {
       ),
     );
   }
+
+  /**
+   * Trigger bulk upsert (Safe: returns Result instead of throwing).
+   */
+  async bulkUpsertSafe(
+    body: BulkUpsertInput,
+    options?: RequestOptions,
+  ): Promise<Result<MessageResponse, BulkUpsertDocsError>> {
+    return await collectionsDocsBulkUpsert(
+      this.client,
+      { collectionName: this.collectionName, requestBody: body },
+      options,
+    );
+  }
+
+  /**
+   * Bulk upsert documents in one call (up to 200MB). Abstracts getBulkUpsert,
+   * S3 upload via presigned URL, and bulkUpsert. Use this for better DX when
+   * you have a document list; use getBulkUpsert + bulkUpsert for low-level control.
+   */
+  async bulkUpsertDocs(
+    body: UpsertDocsInput,
+    options?: RequestOptions,
+  ): Promise<MessageResponse> {
+    const { url, type, httpMethod, objectKey, sizeLimitBytes } = await this.getBulkUpsert(options);
+
+    const payload = { docs: body.docs };
+    const jsonString = JSON.stringify(payload);
+    const sizeBytes = new TextEncoder().encode(jsonString).length;
+    if (sizeBytes > sizeLimitBytes) {
+      throw new Error(
+        `Bulk upsert payload size (${sizeBytes} bytes) exceeds limit (${sizeLimitBytes} bytes)`,
+      );
+    }
+
+    const putResponse = await fetch(url, {
+      method: httpMethod,
+      headers: { "Content-Type": type },
+      body: jsonString,
+    });
+
+    if (!putResponse.ok) {
+      const text = await putResponse.text();
+      throw new Error(
+        `Bulk upsert upload failed: ${putResponse.status} ${putResponse.statusText}${text ? ` - ${text}` : ""}`,
+      );
+    }
+
+    return this.bulkUpsert({ objectKey }, options);
+  }
+
+  /**
+   * Bulk upsert documents in one call (Safe: returns Result instead of throwing).
+   * May return Error for local failures (payload size, upload). API errors use GetBulkUpsertDocsError or BulkUpsertDocsError.
+   */
+  async bulkUpsertDocsSafe(
+    body: UpsertDocsInput,
+    options?: RequestOptions,
+  ): Promise<
+    Result<
+      MessageResponse,
+      GetBulkUpsertDocsError | BulkUpsertDocsError | Error
+    >
+  > {
+    const getResult = await this.getBulkUpsertSafe(options);
+    if (!getResult.ok) return getResult;
+    const { url, type, httpMethod, objectKey, sizeLimitBytes } = getResult.value;
+
+    const payload = { docs: body.docs };
+    const jsonString = JSON.stringify(payload);
+    const sizeBytes = new TextEncoder().encode(jsonString).length;
+    if (sizeBytes > sizeLimitBytes) {
+      return ERR(
+        new Error(
+          `Bulk upsert payload size (${sizeBytes} bytes) exceeds limit (${sizeLimitBytes} bytes)`,
+        ),
+      );
+    }
+
+    const putResponse = await fetch(url, {
+      method: httpMethod,
+      headers: { "Content-Type": type },
+      body: jsonString,
+    });
+
+    if (!putResponse.ok) {
+      const text = await putResponse.text();
+      return ERR(
+        new Error(
+          `Bulk upsert upload failed: ${putResponse.status} ${putResponse.statusText}${text ? ` - ${text}` : ""}`,
+        ),
+      );
+    }
+
+    return this.bulkUpsertSafe({ objectKey }, options);
+  }
 }

package/src/index.ts

@@ -8,7 +8,7 @@ export { HTTPClient } from "./lib/http.js";
 export type { Fetcher, HTTPClientOptions } from "./lib/http.js";
 export * from "./sdk/sdk.js";
 
-/** Collection-scoped client (recommended). See docs/REFACTORING_PROPOSAL.md */
+/** Collection-scoped client (recommended). See docs/REFACTORING_STATUS.md */
 export {
   LambdaDBClient,
   CollectionHandle,
@@ -17,3 +17,27 @@ export {
   type RequestOptions as ClientRequestOptions,
   type LambdaDBClientOptions,
 } from "./client.js";
+
+/** Public API types (inputs and responses for the collection-scoped client). */
+export type * from "./types/public.js";
+
+/** Result type and helpers for Safe methods. */
+export type { Result } from "./types/fp.js";
+export { OK, ERR } from "./types/fp.js";
+
+/** Error classes and per-operation error unions for Safe methods and instanceof checks. */
+export * from "./types/errors.js";
+
+/** Query input helper for collection.query() / collection.querySafe(). */
+export {
+  createQueryInput,
+  type CreateQueryInputOptions,
+} from "./lib/queryInput.js";
+
+/** Retry config type for LambdaDBClientOptions and RequestOptions. */
+export type { RetryConfig } from "./lib/retries.js";
+
+/**
+ * @deprecated Use types from the package root (e.g. CreateCollectionInput, QueryCollectionResponse). Will be removed in the next major version.
+ */
+export type { operations, models } from "./client.js";

package/src/lib/queryInput.ts

@@ -0,0 +1,33 @@
+/**
+ * Helper to build QueryCollectionInput for collection.query() / collection.querySafe().
+ */
+
+import type { FieldsSelectorUnion, PartitionFilter } from "../models/index.js";
+import type { QueryCollectionInput } from "../types/public.js";
+
+/**
+ * Options for createQueryInput (all optional except query).
+ */
+export type CreateQueryInputOptions = {
+  size?: number;
+  consistentRead?: boolean;
+  includeVectors?: boolean;
+  sort?: Array<{ [k: string]: unknown }>;
+  fields?: FieldsSelectorUnion;
+  partitionFilter?: PartitionFilter;
+};
+
+/**
+ * Build a query input object for collection.query() or collection.querySafe().
+ * Pass the required query object (e.g. text search or vector search params) and optional options.
+ *
+ * @example
+ * const input = createQueryInput({ text: "hello" }, { size: 10 });
+ * const result = await collection.query(input);
+ */
+export function createQueryInput(
+  query: { [k: string]: unknown },
+  options?: CreateQueryInputOptions,
+): QueryCollectionInput {
+  return { query, ...options };
+}