@evolu/common 5.4.8 → 6.0.0

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 (242) hide show
  1. package/README.md +30 -34
  2. package/dist/src/Array.d.ts +17 -0
  3. package/dist/src/Array.d.ts.map +1 -0
  4. package/dist/src/Array.js +12 -0
  5. package/dist/src/Assert.d.ts +68 -0
  6. package/dist/src/Assert.d.ts.map +1 -0
  7. package/dist/src/Assert.js +77 -0
  8. package/dist/src/BigInt.d.ts +20 -0
  9. package/dist/src/BigInt.d.ts.map +1 -0
  10. package/dist/src/BigInt.js +18 -0
  11. package/dist/src/Buffer.d.ts +92 -0
  12. package/dist/src/Buffer.d.ts.map +1 -0
  13. package/dist/src/Buffer.js +62 -0
  14. package/dist/src/Callbacks.d.ts +20 -0
  15. package/dist/src/Callbacks.d.ts.map +1 -0
  16. package/dist/src/Callbacks.js +18 -0
  17. package/dist/src/Console.d.ts +78 -0
  18. package/dist/src/Console.d.ts.map +1 -0
  19. package/dist/src/Console.js +103 -0
  20. package/dist/src/Crypto.d.ts +72 -39
  21. package/dist/src/Crypto.d.ts.map +1 -1
  22. package/dist/src/Crypto.js +89 -54
  23. package/dist/src/Eq.d.ts +97 -0
  24. package/dist/src/Eq.d.ts.map +1 -0
  25. package/dist/src/Eq.js +167 -0
  26. package/dist/src/Error.d.ts +14 -10
  27. package/dist/src/Error.d.ts.map +1 -1
  28. package/dist/src/Error.js +43 -11
  29. package/dist/src/Evolu/Config.d.ts +69 -0
  30. package/dist/src/Evolu/Config.d.ts.map +1 -0
  31. package/dist/src/Evolu/Config.js +9 -0
  32. package/dist/src/Evolu/Db.d.ts +126 -0
  33. package/dist/src/Evolu/Db.d.ts.map +1 -0
  34. package/dist/src/Evolu/Db.js +774 -0
  35. package/dist/src/Evolu/Diff.d.ts +43 -0
  36. package/dist/src/Evolu/Diff.d.ts.map +1 -0
  37. package/dist/src/Evolu/Diff.js +95 -0
  38. package/dist/src/Evolu/Evolu.d.ts +334 -0
  39. package/dist/src/Evolu/Evolu.d.ts.map +1 -0
  40. package/dist/src/Evolu/Evolu.js +434 -0
  41. package/dist/src/Evolu/Internal.d.ts +26 -0
  42. package/dist/src/Evolu/Internal.d.ts.map +1 -0
  43. package/dist/src/Evolu/Internal.js +25 -0
  44. package/dist/src/Evolu/Kysely.d.ts +6 -0
  45. package/dist/src/Evolu/Kysely.d.ts.map +1 -0
  46. package/dist/src/Evolu/Kysely.js +21 -0
  47. package/dist/src/Evolu/Owner.d.ts +155 -0
  48. package/dist/src/Evolu/Owner.d.ts.map +1 -0
  49. package/dist/src/Evolu/Owner.js +126 -0
  50. package/dist/src/Evolu/Platform.d.ts +23 -0
  51. package/dist/src/Evolu/Platform.d.ts.map +1 -0
  52. package/dist/src/Evolu/Platform.js +1 -0
  53. package/dist/src/Evolu/Protocol.d.ts +401 -0
  54. package/dist/src/Evolu/Protocol.d.ts.map +1 -0
  55. package/dist/src/Evolu/Protocol.js +1151 -0
  56. package/dist/src/Evolu/Public.d.ts +18 -0
  57. package/dist/src/Evolu/Public.d.ts.map +1 -0
  58. package/dist/src/Evolu/Public.js +11 -0
  59. package/dist/src/Evolu/PublicKysely.d.ts +148 -0
  60. package/dist/src/Evolu/PublicKysely.d.ts.map +1 -0
  61. package/dist/src/Evolu/PublicKysely.js +185 -0
  62. package/dist/src/Evolu/Query.d.ts +63 -0
  63. package/dist/src/Evolu/Query.d.ts.map +1 -0
  64. package/dist/src/Evolu/Query.js +61 -0
  65. package/dist/src/Evolu/Relay.d.ts +13 -0
  66. package/dist/src/Evolu/Relay.d.ts.map +1 -0
  67. package/dist/src/Evolu/Relay.js +109 -0
  68. package/dist/src/Evolu/Schema.d.ts +201 -0
  69. package/dist/src/Evolu/Schema.d.ts.map +1 -0
  70. package/dist/src/Evolu/Schema.js +150 -0
  71. package/dist/src/Evolu/Storage.d.ts +49 -0
  72. package/dist/src/Evolu/Storage.d.ts.map +1 -0
  73. package/dist/src/Evolu/Storage.js +1111 -0
  74. package/dist/src/Evolu/Sync.d.ts +59 -0
  75. package/dist/src/Evolu/Sync.d.ts.map +1 -0
  76. package/dist/src/Evolu/Sync.js +29 -0
  77. package/dist/src/Evolu/Timestamp.d.ts +106 -0
  78. package/dist/src/Evolu/Timestamp.d.ts.map +1 -0
  79. package/dist/src/Evolu/Timestamp.js +179 -0
  80. package/dist/src/Function.d.ts +54 -0
  81. package/dist/src/Function.d.ts.map +1 -0
  82. package/dist/src/Function.js +38 -0
  83. package/dist/src/ManyToManyMap.d.ts +26 -0
  84. package/dist/src/ManyToManyMap.d.ts.map +1 -0
  85. package/dist/src/ManyToManyMap.js +92 -0
  86. package/dist/src/NanoId.d.ts +27 -0
  87. package/dist/src/NanoId.d.ts.map +1 -0
  88. package/dist/src/NanoId.js +6 -0
  89. package/dist/src/Number.d.ts +42 -0
  90. package/dist/src/Number.d.ts.map +1 -0
  91. package/dist/src/Number.js +55 -0
  92. package/dist/src/Object.d.ts +35 -0
  93. package/dist/src/Object.d.ts.map +1 -0
  94. package/dist/src/Object.js +36 -0
  95. package/dist/src/Order.d.ts +90 -0
  96. package/dist/src/Order.d.ts.map +1 -0
  97. package/dist/src/Order.js +85 -0
  98. package/dist/src/Promise.d.ts +180 -0
  99. package/dist/src/Promise.d.ts.map +1 -0
  100. package/dist/src/Promise.js +176 -0
  101. package/dist/src/Random.d.ts +52 -0
  102. package/dist/src/Random.d.ts.map +1 -0
  103. package/dist/src/Random.js +29 -0
  104. package/dist/src/Ref.d.ts +40 -0
  105. package/dist/src/Ref.d.ts.map +1 -0
  106. package/dist/src/Ref.js +13 -0
  107. package/dist/src/Result.d.ts +421 -0
  108. package/dist/src/Result.d.ts.map +1 -0
  109. package/dist/src/Result.js +357 -0
  110. package/dist/src/Skiplist.d.ts +23 -0
  111. package/dist/src/Skiplist.d.ts.map +1 -0
  112. package/dist/src/Skiplist.js +58 -0
  113. package/dist/src/Sqlite.d.ts +116 -52
  114. package/dist/src/Sqlite.d.ts.map +1 -1
  115. package/dist/src/Sqlite.js +183 -67
  116. package/dist/src/Store.d.ts +45 -8
  117. package/dist/src/Store.d.ts.map +1 -1
  118. package/dist/src/Store.js +33 -17
  119. package/dist/src/String.d.ts +2 -0
  120. package/dist/src/String.d.ts.map +1 -0
  121. package/dist/src/String.js +14 -0
  122. package/dist/src/Time.d.ts +20 -0
  123. package/dist/src/Time.d.ts.map +1 -0
  124. package/dist/src/Time.js +25 -0
  125. package/dist/src/Type.d.ts +1937 -0
  126. package/dist/src/Type.d.ts.map +1 -0
  127. package/dist/src/Type.js +2002 -0
  128. package/dist/src/Types.d.ts +188 -0
  129. package/dist/src/Types.d.ts.map +1 -0
  130. package/dist/src/Types.js +6 -0
  131. package/dist/src/WebSocket.d.ts +112 -0
  132. package/dist/src/WebSocket.d.ts.map +1 -0
  133. package/dist/src/WebSocket.js +139 -0
  134. package/dist/src/Worker.d.ts +44 -0
  135. package/dist/src/Worker.d.ts.map +1 -0
  136. package/dist/src/Worker.js +66 -0
  137. package/dist/src/index.d.ts +24 -11
  138. package/dist/src/index.d.ts.map +1 -1
  139. package/dist/src/index.js +24 -11
  140. package/package.json +29 -38
  141. package/src/Array.ts +39 -0
  142. package/src/Assert.ts +116 -0
  143. package/src/BigInt.ts +29 -0
  144. package/src/Buffer.ts +175 -0
  145. package/src/Callbacks.ts +43 -0
  146. package/src/Console.ts +159 -0
  147. package/src/Crypto.ts +169 -115
  148. package/src/Eq.ts +204 -0
  149. package/src/Error.ts +57 -20
  150. package/src/Evolu/Config.ts +83 -0
  151. package/src/Evolu/Db.ts +1275 -0
  152. package/src/Evolu/Diff.ts +142 -0
  153. package/src/Evolu/Evolu.ts +947 -0
  154. package/src/Evolu/Internal.ts +26 -0
  155. package/src/Evolu/Kysely.ts +38 -0
  156. package/src/Evolu/Owner.ts +296 -0
  157. package/src/Evolu/Platform.ts +27 -0
  158. package/src/Evolu/Protocol.ts +1857 -0
  159. package/src/Evolu/Public.ts +43 -0
  160. package/src/Evolu/PublicKysely.ts +240 -0
  161. package/src/Evolu/Query.ts +167 -0
  162. package/src/Evolu/Relay.ts +142 -0
  163. package/src/Evolu/Schema.ts +417 -0
  164. package/src/Evolu/Storage.ts +1281 -0
  165. package/src/Evolu/Sync.ts +105 -0
  166. package/src/Evolu/Timestamp.ts +311 -0
  167. package/src/Function.ts +58 -0
  168. package/src/ManyToManyMap.ts +140 -0
  169. package/src/NanoId.ts +39 -0
  170. package/src/Number.ts +90 -0
  171. package/src/Object.ts +64 -0
  172. package/src/Order.ts +113 -0
  173. package/src/Promise.ts +295 -0
  174. package/src/Random.ts +68 -0
  175. package/src/Ref.ts +63 -0
  176. package/src/Result.ts +453 -0
  177. package/src/Skiplist.ts +102 -0
  178. package/src/Sqlite.ts +366 -153
  179. package/src/Store.ts +79 -36
  180. package/src/String.ts +10 -0
  181. package/src/Time.ts +36 -0
  182. package/src/Type.ts +3978 -0
  183. package/src/Types.ts +209 -0
  184. package/src/WebSocket.ts +273 -0
  185. package/src/Worker.ts +129 -0
  186. package/src/index.ts +24 -11
  187. package/dist/src/Config.d.ts +0 -56
  188. package/dist/src/Config.d.ts.map +0 -1
  189. package/dist/src/Config.js +0 -39
  190. package/dist/src/Crdt.d.ts +0 -89
  191. package/dist/src/Crdt.d.ts.map +0 -1
  192. package/dist/src/Crdt.js +0 -181
  193. package/dist/src/Db.d.ts +0 -107
  194. package/dist/src/Db.d.ts.map +0 -1
  195. package/dist/src/Db.js +0 -443
  196. package/dist/src/Diff.d.ts +0 -27
  197. package/dist/src/Diff.d.ts.map +0 -1
  198. package/dist/src/Diff.js +0 -84
  199. package/dist/src/Evolu.d.ts +0 -426
  200. package/dist/src/Evolu.d.ts.map +0 -1
  201. package/dist/src/Evolu.js +0 -333
  202. package/dist/src/Model.d.ts +0 -141
  203. package/dist/src/Model.d.ts.map +0 -1
  204. package/dist/src/Model.js +0 -125
  205. package/dist/src/Murmurhash.d.ts +0 -2
  206. package/dist/src/Murmurhash.d.ts.map +0 -1
  207. package/dist/src/Murmurhash.js +0 -60
  208. package/dist/src/Owner.d.ts +0 -33
  209. package/dist/src/Owner.d.ts.map +0 -1
  210. package/dist/src/Owner.js +0 -26
  211. package/dist/src/Platform.d.ts +0 -37
  212. package/dist/src/Platform.d.ts.map +0 -1
  213. package/dist/src/Platform.js +0 -11
  214. package/dist/src/Protobuf.d.ts +0 -81
  215. package/dist/src/Protobuf.d.ts.map +0 -1
  216. package/dist/src/Protobuf.js +0 -92
  217. package/dist/src/Public.d.ts +0 -13
  218. package/dist/src/Public.d.ts.map +0 -1
  219. package/dist/src/Public.js +0 -6
  220. package/dist/src/Socket.d.ts +0 -8
  221. package/dist/src/Socket.d.ts.map +0 -1
  222. package/dist/src/Socket.js +0 -51
  223. package/dist/src/Sql.d.ts +0 -12
  224. package/dist/src/Sql.d.ts.map +0 -1
  225. package/dist/src/Sql.js +0 -30
  226. package/dist/src/Sync.d.ts +0 -70
  227. package/dist/src/Sync.d.ts.map +0 -1
  228. package/dist/src/Sync.js +0 -127
  229. package/src/Config.ts +0 -119
  230. package/src/Crdt.ts +0 -361
  231. package/src/Db.ts +0 -955
  232. package/src/Diff.ts +0 -114
  233. package/src/Evolu.ts +0 -1016
  234. package/src/Model.ts +0 -233
  235. package/src/Murmurhash.ts +0 -70
  236. package/src/Owner.ts +0 -69
  237. package/src/Platform.ts +0 -47
  238. package/src/Protobuf.ts +0 -155
  239. package/src/Public.ts +0 -12
  240. package/src/Socket.ts +0 -83
  241. package/src/Sql.ts +0 -41
  242. package/src/Sync.ts +0 -315
