convex 1.42.2 → 1.43.0-alpha.0

package/src/values/value.test.ts

@@ -8,6 +8,7 @@ import {
   modernBigIntToBase64,
   convexToJson,
   jsonToConvex,
+  commitTsPlaceholder,
 } from "./value.js";
 import { compareValues } from "./compare.js";
 
@@ -88,6 +89,36 @@ describe("jsonToConvex", () => {
   });
 });
 
+describe("commit timestamp sentinel", () => {
+  test("round trips through JSON as the singleton", () => {
+    const decoded = jsonToConvex({ property: { $commitTs: null } }) as any;
+    expect(decoded.property).toBe(commitTsPlaceholder);
+    expect(convexToJson({ property: commitTsPlaceholder as any })).toEqual({
+      property: { $commitTs: null },
+    });
+  });
+
+  test("rejects malformed tokens", () => {
+    expect(() => jsonToConvex({ $commitTs: 1 } as any)).toThrow(
+      /Malformed \$commitTs/,
+    );
+    // A `$commitTs` key alongside other fields is not the token; it's an
+    // invalid field name.
+    expect(() => jsonToConvex({ $commitTs: null, x: 1 })).toThrow(/reserved/);
+  });
+
+  test("throws on coercion", () => {
+    expect(() => Number(commitTsPlaceholder)).toThrow(/unresolved/);
+    expect(() => (commitTsPlaceholder as any) + 1n).toThrow(/unresolved/);
+    expect(() => JSON.stringify({ commitTs: commitTsPlaceholder })).toThrow(
+      /unresolved/,
+    );
+    expect(`${commitTsPlaceholder as any}`).toEqual(
+      "[unresolved commit timestamp]",
+    );
+  });
+});
+
 describe("bigints in Safari 14", () => {
   test("roundtrips BigInt even in Safari 14", () => {
     // https://caniuse.com/mdn-javascript_builtins_dataview_setbigint64
@@ -194,4 +225,8 @@ describe("compare", () => {
       }
     }
   });
+
+  test("commit timestamp placeholders compare equal", () => {
+    expect(compareValues(commitTsPlaceholder, commitTsPlaceholder)).toEqual(0);
+  });
 });

package/src/values/value.ts

@@ -11,7 +11,7 @@ import { isSimpleObject } from "../common/index.js";
 const LITTLE_ENDIAN = true;
 // This code is used by code that may not have bigint literals.
 const MIN_INT64 = BigInt("-9223372036854775808");
-const MAX_INT64 = BigInt("9223372036854775807");
+export const MAX_INT64 = BigInt("9223372036854775807");
 const ZERO = BigInt("0");
 const EIGHT = BigInt("8");
 const TWOFIFTYSIX = BigInt("256");
@@ -70,6 +70,7 @@ export type Value =
   | boolean
   | string
   | ArrayBuffer
+  | CommitTsPlaceholder
   | Value[]
   | { [key: string]: undefined | Value };
 
@@ -80,6 +81,51 @@ export type Value =
  */
 export type NumericValue = bigint | number;
 
+const COMMIT_TS_UNRESOLVED =
+  "This commit timestamp is unresolved: its value is assigned when the " +
+  "mutation commits. Read the document after the mutation completes to get " +
+  "its value.";
+
+/**
+ * The placeholder for a transaction's commit timestamp, which is not known
+ * until the mutation commits. Write it into a document field via
+ * `db.vars.commitTs` and it resolves to an int64 (`bigint`) at commit,
+ * ordered by commit order. Reading the field back within the writing
+ * mutation yields the placeholder, which cannot be used as a number.
+ *
+ * @public
+ */
+export class CommitTsPlaceholder {
+  // A private member makes the class nominal: no structurally-similar object
+  // type-checks as a placeholder.
+  declare private readonly __isCommitTsPlaceholder: undefined;
+  [Symbol.toPrimitive](hint: string): string {
+    // Allow string conversion so logging a read-back document doesn't throw.
+    if (hint === "string") {
+      return this.toString();
+    }
+    throw new Error(COMMIT_TS_UNRESOLVED);
+  }
+  valueOf(): never {
+    throw new Error(COMMIT_TS_UNRESOLVED);
+  }
+  toJSON(): never {
+    throw new Error(COMMIT_TS_UNRESOLVED);
+  }
+  toString(): string {
+    return "[unresolved commit timestamp]";
+  }
+}
+
+/**
+ * The placeholder for a commit timestamp that is not yet known, exposed as
+ * `db.vars.commitTs`. A singleton so that a value read back within the
+ * writing mutation compares equal to `db.vars.commitTs`.
+ *
+ * @internal
+ */
+export const commitTsPlaceholder = new CommitTsPlaceholder();
+
 function isSpecial(n: number) {
   return Number.isNaN(n) || !Number.isFinite(n) || Object.is(n, -0);
 }
@@ -235,6 +281,12 @@ export function jsonToConvex(value: JSONValue): Value {
       }
       return float;
     }
+    if (key === "$commitTs") {
+      if (value.$commitTs !== null) {
+        throw new Error(`Malformed $commitTs field on ${value as any}`);
+      }
+      return commitTsPlaceholder;
+    }
     if (key === "$set") {
       throw new Error(
         `Received a Set which is no longer supported as a Convex type.`,
@@ -330,6 +382,9 @@ function convexToJsonInternal(
   if (value instanceof ArrayBuffer) {
     return { $bytes: Base64.fromByteArray(new Uint8Array(value)) };
   }
+  if (value instanceof CommitTsPlaceholder) {
+    return { $commitTs: null };
+  }
   if (Array.isArray(value)) {
     return value.map((value, i) =>
       convexToJsonInternal(value, originalValue, context + `[${i}]`, false),