@dabble/patches 0.4.11 → 0.5.0

package/dist/algorithms/server/commitChanges.js

@@ -1,4 +1,5 @@
 import "../../chunk-IZ2YBCUP.js";
+import { clampTimestamp, createServerTimestamp, timestampDiff } from "../../utils/dates.js";
 import { applyChanges } from "../shared/applyChanges.js";
 import { createVersion } from "./createVersion.js";
 import { getSnapshotAtRevision } from "./getSnapshotAtRevision.js";
@@ -14,6 +15,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis) {
   const currentState = applyChanges(initialState, currentChanges);
   const currentRev = currentChanges.at(-1)?.rev ?? initialRev;
   const baseRev = changes[0].baseRev ?? currentRev;
+  const serverNow = createServerTimestamp();
   let rev = baseRev + 1;
   changes.forEach((c) => {
     if (c.baseRev == null) c.baseRev = baseRev;
@@ -22,7 +24,8 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis) {
     }
     if (c.rev == null) c.rev = rev++;
     else rev = c.rev + 1;
-    c.created = Math.min(c.created, Date.now());
+    c.committedAt = serverNow;
+    c.createdAt = clampTimestamp(c.createdAt, serverNow);
   });
   if (baseRev > currentRev) {
     throw new Error(
@@ -36,7 +39,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis) {
     );
   }
   const lastChange = currentChanges[currentChanges.length - 1];
