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 type { IdentityBindingWire } from '../protocol';
/**
* Typed entry point for durable optimistic GraphQL mutations.
*
* Callers describe relation changes through generated query documents. The
* fluent selection is compiled to a constrained serializable recipe before
* it crosses SharedWorker, Tauri IPC, WASM, or durable queue boundaries.
*/
import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import {
type AnyVariables,
type Client,
CombinedError,
type Operation,
type OperationContext,
type OperationResult,
type OperationResultSource,
stringifyDocument,
} from '@urql/core';
import type { DocumentNode } from 'graphql';
import { validate as validateUuid } from 'uuid';
import type {
EmbeddedLinkPathSegment,
OptimisticLinkPatchWire,
QueryRevalidationWire,
} from '../protocol';
import {
documentOperationName,
type Present,
type StringKey,
} from './generated-selection';
import { selectRecords } from './record-selection';
/** Private operation-context field carrying serializable optimistic data. */
const OPTIMISTIC_MUTATION_CONTEXT_KEY = 'normalizedCacheOptimistic';
// Page-local acknowledgement; deliberately excluded from durable queue data.
const OPTIMISTIC_ENQUEUED_CONTEXT_KEY = 'normalizedCacheOptimisticEnqueued';
/** Private result-extension field carrying the queue disposition. */
const OPTIMISTIC_MUTATION_DISPOSITION_KEY =
'normalizedCacheMutationDisposition';
declare const selectionType: unique symbol;
declare const optimisticUpdateType: unique symbol;
type JsonScalar = string | number | boolean | null;
type ScalarKey<T> = {
[K in StringKey<T>]-?: Present<T[K]> extends JsonScalar ? K : never;
}[StringKey<T>];
type NumberKey<T> = {
[K in StringKey<T>]-?: Present<T[K]> extends number ? K : never;
}[StringKey<T>];
type ScalarInsertFields<T, TExcluded extends StringKey<T>> = Partial<{
[K in Exclude<ScalarKey<T>, TExcluded>]: Extract<
Exclude<T[K], undefined>,
JsonScalar
>;
}>;
type SelectionState = {
readonly document: TypedDocumentNode<unknown, AnyVariables>;
readonly variables: AnyVariables;
readonly path: readonly EmbeddedLinkPathSegment[];
readonly recordRoot?: OptimisticLinkPatchWire['recordRoot'];
};
/** A type-generated path through one query result. */
export type Selection<T> = SelectionState & {
/** Phantom result type retained across fluent path operations. */
readonly [selectionType]: T;
} & (Present<T> extends readonly (infer TItem)[]
? {
/** Selects exactly one list item by one generated scalar field. */
item<K extends ScalarKey<Present<TItem>>>(
field: K,
equals: Present<Present<TItem>[K]>
): Selection<Present<TItem>>;
}
: Present<T> extends object
? {
/** Selects a generated response field on the current object. */
field<K extends StringKey<Present<T>>>(
field: K
): Selection<Present<T>[K]>;
}
: object);
/** A generated selection whose current value is a list. */
export type ListSelection<TItem extends object> = Selection<readonly TItem[]>;
/** The only fields used to identify a normalized GraphQL entity. */
export type NormalizedEntityIdentity = {
__typename: string;
id: string;
};
type NormalizedEntityListKey<T> = {
[K in StringKey<T>]-?: Present<T[K]> extends readonly (infer TItem)[]
? Present<TItem> extends NormalizedEntityIdentity
? K
: never
: never;
}[StringKey<T>];
/** An idempotent change to a normalized-link list. */
export type LinkDiff =
| { kind: 'remove'; entity: NormalizedEntityIdentity }
| { kind: 'prependUnique'; entity: NormalizedEntityIdentity };
/** Opaque serializable cache update produced only by {@link update}. */
export type OptimisticUpdate = OptimisticLinkPatchWire & {
readonly [optimisticUpdateType]: true;
};
export type QueryRevalidation = {
document: DocumentNode;
variables: AnyVariables;
/** Recover incomplete relations without refetching successful local edits. */
onlyOnLinkFailure?: boolean;
};
export type OptimisticMutationOptions = {
/** Required RFC UUID; reuse only when the newer intent safely replaces the older one. */
uuid: string;
/** Opaque durable client correlation; never included in GraphQL variables. */
clientMetadata?: Record<string, unknown>;
identityBindings?: readonly IdentityBindingWire[];
/** Runs after durable layer installation, independently of HTTP settlement. */
onEnqueued?: () => void;
updates?: readonly OptimisticUpdate[];
/** Relevant queries that cannot safely be updated still revalidate on success. */
revalidations?: readonly QueryRevalidation[];
/** Calendar events whose occurrence set the mutation cannot predict. */
uncertainCalendarEventKeys?: readonly string[];
};
/** Existing records may be patched; newly created records must be complete. */
export type OptimisticResponse<T> = T extends readonly (infer Item)[]
? OptimisticResponse<Item>[]
: T extends object
? { [Key in keyof T]?: OptimisticResponse<T[Key]> }
: T;
/** Partial predicted records must retain their cache identity. */
export type OptimisticPatch<T> = T extends readonly (infer Item)[]
? OptimisticPatch<Item>[]
: T extends { id: string }
? { id: string } & { [K in Exclude<keyof T, 'id'>]?: OptimisticPatch<T[K]> }
: T extends object
? { [K in keyof T]?: OptimisticPatch<T[K]> }
: T;
export type OptimisticMutationContext<TData = unknown> = {
uuid: string;
optimisticResponse: TData;
/** Opaque durable client correlation; never included in GraphQL variables. */
clientMetadata?: Record<string, unknown>;
identityBindings?: IdentityBindingWire[];
linkPatches: OptimisticLinkPatchWire[];
revalidations: QueryRevalidationWire[];
uncertainCalendarEventKeys?: string[];
};
/** Caller-facing disposition of one durable optimistic mutation submission. */
export type OptimisticMutationDisposition<TData> =
| { kind: 'committed'; data: TData }
| { kind: 'queued'; transactionId: string }
| { kind: 'permanently-failed'; error: CombinedError };
/** Exchange-private metadata attached after queue routing or settlement. */
export type OptimisticMutationDispositionMetadata =
| { kind: 'committed'; transactionId?: string }
| { kind: 'queued'; transactionId: string }
| {
kind: 'superseded';
transactionId: string;
replacementTransactionId: string;
}
| { kind: 'permanently-failed'; transactionId?: string };
/** Returns a copy of an operation result carrying its queue disposition. */
export function withOptimisticMutationDisposition(
result: OperationResult,
disposition: OptimisticMutationDispositionMetadata
): OperationResult {
const queuedData =
disposition.kind === 'queued'
? optimisticContextOf(result.operation)?.optimisticResponse
: undefined;
return {
...result,
...(disposition.kind === 'queued'
? {
data: queuedData ?? result.data,
// A durable queued mutation is an accepted local write. Preserve the
// network failure in queue diagnostics, not as a caller-facing error
// that would roll back UI state or block the next edit.
error: undefined,
}
: disposition.kind === 'superseded'
? {
// The replacement's optimistic payload is already visible in the
// cache. Never expose this older operation's stale response.
data: undefined,
error: undefined,
}
: {}),
extensions: {
...result.extensions,
[OPTIMISTIC_MUTATION_DISPOSITION_KEY]: disposition,
},
};
}
/** Reads the typed caller-facing disposition attached by the cache exchange. */
export function optimisticMutationDispositionOf<
TData,
TVariables extends AnyVariables,
>(
result: OperationResult<TData, TVariables>
): OptimisticMutationDisposition<TData> | undefined {
const value: unknown =
result.extensions?.[OPTIMISTIC_MUTATION_DISPOSITION_KEY];
if (value === null || typeof value !== 'object' || !('kind' in value)) {
return undefined;
}
const metadata = value as OptimisticMutationDispositionMetadata;
if (metadata.kind === 'queued' && metadata.transactionId) {
return { kind: 'queued', transactionId: metadata.transactionId };
}
if (metadata.kind === 'superseded' && metadata.replacementTransactionId) {
return {
kind: 'queued',
transactionId: metadata.replacementTransactionId,
};
}
if (metadata.kind === 'committed' && result.data != null) {
return { kind: 'committed', data: result.data };
}
if (metadata.kind === 'permanently-failed') {
return {
kind: 'permanently-failed',
error:
result.error ??
new CombinedError({
graphQLErrors: [new Error('mutation returned no data')],
}),
};
}
return undefined;
}
function serializeRevalidation(
revalidation: QueryRevalidation
): QueryRevalidationWire {
return {
query: stringifyDocument(revalidation.document),
operationName: documentOperationName(revalidation.document),
variablesJson: JSON.stringify(revalidation.variables ?? {}),
...(revalidation.onlyOnLinkFailure ? { onlyOnLinkFailure: true } : {}),
};
}
function definedScalarFields(
fields: Readonly<Record<string, JsonScalar | undefined>>
): Record<string, JsonScalar> {
return Object.fromEntries(
Object.entries(fields).filter(
(entry): entry is [string, JsonScalar] => entry[1] !== undefined
)
);
}
function createSelection<T>(state: SelectionState): Selection<T> {
const selection = {
...state,
field(field: string) {
return createSelection({
...state,
path: [...state.path, { field }],
});
},
item(field: string, equals: JsonScalar) {
return createSelection({
...state,
path: [...state.path, { listItem: { whereField: field, equals } }],
});
},
};
return selection as unknown as Selection<T>;
}
/**
* Starts a strongly typed graph selection at a generated query operation.
* Variables and every subsequent path segment are inferred from the
* `TypedDocumentNode` generated by GraphQL Code Generator.
*/
export function select<TData, TVariables extends AnyVariables>(
document: TypedDocumentNode<TData, TVariables>,
variables: TVariables
): Selection<TData> {
return createSelection<TData>({
document: document as TypedDocumentNode<unknown, AnyVariables>,
variables,
path: [],
});
}
/**
* Starts a fragment-typed relation update at one explicit normalized record.
* It requires no cached query path and never enumerates unrelated query variants.
*/
export function selectRecord<
TData extends NormalizedEntityIdentity,
TVariables,
>(
document: TypedDocumentNode<TData, TVariables>,
entity: { __typename: TData['__typename']; id: string }
): Selection<TData> {
const fragment = selectRecords(document);
return createSelection<TData>({
document: document as TypedDocumentNode<unknown, AnyVariables>,
variables: {},
path: [],
recordRoot: {
fragmentName: fragment.fragmentName,
entityKey: normalizedEntityKey(entity),
},
});
}
/** Construct the wire key for one normalized `id: ID!` GraphQL entity. */
export function normalizedEntityKey(entity: NormalizedEntityIdentity): string {
return `${entity.__typename}:${entity.id}`;
}
/** Removes every occurrence of one normalized entity from a selected list. */
export function remove(entity: NormalizedEntityIdentity): LinkDiff {
return { kind: 'remove', entity };
}
/** Uniquely prepends one normalized entity to a selected list. */
export function prependUnique(entity: NormalizedEntityIdentity): LinkDiff {
return { kind: 'prependUnique', entity };
}
/** Compiles a generated graph selection and list diff into a durable update. */
export function update<TItem extends object>(
selection: ListSelection<TItem>,
operation: LinkDiff
): OptimisticUpdate {
return {
query: stringifyDocument(selection.document),
operationName: documentOperationName(selection.document),
variablesJson: JSON.stringify(selection.variables ?? {}),
path: [...selection.path],
...(selection.recordRoot ? { recordRoot: selection.recordRoot } : {}),
operation: {
kind: operation.kind,
entityKey: normalizedEntityKey(operation.entity),
},
} as OptimisticUpdate;
}
/**
* Upserts a logical list member using its matching mutation-response record.
* Settlement resolves the server's ID rather than persisting a temporary ID.
*/
export function upsertByField<TItem extends object, K extends ScalarKey<TItem>>(
selection: ListSelection<TItem>,
args: {
entity: NormalizedEntityIdentity;
whereField: K;
equals: Extract<Present<TItem[K]>, JsonScalar>;
}
): OptimisticUpdate {
const patch: OptimisticLinkPatchWire = {
query: stringifyDocument(selection.document),
operationName: documentOperationName(selection.document),
variablesJson: JSON.stringify(selection.variables ?? {}),
path: [...selection.path],
...(selection.recordRoot ? { recordRoot: selection.recordRoot } : {}),
operation: {
kind: 'upsertByField',
entityKey: normalizedEntityKey(args.entity),
whereField: args.whereField,
equals: args.equals,
},
};
return patch as OptimisticUpdate;
}
/**
* Removes an entity link from a selected embedded list item and decrements
* its count only when the link was present.
*/
export function removeEmbeddedLink<
TItem extends object,
TSelectorField extends ScalarKey<TItem>,
TLinkField extends NormalizedEntityListKey<TItem>,
TCountField extends NumberKey<TItem>,
>(
selection: ListSelection<TItem>,
args: {
listItem: {
whereField: TSelectorField;
equals: Extract<Present<TItem[TSelectorField]>, JsonScalar>;
};
linkField: TLinkField;
countField: TCountField;
entity: NormalizedEntityIdentity;
}
): OptimisticUpdate {
const update: OptimisticLinkPatchWire = {
query: stringifyDocument(selection.document),
operationName: documentOperationName(selection.document),
variablesJson: JSON.stringify(selection.variables ?? {}),
path: [...selection.path],
...(selection.recordRoot ? { recordRoot: selection.recordRoot } : {}),
operation: {
kind: 'removeEmbeddedLink',
listItem: args.listItem,
linkField: args.linkField,
countField: args.countField,
entityKey: normalizedEntityKey(args.entity),
},
};
return update as OptimisticUpdate;
}
/**
* Prepends an entity link inside a selected embedded list item, creating the
* embedded item from scalar fields when its selector does not exist. Its
* count is initialized or incremented only when the link is newly inserted.
*/
export function upsertEmbeddedLink<
TItem extends object,
TSelectorField extends ScalarKey<TItem>,
TLinkField extends NormalizedEntityListKey<TItem>,
TCountField extends NumberKey<TItem>,
>(
selection: ListSelection<TItem>,
args: {
listItem: {
whereField: TSelectorField;
equals: Extract<Present<TItem[TSelectorField]>, JsonScalar>;
};
linkField: TLinkField;
countField: TCountField;
entity: NormalizedEntityIdentity;
insertFields: ScalarInsertFields<
TItem,
TSelectorField | TCountField | TLinkField
>;
}
): OptimisticUpdate {
const update: OptimisticLinkPatchWire = {
query: stringifyDocument(selection.document),
operationName: documentOperationName(selection.document),
variablesJson: JSON.stringify(selection.variables ?? {}),
path: [...selection.path],
...(selection.recordRoot ? { recordRoot: selection.recordRoot } : {}),
operation: {
kind: 'upsertEmbeddedLink',
listItem: args.listItem,
linkField: args.linkField,
countField: args.countField,
entityKey: normalizedEntityKey(args.entity),
insertFields: definedScalarFields(args.insertFields),
},
};
return update as OptimisticUpdate;
}
/**
* Executes `document` with one durable optimistic entity/link transaction.
* The source resolves with the head's network result or a synthetic queued
* disposition when an older mutation currently blocks the operation.
*/
export function executeOptimisticMutation<
TData,
TVariables extends AnyVariables,
>(
client: Client,
document: TypedDocumentNode<TData, TVariables>,
variables: TVariables,
optimisticData: OptimisticResponse<NoInfer<TData>>,
options: OptimisticMutationOptions
): OperationResultSource<OperationResult<TData, TVariables>> {
return client.mutation(
document,
variables,
optimisticMutationContext(optimisticData, options)
);
}
/** Defaults to a fresh transaction; UUID reuse remains an explicit decision. */
export type OptimisticCallOptions = Omit<OptimisticMutationOptions, 'uuid'> & {
uuid?: string;
};
declare module '@urql/core' {
interface OperationContext {
/** Options for automatic optimistic recipes; false explicitly opts out. */
optimisticMutation?: OptimisticCallOptions | false;
}
}
/** Shared compiler used by mutation authoring interfaces and the legacy API. */
export function optimisticMutationContext<TData>(
optimisticData: TData,
options: OptimisticCallOptions = {}
): Partial<OperationContext> {
const uuid = options.uuid ?? crypto.randomUUID();
if (!validateUuid(uuid)) {
throw new TypeError(`invalid optimistic mutation UUID: ${uuid}`);
}
const context: OptimisticMutationContext<TData> = {
uuid,
clientMetadata: options.clientMetadata,
optimisticResponse: optimisticData,
identityBindings: options.identityBindings
? [...options.identityBindings]
: undefined,
linkPatches: [...(options.updates ?? [])],
revalidations: (options.revalidations ?? []).map(serializeRevalidation),
...(options.uncertainCalendarEventKeys?.length
? { uncertainCalendarEventKeys: [...options.uncertainCalendarEventKeys] }
: {}),
};
return {
[OPTIMISTIC_MUTATION_CONTEXT_KEY]: context,
...(options.onEnqueued
? { [OPTIMISTIC_ENQUEUED_CONTEXT_KEY]: options.onEnqueued }
: {}),
};
}
/** Acknowledge installation without allowing caller code to interrupt queue routing. */
export function notifyOptimisticMutationEnqueued(op: Operation): void {
const notify: unknown = op.context[OPTIMISTIC_ENQUEUED_CONTEXT_KEY];
if (typeof notify !== 'function') return;
try {
notify();
} catch (error) {
console.warn('Optimistic enqueue acknowledgement failed', error);
}
}
/** Reads and defensively validates the private context at the exchange edge. */
export function optimisticContextOf(
op: Operation
): OptimisticMutationContext | undefined {
const value: unknown = op.context[OPTIMISTIC_MUTATION_CONTEXT_KEY];
if (
value !== null &&
typeof value === 'object' &&
'optimisticResponse' in value
) {
const context = value as Partial<OptimisticMutationContext> & {
optimisticResponse: unknown;
};
if (typeof context.uuid !== 'string' || !validateUuid(context.uuid)) {
throw new TypeError(
'invalid optimistic mutation UUID in operation context'
);
}
return {
uuid: context.uuid,
clientMetadata: context.clientMetadata,
optimisticResponse: context.optimisticResponse,
identityBindings: context.identityBindings,
linkPatches: Array.isArray(context.linkPatches)
? context.linkPatches
: [],
revalidations: Array.isArray(context.revalidations)
? context.revalidations
: [],
uncertainCalendarEventKeys: Array.isArray(
context.uncertainCalendarEventKeys
)
? context.uncertainCalendarEventKeys
: undefined,
};
}
return undefined;
}