@@ -0,0 +1,43 @@
1
+ import { Query, Row } from "./Query.js";
2
+ export interface QueryPatches {
3
+ readonly query: Query;
4
+ readonly patches: ReadonlyArray<Patch>;
5
+ }
6
+ export type Patch = ReplaceAllPatch | ReplaceAtPatch;
7
+ export interface ReplaceAllPatch {
8
+ readonly op: "replaceAll";
9
+ readonly value: ReadonlyArray<Row>;
10
+ }
11
+ export interface ReplaceAtPatch {
12
+ readonly op: "replaceAt";
13
+ readonly index: number;
14
+ readonly value: Row;
15
+ }
16
+ export declare const applyPatches: (patches: ReadonlyArray<Patch>, current: ReadonlyArray<Row>) => ReadonlyArray<Row>;
17
+ /**
18
+ * We detect only changes in the whole result and in-place edits. In the future,
19
+ * we will add more heuristics. We will probably not implement the Myers diff
20
+ * algorithm because it's faster to rerender all than to compute many detailed
21
+ * patches. We will only implement logic a developer would implement manually,
22
+ * if necessary.
23
+ */
24
+ export declare const makePatches: (previousRows: ReadonlyArray<Row> | undefined, nextRows: ReadonlyArray<Row>) => ReadonlyArray<Patch>;
25
+ /**
26
+ * A unique identifier prepended to JSON-encoded strings. This allows safe
27
+ * detection and parsing of only those columns that require JSON.parse.
28
+ *
29
+ * The identifier is generated using nanoid to ensure randomness and uniqueness,
30
+ * preventing malicious actors from inserting fake data that could be
31
+ * misinterpreted as JSON by the application.
32
+ *
33
+ * Note: The same queries created by different browser tabs will have different
34
+ * identifiers and thus be considered different and cached separately. This is
35
+ * usually not a big deal, but if needed, the DB cache can be optimized by
36
+ * passing the kyselyJsonIdentifier into the DB worker during initialization,
37
+ * allowing queries to be grouped and recognized across tabs or sessions.
38
+ *
39
+ * See: https://github.com/kysely-org/kysely/issues/1372#issuecomment-2702773948
40
+ */
41
+ export declare const kyselyJsonIdentifier: string;
42
+ export declare const parseSqliteJsonArray: <T>(arr: ReadonlyArray<T>) => ReadonlyArray<T>;
43
+ //# sourceMappingURL=Diff.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Diff.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Diff.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,KAAK,GAAG,eAAe,GAAG,cAAc,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;CACrB;AAED,eAAO,MAAM,YAAY,GACvB,SAAS,aAAa,CAAC,KAAK,CAAC,EAC7B,SAAS,aAAa,CAAC,GAAG,CAAC,KAC1B,aAAa,CAAC,GAAG,CAUP,CAAC;AAEd;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,cAAc,aAAa,CAAC,GAAG,CAAC,GAAG,SAAS,EAC5C,UAAU,aAAa,CAAC,GAAG,CAAC,KAC3B,aAAa,CAAC,KAAK,CA6BrB,CAAC;AAUF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,QAAW,CAAC;AAE7C,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,KAAK,aAAa,CAAC,CAAC,CAAC,KACpB,aAAa,CAAC,CAAC,CAMjB,CAAC"}
@@ -0,0 +1,95 @@
1
+ import { nanoid } from "nanoid";
2
+ import { isPlainObject } from "../Object.js";
3
+ import { orderUint8Array } from "../Order.js";
4
+ import { String } from "../Type.js";
5
+ export const applyPatches = (patches, current) => patches.reduce((next, patch) => {
6
+ switch (patch.op) {
7
+ case "replaceAll":
8
+ return parseSqliteJsonArray(patch.value);
9
+ case "replaceAt": {
10
+ const parsedRow = parseSqliteJsonArray([patch.value])[0];
11
+ return next.toSpliced(patch.index, 1, parsedRow);
12
+ }
13
+ }
14
+ }, current);
15
+ /**
16
+ * We detect only changes in the whole result and in-place edits. In the future,
17
+ * we will add more heuristics. We will probably not implement the Myers diff
18
+ * algorithm because it's faster to rerender all than to compute many detailed
19
+ * patches. We will only implement logic a developer would implement manually,
20
+ * if necessary.
21
+ */
22
+ export const makePatches = (previousRows, nextRows) => {
23
+ if (previousRows === undefined)
24
+ return [{ op: "replaceAll", value: nextRows }];
25
+ // TODO: Detect prepend and append, it's cheap.
26
+ if (previousRows.length !== nextRows.length) {
27
+ return [{ op: "replaceAll", value: nextRows }];
28
+ }
29
+ const length = previousRows.length;
30
+ const replaceAtPatches = [];
31
+ for (let i = 0; i < length; i++) {
32
+ const previousRow = previousRows[i];
33
+ const nextRow = nextRows[i];
34
+ // We expect the same shape for both rows.
35
+ for (const key in previousRow)
36
+ if (!areEqual(previousRow[key], nextRow[key])) {
37
+ replaceAtPatches.push({ op: "replaceAt", value: nextRow, index: i });
38
+ break;
39
+ }
40
+ }
41
+ if (length > 0 && replaceAtPatches.length === length) {
42
+ return [{ op: "replaceAll", value: nextRows }];
43
+ }
44
+ return replaceAtPatches;
45
+ };
46
+ // TODO: Replace with eqSqliteValue.
47
+ const areEqual = (a, b) => {
48
+ if (a instanceof Uint8Array && b instanceof Uint8Array) {
49
+ return orderUint8Array(a, b) === 0;
50
+ }
51
+ return a === b;
52
+ };
53
+ /**
54
+ * A unique identifier prepended to JSON-encoded strings. This allows safe
55
+ * detection and parsing of only those columns that require JSON.parse.
56
+ *
57
+ * The identifier is generated using nanoid to ensure randomness and uniqueness,
58
+ * preventing malicious actors from inserting fake data that could be
59
+ * misinterpreted as JSON by the application.
60
+ *
61
+ * Note: The same queries created by different browser tabs will have different
62
+ * identifiers and thus be considered different and cached separately. This is
63
+ * usually not a big deal, but if needed, the DB cache can be optimized by
64
+ * passing the kyselyJsonIdentifier into the DB worker during initialization,
65
+ * allowing queries to be grouped and recognized across tabs or sessions.
66
+ *
67
+ * See: https://github.com/kysely-org/kysely/issues/1372#issuecomment-2702773948
68
+ */
69
+ export const kyselyJsonIdentifier = nanoid();
70
+ export const parseSqliteJsonArray = (arr) => {
71
+ const result = new Array(arr.length);
72
+ for (let i = 0; i < arr.length; ++i) {
73
+ result[i] = parse(arr[i]);
74
+ }
75
+ return result;
76
+ };
77
+ const parse = (obj) => {
78
+ if (String.is(obj) && obj.startsWith(kyselyJsonIdentifier)) {
79
+ return JSON.parse(obj.slice(kyselyJsonIdentifier.length));
80
+ }
81
+ if (Array.isArray(obj)) {
82
+ return parseSqliteJsonArray(obj);
83
+ }
84
+ if (isPlainObject(obj)) {
85
+ return parseObject(obj);
86
+ }
87
+ return obj;
88
+ };
89
+ const parseObject = (obj) => {
90
+ const result = Object.create(null);
91
+ for (const key in obj) {
92
+ result[key] = parse(obj[key]);
93
+ }
94
+ return result;
95
+ };
@@ -0,0 +1,334 @@
1
+ import { ConsoleDep } from "../Console.js";
2
+ import { SymmetricCryptoDecryptError } from "../Crypto.js";
3
+ import { TransferableError } from "../Error.js";
4
+ import { NanoIdLibDep } from "../NanoId.js";
5
+ import { SqliteError } from "../Sqlite.js";
6
+ import { StoreSubscribe } from "../Store.js";
7
+ import { TimeDep } from "../Time.js";
8
+ import { Mnemonic } from "../Type.js";
9
+ import { Config } from "./Config.js";
10
+ import { CreateDbWorkerDep } from "./Db.js";
11
+ import { AppOwner } from "./Owner.js";
12
+ import { CreateAppStateDep, FlushSyncDep } from "./Platform.js";
13
+ import { ProtocolError, ProtocolUnsupportedVersionError } from "./Protocol.js";
14
+ import { Queries, QueriesToQueryRowsPromises, Query, QueryRows, Row } from "./Query.js";
15
+ import { CreateQuery, EvoluSchema, Mutation } from "./Schema.js";
16
+ import { SyncState } from "./Sync.js";
17
+ import { TimestampError } from "./Timestamp.js";
18
+ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
19
+ /**
20
+ * Subscribe to {@link EvoluError} changes.
21
+ *
22
+ * ### Example
23
+ *
24
+ * ```ts
25
+ * const unsubscribe = evolu.subscribeError(() => {
26
+ * const error = evolu.getError();
27
+ * console.log(error);
28
+ * });
29
+ * ```
30
+ */
31
+ readonly subscribeError: StoreSubscribe;
32
+ /** Get {@link EvoluError}. */
33
+ readonly getError: () => EvoluError | null;
34
+ /**
35
+ * Create type-safe SQL {@link Query}.
36
+ *
37
+ * Evolu uses Kysely - the type-safe SQL query builder for TypeScript. See
38
+ * https://kysely.dev.
39
+ *
40
+ * All this function does is compile the Kysely query and serialize it into a
41
+ * unique string. Both operations are fast and cheap.
42
+ *
43
+ * For mutations, use {@link Evolu.insert} and {@link Evolu.update}.
44
+ *
45
+ * ### Example
46
+ *
47
+ * ```ts
48
+ * const allTodos = evolu.createQuery((db) =>
49
+ * db.selectFrom("todo").selectAll(),
50
+ * );
51
+ *
52
+ * const todoById = (id: TodoId) =>
53
+ * evolu.createQuery((db) =>
54
+ * db.selectFrom("todo").selectAll().where("id", "=", id),
55
+ * );
56
+ * ```
57
+ */
58
+ readonly createQuery: CreateQuery<S>;
59
+ /**
60
+ * Load {@link Query} and return a promise with {@link QueryRows}.
61
+ *
62
+ * A returned promise always resolves successfully because there is no reason
63
+ * why loading should fail. All data are local, and the query is typed. A
64
+ * serious unexpected Evolu error shall be handled with
65
+ * {@link Evolu.subscribeError}.
66
+ *
67
+ * Loading is batched, and returned promises are cached, so there is no need
68
+ * for an additional cache. Evolu's internal cache is invalidated on
69
+ * mutation.
70
+ *
71
+ * The returned promise is enriched with special status and value properties
72
+ * for the upcoming React `use` Hook, but other UI libraries can also leverage
73
+ * them. Speaking of React, there are two essential React Suspense-related
74
+ * patterns that every developer should be aware of—passing promises to
75
+ * children and caching over mutations.
76
+ *
77
+ * With promises passed to children, we can load a query as soon as possible,
78
+ * but we don't have to use the returned promise immediately. That's useful
79
+ * for prefetching, which is generally not necessary for local-first apps but
80
+ * can be if a query takes a long time to load.
81
+ *
82
+ * Caching over mutation is a pattern that every developer should know. As we
83
+ * said, Evolu caches promise until a mutation happens. A query loaded after
84
+ * that will return a new pending promise. That's okay for general usage but
85
+ * not for UI with React Suspense because a mutation would suspend rerendered
86
+ * queries on a page, and that's not a good UX.
87
+ *
88
+ * We call this pattern "caching over mutation" because it has no globally
89
+ * accepted name yet. React RFC for React Cache does not exist yet.
90
+ *
91
+ * For better UX, a query must be subscribed for updates. This way, instead of
92
+ * Suspense flashes, the user sees new data immediately because Evolu replaces
93
+ * cached promises with fresh, already resolved new ones.
94
+ *
95
+ * If you are curious why Evolu does not do that for all queries by default,
96
+ * the answer is simple: performance. Tracking changes is costly and
97
+ * meaningful only for visible (hence subscribed) queries anyway. To subscribe
98
+ * to a query, use {@link Evolu.subscribeQuery}.
99
+ *
100
+ * ### Example
101
+ *
102
+ * ```ts
103
+ * const allTodos = evolu.createQuery((db) =>
104
+ * db.selectFrom("todo").selectAll(),
105
+ * );
106
+ * evolu.loadQuery(allTodos).then(({ rows }) => {
107
+ * console.log(rows);
108
+ * });
109
+ * ```
110
+ */
111
+ readonly loadQuery: <R extends Row>(query: Query<R>) => Promise<QueryRows<R>>;
112
+ /**
113
+ * Load an array of {@link Query} queries and return an array of
114
+ * {@link QueryRows} promises. It's like `queries.map(loadQuery)` but with
115
+ * proper types for returned promises.
116
+ *
117
+ * ### Example
118
+ *
119
+ * ```ts
120
+ * evolu.loadQueries([allTodos, todoById(1)]);
121
+ * ```
122
+ */
123
+ readonly loadQueries: <R extends Row, Q extends Queries<R>>(queries: [...Q]) => [...QueriesToQueryRowsPromises<Q>];
124
+ /**
125
+ * Subscribe to {@link Query} {@link QueryRows} changes.
126
+ *
127
+ * ### Example
128
+ *
129
+ * ```ts
130
+ * const unsubscribe = evolu.subscribeQuery(allTodos)(() => {
131
+ * const rows = evolu.getQueryRows(allTodos);
132
+ * });
133
+ * ```
134
+ */
135
+ readonly subscribeQuery: (query: Query) => StoreSubscribe;
136
+ /**
137
+ * Get {@link QueryRows}.
138
+ *
139
+ * ### Example
140
+ *
141
+ * ```ts
142
+ * const unsubscribe = evolu.subscribeQuery(allTodos)(() => {
143
+ * const rows = evolu.getQueryRows(allTodos);
144
+ * });
145
+ * ```
146
+ */
147
+ readonly getQueryRows: <R extends Row>(query: Query<R>) => QueryRows<R>;
148
+ /**
149
+ * Subscribe to {@link AppOwner} changes.
150
+ *
151
+ * ### Example
152
+ *
153
+ * ```ts
154
+ * const unsubscribe = evolu.subscribeAppOwner(() => {
155
+ * const owner = evolu.getAppOwner();
156
+ * });
157
+ * ```
158
+ */
159
+ readonly subscribeAppOwner: StoreSubscribe;
160
+ /**
161
+ * Get {@link AppOwner}.
162
+ *
163
+ * ### Example
164
+ *
165
+ * ```ts
166
+ * const unsubscribe = evolu.subscribeAppOwner(() => {
167
+ * const owner = evolu.getAppOwner();
168
+ * });
169
+ * ```
170
+ */
171
+ readonly getAppOwner: () => AppOwner | null;
172
+ /**
173
+ * Subscribe to {@link SyncState} changes.
174
+ *
175
+ * ### Example
176
+ *
177
+ * ```ts
178
+ * const unsubscribe = evolu.subscribeSyncState(() => {
179
+ * const syncState = evolu.getSyncState();
180
+ * });
181
+ * ```
182
+ */
183
+ readonly subscribeSyncState: StoreSubscribe;
184
+ /**
185
+ * Get {@link SyncState}.
186
+ *
187
+ * ### Example
188
+ *
189
+ * ```ts
190
+ * const unsubscribe = evolu.subscribeSyncState(() => {
191
+ * const syncState = evolu.getSyncState();
192
+ * });
193
+ * ```
194
+ */
195
+ readonly getSyncState: () => SyncState;
196
+ /**
197
+ * Inserts a row.
198
+ *
199
+ * ### Example
200
+ *
201
+ * ```ts
202
+ * // TODO:
203
+ * ```
204
+ */
205
+ insert: Mutation<S, "insert">;
206
+ /**
207
+ * Updates a row.
208
+ *
209
+ * ### Example
210
+ *
211
+ * ```ts
212
+ * // TODO:
213
+ * ```
214
+ */
215
+ update: Mutation<S, "update">;
216
+ /**
217
+ * Upserts a row.
218
+ *
219
+ * ### Example
220
+ *
221
+ * ```ts
222
+ * // TODO:
223
+ * ```
224
+ */
225
+ upsert: Mutation<S, "upsert">;
226
+ /**
227
+ * Delete {@link AppOwner} and all their data from the current device. After
228
+ * the deletion, Evolu will purge the application state. For browsers, this
229
+ * will reload all tabs using Evolu. For native apps, it will restart the
230
+ * app.
231
+ *
232
+ * Reloading can be turned off via options if you want to provide a different
233
+ * UX.
234
+ */
235
+ readonly resetAppOwner: (options?: {
236
+ readonly reload?: boolean;
237
+ }) => Promise<void>;
238
+ /**
239
+ * Restore {@link AppOwner} with all their synced data. It uses
240
+ * {@link Evolu.resetAppOwner}, so be careful.
241
+ */
242
+ readonly restoreAppOwner: (mnemonic: Mnemonic, options?: {
243
+ readonly reload?: boolean;
244
+ }) => Promise<void>;
245
+ /**
246
+ * Reload the app in a platform-specific way. For browsers, this will reload
247
+ * all tabs using Evolu. For native apps, it will restart the app.
248
+ */
249
+ readonly reloadApp: () => void;
250
+ /** Export SQLite database file as Uint8Array. */
251
+ readonly exportDatabase: () => Promise<Uint8Array>;
252
+ }
253
+ /** Represent errors that can occur in Evolu. */
254
+ export type EvoluError = TimestampError | ProtocolError | TransferableError | SymmetricCryptoDecryptError | ProtocolUnsupportedVersionError | SqliteError;
255
+ export type EvoluDeps = CreateDbWorkerDep & TimeDep & NanoIdLibDep & Partial<FlushSyncDep> & ConsoleDep & CreateAppStateDep;
256
+ export interface EvoluConfigWithInitialData<S extends EvoluSchema = EvoluSchema> extends Config {
257
+ /**
258
+ * Use this option to create initial data (fixtures).
259
+ *
260
+ * ### Example
261
+ *
262
+ * ```ts
263
+ * const evolu = createEvolu(evoluReactWebDeps)(Schema, {
264
+ * initialData: (evolu) => {
265
+ * const todoCategory = evolu.insert("todoCategory", {
266
+ * name: "Not Urgent",
267
+ * });
268
+ *
269
+ * // This is a developer error, which should be fixed immediately.
270
+ * assert(todoCategory.ok, "invalid initial data");
271
+ *
272
+ * evolu.insert("todo", {
273
+ * title: "Try React Suspense",
274
+ * categoryId: todoCategory.value.id,
275
+ * });
276
+ * },
277
+ * });
278
+ * ```
279
+ */
280
+ initialData?: (evolu: EvoluForInitialData<S>) => void;
281
+ }
282
+ export interface EvoluForInitialData<S extends EvoluSchema = EvoluSchema> {
283
+ insert: Mutation<S, "insert">;
284
+ }
285
+ /**
286
+ * Creates an {@link Evolu} instance configured with the specified
287
+ * {@link EvoluSchema} and optional configuration.
288
+ *
289
+ * This function returns a configured Evolu instance, providing a typed
290
+ * interface for querying, mutating, and syncing your application's data. The
291
+ * returned instance includes:
292
+ *
293
+ * - Subscription methods for receiving updates on queries, the owner, errors, and
294
+ * sync state.
295
+ * - Methods for creating, updating, or deleting rows in a type-safe manner.
296
+ * - Methods for querying data using Evolu's typed SQL queries, leveraging Kysely
297
+ * under the hood.
298
+ * - Built-in support for local-first and offline-first data with automatic sync
299
+ * and merging.
300
+ * - Automatic schema evolution that updates the underlying database with new
301
+ * columns or tables.
302
+ * - Managing owner data with resetAppOwner and restoreAppOwner.
303
+ *
304
+ * ### Example
305
+ *
306
+ * ```ts
307
+ * const TodoId = id("Todo");
308
+ * type TodoId = InferType<typeof TodoId>;
309
+ *
310
+ * const TodoCategoryId = id("TodoCategory");
311
+ * type TodoCategoryId = InferType<typeof TodoCategoryId>;
312
+ *
313
+ * const NonEmptyString50 = maxLength(50, NonEmptyString);
314
+ * type NonEmptyString50 = InferType<typeof NonEmptyString50>;
315
+ *
316
+ * const Schema = {
317
+ * todo: {
318
+ * id: TodoId,
319
+ * title: NonEmptyString1000,
320
+ * isCompleted: nullOr(SqliteBoolean),
321
+ * categoryId: nullOr(TodoCategoryId),
322
+ * },
323
+ * todoCategory: {
324
+ * id: TodoCategoryId,
325
+ * name: NonEmptyString50,
326
+ * },
327
+ * };
328
+ *
329
+ * const evolu = createEvolu(evoluReactDeps)(Schema);
330
+ * ```
331
+ */
332
+ export declare const createEvolu: (deps: EvoluDeps) => <S extends EvoluSchema>(schema: S, partialConfig?: Partial<EvoluConfigWithInitialData<S>>) => Evolu<S>;
333
+ export declare const createNamespaceName: (config: Config) => (name: string) => string;
334
+ //# sourceMappingURL=Evolu.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Evolu.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Evolu.ts"],"names":[],"mappings":"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"}