-  if (lastChange && lastChange.created < Date.now() - sessionTimeoutMillis) {
+  if (lastChange && timestampDiff(serverNow, lastChange.createdAt) > sessionTimeoutMillis) {
     await createVersion(store, docId, currentState, currentChanges);
   }
   const committedChanges = await store.listChanges(docId, {
@@ -48,7 +51,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis) {
   if (incomingChanges.length === 0) {
     return [committedChanges, []];
   }
-  const isOfflineTimestamp = incomingChanges[0].created < Date.now() - sessionTimeoutMillis;
+  const isOfflineTimestamp = timestampDiff(serverNow, incomingChanges[0].createdAt) > sessionTimeoutMillis;
   if (isOfflineTimestamp || batchId) {
     incomingChanges = await handleOfflineSessionsAndBatches(
       store,

package/dist/algorithms/server/createVersion.js

@@ -8,8 +8,9 @@ async function createVersion(store, docId, state, changes, metadata) {
   }
   const sessionMetadata = createVersionMetadata({
     origin: "main",
-    startDate: changes[0].created,
-    endDate: changes[changes.length - 1].created,
+    // Convert client timestamps to UTC for version metadata (enables lexicographic sorting)
+    startedAt: new Date(changes[0].createdAt).toISOString(),
+    endedAt: new Date(changes[changes.length - 1].createdAt).toISOString(),
     rev: changes[changes.length - 1].rev,
     baseRev,
     ...metadata

package/dist/algorithms/server/handleOfflineSessionsAndBatches.js

@@ -1,6 +1,7 @@
 import "../../chunk-IZ2YBCUP.js";
 import { createSortableId } from "crypto-id";
 import { createVersionMetadata } from "../../data/version.js";
+import { timestampDiff } from "../../utils/dates.js";
 import { applyChanges } from "../shared/applyChanges.js";
 import { getStateAtRevision } from "./getStateAtRevision.js";
 async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId) {
@@ -22,11 +23,11 @@ async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docI
   let sessionStartIndex = 0;
   for (let i = 1; i <= changes.length; i++) {
     const isLastChange = i === changes.length;
-    const timeDiff = isLastChange ? Infinity : changes[i].created - changes[i - 1].created;
+    const timeDiff = isLastChange ? Infinity : timestampDiff(changes[i].createdAt, changes[i - 1].createdAt);
     if (timeDiff > sessionTimeoutMillis || isLastChange) {
       const sessionChanges = changes.slice(sessionStartIndex, i);
       if (sessionChanges.length > 0) {
-        const isContinuation = !!lastVersion && sessionChanges[0].created - lastVersion.endDate <= sessionTimeoutMillis;
+        const isContinuation = !!lastVersion && timestampDiff(sessionChanges[0].createdAt, lastVersion.endedAt) <= sessionTimeoutMillis;
         if (isContinuation) {
           const mergedState = applyChanges(offlineBaseState, sessionChanges);
           await store.saveChanges(docId, sessionChanges);
@@ -39,8 +40,9 @@ async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docI
             parentId,
             groupId,
             origin: "offline",
-            startDate: sessionChanges[0].created,
-            endDate: sessionChanges[sessionChanges.length - 1].created,
+            // Convert client timestamps to UTC for version metadata (enables lexicographic sorting)
+            startedAt: new Date(sessionChanges[0].createdAt).toISOString(),
+            endedAt: new Date(sessionChanges[sessionChanges.length - 1].createdAt).toISOString(),
             rev: sessionChanges[sessionChanges.length - 1].rev,
             baseRev
           });

package/dist/data/change.js

@@ -1,6 +1,7 @@
 import "../chunk-IZ2YBCUP.js";
 import { inc } from "alphacounter";
 import { createId } from "crypto-id";
+import { createClientTimestamp } from "../utils/dates.js";
 function createChangeId(rev) {
   return inc.from(rev) + createId(4);
 }
@@ -9,7 +10,7 @@ function createChange(baseRev, rev, ops, metadata) {
     return {
       id: createId(8),
       ops: baseRev,
-      created: Date.now(),
+      createdAt: createClientTimestamp(),
       ...rev
     };
   } else {
@@ -18,7 +19,7 @@ function createChange(baseRev, rev, ops, metadata) {
       baseRev,
       rev,
       ops,
-      created: Date.now(),
+      createdAt: createClientTimestamp(),
       ...metadata
     };
   }

package/dist/net/http/FetchTransport.js

@@ -13,7 +13,7 @@ class FetchTransport {
   }
   async send(raw) {
     try {
-      const response = await fetch(this.url, {
+      const response = await globalThis.fetch(this.url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",

package/dist/server/PatchesBranchManager.js

@@ -2,6 +2,7 @@ import "../chunk-IZ2YBCUP.js";
 import { createId } from "crypto-id";
 import { createChange } from "../data/change.js";
 import { createVersionMetadata } from "../data/version.js";
+import { createServerTimestamp } from "../utils/dates.js";
 class PatchesBranchManager {
   constructor(store, patchesServer) {
     this.store = store;
@@ -30,12 +31,12 @@ class PatchesBranchManager {
     }
     const stateAtRev = (await this.patchesServer.getStateAtRevision(docId, rev)).state;
     const branchDocId = createId();
-    const now = Date.now();
+    const now = createServerTimestamp();
     const initialVersionMetadata = createVersionMetadata({
       origin: "main",
       // Branch doc versions are 'main' until merged
-      startDate: now,
-      endDate: now,
+      startedAt: now,
+      endedAt: now,
       rev,
       baseRev: rev,
       name: metadata?.name,
@@ -48,7 +49,7 @@ class PatchesBranchManager {
       id: branchDocId,
       branchedFromId: docId,
       branchedRev: rev,
-      created: now,
+      createdAt: now,
       status: "open"
     };
     await this.store.createBranch(branch);
@@ -126,7 +127,7 @@ class PatchesBranchManager {
     return committedMergeChanges;
   }
 }
-const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "branchedFromId", "branchedRev", "created", "status"]);
+const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "branchedFromId", "branchedRev", "createdAt", "status"]);
 function assertBranchMetadata(metadata) {
   if (!metadata) return;
   for (const key in metadata) {

package/dist/server/PatchesHistoryManager.js

@@ -14,7 +14,7 @@ class PatchesHistoryManager {
    */
   async listVersions(docId, options = {}) {
     if (!options.orderBy) {
-      options.orderBy = "startDate";
+      options.orderBy = "startedAt";
     }
     return await this.store.listVersions(docId, options);
   }

package/dist/server/PatchesServer.js

@@ -119,8 +119,8 @@ const nonModifiableMetadataFields = /* @__PURE__ */ new Set([
   "groupId",
   "origin",
   "branchName",
-  "startDate",
-  "endDate",
+  "startedAt",
+  "endedAt",
   "rev",
   "baseRev"
 ]);

package/dist/types.d.ts

@@ -17,8 +17,8 @@ interface ChangeInput {
     baseRev?: number;
     /** Optional revision number. If omitted, server assigns based on current state. */
     rev?: number;
-    /** Client-side timestamp when the change was created. */
-    created: number;
+    /** Client-side ISO timestamp when the change was created (with timezone offset). */
+    createdAt: string;
     /** Optional batch identifier for grouping changes that belong to the same client batch (for multi-batch offline/large edits). */
     batchId?: string;
     /** Optional arbitrary metadata associated with the change. */
@@ -33,6 +33,8 @@ interface Change extends ChangeInput {
     baseRev: number;
     /** The revision number assigned by the server after commit. */
     rev: number;
+    /** Server-side ISO timestamp when the change was committed (UTC with Z). */
+    committedAt: string;
 }
 /**
  * Represents the state of a document in the OT protocol.
@@ -69,8 +71,8 @@ interface Branch {
     branchedFromId: string;
     /** The revision number on the source document where the branch occurred. */
     branchedRev: number;
-    /** Server-side timestamp when the branch record was created. */
-    created: number;
+    /** Server-side ISO timestamp when the branch was created (UTC with Z). */
+    createdAt: string;
     /** Optional user-friendly name for the branch. */
     name?: string;
     /** Current status of the branch. */
@@ -78,7 +80,7 @@ interface Branch {
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
-type EditableBranchMetadata = Disallowed<Branch, 'id' | 'branchedFromId' | 'branchedRev' | 'created' | 'status'>;
+type EditableBranchMetadata = Disallowed<Branch, 'id' | 'branchedFromId' | 'branchedRev' | 'createdAt' | 'status'>;
 /**
  * Metadata, state snapshot, and included changes for a specific version.
  */
@@ -94,10 +96,10 @@ interface VersionMetadata {
     origin: 'main' | 'offline' | 'branch';
     /** User-defined name if origin is 'branch'. */
     branchName?: string;
-    /** Timestamp marking the beginning of the changes included in this version (e.g., first change in session). */
-    startDate: number;
-    /** Timestamp marking the end of the changes included in this version (e.g., last change in session). */
-    endDate: number;
+    /** Server-side ISO timestamp of version start (UTC with Z). */
+    startedAt: string;
+    /** Server-side ISO timestamp of version end (UTC with Z). */
+    endedAt: string;
     /** The revision number this version was created at. */
     rev: number;
     /** The revision number on the main timeline before the changes that created this version. If this is an offline/branch version, this is the revision number of the source document where the branch was created and not . */
@@ -108,7 +110,7 @@ interface VersionMetadata {
 type Disallowed<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>> & {
     [P in K]?: never;
 };
-type EditableVersionMetadata = Disallowed<VersionMetadata, 'id' | 'parentId' | 'groupId' | 'origin' | 'branchName' | 'startDate' | 'endDate' | 'rev' | 'baseRev'>;
+type EditableVersionMetadata = Disallowed<VersionMetadata, 'id' | 'parentId' | 'groupId' | 'origin' | 'branchName' | 'startedAt' | 'endedAt' | 'rev' | 'baseRev'>;
 /**
  * Options for listing committed server changes. *Always* ordered by revision number.
  */
@@ -129,13 +131,13 @@ interface ListChangesOptions {
  */
 interface ListVersionsOptions {
     /** List versions whose orderBy field is *after* this value. */
-    startAfter?: number;
+    startAfter?: number | string;
     /** List versions whose orderBy field is strictly *before* this value. */
-    endBefore?: number;
+    endBefore?: number | string;
     /** Maximum number of versions to return. */
     limit?: number;
-    /** Sort by start date, rev, or baseRev. Defaults to 'rev'. */
-    orderBy?: 'startDate' | 'rev' | 'baseRev';
+    /** Sort by startedAt, rev, or baseRev. Defaults to 'rev'. */
+    orderBy?: 'startedAt' | 'rev' | 'baseRev';
     /** Return versions in descending order. Defaults to false (ascending). When reversed, startAfter and endBefore apply to the *reversed* list. */
     reverse?: boolean;
     /** Filter by the origin type. */

package/dist/utils/dates.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Date utility functions for creating and manipulating ISO 8601 timestamps.
+ *
+ * Client-side timestamps use local timezone offsets (e.g., +04:00).
+ * Server-side timestamps use UTC with Z suffix.
+ */
+/**
+ * Creates an ISO string with local timezone offset for client dates.
+ * Example: "2025-12-26T14:00:00.000+04:00"
+ */
+declare function createClientTimestamp(): string;
+/**
+ * Creates an ISO string with Z suffix for server dates.
+ * Example: "2025-12-26T10:00:00.000Z"
+ */
+declare function createServerTimestamp(): string;
+/**
+ * Parses an ISO string to a Date for comparisons.
+ */
+declare function parseTimestamp(iso: string): Date;
+/**
+ * Calculates milliseconds between two ISO timestamps.
+ * Returns (a - b) in milliseconds.
+ */
+declare function timestampDiff(a: string, b: string): number;
+/**
+ * Extracts the timezone offset string from an ISO timestamp.
+ * Returns "+04:00", "-05:00", or "Z".
+ */
+declare function extractTimezoneOffset(iso: string): string;
+/**
+ * Clamps a timestamp to not exceed a limit, preserving the original timezone offset.
+ * Returns the original if it's <= limit, otherwise returns limit in original's timezone.
+ *
+ * Example:
+ *   timestamp: "2025-12-26T18:00:00.000+04:00" (future)
+ *   limit:     "2025-12-26T10:00:00.000Z"      (server time)
+ *   result:    "2025-12-26T14:00:00.000+04:00" (clamped, same instant as limit)
+ */
+declare function clampTimestamp(timestamp: string, limit: string): string;
+/**
+ * Formats a Date with a specific timezone offset string.
+ * The date is adjusted to display the correct local time for that offset.
+ */
+declare function formatWithOffset(date: Date, offset: string): string;
+/**
+ * Gets the local timezone offset string for the current environment.
+ * Returns "+04:00", "-05:00", or "Z" for UTC.
+ */
+declare function getLocalTimezoneOffset(): string;
+
+export { clampTimestamp, createClientTimestamp, createServerTimestamp, extractTimezoneOffset, formatWithOffset, getLocalTimezoneOffset, parseTimestamp, timestampDiff };

package/dist/utils/dates.js

@@ -0,0 +1,57 @@
+import "../chunk-IZ2YBCUP.js";
+function createClientTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  return formatWithOffset(now, getLocalTimezoneOffset());
+}
+function createServerTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function parseTimestamp(iso) {
+  return new Date(iso);
+}
+function timestampDiff(a, b) {
+  return new Date(a).getTime() - new Date(b).getTime();
+}
+function extractTimezoneOffset(iso) {
+  const match = iso.match(/([+-]\d{2}:\d{2}|Z)$/);
+  return match ? match[1] : "Z";
+}
+function clampTimestamp(timestamp, limit) {
+  const timestampDate = new Date(timestamp);
+  const limitDate = new Date(limit);
+  if (timestampDate <= limitDate) {
+    return timestamp;
+  }
+  const offset = extractTimezoneOffset(timestamp);
+  return formatWithOffset(limitDate, offset);
+}
+function formatWithOffset(date, offset) {
+  if (offset === "Z") {
+    return date.toISOString();
+  }
+  const match = offset.match(/([+-])(\d{2}):(\d{2})/);
+  if (!match) return date.toISOString();
+  const sign = match[1] === "+" ? 1 : -1;
+  const offsetMinutes = sign * (parseInt(match[2]) * 60 + parseInt(match[3]));
+  const localDate = new Date(date.getTime() + offsetMinutes * 60 * 1e3);
+  const iso = localDate.toISOString();
+  return iso.slice(0, -1) + offset;
+}
+function getLocalTimezoneOffset() {
+  const offset = -(/* @__PURE__ */ new Date()).getTimezoneOffset();
+  if (offset === 0) return "Z";
+  const hours = Math.floor(Math.abs(offset) / 60);
+  const mins = Math.abs(offset) % 60;
+  const sign = offset >= 0 ? "+" : "-";
+  return `${sign}${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}`;
+}
+export {
+  clampTimestamp,
+  createClientTimestamp,
+  createServerTimestamp,
+  extractTimezoneOffset,
+  formatWithOffset,
+  getLocalTimezoneOffset,
+  parseTimestamp,
+  timestampDiff
+};

package/package.json

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