Update Result docs with block scope pattern

Author: steida

.changeset/silver-jars-smell.md

@@ -0,0 +1,24 @@
+---
+"@evolu/common": patch
+---
+
+Update Result documentation with block scope pattern for multiple void operations
+
+```ts
+// Before - inventing names to avoid name clash
+const baseTables = createBaseSqliteStorageTables(deps);
+if (!baseTables.ok) return baseTables;
+
+const relayTables = createRelayStorageTables(deps);
+if (!relayTables.ok) return relayTables;
+
+// After - block scopes avoid name clash
+{
+  const result = createBaseSqliteStorageTables(deps);
+  if (!result.ok) return result;
+}
+{
+  const result = createRelayStorageTables(deps);
+  if (!result.ok) return result;
+}
+```

.github/copilot-instructions.md

@@ -112,13 +112,10 @@ const parseJson = (value: string): Result<unknown, ParseJsonError> =>
 
 // ✅ Good - Sequential operations with short-circuiting
 const processData = (deps: DataDeps) => {
-  const step1Result = doStep1(deps);
-  if (!step1Result.ok) return step1Result;
+  const foo = doFoo(deps);
+  if (!foo.ok) return foo;
 
-  const step2Result = doStep2(deps)(step1Result.value);
-  if (!step2Result.ok) return step2Result;
-
-  return ok(step2Result.value);
+  return doStep2(deps)(foo.value);
 };
 
 // ❌ Avoid - Implementation error in public API

packages/common/src/Result.ts

