@evolu/common 6.0.1-preview.8 → 7.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.
- package/README.md +2 -2
- package/dist/src/Array.d.ts +256 -12
- package/dist/src/Array.d.ts.map +1 -1
- package/dist/src/Array.js +215 -9
- package/dist/src/Assert.d.ts +0 -13
- package/dist/src/Assert.d.ts.map +1 -1
- package/dist/src/Assert.js +0 -15
- 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 +8 -7
- package/dist/src/Cache.d.ts +44 -0
- package/dist/src/Cache.d.ts.map +1 -0
- package/dist/src/Cache.js +52 -0
- package/dist/src/Callbacks.d.ts +45 -12
- package/dist/src/Callbacks.d.ts.map +1 -1
- package/dist/src/Callbacks.js +14 -7
- 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 +56 -42
- package/dist/src/Crypto.d.ts.map +1 -1
- package/dist/src/Crypto.js +40 -53
- package/dist/src/Evolu/Db.d.ts +162 -74
- package/dist/src/Evolu/Db.d.ts.map +1 -1
- package/dist/src/Evolu/Db.js +284 -702
- 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 +214 -134
- package/dist/src/Evolu/Evolu.d.ts.map +1 -1
- package/dist/src/Evolu/Evolu.js +189 -180
- 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 +150 -0
- package/dist/src/Evolu/LocalAuth.d.ts.map +1 -0
- package/dist/src/Evolu/LocalAuth.js +174 -0
- package/dist/src/Evolu/Owner.d.ts +273 -120
- package/dist/src/Evolu/Owner.d.ts.map +1 -1
- package/dist/src/Evolu/Owner.js +130 -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 +268 -240
- package/dist/src/Evolu/Protocol.d.ts.map +1 -1
- package/dist/src/Evolu/Protocol.js +600 -454
- 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.d.ts.map +1 -1
- package/dist/src/Evolu/PublicKysely.js +3 -4
- package/dist/src/Evolu/Query.d.ts +2 -1
- package/dist/src/Evolu/Query.d.ts.map +1 -1
- package/dist/src/Evolu/Query.js +1 -1
- package/dist/src/Evolu/Relay.d.ts +91 -8
- package/dist/src/Evolu/Relay.d.ts.map +1 -1
- package/dist/src/Evolu/Relay.js +214 -88
- package/dist/src/Evolu/Schema.d.ts +125 -47
- package/dist/src/Evolu/Schema.d.ts.map +1 -1
- package/dist/src/Evolu/Schema.js +175 -31
- package/dist/src/Evolu/Storage.d.ts +249 -27
- package/dist/src/Evolu/Storage.d.ts.map +1 -1
- package/dist/src/Evolu/Storage.js +198 -92
- 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 +469 -20
- package/dist/src/Evolu/Timestamp.d.ts +83 -30
- package/dist/src/Evolu/Timestamp.d.ts.map +1 -1
- package/dist/src/Evolu/Timestamp.js +79 -34
- package/dist/src/Identicon.d.ts +35 -0
- package/dist/src/Identicon.d.ts.map +1 -0
- package/dist/src/Identicon.js +143 -0
- package/dist/src/Instances.d.ts +34 -0
- package/dist/src/Instances.d.ts.map +1 -0
- package/dist/src/Instances.js +44 -0
- package/dist/src/Number.d.ts +4 -3
- package/dist/src/Number.d.ts.map +1 -1
- package/dist/src/Number.js +5 -4
- package/dist/src/Object.d.ts +10 -4
- package/dist/src/Object.d.ts.map +1 -1
- package/dist/src/Object.js +9 -3
- package/dist/src/Platform.d.ts +20 -0
- package/dist/src/Platform.d.ts.map +1 -0
- package/dist/src/Platform.js +22 -0
- package/dist/src/Random.d.ts +3 -2
- package/dist/src/Random.d.ts.map +1 -1
- package/dist/src/Relation.d.ts +79 -0
- package/dist/src/Relation.d.ts.map +1 -0
- package/dist/src/Relation.js +127 -0
- package/dist/src/Resources.d.ts +118 -0
- package/dist/src/Resources.d.ts.map +1 -0
- package/dist/src/Resources.js +197 -0
- package/dist/src/Result.d.ts +184 -52
- package/dist/src/Result.d.ts.map +1 -1
- package/dist/src/Result.js +30 -241
- package/dist/src/Skiplist.js +2 -1
- package/dist/src/Sqlite.d.ts +89 -5
- package/dist/src/Sqlite.d.ts.map +1 -1
- package/dist/src/Sqlite.js +136 -9
- package/dist/src/Task.d.ts +586 -0
- package/dist/src/Task.d.ts.map +1 -0
- package/dist/src/Task.js +469 -0
- package/dist/src/Time.d.ts +66 -1
- package/dist/src/Time.d.ts.map +1 -1
- package/dist/src/Time.js +99 -5
- package/dist/src/Type.d.ts +676 -343
- package/dist/src/Type.d.ts.map +1 -1
- package/dist/src/Type.js +718 -467
- package/dist/src/Types.d.ts +1 -75
- 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 -18
- 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 +8 -3
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +8 -3
- package/package.json +15 -14
- package/src/Array.ts +301 -19
- package/src/Assert.ts +0 -21
- package/src/Brand.ts +75 -0
- package/src/Buffer.ts +7 -7
- package/src/Cache.ts +85 -0
- package/src/Callbacks.ts +62 -22
- package/src/Console.ts +91 -11
- package/src/Crypto.ts +94 -90
- package/src/Evolu/Db.ts +519 -1026
- package/src/Evolu/Diff.ts +7 -5
- package/src/Evolu/Evolu.ts +477 -361
- package/src/Evolu/Internal.ts +0 -2
- package/src/Evolu/LocalAuth.ts +463 -0
- package/src/Evolu/Owner.ts +355 -228
- package/src/Evolu/Platform.ts +9 -9
- package/src/Evolu/Protocol.ts +842 -742
- package/src/Evolu/Public.ts +7 -14
- package/src/Evolu/PublicKysely.ts +4 -5
- package/src/Evolu/Query.ts +3 -2
- package/src/Evolu/Relay.ts +406 -103
- package/src/Evolu/Schema.ts +323 -91
- package/src/Evolu/Storage.ts +559 -137
- package/src/Evolu/Sync.ts +819 -36
- package/src/Evolu/Timestamp.ts +90 -58
- package/src/Identicon.ts +197 -0
- package/src/Instances.ts +90 -0
- package/src/Number.ts +6 -10
- package/src/Object.ts +13 -5
- package/src/Platform.ts +26 -0
- package/src/Random.ts +3 -2
- package/src/Relation.ts +234 -0
- package/src/Resources.ts +367 -0
- package/src/Result.ts +191 -54
- package/src/Skiplist.ts +1 -1
- package/src/Sqlite.ts +152 -17
- package/src/Task.ts +901 -0
- package/src/Time.ts +180 -5
- package/src/Type.ts +1135 -730
- package/src/Types.ts +1 -77
- package/src/WebSocket.ts +27 -25
- package/src/Worker.ts +72 -23
- package/src/index.ts +8 -3
- 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/ManyToManyMap.d.ts +0 -26
- package/dist/src/ManyToManyMap.d.ts.map +0 -1
- package/dist/src/ManyToManyMap.js +0 -92
- 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/Evolu/Config.ts +0 -83
- package/src/Evolu/Kysely.ts +0 -38
- package/src/ManyToManyMap.ts +0 -140
- package/src/NanoId.ts +0 -39
- package/src/Promise.ts +0 -295
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import { err, ok } from "./Result.js";
|
|
2
|
+
import { PositiveInt } from "./Type.js";
|
|
3
|
+
/**
|
|
4
|
+
* Creates {@link Resources}.
|
|
5
|
+
*
|
|
6
|
+
* This tracks which consumers are using which resources and maintains reference
|
|
7
|
+
* counts to know when it's safe to dispose resources. Resources are created
|
|
8
|
+
* on-demand and disposed with a configurable delay to avoid churn.
|
|
9
|
+
*
|
|
10
|
+
* ### Example Usage
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* // WebSocket connections
|
|
14
|
+
* interface WebSocketConfig {
|
|
15
|
+
* readonly url: WebSocketUrl;
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* type WebSocketUrl = string & Brand<"WebSocketUrl">;
|
|
19
|
+
* type UserId = string & Brand<"UserId">;
|
|
20
|
+
*
|
|
21
|
+
* const webSockets = createResources<
|
|
22
|
+
* WebSocket,
|
|
23
|
+
* WebSocketUrl,
|
|
24
|
+
* WebSocketConfig,
|
|
25
|
+
* User,
|
|
26
|
+
* UserId
|
|
27
|
+
* >({
|
|
28
|
+
* createResource: (config) => new WebSocket(config.url),
|
|
29
|
+
* getResourceKey: (config) => config.url,
|
|
30
|
+
* getConsumerId: (user) => user.id,
|
|
31
|
+
* disposalDelay: 1000,
|
|
32
|
+
* });
|
|
33
|
+
*
|
|
34
|
+
* // Add users to WebSocket connections
|
|
35
|
+
* webSockets.addConsumer(user1, [
|
|
36
|
+
* { url: "ws://server1.com" as WebSocketUrl },
|
|
37
|
+
* { url: "ws://server2.com" as WebSocketUrl },
|
|
38
|
+
* ]);
|
|
39
|
+
* webSockets.addConsumer(user2, [
|
|
40
|
+
* { url: "ws://server1.com" as WebSocketUrl },
|
|
41
|
+
* ]);
|
|
42
|
+
*
|
|
43
|
+
* // Remove users - server1 stays alive (user2 still using it)
|
|
44
|
+
* webSockets.removeConsumer(user1, [
|
|
45
|
+
* { url: "ws://server1.com" as WebSocketUrl },
|
|
46
|
+
* { url: "ws://server2.com" as WebSocketUrl },
|
|
47
|
+
* ]);
|
|
48
|
+
*
|
|
49
|
+
* // server2 gets disposed after delay, server1 stays alive
|
|
50
|
+
* ```
|
|
51
|
+
*/
|
|
52
|
+
export const createResources = (config) => {
|
|
53
|
+
let isDisposed = false;
|
|
54
|
+
const resourcesMap = new Map();
|
|
55
|
+
const consumerCounts = new Map();
|
|
56
|
+
const consumers = new Map();
|
|
57
|
+
const disposalTimeouts = new Map();
|
|
58
|
+
const disposalDelay = config.disposalDelay ?? 100;
|
|
59
|
+
const ensureResource = (resourceConfig) => {
|
|
60
|
+
const key = config.getResourceKey(resourceConfig);
|
|
61
|
+
const timeout = disposalTimeouts.get(key);
|
|
62
|
+
if (timeout) {
|
|
63
|
+
clearTimeout(timeout);
|
|
64
|
+
disposalTimeouts.delete(key);
|
|
65
|
+
}
|
|
66
|
+
if (!resourcesMap.has(key)) {
|
|
67
|
+
const resource = config.createResource(resourceConfig);
|
|
68
|
+
resourcesMap.set(key, resource);
|
|
69
|
+
}
|
|
70
|
+
};
|
|
71
|
+
const scheduleDisposal = (key) => {
|
|
72
|
+
const timeout = setTimeout(() => {
|
|
73
|
+
const resource = resourcesMap.get(key);
|
|
74
|
+
if (resource) {
|
|
75
|
+
resource[Symbol.dispose]();
|
|
76
|
+
resourcesMap.delete(key);
|
|
77
|
+
}
|
|
78
|
+
disposalTimeouts.delete(key);
|
|
79
|
+
}, disposalDelay);
|
|
80
|
+
disposalTimeouts.set(key, timeout);
|
|
81
|
+
};
|
|
82
|
+
const resources = {
|
|
83
|
+
addConsumer: (consumer, resourceConfigs) => {
|
|
84
|
+
if (isDisposed)
|
|
85
|
+
return;
|
|
86
|
+
const consumerId = config.getConsumerId(consumer);
|
|
87
|
+
// Store consumer (last added consumer for this ID)
|
|
88
|
+
consumers.set(consumerId, consumer);
|
|
89
|
+
for (const resourceConfig of resourceConfigs) {
|
|
90
|
+
ensureResource(resourceConfig);
|
|
91
|
+
const resourceKey = config.getResourceKey(resourceConfig);
|
|
92
|
+
let counts = consumerCounts.get(resourceKey);
|
|
93
|
+
if (!counts) {
|
|
94
|
+
counts = new Map();
|
|
95
|
+
consumerCounts.set(resourceKey, counts);
|
|
96
|
+
}
|
|
97
|
+
const currentCount = counts.get(consumerId) ?? 0;
|
|
98
|
+
const newCount = currentCount + 1;
|
|
99
|
+
counts.set(consumerId, PositiveInt.orThrow(newCount));
|
|
100
|
+
// Call onConsumerAdded callback only when consumer is added for the first time (0 -> 1)
|
|
101
|
+
if (currentCount === 0 && config.onConsumerAdded) {
|
|
102
|
+
const resource = resourcesMap.get(resourceKey);
|
|
103
|
+
if (resource) {
|
|
104
|
+
config.onConsumerAdded(consumer, resource, resourceKey);
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
},
|
|
109
|
+
removeConsumer: (consumer, resourceConfigs) => {
|
|
110
|
+
if (isDisposed)
|
|
111
|
+
return ok();
|
|
112
|
+
const consumerId = config.getConsumerId(consumer);
|
|
113
|
+
for (const resourceConfig of resourceConfigs) {
|
|
114
|
+
const key = config.getResourceKey(resourceConfig);
|
|
115
|
+
const counts = consumerCounts.get(key);
|
|
116
|
+
if (!counts) {
|
|
117
|
+
return err({ type: "ResourceNotFoundError", resourceKey: key });
|
|
118
|
+
}
|
|
119
|
+
const currentCount = counts.get(consumerId);
|
|
120
|
+
if (currentCount == null) {
|
|
121
|
+
return err({
|
|
122
|
+
type: "ConsumerNotFoundError",
|
|
123
|
+
consumerId: consumerId,
|
|
124
|
+
resourceKey: key,
|
|
125
|
+
});
|
|
126
|
+
}
|
|
127
|
+
if (currentCount === 1) {
|
|
128
|
+
counts.delete(consumerId);
|
|
129
|
+
// Call onConsumerRemoved callback only when consumer is completely removed (1 -> 0)
|
|
130
|
+
if (config.onConsumerRemoved) {
|
|
131
|
+
const resource = resourcesMap.get(key);
|
|
132
|
+
if (resource) {
|
|
133
|
+
config.onConsumerRemoved(consumer, resource, key);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
if (counts.size === 0) {
|
|
137
|
+
consumerCounts.delete(key);
|
|
138
|
+
scheduleDisposal(key);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
else {
|
|
142
|
+
counts.set(consumerId, PositiveInt.orThrow(currentCount - 1));
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
if (!resources.hasConsumerAnyResource(consumer)) {
|
|
146
|
+
consumers.delete(consumerId);
|
|
147
|
+
}
|
|
148
|
+
return ok();
|
|
149
|
+
},
|
|
150
|
+
getResource: (key) => {
|
|
151
|
+
if (isDisposed)
|
|
152
|
+
return null;
|
|
153
|
+
return resourcesMap.get(key) ?? null;
|
|
154
|
+
},
|
|
155
|
+
getConsumersForResource: (key) => {
|
|
156
|
+
if (isDisposed)
|
|
157
|
+
return [];
|
|
158
|
+
const counts = consumerCounts.get(key);
|
|
159
|
+
return counts ? Array.from(counts.keys()) : [];
|
|
160
|
+
},
|
|
161
|
+
hasConsumerAnyResource: (consumer) => {
|
|
162
|
+
if (isDisposed)
|
|
163
|
+
return false;
|
|
164
|
+
const consumerId = config.getConsumerId(consumer);
|
|
165
|
+
// If slow, can be optimized with reverse index
|
|
166
|
+
return Array.from(consumerCounts.values()).some((counts) => counts.has(consumerId));
|
|
167
|
+
},
|
|
168
|
+
getConsumer: (consumerId) => {
|
|
169
|
+
if (isDisposed)
|
|
170
|
+
return null;
|
|
171
|
+
const consumer = consumers.get(consumerId);
|
|
172
|
+
if (!consumer)
|
|
173
|
+
return null;
|
|
174
|
+
// Only return consumer if it's currently using any resources
|
|
175
|
+
if (!resources.hasConsumerAnyResource(consumer)) {
|
|
176
|
+
return null;
|
|
177
|
+
}
|
|
178
|
+
return consumer;
|
|
179
|
+
},
|
|
180
|
+
[Symbol.dispose]: () => {
|
|
181
|
+
if (isDisposed)
|
|
182
|
+
return;
|
|
183
|
+
isDisposed = true;
|
|
184
|
+
for (const timeout of disposalTimeouts.values()) {
|
|
185
|
+
clearTimeout(timeout);
|
|
186
|
+
}
|
|
187
|
+
disposalTimeouts.clear();
|
|
188
|
+
for (const resource of resourcesMap.values()) {
|
|
189
|
+
resource[Symbol.dispose]();
|
|
190
|
+
}
|
|
191
|
+
resourcesMap.clear();
|
|
192
|
+
consumerCounts.clear();
|
|
193
|
+
consumers.clear();
|
|
194
|
+
},
|
|
195
|
+
};
|
|
196
|
+
return resources;
|
|
197
|
+
};
|
package/dist/src/Result.d.ts
CHANGED
|
@@ -1,36 +1,19 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* 🛡️ Type-safe errors
|
|
3
3
|
*
|
|
4
|
-
* ## Intro
|
|
5
|
-
*
|
|
6
4
|
* The problem with throwing an exception in JavaScript is that the caught error
|
|
7
5
|
* is always of an unknown type. The unknown type is a problem because we can't
|
|
8
6
|
* be sure all errors have been handled because the TypeScript compiler can't
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* Some other languages like Rust 🦀 or Haskell 📚 use a type-safe approach to
|
|
12
|
-
* error handling, where errors are explicitly represented as part of the return
|
|
13
|
-
* type, such as Result or Either, allowing the developer to handle all errors
|
|
14
|
-
* safely. ✅
|
|
15
|
-
*
|
|
16
|
-
* ✨ Evolu uses {@link Result}, and it looks like this:
|
|
7
|
+
* tell us.
|
|
17
8
|
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
* readonly ok: true;
|
|
23
|
-
* readonly value: T;
|
|
24
|
-
* }
|
|
9
|
+
* Languages like Rust 🦀 or Haskell 📚 use a type-safe approach to error
|
|
10
|
+
* handling, where errors are explicitly represented as part of the return type,
|
|
11
|
+
* such as Result or Either, allowing the developer to handle errors safely.
|
|
12
|
+
* TypeScript can have this too via the `Result` type.
|
|
25
13
|
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
* }
|
|
30
|
-
*
|
|
31
|
-
* const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
|
|
32
|
-
* const err = <E>(error: E): Err<E> => ({ ok: false, error });
|
|
33
|
-
* ```
|
|
14
|
+
* The `Result` type can be either {@link Ok} (success) or {@link Err} (error).
|
|
15
|
+
* Use {@link ok} to create a successful result and {@link err} to create an error
|
|
16
|
+
* result.
|
|
34
17
|
*
|
|
35
18
|
* Now let's look at how `Result` can be used for safe JSON parsing:
|
|
36
19
|
*
|
|
@@ -77,12 +60,10 @@
|
|
|
77
60
|
*
|
|
78
61
|
* Let's summarize it:
|
|
79
62
|
*
|
|
80
|
-
* - For
|
|
63
|
+
* - For safe code, use `ok` and `err`.
|
|
81
64
|
* - For unsafe code, use `trySync` or `tryAsync`.
|
|
82
|
-
* - For asynchronous safe code, use `Promise` with {@link Result}.
|
|
83
65
|
*
|
|
84
|
-
* Asynchronous safe (because of a Promise using Result) code
|
|
85
|
-
* straightforward:
|
|
66
|
+
* Asynchronous safe (because of a Promise using Result) code:
|
|
86
67
|
*
|
|
87
68
|
* ```ts
|
|
88
69
|
* const fetchUser = async (
|
|
@@ -103,9 +84,40 @@
|
|
|
103
84
|
* };
|
|
104
85
|
* ```
|
|
105
86
|
*
|
|
106
|
-
*
|
|
87
|
+
* ### Naming Convention
|
|
88
|
+
*
|
|
89
|
+
* - For values: `const user = getUser()`
|
|
90
|
+
* - For a single void operation: `const result = foo()`
|
|
91
|
+
* - For multiple void operations: use descriptive names for all
|
|
92
|
+
*
|
|
93
|
+
* ```ts
|
|
94
|
+
* const processUser = () => {
|
|
95
|
+
* // we have a value
|
|
96
|
+
* const user = getUser();
|
|
97
|
+
* if (!user.ok) return user;
|
|
98
|
+
*
|
|
99
|
+
* // single void operation
|
|
100
|
+
* const result = saveToDatabase(user.value);
|
|
101
|
+
* if (!result.ok) return result;
|
|
102
|
+
*
|
|
103
|
+
* return ok();
|
|
104
|
+
* };
|
|
105
|
+
*
|
|
106
|
+
* const setupDatabase = () => {
|
|
107
|
+
* // multiple void operations - use descriptive names
|
|
108
|
+
* const baseTables = createBaseTables();
|
|
109
|
+
* if (!baseTables.ok) return baseTables;
|
|
110
|
+
*
|
|
111
|
+
* const relayTables = createRelayTables();
|
|
112
|
+
* if (!relayTables.ok) return relayTables;
|
|
113
|
+
*
|
|
114
|
+
* return ok();
|
|
115
|
+
* };
|
|
116
|
+
* ```
|
|
117
|
+
*
|
|
118
|
+
* ### Examples
|
|
107
119
|
*
|
|
108
|
-
*
|
|
120
|
+
* #### Sequential Operations with Short-Circuiting
|
|
109
121
|
*
|
|
110
122
|
* When performing a sequence of operations where any failure should stop
|
|
111
123
|
* further processing, use the `Result` type with early returns.
|
|
@@ -155,37 +167,127 @@
|
|
|
155
167
|
* This approach ensures type-safe error handling, avoids nested try/catch
|
|
156
168
|
* blocks, and clearly communicates the control flow.
|
|
157
169
|
*
|
|
158
|
-
*
|
|
170
|
+
* #### A function with two different errors:
|
|
159
171
|
*
|
|
160
172
|
* ```ts
|
|
161
173
|
* const example = (value: string): Result<number, FooError | BarError> => {
|
|
162
174
|
* const foo = getFoo(value);
|
|
163
175
|
* if (!foo.ok) return foo;
|
|
164
176
|
*
|
|
165
|
-
* const bar =
|
|
177
|
+
* const bar = getBar(foo.value);
|
|
166
178
|
* if (!bar.ok) return bar;
|
|
167
179
|
*
|
|
168
180
|
* return ok(barToNumber(bar.value));
|
|
169
181
|
* };
|
|
170
182
|
* ```
|
|
171
183
|
*
|
|
172
|
-
*
|
|
184
|
+
* ### Handling Unexpected Errors
|
|
185
|
+
*
|
|
186
|
+
* Even with disciplined use of `trySync` and `tryAsync`, unexpected errors can
|
|
187
|
+
* still occur due to programming mistakes, third-party library bugs, or edge
|
|
188
|
+
* cases. These should be logged for debugging, but **unexpected errors are not
|
|
189
|
+
* recoverable** - they represent bugs that must be fixed.
|
|
190
|
+
*
|
|
191
|
+
* **Important**: "Graceful shutdown" and error recovery can only come from
|
|
192
|
+
* expected errors handled via the `Result` type. Unexpected errors should fail
|
|
193
|
+
* fast - the operation fails immediately and the error bubbles up.
|
|
194
|
+
*
|
|
195
|
+
* #### In Browser Environments
|
|
196
|
+
*
|
|
197
|
+
* ```ts
|
|
198
|
+
* // Global error handler for unexpected errors
|
|
199
|
+
* window.addEventListener("error", (event) => {
|
|
200
|
+
* console.error("Uncaught error:", event.error);
|
|
201
|
+
* // Send to error reporting service
|
|
202
|
+
* errorReportingService.report(event.error);
|
|
203
|
+
* });
|
|
204
|
+
*
|
|
205
|
+
* // For unhandled promise rejections
|
|
206
|
+
* window.addEventListener("unhandledrejection", (event) => {
|
|
207
|
+
* console.error("Unhandled promise rejection:", event.reason);
|
|
208
|
+
* errorReportingService.report(event.reason);
|
|
209
|
+
* });
|
|
210
|
+
* ```
|
|
211
|
+
*
|
|
212
|
+
* #### In Node.js Environments
|
|
213
|
+
*
|
|
214
|
+
* ```ts
|
|
215
|
+
* // Handle uncaught exceptions - log and fail fast
|
|
216
|
+
* process.on("uncaughtException", (error) => {
|
|
217
|
+
* console.error("Uncaught exception:", error);
|
|
218
|
+
* errorReportingService.report(error);
|
|
219
|
+
* // Exit immediately - unexpected errors are not recoverable
|
|
220
|
+
* process.exit(1);
|
|
221
|
+
* });
|
|
222
|
+
*
|
|
223
|
+
* // Handle unhandled promise rejections
|
|
224
|
+
* process.on("unhandledRejection", (reason) => {
|
|
225
|
+
* console.error("Unhandled promise rejection:", reason);
|
|
226
|
+
* errorReportingService.report(reason);
|
|
227
|
+
* });
|
|
228
|
+
* ```
|
|
229
|
+
*
|
|
230
|
+
* These global handlers serve as a safety net to log and report unexpected
|
|
231
|
+
* errors for debugging purposes. They do not attempt recovery - unexpected
|
|
232
|
+
* errors represent bugs that must be fixed. The discipline of explicit error
|
|
233
|
+
* handling through the `Result` pattern remains the primary approach for all
|
|
234
|
+
* recoverable scenarios.
|
|
173
235
|
*
|
|
174
|
-
* ###
|
|
236
|
+
* ### FAQ
|
|
237
|
+
*
|
|
238
|
+
* #### When should a function return a plain value instead of `Result<T, E>`?
|
|
239
|
+
*
|
|
240
|
+
* Use `Result<T, E>` only when a function can fail with **known, expected
|
|
241
|
+
* errors** that callers need to handle. If a function cannot fail with a known
|
|
242
|
+
* error, return the value directly.
|
|
243
|
+
*
|
|
244
|
+
* - ✅ Return `Result<User, UserNotFoundError>` - can fail with a known error
|
|
245
|
+
* - ✅ Return `User` - cannot fail with a known error
|
|
246
|
+
* - ❌ Don't return `Result<User, never>` - unnecessary wrapper
|
|
247
|
+
*
|
|
248
|
+
* This keeps the codebase clean and makes error handling intentional. The type
|
|
249
|
+
* system communicates which operations can fail and which cannot.
|
|
250
|
+
*
|
|
251
|
+
* Unsafe code from external libraries (not under our control) should be wrapped
|
|
252
|
+
* with `trySync` or `tryAsync` at the boundaries. Once wrapped, if the error is
|
|
253
|
+
* not important to callers, functions can safely return plain values. If the
|
|
254
|
+
* error matters, use `Result` with a typed error.
|
|
255
|
+
*
|
|
256
|
+
* ```ts
|
|
257
|
+
* // ✅ Safe to return void - unsafe code is wrapped and error is handled
|
|
258
|
+
* const processData = (data: string): void => {
|
|
259
|
+
* const parseResult = trySync(
|
|
260
|
+
* () => JSON.parse(data),
|
|
261
|
+
* (error) => ({ type: "ParseError", message: String(error) }),
|
|
262
|
+
* );
|
|
263
|
+
*
|
|
264
|
+
* if (!parseResult.ok) {
|
|
265
|
+
* logError(parseResult.error);
|
|
266
|
+
* return;
|
|
267
|
+
* }
|
|
268
|
+
*
|
|
269
|
+
* // Continue with safe operations...
|
|
270
|
+
* };
|
|
271
|
+
*
|
|
272
|
+
* // ✅ Can call without try-catch since it returns void
|
|
273
|
+
* processData(jsonString);
|
|
274
|
+
* ```
|
|
275
|
+
*
|
|
276
|
+
* #### What if my function doesn't return a value on success?
|
|
175
277
|
*
|
|
176
278
|
* If your function performs an operation but doesn't need to return a value on
|
|
177
279
|
* success, you can use `Result<void, E>`. Using `Result<void, E>` is clearer
|
|
178
280
|
* than using `Result<true, E>` or `Result<null, E>` because it communicates
|
|
179
281
|
* that the function doesn't produce a value but can produce errors.
|
|
180
282
|
*
|
|
181
|
-
*
|
|
283
|
+
* #### How do I short-circuit processing of an array on the first error?
|
|
182
284
|
*
|
|
183
285
|
* If you want to stop processing as soon as an error occurs (short-circuit),
|
|
184
286
|
* you should produce and check each `Result` inside a loop:
|
|
185
287
|
*
|
|
186
288
|
* ```ts
|
|
187
289
|
* for (const query of [
|
|
188
|
-
* sql`drop table
|
|
290
|
+
* sql`drop table evolu_config;`,
|
|
189
291
|
* sql`drop table evolu_message;`,
|
|
190
292
|
* ]) {
|
|
191
293
|
* const result = deps.sqlite.exec(query);
|
|
@@ -194,12 +296,11 @@
|
|
|
194
296
|
* // All queries succeeded
|
|
195
297
|
* ```
|
|
196
298
|
*
|
|
197
|
-
*
|
|
299
|
+
* #### How do I handle an array of operations and short-circuit on the first error?
|
|
198
300
|
*
|
|
199
301
|
* If you have an array of operations (not results), you should make them
|
|
200
|
-
* _lazy_—that is, represent each operation as a function
|
|
201
|
-
*
|
|
202
|
-
* stop on the first error:
|
|
302
|
+
* _lazy_—that is, represent each operation as a function. This way, you only
|
|
303
|
+
* execute each operation as needed, and can stop on the first error:
|
|
203
304
|
*
|
|
204
305
|
* ```ts
|
|
205
306
|
* import type { LazyValue } from "./Function";
|
|
@@ -232,16 +333,7 @@
|
|
|
232
333
|
* above) over monadic helpers. Imperative code is generally more readable,
|
|
233
334
|
* easier to debug, and more familiar to most JavaScript and TypeScript
|
|
234
335
|
* developers. While monads and functional helpers can be powerful, they often
|
|
235
|
-
* obscure control flow and make debugging harder.
|
|
236
|
-
* handling explicit and straightforward.
|
|
237
|
-
*
|
|
238
|
-
* @module
|
|
239
|
-
*/
|
|
240
|
-
/**
|
|
241
|
-
* A `Result` can be either {@link Ok} (success) or {@link Err} (error).
|
|
242
|
-
*
|
|
243
|
-
* Use {@link ok} to create a successful result and {@link err} to create an error
|
|
244
|
-
* result.
|
|
336
|
+
* obscure control flow and make debugging harder.
|
|
245
337
|
*/
|
|
246
338
|
export type Result<T, E> = Ok<T> | Err<E>;
|
|
247
339
|
/** A successful {@link Result}. */
|
|
@@ -297,6 +389,18 @@ export interface Err<E> {
|
|
|
297
389
|
readonly ok: false;
|
|
298
390
|
readonly error: E;
|
|
299
391
|
}
|
|
392
|
+
/**
|
|
393
|
+
* Extracts the value type from a {@link Result}.
|
|
394
|
+
*
|
|
395
|
+
* @category Utilities
|
|
396
|
+
*/
|
|
397
|
+
export type InferOk<R extends Result<any, any>> = R extends Ok<infer T> ? T : never;
|
|
398
|
+
/**
|
|
399
|
+
* Extracts the error type from a {@link Result}.
|
|
400
|
+
*
|
|
401
|
+
* @category Utilities
|
|
402
|
+
*/
|
|
403
|
+
export type InferErr<R extends Result<any, any>> = R extends Err<infer E> ? E : never;
|
|
300
404
|
/**
|
|
301
405
|
* Creates an {@link Ok} result.
|
|
302
406
|
*
|
|
@@ -346,8 +450,33 @@ export declare const err: <E>(error: E) => Err<E>;
|
|
|
346
450
|
* const config = getOrThrow(loadConfig());
|
|
347
451
|
* // Safe to use config here
|
|
348
452
|
* ```
|
|
453
|
+
*
|
|
454
|
+
* Throws: `Error` with the original error attached as `cause`.
|
|
349
455
|
*/
|
|
350
456
|
export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
|
|
457
|
+
/**
|
|
458
|
+
* Extracts the value from a {@link Result} if it is an `Ok`, or returns `null`
|
|
459
|
+
* if it is an `Err`.
|
|
460
|
+
*
|
|
461
|
+
* **Intended usage:**
|
|
462
|
+
*
|
|
463
|
+
* - When you need to convert a `Result` to a nullable value for APIs that expect
|
|
464
|
+
* `T | null`.
|
|
465
|
+
* - When the error is not important and you just want the value or nothing.
|
|
466
|
+
*
|
|
467
|
+
* ### Example
|
|
468
|
+
*
|
|
469
|
+
* ```ts
|
|
470
|
+
* const parseResult = parseJson('{"key": "value"}');
|
|
471
|
+
* const value = getOrNull(parseResult);
|
|
472
|
+
* // value is unknown | null
|
|
473
|
+
*
|
|
474
|
+
* if (value != null) {
|
|
475
|
+
* console.log("Parsed value:", value);
|
|
476
|
+
* }
|
|
477
|
+
* ```
|
|
478
|
+
*/
|
|
479
|
+
export declare const getOrNull: <T, E>(result: Result<T, E>) => T | null;
|
|
351
480
|
/**
|
|
352
481
|
* Wraps synchronous functions that may throw exceptions, returning a
|
|
353
482
|
* {@link Result}.
|
|
@@ -368,7 +497,10 @@ export declare const getOrThrow: <T, E>(result: Result<T, E>) => T;
|
|
|
368
497
|
* const parseJson = (value: string): Result<unknown, ParseJsonError> =>
|
|
369
498
|
* trySync(
|
|
370
499
|
* () => JSON.parse(value) as unknown,
|
|
371
|
-
* (error)
|
|
500
|
+
* (error): ParseJsonError => ({
|
|
501
|
+
* type: "ParseJsonError",
|
|
502
|
+
* message: String(error),
|
|
503
|
+
* }),
|
|
372
504
|
* );
|
|
373
505
|
* ```
|
|
374
506
|
*/
|
package/dist/src/Result.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"Result.d.ts","sourceRoot":"","sources":["../../src/Result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgVG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAE1C,mCAAmC;AACnC,MAAM,WAAW,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC5C,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAC7C,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/B,2DAA2D;AAC3D,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAKvC;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,GAAG,CAAC,CAAC,CAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAMvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,GAAG,IAC1B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAC1B,IAAI,MAAM,CAAC,EACX,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,MAAM,CAAC,CAAC,EAAE,CAAC,CAMb,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAIpB,CAAC"}
|