@marimo-team/frontend 0.20.1 → 0.20.3-dev76

package/src/core/storage/__tests__/state.test.ts

@@ -0,0 +1,345 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { beforeEach, describe, expect, it } from "vitest";
+import type { VariableName } from "../../variables/types";
+import { exportedForTesting } from "../state";
+import type { StorageEntry, StorageNamespace, StorageState } from "../types";
+
+const { initialState, reducer, createActions } = exportedForTesting;
+
+function makeNamespace(
+  overrides: Partial<StorageNamespace> & { name: string },
+): StorageNamespace {
+  return {
+    displayName: overrides.displayName ?? overrides.name,
+    name: overrides.name,
+    protocol: overrides.protocol ?? "s3",
+    rootPath: overrides.rootPath ?? "/",
+    storageEntries: overrides.storageEntries ?? [],
+  };
+}
+
+function makeEntry(
+  overrides: Partial<StorageEntry> & { path: string },
+): StorageEntry {
+  return {
+    kind: overrides.kind ?? "file",
+    lastModified: overrides.lastModified ?? null,
+    metadata: overrides.metadata ?? {},
+    path: overrides.path,
+    size: overrides.size ?? 0,
+  };
+}
+
+describe("storage state", () => {
+  let state: StorageState;
+
+  const actions = createActions((action) => {
+    state = reducer(state, action);
+  });
+
+  beforeEach(() => {
+    state = initialState();
+  });
+
+  describe("initialState", () => {
+    it("should start with empty namespaces and entries", () => {
+      expect(state).toEqual({
+        namespaces: [],
+        entriesByPath: new Map(),
+      });
+    });
+  });
+
+  describe("setNamespaces", () => {
+    it("should add namespaces from an empty state", () => {
+      const ns1 = makeNamespace({ name: "my_s3", protocol: "s3" });
+      const ns2 = makeNamespace({ name: "my_gcs", protocol: "gcs" });
+
+      actions.setNamespaces({ namespaces: [ns1, ns2] });
+
+      expect(state.namespaces).toEqual([ns1, ns2]);
+    });
+
+    it("should merge namespaces by name, replacing existing ones", () => {
+      const nsOld = makeNamespace({
+        name: "my_s3",
+        protocol: "s3",
+        rootPath: "/old",
+      });
+      const nsOther = makeNamespace({ name: "my_gcs", protocol: "gcs" });
+      actions.setNamespaces({ namespaces: [nsOld, nsOther] });
+
+      const nsUpdated = makeNamespace({
+        name: "my_s3",
+        protocol: "s3",
+        rootPath: "/new",
+      });
+      actions.setNamespaces({ namespaces: [nsUpdated] });
+
+      expect(state.namespaces).toHaveLength(2);
+      expect(state.namespaces).toEqual([nsUpdated, nsOther]);
+    });
+
+    it("should add new namespaces alongside existing ones", () => {
+      const ns1 = makeNamespace({ name: "ns1" });
+      actions.setNamespaces({ namespaces: [ns1] });
+
+      const ns2 = makeNamespace({ name: "ns2" });
+      actions.setNamespaces({ namespaces: [ns2] });
+
+      expect(state.namespaces).toHaveLength(2);
+      expect(state.namespaces).toEqual([ns1, ns2]);
+    });
+
+    it("should not affect entriesByPath", () => {
+      const entry = makeEntry({ path: "file.txt" });
+      actions.setEntries({
+        namespace: "ns",
+        prefix: null,
+        entries: [entry],
+      });
+
+      actions.setNamespaces({
+        namespaces: [makeNamespace({ name: "ns" })],
+      });
+
+      expect(state.entriesByPath.get("ns::")).toEqual([entry]);
+    });
+  });
+
+  describe("setEntries", () => {
+    it("should store entries keyed by namespace and prefix", () => {
+      const entries = [
+        makeEntry({ path: "a.txt", size: 100 }),
+        makeEntry({ path: "b.txt", size: 200 }),
+      ];
+
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: "data/",
+        entries,
+      });
+
+      expect(state.entriesByPath.get("my_s3::data/")).toEqual(entries);
+    });
+
+    it("should use empty string for null prefix", () => {
+      const entries = [makeEntry({ path: "root.txt" })];
+
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: null,
+        entries,
+      });
+
+      expect(state.entriesByPath.get("my_s3::")).toEqual(entries);
+    });
+
+    it("should use empty string for undefined prefix", () => {
+      const entries = [makeEntry({ path: "root.txt" })];
+
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: undefined,
+        entries,
+      });
+
+      expect(state.entriesByPath.get("my_s3::")).toEqual(entries);
+    });
+
+    it("should overwrite entries for the same namespace and prefix", () => {
+      const oldEntries = [makeEntry({ path: "old.txt" })];
+      const newEntries = [makeEntry({ path: "new.txt" })];
+
+      actions.setEntries({
+        namespace: "ns",
+        prefix: "p/",
+        entries: oldEntries,
+      });
+      actions.setEntries({
+        namespace: "ns",
+        prefix: "p/",
+        entries: newEntries,
+      });
+
+      expect(state.entriesByPath.get("ns::p/")).toEqual(newEntries);
+    });
+
+    it("should store entries for different namespaces independently", () => {
+      const entriesA = [makeEntry({ path: "a.txt" })];
+      const entriesB = [makeEntry({ path: "b.txt" })];
+
+      actions.setEntries({
+        namespace: "ns_a",
+        prefix: null,
+        entries: entriesA,
+      });
+      actions.setEntries({
+        namespace: "ns_b",
+        prefix: null,
+        entries: entriesB,
+      });
+
+      expect(state.entriesByPath.get("ns_a::")).toEqual(entriesA);
+      expect(state.entriesByPath.get("ns_b::")).toEqual(entriesB);
+    });
+
+    it("should store entries for different prefixes independently", () => {
+      const entriesRoot = [makeEntry({ path: "root.txt" })];
+      const entriesSub = [makeEntry({ path: "sub/file.txt" })];
+
+      actions.setEntries({
+        namespace: "ns",
+        prefix: null,
+        entries: entriesRoot,
+      });
+      actions.setEntries({
+        namespace: "ns",
+        prefix: "sub/",
+        entries: entriesSub,
+      });
+
+      expect(state.entriesByPath.get("ns::")).toEqual(entriesRoot);
+      expect(state.entriesByPath.get("ns::sub/")).toEqual(entriesSub);
+    });
+
+    it("should not affect namespaces", () => {
+      const ns = makeNamespace({ name: "ns" });
+      actions.setNamespaces({ namespaces: [ns] });
+
+      actions.setEntries({
+        namespace: "ns",
+        prefix: null,
+        entries: [makeEntry({ path: "file.txt" })],
+      });
+
+      expect(state.namespaces).toEqual([ns]);
+    });
+  });
+
+  describe("clearNamespaceCache", () => {
+    it("should remove all entries for the given namespace", () => {
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: null,
+        entries: [makeEntry({ path: "root.txt" })],
+      });
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: "data/",
+        entries: [makeEntry({ path: "data/file.csv" })],
+      });
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: "data/nested/",
+        entries: [makeEntry({ path: "data/nested/deep.txt" })],
+      });
+
+      actions.clearNamespaceCache("my_s3");
+
+      expect(state.entriesByPath.get("my_s3::")).toBeUndefined();
+      expect(state.entriesByPath.get("my_s3::data/")).toBeUndefined();
+      expect(state.entriesByPath.get("my_s3::data/nested/")).toBeUndefined();
+    });
+
+    it("should not affect entries from other namespaces", () => {
+      const otherEntries = [makeEntry({ path: "other.txt" })];
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: null,
+        entries: [makeEntry({ path: "root.txt" })],
+      });
+      actions.setEntries({
+        namespace: "my_gcs",
+        prefix: null,
+        entries: otherEntries,
+      });
+
+      actions.clearNamespaceCache("my_s3");
+
+      expect(state.entriesByPath.get("my_s3::")).toBeUndefined();
+      expect(state.entriesByPath.get("my_gcs::")).toEqual(otherEntries);
+    });
+
+    it("should not affect namespaces", () => {
+      const ns = makeNamespace({ name: "my_s3" });
+      actions.setNamespaces({ namespaces: [ns] });
+      actions.setEntries({
+        namespace: "my_s3",
+        prefix: null,
+        entries: [makeEntry({ path: "file.txt" })],
+      });
+
+      actions.clearNamespaceCache("my_s3");
+
+      expect(state.namespaces).toEqual([ns]);
+    });
+
+    it("should be a no-op for a namespace with no cached entries", () => {
+      actions.setEntries({
+        namespace: "my_gcs",
+        prefix: null,
+        entries: [makeEntry({ path: "file.txt" })],
+      });
+
+      actions.clearNamespaceCache("nonexistent");
+
+      expect(state.entriesByPath.get("my_gcs::")).toEqual([
+        makeEntry({ path: "file.txt" }),
+      ]);
+    });
+  });
+
+  describe("filterFromVariables", () => {
+    it("should keep namespaces whose variable is still in scope", () => {
+      const ns1 = makeNamespace({ name: "var_a" });
+      const ns2 = makeNamespace({ name: "var_b" });
+      actions.setNamespaces({ namespaces: [ns1, ns2] });
+
+      actions.filterFromVariables([
+        "var_a" as VariableName,
+        "var_b" as VariableName,
+      ]);
+
+      expect(state.namespaces).toEqual([ns1, ns2]);
+    });
+
+    it("should remove namespaces whose variable is no longer in scope", () => {
+      const ns1 = makeNamespace({ name: "var_a" });
+      const ns2 = makeNamespace({ name: "var_b" });
+      actions.setNamespaces({ namespaces: [ns1, ns2] });
+
+      actions.filterFromVariables(["var_a" as VariableName]);
+
+      expect(state.namespaces).toEqual([ns1]);
+    });
+
+    it("should remove all named namespaces when given an empty variable list", () => {
+      const ns1 = makeNamespace({ name: "var_a" });
+      const ns2 = makeNamespace({ name: "var_b" });
+      actions.setNamespaces({ namespaces: [ns1, ns2] });
+
+      actions.filterFromVariables([]);
+
+      expect(state.namespaces).toEqual([]);
+    });
+
+    it("should not affect entriesByPath", () => {
+      const ns = makeNamespace({ name: "ns" });
+      actions.setNamespaces({ namespaces: [ns] });
+
+      const entry = makeEntry({ path: "file.txt" });
+      actions.setEntries({
+        namespace: "ns",
+        prefix: null,
+        entries: [entry],
+      });
+
+      actions.filterFromVariables([]);
+
+      // Namespace removed, but entries remain (they are keyed independently)
+      expect(state.namespaces).toEqual([]);
+      expect(state.entriesByPath.get("ns::")).toEqual([entry]);
+    });
+  });
+});

