@evolu/common 6.0.1-preview.32 → 6.0.1-preview.34

package/src/Evolu/Sync.ts

@@ -22,7 +22,13 @@ import { err, ok, Result } from "../Result.js";
 import { sql, SqliteDep, SqliteError, SqliteValue } from "../Sqlite.js";
 import { AbortError, createMutex } from "../Task.js";
 import { TimeDep } from "../Time.js";
-import { IdBytes, idBytesToId, idToIdBytes, PositiveInt } from "../Type.js";
+import {
+  DateIso,
+  IdBytes,
+  idBytesToId,
+  idToIdBytes,
+  PositiveInt,
+} from "../Type.js";
 import { CreateWebSocketDep, WebSocket } from "../WebSocket.js";
 import type { PostMessageDep } from "./Db.js";
 import {
@@ -74,8 +80,8 @@ import {
   TimestampCounterOverflowError,
   TimestampDriftError,
   TimestampTimeOutOfRangeError,
+  timestampToDateIso,
   timestampToTimestampBytes,
-  timestampToTimestampString,
 } from "./Timestamp.js";
 
 export interface Sync extends Disposable {
@@ -341,7 +347,10 @@ export const createSync =
           clockTimestamp = nextTimestamp.value;
 
           const { ownerId = config.appOwner.id, ...dbChange } = change;
-          const message = { timestamp: clockTimestamp, change: dbChange };
+          const message: CrdtMessage = {
+            timestamp: clockTimestamp,
+            change: dbChange,
+          };
 
           const messages = ownerMessages.get(ownerId);
           if (messages) messages.push(message);
@@ -397,7 +406,6 @@ export interface ClockDep {
   readonly clock: Clock;
 }
 
-// HLC
 export interface Clock {
   readonly get: () => Timestamp;
   readonly save: (timestamp: Timestamp) => Result<void, SqliteError>;
@@ -413,9 +421,9 @@ export const createClock =
       save: (timestamp) => {
         currentTimestamp = timestamp;
 
-        const timestampString = timestampToTimestampString(timestamp);
         const result = deps.sqlite.exec(sql.prepared`
-          update evolu_config set "clock" = ${timestampString};
+          update evolu_config
+          set "clock" = ${timestampToTimestampBytes(timestamp)};
         `);
         if (!result.ok) return result;
 
@@ -587,20 +595,26 @@ const createClientStorage =
 
         const { table, id } = rows[0];
         const values: Record<string, SqliteValue> = {};
+        let isInsert = false;
 
         for (const r of rows) {
           assert(r.table === table, "All rows must have the same table");
           assert(eqArrayNumber(r.id, id), "All rows must have the same Id");
-          values[r.column] = r.value;
+          if (r.column === "createdAt") {
+            isInsert = true;
+          } else {
+            values[r.column] = r.value;
+          }
         }
 
         const message: CrdtMessage = {
           timestamp: timestampBytesToTimestamp(timestamp),
-          change: {
+          change: DbChange.orThrow({
             table: rows[0].table,
             id: idBytesToId(rows[0].id),
             values,
-          },
+            isInsert,
+          }),
         };
 
         return encodeAndEncryptDbChange(deps)(message, owner.encryptionKey);
@@ -620,33 +634,27 @@ const createTransportKey = (transportConfig: OwnerTransport): TransportKey => {
 export const applyLocalOnlyChange =
   (deps: SqliteDep & TimeDep) =>
   (change: MutationChange): Result<void, SqliteError> => {
-    const dbChange: DbChange = {
-      table: change.table,
-      id: change.id,
-      values: change.values,
-    };
-
     const isDeletion =
-      "isDeleted" in dbChange.values && dbChange.values.isDeleted === 1;
+      "isDeleted" in change.values && change.values.isDeleted === 1;
 
     if (isDeletion) {
       const result = deps.sqlite.exec(sql`
-        delete from ${sql.identifier(dbChange.table)}
-        where id = ${dbChange.id};
+        delete from ${sql.identifier(change.table)}
+        where id = ${change.id};
       `);
       if (!result.ok) return result;
     } else {
-      const date = new Date(deps.time.now()).toISOString();
+      const now = deps.time.nowIso();
 
-      for (const [column, value] of objectToEntries(dbChange.values)) {
+      for (const [column, value] of objectToEntries(change.values)) {
         const result = deps.sqlite.exec(sql.prepared`
-          insert into ${sql.identifier(dbChange.table)}
+          insert into ${sql.identifier(change.table)}
             ("id", ${sql.identifier(column)}, createdAt, updatedAt)
-          values (${dbChange.id}, ${value}, ${date}, ${date})
+          values (${change.id}, ${value}, ${now}, ${now})
           on conflict ("id") do update
             set
               ${sql.identifier(column)} = ${value},
-              updatedAt = ${date};
+              updatedAt = ${now};
         `);
         if (!result.ok) return result;
       }
@@ -672,7 +680,8 @@ const applyMessages =
     let { firstTimestamp, lastTimestamp } = usageResult.value;
 
     for (const message of messages) {
-      const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message);
+      const date = timestampToDateIso(message.timestamp);
+      const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message, date);
       if (!result1.ok) return result1;
 
       const timestamp = timestampToTimestampBytes(message.timestamp);
@@ -688,6 +697,7 @@ const applyMessages =
         ownerIdBytes,
         message,
         strategy,
+        date,
       );
       if (!result2.ok) return result2;
     }
@@ -710,11 +720,17 @@ const applyMessages =
 
 const applyMessageToAppTable =
   (deps: SqliteDep) =>
-  (ownerId: OwnerIdBytes, message: CrdtMessage): Result<void, SqliteError> => {
-    const timestamp = timestampToTimestampBytes(message.timestamp);
-    const updatedAt = new Date(message.timestamp.millis).toISOString();
+  (
+    ownerId: OwnerIdBytes,
+    message: CrdtMessage,
+    date: DateIso,
+  ): Result<void, SqliteError> => {
+    let entries = objectToEntries(message.change.values);
+    if (message.change.isInsert) {
+      entries = [...entries, ["createdAt", date]];
+    }
 
-    for (const [column, value] of objectToEntries(message.change.values)) {
+    for (const [column, value] of entries) {
       const result = deps.sqlite.exec(sql.prepared`
         with
           existingTimestamp as (
@@ -725,17 +741,17 @@ const applyMessageToAppTable =
               and "table" = ${message.change.table}
               and "id" = ${idToIdBytes(message.change.id)}
               and "column" = ${column}
-              and "timestamp" >= ${timestamp}
+              and "timestamp" >= ${timestampToTimestampBytes(message.timestamp)}
             limit 1
           )
         insert into ${sql.identifier(message.change.table)}
           ("id", ${sql.identifier(column)}, updatedAt)
-        select ${message.change.id}, ${value}, ${updatedAt}
+        select ${message.change.id}, ${value}, ${date}
         where not exists (select 1 from existingTimestamp)
         on conflict ("id") do update
           set
             ${sql.identifier(column)} = ${value},
-            updatedAt = ${updatedAt}
+            updatedAt = ${date}
           where not exists (select 1 from existingTimestamp);
       `);
 
@@ -751,6 +767,7 @@ export const applyMessageToTimestampAndHistoryTables =
     ownerId: OwnerIdBytes,
     message: CrdtMessage,
     strategy: StorageInsertTimestampStrategy,
+    date: DateIso,
   ): Result<void, SqliteError> => {
     const timestamp = timestampToTimestampBytes(message.timestamp);
     const id = idToIdBytes(message.change.id);
@@ -758,7 +775,12 @@ export const applyMessageToTimestampAndHistoryTables =
     const result = deps.storage.insertTimestamp(ownerId, timestamp, strategy);
     if (!result.ok) return result;
 
-    for (const [column, value] of Object.entries(message.change.values)) {
+    let entries = objectToEntries(message.change.values);
+    if (message.change.isInsert) {
+      entries = [...entries, ["createdAt", date]];
+    }
+
+    for (const [column, value] of entries) {
       const result = deps.sqlite.exec(sql.prepared`
         insert into evolu_history
           ("ownerId", "table", "id", "column", "value", "timestamp")

package/src/Evolu/Timestamp.ts

@@ -1,5 +1,3 @@
-import { assert } from "../Assert.js";
-import { Brand } from "../Brand.js";
 import { bytesToHex } from "../Buffer.js";
 import { RandomBytesDep } from "../Crypto.js";
 import { createEqObject, eqNumber, eqString } from "../Eq.js";
@@ -9,6 +7,7 @@ import { err, ok, Result } from "../Result.js";
 import { TimeDep } from "../Time.js";
 import {
   brand,
+  DateIso,
   InferType,
   lessThanOrEqualTo,
   NonNegativeInt,
@@ -163,10 +162,9 @@ export const maxNodeId = "ffffffffffffffff" as NodeId;
  * queue:
  *
  * 1. Write changes immediately to a local-only table
- * 2. Periodically/randomly flush messages to sync tables
- * 3. This decouples user activity from sync timing
+ * 2. Periodically and randomly flush messages to sync tables
  *
- * Tradeoff: It breaks real-time collaboration.
+ * **Trade-off:** It breaks real-time collaboration.
  */
 export const Timestamp = object({
   millis: Millis,
@@ -193,29 +191,6 @@ export const createInitialTimestamp = (deps: RandomBytesDep): Timestamp => {
   return createTimestamp({ nodeId });
 };
 
-/** Sortable string representation of {@link Timestamp}. */
-export type TimestampString = string & Brand<"TimestampString">;
-
-export const timestampToTimestampString = (t: Timestamp): TimestampString =>
-  [
-    new Date(t.millis).toISOString(),
-    t.counter.toString(16).toUpperCase().padStart(4, "0"),
-    t.nodeId,
-  ].join("-") as TimestampString;
-
-export const timestampStringToTimestamp = (
-  timestampString: TimestampString,
-): Timestamp => {
-  const array = timestampString.split("-");
-  const timestamp = {
-    millis: Date.parse(array.slice(0, 3).join("-")).valueOf(),
-    counter: parseInt(array[3], 16),
-    nodeId: array[4],
-  };
-  assert(Timestamp.is(timestamp), "timestampString is malformed");
-  return timestamp;
-};
-
 const getNextMillis =
   (deps: TimeDep & TimestampConfigDep) =>
   (
@@ -362,3 +337,7 @@ export const timestampBytesToTimestamp = (
 };
 
 export const orderTimestampBytes: Order<TimestampBytes> = orderUint8Array;
+
+export const timestampToDateIso = (timestamp: Timestamp): DateIso =>
+  // `as DateIso` is safe because the timestamp is always valid
+  new Date(timestamp.millis).toISOString() as DateIso;

package/src/Object.ts

@@ -25,14 +25,22 @@ export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
 type StringKeyOf<T> = Extract<keyof T, string>;
 
 /**
- * Converts a record to entries, preserving branded string key types (e.g.,
- * `type Id = 'id' & string`) via `StringKeyOf<T>`, unlike `Object.entries`
- * which widens keys to `string`.
+ * Like `Object.entries` but preserves branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const users: Record<UserId, string> = {};
+ * const entries = objectToEntries(users); // [UserId, string][]
+ * ```
  */
 export const objectToEntries = <T extends Record<string, any>>(
   record: T,
-): Array<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
-  Object.entries(record) as Array<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+): ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
+  Object.entries(record) as Array<
+    [StringKeyOf<T>, T[StringKeyOf<T>]]
+  > as ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
 
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving

package/src/Type.ts

@@ -3,10 +3,7 @@
  *
  * Evolu {@link Type} is like a type guard that returns typed errors (via
  * {@link Result}) instead of throwing. We either get a safely typed value or a
- * precise, composable error value telling us exactly why validation failed.
- *
- * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
- * interoperability with 40+ validation-compatible tools and frameworks.
+ * composable typed error telling us exactly why validation failed.
  *
  * Why another validation library?
  *
@@ -15,12 +12,19 @@
  *   messages.
  * - **Consistent constraints via {@link Brand}** – every constraint becomes part
  *   of the type.
- * - **No user-land chaining DSL** – designed with the upcoming ES pipe operator
- *   in mind.
- * - **Selective validation** – parent validations are skipped when already proved
- *   by typing.
- * - **Simple, top-down implementation** – readable source code from top to bottom
- *   with no hidden magic; just plain functions and composition.
+ * - **Skippable validation** – parent validations can be skipped when already
+ *   proved by types.
+ * - **Simple, top-down implementation** – readable source code from top to
+ *   bottom.
+ * - **No user-land chaining DSL** – prepared for TC39 Hack pipes.
+ *
+ * A distinctive feature of Evolu Type compared to other validation libraries is
+ * that it returns typed errors rather than string messages. This allows
+ * TypeScript to enforce that all validation errors are handled by type
+ * checking, significantly improving the developer experience.
+ *
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
  *
  * ### Base Types Quick Start
  *
@@ -171,6 +175,29 @@
  * reverse transforms would not buy much. We may revisit this if we can design a
  * minimal, 100% safe API that preserves simplicity.
  *
+ * ### Prepared for TC39 Hack Pipes
+ *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper) and read well, but with
+ * TC39 Hack pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
+ * Note `minLength` and `maxLength` are curried because they are factories.
+ *
  * @module
  */
 
@@ -1497,7 +1524,7 @@ export const base64UrlToUint8Array: (str: Base64Url) => Uint8Array =
  * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
  * `_`). See `UrlSafeString` for details.
  *
- * The string must be between 1 and 42 characters.
+ * The string must be between 1 and 64 characters.
  *
  * ### Example
  *
@@ -1513,7 +1540,7 @@ export const base64UrlToUint8Array: (str: Base64Url) => Uint8Array =
  * @category String
  */
 export const SimpleName = brand("SimpleName", UrlSafeString, (value) =>
-  value.length >= 1 && value.length <= 42
+  value.length >= 1 && value.length <= 64
     ? ok(value)
     : err<SimpleNameError>({ type: "SimpleName", value }),
 );
@@ -1523,6 +1550,25 @@ export interface SimpleNameError extends TypeError<"SimpleName"> {}
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper), but with TC39 Hack
+ * pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
  * @category String
  */
 export const SimplePassword = brand(
@@ -3428,26 +3474,6 @@ export const formatInt64Error = createTypeErrorFormatter<Int64Error>(
     `The value ${error.value} is not a valid 64-bit signed integer (Int64).`,
 );
 
-// // co s timhle? je to string, ze ktereho lze udelat bigint
-
-// export const BigIntFromString = transform(
-//   String,
-//   BigInt,
-//   (value) =>
-//     trySync(
-//       () => globalThis.BigInt(value),
-//       (): BigIntFromStringError => ({ type: "BigIntFromString", value }),
-//     ),
-//   (value) => value.toString(),
-// );
-
-// export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {}
-
-// export const formatBigIntFromStringError =
-//   createTypeErrorFormatter<BigIntFromStringError>(
-//     (error) => `The value ${error.value} could not be converted to a BigInt.`,
-//   );
-
 /**
  * Stringified {@link Int64}.
  *