@milaboratories/pl-middle-layer 1.71.16 → 1.72.0

package/src/middle_layer/project_list.test.ts

@@ -0,0 +1,183 @@
+/**
+ * The project-list reader against a hand-built projects resource: what it keeps, what it skips
+ * and in which order. No backend — `projectListEntries` is the whole computable body, fed here
+ * with a stand-in node instead of a synchronized tree.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { ResourceType } from "@milaboratories/pl-client";
+import { asSignedResourceId } from "@milaboratories/pl-client";
+import type { ProjectMeta } from "@milaboratories/pl-model-middle-layer";
+import {
+  ProjectCreatedTimestamp,
+  ProjectLastModifiedTimestamp,
+  ProjectMetaKey,
+  ProjectResourceType,
+} from "../model/project_model";
+import type { ProjectId } from "../model/project_model";
+import { projectListEntries } from "./project_list";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** One field of the projects resource: a node, or a field that resolves to nothing. */
+interface Entry {
+  readonly field: string;
+  readonly id?: number;
+  readonly type?: ResourceType;
+  readonly kv?: Record<string, unknown>;
+  /** A field whose value has not resolved yet — `traverse` returns undefined. */
+  readonly unresolved?: boolean;
+}
+
+/** A project field with the metadata a synced project carries. */
+function project(field: string, id: number, label: string, created: number, modified: number) {
+  return {
+    field,
+    id,
+    type: ProjectResourceType,
+    kv: {
+      [ProjectMetaKey]: { label } satisfies ProjectMeta,
+      [ProjectCreatedTimestamp]: created,
+      [ProjectLastModifiedTimestamp]: modified,
+    },
+  } satisfies Entry;
+}
+
+/** Stand-in for the projects-list tree node, carrying exactly what the reader reads. */
+function projectsNode(...entries: Entry[]) {
+  return {
+    listDynamicFields: () => entries.map((e) => e.field),
+    traverse: (fieldName: string) => {
+      const entry = entries.find((e) => e.field === fieldName);
+      if (entry === undefined || entry.unresolved) return undefined;
+      return {
+        id: asSignedResourceId(`0x${(entry.id ?? 0).toString(16)}|ab`),
+        resourceType: entry.type ?? ProjectResourceType,
+        getKeyValueAsJson: <T>(key: string) => (entry.kv ?? {})[key] as T | undefined,
+      };
+    },
+  };
+}
+
+const NoneOpened: ProjectId[] = [];
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("tolerance", () => {
+  it("keeps every synced project", () => {
+    const entries = projectListEntries(
+      projectsNode(project("uuid-a", 1, "A", 100, 100), project("uuid-b", 2, "B", 200, 200)),
+      NoneOpened,
+    );
+
+    expect(entries.map((e) => e.meta.label)).toStrictEqual(["B", "A"]);
+    expect(entries[1].created).toStrictEqual(new Date(100));
+    expect(entries[1].lastModified).toStrictEqual(new Date(100));
+  });
+
+  it("skips a sibling that is not a project, and keeps the projects around it", () => {
+    const entries = projectListEntries(
+      projectsNode(
+        project("uuid-a", 1, "A", 100, 100),
+        { field: "folders", id: 9, type: { name: "Folders", version: "1" } },
+        project("uuid-b", 2, "B", 200, 200),
+      ),
+      NoneOpened,
+    );
+
+    expect(entries.map((e) => e.meta.label)).toStrictEqual(["B", "A"]);
+  });
+
+  it("skips a project whose metadata has not synced yet", () => {
+    const halfSynced = [
+      { name: "no key at all", kv: {} },
+      {
+        name: "meta missing",
+        kv: { [ProjectCreatedTimestamp]: 1, [ProjectLastModifiedTimestamp]: 1 },
+      },
+      {
+        name: "created missing",
+        kv: { [ProjectMetaKey]: { label: "x" }, [ProjectLastModifiedTimestamp]: 1 },
+      },
+      {
+        name: "lastModified missing",
+        kv: { [ProjectMetaKey]: { label: "x" }, [ProjectCreatedTimestamp]: 1 },
+      },
+    ];
+
+    for (const { name, kv } of halfSynced) {
+      const entries = projectListEntries(
+        projectsNode(
+          { field: "uuid-half", id: 9, type: ProjectResourceType, kv },
+          project("uuid-a", 1, "A", 100, 100),
+        ),
+        NoneOpened,
+      );
+      expect(
+        entries.map((e) => e.meta.label),
+        name,
+      ).toStrictEqual(["A"]);
+    }
+  });
+
+  it("skips a field that resolves to nothing", () => {
+    const entries = projectListEntries(
+      projectsNode({ field: "uuid-pending", unresolved: true }, project("uuid-a", 1, "A", 1, 1)),
+      NoneOpened,
+    );
+
+    expect(entries.map((e) => e.meta.label)).toStrictEqual(["A"]);
+  });
+
+  it("returns an empty list rather than throwing when nothing on the resource is a project", () => {
+    const entries = projectListEntries(
+      projectsNode({ field: "folders", id: 9, type: { name: "Folders", version: "1" } }),
+      NoneOpened,
+    );
+
+    expect(entries).toStrictEqual([]);
+  });
+});
+
+describe("ordering", () => {
+  it("sorts most recently modified first, regardless of field order", () => {
+    const entries = projectListEntries(
+      projectsNode(
+        project("uuid-mid", 1, "mid", 0, 200),
+        project("uuid-newest", 2, "newest", 0, 300),
+        project("uuid-oldest", 3, "oldest", 0, 100),
+      ),
+      NoneOpened,
+    );
+
+    expect(entries.map((e) => e.meta.label)).toStrictEqual(["newest", "mid", "oldest"]);
+  });
+
+  it("orders on last-modified and not on creation", () => {
+    const entries = projectListEntries(
+      projectsNode(
+        project("uuid-a", 1, "created first, touched last", 100, 900),
+        project("uuid-b", 2, "created last, touched first", 800, 850),
+      ),
+      NoneOpened,
+    );
+
+    expect(entries.map((e) => e.meta.label)).toStrictEqual([
+      "created first, touched last",
+      "created last, touched first",
+    ]);
+  });
+});
+
+describe("opened flag", () => {
+  it("marks exactly the projects the caller lists as opened", () => {
+    const node = projectsNode(project("uuid-a", 1, "A", 1, 1), project("uuid-b", 2, "B", 2, 2));
+    const opened = projectListEntries(node, NoneOpened)
+      .filter((e) => e.meta.label === "A")
+      .map((e) => e.id);
+
+    const entries = projectListEntries(node, opened);
+
+    expect(entries.filter((e) => e.opened).map((e) => e.meta.label)).toStrictEqual(["A"]);
+  });
+});

