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

package/src/models/operations/updatecollection.ts

@@ -10,7 +10,10 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import * as models from "../index.js";
 
 export type UpdateCollectionRequestBody = {
-  indexConfigs: { [k: string]: models.IndexConfigsUnion };
+  indexConfigs?: { [k: string]: models.IndexConfigsUnion } | undefined;
+  description?: string | undefined;
+  tags?: Record<string, string> | undefined;
+  snapshotRetentionInDays?: number | undefined;
 };
 
 export type UpdateCollectionRequest = {
@@ -30,7 +33,10 @@ export type UpdateCollectionResponse = {
 
 /** @internal */
 export type UpdateCollectionRequestBody$Outbound = {
-  indexConfigs: { [k: string]: models.IndexConfigsUnion$Outbound };
+  indexConfigs?: { [k: string]: models.IndexConfigsUnion$Outbound } | undefined;
+  description?: string | undefined;
+  tags?: Record<string, string> | undefined;
+  snapshotRetentionInDays?: number | undefined;
 };
 
 /** @internal */
@@ -39,7 +45,19 @@ export const UpdateCollectionRequestBody$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   UpdateCollectionRequestBody
 > = z.object({
-  indexConfigs: z.record(models.IndexConfigsUnion$outboundSchema),
+  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",
 });
 
 export function updateCollectionRequestBodyToJSON(

package/src/models/operations/updatedocs.ts

@@ -10,6 +10,8 @@ export type UpdateDocsRequestBody = {
    * A list of documents to update. Each document must contain 'id' field to be updated. For managed embedding vector fields, omit the managed vector field and update only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
 export type UpdateDocsRequest = {
@@ -23,6 +25,7 @@ export type UpdateDocsRequest = {
 /** @internal */
 export type UpdateDocsRequestBody$Outbound = {
   docs: Array<{ [k: string]: any }>;
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -32,6 +35,7 @@ export const UpdateDocsRequestBody$outboundSchema: z.ZodType<
   UpdateDocsRequestBody
 > = z.object({
   docs: z.array(z.record(z.any())),
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
 });
 
 export function updateDocsRequestBodyToJSON(

package/src/models/operations/upsertdocs.ts

@@ -10,6 +10,8 @@ export type UpsertDocsRequestBody = {
    * A list of documents to upsert. For managed embedding vector fields, omit the managed vector field and provide only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
+  /** Write target Branch. Omitting it writes to main. */
+  branch?: string | undefined;
 };
 
 export type UpsertDocsRequest = {
@@ -23,6 +25,7 @@ export type UpsertDocsRequest = {
 /** @internal */
 export type UpsertDocsRequestBody$Outbound = {
   docs: Array<{ [k: string]: any }>;
+  branch?: string | undefined;
 };
 
 /** @internal */
@@ -32,6 +35,7 @@ export const UpsertDocsRequestBody$outboundSchema: z.ZodType<
   UpsertDocsRequestBody
 > = z.object({
   docs: z.array(z.record(z.any())),
+  branch: z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/).optional(),
 });
 
 export function upsertDocsRequestBodyToJSON(

package/src/models/versioning.ts

@@ -0,0 +1,118 @@
+import * as z from "zod/v3";
+
+const refNameSchema = z.string().regex(/^[a-zA-Z0-9_-]{3,52}$/);
+
+export type BranchRef = {
+  kind: "branch";
+  name: string;
+};
+
+export type TagRef = {
+  kind: "tag";
+  name: string;
+};
+
+export type AliasRef = {
+  kind: "alias";
+  name: string;
+};
+
+/** A Branch, Tag, or Alias used to select document reads. */
+export type ReadRef = BranchRef | TagRef | AliasRef;
+
+export type BranchSource = BranchRef & {
+  /** Latest committed snapshot cutoff as Unix epoch milliseconds. */
+  asOf?: number | undefined;
+};
+
+export type TagSource = TagRef;
+
+/** A Branch or Tag used as the source of a new Branch or Tag. */
+export type RefSource = BranchSource | TagSource;
+
+/** A Branch or Tag used as the target of an Alias. */
+export type AliasTarget = BranchRef | TagRef;
+
+export type RefDetails = {
+  name: string;
+  snapshotId: string | null;
+  /** Ref creation time as Unix epoch milliseconds. */
+  createdAt: number;
+};
+
+export type AliasTargetKind = "BRANCH" | "TAG";
+
+export type AliasDetails = {
+  aliasId: string;
+  aliasName: string;
+  targetKind: AliasTargetKind;
+  targetName: string;
+  targetId: string;
+  aliasRevision: number;
+  dangling: boolean;
+  /** Alias creation time as Unix epoch milliseconds. */
+  createdAt: number;
+};
+
+/** @internal */
+export const BranchRef$schema = z.object({
+  kind: z.literal("branch"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const TagRef$schema = z.object({
+  kind: z.literal("tag"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const AliasRef$schema = z.object({
+  kind: z.literal("alias"),
+  name: refNameSchema,
+}).strict();
+
+/** @internal */
+export const ReadRef$schema: z.ZodType<ReadRef> = z.discriminatedUnion("kind", [
+  BranchRef$schema,
+  TagRef$schema,
+  AliasRef$schema,
+]);
+
+/** @internal */
+export const BranchSource$schema = z.object({
+  kind: z.literal("branch"),
+  name: refNameSchema,
+  asOf: z.number().int().optional(),
+}).strict();
+
+/** @internal */
+export const RefSource$schema: z.ZodType<RefSource> = z.union([
+  BranchSource$schema,
+  TagRef$schema,
+]);
+
+/** @internal */
+export const AliasTarget$schema: z.ZodType<AliasTarget> = z.union([
+  BranchRef$schema,
+  TagRef$schema,
+]);
+
+/** @internal */
+export const RefDetails$inboundSchema: z.ZodType<RefDetails> = z.object({
+  name: z.string(),
+  snapshotId: z.string().nullable(),
+  createdAt: z.number().int(),
+});
+
+/** @internal */
+export const AliasDetails$inboundSchema: z.ZodType<AliasDetails> = z.object({
+  aliasId: z.string(),
+  aliasName: z.string(),
+  targetKind: z.enum(["BRANCH", "TAG"]),
+  targetName: z.string(),
+  targetId: z.string(),
+  aliasRevision: z.number().int().nonnegative(),
+  dangling: z.boolean(),
+  createdAt: z.number().int(),
+});

package/src/types/public.ts

@@ -6,15 +6,39 @@
 // ---- Input types (RequestBody / Request aliased as XxxInput) ----
 export type { CreateCollectionRequest as CreateCollectionInput } from "../models/operations/createcollection.js";
 export type { UpdateCollectionRequestBody as UpdateCollectionInput } from "../models/operations/updatecollection.js";
-export type { QueryCollectionRequestBody as QueryCollectionInput } from "../models/operations/querycollection.js";
 export type { UpsertDocsRequestBody as UpsertDocsInput } from "../models/operations/upsertdocs.js";
 export type { UpdateDocsRequestBody as UpdateDocsInput } from "../models/operations/updatedocs.js";
 export type { DeleteDocsRequestBody as DeleteDocsInput } from "../models/operations/deletedocs.js";
-export type { FetchDocsRequestBody as FetchDocsInput } from "../models/operations/fetchdocs.js";
 export type { BulkUpsertDocsRequestBody as BulkUpsertInput } from "../models/operations/bulkupsertdocs.js";
 
 import type { ListDocsRequest } from "../models/operations/listdocs.js";
 import type { ListCollectionsRequest } from "../models/operations/listcollections.js";
+import type { QueryCollectionRequestBody } from "../models/operations/querycollection.js";
+import type { FetchDocsRequestBody } from "../models/operations/fetchdocs.js";
+import type {
+  AliasDetails as AliasDetailsModel,
+  AliasRef,
+  BranchRef,
+  ReadRef,
+  RefDetails as RefDetailsModel,
+  TagRef,
+} from "../models/versioning.js";
+
+type ConsistentReadForRef =
+  | { ref?: BranchRef | undefined; consistentRead?: boolean | undefined }
+  | { ref: TagRef | AliasRef; consistentRead?: false | undefined };
+
+/** Query input with consistent reads restricted to direct Branch refs. */
+export type QueryCollectionInput = Omit<
+  QueryCollectionRequestBody,
+  "ref" | "consistentRead"
+> & ConsistentReadForRef;
+
+/** Fetch input with consistent reads restricted to direct Branch refs. */
+export type FetchDocsInput = Omit<
+  FetchDocsRequestBody,
+  "ref" | "consistentRead"
+> & ConsistentReadForRef;
 
 /** Parameters for listing documents, including extended list options. */
 export type ListDocsInput = Pick<
@@ -24,6 +48,8 @@ export type ListDocsInput = Pick<
   filter?: Record<string, unknown> | undefined;
   partitionFilter?: import("../models/index.js").PartitionFilter | undefined;
   fields?: import("../models/index.js").FieldsSelectorUnion | undefined;
+  /** Read target. Omitting it reads from main. */
+  ref?: ReadRef | undefined;
 };
 
 /** Parameters for listing collections (size, pageToken). */
@@ -46,12 +72,57 @@ export type {
   ListDocsDoc,
 } from "../models/operations/listdocs.js";
 export type { MessageResponse } from "../models/index.js";
-export type {
-  FetchDocsResponse,
-  FetchDocsDoc,
-} from "../models/operations/fetchdocs.js";
+export type { FetchDocsResponse, FetchDocsDoc } from "../models/operations/fetchdocs.js";
 export type { GetBulkUpsertDocsResponse } from "../models/operations/getbulkupsertdocs.js";
 
+export type {
+  AliasRef,
+  AliasTarget,
+  BranchRef,
+  BranchSource,
+  ReadRef,
+  RefSource,
+  TagRef,
+  TagSource,
+} from "../models/versioning.js";
+
+export type RefDetails = Omit<RefDetailsModel, "createdAt"> & {
+  createdAt: Date;
+};
+
+export type AliasDetails = Omit<AliasDetailsModel, "createdAt"> & {
+  createdAt: Date;
+};
+
+export type CreateBranchInput = {
+  branchName: string;
+  source?: import("../models/versioning.js").RefSource | undefined;
+};
+
+export type CreateBranchResponse = { branch: RefDetails };
+export type ListBranchesResponse = { branches: RefDetails[] };
+
+export type CreateTagInput = {
+  tagName: string;
+  source?: import("../models/versioning.js").RefSource | undefined;
+};
+
+export type CreateTagResponse = { tag: RefDetails };
+export type ListTagsResponse = { tags: RefDetails[] };
+
+export type CreateAliasInput = {
+  aliasName: string;
+  target: import("../models/versioning.js").AliasTarget;
+};
+
+export type RetargetAliasInput = {
+  target: import("../models/versioning.js").AliasTarget;
+};
+
+export type AliasResponse = { alias: AliasDetails };
+export type ListAliasesResponse = { aliases: AliasDetails[] };
+export type GetBulkUpsertInput = { branch?: string | undefined };
+
 // ---- Models referenced by request/response bodies ----
 export type {
   IndexConfigsUnion,
@@ -64,8 +135,11 @@ export type {
   CollectionResponse,
 } from "../models/index.js";
 
-// ---- Timestamp helpers (Unix seconds → Date) ----
+// ---- Timestamp helpers (Unix epoch milliseconds → Date) ----
 import type { CollectionResponse as CollectionResponseModel } from "../models/index.js";
+import type {
+  CreateCollectionResponse as CreateCollectionResponseModel,
+} from "../models/operations/createcollection.js";
 
 /**
  * Collection response with timestamp fields as Date (for better DX).
@@ -75,8 +149,8 @@ export type CollectionResponseWithDates = Omit<
   CollectionResponseModel,
   "createdAt" | "updatedAt" | "dataUpdatedAt"
 > & {
-  createdAt?: Date | undefined;
-  updatedAt?: Date | undefined;
+  createdAt: Date;
+  updatedAt: Date;
   dataUpdatedAt?: Date | undefined;
 };
 
@@ -89,17 +163,19 @@ export type ListCollectionsResponseWithDates = {
 };
 
 /**
- * Converts Unix-second timestamp fields to Date. Safe to call on partial responses.
+ * Converts Unix-millisecond timestamp fields to Date. Safe to call on partial responses.
  */
 export function collectionResponseWithDates(
   c: CollectionResponseModel,
 ): CollectionResponseWithDates {
   const { createdAt, updatedAt, dataUpdatedAt, ...rest } = c;
-  const out: CollectionResponseWithDates = { ...rest };
-  if (createdAt != null) out.createdAt = new Date(createdAt * 1000);
-  if (updatedAt != null) out.updatedAt = new Date(updatedAt * 1000);
+  const out: CollectionResponseWithDates = {
+    ...rest,
+    createdAt: new Date(createdAt),
+    updatedAt: new Date(updatedAt),
+  };
   if (dataUpdatedAt != null)
-    out.dataUpdatedAt = new Date(dataUpdatedAt * 1000);
+    out.dataUpdatedAt = new Date(dataUpdatedAt);
   return out;
 }
 
@@ -126,3 +202,40 @@ export function getCollectionResponseWithDates(res: {
 }): GetCollectionResponseWithDates {
   return { collection: collectionResponseWithDates(res.collection) };
 }
+
+/** Update response with timestamp fields converted to Date. */
+export type UpdateCollectionResponseWithDates = GetCollectionResponseWithDates;
+
+export function updateCollectionResponseWithDates(res: {
+  collection: CollectionResponseModel;
+}): UpdateCollectionResponseWithDates {
+  return getCollectionResponseWithDates(res);
+}
+
+/** Create response with its Unix-millisecond timestamp converted to Date. */
+export type CreateCollectionResponseWithDates = {
+  collection: Omit<CreateCollectionResponseModel["collection"], "createdAt"> & {
+    createdAt: Date;
+  };
+};
+
+export function createCollectionResponseWithDates(
+  response: CreateCollectionResponseModel,
+): CreateCollectionResponseWithDates {
+  return {
+    collection: {
+      ...response.collection,
+      createdAt: new Date(response.collection.createdAt),
+    },
+  };
+}
+
+/** @internal */
+export function refDetailsWithDate(details: RefDetailsModel): RefDetails {
+  return { ...details, createdAt: new Date(details.createdAt) };
+}
+
+/** @internal */
+export function aliasDetailsWithDate(details: AliasDetailsModel): AliasDetails {
+  return { ...details, createdAt: new Date(details.createdAt) };
+}