@evolu/common 8.1.0 → 8.3.0

package/dist/src/local-first/Owner.d.ts

@@ -1,5 +1,34 @@
 /**
- * Owner identity and cryptographic key derivation.
+ * ## Intro
+ *
+ * Cryptographic identities that define ownership, encryption, sync, and
+ * deletion boundaries for Evolu data.
+ *
+ * Every database change belongs to an {@link Owner} and is encrypted with its
+ * {@link OwnerEncryptionKey}. Owners also make sync selective: only the
+ * {@link AppOwner} is synced by default, while other owners can be synced when
+ * needed.
+ *
+ * Individual changes in an append-only local-first history can only be marked
+ * as deleted. An entire owner, however, can be removed from devices and relays
+ * together with all of its data. The AppOwner must remain because it coordinates
+ * the deletion of other owners across devices.
+ *
+ * Choose an owner by how its data should live and be shared:
+ *
+ * - {@link AppOwner} coordinates sync and persists for the lifetime of the app
+ *   identity.
+ * - {@link ShardOwner} partitions application data so it can be synced and
+ *   deleted independently.
+ * - {@link SharedOwner} grants collaborative read and write access.
+ * - {@link SharedReadonlyOwner} grants read-only access to shared data.
+ *
+ * An {@link OwnerSecret} deterministically derives three independent values
+ * using SLIP-21:
+ *
+ * - {@link OwnerId}: the public identifier.
+ * - {@link OwnerEncryptionKey}: the symmetric key that protects the data.
+ * - {@link OwnerWriteKey}: the rotatable token that authorizes writes.
  *
  * @module
  */
@@ -11,6 +40,7 @@ import { TimestampBytes } from "./Timestamp.ts";
  * {@link Owner} without a {@link OwnerWriteKey}.
  *
  * @see {@link createSharedReadonlyOwner}