package/src/middle_layer/project_list.ts

@@ -22,10 +22,11 @@ import {
   ProjectCreatedTimestamp,
   ProjectLastModifiedTimestamp,
   ProjectMetaKey,
+  ProjectResourceType,
 } from "../model/project_model";
 import type { MiddleLayerEnvironment } from "./middle_layer";
-import { notEmpty } from "@milaboratories/ts-helpers";
 import type { ProjectMeta } from "@milaboratories/pl-model-middle-layer";
+import { asProjectId } from "@milaboratories/pl-model-common";
 
 export const ProjectsField = "projects";
 export const ProjectsResourceType: ResourceType = { name: "Projects", version: "1" };
@@ -77,27 +78,63 @@ export async function createProjectList(
     const node = ctx.accessor(tree.entry()).node();
     const oProjects = openedProjects.getValue(ctx);
     if (node === undefined) return undefined;
-    const result: ProjectListEntry[] = [];
-
-    // Projects list resource keeps projects assigned to fields. Each field name is project's UUID
-    for (const field of node.listDynamicFields()) {
-      const prj = node.traverse(field);
-      if (prj === undefined) continue;
-      const meta = notEmpty(prj.getKeyValueAsJson<ProjectMeta>(ProjectMetaKey));
-      const created = notEmpty(prj.getKeyValueAsJson<number>(ProjectCreatedTimestamp));
-      const lastModified = notEmpty(prj.getKeyValueAsJson<number>(ProjectLastModifiedTimestamp));
-      const projectId = resourceIdToString(prj.id) as ProjectId;
-      result.push({
-        id: projectId,
-        created: new Date(created),
-        lastModified: new Date(lastModified),
-        opened: oProjects.indexOf(projectId) >= 0,
-        meta,
-      });
-    }
-    result.sort((p) => -p.lastModified.valueOf());
-    return result;
+    return projectListEntries(node, oProjects);
   }).withStableType();
 
   return { computable: c, tree };
 }
