@functional-systems/lambdadb 0.5.0-rc.1 → 0.5.0-rc.3

package/src/models/operations/updatecollection.ts

@@ -3,19 +3,28 @@
  */
 
 import * as z from "zod/v3";
+import { collectionTagsSchema } from "../../lib/collectionContract.js";
 import { remap as remap$ } from "../../lib/primitives.js";
 import { 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";
 
-export type UpdateCollectionRequestBody = {
-  indexConfigs?: { [k: string]: models.IndexConfigsUnion } | undefined;
-  description?: string | undefined;
-  tags?: Record<string, string> | undefined;
-  snapshotRetentionInDays?: number | undefined;
+type UpdateCollectionFields = {
+  indexConfigs?: { [k: string]: models.IndexConfigsUnion } | null | undefined;
+  description?: string | null | undefined;
+  tags?: Record<string, string> | null | undefined;
+  snapshotRetentionInDays?: number | null | undefined;
 };
 
+export type UpdateCollectionRequestBody =
+  | (UpdateCollectionFields & {
+    indexConfigs: { [k: string]: models.IndexConfigsUnion };
+  })
+  | (UpdateCollectionFields & { description: string })
+  | (UpdateCollectionFields & { tags: Record<string, string> })
+  | (UpdateCollectionFields & { snapshotRetentionInDays: number });
+
 export type UpdateCollectionRequest = {
   /**
    * Collection name.
@@ -32,33 +41,45 @@ export type UpdateCollectionResponse = {
 };
 
 /** @internal */
-export type UpdateCollectionRequestBody$Outbound = {
-  indexConfigs?: { [k: string]: models.IndexConfigsUnion$Outbound } | undefined;
-  description?: string | undefined;
-  tags?: Record<string, string> | undefined;
-  snapshotRetentionInDays?: number | undefined;
+type UpdateCollectionFields$Outbound = {
+  indexConfigs?:
+    | { [k: string]: models.IndexConfigsUnion$Outbound }
+    | null
+    | undefined;
+  description?: string | null | undefined;
+  tags?: Record<string, string> | null | undefined;
+  snapshotRetentionInDays?: number | null | undefined;
 };
 
+export type UpdateCollectionRequestBody$Outbound =
+  | (UpdateCollectionFields$Outbound & {
+    indexConfigs: { [k: string]: models.IndexConfigsUnion$Outbound };
+  })
+  | (UpdateCollectionFields$Outbound & { description: string })
+  | (UpdateCollectionFields$Outbound & { tags: Record<string, string> })
+  | (UpdateCollectionFields$Outbound & { snapshotRetentionInDays: number });
+
 /** @internal */
 export const UpdateCollectionRequestBody$outboundSchema: z.ZodType<
   UpdateCollectionRequestBody$Outbound,
   z.ZodTypeDef,
   UpdateCollectionRequestBody
 > = z.object({
-  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema).optional(),
-  description: z.string().max(255).optional(),
-  tags: z.record(
-    z.string().min(1).max(127).regex(/^[^:#,]+$/),
-  ).refine((value) => Object.keys(value).length <= 5, {
-    message: "Collection tags support at most five entries",
-  }).refine(
-    (value) => Object.keys(value).every((key) => /^[A-Za-z0-9_.-]{1,63}$/.test(key)),
-    { message: "Invalid collection tag key" },
-  ).optional(),
-  snapshotRetentionInDays: z.number().int().min(1).max(31).optional(),
-}).refine((value) => Object.values(value).some((item) => item !== undefined), {
-  message: "At least one collection field must be provided",
-});
+  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema).refine(
+    (value) => Object.keys(value).length > 0,
+    { message: "Collection indexConfigs must contain at least one field" },
+  ).nullable().optional(),
+  description: z.string().max(255).nullable().optional(),
+  tags: collectionTagsSchema.nullable().optional(),
+  snapshotRetentionInDays: z.number().int().min(1).max(31).nullable().optional(),
+}).strict().refine(
+  (value) => Object.values(value).some((item) => item !== undefined && item !== null),
+  { message: "At least one non-null collection field must be provided" },
+) as z.ZodType<
+  UpdateCollectionRequestBody$Outbound,
+  z.ZodTypeDef,
+  UpdateCollectionRequestBody
+>;
 
 export function updateCollectionRequestBodyToJSON(
   updateCollectionRequestBody: UpdateCollectionRequestBody,

package/src/models/operations/updatedocs.ts

@@ -36,7 +36,7 @@ export const UpdateDocsRequestBody$outboundSchema: z.ZodType<
 > = z.object({
   docs: z.array(z.record(z.any())),
   branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
-});
+}).strict();
 
 export function updateDocsRequestBodyToJSON(
   updateDocsRequestBody: UpdateDocsRequestBody,

package/src/models/operations/upsertdocs.ts

@@ -36,7 +36,7 @@ export const UpsertDocsRequestBody$outboundSchema: z.ZodType<
 > = z.object({
   docs: z.array(z.record(z.any())),
   branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
-});
+}).strict();
 
 export function upsertDocsRequestBodyToJSON(
   upsertDocsRequestBody: UpsertDocsRequestBody,

package/src/models/versioning.ts

@@ -33,10 +33,28 @@ export type RefSource = BranchSource | TagSource;
 /** A Branch or Tag used as the target of an Alias. */
 export type AliasTarget = BranchRef | TagRef;
 
-export type RefDetails = {
+export type SnapshotDetails = {
+  snapshotId: string;
+  /** Snapshot commit time as Unix epoch milliseconds. */
+  snapshotCommittedAt: number;
+};
+
+export type BranchDetails = {
   name: string;
-  snapshotId: string | null;
-  /** Ref creation time as Unix epoch milliseconds. */
+  /** Current committed head; null for an empty branch. */
+  headSnapshot: SnapshotDetails | null;
+  /**
+   * Fixed fork snapshot, not the previous head. Null for main or an empty source.
+   * This metadata does not extend snapshot retention.
+   */
+  parentSnapshot: SnapshotDetails | null;
+  /** Branch creation time as Unix epoch milliseconds. */
+  createdAt: number;
+};
+
+export type TagDetails = SnapshotDetails & {
+  name: string;
+  /** Tag creation time, independent of the pinned snapshot commit time. */
   createdAt: number;
 };
 
@@ -99,9 +117,24 @@ export const AliasTarget$schema: z.ZodType<AliasTarget> = z.union([
 ]);
 
 /** @internal */
-export const RefDetails$inboundSchema: z.ZodType<RefDetails> = z.object({
+export const SnapshotDetails$inboundSchema: z.ZodType<SnapshotDetails> = z.object({
+  snapshotId: z.string(),
+  snapshotCommittedAt: z.number().int(),
+});
+
+/** @internal */
+export const BranchDetails$inboundSchema: z.ZodType<BranchDetails> = z.object({
+  name: z.string(),
+  headSnapshot: SnapshotDetails$inboundSchema.nullable(),
+  parentSnapshot: SnapshotDetails$inboundSchema.nullable(),
+  createdAt: z.number().int(),
+});
+
+/** @internal */
+export const TagDetails$inboundSchema: z.ZodType<TagDetails> = z.object({
   name: z.string(),
-  snapshotId: z.string().nullable(),
+  snapshotId: z.string(),
+  snapshotCommittedAt: z.number().int(),
   createdAt: z.number().int(),
 });
 

package/src/sdk/docs.ts

@@ -89,7 +89,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Delete documents by document IDs or query filter from a collection.
+   * Delete documents by exactly one of document IDs or query filter.
    */
   async delete(
     request: operations.DeleteDocsRequest,

package/src/types/errors.ts

@@ -18,9 +18,14 @@ import type {
 // ---- Re-export error classes for instanceof checks and typing ----
 export {
   BadRequestError,
+  BadGatewayError,
+  CatalogConflictError,
+  GatewayTimeoutError,
   UnauthenticatedError,
+  PayloadTooLargeError,
   ResourceNotFoundError,
   ResourceAlreadyExistsError,
+  ServiceUnavailableError,
   TooManyRequestsError,
   InternalServerError,
   LambdaDBError,
@@ -50,12 +55,20 @@ export type LambdaDBClientError =
 
 // ---- API error unions (subset of errors.* per operation) ----
 
-/** Errors that can occur when listing collections, getting a collection, deleting a collection, or getting bulk upsert info. */
+/** Transport errors handled by the shared Gateway response matcher. */
+type GatewayResponseError =
+  | errors.PayloadTooLargeError
+  | errors.BadGatewayError
+  | errors.ServiceUnavailableError
+  | errors.GatewayTimeoutError;
+
+/** Errors that can occur when listing or getting collections. */
 export type ListCollectionsError =
   | errors.UnauthenticatedError
   | errors.ResourceNotFoundError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
 /** Errors that can occur when creating a collection. */
@@ -65,6 +78,7 @@ export type CreateCollectionError =
   | errors.ResourceAlreadyExistsError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
 /** Errors that can occur when getting a collection. */
@@ -72,26 +86,31 @@ export type GetCollectionError = ListCollectionsError;
 
 /** Errors that can occur when updating a collection. */
 export type UpdateCollectionError =
+  | errors.CatalogConflictError
+  | QueryCollectionError;
+
+/** Errors that can occur when deleting a collection. */
+export type DeleteCollectionError =
+  | errors.CatalogConflictError
+  | ListCollectionsError;
+
+/** Errors that can occur when querying a collection. */
+export type QueryCollectionError =
   | errors.BadRequestError
   | errors.UnauthenticatedError
   | errors.ResourceNotFoundError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | GatewayResponseError
   | LambdaDBClientError;
 
-/** Errors that can occur when deleting a collection. */
-export type DeleteCollectionError = ListCollectionsError;
-
-/** Errors that can occur when querying a collection. */
-export type QueryCollectionError = UpdateCollectionError;
-
 /** Errors that can occur when listing, upserting, updating, deleting, or fetching docs, or when calling bulkUpsert. */
-export type ListDocsError = UpdateCollectionError;
-export type UpsertDocsError = UpdateCollectionError;
-export type UpdateDocsError = UpdateCollectionError;
-export type DeleteDocsError = UpdateCollectionError;
-export type FetchDocsError = UpdateCollectionError;
-export type BulkUpsertDocsError = UpdateCollectionError;
+export type ListDocsError = QueryCollectionError;
+export type UpsertDocsError = QueryCollectionError;
+export type UpdateDocsError = QueryCollectionError;
+export type DeleteDocsError = QueryCollectionError;
+export type FetchDocsError = QueryCollectionError;
+export type BulkUpsertDocsError = QueryCollectionError;
 
 /** Errors that can occur when getting bulk upsert docs info. */
 export type GetBulkUpsertDocsError =

package/src/types/public.ts

@@ -20,7 +20,9 @@ import type {
   AliasRef,
   BranchRef,
   ReadRef,
-  RefDetails as RefDetailsModel,
+  BranchDetails as BranchDetailsModel,
+  SnapshotDetails as SnapshotDetailsModel,
+  TagDetails as TagDetailsModel,
   TagRef,
 } from "../models/versioning.js";
 
@@ -86,7 +88,18 @@ export type {
   TagSource,
 } from "../models/versioning.js";
 
-export type RefDetails = Omit<RefDetailsModel, "createdAt"> & {
+export type SnapshotDetails = Omit<SnapshotDetailsModel, "snapshotCommittedAt"> & {
+  snapshotCommittedAt: Date;
+};
+
+export type BranchDetails = Omit<BranchDetailsModel, "createdAt" | "headSnapshot" | "parentSnapshot"> & {
+  headSnapshot: SnapshotDetails | null;
+  parentSnapshot: SnapshotDetails | null;
+  createdAt: Date;
+};
+
+export type TagDetails = Omit<TagDetailsModel, "createdAt" | "snapshotCommittedAt"> & {
+  snapshotCommittedAt: Date;
   createdAt: Date;
 };
 
@@ -99,16 +112,16 @@ export type CreateBranchInput = {
   source?: import("../models/versioning.js").RefSource | undefined;
 };
 
-export type CreateBranchResponse = { branch: RefDetails };
-export type ListBranchesResponse = { branches: RefDetails[] };
+export type CreateBranchResponse = { branch: BranchDetails };
+export type ListBranchesResponse = { branches: BranchDetails[] };
 
 export type CreateTagInput = {
   tagName: string;
   source?: import("../models/versioning.js").RefSource | undefined;
 };
 
-export type CreateTagResponse = { tag: RefDetails };
-export type ListTagsResponse = { tags: RefDetails[] };
+export type CreateTagResponse = { tag: TagDetails };
+export type ListTagsResponse = { tags: TagDetails[] };
 
 export type CreateAliasInput = {
   aliasName: string;
@@ -231,8 +244,27 @@ export function createCollectionResponseWithDates(
 }
 
 /** @internal */
-export function refDetailsWithDate(details: RefDetailsModel): RefDetails {
-  return { ...details, createdAt: new Date(details.createdAt) };
+export function snapshotDetailsWithDate(details: SnapshotDetailsModel): SnapshotDetails {
+  return { ...details, snapshotCommittedAt: new Date(details.snapshotCommittedAt) };
+}
+
+/** @internal */
+export function branchDetailsWithDates(details: BranchDetailsModel): BranchDetails {
+  return {
+    ...details,
+    headSnapshot: details.headSnapshot === null ? null : snapshotDetailsWithDate(details.headSnapshot),
+    parentSnapshot: details.parentSnapshot === null ? null : snapshotDetailsWithDate(details.parentSnapshot),
+    createdAt: new Date(details.createdAt),
+  };
+}
+
+/** @internal */
+export function tagDetailsWithDates(details: TagDetailsModel): TagDetails {
+  return {
+    ...snapshotDetailsWithDate(details),
+    name: details.name,
+    createdAt: new Date(details.createdAt),
+  };
 }
 
 /** @internal */

package/src/versioning.ts

@@ -13,7 +13,8 @@ import type { SDKValidationError } from "./models/errors/sdkvalidationerror.js";
 import {
   AliasDetails$inboundSchema,
   AliasTarget$schema,
-  RefDetails$inboundSchema,
+  BranchDetails$inboundSchema,
+  TagDetails$inboundSchema,
   RefSource$schema,
   type AliasRef,
   type BranchRef,
@@ -30,7 +31,8 @@ import type {
 } from "./models/errors/httpclienterrors.js";
 import {
   aliasDetailsWithDate,
-  refDetailsWithDate,
+  branchDetailsWithDates,
+  tagDetailsWithDates,
   type AliasResponse,
   type CreateAliasInput,
   type CreateBranchInput,
@@ -47,7 +49,7 @@ import type { Result } from "./types/fp.js";
 
 /** Exact public contract revision implemented by this SDK. */
 export const DATA_VERSIONING_CONTRACT_REVISION =
-  "a52ce19f5a1ce5ad3a30a55a5560e4591f0be9fa" as const;
+  "c8495bf47cd8918cfd546b4742823fd4cf3d0814" as const;
 
 const refNamePattern = /^[a-zA-Z0-9_-]{3,52}$/;
 const refNameSchema = z.string().regex(refNamePattern);
@@ -112,8 +114,13 @@ export type VersioningError =
   | errors.UnauthenticatedError
   | errors.ResourceNotFoundError
   | errors.ResourceAlreadyExistsError
+  | errors.CatalogConflictError
+  | errors.PayloadTooLargeError
   | errors.TooManyRequestsError
   | errors.InternalServerError
+  | errors.BadGatewayError
+  | errors.ServiceUnavailableError
+  | errors.GatewayTimeoutError
   | LambdaDBError
   | ResponseValidationError
   | ConnectionError
@@ -130,6 +137,7 @@ type VersioningRequest<TInput, TOutput> = {
   path: string;
   responseSchema: z.ZodType<TOutput>;
   successStatus: 200 | 201;
+  conflict?: "already-exists" | "catalog" | undefined;
 };
 
 async function requestVersioning<TInput, TOutput>(
@@ -201,14 +209,20 @@ async function requestVersioning<TInput, TOutput>(
   if (!responseResult.ok) return responseResult;
 
   const response = responseResult.value;
+  const conflictMatchers = request.conflict === "already-exists"
+    ? [M.jsonErr(409, errors.ResourceAlreadyExistsError$inboundSchema)]
+    : request.conflict === "catalog"
+    ? [M.jsonErr(409, errors.CatalogConflictError$inboundSchema)]
+    : [];
   const [result] = await M.match<TOutput, VersioningError>(
     M.json(request.successStatus, request.responseSchema),
     M.jsonErr(400, errors.BadRequestError$inboundSchema),
     M.jsonErr(401, errors.UnauthenticatedError$inboundSchema),
     M.jsonErr(404, errors.ResourceNotFoundError$inboundSchema),
-    M.jsonErr(409, errors.ResourceAlreadyExistsError$inboundSchema),
+    ...conflictMatchers,
     M.jsonErr(429, errors.TooManyRequestsError$inboundSchema),
     M.jsonErr(500, errors.InternalServerError$inboundSchema),
+    ...M.gatewayErrorMatchers(),
     M.fail("4XX"),
     M.fail("5XX"),
   )(response, httpRequest, {
@@ -225,15 +239,15 @@ const createBranchSchema: z.ZodType<CreateBranchInput> = z.object({
   branchName: z.string().regex(refNamePattern),
   source: RefSource$schema.optional(),
 }).strict();
-const createBranchResponseSchema = z.object({ branch: RefDetails$inboundSchema });
-const listBranchesResponseSchema = z.object({ branches: z.array(RefDetails$inboundSchema) });
+const createBranchResponseSchema = z.object({ branch: BranchDetails$inboundSchema });
+const listBranchesResponseSchema = z.object({ branches: z.array(BranchDetails$inboundSchema) });
 
 const createTagSchema: z.ZodType<CreateTagInput> = z.object({
   tagName: z.string().regex(refNamePattern),
   source: RefSource$schema.optional(),
 }).strict();
-const createTagResponseSchema = z.object({ tag: RefDetails$inboundSchema });
-const listTagsResponseSchema = z.object({ tags: z.array(RefDetails$inboundSchema) });
+const createTagResponseSchema = z.object({ tag: TagDetails$inboundSchema });
+const listTagsResponseSchema = z.object({ tags: z.array(TagDetails$inboundSchema) });
 
 const createAliasSchema: z.ZodType<CreateAliasInput> = z.object({
   aliasName: z.string().regex(refNamePattern),
@@ -269,9 +283,10 @@ export class CollectionBranches {
       path: pathFor(this.collectionName, "/branches"),
       responseSchema: createBranchResponseSchema,
       successStatus: 201,
+      conflict: "already-exists",
     }, options);
     if (!result.ok) return result;
-    return { ok: true, value: { branch: refDetailsWithDate(result.value.branch) } };
+    return { ok: true, value: { branch: branchDetailsWithDates(result.value.branch) } };
   }
 
   async list(options?: RequestOptions): Promise<ListBranchesResponse> {
@@ -288,7 +303,7 @@ export class CollectionBranches {
       successStatus: 200,
     }, options);
     if (!result.ok) return result;
-    return { ok: true, value: { branches: result.value.branches.map(refDetailsWithDate) } };
+    return { ok: true, value: { branches: result.value.branches.map(branchDetailsWithDates) } };
   }
 
   async delete(branchName: string, options?: RequestOptions): Promise<MessageResponse> {
@@ -312,6 +327,7 @@ export class CollectionBranches {
       path: pathFor(this.collectionName, `/branches/${encodeURIComponent(parsedName.value)}`),
       responseSchema: messageResponseSchema,
       successStatus: 200,
+      conflict: "catalog",
     }, options);
   }
 }
@@ -339,9 +355,10 @@ export class CollectionTags {
       path: pathFor(this.collectionName, "/tags"),
       responseSchema: createTagResponseSchema,
       successStatus: 201,
+      conflict: "already-exists",
     }, options);
     if (!result.ok) return result;
-    return { ok: true, value: { tag: refDetailsWithDate(result.value.tag) } };
+    return { ok: true, value: { tag: tagDetailsWithDates(result.value.tag) } };
   }
 
   async list(options?: RequestOptions): Promise<ListTagsResponse> {
@@ -358,7 +375,7 @@ export class CollectionTags {
       successStatus: 200,
     }, options);
     if (!result.ok) return result;
-    return { ok: true, value: { tags: result.value.tags.map(refDetailsWithDate) } };
+    return { ok: true, value: { tags: result.value.tags.map(tagDetailsWithDates) } };
   }
 
   async delete(tagName: string, options?: RequestOptions): Promise<MessageResponse> {
@@ -382,6 +399,7 @@ export class CollectionTags {
       path: pathFor(this.collectionName, `/tags/${encodeURIComponent(parsedName.value)}`),
       responseSchema: messageResponseSchema,
       successStatus: 200,
+      conflict: "catalog",
     }, options);
   }
 }
@@ -409,6 +427,7 @@ export class CollectionAliases {
       path: pathFor(this.collectionName, "/aliases"),
       responseSchema: aliasResponseSchema,
       successStatus: 201,
+      conflict: "already-exists",
     }, options);
     if (!result.ok) return result;
     return { ok: true, value: { alias: aliasDetailsWithDate(result.value.alias) } };
@@ -459,6 +478,7 @@ export class CollectionAliases {
       path: pathFor(this.collectionName, `/aliases/${encodeURIComponent(parsedName.value)}`),
       responseSchema: aliasResponseSchema,
       successStatus: 200,
+      conflict: "catalog",
     }, options);
     if (!result.ok) return result;
     return { ok: true, value: { alias: aliasDetailsWithDate(result.value.alias) } };
@@ -485,6 +505,7 @@ export class CollectionAliases {
       path: pathFor(this.collectionName, `/aliases/${encodeURIComponent(parsedName.value)}`),
       responseSchema: messageResponseSchema,
       successStatus: 200,
+      conflict: "catalog",
     }, options);
   }
 }