Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import { beginInteraction } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
createMachine,
type Machine,
type MachineScopes,
} from '@macro-inc/machine';
import { untrack } from 'solid-js';
import { createStore, produce } from 'solid-js/store';
import { match } from 'ts-pattern';
import type { Entry, PaneId } from '../routes/types';
import { isPromise, type MaybePromise, mapMaybe } from '../utils';
import {
IDLE,
type Phase,
type Command as RunCommand,
type Event as RunEvent,
type Running,
type State as RunState,
runDef,
} from './run';
import {
CANCELLED_RESULT,
type Navigation,
type NavigationCause,
type NavigationResult,
type PaneTarget,
} from './types';
import {
type Command as GateCommand,
type Event as GateEvent,
type State as GateState,
urlGateDef,
} from './url-gate';
/** An in-flight navigation as it affects one pane. */
export type PendingNavigation = {
phase: Phase;
cause: NavigationCause;
pane: PaneId;
from?: Entry;
to: Entry;
};
type InFlight = {
phase: Phase;
cause: NavigationCause;
targets: readonly PaneTarget[];
};
type Run = Machine<RunState, RunEvent>;
type PaneRun = { pane: PaneId; machine: Run };
type Settle = (result: NavigationResult) => void;
export type RegisterCommitCallback = (
navigation: Navigation,
callback: () => void
) => void;
const URL_KEY = '@url';
/** What each pane, and the URL navigation run, has in flight. */
function createInFlight() {
const [inFlight, setInFlight] = createStore<
Record<string, InFlight | undefined>
>({});
const clear = (key: string) => {
if (!inFlight[key]) return;
setInFlight(
produce((draft) => {
delete draft[key];
})
);
};
/** Publishes a run once a phase waits on async work; runs that finish at once never show. */
const show = (key: string, state: Running) => {
const { navigation } = state;
setInFlight(key, {
phase: state.t,
cause: navigation.cause,
targets: navigation.targets,
});
};
/** Keeps a published run up to date as it moves on. */
const follow = (key: string, state: RunState) => {
const published = untrack(() => inFlight[key]) !== undefined;
if (!published) return;
if (state.t === 'idle') {
clear(key);
return;
}
show(key, state);
};
const pendingFrom = (
key: string,
pane: PaneId
): PendingNavigation | undefined => {
const record = inFlight[key];
if (!record) return;
const target = record.targets.find((candidate) => candidate.pane === pane);
if (!target) return;
const { phase, cause } = record;
return { phase, cause, pane, from: target.from, to: target.to };
};
/** The in-flight navigation that affects `pane`, from the pane itself or the URL. */
const pending = (pane: PaneId) =>
pendingFrom(pane, pane) ?? pendingFrom(URL_KEY, pane);
return { show, follow, pending };
}
function runAll(actions: readonly (() => void)[]) {
for (const action of actions) {
action();
}
}
export type Runner = ReturnType<typeof createRunner>;
/**
* Runs navigations: a run machine (`run.ts`) per pane and one for URL
* navigations, with the URL gate (`url-gate.ts`) deciding when pane
* actions may run. It never looks at what a navigation does; each one
* applies itself.
*/
export function createRunner(options: {
/** Phase work for a run; `waiting` hears when a phase goes async. */
phases(
waiting: (state: Running) => void,
onCommit: RegisterCommitCallback
): MachineScopes<RunState, RunEvent>;
/** Panes still open; runs of the others are dropped once idle. */
live(): readonly PaneId[];
}) {
const inFlight = createInFlight();
const settlers = new WeakMap<
Navigation,
{ settle: Settle; callbacks: (() => void)[] }
>();
const outstanding = new Set<Promise<unknown>>();
const waiters: (() => void)[] = [];
const paneRuns: PaneRun[] = [];
let committing = 0;
let disposed = false;
const track = async (promise: Promise<unknown>) => {
outstanding.add(promise);
await promise;
outstanding.delete(promise);
};
/** Starts `navigation`; one that never waits has settled by the time `start` returns. */
const run = (
navigation: Navigation,
begin: () => void
): MaybePromise<NavigationResult> => {
let resolve!: (value: NavigationResult) => void;
const promise = new Promise<NavigationResult>((settle) => {
resolve = settle;
});
let result: NavigationResult | undefined;
settlers.set(navigation, {
settle(value) {
result = value;
resolve(value);
},
callbacks: [],
});
fireAndForget(track(promise), 'split-router');
begin();
return result ?? promise;
};
const settle = (navigation: Navigation, result: NavigationResult) => {
const settler = settlers.get(navigation);
settlers.delete(navigation);
settler?.settle(result);
};
const onCommit: RegisterCommitCallback = (navigation, callback) => {
settlers.get(navigation)?.callbacks.push(callback);
};
const isOpen = () => {
const { t } = gate.getState();
const gateOpen = t === 'open' || t === 'disposed';
return gateOpen && committing === 0;
};
/** Lets waiting actions run once no commit or URL navigation holds them back. */
const release = () => {
if (!isOpen()) return;
runAll(waiters.splice(0));
};
/**
* Applies one navigation. Actions it sets off, such as a view redirecting
* as it mounts, wait until it has written the URL. An apply that throws is
* turned down so the machines keep running.
*/
const commit = (
navigation: Navigation,
entries: readonly Entry[]
): NavigationResult => {
committing += 1;
// Views the commit mounts join this trace until they have loaded.
const interaction = beginInteraction('navigation', {
kind: 'navigation',
attributes: {
'navigation.cause': navigation.cause,
'navigation.pane_count': navigation.targets.length,
},
});
try {
const result = navigation.apply(entries);
const callbacks = settlers.get(navigation)?.callbacks.splice(0) ?? [];
if (result.status === 'committed') {
for (const callback of callbacks) {
if (disposed) break;
try {
callback();
} catch (error) {
console.error('Split router commit callback failed', error);
}
}
}
return result;
} catch (error) {
console.error('Split router could not commit a navigation', error);
return CANCELLED_RESULT;
} finally {
interaction.end();
committing -= 1;
release();
}
};
/** A run whose waiting phases show under `key` in `pending`. */
const createRun = (
key: string,
execute: (command: RunCommand) => void
): Run => {
const scopes = options.phases(
(state) => inFlight.show(key, state),
onCommit
);
const machine = createMachine<RunState, RunEvent, RunCommand>({
initial: IDLE,
def: runDef,
scopes,
execute,
});
machine.subscribe((state) => inFlight.follow(key, state));
return machine;
};
const findRun = (pane: PaneId) =>
paneRuns.find((item) => item.pane === pane)?.machine;
const isFinished = (item: PaneRun, live: readonly PaneId[]) => {
const stillOpen = live.includes(item.pane);
const idle = item.machine.getState().t === 'idle';
return idle && !stillOpen;
};
/** Drops the runs of panes that were removed and have nothing in flight. */
const sweep = () => {
const live = options.live();
const finished = paneRuns.filter((item) => isFinished(item, live));
for (const item of finished) {
item.machine.dispose();
paneRuns.splice(paneRuns.indexOf(item), 1);
}
};
const abortPanes = (reason: 'superseded' | 'disposed') => {
for (const { machine } of [...paneRuns]) {
machine.dispatch({ t: 'abort', reason });
}
};
const executePaneRun = (command: RunCommand) => {
match(command)
.with({ t: 'commit' }, ({ navigation, entries }) =>
settle(navigation, commit(navigation, entries))
)
.with({ t: 'cancel' }, ({ navigation }) =>
settle(navigation, CANCELLED_RESULT)
)
.exhaustive();
sweep();
};
const paneRun = (pane: PaneId): Run => {
const existing = findRun(pane);
if (existing) return existing;
const created = createRun(pane, executePaneRun);
paneRuns.push({ pane, machine: created });
return created;
};
const abort = (pane: PaneId) => {
findRun(pane)?.dispatch({ t: 'abort', reason: 'superseded' });
};
const commitUrl = (navigation: Navigation, entries: readonly Entry[]) => {
const result = commit(navigation, entries);
settle(navigation, result);
const failed = result.status === 'cancelled';
if (failed) return 'failed';
return 'committed';
};
const executeUrlRun = (command: RunCommand) => {
const { navigation } = command;
const outcome = match(command)
.with({ t: 'commit' }, ({ entries }) => commitUrl(navigation, entries))
.with({ t: 'cancel' }, ({ reason }) => {
settle(navigation, CANCELLED_RESULT);
return reason;
})
.exhaustive();
gate.dispatch({ t: 'settled', navigation, outcome });
};
const urlRun = createRun(URL_KEY, executeUrlRun);
const abortUrl = (
navigation: Navigation,
reason: 'interrupted' | 'disposed'
) => {
const state = urlRun.getState();
const running = state.t !== 'idle' && state.navigation === navigation;
if (running) {
urlRun.dispatch({ t: 'abort', reason });
return;
}
// Turned away before it ran.
settle(navigation, CANCELLED_RESULT);
};
const revert = (
navigation: Navigation,
dispatch: (event: GateEvent) => void
) => {
const landed = navigation.revert?.();
fireAndForget(
mapMaybe(landed, () => dispatch({ t: 'revert-landed' })),
'split-router'
);
};
const executeGate = (
command: GateCommand,
dispatch: (event: GateEvent) => void
) => {
match(command)
.with({ t: 'run' }, ({ navigation }) =>
urlRun.dispatch({ t: 'navigate', navigation })
)
.with({ t: 'abort' }, ({ navigation, reason }) =>
abortUrl(navigation, reason)
)
.with({ t: 'revert' }, ({ navigation }) => revert(navigation, dispatch))
.with({ t: 'cancel-pane-runs' }, () => abortPanes('superseded'))
.with({ t: 'opened' }, release)
.exhaustive();
sweep();
};
const gate = createMachine<GateState, GateEvent, GateCommand>({
initial: { t: 'open' },
def: urlGateDef,
execute: executeGate,
});
/**
* Settles once pane actions may run: no commit is running and no URL
* navigation could replace the panes. Synchronous when nothing is in the
* way, including a revert that lands at once.
*/
const whenIdle = (): MaybePromise<void> => {
if (isOpen()) return;
// A running commit ends by itself; only a URL navigation needs to hear that an action waits.
if (committing === 0) gate.dispatch({ t: 'action' });
if (isOpen()) return;
const opened = new Promise<void>((resolve) => waiters.push(resolve));
fireAndForget(track(opened), 'split-router');
return opened;
};
/**
* Runs `work` once pane actions may run, or returns `disposed` after
* `dispose()`. Waking up is no promise: a URL navigation may have started
* since, so a woken action asks again.
*/
const act = <T>(
disposedValue: T,
work: () => MaybePromise<T>
): MaybePromise<T> => {
const idle = whenIdle();
if (isPromise(idle)) return mapMaybe(idle, () => act(disposedValue, work));
if (disposed) return disposedValue;
return untrack(work);
};
return {
/** Navigates one pane, replacing whatever that pane had in flight. */
start(pane: PaneId, navigation: Navigation) {
const begin = () => paneRun(pane).dispatch({ t: 'navigate', navigation });
return run(navigation, begin);
},
/** Starts a URL navigation; `blocking` makes pane actions wait instead of interrupting it. */
startUrl(navigation: Navigation, blocking: boolean) {
const begin = () => gate.dispatch({ t: 'start', navigation, blocking });
return run(navigation, begin);
},
/** Applies without guards or middleware. */
commitNow(navigation: Navigation): NavigationResult {
const entries = navigation.targets.map((target) => target.to);
return commit(navigation, entries);
},
whenIdle,
act,
abort,
/** The navigation `pane`'s own run has in flight, if any. */
inFlight(pane: PaneId): Navigation | undefined {
const state = findRun(pane)?.getState();
if (!state || state.t === 'idle') return;
return state.navigation;
},
isRunning(pane: PaneId): boolean {
const machine = findRun(pane);
if (!machine) return false;
return machine.getState().t !== 'idle';
},
pending: inFlight.pending,
/** Resolves once nothing is in flight. */
async settled(): Promise<void> {
while (outstanding.size > 0) {
await Promise.all(outstanding);
}
},
/** Cancels everything; waiting actions run and see the runner disposed. */
dispose(): void {
disposed = true;
gate.dispatch({ t: 'dispose' });
abortPanes('disposed');
for (const { machine } of paneRuns) {
machine.dispose();
}
paneRuns.length = 0;
urlRun.dispose();
},
};
}