@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.
- package/dist/src/Assert.d.ts +6 -3
- package/dist/src/Assert.d.ts.map +1 -1
- package/dist/src/Assert.js +7 -4
- package/dist/src/Brand.d.ts +75 -0
- package/dist/src/Brand.d.ts.map +1 -0
- package/dist/src/Brand.js +1 -0
- package/dist/src/Buffer.d.ts +1 -1
- package/dist/src/Buffer.d.ts.map +1 -1
- package/dist/src/Buffer.js +1 -1
- package/dist/src/CallbackRegistry.d.ts +53 -0
- package/dist/src/CallbackRegistry.d.ts.map +1 -0
- package/dist/src/CallbackRegistry.js +25 -0
- package/dist/src/Console.d.ts +31 -6
- package/dist/src/Console.d.ts.map +1 -1
- package/dist/src/Console.js +72 -9
- package/dist/src/Crypto.d.ts +61 -34
- package/dist/src/Crypto.d.ts.map +1 -1
- package/dist/src/Crypto.js +29 -42
- package/dist/src/Evolu/Db.d.ts +159 -66
- package/dist/src/Evolu/Db.d.ts.map +1 -1
- package/dist/src/Evolu/Db.js +300 -705
- package/dist/src/Evolu/Diff.d.ts +3 -3
- package/dist/src/Evolu/Diff.d.ts.map +1 -1
- package/dist/src/Evolu/Diff.js +7 -5
- package/dist/src/Evolu/Evolu.d.ts +200 -115
- package/dist/src/Evolu/Evolu.d.ts.map +1 -1
- package/dist/src/Evolu/Evolu.js +287 -157
- package/dist/src/Evolu/Internal.d.ts +0 -2
- package/dist/src/Evolu/Internal.d.ts.map +1 -1
- package/dist/src/Evolu/Internal.js +0 -2
- package/dist/src/Evolu/LocalAuth.d.ts +144 -0
- package/dist/src/Evolu/LocalAuth.d.ts.map +1 -0
- package/dist/src/Evolu/LocalAuth.js +171 -0
- package/dist/src/Evolu/Owner.d.ts +209 -124
- package/dist/src/Evolu/Owner.d.ts.map +1 -1
- package/dist/src/Evolu/Owner.js +118 -104
- package/dist/src/Evolu/Platform.d.ts +9 -7
- package/dist/src/Evolu/Platform.d.ts.map +1 -1
- package/dist/src/Evolu/Protocol.d.ts +256 -211
- package/dist/src/Evolu/Protocol.d.ts.map +1 -1
- package/dist/src/Evolu/Protocol.js +558 -359
- package/dist/src/Evolu/Public.d.ts +6 -8
- package/dist/src/Evolu/Public.d.ts.map +1 -1
- package/dist/src/Evolu/Public.js +2 -3
- package/dist/src/Evolu/PublicKysely.js +3 -3
- package/dist/src/Evolu/Query.d.ts +2 -1
- package/dist/src/Evolu/Query.d.ts.map +1 -1
- package/dist/src/Evolu/Relay.d.ts +72 -4
- package/dist/src/Evolu/Relay.d.ts.map +1 -1
- package/dist/src/Evolu/Relay.js +124 -13
- package/dist/src/Evolu/Schema.d.ts +129 -73
- package/dist/src/Evolu/Schema.d.ts.map +1 -1
- package/dist/src/Evolu/Schema.js +169 -89
- package/dist/src/Evolu/Storage.d.ts +159 -14
- package/dist/src/Evolu/Storage.d.ts.map +1 -1
- package/dist/src/Evolu/Storage.js +42 -32
- package/dist/src/Evolu/Sync.d.ts +68 -13
- package/dist/src/Evolu/Sync.d.ts.map +1 -1
- package/dist/src/Evolu/Sync.js +414 -20
- package/dist/src/Evolu/Timestamp.d.ts +35 -27
- package/dist/src/Evolu/Timestamp.d.ts.map +1 -1
- package/dist/src/Evolu/Timestamp.js +27 -18
- package/dist/src/ManyToManyMap.d.ts +74 -10
- package/dist/src/ManyToManyMap.d.ts.map +1 -1
- package/dist/src/ManyToManyMap.js +41 -6
- package/dist/src/Number.d.ts +2 -1
- package/dist/src/Number.d.ts.map +1 -1
- package/dist/src/Random.d.ts +3 -2
- package/dist/src/Random.d.ts.map +1 -1
- package/dist/src/RefCountedResourceManager.d.ts +119 -0
- package/dist/src/RefCountedResourceManager.d.ts.map +1 -0
- package/dist/src/RefCountedResourceManager.js +197 -0
- package/dist/src/Result.d.ts +176 -51
- package/dist/src/Result.d.ts.map +1 -1
- package/dist/src/Result.js +30 -241
- package/dist/src/Sqlite.d.ts +21 -4
- package/dist/src/Sqlite.d.ts.map +1 -1
- package/dist/src/Sqlite.js +50 -8
- package/dist/src/Task.d.ts +511 -0
- package/dist/src/Task.d.ts.map +1 -0
- package/dist/src/Task.js +410 -0
- package/dist/src/Time.d.ts +59 -0
- package/dist/src/Time.d.ts.map +1 -1
- package/dist/src/Time.js +87 -4
- package/dist/src/Type.d.ts +474 -327
- package/dist/src/Type.d.ts.map +1 -1
- package/dist/src/Type.js +502 -436
- package/dist/src/Types.d.ts +0 -74
- package/dist/src/Types.d.ts.map +1 -1
- package/dist/src/WebSocket.d.ts +5 -2
- package/dist/src/WebSocket.d.ts.map +1 -1
- package/dist/src/WebSocket.js +12 -13
- package/dist/src/Worker.d.ts +39 -11
- package/dist/src/Worker.d.ts.map +1 -1
- package/dist/src/Worker.js +22 -4
- package/dist/src/index.d.ts +3 -3
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +3 -3
- package/package.json +14 -13
- package/src/Assert.ts +8 -7
- package/src/Brand.ts +75 -0
- package/src/Buffer.ts +1 -1
- package/src/CallbackRegistry.ts +84 -0
- package/src/Console.ts +91 -11
- package/src/Crypto.ts +94 -79
- package/src/Evolu/Db.ts +528 -1027
- package/src/Evolu/Diff.ts +7 -5
- package/src/Evolu/Evolu.ts +682 -329
- package/src/Evolu/Internal.ts +0 -2
- package/src/Evolu/LocalAuth.ts +422 -0
- package/src/Evolu/Owner.ts +282 -227
- package/src/Evolu/Platform.ts +9 -9
- package/src/Evolu/Protocol.ts +788 -640
- package/src/Evolu/Public.ts +7 -14
- package/src/Evolu/PublicKysely.ts +3 -3
- package/src/Evolu/Query.ts +2 -1
- package/src/Evolu/Relay.ts +238 -18
- package/src/Evolu/Schema.ts +391 -191
- package/src/Evolu/Storage.ts +275 -55
- package/src/Evolu/Sync.ts +708 -37
- package/src/Evolu/Timestamp.ts +38 -35
- package/src/ManyToManyMap.ts +127 -24
- package/src/Number.ts +2 -6
- package/src/Random.ts +3 -2
- package/src/RefCountedResourceManager.ts +368 -0
- package/src/Result.ts +183 -53
- package/src/Sqlite.ts +59 -23
- package/src/Task.ts +779 -0
- package/src/Time.ts +168 -4
- package/src/Type.ts +708 -660
- package/src/Types.ts +0 -76
- package/src/WebSocket.ts +23 -17
- package/src/Worker.ts +72 -23
- package/src/index.ts +3 -3
- package/dist/src/Callbacks.d.ts +0 -20
- package/dist/src/Callbacks.d.ts.map +0 -1
- package/dist/src/Callbacks.js +0 -18
- package/dist/src/Evolu/Config.d.ts +0 -69
- package/dist/src/Evolu/Config.d.ts.map +0 -1
- package/dist/src/Evolu/Config.js +0 -9
- package/dist/src/Evolu/Kysely.d.ts +0 -6
- package/dist/src/Evolu/Kysely.d.ts.map +0 -1
- package/dist/src/Evolu/Kysely.js +0 -21
- package/dist/src/NanoId.d.ts +0 -27
- package/dist/src/NanoId.d.ts.map +0 -1
- package/dist/src/NanoId.js +0 -6
- package/dist/src/Promise.d.ts +0 -180
- package/dist/src/Promise.d.ts.map +0 -1
- package/dist/src/Promise.js +0 -176
- package/src/Callbacks.ts +0 -43
- package/src/Evolu/Config.ts +0 -83
- package/src/Evolu/Kysely.ts +0 -38
- package/src/NanoId.ts +0 -39
- 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
|
-
*
|
|
5
|
+
* 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
|
|
3
6
|
*
|
|
4
|
-
* @
|
|
7
|
+
* Can be created using {@link createOwnerSecret} or converted from a
|
|
8
|
+
* {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
|
|
5
9
|
*/
|
|
6
|
-
import
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
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:
|
|
35
|
-
readonly 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
|
-
*
|
|
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").
|
|
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
|
-
|
|
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
|
|
55
|
-
*
|
|
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
|
|
58
|
-
export 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
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
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
|
|
67
|
-
readonly type: "AppOwner";
|
|
68
|
-
}
|
|
86
|
+
export declare const createOwner: (secret: OwnerSecret) => Owner;
|
|
69
87
|
/**
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
*
|
|
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
|
|
80
|
-
readonly type: "
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
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
|
|
96
|
-
readonly type: "SharedOwner";
|
|
97
|
-
readonly mnemonic: Mnemonic;
|
|
98
|
-
readonly writeKey: WriteKey;
|
|
99
|
-
}
|
|
125
|
+
export type TransportConfig = WebSocketTransportConfig;
|
|
100
126
|
/**
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
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
|
|
108
|
-
readonly type: "
|
|
109
|
-
readonly
|
|
147
|
+
export interface WebSocketTransportConfig {
|
|
148
|
+
readonly type: "WebSocket";
|
|
149
|
+
readonly url: string;
|
|
110
150
|
}
|
|
111
151
|
/**
|
|
112
|
-
* Creates
|
|
113
|
-
*
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
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
|
|
165
|
+
export declare const createWebSocketTransportConfig: ({ relayUrl, ownerId, }: {
|
|
166
|
+
readonly relayUrl: string;
|
|
167
|
+
readonly ownerId: OwnerId;
|
|
168
|
+
}) => WebSocketTransportConfig;
|
|
123
169
|
/**
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
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
|
|
182
|
+
export declare const parseOwnerIdFromUrl: (url: string | undefined) => OwnerId | null;
|
|
130
183
|
/**
|
|
131
|
-
*
|
|
132
|
-
*
|
|
133
|
-
*
|
|
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
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
*
|
|
141
|
-
*
|
|
142
|
-
*
|
|
143
|
-
*
|
|
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
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
151
|
-
*
|
|
152
|
-
*
|
|
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
|
|
231
|
+
export declare const createSharedOwner: (secret: OwnerSecret, transports?: ReadonlyArray<TransportConfig>) => SharedOwner;
|
|
155
232
|
/**
|
|
156
|
-
*
|
|
157
|
-
* {@link
|
|
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
|
|
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":"
|
|
1
|
+
{"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Owner.ts"],"names":[],"mappings":"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"}
|