Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

6.2 KB
Raw Blame
import { MakeLogicType, actions, kea, key, listeners, path, props, reducers, selectors } from 'kea'

export interface NotebookOperationsLogicProps {
    shortId: string
}

export type NotebookOperation = {
    /** Unique per operation, e.g. `${nodeId}:run` — re-registering the same id is idempotent. */
    id: string
    nodeId: string
    kind: 'run' | 'page'
    label?: string
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookOperationsLogicValues {
    activeOperation: NotebookOperation | null
    isBusy: boolean
    operations: Record<string, NotebookOperation>
    releasedNodeId: string | null
    runQueue: string[]
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookOperationsLogicActions {
    dequeueRun: (nodeId: string) => {
        nodeId: string
    }
    enqueueRun: (nodeId: string) => {
        nodeId: string
    }
    finishNodeOperations: (nodeId: string) => {
        nodeId: string
    }
    finishOperation: (id: string) => {
        id: string
    }
    releaseQueuedRun: (nodeId: string) => {
        nodeId: string
    }
    settleReleasedRun: (nodeId: string) => {
        nodeId: string
    }
    startOperation: (operation: NotebookOperation) => {
        operation: NotebookOperation
    }
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface notebookOperationsLogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        activeOperation: (operations: Record<string, NotebookOperation>) => NotebookOperation | null
        isBusy: (operations: Record<string, NotebookOperation>) => boolean
    }
}

export type notebookOperationsLogicType = MakeLogicType<
    notebookOperationsLogicValues,
    notebookOperationsLogicActions,
    NotebookOperationsLogicProps,
    notebookOperationsLogicMeta
>

/**
 * Notebook-wide registry of in-flight data operations (query runs, page fetches).
 *
 * One operation at a time per notebook: node logics register on start and release on every
 * terminal path, and gate their own actions on `isBusy` so a user can't stack operations
 * across cells. A run started while the notebook is busy waits in `runQueue`, the way Jupyter queues
 * cells behind a busy kernel, and the queue releases one cell each time the notebook goes idle.
 * Client-local UX only — collaborators and other tabs are not serialized;
 * server-side guards remain the real enforcement.
 */
export const notebookOperationsLogic = kea<notebookOperationsLogicType>([
    path((key) => ['scenes', 'notebooks', 'Notebook', 'notebookOperationsLogic', key]),
    props({} as NotebookOperationsLogicProps),
    key((props) => props.shortId),
    actions({
        startOperation: (operation: NotebookOperation) => ({ operation }),
        finishOperation: (id: string) => ({ id }),
        // Sweep for unmount/delete of a node: a removed cell must never wedge the notebook.
        finishNodeOperations: (nodeId: string) => ({ nodeId }),
        enqueueRun: (nodeId: string) => ({ nodeId }),
        dequeueRun: (nodeId: string) => ({ nodeId }),
        // The node logic with this id picks it up and starts its stored run.
        releaseQueuedRun: (nodeId: string) => ({ nodeId }),
        // A released run that stopped before it took the notebook, e.g. while preparing its inputs.
        settleReleasedRun: (nodeId: string) => ({ nodeId }),
    }),
    reducers({
        operations: [
            {} as Record<string, NotebookOperation>,
            {
                startOperation: (state, { operation }) => ({ ...state, [operation.id]: operation }),
                finishOperation: (state, { id }) => {
                    if (!(id in state)) {
                        return state
                    }
                    const next = { ...state }
                    delete next[id]
                    return next
                },
                finishNodeOperations: (state, { nodeId }) =>
                    Object.fromEntries(Object.entries(state).filter(([, operation]) => operation.nodeId !== nodeId)),
            },
        ],
        // Released but not yet started: its inputs can take a while to prepare, and the notebook is
        // idle meanwhile, so this keeps the queue from releasing a second cell in that gap.
        releasedNodeId: [
            null as string | null,
            {
                releaseQueuedRun: (_, { nodeId }) => nodeId,
                startOperation: (state, { operation }) => (operation.nodeId === state ? null : state),
                settleReleasedRun: (state, { nodeId }) => (nodeId === state ? null : state),
                finishNodeOperations: (state, { nodeId }) => (nodeId === state ? null : state),
            },
        ],
        runQueue: [
            [] as string[],
            {
                enqueueRun: (state, { nodeId }) => (state.includes(nodeId) ? state : [...state, nodeId]),
                dequeueRun: (state, { nodeId }) => state.filter((id) => id !== nodeId),
                releaseQueuedRun: (state, { nodeId }) => state.filter((id) => id !== nodeId),
                finishNodeOperations: (state, { nodeId }) => state.filter((id) => id !== nodeId),
            },
        ],
    }),
    selectors({
        activeOperation: [
            (s) => [s.operations],
            (operations: Record<string, NotebookOperation>): NotebookOperation | null =>
                Object.values(operations)[0] ?? null,
        ],
        isBusy: [
            (s) => [s.operations],
            (operations: Record<string, NotebookOperation>): boolean => Object.keys(operations).length > 0,
        ],
    }),
    listeners(({ actions, values }) => {
        const releaseNext = (): void => {
            if (!values.isBusy && !values.releasedNodeId && values.runQueue.length > 0) {
                actions.releaseQueuedRun(values.runQueue[0])
            }
        }
        return {
            finishOperation: releaseNext,
            finishNodeOperations: releaseNext,
            settleReleasedRun: releaseNext,
            // A run queued while the notebook was already idle again, e.g. behind a page fetch that
            // finished in the same tick, would otherwise wait for an operation that never ends.
            enqueueRun: releaseNext,
        }
    }),
])