@dabble/patches 0.2.18 → 0.2.19

package/dist/server/PatchesBranchManager.d.ts

@@ -1,4 +1,4 @@
-import type { Branch, BranchStatus, Change } from '../types.js';
+import type { Branch, BranchStatus, Change, EditableBranchMetadata } from '../types.js';
 import type { PatchesServer } from './PatchesServer.js';
 import type { BranchingStoreBackend } from './types.js';
 /**
@@ -24,7 +24,13 @@ export declare class PatchesBranchManager {
      * @param metadata - Additional optional metadata to store with the branch.
      * @returns The ID of the new branch document.
      */
-    createBranch(docId: string, rev: number, branchName?: string, metadata?: Record<string, any>): Promise<string>;
+    createBranch(docId: string, rev: number, metadata?: EditableBranchMetadata): Promise<string>;
+    /**
+     * Updates a branch's metadata.
+     * @param branchId - The ID of the branch to update.
+     * @param metadata - The metadata to update.
+     */
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
     /**
      * Closes a branch, marking it as merged or deleted.
      * @param branchId - The ID of the branch to close.
@@ -39,3 +45,4 @@ export declare class PatchesBranchManager {
      */
     mergeBranch(branchId: string): Promise<Change[]>;
 }
+export declare function assertBranchMetadata(metadata?: EditableBranchMetadata): void;

package/dist/server/PatchesBranchManager.js