+ * @group Core
  */
 export interface ReadonlyOwner {
     readonly id: OwnerId;
@@ -18,35 +48,11 @@ export interface ReadonlyOwner {
     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 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:
- *
- * - **Coordination**: {@link AppOwner} for sync coordination and long-term
- *   persistence
- * - **Data partitioning**: {@link ShardOwner} for partitioning application data
- * - **Collaboration**: {@link SharedOwner} for collaborative write access
- * - **Data sharing**: {@link SharedReadonlyOwner} for read-only access to shared
- *   data
+ * An {@link ReadonlyOwner} with an {@link OwnerWriteKey} for authorizing writes.
  *
- * Owners are cryptographically derived from an {@link OwnerSecret} using
- * SLIP-21, ensuring secure and deterministic key generation:
+ * See the {@link @evolu/common!"local-first/Owner" | Owners overview}.
  *
- * - {@link OwnerId}: Globally unique public identifier
- * - {@link OwnerEncryptionKey}: Symmetric encryption key for data protection
- * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
- *
- * @see {@link createAppOwner}
- * @see {@link createShardOwner}
- * @see {@link createSharedOwner}
- * @see {@link createSharedReadonlyOwner}
+ * @group Core
  */
 export interface Owner extends ReadonlyOwner {
     /** TODO: Wrap with `Redacted` in the next major version. */
@@ -55,37 +61,67 @@ export interface Owner extends ReadonlyOwner {
 /**
  * An {@link ReadonlyOwner} or {@link Owner} with non-empty {@link OwnerTransport}s
  * so it can be synced.
+ *
+ * @group Transport
  */
 export interface SyncOwner {
     readonly owner: ReadonlyOwner | Owner;
     readonly transports: NonEmptyReadonlyArray<OwnerTransport>;
 }
-/** OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}. */
+/**
+ * A branded {@link Id} that uniquely identifies an {@link Owner}.
+ *
+ * @group Core
+ */
 export declare const OwnerId: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"String", string, string, import("../Type.ts").TypeOfError<"String">, null, import("../Type.ts").TypeOfError<"String">, never, string, true>, "Id", import("../Type.ts").IdError>, "OwnerId", never>;
 export type OwnerId = typeof OwnerId.Output;
-/** Bytes representation of {@link OwnerId}. */
+/**
+ * Binary representation of {@link OwnerId}.
+ *
+ * @group Core
+ */
 export declare const OwnerIdBytes: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Length16", import("../Type.ts").LengthError<16>>, "IdBytes", never>, "OwnerIdBytes", never>;
 export type OwnerIdBytes = typeof OwnerIdBytes.Output;
-/** Converts {@link OwnerId} to {@link OwnerIdBytes}. */
+/**
+ * Converts {@link OwnerId} to {@link OwnerIdBytes}.
+ *
+ * @group Core
+ */
 export declare const ownerIdToOwnerIdBytes: (ownerId: OwnerId) => OwnerIdBytes;
-/** Converts {@link OwnerIdBytes} to {@link OwnerId}. */
+/**
+ * Converts {@link OwnerIdBytes} to {@link OwnerId}.
+ *
+ * @group Core
+ */
 export declare const ownerIdBytesToOwnerId: (ownerIdBytes: OwnerIdBytes) => OwnerId;
+/**
+ * Length of an {@link OwnerWriteKey} in bytes.
+ *
+ * @group Core
+ */
 export declare const ownerWriteKeyLength: number & import("../Brand.ts").Brand<"NonNaN"> & import("../Brand.ts").Brand<"Finite"> & import("../Brand.ts").Brand<"Int"> & import("../Brand.ts").Brand<"NonNegative">;
-/** Symmetric encryption key for {@link Owner} data protection. */
+/**
+ * Symmetric encryption key for {@link Owner} data protection.
+ *
+ * @group Core
+ */
 export declare const OwnerEncryptionKey: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Entropy", never>, "Length32", import("../Type.ts").LengthError<32>>, "EncryptionKey", never>, "OwnerEncryptionKey", never>;
 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}.
+ * A token that authorizes write operations for an {@link Owner}.
+ *
+ * The initial key is derived from {@link OwnerSecret}. Replace it with a random
+ * key from {@link createOwnerWriteKey} to rotate write access without changing
+ * the owner identity or encryption key.
+ *
+ * @group Core
  */
 export declare const OwnerWriteKey: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Entropy", never>, "Length16", import("../Type.ts").LengthError<16>>, "OwnerWriteKey", never>;
 export type OwnerWriteKey = typeof OwnerWriteKey.Output;
 /**
- * Creates a new random {@link OwnerWriteKey} for rotation.
+ * Creates a random {@link OwnerWriteKey} for rotating write access.
  *
- * The initial OwnerWriteKey is deterministically derived from
- * {@link OwnerSecret}. Use `createOwnerWriteKey` to rotate (replace) the write
- * key without changing the owner identity.
+ * @group Core
  */
 export declare const createOwnerWriteKey: (deps: RandomBytesDep) => OwnerWriteKey;
 /**
@@ -93,16 +129,34 @@ export declare const createOwnerWriteKey: (deps: RandomBytesDep) => OwnerWriteKe
  *
  * Can be created using {@link createOwnerSecret} or converted from a
  * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
+ *
+ * @group Core
  */
 export declare const OwnerSecret: import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").BrandType<import("../Type.ts").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.ts").ObjectTagError<"Uint8Array">, null, import("../Type.ts").ObjectTagError<"Uint8Array">, never, Uint8Array<ArrayBufferLike>, true>, "Entropy", never>, "Length32", import("../Type.ts").LengthError<32>>, "OwnerSecret", never>;
 export type OwnerSecret = typeof OwnerSecret.Output;
-/** Creates a {@link OwnerSecret}. */
+/**
+ * Creates a cryptographically random {@link OwnerSecret}.
+ *
+ * @group Core
+ */
 export declare const createOwnerSecret: (deps: RandomBytesDep) => OwnerSecret;
-/** Deterministic {@link OwnerSecret} for tests. */
+/**
+ * Deterministic {@link OwnerSecret} for tests.
+ *
+ * @group Testing
+ */
 export declare const testOwnerSecret: Uint8Array<ArrayBufferLike> & import("../Brand.ts").Brand<"Entropy"> & import("../Brand.ts").Brand<"Length32"> & import("../Brand.ts").Brand<"OwnerSecret">;
-/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+/**
+ * Converts an {@link OwnerSecret} to a {@link Mnemonic}.
+ *
+ * @group Core
+ */
 export declare const ownerSecretToMnemonic: (secret: OwnerSecret) => Mnemonic;
-/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+/**
+ * Converts a {@link Mnemonic} to an {@link OwnerSecret}.
+ *
+ * @group Core
+ */
 export declare const mnemonicToOwnerSecret: (mnemonic: Mnemonic) => OwnerSecret;
 /**
  * The AppOwner represents the application owner. It's created using a
@@ -135,6 +189,8 @@ export declare const mnemonicToOwnerSecret: (mnemonic: Mnemonic) => OwnerSecret;
  * For data sharing scenarios, use {@link SharedOwner} and
  * {@link SharedReadonlyOwner} to make intent explicit and distinguish
  * collaborative usage from {@link AppOwner} coordination.
+ *
+ * @group Variants
  */
 export interface AppOwner extends Owner, Typed<"AppOwner"> {
     /**
@@ -146,9 +202,17 @@ export interface AppOwner extends Owner, Typed<"AppOwner"> {
      */
     readonly mnemonic: Mnemonic;
 }
-/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+/**
+ * Creates an {@link AppOwner} from an {@link OwnerSecret}.
+ *
+ * @group Variants
+ */
 export declare const createAppOwner: (secret: OwnerSecret) => AppOwner;
-/** Deterministic {@link AppOwner} for tests. */
+/**
+ * Deterministic {@link AppOwner} for tests.
+ *
+ * @group Testing
+ */
 export declare const testAppOwner: AppOwner;
 /**
  * An {@link Owner} for sharding data.
@@ -160,10 +224,16 @@ export declare const testAppOwner: AppOwner;
  * Can be created from {@link OwnerSecret} via {@link createShardOwner} or
  * deterministically derived from {@link AppOwner} using
  * {@link deriveShardOwner}.
+ *
+ * @group Variants
  */
 export interface ShardOwner extends Owner, Typed<"ShardOwner"> {
 }
-/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+/**
+ * Creates a {@link ShardOwner} from an {@link OwnerSecret}.
+ *
+ * @group Variants
+ */
 export declare const createShardOwner: (secret: OwnerSecret) => ShardOwner;
 /**
  * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
@@ -182,9 +252,15 @@ export declare const createShardOwner: (secret: OwnerSecret) => ShardOwner;
  * - Use paths like `["shard", 1]` for versioned data lifecycle
  * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
  * - Each device can derive the same owners and set up initial structure
+ *
+ * @group Variants
  */
 export declare const deriveShardOwner: (owner: AppOwner, path: NonEmptyReadonlyArray<string | number>) => ShardOwner;
-/** An {@link Owner} for collaborative data with write access. */
+/**
+ * An {@link Owner} for collaborative data with write access.
+ *
+ * @group Variants
+ */
 export interface SharedOwner extends Owner, Typed<"SharedOwner"> {
 }
 /**
@@ -193,21 +269,31 @@ export interface SharedOwner extends Owner, Typed<"SharedOwner"> {
  *
  * Use {@link createSharedReadonlyOwner} to create a read-only version for
  * sharing.
+ *
+ * @group Variants
  */
 export declare const createSharedOwner: (secret: OwnerSecret) => 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.
+ *
+ * @group Variants
  */
 export interface SharedReadonlyOwner extends ReadonlyOwner, Typed<"SharedReadonlyOwner"> {
 }
-/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
+/**
+ * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}.
+ *
+ * @group Variants
+ */
 export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
 /**
  * Transport configuration for connecting to relays.
  *
  * Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
+ *
+ * @group Transport
  */
 export type OwnerTransport = OwnerWebSocketTransport;
 /**
@@ -236,6 +322,7 @@ export type OwnerTransport = OwnerWebSocketTransport;
  *
  * @see {@link createOwnerWebSocketTransport}
  * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
+ * @group Transport
  */
 export interface OwnerWebSocketTransport extends Typed<"WebSocket"> {
     readonly url: string;
@@ -284,6 +371,8 @@ export interface OwnerWebSocketTransport extends Typed<"WebSocket"> {
  *   url: `wss://relay.evolu.dev?ownerId=${appOwner.id}`,
  * });
  * ```
+ *
+ * @group Transport
  */
 export declare const createOwnerWebSocketTransport: (config: {
     readonly url: string;
@@ -319,37 +408,40 @@ export declare const createOwnerWebSocketTransport: (config: {
  *   parseOwnerIdFromOwnerWebSocketTransportUrl("/sync?ownerId=invalid"),
  * ).toBeNull();
  * ```
+ *
+ * @group Transport
  */
 export declare const parseOwnerIdFromOwnerWebSocketTransportUrl: (url: string) => OwnerId | null;
-/** Common interface implemented by all owner domain errors. */
+/**
+ * Common interface implemented by all owner domain errors.
+ *
+ * @group Core
+ */
 export interface OwnerError {
     readonly ownerId: OwnerId;
 }
 /**
- * Usage data for an {@link OwnerId}.
+ * Storage usage and timestamp bounds for an {@link Owner}.
  *
- * Tracks storage usage to enforce quotas if needed, and some other stuff.
+ * Storage and relay implementations use this metadata for quota enforcement and
+ * timestamp insertion strategies.
  *
- * TODO:
- *
- * - Add transferredBytes for billing and monitoring network usage.
+ * @group Core
  */
 export interface OwnerUsage {
-    /** The {@link Owner} this usage data belongs to. */
+    /** Binary identifier of the {@link Owner} this usage belongs to. */
     readonly ownerId: OwnerIdBytes;
     /**
      * Total logical data bytes stored.
      *
-     * Measures the size of {@link EncryptedDbChange}s only, excluding
-     * {@link Storage} implementation overhead (with SqliteStorage: indexes,
-     * skiplist columns, etc.). This provides:
+     * Measures only {@link EncryptedDbChange} data and excludes {@link Storage}
+     * implementation overhead such as indexes and skip-list columns. This makes
+     * the measurement consistent across storage implementations and suitable for:
      *
      * - **Predictable measurement** - same data = same byte count across all
      *   instances
-     * - **Quota enforcement** - consistent billing/limits independent of storage
-     *   implementation
-     * - **Overhead tracking** - actual Storage size can be compared against this to
-     *   monitor efficiency
+     * - **Quota enforcement** - limits independent of storage implementation
+     * - **Overhead tracking** - comparison with actual storage size
      */
     readonly storedBytes: NonNegativeInt;
     /** Tracks the earliest timestamp for timestamp insertion strategies. */
@@ -390,6 +482,8 @@ export interface OwnerUsage {
  *
  * DeviceAppOwner Evolu instance is secure only when its data stays on the
  * device.
+ *
+ * @group Variants
  */
 export interface DeviceAppOwner extends AppOwner {
     readonly source: "ExpoSecureStore" | "WebAuthnPrf" | "ElectronSafeStorage";

package/dist/src/local-first/Owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/local-first/Owner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/local-first/Owner.ts"],"names":[],"mappings":"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"}

package/dist/src/local-first/Owner.js

@@ -1,5 +1,34 @@
 /**
- * Owner identity and cryptographic key derivation.
+ * ## Intro
+ *
+ * Cryptographic identities that define ownership, encryption, sync, and
+ * deletion boundaries for Evolu data.
+ *
+ * Every database change belongs to an {@link Owner} and is encrypted with its
+ * {@link OwnerEncryptionKey}. Owners also make sync selective: only the
+ * {@link AppOwner} is synced by default, while other owners can be synced when
+ * needed.
+ *
+ * Individual changes in an append-only local-first history can only be marked
+ * as deleted. An entire owner, however, can be removed from devices and relays
+ * together with all of its data. The AppOwner must remain because it coordinates
+ * the deletion of other owners across devices.
+ *
+ * Choose an owner by how its data should live and be shared:
+ *
+ * - {@link AppOwner} coordinates sync and persists for the lifetime of the app
+ *   identity.
+ * - {@link ShardOwner} partitions application data so it can be synced and
+ *   deleted independently.
+ * - {@link SharedOwner} grants collaborative read and write access.
+ * - {@link SharedReadonlyOwner} grants read-only access to shared data.
+ *
+ * An {@link OwnerSecret} deterministically derives three independent values
+ * using SLIP-21:
+ *
+ * - {@link OwnerId}: the public identifier.
+ * - {@link OwnerEncryptionKey}: the symmetric key that protects the data.
+ * - {@link OwnerWriteKey}: the rotatable token that authorizes writes.
  *
  * @module
  */
@@ -10,28 +39,56 @@ import { testCreateRandomLib } from "../Random.js";
 import { getOrNull } from "../Result.js";
 import { brand, Id, IdBytes, idBytesToId, idToIdBytes, Mnemonic, NonNegativeInt, } from "../Type.js";
 import { TimestampBytes } from "./Timestamp.js";
-/** OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}. */
+/**
+ * A branded {@link Id} that uniquely identifies an {@link Owner}.
+ *
+ * @group Core
+ */
 export const OwnerId = /*#__PURE__*/ brand("OwnerId", Id);
-/** Bytes representation of {@link OwnerId}. */
+/**
+ * Binary representation of {@link OwnerId}.
+ *
+ * @group Core
+ */
 export const OwnerIdBytes = /*#__PURE__*/ brand("OwnerIdBytes", IdBytes);
-/** Converts {@link OwnerId} to {@link OwnerIdBytes}. */
+/**
+ * Converts {@link OwnerId} to {@link OwnerIdBytes}.
+ *
+ * @group Core
+ */
 export const ownerIdToOwnerIdBytes = (ownerId) => idToIdBytes(ownerId);
-/** Converts {@link OwnerIdBytes} to {@link OwnerId}. */
+/**
+ * Converts {@link OwnerIdBytes} to {@link OwnerId}.
+ *
+ * @group Core
+ */
 export const ownerIdBytesToOwnerId = (ownerIdBytes) => idBytesToId(ownerIdBytes);
+/**
+ * Length of an {@link OwnerWriteKey} in bytes.
+ *
+ * @group Core
+ */
 export const ownerWriteKeyLength = /*#__PURE__*/ NonNegativeInt.orThrow(16);
-/** Symmetric encryption key for {@link Owner} data protection. */
+/**
+ * Symmetric encryption key for {@link Owner} data protection.
+ *
+ * @group Core
+ */
 export const OwnerEncryptionKey = /*#__PURE__*/ brand("OwnerEncryptionKey", EncryptionKey);
 /**
- * A secure token for write operations. It's derived from {@link OwnerSecret} by
- * default and can be rotated via {@link createOwnerWriteKey}.
+ * A token that authorizes write operations for an {@link Owner}.
+ *
+ * The initial key is derived from {@link OwnerSecret}. Replace it with a random
+ * key from {@link createOwnerWriteKey} to rotate write access without changing
+ * the owner identity or encryption key.
+ *
+ * @group Core
  */
 export const OwnerWriteKey = /*#__PURE__*/ brand("OwnerWriteKey", Entropy16);
 /**
- * Creates a new random {@link OwnerWriteKey} for rotation.
+ * Creates a random {@link OwnerWriteKey} for rotating write access.
  *
- * The initial OwnerWriteKey is deterministically derived from
- * {@link OwnerSecret}. Use `createOwnerWriteKey` to rotate (replace) the write
- * key without changing the owner identity.
+ * @group Core
  */
 export const createOwnerWriteKey = (deps) => deps.randomBytes.create(16);
 /**
@@ -39,19 +96,37 @@ export const createOwnerWriteKey = (deps) => deps.randomBytes.create(16);
  *
  * Can be created using {@link createOwnerSecret} or converted from a
  * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
+ *
+ * @group Core
  */
 export const OwnerSecret = /*#__PURE__*/ brand("OwnerSecret", Entropy32);
-/** Creates a {@link OwnerSecret}. */
+/**
+ * Creates a cryptographically random {@link OwnerSecret}.
+ *
+ * @group Core
+ */
 export const createOwnerSecret = (deps) => deps.randomBytes.create(32);
-/** Deterministic {@link OwnerSecret} for tests. */
+/**
+ * Deterministic {@link OwnerSecret} for tests.
+ *
+ * @group Testing
+ */
 export const testOwnerSecret = /*#__PURE__*/ createOwnerSecret({
     randomBytes: /*#__PURE__*/ testCreateRandomBytes({
         randomLib: /*#__PURE__*/ testCreateRandomLib(),
     }),
 });
-/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+/**
+ * Converts an {@link OwnerSecret} to a {@link Mnemonic}.
+ *
+ * @group Core
+ */
 export const ownerSecretToMnemonic = (secret) => bip39.entropyToMnemonic(secret, wordlist);
-/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+/**
+ * Converts a {@link Mnemonic} to an {@link OwnerSecret}.
+ *
+ * @group Core
+ */
 export const mnemonicToOwnerSecret = (mnemonic) => bip39.mnemonicToEntropy(mnemonic, wordlist);
 /**
  * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
@@ -62,15 +137,27 @@ const createOwner = (secret) => ({
     encryptionKey: OwnerEncryptionKey.orThrow(createSlip21(secret, ["Evolu", "OwnerEncryptionKey"])),
     writeKey: OwnerWriteKey.orThrow(createSlip21(secret, ["Evolu", "OwnerWriteKey"]).slice(0, 16)),
 });
-/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+/**
+ * Creates an {@link AppOwner} from an {@link OwnerSecret}.
+ *
+ * @group Variants
+ */
 export const createAppOwner = (secret) => ({
     ...createOwner(secret),
     type: "AppOwner",
     mnemonic: ownerSecretToMnemonic(secret),
 });
-/** Deterministic {@link AppOwner} for tests. */
+/**
+ * Deterministic {@link AppOwner} for tests.
+ *
+ * @group Testing
+ */
 export const testAppOwner = /*#__PURE__*/ createAppOwner(testOwnerSecret);
-/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+/**
+ * Creates a {@link ShardOwner} from an {@link OwnerSecret}.
+ *
+ * @group Variants
+ */
 export const createShardOwner = (secret) => ({
     ...createOwner(secret),
     type: "ShardOwner",
@@ -92,6 +179,8 @@ export const createShardOwner = (secret) => ({
  * - Use paths like `["shard", 1]` for versioned data lifecycle
  * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
  * - Each device can derive the same owners and set up initial structure
+ *
+ * @group Variants
  */
 export const deriveShardOwner = (owner, path) => {
     const secret = createSlip21(owner.encryptionKey, path);
@@ -106,12 +195,18 @@ export const deriveShardOwner = (owner, path) => {
  *
  * Use {@link createSharedReadonlyOwner} to create a read-only version for
  * sharing.
+ *
+ * @group Variants
  */
 export const createSharedOwner = (secret) => ({
     ...createOwner(secret),
     type: "SharedOwner",
 });
-/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
+/**
+ * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}.
+ *
+ * @group Variants
+ */
 export const createSharedReadonlyOwner = (sharedOwner) => ({
     type: "SharedReadonlyOwner",
     id: sharedOwner.id,
@@ -161,6 +256,8 @@ export const createSharedReadonlyOwner = (sharedOwner) => ({
  *   url: `wss://relay.evolu.dev?ownerId=${appOwner.id}`,
  * });
  * ```
+ *
+ * @group Transport
  */
 export const createOwnerWebSocketTransport = (config) => ({
     type: "WebSocket",
@@ -196,5 +293,7 @@ export const createOwnerWebSocketTransport = (config) => ({
  *   parseOwnerIdFromOwnerWebSocketTransportUrl("/sync?ownerId=invalid"),
  * ).toBeNull();
  * ```
+ *
+ * @group Transport
  */
 export const parseOwnerIdFromOwnerWebSocketTransportUrl = (url) => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/common",
-  "version": "8.1.0",
+  "version": "8.3.0",
   "description": "TypeScript library and local-first platform",
   "keywords": [
     "evolu",

package/src/Function.ts

@@ -162,6 +162,8 @@ export function disposable<T extends object>(
   value: T extends Disposable ? Omit<T, typeof Symbol.dispose> : T,
   disposer?: DisposableStack,
 ): T extends Disposable ? T : T & Disposable;
+
+/** Creates an asynchronously disposable object. */
 export function disposable<T extends object>(
   value: T extends AsyncDisposable ? Omit<T, typeof Symbol.asyncDispose> : T,
   disposer: AsyncDisposableStack,

package/src/Http.ts

@@ -377,24 +377,33 @@ export function fetch(
   init?: Omit<RequestInit, "signal">,
 ): Task<string, FetchError>;
 
+/** Fetches a resource and parses a successful response body as JSON. */
 export function fetch(
   input: RequestInfo | URL,
   mode: "json",
   init?: Omit<RequestInit, "signal">,
 ): Task<unknown, FetchError>;
 
+/** Fetches a resource and reads a successful response body as bytes. */
 export function fetch(
   input: RequestInfo | URL,
   mode: "bytes",
   init?: Omit<RequestInit, "signal">,
 ): Task<Uint8Array<ArrayBuffer>, FetchError>;
 
+/**
+ * Fetches a resource and returns its body-free response metadata.
+ *
+ * HTTP status is returned as data rather than interpreted as success or
+ * failure.
+ */
 export function fetch(
   input: RequestInfo | URL,
   mode: "headers",
   init?: Omit<RequestInit, "signal">,
 ): Task<FetchResponse, FetchTransportError>;
 
+/** Fetches a resource and consumes its response with a custom callback. */
 export function fetch<T, E = never>(
   input: RequestInfo | URL,
   consume: FetchConsume<T, E>,