chore: runner cleanups, mostly renaming "cell" to "doc" when the code is about docs (#499)

* remove duplicate code from query-result-proxy
* moved scheduler's utilities to scheduler
* rename `cell` to `doc` where appropriate
* renamed cell-map to doc-map
* rename cell-map to doc-map
* more renaming of `cell` to `doc`

Author: seefeldb

typescript/packages/common-cli/charm_test.ts

@@ -1,35 +1,41 @@
 /**
- * @file This file is Ellyse's exploration into the interactions between 
- * charms, cells, and documents, and how they relate to common memory. 
+ * @file This file is Ellyse's exploration into the interactions between
+ * charms, cells, and documents, and how they relate to common memory.
  *
  * I'm starting from the bottom (common memory) up and purposely calling
  * APIs that would normally call into common memory.
- *
  */
-import { CharmManager, Charm } from "../common-charm/src/charm.ts";
+import { Charm, CharmManager } from "../common-charm/src/charm.ts";
 import { Cell } from "../common-runner/src/cell.ts";
 import { DocImpl, getDoc } from "../common-runner/src/doc.ts";
-import { EntityId } from "../common-runner/src/cell-map.ts";
+import { EntityId } from "../common-runner/src/doc-map.ts";
 import { storage } from "../common-charm/src/storage.ts";
 import { getSpace, Space } from "../common-runner/src/space.ts";
 
 const replica = "ellyse7";
 const TOOLSHED_API_URL = "https://toolshed.saga-castor.ts.net/";
 
 // simple log function
-const log: <T>(s: T, prefix?: string) => void = (s, prefix?) => 
-  console.log("-------------\n" + (prefix ? prefix : "") + ":\n" + JSON.stringify(s, null, 2));
+const log: <T>(s: T, prefix?: string) => void = (s, prefix?) =>
+  console.log(
+    "-------------\n" + (prefix ? prefix : "") + ":\n" +
+      JSON.stringify(s, null, 2),
+  );
 
-function createCell(space: Space): Cell<Charm>  {
+function createCell(space: Space): Cell<Charm> {
   const myCharm: Charm = {
     NAME: "mycharm",
     UI: "someui",
     "somekey": "some value",
   };
 
-  // make this a DocImpl<Charm> because we need to return a Cell<Charm> since 
+  // make this a DocImpl<Charm> because we need to return a Cell<Charm> since
   // that's what CharmManger.add() needs later on
-  const myDoc: DocImpl<Charm> = getDoc<Charm>(myCharm, crypto.randomUUID(), space);
+  const myDoc: DocImpl<Charm> = getDoc<Charm>(
+    myCharm,
+    crypto.randomUUID(),
+    space,
+  );
   return myDoc.asCell();
 }
 
@@ -38,15 +44,15 @@ async function main() {
   const charmManager = new CharmManager(replica);
   log(charmManager, "charmManager");
 
-  // let's try to create a cell 
+  // let's try to create a cell
   const space: Space = getSpace(replica);
   const cell: Cell<Charm> = createCell(space);
   log(cell.get(), "cell value from Cell.get()");
-  
-  // this feels like magic and wrong, 
-  // but we crash in the next CharmManager.add() if this isn't set 
+
+  // this feels like magic and wrong,
+  // but we crash in the next CharmManager.add() if this isn't set
   storage.setRemoteStorage(
-    new URL(TOOLSHED_API_URL)
+    new URL(TOOLSHED_API_URL),
   );
 
   // let's add the cell to the charmManager

typescript/packages/common-cli/memory_test.ts

@@ -1,7 +1,7 @@
 import { MemorySpace } from "@commontools/memory";
 import { RemoteStorageProvider } from "../common-charm/src/storage/remote.ts";
 import { StorageProvider } from "../common-charm/src/storage/base.ts";
-import { EntityId } from "../common-runner/src/cell-map.ts";
+import { EntityId } from "../common-runner/src/doc-map.ts";
 
 // some config stuff, hardcoded, ofcourse
 const replica = "ellyse5";
@@ -79,10 +79,11 @@ async function main() {
   // now lets try to store a batch of values
   console.log("storing all entities");
   const result = await storageProvider.send(people_batch);
-  if (result.ok)
+  if (result.ok) {
     console.log("sent entities successfully");
-  else
+  } else {
     console.log("got error: " + JSON.stringify(result.error, null, 2));
+  }
 }
 
 main();

typescript/packages/common-runner/src/builtins/fetch-data.ts

@@ -9,10 +9,10 @@ import { refer } from "merkle-reference";
  *
  * Returns the fetched result as `result`. `pending` is true while a request is pending.
  *
- * @param url - A cell containing the URL to fetch data from.
+ * @param url - A doc containing the URL to fetch data from.
  * @param mode - The mode to use for fetching data. Either `text` or `json`
  *   default to `json` results.
- * @returns { pending: boolean, result: any, error: any } - As individual cells, representing `pending` state, final `result`, and any `error`.
+ * @returns { pending: boolean, result: any, error: any } - As individual docs, representing `pending` state, final `result`, and any `error`.
  */
 export function fetchData(
   inputsCell: DocImpl<{

typescript/packages/common-runner/src/builtins/llm.ts

@@ -12,18 +12,18 @@ import { type ReactivityLog } from "../scheduler.ts";
  * Returns the complete result as `result` and the incremental result as
  * `partial`. `pending` is true while a request is pending.
  *
- * @param prompt - A cell to store the prompt message - if you only have a single message
+ * @param prompt - A doc to store the prompt message - if you only have a single message
  * @param messages - list of messages to send to the LLM. - alternating user and assistant messages.
  *  - if you end with an assistant message, the LLM will continue from there.
  *  - if both prompt and messages are empty, no LLM call will be made,
  *    result and partial will be undefined.
- * @param model - A cell to store the model to use.
- * @param system - A cell to store the system message.
- * @param stop - A cell to store (optional) stop sequence.
- * @param max_tokens - A cell to store the maximum number of tokens to generate.
+ * @param model - A doc to store the model to use.
+ * @param system - A doc to store the system message.
+ * @param stop - A doc to store (optional) stop sequence.
+ * @param max_tokens - A doc to store the maximum number of tokens to generate.
  *
  * @returns { pending: boolean, result?: string, partial?: string } - As individual
- *   cells, representing `pending` state, final `result` and incrementally
+ *   docs, representing `pending` state, final `result` and incrementally
  *   updating `partial` result.
  */
 export function llm(
@@ -114,7 +114,7 @@ export function llm(
 
     // Return if the same request is being made again, either concurrently (same
     // as previousCallHash) or when rehydrated from storage (same as the
-    // contents of the requestHash cell).
+    // contents of the requestHash doc).
     if (hash === previousCallHash || hash === requestHash.get()) return;
     previousCallHash = hash;
 

typescript/packages/common-runner/src/builtins/map.ts

@@ -13,19 +13,19 @@ import { type AddCancel } from "../cancel.ts";
  * The goal is to keep the output array current without recomputing too much.
  *
  * Approach:
- * 1. Create a cell to store the result.
- * 2. Create a handler to update the result cell when the input cell changes.
- * 3. Create a handler to update the result cell when the op cell changes.
- * 4. For each value in the input cell, create a handler to update the result
- *    cell when the value changes.
+ * 1. Create a doc to store the result.
+ * 2. Create a handler to update the result doc when the input doc changes.
+ * 3. Create a handler to update the result doc when the op doc changes.
+ * 4. For each value in the input doc, create a handler to update the result
+ *    doc when the value changes.
  *
  * TODO: Optimization depends on javascript objects and not lookslike objects.
  * We should make sure updates to arrays don't unnecessarily re-ify objects
  * and/or change the comparision here.
  *
- * @param list - A cell containing an array of values to map over.
+ * @param list - A doc containing an array of values to map over.
  * @param op - A recipe to apply to each value.
- * @returns A cell containing the mapped values.
+ * @returns A doc containing the mapped values.
  */
 export function map(
   inputsCell: DocImpl<{
@@ -72,7 +72,7 @@ export function map(
       throw new Error("map currently only supports arrays");
     }
 
-    // // Hack to get to underlying array that lists cell references, etc.
+    // Hack to get to underlying array that lists doc links, etc.
     const listRef = getDocLinkOrThrow(list);
 
     // Same for op, but here it's so that the proxy doesn't follow the aliases
@@ -106,7 +106,7 @@ export function map(
       // TODO(seefeld): Have `run` return cancel, once we make resultCell required
       addCancel(cancels.get(resultCell));
 
-      // Send the result value to the result cell
+      // Send the result value to the result doc
       result.setAtPath([initializedUpTo], { cell: resultCell, path: [] }, log);
 
       initializedUpTo++;

typescript/packages/common-runner/src/builtins/stream-data.ts

@@ -11,8 +11,8 @@ import { type ReactivityLog } from "../scheduler.ts";
  *
  * Returns the streamed result as `result`. `pending` is true while a request is pending.
  *
- * @param url - A cell containing the URL to stream data from.
- * @returns { pending: boolean, result: any, error: any } - As individual cells, representing `pending` state, streamed `result`, and any `error`.
+ * @param url - A doc containing the URL to stream data from.
+ * @returns { pending: boolean, result: any, error: any } - As individual docs, representing `pending` state, streamed `result`, and any `error`.
  */
 export function streamData(
   inputsCell: DocImpl<{
@@ -53,7 +53,7 @@ export function streamData(
   result.sourceCell = parentDoc;
   error.sourceCell = parentDoc;
 
-  // Since we'll only write into the cells above, we only have to call this once
+  // Since we'll only write into the docs above, we only have to call this once
   // here, instead of in the action.
   sendResult({ pending, result, error });
 

typescript/packages/common-runner/src/cell.ts

@@ -13,9 +13,9 @@ import {
   getDocLinkOrValue,
   type QueryResult,
 } from "./query-result-proxy.ts";
-import { followLinks, prepareForSaving, resolvePath } from "./utils.ts";
+import { prepareForSaving, resolveLinkToValue, resolvePath } from "./utils.ts";
 import { queueEvent, type ReactivityLog, subscribe } from "./scheduler.ts";
-import { type EntityId, getDocByEntityId, getEntityId } from "./cell-map.ts";
+import { type EntityId, getDocByEntityId, getEntityId } from "./doc-map.ts";
 import { type Cancel, isCancel, useCancelGroup } from "./cancel.ts";
 import { validateAndTransform } from "./schema.ts";
 import { type Schema } from "@commontools/builder";
@@ -203,7 +203,7 @@ export function createCell<T>(
   // Resolve the path to check whether it's a stream. We're not logging this right now.
   // The corner case where during it's lifetime this changes from non-stream to stream
   // or vice versa will not be detected.
-  const ref = followLinks(resolvePath(doc, path));
+  const ref = resolveLinkToValue(doc, path);
   if (isStreamAlias(ref.cell.getAtPath(ref.path))) {
     return createStreamCell(ref.cell, ref.path) as unknown as Cell<T>;
   } else return createRegularCell(doc, path, log, schema, rootSchema);