+
+/** The part of a tree node this reader needs from a single entry of the projects list. */
+interface ProjectListEntryNode {
+  readonly id: SignedResourceId;
+  readonly resourceType: ResourceType;
+  getKeyValueAsJson<T>(key: string): T | undefined;
+}
+
+/** The part of a tree node this reader needs from the projects-list resource itself. */
+interface ProjectsListNode {
+  listDynamicFields(): string[];
+  traverse(fieldName: string): ProjectListEntryNode | undefined;
+}
+
+/**
+ * Builds the project list out of the projects-list resource, most recently modified first.
+ *
+ * Skips, rather than throws on, anything that is not a fully synced project. The projects
+ * resource carries the user's entire project list, so one unexpected sibling field — or one
+ * project whose metadata has not arrived yet — must cost that entry and nothing else. Both the
+ * traversal and the metadata reads are watched, so an entry appears as soon as it syncs.
+ *
+ * The resource type is matched by name only: the point is to exclude foreign resources, not to
+ * hide a project stored under an earlier resource-type version.
+ */
+export function projectListEntries(
+  node: ProjectsListNode,
+  openedProjects: readonly ProjectId[],
+): ProjectListEntry[] {
+  const result: ProjectListEntry[] = [];
+
+  // Projects list resource keeps projects assigned to fields. Each field name is project's UUID
+  for (const field of node.listDynamicFields()) {
+    const prj = node.traverse(field);
+    if (prj === undefined) continue;
+    if (prj.resourceType.name !== ProjectResourceType.name) continue;
+
+    const meta = prj.getKeyValueAsJson<ProjectMeta>(ProjectMetaKey);
+    const created = prj.getKeyValueAsJson<number>(ProjectCreatedTimestamp);
+    const lastModified = prj.getKeyValueAsJson<number>(ProjectLastModifiedTimestamp);
+    if (meta === undefined || created === undefined || lastModified === undefined) continue;
+
+    const projectId = asProjectId(resourceIdToString(prj.id));
+    result.push({
+      id: projectId,
+      created: new Date(created),
+      lastModified: new Date(lastModified),
+      opened: openedProjects.indexOf(projectId) >= 0,
+      meta,
+    });
+  }
+
+  result.sort((a, b) => b.lastModified.valueOf() - a.lastModified.valueOf());
+  return result;
+}

package/src/middle_layer/sharing.test.ts

