@evolu/common 8.0.0-next.4 → 8.0.0

package/src/local-first/LocalAuth.ts

@@ -4,9 +4,9 @@
  * @module
  */
 
-import type { RandomBytesDep } from "../Crypto.js";
-import type { Mnemonic } from "../Type.js";
-import type { AppOwner } from "./Owner.js";
+import type { RandomBytesDep } from "../Crypto.ts";
+import type { Mnemonic } from "../Type.ts";
+import type { AppOwner } from "./Owner.ts";
 import {
   createAppOwner,
   createOwnerSecret,
@@ -14,7 +14,7 @@ import {
   OwnerEncryptionKey,
   OwnerId,
   OwnerWriteKey,
-} from "./Owner.js";
+} from "./Owner.ts";
 
 /**
  * Local authentication and authorization system for Evolu. This is API is
@@ -439,17 +439,11 @@ export interface MutationResult {
  * storing a value.
  */
 export type SecurityLevel =
-  | "secureEnclave"
-  | "strongBox"
-  | "biometry"
-  | "deviceCredential"
-  | "software";
+  "secureEnclave" | "strongBox" | "biometry" | "deviceCredential" | "software";
 
 /** Enumerates the native storage backend used to persist sensitive data. */
 export type StorageBackend =
-  | "keychain"
-  | "androidKeystore"
-  | "encryptedSharedPreferences";
+  "keychain" | "androidKeystore" | "encryptedSharedPreferences";
 
 /**
  * Enumerates the access-control policy enforced by the underlying secure

package/src/local-first/Owner.ts

@@ -6,17 +6,17 @@
 
 import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
-import type { NonEmptyReadonlyArray } from "../Array.js";
-import type { RandomBytesDep } from "../Crypto.js";
+import type { NonEmptyReadonlyArray } from "../Array.ts";
+import type { RandomBytesDep } from "../Crypto.ts";
 import {
   createSlip21,
   EncryptionKey,
   Entropy16,
   Entropy32,
   testCreateRandomBytes,
-} from "../Crypto.js";
-import { testCreateRandomLib } from "../Random.js";
-import { getOrNull } from "../Result.js";
+} from "../Crypto.ts";
+import { testCreateRandomLib } from "../Random.ts";
+import { getOrNull } from "../Result.ts";
 import {
   brand,
   Id,
@@ -26,9 +26,9 @@ import {
   Mnemonic,
   NonNegativeInt,
   type Typed,
-} from "../Type.js";
-import type { EncryptedDbChange, Storage } from "./Storage.js";
-import { TimestampBytes } from "./Timestamp.js";
+} from "../Type.ts";
+import type { EncryptedDbChange, Storage } from "./Storage.ts";
+import { TimestampBytes } from "./Timestamp.ts";
 
 /**
  * {@link Owner} without a {@link OwnerWriteKey}.
@@ -88,11 +88,11 @@ export interface SyncOwner {
 
 /** OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}. */
 export const OwnerId = /*#__PURE__*/ brand("OwnerId", Id);
-export type OwnerId = typeof OwnerId.Type;
+export type OwnerId = typeof OwnerId.Output;
 
 /** Bytes representation of {@link OwnerId}. */
 export const OwnerIdBytes = /*#__PURE__*/ brand("OwnerIdBytes", IdBytes);
-export type OwnerIdBytes = typeof OwnerIdBytes.Type;
+export type OwnerIdBytes = typeof OwnerIdBytes.Output;
 
 /** Converts {@link OwnerId} to {@link OwnerIdBytes}. */
 export const ownerIdToOwnerIdBytes = (ownerId: OwnerId): OwnerIdBytes =>
@@ -109,14 +109,14 @@ export const OwnerEncryptionKey = /*#__PURE__*/ brand(
   "OwnerEncryptionKey",
   EncryptionKey,
 );
-export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
+export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Output;
 
 /**
  * A secure token for write operations. It's derived from {@link OwnerSecret} by
  * default and can be rotated via {@link createOwnerWriteKey}.
  */
 export const OwnerWriteKey = /*#__PURE__*/ brand("OwnerWriteKey", Entropy16);
-export type OwnerWriteKey = typeof OwnerWriteKey.Type;
+export type OwnerWriteKey = typeof OwnerWriteKey.Output;
 
 /**
  * Creates a new random {@link OwnerWriteKey} for rotation.
@@ -135,7 +135,7 @@ export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
  * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
  */
 export const OwnerSecret = /*#__PURE__*/ brand("OwnerSecret", Entropy32);
