@evolu/common 6.0.1-preview.12 → 6.0.1-preview.14

package/src/Evolu/Evolu.ts

@@ -45,6 +45,7 @@ import {
 } from "./Query.js";
 import {
   CreateQuery,
+  DefaultColumns,
   EvoluSchema,
   evoluSchemaToDbSchema,
   insertable,
@@ -253,34 +254,154 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
   readonly getSyncState: () => SyncState;
 
   /**
-   * Inserts a row.
+   * Inserts a row into the database and returns a {@link Result} with the new
+   * {@link Id}.
+   *
+   * The first argument is the table name, and the second is an object
+   * containing the row data. An optional third argument provides mutation
+   * options including an `onComplete` callback and `onlyValidate` flag.
+   *
+   * Returns a Result type - use `.ok` to check if the insertion succeeded, and
+   * `.value.id` to access the generated ID on success, or `.error` to handle
+   * validation errors.
+   *
+   * Evolu does not use SQL for mutations to ensure data can be safely and
+   * predictably merged without conflicts. Explicit mutations also allow Evolu
+   * to automatically add and update {@link DefaultColumns}.
    *
    * ### Example
    *
    * ```ts
-   * // TODO:
+   * const result = evolu.insert("todo", {
+   *   title: "Learn Evolu",
+   *   isCompleted: false,
+   * });
+   *
+   * if (result.ok) {
+   *   console.log("Todo created with ID:", result.value.id);
+   * } else {
+   *   console.error("Validation error:", result.error);
+   * }
+   *
+   * // With onComplete callback
+   * evolu.insert(
+   *   "todo",
+   *   { title: "Another todo" },
+   *   {
+   *     onComplete: () => {
+   *       console.log("Insert completed");
+   *     },
+   *   },
+   * );
    * ```
    */
   insert: Mutation<S, "insert">;
 
   /**
-   * Updates a row.
+   * Updates a row in the database and returns a {@link Result} with the existing
+   * {@link Id}.
+   *
+   * The first argument is the table name, and the second is an object
+   * containing the row data including the required `id` field. An optional
+   * third argument provides mutation options including an `onComplete` callback
+   * and `onlyValidate` flag.
+   *
+   * Returns a Result type - use `.ok` to check if the update succeeded, and
+   * `.value.id` to access the ID on success, or `.error` to handle validation
+   * errors.
+   *
+   * Evolu does not use SQL for mutations to ensure data can be safely and
+   * predictably merged without conflicts. Explicit mutations also allow Evolu
+   * to automatically add and update {@link DefaultColumns}.
    *
    * ### Example
    *
    * ```ts
-   * // TODO:
+   * const result = evolu.update("todo", {
+   *   id: todoId,
+   *   title: "Updated title",
+   *   isCompleted: true,
+   * });
+   *
+   * if (result.ok) {
+   *   console.log("Todo updated with ID:", result.value.id);
+   * } else {
+   *   console.error("Validation error:", result.error);
+   * }
+   *
+   * // To delete a row, set isDeleted to true
+   * evolu.update("todo", { id: todoId, isDeleted: true });
+   *
+   * // With onComplete callback
+   * evolu.update(
+   *   "todo",
+   *   { id: todoId, title: "New title" },
+   *   {
+   *     onComplete: () => {
+   *       console.log("Update completed");
+   *     },
+   *   },
+   * );
    * ```
    */
   update: Mutation<S, "update">;
 
   /**
-   * Upserts a row.
+   * Upserts a row in the database and returns a {@link Result} with the existing
+   * {@link Id}.
+   *
+   * The first argument is the table name, and the second is an object
+   * containing the row data including the required `id` field. An optional
+   * third argument provides mutation options including an `onComplete` callback
+   * and `onlyValidate` flag.
+   *
+   * This function allows you to use custom IDs and optionally set `createdAt`,
+   * which is useful for external systems, data migrations, or when the same row
+   * may already be created on a different device.
+   *
+   * Returns a Result type - use `.ok` to check if the upsert succeeded, and
+   * `.value.id` to access the ID on success, or `.error` to handle validation
+   * errors.
+   *
+   * Evolu does not use SQL for mutations to ensure data can be safely and
+   * predictably merged without conflicts. Explicit mutations also allow Evolu
+   * to automatically add and update {@link DefaultColumns}.
    *
    * ### Example
    *
    * ```ts
-   * // TODO:
+   * // Use deterministic ID for stable upserts across devices
+   * const stableId = createIdFromString("my-todo-1");
+   *
+   * const result = evolu.upsert("todo", {
+   *   id: stableId,
+   *   title: "Learn Evolu",
+   *   isCompleted: false,
+   * });
+   *
+   * if (result.ok) {
+   *   console.log("Todo upserted with ID:", result.value.id);
+   * } else {
+   *   console.error("Validation error:", result.error);
+   * }
+   *
+   * // Data migration with custom createdAt
+   * evolu.upsert("todo", {
+   *   id: externalId,
+   *   title: "Migrated todo",
+   *   createdAt: new Date("2023-01-01"), // Preserve original timestamp
+   * });
+   *
+   * // With onComplete callback
+   * evolu.upsert(
+   *   "todo",
+   *   { id: stableId, title: "Updated title" },
+   *   {
+   *     onComplete: () => {
+   *       console.log("Upsert completed");
+   *     },
+   *   },
+   * );
    * ```
    */
   upsert: Mutation<S, "upsert">;
@@ -594,7 +715,11 @@ const createEvoluInstance =
           const values = getMutationType(table, "insert").fromUnknown(props);
 
           if (values.ok) {
-            const dbChange = { table, id, values: values.value };
+            const valuesWithCreatedAt = {
+              ...values.value,
+              createdAt: new Date(deps.time.now()).toISOString(),
+            };
+            const dbChange = { table, id, values: valuesWithCreatedAt };
             assertValidDbChange(dbChange);
             initialDataDbChanges.push(dbChange);
             return ok({ id });
@@ -646,10 +771,23 @@ const createEvoluInstance =
             // We insert `undefined` to detect such a situation.
             mutateMicrotaskQueue.push([undefined, undefined]);
           } else {
-            // Remove `id` from values.
-            const { id: _id, ...values } = result.value;
-            const dbChange = { table, id, values };
+            const values = { ...result.value };
+
+            delete values.id;
+            if (kind === "insert" || kind === "upsert") {
+              // Only set createdAt if not provided by user
+              if (!("createdAt" in values)) {
+                values.createdAt = new Date(deps.time.now()).toISOString();
+              }
+            }
+
+            const dbChange = {
+              table,
+              id,
+              values,
+            };
             assertValidDbChange(dbChange);
+
             mutateMicrotaskQueue.push([dbChange, options?.onComplete]);
           }
 

package/src/Evolu/Protocol.ts

@@ -188,8 +188,10 @@ import {
 } from "./Owner.js";
 import {
   BinaryTimestamp,
+  binaryTimestampLength,
   binaryTimestampToTimestamp,
   Counter,
+  eqTimestamp,
   Millis,
   NodeId,
   Timestamp,
@@ -399,7 +401,8 @@ export type ProtocolError =
   | ProtocolInvalidDataError
   | ProtocolWriteKeyError
   | ProtocolWriteError
-  | ProtocolSyncError;
+  | ProtocolSyncError
+  | ProtocolTimestampMismatchError;
 
 /** Base interface for all protocol errors. */
 export interface ProtocolErrorBase {
@@ -445,6 +448,17 @@ export interface ProtocolSyncError extends ProtocolErrorBase {
   readonly type: "ProtocolSyncError";
 }
 
+/**
+ * Error when embedded timestamp doesn't match expected timestamp in
+ * EncryptedDbChange. Indicates potential tampering or corruption of CRDT
+ * messages.
+ */
+export interface ProtocolTimestampMismatchError {
+  readonly type: "ProtocolTimestampMismatchError";
+  readonly expected: Timestamp;
+  readonly embedded: Timestamp;
+}
+
 /**
  * Creates a {@link ProtocolMessage} from CRDT messages.
  *
@@ -469,7 +483,7 @@ export const createProtocolMessageFromCrdtMessages =
 
     for (const message of messages) {
       const change = encodeAndEncryptDbChange(deps)(
-        message.change,
+        message,
         owner.encryptionKey,
       );
       const encryptedCrdtMessage = { timestamp: message.timestamp, change };
@@ -1484,7 +1498,7 @@ const decodeTimestamps = (
   for (let i = 0; i < length; i++) {
     const deltaMillis = decodeNonNegativeInt(buffer);
     const millis = Millis.from(previousMillis + deltaMillis);
-    if (!millis.ok) throw new Error(millis.error.type);
+    if (!millis.ok) throw new ProtocolDecodeError(millis.error.type);
     millises.push(millis.value);
     previousMillis = millis.value;
   }
@@ -1493,7 +1507,7 @@ const decodeTimestamps = (
   let counterIndex = 0;
   while (counterIndex < length) {
     const counter = Counter.from(decodeNonNegativeInt(buffer));
-    if (!counter.ok) throw new Error(counter.error.type);
+    if (!counter.ok) throw new ProtocolDecodeError(counter.error.type);
     const runLength = decodeNonNegativeInt(buffer);
     for (let i = 0; i < runLength; i++) {
       counters.push(counter.value);
@@ -1659,12 +1673,24 @@ export const binaryTimestampToFingerprint = (
 /**
  * Encodes and encrypts a {@link DbChange} using the provided owner's encryption
  * key. Returns an encrypted binary representation as {@link EncryptedDbChange}.
+ *
+ * The format includes the protocol version for backward compatibility and the
+ * timestamp for tamper-proof verification that the timestamp matches the change
+ * data.
  */
 export const encodeAndEncryptDbChange =
   (deps: SymmetricCryptoDep) =>
-  (change: DbChange, key: EncryptionKey): EncryptedDbChange => {
+  (message: CrdtMessage, key: EncryptionKey): EncryptedDbChange => {
+    const change = message.change;
     const buffer = createBuffer();
 
+    // Encode protocol version first for backward compatibility
+    encodeNonNegativeInt(buffer, protocolVersion);
+
+    // Encode the timestamp (after version) for tamper verification
+    const binaryTimestamp = timestampToBinaryTimestamp(message.timestamp);
+    buffer.extend(binaryTimestamp);
+
     encodeBase64Url256(buffer, change.table);
 
     buffer.extend(idToBinaryId(change.id));
@@ -1700,50 +1726,76 @@ export const encodeAndEncryptDbChange =
   };
 
 /**
- * Decrypts and decodes an {@link EncryptedDbChange} using the provided owner's
- * encryption key.
+ * Decrypts and decodes an {@link EncryptedCrdtMessage} using the provided
+ * owner's encryption key. Verifies that the embedded timestamp matches the
+ * expected timestamp to ensure message integrity.
  */
 export const decryptAndDecodeDbChange =
   (deps: SymmetricCryptoDep) =>
   (
-    change: EncryptedDbChange,
+    message: EncryptedCrdtMessage,
     key: EncryptionKey,
-  ): Result<DbChange, SymmetricCryptoDecryptError | ProtocolInvalidDataError> =>
-    tryDecodeProtocolData<DbChange, SymmetricCryptoDecryptError>(
-      change,
-      (buffer) => {
-        const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
-
-        const ciphertextLength = decodeLength(buffer);
-        const ciphertext = buffer.shiftN(ciphertextLength);
-
-        const plaintextBytes = deps.symmetricCrypto.decrypt(
-          ciphertext,
-          key,
-          nonce,
-        );
-        if (!plaintextBytes.ok) return plaintextBytes;
+  ): Result<
+    DbChange,
+    | SymmetricCryptoDecryptError
+    | ProtocolInvalidDataError
+    | ProtocolTimestampMismatchError
+  > =>
+    tryDecodeProtocolData<
+      DbChange,
+      SymmetricCryptoDecryptError | ProtocolTimestampMismatchError
+    >(message.change, (buffer) => {
+      const nonce = buffer.shiftN(deps.symmetricCrypto.nonceLength);
+
+      const ciphertextLength = decodeLength(buffer);
+      const ciphertext = buffer.shiftN(ciphertextLength);
+
+      const plaintextBytes = deps.symmetricCrypto.decrypt(
+        ciphertext,
+        key,
+        nonce,
+      );
+      if (!plaintextBytes.ok) return plaintextBytes;
 
-        buffer.reset();
-        buffer.extend(plaintextBytes.value);
+      buffer.reset();
+      buffer.extend(plaintextBytes.value);
 
-        const table = decodeBase64Url256WithLength(buffer);
-        const id = decodeId(buffer);
+      // Decode version (for future compatibility, no validation needed for now)
+      decodeNonNegativeInt(buffer);
 
-        const length = decodeLength(buffer);
-        const values = Object.create(null) as Record<string, SqliteValue>;
+      // Decode and verify the embedded timestamp
+      const embeddedBinaryTimestamp = buffer.shiftN(
+        binaryTimestampLength,
+      ) as BinaryTimestamp;
+      const embeddedTimestamp = binaryTimestampToTimestamp(
+        embeddedBinaryTimestamp,
+      );
 
-        for (let i = 0; i < length; i++) {
-          const column = decodeBase64Url256WithLength(buffer);
-          const value = decodeSqliteValue(buffer);
-          values[column] = value;
-        }
+      // Verify timestamp integrity
+      if (!eqTimestamp(embeddedTimestamp, message.timestamp)) {
+        return err<ProtocolTimestampMismatchError>({
+          type: "ProtocolTimestampMismatchError",
+          expected: message.timestamp,
+          embedded: embeddedTimestamp,
+        });
+      }
 
-        const dbChange = { table, id, values };
+      const table = decodeBase64Url256WithLength(buffer);
+      const id = decodeId(buffer);
 
-        return ok(dbChange);
-      },
-    );
+      const length = decodeLength(buffer);
+      const values = Object.create(null) as Record<string, SqliteValue>;
+
+      for (let i = 0; i < length; i++) {
+        const column = decodeBase64Url256WithLength(buffer);
+        const value = decodeSqliteValue(buffer);
+        values[column] = value;
+      }
+
+      const dbChange = { table, id, values };
+
+      return ok(dbChange);
+    });
 
 /**
  * Encodes a non-negative integer into a variable-length integer format. It's

package/src/Evolu/Schema.ts

@@ -9,6 +9,7 @@ import {
   brand,
   BrandType,
   createTypeErrorFormatter,
+  DateIso,
   DateIsoString,
   IdType,
   InferErrors,
@@ -30,7 +31,11 @@ import { Simplify } from "../Types.js";
 import { DbSchema } from "./Db.js";
 import { createIndexes, DbIndexesBuilder } from "./Kysely.js";
 import { AppOwner, ShardOwner, SharedOwner } from "./Owner.js";
-import { BinaryId, maxProtocolMessageRangesSize } from "./Protocol.js";
+import {
+  BinaryId,
+  maxProtocolMessageRangesSize,
+  CrdtMessage,
+} from "./Protocol.js";
 import { Query, Row } from "./Query.js";
 import { BinaryTimestamp } from "./Timestamp.js";
 
@@ -198,6 +203,16 @@ export type CreateQuery<S extends EvoluSchema> = <R extends Row>(
   options?: SqliteQueryOptions,
 ) => Query<Simplify<R>>;
 
+/**
+ * Default columns automatically added to all tables.
+ *
+ * - `createdAt`: Set by Evolu when `insert` is called, or can be custom with
+ *   `upsert`.
+ * - `updatedAt`: Always set by Evolu, derived from {@link CrdtMessage} timestamp.
+ *   If you defer sync to avoid leaking time activity, use a custom column to
+ *   preserve real update time.
+ * - `isDeleted`: Soft delete flag.
+ */
 export const DefaultColumns = object({
   createdAt: DateIsoString,
   updatedAt: DateIsoString,
@@ -346,25 +361,41 @@ export type Updateable<Props extends Record<string, AnyType>> = InferInput<
 >;
 
 /**
- * Type Factory to create upsertable Type. It makes nullable Types optional and
- * ensures the {@link maxMutationSize}.
+ * Type Factory to create upsertable Type. It makes nullable Types optional,
+ * includes optional default columns (createdAt, isDeleted), and ensures the
+ * {@link maxMutationSize}.
  *
  * ### Example
  *
  * ```ts
  * const UpsertableTodo = upsertable(Schema.todo);
  * type UpsertableTodo = typeof UpsertableTodo.Type;
- * const todo = UpsertableTodo.from({ id, title });
+ * const todo = UpsertableTodo.from({
+ *   id,
+ *   title,
+ *   createdAt: "2023-01-01T00:00:00.000Z",
+ * });
  * if (!todo.ok) return; // handle errors
  * ```
  */
 export const upsertable = <Props extends Record<string, AnyType>>(
   props: Props,
-): ValidMutationSize<UpsertableProps<Props>> =>
-  validMutationSize(nullableToOptional(props));
+): ValidMutationSize<UpsertableProps<Props>> => {
+  const propsWithDefaults = {
+    ...props,
+    createdAt: optional(DateIso),
+    isDeleted: optional(SqliteBoolean),
+  };
+  return validMutationSize(nullableToOptional(propsWithDefaults));
+};
 
 export type UpsertableProps<Props extends Record<string, AnyType>> =
-  NullableToOptionalProps<Props>;
+  NullableToOptionalProps<
+    Props & {
+      createdAt: OptionalType<typeof DateIso>;
+      isDeleted: OptionalType<typeof SqliteBoolean>;
+    }
+  >;
 
 export type Upsertable<Props extends Record<string, AnyType>> = InferInput<
   ObjectType<UpsertableProps<Props>>

package/src/Evolu/Timestamp.ts

@@ -1,4 +1,5 @@
 import { assert } from "../Assert.js";
+import { createEqObject, eqNumber, eqString } from "../Eq.js";
 import { NanoIdLibDep } from "../NanoId.js";
 import { increment } from "../Number.js";
 import { Order, orderUint8Array } from "../Order.js";
@@ -124,6 +125,13 @@ export const Timestamp = object({
 });
 export type Timestamp = typeof Timestamp.Type;
 
+/** Equality function for comparing {@link Timestamp}. */
+export const eqTimestamp = createEqObject<Timestamp>({
+  millis: eqNumber,
+  counter: eqNumber,
+  nodeId: eqString,
+});
+
 export const createTimestamp = ({
   millis = minMillis,
   counter = minCounter,

package/src/Type.ts

@@ -1994,7 +1994,11 @@ export const TrimString = trim(String);
  *
  * ### Example
  *
- * TODO:
+ * ```ts
+ * DateIso.from(new Date("2023-12-25T10:30:00.000Z")); // ok("2023-12-25T10:30:00.000Z")
+ * DateIso.to("2023-12-25T10:30:00.000Z"); // Date object
+ * DateIso.from(new Date("invalid")); // err({ type: "DateIsoString", value: "Invalid Date" })
+ * ```
  *
  * @category String
  */