@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/dist/src/Assert.d.ts +6 -3
  2. package/dist/src/Assert.d.ts.map +1 -1
  3. package/dist/src/Assert.js +7 -4
  4. package/dist/src/Brand.d.ts +75 -0
  5. package/dist/src/Brand.d.ts.map +1 -0
  6. package/dist/src/Brand.js +1 -0
  7. package/dist/src/Buffer.d.ts +1 -1
  8. package/dist/src/Buffer.d.ts.map +1 -1
  9. package/dist/src/Buffer.js +1 -1
  10. package/dist/src/CallbackRegistry.d.ts +53 -0
  11. package/dist/src/CallbackRegistry.d.ts.map +1 -0
  12. package/dist/src/CallbackRegistry.js +25 -0
  13. package/dist/src/Console.d.ts +31 -6
  14. package/dist/src/Console.d.ts.map +1 -1
  15. package/dist/src/Console.js +72 -9
  16. package/dist/src/Crypto.d.ts +61 -34
  17. package/dist/src/Crypto.d.ts.map +1 -1
  18. package/dist/src/Crypto.js +29 -42
  19. package/dist/src/Evolu/Db.d.ts +159 -66
  20. package/dist/src/Evolu/Db.d.ts.map +1 -1
  21. package/dist/src/Evolu/Db.js +300 -705
  22. package/dist/src/Evolu/Diff.d.ts +3 -3
  23. package/dist/src/Evolu/Diff.d.ts.map +1 -1
  24. package/dist/src/Evolu/Diff.js +7 -5
  25. package/dist/src/Evolu/Evolu.d.ts +200 -115
  26. package/dist/src/Evolu/Evolu.d.ts.map +1 -1
  27. package/dist/src/Evolu/Evolu.js +287 -157
  28. package/dist/src/Evolu/Internal.d.ts +0 -2
  29. package/dist/src/Evolu/Internal.d.ts.map +1 -1
  30. package/dist/src/Evolu/Internal.js +0 -2
  31. package/dist/src/Evolu/LocalAuth.d.ts +144 -0
  32. package/dist/src/Evolu/LocalAuth.d.ts.map +1 -0
  33. package/dist/src/Evolu/LocalAuth.js +171 -0
  34. package/dist/src/Evolu/Owner.d.ts +209 -124
  35. package/dist/src/Evolu/Owner.d.ts.map +1 -1
  36. package/dist/src/Evolu/Owner.js +118 -104
  37. package/dist/src/Evolu/Platform.d.ts +9 -7
  38. package/dist/src/Evolu/Platform.d.ts.map +1 -1
  39. package/dist/src/Evolu/Protocol.d.ts +256 -211
  40. package/dist/src/Evolu/Protocol.d.ts.map +1 -1
  41. package/dist/src/Evolu/Protocol.js +558 -359
  42. package/dist/src/Evolu/Public.d.ts +6 -8
  43. package/dist/src/Evolu/Public.d.ts.map +1 -1
  44. package/dist/src/Evolu/Public.js +2 -3
  45. package/dist/src/Evolu/PublicKysely.js +3 -3
  46. package/dist/src/Evolu/Query.d.ts +2 -1
  47. package/dist/src/Evolu/Query.d.ts.map +1 -1
  48. package/dist/src/Evolu/Relay.d.ts +72 -4
  49. package/dist/src/Evolu/Relay.d.ts.map +1 -1
  50. package/dist/src/Evolu/Relay.js +124 -13
  51. package/dist/src/Evolu/Schema.d.ts +129 -73
  52. package/dist/src/Evolu/Schema.d.ts.map +1 -1
  53. package/dist/src/Evolu/Schema.js +169 -89
  54. package/dist/src/Evolu/Storage.d.ts +159 -14
  55. package/dist/src/Evolu/Storage.d.ts.map +1 -1
  56. package/dist/src/Evolu/Storage.js +42 -32
  57. package/dist/src/Evolu/Sync.d.ts +68 -13
  58. package/dist/src/Evolu/Sync.d.ts.map +1 -1
  59. package/dist/src/Evolu/Sync.js +414 -20
  60. package/dist/src/Evolu/Timestamp.d.ts +35 -27
  61. package/dist/src/Evolu/Timestamp.d.ts.map +1 -1
  62. package/dist/src/Evolu/Timestamp.js +27 -18
  63. package/dist/src/ManyToManyMap.d.ts +74 -10
  64. package/dist/src/ManyToManyMap.d.ts.map +1 -1
  65. package/dist/src/ManyToManyMap.js +41 -6
  66. package/dist/src/Number.d.ts +2 -1
  67. package/dist/src/Number.d.ts.map +1 -1
  68. package/dist/src/Random.d.ts +3 -2
  69. package/dist/src/Random.d.ts.map +1 -1
  70. package/dist/src/RefCountedResourceManager.d.ts +119 -0
  71. package/dist/src/RefCountedResourceManager.d.ts.map +1 -0
  72. package/dist/src/RefCountedResourceManager.js +197 -0
  73. package/dist/src/Result.d.ts +176 -51
  74. package/dist/src/Result.d.ts.map +1 -1
  75. package/dist/src/Result.js +30 -241
  76. package/dist/src/Sqlite.d.ts +21 -4
  77. package/dist/src/Sqlite.d.ts.map +1 -1
  78. package/dist/src/Sqlite.js +50 -8
  79. package/dist/src/Task.d.ts +511 -0
  80. package/dist/src/Task.d.ts.map +1 -0
  81. package/dist/src/Task.js +410 -0
  82. package/dist/src/Time.d.ts +59 -0
  83. package/dist/src/Time.d.ts.map +1 -1
  84. package/dist/src/Time.js +87 -4
  85. package/dist/src/Type.d.ts +474 -327
  86. package/dist/src/Type.d.ts.map +1 -1
  87. package/dist/src/Type.js +502 -436
  88. package/dist/src/Types.d.ts +0 -74
  89. package/dist/src/Types.d.ts.map +1 -1
  90. package/dist/src/WebSocket.d.ts +5 -2
  91. package/dist/src/WebSocket.d.ts.map +1 -1
  92. package/dist/src/WebSocket.js +12 -13
  93. package/dist/src/Worker.d.ts +39 -11
  94. package/dist/src/Worker.d.ts.map +1 -1
  95. package/dist/src/Worker.js +22 -4
  96. package/dist/src/index.d.ts +3 -3
  97. package/dist/src/index.d.ts.map +1 -1
  98. package/dist/src/index.js +3 -3
  99. package/package.json +14 -13
  100. package/src/Assert.ts +8 -7
  101. package/src/Brand.ts +75 -0
  102. package/src/Buffer.ts +1 -1
  103. package/src/CallbackRegistry.ts +84 -0
  104. package/src/Console.ts +91 -11
  105. package/src/Crypto.ts +94 -79
  106. package/src/Evolu/Db.ts +528 -1027
  107. package/src/Evolu/Diff.ts +7 -5
  108. package/src/Evolu/Evolu.ts +682 -329
  109. package/src/Evolu/Internal.ts +0 -2
  110. package/src/Evolu/LocalAuth.ts +422 -0
  111. package/src/Evolu/Owner.ts +282 -227
  112. package/src/Evolu/Platform.ts +9 -9
  113. package/src/Evolu/Protocol.ts +788 -640
  114. package/src/Evolu/Public.ts +7 -14
  115. package/src/Evolu/PublicKysely.ts +3 -3
  116. package/src/Evolu/Query.ts +2 -1
  117. package/src/Evolu/Relay.ts +238 -18
  118. package/src/Evolu/Schema.ts +391 -191
  119. package/src/Evolu/Storage.ts +275 -55
  120. package/src/Evolu/Sync.ts +708 -37
  121. package/src/Evolu/Timestamp.ts +38 -35
  122. package/src/ManyToManyMap.ts +127 -24
  123. package/src/Number.ts +2 -6
  124. package/src/Random.ts +3 -2
  125. package/src/RefCountedResourceManager.ts +368 -0
  126. package/src/Result.ts +183 -53
  127. package/src/Sqlite.ts +59 -23
  128. package/src/Task.ts +779 -0
  129. package/src/Time.ts +168 -4
  130. package/src/Type.ts +708 -660
  131. package/src/Types.ts +0 -76
  132. package/src/WebSocket.ts +23 -17
  133. package/src/Worker.ts +72 -23
  134. package/src/index.ts +3 -3
  135. package/dist/src/Callbacks.d.ts +0 -20
  136. package/dist/src/Callbacks.d.ts.map +0 -1
  137. package/dist/src/Callbacks.js +0 -18
  138. package/dist/src/Evolu/Config.d.ts +0 -69
  139. package/dist/src/Evolu/Config.d.ts.map +0 -1
  140. package/dist/src/Evolu/Config.js +0 -9
  141. package/dist/src/Evolu/Kysely.d.ts +0 -6
  142. package/dist/src/Evolu/Kysely.d.ts.map +0 -1
  143. package/dist/src/Evolu/Kysely.js +0 -21
  144. package/dist/src/NanoId.d.ts +0 -27
  145. package/dist/src/NanoId.d.ts.map +0 -1
  146. package/dist/src/NanoId.js +0 -6
  147. package/dist/src/Promise.d.ts +0 -180
  148. package/dist/src/Promise.d.ts.map +0 -1
  149. package/dist/src/Promise.js +0 -176
  150. package/src/Callbacks.ts +0 -43
  151. package/src/Evolu/Config.ts +0 -83
  152. package/src/Evolu/Kysely.ts +0 -38
  153. package/src/NanoId.ts +0 -39
  154. package/src/Promise.ts +0 -295
