Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Keep host implementation types private (#11353)

Trevor Manz66fd82c19765
diff --git a/frontend/src/core/host/__tests__/stream.test.ts b/frontend/src/core/host/__tests__/stream.test.ts
index ffe80690a2..a7470793c0 100644
--- a/frontend/src/core/host/__tests__/stream.test.ts
+++ b/frontend/src/core/host/__tests__/stream.test.ts
@@ -3,7 +3,7 @@
import { describe, expect, it } from "vitest";
import type { NotebookEvent } from "../events";
import type { Resource } from "../resources/resource";
-import { createStream, type Stream, type StreamState } from "../stream";
+import { createStream } from "../stream";
import { fixtureEvents } from "./fixtures";
interface CellIds {
@@ -54,17 +54,15 @@ const revisions: Resource<Revisions> = {
},
};
-interface Resources {
- cells: CellIds;
- revisions: Revisions;
+function createTestStream() {
+ return createStream({ cells, revisions });
}
-type State = StreamState<Resources>;
function replay(
- stream: Stream<Resources>,
+ stream: ReturnType<typeof createTestStream>,
events: readonly NotebookEvent[],
- from: State = stream.initial,
-): State {
+ from = stream.initial,
+) {
return events.reduce((state, event) => stream.reduce(state, event), from);
}
@@ -77,7 +75,7 @@ if (cellEvent?.event !== "cell") {
describe("notebook stream", () => {
it("reads the snapshot, goes live at ready, and rebuilds after reset", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const partial = replay(stream, snapshot.slice(0, ready));
expect(partial).toMatchObject({
phase: "snapshot",
@@ -105,7 +103,7 @@ describe("notebook stream", () => {
});
it("keeps resource state by reference when an event does not apply", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const state = replay(stream, snapshot);
const runtime = snapshot.find((event) => event.event === "runtime");
const unhandled = stream.reduce(state, { ...runtime!, id: "100" });
@@ -121,7 +119,7 @@ describe("notebook stream", () => {
});
it("clears resources when its notebook is removed and ignores other notebooks", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const state = replay(stream, snapshot);
const time = "2026-10-01T09:30:00Z";
expect(
@@ -141,7 +139,7 @@ describe("notebook stream", () => {
});
it("rejects objects from another notebook", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const state = replay(stream, snapshot.slice(0, ready));
const notebook = snapshot[0];
if (notebook.event !== "notebook") {
@@ -162,7 +160,7 @@ describe("notebook stream", () => {
});
it("records each live event's cursor and resumes in place", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const partial = replay(stream, snapshot.slice(0, ready));
expect(stream.resume(partial)).toEqual({
...stream.initial,
@@ -195,7 +193,7 @@ describe("notebook stream", () => {
});
it("requires a cursor on live events other than reset and notifications", () => {
- const stream = createStream({ cells, revisions });
+ const stream = createTestStream();
const state = replay(stream, snapshot);
expect(() => stream.reduce(state, cellEvent)).toThrow("cursor");
expect(
diff --git a/frontend/src/core/host/resources/document.ts b/frontend/src/core/host/resources/document.ts
index a048b307ff..3715cc619c 100644
--- a/frontend/src/core/host/resources/document.ts
+++ b/frontend/src/core/host/resources/document.ts
@@ -27,7 +27,7 @@ interface PendingDocument {
* A snapshot's records are pending until `ready`. A live revision is pending
* from its first cell until its `document` event.
*/
-export interface DocumentState {
+interface DocumentState {
readonly current: Document | null;
readonly pending: PendingDocument | null;
}
diff --git a/frontend/src/core/host/resources/resource.ts b/frontend/src/core/host/resources/resource.ts
index 4164bdae1d..55d49ebcca 100644
--- a/frontend/src/core/host/resources/resource.ts
+++ b/frontend/src/core/host/resources/resource.ts
@@ -2,36 +2,24 @@
import type * as Protocol from "../protocol";
-/** An event name from the protocol. */
-export type EventName = Protocol.EventOutput["event"];
-
-/** The decoded event with the given name. */
-export type EventOf<Name extends EventName> = Extract<
- Protocol.EventOutput,
- { event: Name }
->;
-
/**
* Events the stream handles itself.
*
* They identify the notebook, discard state, or carry a native
* notification. Resources do not receive them.
*/
-export type StreamEventName =
- | "reset"
- | "notebook"
- | "notebook.removed"
- | "marimo";
+type StreamEventName = "reset" | "notebook" | "notebook.removed" | "marimo";
/** Events a resource may handle. `ready` marks the end of the snapshot. */
-export type ResourceEventName = Exclude<EventName, StreamEventName>;
-
-/** `snapshot` until `ready` arrives and `live` after it. */
-export type StreamPhase = "snapshot" | "live";
+export type ResourceEvent = Exclude<
+ Protocol.EventOutput,
+ { event: StreamEventName }
+>;
/** What a handler may know about the stream beyond the event. */
export interface HandlerContext {
- readonly phase: StreamPhase;
+ /** `snapshot` until `ready` arrives and `live` after it. */
+ readonly phase: "snapshot" | "live";
}
/**
@@ -39,10 +27,10 @@ export interface HandlerContext {
*
* A handler returns `state` when the event does not apply to it.
*/
-export type EventHandlers<State> = {
- readonly [Name in ResourceEventName]?: (
+type EventHandlers<State> = {
+ readonly [Name in ResourceEvent["event"]]?: (
state: State,
- event: EventOf<Name>,
+ event: Extract<ResourceEvent, { event: Name }>,
context: HandlerContext,
) => State;
};
diff --git a/frontend/src/core/host/stream.ts b/frontend/src/core/host/stream.ts
index 4f009b3cb9..5165874018 100644
--- a/frontend/src/core/host/stream.ts
+++ b/frontend/src/core/host/stream.ts
@@ -3,15 +3,13 @@
import type { NotebookEvent } from "./events";
import type * as Protocol from "./protocol";
import type {
- EventOf,
HandlerContext,
Resource,
- ResourceEventName,
- StreamPhase,
+ ResourceEvent,
} from "./resources/resource";
/** A resource for each entry of a state map under the same name. */
-export type Resources<States> = {
+type Resources<States> = {
readonly [Name in keyof States]: Resource<States[Name]>;
};
@@ -21,8 +19,8 @@ export type Resources<States> = {
* Holds the phase, the notebook identity, the resume cursor, and the state
* of each resource.
*/
-export interface StreamState<States> {
- readonly phase: StreamPhase;
+interface StreamState<States> {
+ readonly phase: HandlerContext["phase"];
/**
* The notebook the stream describes.
*
@@ -40,7 +38,7 @@ export interface StreamState<States> {
}
/** A reducer over the events of one notebook stream. */
-export interface Stream<States> {
+interface Stream<States> {
readonly initial: StreamState<States>;
/**
* Apply one event.
@@ -71,7 +69,7 @@ const UNCURSORED = new Set<NotebookEvent["event"]>([
* Undefined for objects that do not name one.
*/
function notebookIdOf(
- event: EventOf<ResourceEventName>,
+ event: ResourceEvent,
): Protocol.NotebookIdOutput | undefined {
switch (event.event) {
case "document":
@@ -127,7 +125,7 @@ export function createStream<States extends object>(
function fanOut(
state: StreamState<States>,
- event: EventOf<ResourceEventName>,
+ event: ResourceEvent,
): StreamState<States> {
const context: HandlerContext = { phase: state.phase };
let next = state.resources;