-export type OwnerSecret = typeof OwnerSecret.Type;
+export type OwnerSecret = typeof OwnerSecret.Output;
 
 /** Creates a {@link OwnerSecret}. */
 export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
@@ -359,15 +359,37 @@ export interface OwnerWebSocketTransport extends Typed<"WebSocket"> {
  * ### Example
  *
  * ```ts
- * // Create transport "wss://relay.evolu.dev?ownerId=..."
+ * import {
+ *   AppName,
+ *   createAppOwner,
+ *   createEvolu,
+ *   createOwnerWebSocketTransport,
+ *   createOwnerSecret,
+ *   createRandomBytes,
+ *   id,
+ * } from "@evolu/common";
+ *
+ * // Create once, persist the mnemonic securely, and restore it on later runs.
+ * const appOwner = createAppOwner(
+ *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+ * );
  * const transport = createOwnerWebSocketTransport({
  *   url: "wss://relay.evolu.dev",
- *   ownerId: owner.id,
+ *   ownerId: appOwner.id,
  * });
+ * const createTodoEvolu = createEvolu(
+ *   { todo: { id: id("Todo") } },
+ *   {
+ *     appName: AppName.orThrow("OwnerTransportExample"),
+ *     appOwner,
+ *     transports: [transport],
+ *   },
+ * );
  *
- * // Use with createEvolu
- * const evolu = createEvolu(deps)(Schema, {
- *   transports: [transport],
+ * expect(createTodoEvolu).toBeTypeOf("function");
+ * expect(transport).toEqual({
+ *   type: "WebSocket",
+ *   url: `wss://relay.evolu.dev?ownerId=${appOwner.id}`,
  * });
  * ```
  */
@@ -389,10 +411,25 @@ export const createOwnerWebSocketTransport = (config: {
  * ### Example
  *
  * ```ts
- * parseOwnerIdFromOwnerWebSocketTransportUrl(
- *   "/sync?ownerId=_12345678abcdefgh",
+ * import {
+ *   createAppOwner,
+ *   createOwnerSecret,
+ *   createRandomBytes,
+ *   parseOwnerIdFromOwnerWebSocketTransportUrl,
+ * } from "@evolu/common";
+ *
+ * // Create once, persist the mnemonic securely, and restore it on later runs.
+ * const appOwner = createAppOwner(
+ *   createOwnerSecret({ randomBytes: createRandomBytes() }),
+ * );
+ * const url = `/sync?ownerId=${appOwner.id}`;
+ *
+ * expect(parseOwnerIdFromOwnerWebSocketTransportUrl(url)).toBe(
+ *   appOwner.id,
  * );
- * // Returns: OwnerId or null
+ * expect(
+ *   parseOwnerIdFromOwnerWebSocketTransportUrl("/sync?ownerId=invalid"),
+ * ).toBeNull();
  * ```
  */
 export const parseOwnerIdFromOwnerWebSocketTransportUrl = (

package/src/local-first/Protocol.ts

@@ -178,9 +178,9 @@
  */
 
 import { Packr } from "msgpackr";
-import { isNonEmptyArray, type NonEmptyReadonlyArray } from "../Array.js";
-import { assert } from "../Assert.js";
-import type { Brand } from "../Brand.js";
+import { isNonEmptyArray, type NonEmptyReadonlyArray } from "../Array.ts";
+import { assert, assertNonNullable } from "../Assert.ts";
+import type { Brand } from "../Brand.ts";
 import {
   type Buffer,
   bytesToHex,
@@ -188,8 +188,8 @@ import {
   createBuffer,
   hexToBytes,
   utf8ToBytes,
-} from "../Buffer.js";
-import type { ConsoleDep } from "../Console.js";
+} from "../Buffer.ts";
+import type { ConsoleDep } from "../Console.ts";
 import {
   createPadmePadding,
   decryptWithXChaCha20Poly1305,
@@ -200,14 +200,14 @@ import {
   type RandomBytesDep,
   XChaCha20Poly1305Ciphertext,
   xChaCha20Poly1305NonceLength,
-} from "../Crypto.js";
-import { eqArrayNumber } from "../Eq.js";
-import { computeBalancedBuckets } from "../Number.js";
-import { createRecord, objectToEntries } from "../Object.js";
-import { err, ok, type Result } from "../Result.js";
-import { SqliteValue } from "../Sqlite.js";
-import type { Task } from "../Task.js";
-import { Millis } from "../Time.js";
+} from "../Crypto.ts";
+import { eqArrayNumber } from "../Eq.ts";
+import { computeBalancedBuckets } from "../Number.ts";
+import { createMutableRecord, objectToEntries } from "../Object.ts";
+import { err, ok, type Result } from "../Result.ts";
+import { SqliteValue } from "../Sqlite.ts";
+import { AbortError, type Task } from "../Task.ts";
+import { Millis } from "../Time.ts";
 import {
   Base64Url,
   base64UrlToUint8Array,
@@ -228,8 +228,8 @@ import {
   type Typed,
   uint8ArrayToBase64Url,
   zeroNonNegativeInt,
-} from "../Type.js";
-import type { Predicate } from "../Types.js";
+} from "../Type.ts";
+import type { Predicate } from "../Types.ts";
 import {
   type Owner,
   type OwnerError,
@@ -238,7 +238,7 @@ import {
   ownerIdToOwnerIdBytes,
   OwnerWriteKey,
   ownerWriteKeyLength,
-} from "./Owner.js";
+} from "./Owner.ts";
 import {
   type BaseRange,
   type CrdtMessage,
@@ -255,7 +255,7 @@ import {
   type SkipRange,
   type StorageDep,
   type TimestampsRange,
-} from "./Storage.js";
+} from "./Storage.ts";
 import {
   Counter,
   eqTimestamp,
@@ -265,7 +265,7 @@ import {
   timestampBytesLength,
   timestampBytesToTimestamp,
   timestampToTimestampBytes,
-} from "./Timestamp.js";
+} from "./Timestamp.ts";
 
 /**
  * Evolu uses MessagePack for numbers and JSONs.
@@ -299,7 +299,7 @@ export const ProtocolMessageMaxSize = /*#__PURE__*/ between(
   maxProtocolMessageMaxSize,
 )(Int);
 
-export type ProtocolMessageMaxSize = typeof ProtocolMessageMaxSize.Type;
+export type ProtocolMessageMaxSize = typeof ProtocolMessageMaxSize.Output;
 
 /**
  * Default {@link ProtocolMessageMaxSize} (1MB).
@@ -326,7 +326,7 @@ export const ProtocolMessageRangesMaxSize = /*#__PURE__*/ between(
   100_000,
 )(Int);
 export type ProtocolMessageRangesMaxSize =
-  typeof ProtocolMessageRangesMaxSize.Type;
+  typeof ProtocolMessageRangesMaxSize.Output;
 
 /**
  * Default {@link ProtocolMessageRangesMaxSize} (30KB).
@@ -1014,6 +1014,7 @@ export const applyProtocolMessageAsClient =
           // Quota errors are handled by Storage; protocol just stops syncing.
           if (!result.ok) return ok({ type: "NoResponse" });
         } catch (error) {
+          if (AbortError.is(error)) throw error;
           run.deps.console.error(error);
           return ok({ type: "NoResponse" });
         }
@@ -1054,6 +1055,7 @@ export const applyProtocolMessageAsClient =
 
       return ok({ type: "Response", message: output.unwrap() });
     } catch (error) {
+      if (AbortError.is(error)) throw error;
       return err<ProtocolInvalidDataError>({
         type: "ProtocolInvalidDataError",
         data: inputMessage,
@@ -1180,6 +1182,7 @@ export const applyProtocolMessageAsRelay =
             return ok({ type: "Response", message });
           }
         } catch (error) {
+          if (AbortError.is(error)) throw error;
           run.deps.console.error(error);
           const message = createProtocolMessageBuffer(ownerId, {
             messageType: MessageType.Response,
@@ -1246,6 +1249,7 @@ export const applyProtocolMessageAsRelay =
       // Non-initiators always respond to provide sync completion feedback,
       return ok({ type: "Response", message });
     } catch (error) {
+      if (AbortError.is(error)) throw error;
       return err<ProtocolInvalidDataError>({
         type: "ProtocolInvalidDataError",
         data: inputMessage,
@@ -1699,14 +1703,14 @@ const decodeTimestamps = (
   const millises = new Array<Millis>(length);
   for (let i = 0; i < length; i++) {
     const deltaMillis = decodeNonNegativeInt(buffer);
-    const millis = Millis.from(previousMillis + deltaMillis);
+    const millis = Millis.fromUnknown(previousMillis + deltaMillis);
     if (!millis.ok) throw new ProtocolDecodeError(millis.error.type);
     millises[i] = millis.value;
     previousMillis = millis.value;
   }
 
   const counters = decodeRle(buffer, length, (): Counter => {
-    const counter = Counter.from(decodeNonNegativeInt(buffer));
+    const counter = Counter.fromUnknown(decodeNonNegativeInt(buffer));
     if (!counter.ok) throw new ProtocolDecodeError(counter.error.type);
     return counter.value;
   });
@@ -1803,7 +1807,13 @@ export const decodeNumber = (buffer: Buffer): number => {
  * ### Example
  *
  * ```ts
- * encodeFlags(buffer, [true, false, true]); // Encodes bits 0, 1, 2
+ * import { createBuffer } from "@evolu/common";
+ * import { encodeFlags } from "@evolu/common/local-first";
+ *
+ * const buffer = createBuffer();
+ * encodeFlags(buffer, [true, false, true]);
+ *
+ * expect(buffer.unwrap()).toEqual(new Uint8Array([0b101]));
  * ```
  */
 export const encodeFlags = (
@@ -1825,7 +1835,14 @@ export const encodeFlags = (
  * ### Example
  *
  * ```ts
- * const flags = decodeFlags(buffer, 3); // Decode 3 flags
+ * import { createBuffer, PositiveInt } from "@evolu/common";
+ * import { decodeFlags } from "@evolu/common/local-first";
+ *
+ * const buffer = createBuffer([0b101]);
+ * const flags = decodeFlags(buffer, PositiveInt.orThrow(3));
+ *
+ * expect(flags).toEqual([true, false, true]);
+ * expect(buffer.getLength()).toBe(0);
  * ```
  */
 export const decodeFlags = (
@@ -1874,6 +1891,7 @@ export const encodeAndEncryptDbChange =
 
     encodeLength(buffer, entries);
     for (const [column, value] of entries) {
+      assertNonNullable(value);
       encodeString(buffer, column);
       encodeSqliteValue(buffer, value);
     }
@@ -1944,7 +1962,7 @@ export const decryptAndDecodeDbChange = (
     const id = decodeId(buffer);
 
     const length = decodeLength(buffer);
-    const values = createRecord<string, SqliteValue>();
+    const values = createMutableRecord<string, SqliteValue>();
 
     for (let i = 0; i < length; i++) {
       const column = decodeString(buffer);
@@ -2019,7 +2037,7 @@ export const decodeNonNegativeInt = (buffer: Buffer): NonNegativeInt => {
     shift += 7n;
   }
 
-  const int = NonNegativeInt.from(globalThis.Number(result));
+  const int = NonNegativeInt.fromUnknown(globalThis.Number(result));
   if (!int.ok) throw new ProtocolDecodeError(int.error.type);
 
   return int.value;
@@ -2098,7 +2116,7 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
         return;
       }
 
-      const dateIso = DateIso.fromParent(value);
+      const dateIso = DateIso.from.parent(value);
       if (dateIso.ok) {
         const time = new Date(dateIso.value).getTime();
         if (NonNegativeInt.is(time)) {
@@ -2117,14 +2135,14 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
         return;
       }
 
-      const id = Id.fromParent(value);
+      const id = Id.from.parent(value);
       if (id.ok) {
         encodeNonNegativeInt(buffer, ProtocolValueType.Id);
         buffer.extend(idToIdBytes(id.value));
         return;
       }
 
-      const json = Json.fromParent(value);
+      const json = Json.from.parent(value);
       // Only encode as Json if it survives JSON.parse/JSON.stringify round-trip.
       // 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.
@@ -2136,7 +2154,7 @@ export const encodeSqliteValue = (buffer: Buffer, value: SqliteValue): void => {
         return;
       }
 
-      const base64Url = Base64Url.fromParent(value);
+      const base64Url = Base64Url.from.parent(value);
       if (base64Url.ok) {
         encodeNonNegativeInt(buffer, ProtocolValueType.Base64Url);
         const bytes = base64UrlToUint8Array(base64Url.value);
@@ -2211,7 +2229,7 @@ export const decodeSqliteValue = (buffer: Buffer): SqliteValue => {
         type === ProtocolValueType.DateIsoWithNonNegativeTime
           ? decodeNonNegativeInt(buffer)
           : decodeNumber(buffer);
-      const dateIso = DateIso.fromParent(new Date(time).toISOString());
+      const dateIso = DateIso.from.parent(new Date(time).toISOString());
       if (!dateIso.ok) throw new ProtocolDecodeError(dateIso.error.type);
       return dateIso.value;
     }