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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;