package/src/core/storage/__tests__/types.test.ts

@@ -0,0 +1,83 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import { storageNamespacePrefix, storagePathKey, storageUrl } from "../types";
+
+describe("storagePathKey", () => {
+  it("should join namespace and prefix", () => {
+    expect(storagePathKey("ns", "data/")).toBe("ns::data/");
+  });
+
+  it("should use empty string for null prefix", () => {
+    expect(storagePathKey("ns", null)).toBe("ns::");
+  });
+
+  it("should use empty string for undefined prefix", () => {
+    expect(storagePathKey("ns", undefined)).toBe("ns::");
+  });
+});
+
+describe("storageNamespacePrefix", () => {
+  it("should append separator", () => {
+    expect(storageNamespacePrefix("my_s3")).toBe("my_s3::");
+  });
+});
+
+describe("storageUrl", () => {
+  it("should combine protocol, rootPath, and entryPath", () => {
+    expect(storageUrl("s3", "my-bucket", "data/file.csv")).toEqual(
+      new URL("s3://my-bucket/data/file.csv"),
+    );
+  });
+
+  it("should handle empty rootPath", () => {
+    expect(storageUrl("s3", "", "marimo-artifacts/file.csv")).toEqual(
+      new URL("s3://marimo-artifacts/file.csv"),
+    );
+  });
+
+  it("should handle rootPath with trailing slash", () => {
+    expect(storageUrl("s3", "my-bucket/", "data/file.csv")).toEqual(
+      new URL("s3://my-bucket/data/file.csv"),
+    );
+  });
+
+  it("should handle entryPath with leading slash", () => {
+    expect(storageUrl("s3", "my-bucket", "/data/file.csv")).toEqual(
+      new URL("s3://my-bucket/data/file.csv"),
+    );
+  });
+
+  it("should collapse multiple slashes between rootPath and entryPath", () => {
+    expect(storageUrl("s3", "my-bucket/", "/data/file.csv")).toEqual(
+      new URL("s3://my-bucket/data/file.csv"),
+    );
+  });
+
+  it("should handle directory paths with trailing slash", () => {
+    expect(storageUrl("gcs", "my-bucket", "data/")).toEqual(
+      new URL("gcs://my-bucket/data/"),
+    );
+  });
+
+  it("should handle empty entryPath", () => {
+    expect(storageUrl("s3", "my-bucket", "")).toEqual(
+      new URL("s3://my-bucket"),
+    );
+  });
+
+  it("should handle both rootPath and entryPath empty", () => {
+    expect(storageUrl("s3", "", "")).toEqual(new URL("s3://"));
+  });
+
+  it("should work with file protocol", () => {
+    expect(storageUrl("file", "/home/user", "docs/readme.md")).toEqual(
+      new URL("file:///home/user/docs/readme.md"),
+    );
+  });
+
+  it("should work with nested rootPath", () => {
+    expect(storageUrl("s3", "bucket/prefix", "sub/file.txt")).toEqual(
+      new URL("s3://bucket/prefix/sub/file.txt"),
+    );
+  });
+});