@@ -1,160 +1,245 @@
1
+ import { NonEmptyReadonlyArray } from "../Array.js";
2
+ import { EncryptionKey, RandomBytesDep } from "../Crypto.js";
3
+ import { Mnemonic, NonNegativeInt } from "../Type.js";
1
4
  /**
2
- * TODO:
5
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
3
6
  *
4
- * @module
7
+ * Can be created using {@link createOwnerSecret} or converted from a
8
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
5
9
  */
6
- import { CreateMnemonicDep, CreateRandomBytesDep, EncryptionKey, MnemonicSeed } from "../Crypto.js";
7
- import { NanoIdLibDep } from "../NanoId.js";
8
- import { TimeDep } from "../Time.js";
9
- import { DateIsoString, Mnemonic, NonNegativeInt } from "../Type.js";
10
- import { TimestampString } from "./Timestamp.js";
10
+ export declare const OwnerSecret: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerSecret", import("../Type.js").BrandWithoutRefineError<"OwnerSecret", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>;
11
+ export type OwnerSecret = typeof OwnerSecret.Type;
12
+ /** Creates a {@link OwnerSecret}. */
13
+ export declare const createOwnerSecret: (deps: RandomBytesDep) => OwnerSecret;
14
+ /** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
15
+ export declare const ownerSecretToMnemonic: (secret: OwnerSecret) => Mnemonic;
16
+ /** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
17
+ export declare const mnemonicToOwnerSecret: (mnemonic: Mnemonic) => OwnerSecret;
11
18
  /**
12
- * `Owner` is an entity in Evolu that owns data, meaning it is locally stored on
13
- * a device under the user’s control. Data can be personal private, peer-to-peer
14
- * shared, or aggregated from multiple owners.
15
- *
16
- * An owner has a {@link Mnemonic} from which {@link OwnerId} and
17
- * {@link EncryptionKey} are deterministically derived using SLIP-21, and an
18
- * optional {@link WriteKey} that, when present, enables writing to the Evolu
19
- * Relay or peers. The {@link WriteKey} can be rotated.
20
- *
21
- * Variants include {@link AppOwner}, {@link ShardOwner}, {@link SharedOwner}, and
22
- * {@link SharedReadonlyOwner}, each with specific roles and properties detailed
23
- * in their respective definitions.
24
- *
25
- * Public-key cryptography isn’t included here as it belongs to app and varies
26
- * by use case. An Evolu app without collaboration doesn’t need it, while a
27
- * Nostr-like app can leverage Nostr NIPs, or a super-safe app can use
28
- * post-quantum cryptography.
19
+ * The Owner represents ownership of data in Evolu. Every database change is
20
+ * assigned to an owner, enabling sync functionality and access control.
21
+ *
22
+ * Owners enable **partial sync** - applications can choose which owners to
23
+ * sync, allowing selective data synchronization based on specific needs.
24
+ *
25
+ * Owners also provide **real data deletion** - while individual changes in
26
+ * local-first/distributed systems can only be marked as deleted, entire owners
27
+ * can be completely deleted from both relays and devices (except for
28
+ * {@link AppOwner}, which must be preserved for sync coordination).
29
+ *
30
+ * Evolu provides different owner types depending on their use case:
31
+ *
32
+ * - **Coordination**: {@link AppOwner} for sync coordination and long-term
33
+ * persistence
34
+ * - **Data partitioning**: {@link ShardOwner} for partitioning application data
35
+ * - **Collaboration**: {@link SharedOwner} for collaborative write access
36
+ * - **Data sharing**: {@link SharedReadonlyOwner} for read-only access to shared
37
+ * data
38
+ *
39
+ * Owners are cryptographically derived from an {@link OwnerSecret} using
40
+ * SLIP-21, ensuring secure and deterministic key generation:
41
+ *
42
+ * - {@link OwnerId}: Globally unique public identifier
43
+ * - {@link EncryptionKey}: Symmetric encryption key for data protection
44
+ * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
45
+ *
46
+ * @see {@link createOwner}
29
47
  */