@@ -0,0 +1,183 @@
+import { expect, test } from "vitest";
+import * as tp from "node:timers/promises";
+import { resourceIdToString } from "@milaboratories/pl-client";
+import type { FolderId, FoldersItem } from "@milaboratories/pl-model-middle-layer";
+import type { TemplateId } from "@milaboratories/pl-model-common";
+import { PROJECT_TEMPLATE_SCHEMA_V1 } from "@milaboratories/pl-model-common";
+import { withMlKeepingRoots } from "../test/with_ml";
+import { createTemplate } from "../mutator/template";
+import type { FoldersListing } from "./folders";
+import type { MiddleLayer } from "./middle_layer";
+import { ensureTemplateListRid } from "./template_list";
+
+// The file's roots outlive their tests and are deleted together after the last one, so the
+// backend's cleanup of their projects never runs under this file's own writes.
+const withMl = withMlKeepingRoots();
+
+/**
+ * Sharing folders and projects against a live backend: what a copy out of a share builds, and
+ * where it puts it.
+ *
+ * The test server has one user, so every share here goes to everyone and is copied by its own
+ * donor, which is enough to exercise the whole copy: the envelope is discovered and copied from
+ * exactly as a recipient's would be.
+ *
+ * Needs a backend, like every `withMl` test in this package, and no gate: `PL_ADDRESS` is either
+ * configured or the client fails to connect.
+ */
+
+test("a shared folder is rebuilt whole inside the destination, its root named to fit there", async () => {
+  await withMl(async (ml) => {
+    const source = await ml.createFolder("Repertoires");
+    await ml.setFolderDescription(source, "Every donor, both replicates");
+    const nested = await ml.createFolder("2024", source);
+    const alpha = await ml.createProject({ label: "Alpha", description: "Donor 14" }, source);
+    await ml.createProject({ label: "Beta" }, nested);
+    const pipeline = await storeTemplate(ml, "Pipeline", "Clonotyping, then clustering");
+    await move(ml, { kind: "template", id: pipeline }, nested);
+
+    // The destination already holds a folder of the shared root's name.
+    const inbox = await ml.createFolder("Inbox");
+    await ml.createFolder("Repertoires", inbox);
+
+    const shared = await ml.shareFolder(source, { everyone: true, title: "Repertoires" });
+    const outcome = await ml.copyShare([shared.shareId], inbox);
+
+    expect(outcome.failed).toStrictEqual([]);
+    expect(outcome.projects).toHaveLength(2);
+    expect(outcome.templates).toHaveLength(1);
+
+    const listing = await untilListing(
+      ml,
+      (l) => l.projects.length === 4 && l.templates.length === 2 && l.folders.length === 6,
+    );
+
+    // Only the root lands beside what the destination already holds, so only the root is renamed.
+    const root = listing.folders.find((f) => f.parent === inbox && f.name !== "Repertoires");
+    if (root === undefined) throw new Error("the shared folder was not rebuilt in the destination");
+    expect(root.name).toBe("Repertoires (Copy)");
+    expect(root.description).toBe("Every donor, both replicates");
+
+    const inside = listing.folders.filter((f) => f.ancestors.includes(root.id));
+    expect(inside.map((f) => f.name)).toStrictEqual(["2024"]);
+    const rebuilt = inside[0];
+    expect(rebuilt.parent).toBe(root.id);
+
+    // Every copy lands in the rebuilt counterpart of the folder it was shared from.
+    const copies = listing.projects.filter((p) => outcome.projects.includes(p.id));
+    const alphaCopy = copies.find((p) => p.meta.label === "Alpha");
+    expect(alphaCopy?.folder).toBe(root.id);
+    expect(alphaCopy?.meta.description).toBe("Donor 14");
+    expect(copies.find((p) => p.meta.label === "Beta")?.folder).toBe(rebuilt.id);
+
+    const pipelineCopy = listing.templates.find((t) => t.id === outcome.templates[0]);
+    expect(pipelineCopy).toMatchObject({
+      label: "Pipeline",
+      description: "Clonotyping, then clustering",
+      folder: rebuilt.id,
+    });
+
+    // The shared subtree itself is left where it was.
+    expect(listing.projects.find((p) => p.id === alpha)?.folder).toBe(source);
+    expect(listing.templates.find((t) => t.id === pipeline)?.folder).toBe(nested);
+  });
+});
+
+test("a shared project copied into a folder lands there, named to fit beside what it holds", async () => {
+  await withMl(async (ml) => {
+    const source = await ml.createProject({ label: "Alpha" });
+    const inbox = await ml.createFolder("Inbox");
+    await ml.createProject({ label: "Alpha" }, inbox);
+
+    const shared = await ml.shareProjects([source], {
+      everyone: true,
+      title: "Alpha",
+      mode: "copy",
+    });
+    const outcome = await ml.copyShare([shared.shareId], inbox);
+
+    expect(outcome.failed).toStrictEqual([]);
+    expect(outcome.projects).toHaveLength(1);
+
+    const listing = await untilListing(ml, (l) => l.projects.length === 3);
+    const copy = listing.projects.find((p) => p.id === outcome.projects[0]);
+    expect(copy?.folder).toBe(inbox);
+    expect(copy?.meta.label).toBe("Alpha (Copy)");
+    expect(listing.projects.find((p) => p.id === source)?.folder).toBeUndefined();
+  });
+});
+
+test("replacing a project share leaves one share, under a new id", async () => {
+  await withMl(async (ml) => {
+    const project = await ml.createProject({ label: "Alpha" });
+
+    const first = await ml.shareProjects([project], {
+      everyone: true,
+      title: "Alpha",
+      mode: "copy",
+    });
+    const replacement = await ml.shareProjects([project], {
+      everyone: true,
+      title: "Alpha, again",
+      mode: "copy",
+      replace: [first.shareId],
+    });
+    expect(replacement.shareId).not.toBe(first.shareId);
+
+    // The replaced share is deleted in the transaction that creates its replacement, so the
+    // outbox never holds both.
+    const outgoing = (await ml.outgoingShares.getValue()) ?? [];
+    expect(outgoing.map((s) => s.shareId)).toStrictEqual([replacement.shareId]);
+    expect(outgoing[0]).toMatchObject({ payloadKind: "projects", title: "Alpha, again" });
+    expect(outgoing[0].projects.map((p) => p.projectId)).toStrictEqual([project]);
+  });
+});
+
+//
+// Internals
+//
+
+/** Stores an empty template at the top level and returns its id. */
+async function storeTemplate(
+  ml: MiddleLayer,
+  label: string,
+  description: string,
+): Promise<TemplateId> {
+  const rid = await ml.pl.withWriteTx("TestStoreTemplate", async (tx) => {
+    const listRid = await ensureTemplateListRid(tx);
+    const tpl = createTemplate(
+      tx,
+      listRid,
+      { label, description },
+      { schemaVersion: 1, document: { schema: PROJECT_TEMPLATE_SCHEMA_V1, blocks: [] } },
+    );
+    await tx.commit();
+    return await tpl.globalId;
+  });
+  return resourceIdToString(rid) as TemplateId;
+}
+
+/** Moves one item with its own fresh plan, for the steps a test only needs as setup. */
+async function move(ml: MiddleLayer, item: FoldersItem, destination: FolderId): Promise<void> {
+  const planned = await ml.previewFoldersMove([item], destination);
+  if (!planned.ok) throw new Error(`cannot plan move: ${JSON.stringify(planned.issues)}`);
+  const outcome = await ml.moveFolderItems([item], destination, planned.plan);
+  if (!outcome.ok) throw new Error(`move refused: ${outcome.reason}`);
+}
+
+/**
+ * The listing is fed by polled trees, so a test waits for the state it expects rather than
+ * reading once.
+ */
+async function untilListing(
+  ml: MiddleLayer,
+  predicate: (listing: FoldersListing) => boolean,
+): Promise<FoldersListing> {
+  let last: FoldersListing | undefined = undefined;
+  for (let attempt = 0; attempt < 60; attempt++) {
+    last = await ml.folders.awaitStableValue();
+    if (predicate(last)) return last;
+    await tp.setTimeout(250);
+  }
+  throw new Error(`folder listing never matched; last value: ${JSON.stringify(last)}`);
+}