@evolu/common 8.6.1 → 8.7.0

package/src/Sqlite.ts

@@ -8,19 +8,19 @@ import type { Brand } from "./Brand.ts";
 import { bytesToHex, hexToBytes } from "./Buffer.ts";
 import type { EncryptionKey } from "./Crypto.ts";
 import type { Eq } from "./Eq.ts";
-import { createEqObject, eqArrayNumber, eqString } from "./Eq.ts";
+import { createEqObject, eqString, eqUint8Array } from "./Eq.ts";
 import { disposable } from "./Function.ts";
 import { createMutableRecord, objectToEntries } from "./Object.ts";
 import type { Result } from "./Result.ts";
 import { ok } from "./Result.ts";
-import { testCreateRun, type Task, type TestRunDep } from "./Task.ts";
+import { type Task, testCreateRun, type TestRunDep } from "./Task.ts";
 import {
   array,
   type ArrayType,
+  FiniteNumber,
   type InferType,
   type Name,
   Null,
-  Number,
   object,
   type ObjectType,
   record,
@@ -79,7 +79,7 @@ export interface SqliteTransaction {
 /** Represents a SQL query to be executed on a {@link Sqlite} database. */
 export interface SqliteQuery {
   readonly sql: SafeSql;
-  readonly parameters: Array<SqliteValue>;
+  readonly parameters: SqliteQueryParameters;
   readonly options?: SqliteQueryOptions;
 }
 
@@ -92,20 +92,38 @@ export type SafeSql = string & Brand<"SafeSql">;
 /**
  * A value that can be stored in {@link Sqlite}.
  *
+ * Numeric values use {@link FiniteNumber} because JavaScript numbers also
+ * include `NaN` and infinities. SQLite binds `NaN` as `NULL`, while JSON
+ * serialization converts all non-finite numbers to `null`. Restricting numbers
+ * to finite values preserves them across storage and query serialization.
+ *
  * Note that Evolu can't support Int64 because expo-sqlite (and some others) do
  * not support it.
  */
 export const SqliteValue = /*#__PURE__*/ union(
+  FiniteNumber,
   Null,
   String,
-  Number,
   Uint8Array,
 );
 export type SqliteValue = typeof SqliteValue.Output;
 
-/** Equality comparison for {@link SqliteValue}. */
-export const eqSqliteValue: Eq<SqliteValue> = (x, y) =>
-  Uint8Array.is(x) && Uint8Array.is(y) ? eqArrayNumber(x, y) : x === y;
+/** Parameters of a {@link SqliteQuery}. */
+export const SqliteQueryParameters = /*#__PURE__*/ array(SqliteValue);
+export type SqliteQueryParameters = typeof SqliteQueryParameters.Output;
+
+/**
+ * A value used in {@link sql} template parameters and {@link Sqlite} query
+ * results.
+ *
+ * It differs from {@link SqliteValue} only by using `number` instead of
+ * {@link FiniteNumber}.
+ */
+export type SqliteValueInput = typeof SqliteValue.Input;
+
+/** Equality comparison for {@link SqliteValueInput}. */
+export const eqSqliteValue: Eq<SqliteValueInput> = (x, y) =>
+  Uint8Array.is(x) && Uint8Array.is(y) ? eqUint8Array(x, y) : x === y;
 
 /** Options for configuring {@link SqliteQuery} execution behavior. */
 export interface SqliteQueryOptions {
@@ -139,7 +157,7 @@ export const sqliteQueryToSqliteQueryString = (
   query: SqliteQuery,
 ): SqliteQueryString => {
   const params = query.parameters.map((value) =>
-    value instanceof globalThis.Uint8Array
+    Uint8Array.is(value)
       ? (["b", bytesToHex(value)] as const)
       : (["j", value] as const),
   );
@@ -157,7 +175,9 @@ export const sqliteQueryStringToSqliteQuery = (
 ): SqliteQuery => {
   const [sql, paramsArr, optionsArr] = JSON.parse(query) as [
     SafeSql,
-    Array<readonly ["b", string] | readonly ["j", string | number | null]>,
+    Array<
+      readonly ["b", string] | readonly ["j", string | FiniteNumber | null]
+    >,
     Array<Array<string | number | null>>,
   ];
 
@@ -184,9 +204,9 @@ export interface SqliteExecResult<R extends SqliteRow = SqliteRow> {
 
 /**
  * A row returned from a {@link Sqlite} query, mapping column names to
- * {@link SqliteValue}.
+ * {@link SqliteValueInput}.
  */
-export type SqliteRow = Record<string, SqliteValue>;
+export type SqliteRow = Record<string, SqliteValueInput>;
 
 /**
  * SQLite driver interface.
@@ -423,7 +443,7 @@ export interface RawSql extends Typed<"RawSql"> {
 }
 
 /** A parameter accepted by the {@link sql} tagged template. */
-export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
+export type SqlTemplateParam = SqliteValueInput | SqlIdentifier | RawSql;
 
 /**
  * Creates a safe SQL query using a tagged template literal.
@@ -484,7 +504,7 @@ export const sql = (
         sql += param.sql;
       } else {
         sql += "?";
-        values.push(param);
+        values.push(SqliteValue.orThrow(param));
       }
     }
   }
@@ -647,8 +667,6 @@ export const getSqliteSnapshot = (deps: SqliteDep): SqliteSnapshot => {
  *
  * See: https://www.sqlite.org/quirks.html#no_separate_boolean_datatype
  *
- * ## Tips
- *
  * - Use {@link sqliteTrue} and {@link sqliteFalse} constants for better
  *   readability.
  * - Use {@link booleanToSqliteBoolean} and {@link sqliteBooleanToBoolean} for

package/src/local-first/Db.ts

@@ -45,6 +45,7 @@ import { callback, type Run, type Task } from "../Task.ts";
 import { Millis, millisToDateIso, type TimeDep } from "../Time.ts";
 import {
   assertType,
+  type FiniteNumber,
   Id,
   IdBytes,
   idBytesToId,
@@ -942,7 +943,8 @@ const dbChangeToColumns = (change: DbChange, now: Millis) => {
   if (change.isDelete != null) {
     values = appendToArray(values, [
       "isDeleted",
-      booleanToSqliteBoolean(change.isDelete),
+      // SQLite boolean values are fixed to the finite numbers 0 and 1.
+      booleanToSqliteBoolean(change.isDelete) as FiniteNumber,
     ]);
   }
 

package/src/local-first/Protocol.ts

@@ -170,14 +170,11 @@
  *   initiator/non-initiator terminology instead, and consolidate into a single
  *   `applyProtocolMessage` function with conditional arguments to reduce code
  *   duplication.
- * - Replace try-catch with Result + new Error (to preserve stacktraces). Measure
- *   Result overhead, it should be super small.
  * - Allow clients to broadcast messages that are not persisted by relays. This
  *   would enable real-time ephemeral data (like cursor positions, typing
  *   indicators) to be forwarded by relays without storage overhead.
  */
 
-import { Packr } from "msgpackr";
 import {
   createMutableArray,
   isNonEmptyArray,
@@ -190,6 +187,8 @@ import {
   bytesToHex,
   bytesToUtf8,
   createBuffer,
+  decodeJsonValue,
+  encodeJsonValue,
   hexToBytes,
   utf8ToBytes,
 } from "../Buffer.ts";
@@ -217,6 +216,7 @@ import {
   base64UrlToUint8Array,
   between,
   DateIso,
+  FiniteNumber,
   Id,
   IdBytes,
   idBytesToId,
@@ -226,7 +226,6 @@ import {
   Json,
   jsonToJsonValue,
   NonNegativeInt,
-  Number,
   onePositiveInt,
   PositiveInt,
   type Typed,
@@ -271,13 +270,7 @@ import {
   timestampToTimestampBytes,
 } from "./Timestamp.ts";
 
-/**
- * Evolu uses MessagePack for numbers and JSONs.
- *
- * - `variableMapSize: true` - More compact maps, ~5-10% slower encoding
- * - `useRecords: false` - Standard MessagePack without extensions
- */
-const packr = new Packr({ variableMapSize: true, useRecords: false });
+const jsonBuffer = createBuffer();
 
 const minProtocolMessageMaxSize = 1_000_000;
 const maxProtocolMessageMaxSize = 100_000_000;
@@ -1775,33 +1768,16 @@ const decodeId = (buffer: Buffer): Id => {
 };
 
 /**
- * Evolu uses MessagePack to handle all number variants except for
- * NonNegativeInt. For NonNegativeInt, Evolu provides more efficient encoding.
+ * Evolu uses MessagePack to handle finite numbers except for NonNegativeInt.
+ * For NonNegativeInt, Evolu provides more efficient encoding.
  */
-export const encodeNumber = (buffer: Buffer, number: number): void => {
-  buffer.extend(packr.pack(number));
+export const encodeNumber = (buffer: Buffer, number: FiniteNumber): void => {
+  encodeJsonValue(buffer, number);
 };
 
-export const decodeNumber = (buffer: Buffer): number => {
-  let number: unknown;
-  let end: unknown;
-
-  packr.unpackMultiple(
-    buffer.unwrap(),
-    (n: unknown, _: unknown, e: unknown) => {
-      number = n;
-      end = e;
-      return false;
-    },
-  );
-
-  const endResult = NonNegativeInt.fromUnknown(end);
-  if (!endResult.ok) throw new ProtocolDecodeError(endResult.error.type);
-
-  const numberResult = Number.fromUnknown(number);
+export const decodeNumber = (buffer: Buffer): FiniteNumber => {
+  const numberResult = FiniteNumber.fromUnknown(decodeJsonValue(buffer));
   if (!numberResult.ok) throw new ProtocolDecodeError(numberResult.error.type);
-
-  buffer.shiftN(endResult.value);
   return numberResult.value;
 };
 
@@ -2140,7 +2116,7 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
             buffer,
             ProtocolValueType.DateIsoWithNegativeTime,
           );
-          encodeNumber(buffer, time);
+          encodeNumber(buffer, FiniteNumber.orThrow(time));
         }
         return;
       }
@@ -2157,10 +2133,16 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
       // Some valid JSON strings like "-0E0" get normalized to "0" during parsing,
       // which would cause data corruption if we don't verify round-trip safety.
       if (json.ok && JSON.stringify(jsonToJsonValue(json.value)) === value) {
-        const jsonBytes = packr.pack(jsonToJsonValue(json.value));
-        encodeNonNegativeInt(buffer, ProtocolValueType.Json);
-        encodeLength(buffer, jsonBytes);
-        buffer.extend(jsonBytes);
+        jsonBuffer.reset();
+        try {
+          encodeJsonValue(jsonBuffer, jsonToJsonValue(json.value));
+          const jsonBytes = jsonBuffer.unwrap();
+          encodeNonNegativeInt(buffer, ProtocolValueType.Json);
+          encodeLength(buffer, jsonBytes);
+          buffer.extend(jsonBytes);
+        } finally {
+          jsonBuffer.reset();
+        }
         return;
       }
 
@@ -2179,7 +2161,9 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
     }
 
     case "number": {
-      if (NonNegativeInt.is(value)) {
+      // Negative zero is a non-negative integer in JavaScript, but integer
+      // encoding would lose its observable sign.
+      if (!globalThis.Object.is(value, -0) && NonNegativeInt.is(value)) {
         if (isSmallInt(value)) {
           encodeNonNegativeInt(buffer, value);
           return;
@@ -2229,8 +2213,12 @@ export const decodeSqliteValue = (buffer: Buffer): SqliteValue => {
 
     case ProtocolValueType.Json: {
       const length = decodeLength(buffer);
-      const bytes = buffer.shiftN(length);
-      return JSON.stringify(packr.unpack(bytes));
+      const lengthBeforeDecoding = buffer.getLength();
+      const value = decodeJsonValue(buffer);
+      if (lengthBeforeDecoding - buffer.getLength() !== length) {
+        throw new ProtocolDecodeError("Invalid JSON MessagePack length");
+      }
+      return JSON.stringify(value);
     }
 
     case ProtocolValueType.DateIsoWithNonNegativeTime:

package/src/local-first/Query.ts

@@ -26,8 +26,8 @@ import type { Brand } from "../Brand.ts";
 import { createRandomBytes } from "../Crypto.ts";
 import type { ReadonlyRecord } from "../Object.ts";
 import { createMutableRecord, isPlainObject } from "../Object.ts";
-import type { SqliteQueryString } from "../Sqlite.ts";
-import { eqSqliteValue, SqliteValue } from "../Sqlite.ts";
+import type { SqliteQueryString, SqliteValueInput } from "../Sqlite.ts";
+import { eqSqliteValue } from "../Sqlite.ts";
 import { createId, String } from "../Type.ts";
 import type { EvoluSchema } from "./Schema.ts";
 
@@ -107,7 +107,7 @@ export type InferRow<T extends Query> =
 
 export interface Row {
   readonly [key: string]:
-    | SqliteValue
+    | SqliteValueInput
     // for evoluJsonObjectFrom
     | Row
     // for evoluJsonArrayFrom
@@ -400,8 +400,8 @@ export const makePatches = (
     for (const key in previousRow)
       if (
         !eqSqliteValue(
-          previousRow[key] as SqliteValue,
-          nextRow[key] as SqliteValue,
+          previousRow[key] as SqliteValueInput,
+          nextRow[key] as SqliteValueInput,
         )
       ) {
         replaceAtPatches.push({ op: "replaceAt", value: nextRow, index: i });

package/src/local-first/Schema.ts

@@ -19,11 +19,14 @@ import {
   type SqliteIndex,
   type SqliteQuery,
   type SqliteQueryOptions,
+  SqliteQueryParameters,
   type SqliteSchema,
   SqliteValue,
 } from "../Sqlite.ts";
 import {
+  assertType,
   DateIso,
+  type FiniteNumber,
   type Id,
   IdBytes,
   type InferType,
@@ -54,6 +57,11 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * Column types are Standard Schema v1 compatible — use Evolu Type, Zod,
  * Valibot, ArkType, or any library that implements Standard Schema.
  *
+ * Each column schema's inferred output must be compatible with SQLite. Numeric
+ * outputs must be assignable to {@link FiniteNumber}. Standard Schema does not
+ * standardize nominal brands, so a library-specific finite validator whose
+ * output remains `number` must brand its validated output compatibly.
+ *
  * Table schema defines columns that are required for table rows. For optional
  * columns, use a schema whose output type includes `null`.
  *
@@ -63,7 +71,9 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * import * as z from "zod";
  * import {
  *   assertOk,
+ *   assertType,
  *   assertTrue,
+ *   type FiniteNumber,
  *   id,
  *   NonEmptyTrimmedString100,
  *   nullOr,
@@ -84,10 +94,17 @@ export type AnyStandardSchemaV1 = StandardSchemaV1<any, any>;
  * assertOk(Schema.todo.title.fromUnknown("Write docs"), "Write docs");
  *
  * // Zod, or another Standard Schema library
+ * // Zod 4 numbers are finite by default; Evolu Type Number models all JavaScript numbers.
+ * const ZodFiniteNumber = z
+ *   .number()
+ *   .transform((value): FiniteNumber => value as FiniteNumber);
+ * assertType<FiniteNumber, z.output<typeof ZodFiniteNumber>>();
+ *
  * const ZodSchema = {
  *   todo: {
  *     id: TodoId,
  *     title: z.string().min(1).max(100),
+ *     position: ZodFiniteNumber,
  *     isCompleted: z.union([z.literal(0), z.literal(1)]).nullable(),
  *   },
  * };
@@ -377,11 +394,10 @@ export type ValidateColumnTypes<S extends EvoluSchema> =
     ? TableName extends keyof S
       ? keyof S[TableName] extends infer ColumnName
         ? ColumnName extends keyof S[TableName]
-          ? StandardSchemaV1.InferOutput<
-              S[TableName][ColumnName]
-            > extends SqliteValue
+          ? StandardSchemaV1.InferOutput<S[TableName][ColumnName]> extends
+              SqliteValue | SqliteBoolean
             ? never
-            : SchemaValidationError<`Table "${TableName & string}" column "${ColumnName & string}" type is not compatible with SQLite. Column types must extend SqliteValue (string, number, Uint8Array, or null).`>
+            : SchemaValidationError<`Table "${TableName & string}" column "${ColumnName & string}" type is not compatible with SQLite. Column types must extend SqliteValue (string, FiniteNumber, Uint8Array, or null).`>
           : never
         : never
       : never
@@ -492,11 +508,10 @@ export const createQueryBuilder = <S extends EvoluSchema>(
 ): CreateQuery<S> => {
   const createQuery: CreateQuery<S> = (queryCallback, options) => {
     const compiledQuery = queryCallback(kysely as never).compile();
+    assertType(SqliteQueryParameters, compiledQuery.parameters);
     const sqliteQuery: SqliteQuery = {
       sql: compiledQuery.sql as SafeSql,
-      parameters: compiledQuery.parameters as NonNullable<
-        SqliteQuery["parameters"]
-      >,
+      parameters: compiledQuery.parameters,
       ...(options && { options }),
     };