30
48
  export interface Owner {
31
- readonly mnemonic: Mnemonic;
32
- readonly createdAt: DateIsoString;
33
49
  readonly id: OwnerId;
34
- readonly encryptionKey: EncryptionKey;
35
- readonly writeKey: WriteKey;
36
- }
37
- export interface OwnerWithWriteAccess {
38
- readonly id: OwnerId;
39
- readonly encryptionKey: EncryptionKey;
40
- readonly writeKey: WriteKey;
50
+ readonly encryptionKey: OwnerEncryptionKey;
51
+ readonly writeKey: OwnerWriteKey;
41
52
  }
42
53
  /**
43
- * The unique identifier of {@link Owner} derived from the {@link Mnemonic}.
44
- *
45
- * This branded {@link Id} type, generated by {@link createSlip21Id}, is a
46
- * 21-character {@link Base64Url} string (126 bits of entropy), providing a
47
- * compact, shareable, and secure identifier for UI use, tied to the owner's
48
- * mnemonic and derivation path.
54
+ * OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}.
55
+ * Branded from {@link Id} to leverage existing helpers like {@link idToIdBytes}.
49
56
  */
50
- export declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").RegexError<"Id">, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").RegexError<"Id">>, never>;
57
+ export declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").IdError, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").IdError>, never>;
51
58
  export type OwnerId = typeof OwnerId.Type;
