@functional-systems/lambdadb 0.3.1 → 0.3.3

package/dist/esm/types/public.js.map

@@ -1 +1 @@
-{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/types/public.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0EH;;GAEG;AACH,MAAM,UAAU,2BAA2B,CACzC,CAA0B;IAE1B,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAgC,EAAE,GAAG,IAAI,EAAE,CAAC;IACrD,IAAI,SAAS,IAAI,IAAI;QAAE,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAClE,IAAI,SAAS,IAAI,IAAI;QAAE,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAClE,IAAI,aAAa,IAAI,IAAI;QACvB,GAAG,CAAC,aAAa,GAAG,IAAI,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACrD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gCAAgC,CAAC,GAGhD;IACC,MAAM,GAAG,GAAqC;QAC5C,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,2BAA2B,CAAC;KAC9D,CAAC;IACF,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS;QAAE,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IAC3E,OAAO,GAAG,CAAC;AACb,CAAC;AAOD,uEAAuE;AACvE,MAAM,UAAU,8BAA8B,CAAC,GAE9C;IACC,OAAO,EAAE,UAAU,EAAE,2BAA2B,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;AACrE,CAAC"}
+{"version":3,"file":"public.js","sourceRoot":"","sources":["../../../src/types/public.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6EH;;GAEG;AACH,MAAM,UAAU,2BAA2B,CACzC,CAA0B;IAE1B,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAgC,EAAE,GAAG,IAAI,EAAE,CAAC;IACrD,IAAI,SAAS,IAAI,IAAI;QAAE,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAClE,IAAI,SAAS,IAAI,IAAI;QAAE,GAAG,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAClE,IAAI,aAAa,IAAI,IAAI;QACvB,GAAG,CAAC,aAAa,GAAG,IAAI,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACrD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gCAAgC,CAAC,GAGhD;IACC,MAAM,GAAG,GAAqC;QAC5C,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,2BAA2B,CAAC;KAC9D,CAAC;IACF,IAAI,GAAG,CAAC,aAAa,KAAK,SAAS;QAAE,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IAC3E,OAAO,GAAG,CAAC;AACb,CAAC;AAOD,uEAAuE;AACvE,MAAM,UAAU,8BAA8B,CAAC,GAE9C;IACC,OAAO,EAAE,UAAU,EAAE,2BAA2B,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@functional-systems/lambdadb",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "author": "Functional Systems, Inc.",
   "homepage": "https://github.com/lambdadb/lambdadb-typescript-client#readme",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
   "scripts": {
     "lint": "eslint --cache --max-warnings=0 src",
     "build": "tshy",
-    "test": "echo \"No tests yet\"",
+    "test": "npm run build && node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {

package/src/client.ts

@@ -26,6 +26,7 @@ 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 { UnexpectedClientError } from "./models/errors/httpclienterrors.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";
@@ -40,6 +41,7 @@ import {
   type QueryCollectionDoc,
   type ListDocsInput,
   type ListDocsResponse,
+  type ListDocsDoc,
   type ListCollectionsInput,
   type ListCollectionsResponseWithDates,
   type GetCollectionResponseWithDates,
@@ -88,12 +90,40 @@ async function fetchDocsFromUrl<T>(docsUrl: string): Promise<T[]> {
   const res = await fetch(docsUrl);
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(
+    throw new UnexpectedClientError(
       `Failed to fetch documents from URL: ${res.status} ${res.statusText}${text ? ` - ${text}` : ""}`,
     );
   }
-  const json = (await res.json()) as { docs?: T[] };
-  return json.docs ?? [];
+  const text = await res.text();
+  if (text.trim() === "") {
+    return [];
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch (cause) {
+    throw new UnexpectedClientError(
+      "Failed to parse documents from URL as JSON",
+      { cause },
+    );
+  }
+
+  if (payload == null) {
+    return [];
+  }
+  if (typeof payload !== "object" || Array.isArray(payload)) {
+    throw new UnexpectedClientError("Unexpected document payload shape from URL");
+  }
+
+  const { docs } = payload as { docs?: unknown };
+  if (docs == null) {
+    return [];
+  }
+  if (!Array.isArray(docs)) {
+    throw new UnexpectedClientError("Unexpected docs payload shape from URL");
+  }
+  return docs as T[];
 }
 
 /** Default base URL for the LambdaDB API. */
@@ -401,32 +431,50 @@ class CollectionDocs {
 
   /**
    * List documents in the collection.
+   * When the API returns docs via docsUrl (isDocsInline false), documents are
+   * fetched from the presigned URL automatically so the response always has docs.
    */
   async list(
     params?: ListDocsInput,
     options?: RequestOptions,
   ) {
-    return unwrapAsync(
+    const result = await unwrapAsync(
       collectionsDocsListDocs(
         this.client,
         { collectionName: this.collectionName, ...params },
         options,
       ),
     );
+    if (!result.isDocsInline && result.docsUrl) {
+      const docs = await fetchDocsFromUrl<ListDocsDoc>(result.docsUrl);
+      return { ...result, docs, isDocsInline: true };
+    }
+    return result;
   }
 
   /**
    * List documents in the collection (Safe: returns Result instead of throwing).
+   * When the API returns docs via docsUrl, documents are fetched from the presigned URL automatically.
    */
   async listSafe(
     params?: ListDocsInput,
     options?: RequestOptions,
   ): Promise<Result<ListDocsResponse, ListDocsError>> {
-    return await collectionsDocsListDocs(
+    const result = await collectionsDocsListDocs(
       this.client,
       { collectionName: this.collectionName, ...params },
       options,
     );
+    if (!result.ok) return result;
+    if (!result.value.isDocsInline && result.value.docsUrl) {
+      try {
+        const docs = await fetchDocsFromUrl<ListDocsDoc>(result.value.docsUrl);
+        return OK({ ...result.value, docs, isDocsInline: true });
+      } catch (e) {
+        return ERR(e as ListDocsError);
+      }
+    }
+    return result;
   }
 
   /**

package/src/lib/matchers.ts

@@ -224,7 +224,24 @@ export function match<T, E>(
     switch (encoding) {
       case "json":
         body = await response.text();
-        raw = JSON.parse(body);
+        if (body.trim() === "") {
+          raw = undefined;
+          break;
+        }
+        try {
+          raw = JSON.parse(body);
+        } catch (cause) {
+          return [ERR(
+            new ResponseValidationError("Response validation failed", {
+              cause,
+              rawValue: body,
+              rawMessage: "Response validation failed",
+              request,
+              response,
+              body,
+            }),
+          ), body];
+        }
         break;
       case "jsonl":
         raw = response.body;

package/src/lib/schemas.ts

@@ -4,6 +4,7 @@
 
 import {
   output,
+  preprocess,
   ZodEffects,
   ZodError,
   ZodObject,
@@ -50,6 +51,17 @@ export function safeParse<Inp, Out>(
   }
 }
 
+/**
+ * Converts explicit JSON nulls to undefined before applying the provided
+ * schema. This lets inbound response schemas tolerate APIs that return
+ * `null` instead of omitting optional fields.
+ */
+export function nullToUndefined<T extends ZodTypeAny>(
+  schema: T,
+): ZodEffects<T, output<T>, unknown> {
+  return preprocess((value) => value === null ? undefined : value, schema);
+}
+
 export function collectExtraKeys<
   Shape extends ZodRawShape,
   Catchall extends ZodTypeAny,

package/src/models/collectionresponse.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../lib/schemas.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
 import {
@@ -74,12 +74,12 @@ export const CollectionResponse$inboundSchema: z.ZodType<
   projectName: z.string(),
   collectionName: z.string(),
   indexConfigs: z.record(IndexConfigsUnion$inboundSchema),
-  partitionConfig: PartitionConfig$inboundSchema.optional(),
+  partitionConfig: nullToUndefined(PartitionConfig$inboundSchema.optional()),
   numPartitions: z.number().int(),
   numDocs: z.number().int(),
-  sourceProjectName: z.string().optional(),
-  sourceCollectionName: z.string().optional(),
-  sourceCollectionVersionId: z.string().optional(),
+  sourceProjectName: nullToUndefined(z.string().optional()),
+  sourceCollectionName: nullToUndefined(z.string().optional()),
+  sourceCollectionVersionId: nullToUndefined(z.string().optional()),
   collectionStatus: Status$inboundSchema,
   createdAt: z.number().int(),
   updatedAt: z.number().int(),

package/src/models/errors/badrequesterror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type BadRequestErrorData = {
@@ -31,7 +32,7 @@ export const BadRequestError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/errors/internalservererror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type InternalServerErrorData = {
@@ -31,7 +32,7 @@ export const InternalServerError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/errors/resourcealreadyexistserror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type ResourceAlreadyExistsErrorData = {
@@ -31,7 +32,7 @@ export const ResourceAlreadyExistsError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/errors/resourcenotfounderror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type ResourceNotFoundErrorData = {
@@ -31,7 +32,7 @@ export const ResourceNotFoundError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/errors/toomanyrequestserror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type TooManyRequestsErrorData = {
@@ -31,7 +32,7 @@ export const TooManyRequestsError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/errors/unauthenticatederror.ts

@@ -3,6 +3,7 @@
  */
 
 import * as z from "zod/v3";
+import { nullToUndefined } from "../../lib/schemas.js";
 import { LambdaDBError } from "./lambdadberror.js";
 
 export type UnauthenticatedErrorData = {
@@ -31,7 +32,7 @@ export const UnauthenticatedError$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  message: z.string().optional(),
+  message: nullToUndefined(z.string().optional()),
   request$: z.instanceof(Request),
   response$: z.instanceof(Response),
   body$: z.string(),

package/src/models/indexconfigsunion.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../lib/schemas.js";
 import { ClosedEnum } from "../types/enums.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
@@ -182,7 +182,7 @@ export const IndexConfigsVector$inboundSchema: z.ZodType<
 > = z.object({
   type: z.literal("vector"),
   dimensions: z.number().int(),
-  similarity: Similarity$inboundSchema.default("cosine"),
+  similarity: nullToUndefined(Similarity$inboundSchema.default("cosine")),
 });
 /** @internal */
 export type IndexConfigsVector$Outbound = {
@@ -233,7 +233,7 @@ export const IndexConfigsText$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   type: z.literal("text"),
-  analyzers: z.array(Analyzer$inboundSchema).optional(),
+  analyzers: nullToUndefined(z.array(Analyzer$inboundSchema).optional()),
 });
 /** @internal */
 export type IndexConfigsText$Outbound = {

package/src/models/operations/fetchdocs.ts

@@ -4,7 +4,7 @@
 
 import * as z from "zod/v3";
 import { remap as remap$ } from "../../lib/primitives.js";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
@@ -153,7 +153,7 @@ export const FetchDocsResponse$inboundSchema: z.ZodType<
   took: z.number().int(),
   docs: z.array(z.lazy(() => FetchDocsDoc$inboundSchema)),
   isDocsInline: z.boolean(),
-  docsUrl: z.string().optional(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function fetchDocsResponseFromJSON(

package/src/models/operations/getbulkupsertdocs.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { ClosedEnum } from "../../types/enums.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
@@ -101,10 +101,10 @@ export const GetBulkUpsertDocsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   url: z.string(),
-  type: Type$inboundSchema.default("application/json"),
-  httpMethod: HttpMethod$inboundSchema.default("PUT"),
+  type: nullToUndefined(Type$inboundSchema.default("application/json")),
+  httpMethod: nullToUndefined(HttpMethod$inboundSchema.default("PUT")),
   objectKey: z.string(),
-  sizeLimitBytes: z.number().int().default(209715200),
+  sizeLimitBytes: nullToUndefined(z.number().int().default(209715200)),
 });
 
 export function getBulkUpsertDocsResponseFromJSON(

package/src/models/operations/listcollections.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
@@ -50,7 +50,7 @@ export const ListCollectionsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   collections: z.array(models.CollectionResponse$inboundSchema),
-  nextPageToken: z.string().optional(),
+  nextPageToken: nullToUndefined(z.string().optional()),
 });
 
 export function listCollectionsResponseFromJSON(

package/src/models/operations/listdocs.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
@@ -22,6 +22,11 @@ export type ListDocsRequest = {
   pageToken?: string | undefined;
 };
 
+export type ListDocsDoc = {
+  collection: string;
+  doc: { [k: string]: any };
+};
+
 /**
  * Documents list.
  */
@@ -30,8 +35,16 @@ export type ListDocsResponse = {
   /**
    * A list of documents.
    */
-  docs: Array<{ [k: string]: any }>;
+  docs: Array<ListDocsDoc>;
   nextPageToken?: string | undefined;
+  /**
+   * Whether the list of documents is included.
+   */
+  isDocsInline: boolean;
+  /**
+   * Download URL for the list of documents.
+   */
+  docsUrl?: string | undefined;
 };
 
 /** @internal */
@@ -58,6 +71,16 @@ export function listDocsRequestToJSON(
   return JSON.stringify(ListDocsRequest$outboundSchema.parse(listDocsRequest));
 }
 
+/** @internal */
+export const ListDocsDoc$inboundSchema: z.ZodType<
+  ListDocsDoc,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  collection: z.string(),
+  doc: z.record(z.any()),
+});
+
 /** @internal */
 export const ListDocsResponse$inboundSchema: z.ZodType<
   ListDocsResponse,
@@ -65,8 +88,10 @@ export const ListDocsResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   total: z.number().int(),
-  docs: z.array(z.record(z.any())),
-  nextPageToken: z.string().optional(),
+  docs: z.array(ListDocsDoc$inboundSchema),
+  nextPageToken: nullToUndefined(z.string().optional()),
+  isDocsInline: z.boolean(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function listDocsResponseFromJSON(

package/src/models/operations/querycollection.ts

@@ -4,7 +4,7 @@
 
 import * as z from "zod/v3";
 import { remap as remap$ } from "../../lib/primitives.js";
-import { safeParse } from "../../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
@@ -156,7 +156,7 @@ export const QueryCollectionDoc$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   collection: z.string(),
-  score: z.number().optional(),
+  score: nullToUndefined(z.number().optional()),
   doc: z.record(z.any()),
 });
 
@@ -177,11 +177,11 @@ export const QueryCollectionResponse$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   took: z.number().int(),
-  maxScore: z.number().optional(),
+  maxScore: nullToUndefined(z.number().optional()),
   total: z.number().int(),
   docs: z.array(z.lazy(() => QueryCollectionDoc$inboundSchema)),
   isDocsInline: z.boolean(),
-  docsUrl: z.string().optional(),
+  docsUrl: nullToUndefined(z.string().optional()),
 });
 
 export function queryCollectionResponseFromJSON(

package/src/models/partitionconfig.ts

@@ -3,7 +3,7 @@
  */
 
 import * as z from "zod/v3";
-import { safeParse } from "../lib/schemas.js";
+import { nullToUndefined, safeParse } from "../lib/schemas.js";
 import { ClosedEnum } from "../types/enums.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
@@ -47,9 +47,9 @@ export const PartitionConfig$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  fieldName: z.string().optional(),
-  dataType: DataType$inboundSchema.optional(),
-  numPartitions: z.number().int().optional(),
+  fieldName: nullToUndefined(z.string().optional()),
+  dataType: nullToUndefined(DataType$inboundSchema.optional()),
+  numPartitions: nullToUndefined(z.number().int().optional()),
 });
 /** @internal */
 export type PartitionConfig$Outbound = {

package/src/types/public.ts

@@ -34,7 +34,10 @@ export type {
   QueryCollectionResponse,
   QueryCollectionDoc,
 } from "../models/operations/querycollection.js";
-export type { ListDocsResponse } from "../models/operations/listdocs.js";
+export type {
+  ListDocsResponse,
+  ListDocsDoc,
+} from "../models/operations/listdocs.js";
 export type { MessageResponse } from "../models/index.js";
 export type {
   FetchDocsResponse,

package/test/null-response.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { LambdaDBClient } from "../dist/esm/index.js";
+import { HTTPClient } from "../dist/esm/lib/http.js";
+import { ResponseValidationError } from "../dist/esm/models/errors/responsevalidationerror.js";
+import { QueryCollectionResponse$inboundSchema } from "../dist/esm/models/operations/querycollection.js";
+
+function jsonResponse(body, init = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    ...init,
+  });
+}
+
+test("response schemas accept null for optional response fields", () => {
+  const parsed = QueryCollectionResponse$inboundSchema.parse({
+    took: 1,
+    maxScore: null,
+    total: 1,
+    docs: [{ collection: "items", score: null, doc: { id: "a" } }],
+    isDocsInline: false,
+    docsUrl: null,
+  });
+
+  assert.equal(parsed.maxScore, undefined);
+  assert.equal(parsed.docsUrl, undefined);
+  assert.equal(parsed.docs[0].score, undefined);
+});
+
+test("safe methods return ResponseValidationError for invalid JSON bodies", async () => {
+  const httpClient = new HTTPClient({
+    fetcher: async () =>
+      new Response("{", {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+  });
+  const client = new LambdaDBClient({ httpClient, projectApiKey: "test-key" });
+
+  const result = await client.listCollectionsSafe();
+
+  assert.equal(result.ok, false);
+  assert.ok(result.error instanceof ResponseValidationError);
+  assert.equal(result.error.rawValue, "{");
+});
+
+test("docsUrl fetches treat null document payloads as an empty docs array", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => jsonResponse(null);
+
+  try {
+    const httpClient = new HTTPClient({
+      fetcher: async () =>
+        jsonResponse({
+          total: 1,
+          docs: [],
+          isDocsInline: false,
+          docsUrl: "https://example.test/docs.json",
+        }),
+    });
+    const client = new LambdaDBClient({ httpClient, projectApiKey: "test-key" });
+
+    const result = await client.collection("items").docs.listSafe();
+
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.value.docs, []);
+    assert.equal(result.value.isDocsInline, true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});