package/src/core/storage/__tests__/useStorageEntries.test.tsx

@@ -0,0 +1,187 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { renderHook, waitFor } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import type { ReactNode } from "react";
+import * as React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { storageAtom, useStorageEntries } from "../state";
+import type { StorageEntry, StorageState } from "../types";
+
+const mockRequest = vi.fn();
+
+vi.mock("../request-registry", () => ({
+  ListStorageEntries: {
+    request: (...args: unknown[]) => mockRequest(...args),
+  },
+}));
+
+function makeEntry(
+  overrides: Partial<StorageEntry> & { path: string },
+): StorageEntry {
+  return {
+    kind: overrides.kind ?? "file",
+    lastModified: overrides.lastModified ?? null,
+    metadata: overrides.metadata ?? {},
+    path: overrides.path,
+    size: overrides.size ?? 0,
+  };
+}
+
+describe("useStorageEntries", () => {
+  let store: ReturnType<typeof createStore>;
+
+  const wrapper = ({ children }: { children: ReactNode }) =>
+    React.createElement(Provider, { store }, children);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    store = createStore();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function setStorageState(state: Partial<StorageState>) {
+    const current = store.get(storageAtom);
+    store.set(storageAtom, { ...current, ...state });
+  }
+
+  it("should fetch entries when not cached", async () => {
+    const entries = [
+      makeEntry({ path: "a.txt" }),
+      makeEntry({ path: "b.txt" }),
+    ];
+    mockRequest.mockResolvedValue({ entries });
+
+    const { result } = renderHook(() => useStorageEntries("my_s3", "data/"), {
+      wrapper,
+    });
+
+    expect(result.current.isPending).toBe(true);
+    expect(result.current.entries).toEqual([]);
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(false);
+    });
+
+    expect(result.current.entries).toEqual(entries);
+    expect(mockRequest).toHaveBeenCalledWith({
+      namespace: "my_s3",
+      prefix: "data/",
+      limit: 150,
+    });
+  });
+
+  it("should return cached entries without fetching", async () => {
+    const entries = [makeEntry({ path: "cached.txt" })];
+    setStorageState({
+      entriesByPath: new Map([["my_s3::data/", entries]]),
+    });
+
+    const { result } = renderHook(() => useStorageEntries("my_s3", "data/"), {
+      wrapper,
+    });
+
+    expect(result.current.entries).toEqual(entries);
+    expect(result.current.isPending).toBe(false);
+    expect(result.current.error).toBeUndefined();
+    expect(mockRequest).not.toHaveBeenCalled();
+  });
+
+  it("should normalize null prefix to empty string", async () => {
+    const entries = [makeEntry({ path: "root.txt" })];
+    mockRequest.mockResolvedValue({ entries });
+
+    const { result } = renderHook(() => useStorageEntries("ns"), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(false);
+    });
+
+    expect(result.current.entries).toEqual(entries);
+    expect(mockRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ prefix: "" }),
+    );
+  });
+
+  it("should normalize undefined prefix to empty string", async () => {
+    const entries = [makeEntry({ path: "root.txt" })];
+    mockRequest.mockResolvedValue({ entries });
+
+    const { result } = renderHook(() => useStorageEntries("ns", undefined), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.isPending).toBe(false);
+    });
+
+    expect(mockRequest).toHaveBeenCalledWith(
+      expect.objectContaining({ prefix: "" }),
+    );
+  });
+
+  it("should return the error when fetch fails and nothing is cached", async () => {
+    mockRequest.mockRejectedValue(new Error("network failure"));
+
+    const { result } = renderHook(() => useStorageEntries("ns", "pfx/"), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.error).toBeDefined();
+    });
+
+    expect(result.current.error?.message).toBe("network failure");
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("should surface result.error as a thrown error", async () => {
+    mockRequest.mockResolvedValue({
+      entries: [],
+      error: "access denied",
+    });
+
+    const { result } = renderHook(() => useStorageEntries("ns", "pfx/"), {
+      wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.error).toBeDefined();
+    });
+
+    expect(result.current.error?.message).toBe("access denied");
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("should suppress error when entries are cached", async () => {
+    const entries = [makeEntry({ path: "ok.txt" })];
+    setStorageState({
+      entriesByPath: new Map([["ns::pfx/", entries]]),
+    });
+
+    const { result } = renderHook(() => useStorageEntries("ns", "pfx/"), {
+      wrapper,
+    });
+
+    expect(result.current.error).toBeUndefined();
+    expect(result.current.entries).toEqual(entries);
+    expect(result.current.isPending).toBe(false);
+  });
+
+  it("should store fetched entries in the atom", async () => {
+    const entries = [makeEntry({ path: "new.txt" })];
+    mockRequest.mockResolvedValue({ entries });
+
+    renderHook(() => useStorageEntries("ns", "sub/"), { wrapper });
+
+    await waitFor(() => {
+      const state = store.get(storageAtom);
+      expect(state.entriesByPath.get("ns::sub/")).toEqual(entries);
+    });
+  });
+});

package/src/core/storage/request-registry.ts

@@ -0,0 +1,36 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { NotificationMessageData } from "../kernel/messages";
+import { DeferredRequestRegistry } from "../network/DeferredRequestRegistry";
+import { getRequestClient } from "../network/requests";
+import type {
+  StorageDownloadRequest,
+  StorageListEntriesRequest,
+} from "../network/types";
+
+export type StorageEntriesResult = NotificationMessageData<"storage-entries">;
+
+export type StorageDownloadReadyResult =
+  NotificationMessageData<"storage-download-ready">;
+
+export const ListStorageEntries = new DeferredRequestRegistry<
+  Omit<StorageListEntriesRequest, "requestId">,
+  StorageEntriesResult
+>("storage-list-entries", async (requestId, req) => {
+  const client = getRequestClient();
+  await client.listStorageEntries({
+    requestId: requestId,
+    ...req,
+  });
+});
+
+export const DownloadStorage = new DeferredRequestRegistry<
+  Omit<StorageDownloadRequest, "requestId">,
+  StorageDownloadReadyResult
+>("storage-download", async (requestId, req) => {
+  const client = getRequestClient();
+  await client.downloadStorage({
+    requestId: requestId,
+    ...req,
+  });
+});