52
- export declare const writeKeyLength: NonNegativeInt;
59
+ /** Bytes representation of {@link OwnerId}. */
60
+ export declare const OwnerIdBytes: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").Uint8ArrayError>, "IdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>, never>, "OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>>, never>;
61
+ export type OwnerIdBytes = typeof OwnerIdBytes.Type;
62
+ export declare const ownerIdToOwnerIdBytes: (ownerId: OwnerId) => OwnerIdBytes;
63
+ export declare const ownerIdBytesToOwnerId: (ownerIdBytes: OwnerIdBytes) => OwnerId;
64
+ export declare const ownerWriteKeyLength: NonNegativeInt;
65
+ export declare const OwnerEncryptionKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "EncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>, "OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>>, never>;
66
+ export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
53
67
  /**
54
- * A secure token proving the initiator can write changes. Derived from a
55
- * mnemonic or randomly generated. It's rotatable.
68
+ * A secure token for write operations. It's derived from {@link OwnerSecret} by
69
+ * default and can be rotated via {@link createOwnerWriteKey}.
56
70
  */
57
- export declare const WriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, `Length${number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">}`, import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>, import("../Type.js").Uint8ArrayError>, "WriteKey", import("../Type.js").BrandWithoutRefineError<"WriteKey", import("../Type.js").Uint8ArrayError | import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>>, never>;
58
- export type WriteKey = typeof WriteKey.Type;
71
+ export declare const OwnerWriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerWriteKey", import("../Type.js").BrandWithoutRefineError<"OwnerWriteKey", import("../Type.js").LengthError<16> | import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, never>;
72
+ export type OwnerWriteKey = typeof OwnerWriteKey.Type;
73
+ /** Creates a randomly generated {@link OwnerWriteKey}. */
74
+ export declare const createOwnerWriteKey: (deps: RandomBytesDep) => OwnerWriteKey;
59
75
  /**
60
- * The root owner of an Evolu app, created from a mnemonic safely generated on a
61
- * device when the app is initialized or restored on another device using an
62
- * existing mnemonic. It manages the app's core data, including the storage of
63
- * other owners' mnemonics in an encrypted app table. Its `writeKey` is
64
- * deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
76
+ * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
77
+ * derivation.
78
+ *
79
+ * This is an internal helper function, use:
80
+ *
81
+ * - {@link createAppOwner}
82
+ * - {@link createShardOwner}
83
+ * - {@link createSharedOwner}
84
+ * - {@link createSharedReadonlyOwner}
65
85
  */
