Merge pull request #111 from mathesar-foundation/rpc_client

RPC client plans

docs/projects/2024/architecture-transition/rpc-client.md

@@ -0,0 +1,103 @@
+# JSON-RPC client plans
+
+## Examples of how the API would be called
+
+### Non-batched
+
+```ts
+/** @type {ApiRequest<Spacecraft>>} */
+const request = api.spacecrafts.get({ id: 42 });
+
+/** @type {CancellablePromise<Spacecraft>} */
+const promise = request.run();
+
+/** @type {Spacecraft} */
+const spacecraft = await promise; // Might throw!
+```
+
+### Batched
+
+```ts
+/** @type {[ApiResult<Spacecraft>, ApiResult<Voyage>]} */
+const [spacecraftResult, voyageResult] = await batchSend(
+ api.spacecrafts.get({ id: 42 }),
+ api.voyages.get({ id: 100 }),
+);
+
+/** @type {Spacecraft} */
+const spacecraft = spacecraftResult.unwrap(); // Might throw!
+
+/** @type {Voyage} */
+const voyage = voyageResult.unwrap(); // Might throw!
+```
+
+## Lower-level types
+
+_(Some of these would actually be **classes**, but the type defs written below give you a rough idea of how they would work.)_
+
+### ApiResult
+
+```ts
+interface ApiOk<T> {
+ status: 'ok';
+ value: T;
+}
+
+interface ApiError {
+ status: 'error';
+ code: number;
+ message: string;
+ data?: unknown;
+}
+
+type ApiResult<T> = ApiOk<T> | ApiError;
+```
+
+### ApiRequest
+
+```ts
+class ApiRequest<T> {
+ /**
+ * The simplest, most common way to run an API request.
+ *
+ * @throws `ApiError` when awaited if any errors are encountered.
+ */
+ run(): CancellablePromise<T> {
+ throw Error('Not yet implemented');
+ }
+
+ /**
+ * Provides more fine-grained control instead of `run` by returning
+ * ApiResult which can be type-narrowed manually.
+ *
+ * Will not reject or throw errors.
+ */
+ send(): CancellablePromise<ApiResult<T>> {
+ throw Error('Not yet implemented');
+ }
+}
+```
+
+## Error handling
+
+### Error handling with try/catch
+
+```ts
+try {
+ const spacecraft = await api.spacecrafts.get({ id: 42 }).run();
+ toast.success(spacecraft.name);
+} catch (e) {
+ toast.error(getErrorMessage(e));
+}
+```
+
+### Error handling with `match`
+
+```ts
+match(await api.spacecrafts.get({ id: 42 }).send(), 'status', {
+ ok: ({ value: spacecraft }) => toast.success(spacecraft.name),
+ error: ({ message }) => toast.error(message),
+});
+```
+
+(I already implemented this `match` function in #3037 [here](https://github.com/mathesar-foundation/mathesar/blob/4f2a253cc8c83a1bd231ae2158b31fbb4c1c4097/mathesar_ui/src/utils/patternMatching.ts#L29).)