feat(link-utils): make parsed links complete memory addresses (#1342)

feat(link-utils): introduce `type` field for parsed links, making them memory addresses

- Added a new `type` property to normalized link structures in `link-utils.ts`, defaulting to `application/json`.
- Updated link parsing, normalization, and equality logic to handle the new `type` field.
- Refactored related functions and tests to ensure correct handling and propagation of the `type` property.
- Enhanced test cases in `link-utils.test.ts` to cover scenarios involving the `type` field and its default value.

Author: seefeldb

packages/runner/src/link-utils.ts

@@ -20,6 +20,7 @@ import {
   isQueryResultForDereferencing,
   QueryResultInternals,
 } from "./query-result-proxy.ts";
+import { type IMemoryAddress } from "./storage/interface.ts";
 
 /**
  * Normalized link structure returned by parsers
@@ -28,22 +29,19 @@ export type NormalizedLink = {
   id?: URI; // URI format with "of:" prefix
   path: string[];
   space?: MemorySpace;
+  type?: string; // Default is "application/json"
   schema?: JSONSchema;
   rootSchema?: JSONSchema;
   overwrite?: "redirect"; // "this" gets normalized away to undefined
 };
 
 /**
- * Normalized link with required id and space (when base Cell is provided)
+ * Full normalized link that from a complete link, i.e. with required id, space
+ * and type. Gets created by parseLink if a base is provided.
+ *
+ * Any such link can be used as a memory address.
  */
-export type NormalizedFullLink = {
-  id: URI; // URI format with "of:" prefix
-  path: string[];
-  space: MemorySpace;
-  schema?: JSONSchema;
-  rootSchema?: JSONSchema;
-  overwrite?: "redirect"; // "this" gets normalized away to undefined
-};
+export type NormalizedFullLink = NormalizedLink & IMemoryAddress;
 
 /**
  * A type reflecting all possible link formats, including cells themselves.
@@ -175,6 +173,7 @@ export function isNormalizedFullLink(value: any): value is NormalizedFullLink {
     isRecord(value) &&
     typeof value.id === "string" &&
     typeof value.space === "string" &&
+    typeof value.type === "string" &&
     Array.isArray(value.path)
   );
 }
@@ -248,6 +247,7 @@ export function parseLink(
       id: toURI(value.getDoc().entityId),
       path: value.path.map((p) => p.toString()),
       space: value.space,
+      type: "application/json",
       schema: value.schema,
       rootSchema: value.rootSchema,
     };
@@ -259,6 +259,7 @@ export function parseLink(
       id: toURI(value.entityId),
       path: [],
       space: value.space,
+      type: "application/json",
     };
   }
 
@@ -280,6 +281,7 @@ export function parseLink(
       id: id,
       path: path.map((p) => p.toString()),
       space: resolvedSpace,
+      type: "application/json",
       schema: link.schema,
       rootSchema: link.rootSchema,
       overwrite: link.overwrite === "redirect" ? "redirect" : undefined,
@@ -292,6 +294,7 @@ export function parseLink(
       id: toURI(value.cell.entityId),
       path: value.path.map((p) => p.toString()),
       space: value.cell.space,
+      type: "application/json",
       schema: value.schema,
       rootSchema: value.rootSchema,
     };
@@ -303,6 +306,7 @@ export function parseLink(
       id: toURI(value.cell["/"]),
       path: value.path.map((p) => p.toString()),
       space: base?.space, // Space must come from context for JSON links
+      type: "application/json",
     };
   }
 
@@ -311,6 +315,7 @@ export function parseLink(
       id: toURI(value["/"]),
       path: [],
       space: base?.space, // Space must come from context for JSON links
+      type: "application/json",
     };
   }
 
@@ -341,6 +346,7 @@ export function parseLink(
         ? alias.path.map((p) => p.toString())
         : [],
       space: resolvedSpace,
+      type: "application/json",
       schema: alias.schema as JSONSchema | undefined,
       rootSchema: alias.rootSchema as JSONSchema | undefined,
     };
@@ -503,7 +509,8 @@ export function areNormalizedLinksSame(
   link2: NormalizedLink,
 ): boolean {
   return link1.id === link2.id && link1.space === link2.space &&
-    arrayEqual(link1.path, link2.path);
+    arrayEqual(link1.path, link2.path) &&
+    (link1.type ?? "application/json") === (link2.type ?? "application/json");
 }
 
 export function createSigilLinkFromParsedLink(

packages/runner/test/link-utils.test.ts

@@ -212,6 +212,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: [],
         space: space,
+        type: "application/json",
         schema: undefined,
         rootSchema: undefined,
       });
@@ -227,6 +228,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: ["nested"],
         space: space,
+        type: "application/json",
         schema: undefined,
         rootSchema: undefined,
       });
@@ -241,6 +243,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: [],
         space: space,
+        type: "application/json",
       });
     });
 
@@ -262,6 +265,7 @@ describe("link-utils", () => {
         id: "of:test",
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
         schema: { type: "number" },
         rootSchema: { type: "object" },
       });
@@ -286,6 +290,7 @@ describe("link-utils", () => {
         id: "of:test",
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
         schema: { type: "number" },
         rootSchema: { type: "object" },
       });
@@ -298,6 +303,7 @@ describe("link-utils", () => {
             id: "of:test",
             path: ["nested", "value"],
             space: space,
+            type: "application/json",
             schema: { type: "number" },
             rootSchema: { type: "object" },
             overwrite: "redirect",
@@ -310,6 +316,7 @@ describe("link-utils", () => {
         id: "of:test",
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
         schema: { type: "number" },
         rootSchema: { type: "object" },
         overwrite: "redirect",
@@ -332,6 +339,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
         schema: undefined,
         rootSchema: undefined,
       });
@@ -346,6 +354,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: [],
         space: space,
+        type: "application/json",
         schema: undefined,
         rootSchema: undefined,
       });
@@ -363,6 +372,7 @@ describe("link-utils", () => {
         id: "of:test",
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
       });
     });
 
@@ -382,6 +392,7 @@ describe("link-utils", () => {
         id: expect.stringContaining("of:"),
         path: ["nested", "value"],
         space: space,
+        type: "application/json",
         schema: { type: "number" },
         rootSchema: { type: "object" },
       });
@@ -399,6 +410,7 @@ describe("link-utils", () => {
       expect(result).toEqual({
         id: expect.stringContaining("of:"),
         path: ["nested", "value"],
+        type: "application/json",
         space: space,
         schema: undefined,
         rootSchema: undefined,

packages/runner/test/schema.test.ts

@@ -290,6 +290,7 @@ describe("Schema Support", () => {
         space,
         schema: current.schema,
         rootSchema: current.rootSchema,
+        type: "application/json",
       });
 
       // .get() the currently selected cell. This should not change when
@@ -313,6 +314,7 @@ describe("Schema Support", () => {
         id: toURI(initialEntityId),
         path: ["foo"],
         space,
+        type: "application/json",
         schema: omitSchema,
         rootSchema: schema,
       });