66
- export interface AppOwner extends Owner {
67
- readonly type: "AppOwner";
68
- }
86
+ export declare const createOwner: (secret: OwnerSecret) => Owner;
69
87
  /**
70
- * Used to shard data within an app for partial or deferred sync. Created in the
71
- * Evolu `initialData` function or dynamically as needed. Its mnemonic is stored
72
- * in an app table (encrypted by `AppOwner`) and synced between devices. Its
73
- * `writeKey` is deterministic and rotatable, enabling selective syncing of data
74
- * subsets. Not intended for sharing outside the app.
75
- *
76
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
77
- * Evolu from the `mnemonic`, reducing storage overhead.
88
+ * The AppOwner represents the application owner. It's created using a
89
+ * cryptographically secure random generator or derived from an external source,
90
+ * e.g., mnemonic stored securely in a hardware device.
91
+ *
92
+ * While it's possible to store all application data in AppOwner, the better
93
+ * approach is to use it only for sync coordination. Storing all app data in
94
+ * AppOwner means that data will be stored/synced forever. And that's a problem
95
+ * if we want to provide real data deletion or in-app data migration without
96
+ * data duplication. In local-first apps/distributed systems, we can't delete
97
+ * individual changes, we only mark them as deleted, otherwise sync could not
98
+ * work.
99
+ *
100
+ * If we really want to delete data or at least avoid syncing it, we must store
101
+ * it using a different owner than AppOwner, e.g. {@link ShardOwner} or
102
+ * {@link SharedOwner}, and delete that owner. The AppOwner itself must be
103
+ * preserved because it coordinates deletion information across devices. Other
104
+ * devices need to sync the information that an owner was deleted so they can
105
+ * delete their local data as well.
78
106
  */