@@ -25,7 +25,7 @@ export class PatchesBranchManager {
      * @param metadata - Additional optional metadata to store with the branch.
      * @returns The ID of the new branch document.
      */
-    async createBranch(docId, rev, branchName, metadata) {
+    async createBranch(docId, rev, metadata) {
         // Prevent branching off a branch
         const maybeBranch = await this.store.loadBranch(docId);
         if (maybeBranch) {
@@ -43,24 +43,32 @@ export class PatchesBranchManager {
             endDate: now,
             rev,
             baseRev: rev,
-            name: branchName,
+            name: metadata?.name,
             groupId: branchDocId,
-            branchName,
+            branchName: metadata?.name,
         };
         await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
         // 2. Create the branch metadata record
         const branch = {
+            ...metadata,
             id: branchDocId,
             branchedFromId: docId,
             branchedRev: rev,
             created: now,
-            name: branchName,
             status: 'open',
-            ...(metadata && { metadata }),
         };
         await this.store.createBranch(branch);
         return branchDocId;
     }
+    /**
+     * Updates a branch's metadata.
+     * @param branchId - The ID of the branch to update.
+     * @param metadata - The metadata to update.
+     */
+    async updateBranch(branchId, metadata) {
+        assertBranchMetadata(metadata);
+        await this.store.updateBranch(branchId, metadata);
+    }
     /**
      * Closes a branch, marking it as merged or deleted.
      * @param branchId - The ID of the branch to close.
@@ -136,3 +144,13 @@ export class PatchesBranchManager {
         return committedMergeChanges;
     }
 }
+const nonModifiableMetadataFields = new Set(['id', 'branchedFromId', 'branchedRev', 'created', 'status']);
+export function assertBranchMetadata(metadata) {
+    if (!metadata)
+        return;
+    for (const key in metadata) {
+        if (nonModifiableMetadataFields.has(key)) {
+            throw new Error(`Cannot modify branch field ${key}`);
+        }
+    }
+}

package/dist/server/PatchesHistoryManager.d.ts

@@ -1,5 +1,5 @@
-import type { Change, ListVersionsOptions, VersionMetadata } from '../types.js';
-import type { PatchesServer } from './PatchesServer.js';
+import type { Change, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, VersionMetadata } from '../types.js';
+import { type PatchesServer } from './PatchesServer.js';
 /**
  * Helps retrieve historical information (versions, changes) for a document
  * using the new versioning model based on IDs and metadata.
@@ -21,14 +21,14 @@ export declare class PatchesHistoryManager {
      * @param name The name of the version.
      * @returns The ID of the created version.
      */
-    createVersion(docId: string, name: string): Promise<string>;
+    createVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string>;
     /**
      * Updates the name of a specific version.
      * @param docId - The ID of the document.
      * @param versionId - The ID of the version to update.
      * @param name - The new name for the version.
      */
-    updateVersion(docId: string, versionId: string, updates: Pick<VersionMetadata, 'name'>): Promise<void>;
+    updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     /**
      * Loads the full document state snapshot for a specific version by its ID.
      * @param docId - The ID of the document.
@@ -53,10 +53,5 @@ export declare class PatchesHistoryManager {
      * @param options - Options like start/end revision, limit.
      * @returns The list of committed Change objects.
      */
-    listServerChanges(docId: string, options?: {
-        limit?: number;
-        startAfterRev?: number;
-        endBeforeRev?: number;
-        reverse?: boolean;
-    }): Promise<Change[]>;
+    listServerChanges(docId: string, options?: ListChangesOptions): Promise<Change[]>;
 }

package/dist/server/PatchesHistoryManager.js

@@ -1,3 +1,4 @@
+import { assertVersionMetadata } from './PatchesServer.js';
 /**
  * Helps retrieve historical information (versions, changes) for a document
  * using the new versioning model based on IDs and metadata.
@@ -25,8 +26,9 @@ export class PatchesHistoryManager {
      * @param name The name of the version.
      * @returns The ID of the created version.
      */
-    async createVersion(docId, name) {
-        return await this.patches.createVersion(docId, name);
+    async createVersion(docId, metadata) {
+        assertVersionMetadata(metadata);
+        return await this.patches.createVersion(docId, metadata);
     }
     /**
      * Updates the name of a specific version.
@@ -34,8 +36,9 @@ export class PatchesHistoryManager {
      * @param versionId - The ID of the version to update.
      * @param name - The new name for the version.
      */
-    async updateVersion(docId, versionId, updates) {
-        return this.store.updateVersion(docId, versionId, { name: updates.name });
+    async updateVersion(docId, versionId, metadata) {
+        assertVersionMetadata(metadata);
+        return this.store.updateVersion(docId, versionId, metadata);
     }
     /**
      * Loads the full document state snapshot for a specific version by its ID.
@@ -78,7 +81,6 @@ export class PatchesHistoryManager {
      * @returns The list of committed Change objects.
      */
     async listServerChanges(docId, options = {}) {
-        // Added return type
         return await this.store.listChanges(docId, options);
     }
 }

package/dist/server/PatchesServer.d.ts

@@ -1,4 +1,4 @@
-import type { Change, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
+import type { Change, EditableVersionMetadata, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
 import type { PatchesStoreBackend } from './types.js';
 /**
  * Configuration options for the PatchesServer.
@@ -67,7 +67,7 @@ export declare class PatchesServer {
      * @param name The name of the version.
      * @returns The ID of the created version.
      */
-    createVersion(docId: string, name: string): Promise<string>;
+    createVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string>;
     /**
      * Gets the state at a specific revision.
      * @param docId The document ID.
@@ -88,10 +88,10 @@ export declare class PatchesServer {
      * @param docId The document ID.
      * @param state The document state at the time of the version.
      * @param changes The changes since the last version that created the state (the last change's rev is the state's rev and will be the version's rev).
-     * @param name The name of the version.
+     * @param metadata The metadata of the version.
      * @returns The ID of the created version.
      */
-    protected _createVersion(docId: string, state: any, changes: Change[], name?: string): Promise<VersionMetadata | undefined>;
+    protected _createVersion(docId: string, state: any, changes: Change[], metadata?: EditableVersionMetadata): Promise<VersionMetadata | undefined>;
     /**
      * Handles offline/large batch versioning logic for multi-batch uploads.
      * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
@@ -103,3 +103,4 @@ export declare class PatchesServer {
      */
     protected _handleOfflineBatches(docId: string, changes: Change[], baseRev: number, batchId?: string): Promise<Change[]>;
 }
+export declare function assertVersionMetadata(metadata?: EditableVersionMetadata): void;

package/dist/server/PatchesServer.js

@@ -159,10 +159,11 @@ export class PatchesServer {
      * @param name The name of the version.
      * @returns The ID of the created version.
      */
-    async createVersion(docId, name) {
+    async createVersion(docId, metadata) {
+        assertVersionMetadata(metadata);
         let { state, changes } = await this._getSnapshotAtRevision(docId);
         state = applyChanges(state, changes);
-        const version = await this._createVersion(docId, state, changes, name);
+        const version = await this._createVersion(docId, state, changes, metadata);
         if (!version) {
             throw new Error(`No changes to create a version for doc ${docId}.`);
         }
@@ -218,10 +219,10 @@ export class PatchesServer {
      * @param docId The document ID.
      * @param state The document state at the time of the version.
      * @param changes The changes since the last version that created the state (the last change's rev is the state's rev and will be the version's rev).
-     * @param name The name of the version.
+     * @param metadata The metadata of the version.
      * @returns The ID of the created version.
      */
-    async _createVersion(docId, state, changes, name) {
+    async _createVersion(docId, state, changes, metadata) {
         if (changes.length === 0)
             return;
         const baseRev = changes[0].baseRev;
@@ -231,12 +232,12 @@ export class PatchesServer {
         const versionId = createId();
         const sessionMetadata = {
             id: versionId,
-            name,
             origin: 'main',
             startDate: changes[0].created,
             endDate: changes[changes.length - 1].created,
             rev: changes[changes.length - 1].rev,
             baseRev,
+            ...metadata,
         };
         await this.store.createVersion(docId, sessionMetadata, state, changes);
         return sessionMetadata;
@@ -320,3 +321,23 @@ export class PatchesServer {
         ];
     }
 }
+const nonModifiableMetadataFields = new Set([
+    'id',
+    'parentId',
+    'groupId',
+    'origin',
+    'branchName',
+    'startDate',
+    'endDate',
+    'rev',
+    'baseRev',
+]);
+export function assertVersionMetadata(metadata) {
+    if (!metadata)
+        return;
+    for (const key in metadata) {
+        if (nonModifiableMetadataFields.has(key)) {
+            throw new Error(`Cannot modify version field ${key}`);
+        }
+    }
+}

package/dist/server/types.d.ts

@@ -1,4 +1,4 @@
-import type { Branch, Change, ListChangesOptions, ListVersionsOptions, VersionMetadata } from '../types';
+import type { Branch, Change, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, VersionMetadata } from '../types';
 /**
  * Interface for a backend storage system for patch synchronization.
  * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
@@ -18,7 +18,7 @@ export interface PatchesStoreBackend {
      */
     createVersion(docId: string, metadata: VersionMetadata, state: any, changes: Change[]): Promise<void>;
     /** Update a version's metadata. */
-    updateVersion(docId: string, versionId: string, metadata: Partial<VersionMetadata>): Promise<void>;
+    updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     /** Lists version metadata based on filtering/sorting options. */
     listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
     /** Loads the state snapshot for a specific version ID. */

package/dist/types.d.ts

@@ -51,6 +51,7 @@ export interface Branch {
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
+export type EditableBranchMetadata = Disallowed<Branch, 'id' | 'branchedFromId' | 'branchedRev' | 'created' | 'status'>;
 /**
  * Metadata, state snapshot, and included changes for a specific version.
  */
@@ -77,6 +78,10 @@ export interface VersionMetadata {
     /** Optional arbitrary metadata associated with the version. */
     [metadata: string]: any;
 }
+type Disallowed<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>> & {
+    [P in K]?: never;
+};
+export type EditableVersionMetadata = Disallowed<VersionMetadata, 'id' | 'parentId' | 'groupId' | 'origin' | 'branchName' | 'startDate' | 'endDate' | 'rev' | 'baseRev'>;
 /**
  * Options for listing committed server changes. *Always* ordered by revision number.
  */
@@ -117,3 +122,4 @@ export interface Deferred<T = void> {
     reject: (reason?: any) => void;
     status: 'pending' | 'fulfilled' | 'rejected';
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {