Improve Owner docs and code, close evoluhq#615

Author: steida

.changeset/bumpy-cameras-ask.md

@@ -0,0 +1,14 @@
+---
+"@evolu/common": patch
+---
+
+Improve Owner API documentation and consistency
+
+- Add `ReadonlyOwner` interface for owners without write keys
+- Export `UnuseOwner` type for better API clarity
+- Improve JSDoc comments across Owner types and related interfaces
+- Rename `BaseOwnerError` to `OwnerError` for consistency
+- Remove `createOwner` from public exports (use specific owner creation functions)
+- Remove transport properties from owner types (now passed via `useOwner`)
+- Add documentation for `OwnerWriteKey` rotation
+- Improve `useOwner` documentation in React and Vue hooks

packages/common/src/local-first/Evolu.ts

@@ -423,32 +423,36 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> extends Disposable {
   readonly exportDatabase: () => Promise<Uint8Array<ArrayBuffer>>;
 
   /**
-   * Use an owner. Using an owner means syncing it and subscribing to
-   * broadcasted changes. Returns a function to stop using the owner.
+   * Use a {@link SyncOwner}. Returns a {@link UnuseOwner}.
    *
-   * Transport connections are automatically deduplicated and reference-counted,
-   * so multiple owners using the same transport will share a single
-   * connection.
+   * Using an owner means syncing it with its transports, or the transports
+   * defined in Evolu config if the owner has no transports defined.
+   *
+   * Transport are automatically deduplicated and reference-counted, so multiple
+   * owners using the same transport will share a single connection.
    *
    * ### Example
    *
    * ```ts
-   * // Use an owner (starts syncing and subscribing to changes).
-   * const unuse = evolu.useOwner(shardOwner);
+   * // Use an owner (starts syncing).
+   * const unuseOwner = evolu.useOwner(shardOwner);
    *
    * // Later, stop using the owner.
-   * unuse();
+   * unuseOwner();
    *
    * // Bulk operations.
-   * const unuses = owners.map((owner) => evolu.useOwner(owner));
-   * // Later: unuses.forEach(unuse => unuse());
+   * const unuseOwners = owners.map((owner) => evolu.useOwner(owner));
+   * // Later: for (const unuse of unuseOwners) unuse();
    * ```
    *
    * @experimental
    */
-  readonly useOwner: (owner: SyncOwner) => () => void;
+  readonly useOwner: (owner: SyncOwner) => UnuseOwner;
 }
 
+/** Function returned by {@link Evolu#useOwner} to stop using an {@link SyncOwner}. */
+export type UnuseOwner = () => void;
+
 /** Represents errors that can occur in Evolu. */
 export type EvoluError =
   | ProtocolError

packages/common/src/local-first/Owner.ts

@@ -22,15 +22,23 @@ import type { EncryptedDbChange, Storage } from "./Storage.js";
 import { TimestampBytes } from "./Timestamp.js";
 
 /**
- * The Owner represents ownership of data in Evolu. Every database change is
- * assigned to an owner, enabling sync functionality and access control.
+ * {@link Owner} without a {@link OwnerWriteKey}.
  *
- * Owners enable **partial sync** - applications can choose which owners to
- * sync, allowing selective data synchronization based on specific needs.
+ * @see {@link createSharedReadonlyOwner}
+ */
+export interface ReadonlyOwner {
+  readonly id: OwnerId;
+  readonly encryptionKey: OwnerEncryptionKey;
+}
+
+/**
+ * The Owner represents ownership of data in Evolu. Every database change is
+ * assigned to an owner and encrypted with its {@link OwnerEncryptionKey}. Owners
+ * allow partial sync, only the {@link AppOwner} is synced by default.
  *
- * Owners also provide **real data deletion** - while individual changes in
- * local-first/distributed systems can only be marked as deleted, entire owners
- * can be completely deleted from both relays and devices (except for
+ * Owners can also provide real data deletion, while individual changes in
+ * local-first/distributed systems can only be soft deleted, entire owners can
+ * be completely deleted from both relays and devices (except for
  * {@link AppOwner}, which must be preserved for sync coordination).
  *
  * Evolu provides different owner types depending on their use case:
@@ -46,36 +54,37 @@ import { TimestampBytes } from "./Timestamp.js";
  * SLIP-21, ensuring secure and deterministic key generation:
  *
  * - {@link OwnerId}: Globally unique public identifier
- * - {@link EncryptionKey}: Symmetric encryption key for data protection
+ * - {@link OwnerEncryptionKey}: Symmetric encryption key for data protection
  * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
  *
- * @see {@link createOwner}
+ * @see {@link createAppOwner}
+ * @see {@link createShardOwner}
+ * @see {@link createSharedOwner}
+ * @see {@link createSharedReadonlyOwner}
  */
-export interface Owner {
-  readonly id: OwnerId;
-  readonly encryptionKey: OwnerEncryptionKey;
+export interface Owner extends ReadonlyOwner {
   readonly writeKey: OwnerWriteKey;
 }
 
-/**
- * OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}.
- * Branded from {@link Id} to leverage existing helpers like {@link idToIdBytes}.
- */
+/** OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}. */
 export const OwnerId = brand("OwnerId", Id);
 export type OwnerId = typeof OwnerId.Type;
 
 /** Bytes representation of {@link OwnerId}. */
 export const OwnerIdBytes = brand("OwnerIdBytes", IdBytes);
 export type OwnerIdBytes = typeof OwnerIdBytes.Type;
 
+/** Converts {@link OwnerId} to {@link OwnerIdBytes}. */
 export const ownerIdToOwnerIdBytes = (ownerId: OwnerId): OwnerIdBytes =>
   idToIdBytes(ownerId) as OwnerIdBytes;
 
+/** Converts {@link OwnerIdBytes} to {@link OwnerId}. */
 export const ownerIdBytesToOwnerId = (ownerIdBytes: OwnerIdBytes): OwnerId =>
   idBytesToId(ownerIdBytes as IdBytes) as OwnerId;
 
 export const ownerWriteKeyLength = NonNegativeInt.orThrow(16);
 
+/** Symmetric encryption key for {@link Owner} data protection. */
 export const OwnerEncryptionKey = brand("OwnerEncryptionKey", EncryptionKey);
 export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 
@@ -86,6 +95,16 @@ export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
 export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 
+/**
+ * Creates a new random {@link OwnerWriteKey} for rotation.
+ *
+ * The initial OwnerWriteKey is deterministically derived from
+ * {@link OwnerSecret}. Use `createOwnerWriteKey` to rotate (replace) the write
+ * key without changing the owner identity.
+ */
+export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
+  deps.randomBytes.create(16) as OwnerWriteKey;
+
 /**
  * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
  *
@@ -107,22 +126,11 @@ export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
 export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
   bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
 
-/** Creates a randomly generated {@link OwnerWriteKey}. */
-export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
-  deps.randomBytes.create(16) as OwnerWriteKey;
-
 /**
  * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
  * derivation.
- *
- * This is an internal helper function, use:
- *
- * - {@link createAppOwner}
- * - {@link createShardOwner}
- * - {@link createSharedOwner}
- * - {@link createSharedReadonlyOwner}
  */
-export const createOwner = (secret: OwnerSecret): Owner => ({
+const createOwner = (secret: OwnerSecret): Owner => ({
   id: ownerIdBytesToOwnerId(
     OwnerIdBytes.orThrow(
       createSlip21(secret, ["Evolu", "OwnerIdBytes"]).slice(0, 16),
@@ -182,9 +190,9 @@ export interface AppOwner extends Owner {
 
 /** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
 export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
+  ...createOwner(secret),
   type: "AppOwner",
   mnemonic: ownerSecretToMnemonic(secret),
-  ...createOwner(secret),
 });
 
 /**
@@ -200,18 +208,13 @@ export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
  */
 export interface ShardOwner extends Owner {
   readonly type: "ShardOwner";
-  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
-export const createShardOwner = (
-  secret: OwnerSecret,
-  transports?: ReadonlyArray<OwnerTransport>,
-): ShardOwner => {
+export const createShardOwner = (secret: OwnerSecret): ShardOwner => {
   return {
-    type: "ShardOwner",
     ...createOwner(secret),
-    ...(transports && { transports }),
+    type: "ShardOwner",
   };
 };
 
@@ -236,21 +239,18 @@ export const createShardOwner = (
 export const deriveShardOwner = (
   owner: AppOwner,
   path: NonEmptyReadonlyArray<string | number>,
-  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
   const secret = createSlip21(owner.encryptionKey, path) as OwnerSecret;
 
   return {
-    type: "ShardOwner",
     ...createOwner(secret),
-    ...(transports && { transports }),
+    type: "ShardOwner",
   };
 };
 
 /** An {@link Owner} for collaborative data with write access. */
 export interface SharedOwner extends Owner {
   readonly type: "SharedOwner";
-  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /**
@@ -260,27 +260,18 @@ export interface SharedOwner extends Owner {
  * Use {@link createSharedReadonlyOwner} to create a read-only version for
  * sharing.
  */
-export const createSharedOwner = (
-  secret: OwnerSecret,
-  transports?: ReadonlyArray<OwnerTransport>,
-): SharedOwner => {
-  return {
-    type: "SharedOwner",
-    ...createOwner(secret),
-    ...(transports && { transports }),
-  };
-};
+export const createSharedOwner = (secret: OwnerSecret): SharedOwner => ({
+  ...createOwner(secret),
+  type: "SharedOwner",
+});
 
 /**
  * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
  * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
  * data without write access.
  */
-export interface SharedReadonlyOwner {
+export interface SharedReadonlyOwner extends ReadonlyOwner {
   readonly type: "SharedReadonlyOwner";
-  readonly id: OwnerId;
-  readonly encryptionKey: EncryptionKey;
-  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
@@ -290,7 +281,6 @@ export const createSharedReadonlyOwner = (
   type: "SharedReadonlyOwner",
   id: sharedOwner.id,
   encryptionKey: sharedOwner.encryptionKey,
-  ...(sharedOwner.transports && { transports: sharedOwner.transports }),
 });
 
 /**
@@ -383,8 +373,8 @@ export const parseOwnerIdFromOwnerWebSocketTransportUrl = (
   url: string,
 ): OwnerId | null => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));
 
-/** Base interface for all owner errors. */
-export interface BaseOwnerError {
+/** Common interface implemented by all owner domain errors. */
+export interface OwnerError {
   readonly ownerId: OwnerId;
 }
 

packages/common/src/local-first/Protocol.ts

@@ -221,7 +221,7 @@ import {
 } from "../Type.js";
 import { Predicate } from "../Types.js";
 import {
-  BaseOwnerError,
+  OwnerError,
   Owner,
   OwnerId,
   OwnerIdBytes,
@@ -382,7 +382,7 @@ export type ProtocolError =
  * Represents a version mismatch in the Evolu Protocol. Occurs when the
  * initiator and non-initiator are using incompatible protocol versions.
  */
-export interface ProtocolVersionError extends BaseOwnerError {
+export interface ProtocolVersionError extends OwnerError {
   readonly type: "ProtocolVersionError";
   readonly version: NonNegativeInt;
   /** Indicates which side is obsolete and should update. */
@@ -397,15 +397,15 @@ export interface ProtocolInvalidDataError {
 }
 
 /** Error when a {@link OwnerWriteKey} is invalid, missing, or fails validation. */
-export interface ProtocolWriteKeyError extends BaseOwnerError {
+export interface ProtocolWriteKeyError extends OwnerError {
   readonly type: "ProtocolWriteKeyError";
 }
 
 /**
  * Error indicating a serious relay-side write failure. Clients should log this
  * error and show a generic sync error to the user.
  */
-export interface ProtocolWriteError extends BaseOwnerError {
+export interface ProtocolWriteError extends OwnerError {
   readonly type: "ProtocolWriteError";
 }
 
@@ -422,15 +422,15 @@ export interface ProtocolWriteError extends BaseOwnerError {
  * plan. Quota monitoring and management is the relay provider's
  * responsibility.
  */
-export interface ProtocolQuotaError extends BaseOwnerError {
+export interface ProtocolQuotaError extends OwnerError {
   readonly type: "ProtocolQuotaError";
 }
 
 /**
  * Error indicating a serious relay-side synchronization failure. Clients should
  * log this error and show a generic sync error to the user.
  */
-export interface ProtocolSyncError extends BaseOwnerError {
+export interface ProtocolSyncError extends OwnerError {
   readonly type: "ProtocolSyncError";
 }
 

packages/common/src/local-first/Public.ts

@@ -6,6 +6,7 @@
 
 export { createEvolu } from "./Evolu.js";
 export type { Evolu, EvoluConfig, EvoluDeps, EvoluError } from "./Evolu.js";
+export type { UnuseOwner } from "./Evolu.js";
 export * from "./LocalAuth.js";
 export * from "./Owner.js";
 export * as kysely from "./PublicKysely.js";

packages/common/src/local-first/Storage.ts

@@ -26,7 +26,7 @@ import {
   TypeError,
 } from "../Type.js";
 import {
-  BaseOwnerError,
+  OwnerError,
   Owner,
   OwnerId,
   OwnerIdBytes,
@@ -172,12 +172,12 @@ export interface StorageDep {
 }
 
 /** Error indicating a serious write failure. */
-export interface StorageWriteError extends BaseOwnerError {
+export interface StorageWriteError extends OwnerError {
   readonly type: "StorageWriteError";
 }
 
 /** Error when storage or billing quota is exceeded. */
-export interface StorageQuotaError extends BaseOwnerError {
+export interface StorageQuotaError extends OwnerError {
   readonly type: "StorageQuotaError";
 }