79
- export interface ShardOwner {
80
- readonly type: "ShardOwner";
81
- readonly mnemonic: Mnemonic;
82
- readonly writeKey: WriteKey;
107
+ export interface AppOwner extends Owner {
108
+ readonly type: "AppOwner";
109
+ /**
110
+ * The mnemonic that was used to derive the AppOwner keys. Optional when the
111
+ * AppOwner is created from external keys to avoid sharing the mnemonic with
112
+ * the Evolu app.
113
+ */
114
+ readonly mnemonic?: Mnemonic | null;
83
115
  }
116
+ /** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
117
+ export declare const createAppOwner: (secret: OwnerSecret) => AppOwner;
84
118
  /**
85
- * Used to share data among one or more users, enabling collaboration or
86
- * controlled access. Its `writeKey` is random (not derived from the mnemonic,
87
- * stored alongside it in the app table) and rotatable, ensuring it cannot be
88
- * regenerated by others if shared. Share the `mnemonic` alone for read-only
89
- * access (as `SharedReadonlyOwner`) or share SharedOwner itself for write
90
- * access.
91
- *
92
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
93
- * Evolu from the `mnemonic`, reducing storage overhead.
119
+ * Transport configuration for connecting to relays.
120
+ *
121
+ * Each {@link Owner} can specify one or more transports to connect to different
122
+ * relays for data synchronization. Currently supports WebSocket transport, with
123
+ * future support planned for Bluetooth, LocalNetwork, and other protocols.
94
124
  */
95
- export interface SharedOwner {
96
- readonly type: "SharedOwner";
97
- readonly mnemonic: Mnemonic;
98
- readonly writeKey: WriteKey;
99
- }
125
+ export type TransportConfig = WebSocketTransportConfig;
100
126
  /**
101
- * Used for sharing data that can only be read, such as with followers or peers
102
- * in a read-only sync scenario. It lacks a `writeKey`, containing only the
103
- * `mnemonic` from which `id` and `encryptionKey` are derived by Evolu.
104
- * Typically derived from a `SharedOwner` by sharing its `mnemonic` without the
105
- * `writeKey`.
127
+ * WebSocket transport configuration for relay connections.
128
+ *
129
+ * Use {@link createWebSocketTransportConfig} to create a properly formatted URL
130
+ * with {@link OwnerId}. The relay uses {@link parseOwnerIdFromUrl} to extract the
131
+ * OwnerId from the query string.
132
+ *
133
+ * ### Authentication and Error Handling
134
+ *
135
+ * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
136
+ * server error), the browser WebSocket API does not expose the specific HTTP
137
+ * status code or reason - it only reports a generic connection failure. The
138
+ * client automatically retries with exponential backoff and jitter, eventually
139
+ * succeeding once the configuration or server issue is resolved.
140
+ *
141
+ * Legitimate clients will be properly configured with valid credentials, so
142
+ * automatic retry is appropriate.
143
+ *
144
+ * @see {@link createWebSocketTransportConfig}
145
+ * @see {@link parseOwnerIdFromUrl}
106
146
  */
107
- export interface SharedReadonlyOwner {
108
- readonly type: "SharedReadonlyOwner";
109
- readonly mnemonic: Mnemonic;
147
+ export interface WebSocketTransportConfig {
148
+ readonly type: "WebSocket";
149
+ readonly url: string;
110
150
  }
111
151
  /**
112
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
113
- * it on another device; otherwise, generates a new mnemonic.
114
- */
115
- export declare const createAppOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">) => AppOwner;
116
- /**
117
- * Creates a {@link ShardOwner} for sharding app data with a freshly generated
118
- * mnemonic. Unlike {@link createAppOwner}, it doesn’t accept an existing
119
- * mnemonic because ShardOwner mnemonics are always generated and restored
120
- * automatically via database sync.
152
+ * Creates a {@link WebSocketTransportConfig} for the given relay URL and
153
+ * {@link OwnerId}.
154
+ *
155
+ * ### Example
156
+ *
157
+ * ```ts
158
+ * const transport = createWebSocketTransportConfig({
159
+ * relayUrl: "wss://relay.evolu.dev",
160
+ * ownerId: owner.id,
161
+ * });
162
+ * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
163
+ * ```
121
164
  */
122
- export declare const createShardOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => ShardOwner;
165
+ export declare const createWebSocketTransportConfig: ({ relayUrl, ownerId, }: {
166
+ readonly relayUrl: string;
167
+ readonly ownerId: OwnerId;
168
+ }) => WebSocketTransportConfig;
123
169
  /**
124
- * Creates a fresh {@link SharedOwner} for sharing data with write access. Takes
125
- * no arguments as both `mnemonic` and rotatable `writeKey` are newly generated;
126
- * when shared, recipients use the provided `mnemonic` and `writeKey` directly
127
- * as a {@link SharedOwner} without needing to recreate it.
170
+ * Extracts {@link OwnerId} from a URL query string.
171
+ *
172
+ * Parses the query string `?ownerId=...` and validates that the extracted value
173
+ * is a valid {@link OwnerId}.
174
+ *
175
+ * ### Example
176
+ *
177
+ * ```ts
178
+ * parseOwnerIdFromUrl("/sync?ownerId=_12345678abcdefgh");
179
+ * // Returns: OwnerId or null
180
+ * ```
128
181
  */
129
- export declare const createSharedOwner: (deps: CreateRandomBytesDep & CreateMnemonicDep) => SharedOwner;
182
+ export declare const parseOwnerIdFromUrl: (url: string | undefined) => OwnerId | null;
130
183
  /**
131
- * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner} for read-only
132
- * data sharing. Extracts the `mnemonic` from the provided {@link SharedOwner},
133
- * omitting its `writeKey` to ensure read-only access.
184
+ * An {@link Owner} for sharding data.
185
+ *
186
+ * ShardOwners are the recommended storage location for most application data
187
+ * because they can be completely deleted (both on relays and devices) and
188
+ * conditionally synced.
189
+ *
190
+ * Can be created from {@link OwnerSecret} via {@link createShardOwner} or
191
+ * deterministically derived from {@link AppOwner} using
192
+ * {@link deriveShardOwner}.
134
193
  */
135
- export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
136
- /** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
137
- export declare const createOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">, writeKey?: WriteKey) => Owner;
138
- export declare const createWriteKey: (deps: CreateRandomBytesDep) => (seed?: MnemonicSeed) => WriteKey;
194
+ export interface ShardOwner extends Owner {
195
+ readonly type: "ShardOwner";
196
+ readonly transports?: ReadonlyArray<TransportConfig>;
197
+ }
198
+ /** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
199
+ export declare const createShardOwner: (secret: OwnerSecret, transports?: ReadonlyArray<TransportConfig>) => ShardOwner;
139
200
  /**
140
- * An `OwnerRow` represents a row in the `evolu_owner` table, based on an
141
- * {@link Owner} with an added `timestamp` ({@link TimestampString}) for CRDT
142
- * sync. It supports all {@link Owner} variants with an optional `writeKey`; use
143
- * {@link createOwnerRow} to align it with a specific {@link Owner}.
201
+ * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
202
+ *
203
+ * **Advantages of derived owners:**
204
+ *
205
+ * - **Deterministic**: Same path always produces the same ShardOwner across all
206
+ * devices
207
+ * - **Immediate availability**: Can be hardcoded and used before sync occurs
208
+ * - **Consistent setup**: All devices start with identical data structure
209
+ * - **Lifecycle management**: Can implement epoch patterns for clean data
210
+ * deletion and recreation
211
+ *
212
+ * **Common patterns:**
213
+ *
214
+ * - Use paths like `["shard", 1]` for versioned data lifecycle
215
+ * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
216
+ * - Each device can derive the same owners and set up initial structure
144
217
  */
145
- export type OwnerRow = Omit<Owner, "writeKey"> & {
146
- readonly writeKey: WriteKey | null;
147
- readonly timestamp: TimestampString;
148
- };
218
+ export declare const deriveShardOwner: (owner: AppOwner, path: NonEmptyReadonlyArray<string | number>, transports?: ReadonlyArray<TransportConfig>) => ShardOwner;
219
+ /** An {@link Owner} for collaborative data with write access. */
220
+ export interface SharedOwner extends Owner {
221
+ readonly type: "SharedOwner";
222
+ readonly transports?: ReadonlyArray<TransportConfig>;
223
+ }
149
224
  /**
150
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
151
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
152
- * sync.
225
+ * Creates a {@link SharedOwner} from an {@link OwnerSecret} for collaborative
226
+ * write access.
227
+ *
228
+ * Use {@link createSharedReadonlyOwner} to create a read-only version for
229
+ * sharing.
153
230
  */
154
- export declare const createOwnerRow: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep & NanoIdLibDep) => (owner: AppOwner | ShardOwner | SharedOwner | SharedReadonlyOwner) => OwnerRow;
231
+ export declare const createSharedOwner: (secret: OwnerSecret, transports?: ReadonlyArray<TransportConfig>) => SharedOwner;
155
232
  /**
156
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
157
- * {@link SharedOwner}, returning a new instance with the updated key.
233
+ * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
234
+ * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
235
+ * data without write access.
158
236
  */
159
- export declare const rotateWriteKey: <T extends AppOwner | ShardOwner | SharedOwner>(owner: T, newWriteKey: WriteKey) => T;
237
+ export interface SharedReadonlyOwner {
238
+ readonly type: "SharedReadonlyOwner";
239
+ readonly id: OwnerId;
240
+ readonly encryptionKey: EncryptionKey;
241
+ readonly transports?: ReadonlyArray<TransportConfig>;
242
+ }
243
+ /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
244
+ export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
160
245
  //# sourceMappingURL=Owner.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Owner.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Owner.ts"],"names":[],"mappings":"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"}