@@ -1,3 +1,5 @@
+import type { Task } from "./Task.js";
+
 /**
  * The problem with throwing an exception in JavaScript is that the caught error
  * is always of an unknown type. The unknown type is a problem because we can't
@@ -82,32 +84,38 @@
  * };
  * ```
  *
+ * For lazy, cancellable async operations, see {@link Task}.
+ *
  * ### Naming convention
  *
- * - For values: `const user = getUser()`
- * - For a single void operation: `const result = foo()`
- * - For multiple void operations: use descriptive names for all
+ * - **For values you need:** use a name without Result suffix (`user`, `config`)
+ * - **For void operations:** use `result` (no value to name)
+ *
+ * For multiple void operations, use block scopes to avoid potentially long
+ * names like `createBaseTablesResult`, `createRelayTablesResult`, or counters
+ * like `result1`, `result2`:
  *
  * ```ts
  * const processUser = () => {
- *   // we have a value
  *   const user = getUser();
  *   if (!user.ok) return user;
  *
- *   // single void operation
  *   const result = saveToDatabase(user.value);
  *   if (!result.ok) return result;
  *
  *   return ok();
  * };
  *
  * const setupDatabase = () => {
- *   // multiple void operations - use descriptive names
- *   const baseTables = createBaseTables();
- *   if (!baseTables.ok) return baseTables;
- *
- *   const relayTables = createRelayTables();
- *   if (!relayTables.ok) return relayTables;
+ *   // Multiple void operations - use block scopes to avoid name clash
+ *   {
+ *     const result = createBaseTables();
+ *     if (!result.ok) return result;
+ *   }
+ *   {
+ *     const result = createRelayTables();
+ *     if (!result.ok) return result;
+ *   }
  *
  *   return ok();
  * };
@@ -124,30 +132,31 @@
  * schema, and initializes the database, stopping on the first error:
  *
  * ```ts
- * const resetResult = deps.sqlite.transaction(() => {
- *   const dropAllTablesResult = dropAllTables(deps);
- *   if (!dropAllTablesResult.ok) return dropAllTablesResult;
+ * const result = deps.sqlite.transaction(() => {
+ *   const result = dropAllTables(deps);
+ *   if (!result.ok) return result;
  *
  *   if (message.restore) {
  *     const dbSchema = getDbSchema(deps)();
  *     if (!dbSchema.ok) return dbSchema;
  *
- *     const ensureDbSchemaResult = ensureDbSchema(deps)(
- *       message.restore.dbSchema,
- *       dbSchema.value,
- *     );
- *     if (!ensureDbSchemaResult.ok) return ensureDbSchemaResult;
- *
- *     const initializeDbResult = initializeDb(deps)(
- *       message.restore.mnemonic,
- *     );
- *     if (!initializeDbResult.ok) return initializeDbResult;
+ *     {
+ *       const result = ensureDbSchema(deps)(
+ *         message.restore.dbSchema,
+ *         dbSchema.value,
+ *       );
+ *       if (!result.ok) return result;
+ *     }
+ *     {
+ *       const result = initializeDb(deps)(message.restore.mnemonic);
+ *       if (!result.ok) return result;
+ *     }
  *   }
  *   return ok();
  * });
  *
- * if (!resetResult.ok) {
- *   deps.postMessage({ type: "onError", error: resetResult.error });
+ * if (!result.ok) {
+ *   deps.postMessage({ type: "onError", error: result.error });
  *   return;
  * }
  * ```
@@ -254,13 +263,13 @@
  * ```ts
  * // ✅ Safe to return void - unsafe code is wrapped and error is handled
  * const processData = (data: string): void => {
- *   const parseResult = trySync(
+ *   const result = trySync(
  *     () => JSON.parse(data),
  *     (error) => ({ type: "ParseError", message: String(error) }),
  *   );
  *
- *   if (!parseResult.ok) {
- *     logError(parseResult.error);
+ *   if (!result.ok) {
+ *     logError(result.error);
  *     return;
  *   }
  *

packages/common/src/Task.ts

@@ -570,10 +570,12 @@ export const retry = <T, E>(
       }
 
       // Wait before retry
-      const delayResult = await wait(NonNegativeInt.orThrow(delay))(context);
-      if (!delayResult.ok) {
-        // If delay was aborted, return AbortError (will be handled by toTask)
-        return delayResult;
+      {
+        const result = await wait(NonNegativeInt.orThrow(delay))(context);
+        if (!result.ok) {
+          // If delay was aborted, return AbortError (will be handled by toTask)
+          return result;
+        }
       }
     }
   });

packages/common/src/local-first/Protocol.ts

@@ -972,12 +972,9 @@ export const applyProtocolMessageAsClient =
       const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
       if (isNonEmptyReadonlyArray(messages)) {
-        const writeResult = await deps.storage.writeMessages(
-          ownerIdBytes,
-          messages,
-        );
+        const result = await deps.storage.writeMessages(ownerIdBytes, messages);
         // Errors are handled by the Storage. Here we just stop syncing.
-        if (!writeResult.ok) return ok({ type: "no-response" });
+        if (!result.ok) return ok({ type: "no-response" });
       }
 
       // Now: No writeKey, no sync.
@@ -1006,10 +1003,10 @@ export const applyProtocolMessageAsClient =
         rangesMaxSize: options.rangesMaxSize,
       });
 
-      const syncResult = sync(deps)(ranges, output, ownerIdBytes);
+      const result = sync(deps)(ranges, output, ownerIdBytes);
 
       // Client sync error (handled via Storage) or no changes.
-      if (!syncResult.ok || !syncResult.value) {
+      if (!result.ok || !result.value) {
         return ok({ type: "no-response" });
       }
 
@@ -1126,14 +1123,11 @@ export const applyProtocolMessageAsRelay =
           });
         }
 
-        const writeResult = await deps.storage.writeMessages(
-          ownerIdBytes,
-          messages,
-        );
+        const result = await deps.storage.writeMessages(ownerIdBytes, messages);
 
-        if (!writeResult.ok) {
+        if (!result.ok) {
           const errorCode =
-            writeResult.error.type === "StorageWriteError"
+            result.error.type === "StorageWriteError"
               ? ProtocolErrorCode.WriteError
               : ProtocolErrorCode.QuotaError;
           const message = createProtocolMessageBuffer(ownerId, {
@@ -1189,13 +1183,13 @@ export const applyProtocolMessageAsRelay =
         return ok({ type: "response", message: output.unwrap() });
       }
 
-      const syncResult = sync(deps)(ranges, output, ownerIdBytes);
+      const result = sync(deps)(ranges, output, ownerIdBytes);
 
-      const message = syncResult.ok
+      const message = result.ok
         ? output.unwrap()
         : createProtocolMessageBuffer(ownerId, {
             messageType: MessageType.Response,
-            errorCode: syncResult.error,
+            errorCode: result.error,
           }).unwrap();
 
       // Non-initiators always respond to provide sync completion feedback,

packages/common/src/local-first/Relay.ts

@@ -217,13 +217,8 @@ export const createRelaySqliteStorage =
               (storedBytes ?? 0) + incomingBytes,
             );
 
-            const withinQuotaResult = config.isOwnerWithinQuota(
-              ownerId,
-              newStoredBytes,
-            );
-            const isWithinQuota = isAsync(withinQuotaResult)
-              ? await withinQuotaResult
-              : withinQuotaResult;
+            const result = config.isOwnerWithinQuota(ownerId, newStoredBytes);
+            const isWithinQuota = isAsync(result) ? await result : result;
             if (!isWithinQuota) {
               return err({ type: "StorageQuotaError", ownerId });
             }
@@ -240,30 +235,31 @@ export const createRelaySqliteStorage =
                     lastTimestamp,
                   );
 
-                const insertTimestampResult = sqliteStorageBase.insertTimestamp(
-                  ownerIdBytes,
-                  timestamp,
-                  strategy,
-                );
-                if (!insertTimestampResult.ok) return insertTimestampResult;
-
-                const insertMessage = deps.sqlite.exec(sql`
-                  insert into evolu_message ("ownerId", "timestamp", "change")
-                  values (${ownerIdBytes}, ${timestamp}, ${change})
-                  on conflict do nothing;
-                `);
-                if (!insertMessage.ok) return insertMessage;
+                {
+                  const result = sqliteStorageBase.insertTimestamp(
+                    ownerIdBytes,
+                    timestamp,
+                    strategy,
+                  );
+                  if (!result.ok) return result;
+                }
+
+                {
+                  const result = deps.sqlite.exec(sql`
+                    insert into evolu_message ("ownerId", "timestamp", "change")
+                    values (${ownerIdBytes}, ${timestamp}, ${change})
+                    on conflict do nothing;
+                  `);
+                  if (!result.ok) return result;
+                }
               }
 
-              const updateUsage = updateOwnerUsage(deps)(
+              return updateOwnerUsage(deps)(
                 ownerIdBytes,
                 newStoredBytes,
                 firstTimestamp,
                 lastTimestamp,
               );
-              if (!updateUsage.ok) return updateUsage;
-
-              return ok();
             });
           })();
 

packages/nodejs/src/local-first/Relay.ts

@@ -87,11 +87,14 @@ const createNodeJsRelayWithDeps =
     const depsWithSqlite = { ...deps, sqlite: sqlite.value };
 
     if (!dbFileExists) {
-      const baseTables = createBaseSqliteStorageTables(depsWithSqlite);
-      if (!baseTables.ok) return baseTables;
-
-      const relayTables = createRelayStorageTables(depsWithSqlite);
-      if (!relayTables.ok) return relayTables;
+      {
+        const result = createBaseSqliteStorageTables(depsWithSqlite);
+        if (!result.ok) return result;
+      }
+      {
+        const result = createRelayStorageTables(depsWithSqlite);
+        if (!result.ok) return result;
+      }
     }
 
     const storage = createRelaySqliteStorage(depsWithSqlite)({