@functional-systems/lambdadb 0.5.0-rc.2 → 0.5.0

package/src/models/versioning.ts

@@ -27,16 +27,46 @@ export type BranchSource = BranchRef & {
 
 export type TagSource = TagRef;
 
-/** A Branch or Tag used as the source of a new Branch or Tag. */
+/** A Branch or Tag used as the source of a new 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 = {
+export type SnapshotDetails = {
+  snapshotId: string;
+  /** Snapshot commit time as Unix epoch milliseconds. */
+  snapshotCommittedAt: number;
+};
+
+/** Historical direct source identity, independent of snapshot origin. */
+export type ParentBranchDetails = {
+  branchId: string;
+  name: string;
+};
+
+export type BranchDetails = {
   name: string;
-  snapshotId: string | null;
-  /** Ref creation time as Unix epoch milliseconds. */
+  /**
+   * Fixed direct source, even for an empty head or an ancestor snapshot selected
+   * by asOf. Null for main or unrecorded parents. Survives parent deletion and
+   * name reuse; this metadata does not prevent parent deletion.
+   */
+  parentBranch: ParentBranchDetails | null;
+  /** 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 +129,31 @@ 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 ParentBranchDetails$inboundSchema: z.ZodType<ParentBranchDetails> = z.object({
+  branchId: z.string(),
+  name: z.string(),
+});
+
+/** @internal */
+export const BranchDetails$inboundSchema: z.ZodType<BranchDetails> = z.object({
+  name: z.string(),
+  parentBranch: ParentBranchDetails$inboundSchema.nullable(),
+  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/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";
 
@@ -80,13 +82,25 @@ export type {
   AliasTarget,
   BranchRef,
   BranchSource,
+  ParentBranchDetails,
   ReadRef,
   RefSource,
   TagRef,
   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;
 };
 
@@ -96,19 +110,20 @@ export type AliasDetails = Omit<AliasDetailsModel, "createdAt"> & {
 
 export type CreateBranchInput = {
   branchName: string;
-  source?: import("../models/versioning.js").RefSource | undefined;
+  /** Omit to use main; only Branch sources support creating a Branch. */
+  source?: import("../models/versioning.js").BranchSource | 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 +246,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,9 @@ import type { SDKValidationError } from "./models/errors/sdkvalidationerror.js";
 import {
   AliasDetails$inboundSchema,
   AliasTarget$schema,
-  RefDetails$inboundSchema,
+  BranchDetails$inboundSchema,
+  BranchSource$schema,
+  TagDetails$inboundSchema,
   RefSource$schema,
   type AliasRef,
   type BranchRef,
@@ -30,7 +32,8 @@ import type {
 } from "./models/errors/httpclienterrors.js";
 import {
   aliasDetailsWithDate,
-  refDetailsWithDate,
+  branchDetailsWithDates,
+  tagDetailsWithDates,
   type AliasResponse,
   type CreateAliasInput,
   type CreateBranchInput,
@@ -47,7 +50,7 @@ import type { Result } from "./types/fp.js";
 
 /** Exact public contract revision implemented by this SDK. */
 export const DATA_VERSIONING_CONTRACT_REVISION =
-  "b171ff0a408bbeb024535941b83b861d205a829f" as const;
+  "c44180406c05b1a9043d8516e7c7f60df91fc9a7" as const;
 
 const refNamePattern = /^[a-zA-Z0-9_-]{3,52}$/;
 const refNameSchema = z.string().regex(refNamePattern);
@@ -235,17 +238,17 @@ function pathFor(collectionName: string, suffix: string): string {
 
 const createBranchSchema: z.ZodType<CreateBranchInput> = z.object({
   branchName: z.string().regex(refNamePattern),
-  source: RefSource$schema.optional(),
+  source: BranchSource$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),
@@ -284,7 +287,7 @@ export class CollectionBranches {
       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> {
@@ -301,7 +304,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> {
@@ -356,7 +359,7 @@ export class CollectionTags {
       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> {
@@ -373,7 +376,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> {