@aleph-alpha/chat-kit 1.0.0 → 1.1.0

package/src/handlers/useMessageHandler.ts

@@ -0,0 +1,138 @@
+import {
+  generateId,
+  addNode as treeAddNode,
+  createEmptyTree,
+  getLinearPath,
+  navigate as treeNavigate,
+  updateNode,
+  updateNodeId,
+} from '../helpers';
+import type {
+  BaseMessage,
+  ConversationTree,
+  MessageRole,
+  MessageStatus,
+  TreeMessage,
+} from '../types';
+import { computed, reactive, readonly, ref, type Ref } from 'vue';
+
+export const useMessageHandler = () => {
+  const tree = reactive<ConversationTree>(createEmptyTree());
+  const currentUserMessage = ref('');
+
+  const messages = computed<BaseMessage[]>(() => getLinearPath(tree));
+
+  const currentLeafId = computed<string | null>(() => {
+    const list = messages.value;
+    return list.length > 0 ? list[list.length - 1].id : null;
+  });
+
+  function setCurrentUserMessage(text: string) {
+    currentUserMessage.value = text;
+  }
+
+  function clearCurrentUserMessage() {
+    currentUserMessage.value = '';
+  }
+
+  function commitUserMessage(): BaseMessage {
+    const id = generateId();
+    const text = currentUserMessage.value.trim();
+    if (!text) throw new Error('No message');
+
+    const node: TreeMessage = {
+      id,
+      parentId: currentLeafId.value,
+      childrenIds: [],
+      activeChildIndex: 0,
+      role: 'user',
+      content: text,
+      status: 'completed',
+      createdAt: new Date(),
+    };
+
+    treeAddNode(tree, node);
+    clearCurrentUserMessage();
+
+    return {
+      id: node.id,
+      role: node.role,
+      content: node.content,
+      createdAt: node.createdAt,
+      status: node.status,
+    };
+  }
+
+  function updateMessage(message: {
+    id: string;
+    content: string;
+    role: MessageRole;
+    status: MessageStatus;
+  }) {
+    const existing = tree.nodes[message.id];
+
+    if (existing) {
+      updateNode(tree, message.id, {
+        content: message.content,
+        role: message.role,
+        status: message.status,
+      });
+    } else {
+      const node: TreeMessage = {
+        id: message.id,
+        parentId: currentLeafId.value,
+        childrenIds: [],
+        activeChildIndex: 0,
+        role: message.role,
+        content: message.content,
+        status: message.status,
+        createdAt: new Date(),
+      };
+      treeAddNode(tree, node);
+    }
+  }
+
+  function getMessageById(id: string): BaseMessage | undefined {
+    const node = tree.nodes[id];
+    if (!node) return undefined;
+    return {
+      id: node.id,
+      role: node.role,
+      content: node.content,
+      createdAt: node.createdAt,
+      status: node.status,
+    };
+  }
+
+  function updateMessageId(oldId: string, newId: string) {
+    updateNodeId(tree, oldId, newId);
+  }
+
+  function clearMessages() {
+    Object.assign(tree, createEmptyTree());
+  }
+
+  function setTree(incoming: ConversationTree) {
+    tree.nodes = incoming.nodes;
+    tree.rootId = incoming.rootId;
+  }
+
+  function navigate(targetId: string) {
+    treeNavigate(tree, targetId);
+  }
+
+  return {
+    messages: messages as Ref<BaseMessage[]>,
+    currentUserMessage: readonly(currentUserMessage),
+    currentLeafId,
+    updateMessage,
+    setCurrentUserMessage,
+    getMessageById,
+    clearCurrentUserMessage,
+    commitUserMessage,
+    updateMessageId,
+    clearMessages,
+    setTree,
+    navigate,
+  };
+};

package/src/helpers/conversationTree.spec.ts

@@ -0,0 +1,423 @@
+import type { ConversationTree, TreeMessage } from '../types';
+import {
+  addNode,
+  createEmptyTree,
+  getLinearPath,
+  navigate,
+  updateNode,
+  updateNodeId,
+} from './conversationTree';
+
+function makeTreeMessage(
+  overrides: Partial<TreeMessage> & { id: string },
+): TreeMessage {
+  return {
+    parentId: null,
+    childrenIds: [],
+    activeChildIndex: 0,
+    role: 'user',
+    content: '',
+    status: 'completed',
+    createdAt: new Date('2025-01-01'),
+    ...overrides,
+  };
+}
+
+function makeTree(
+  nodes: Record<string, TreeMessage>,
+  rootId: string,
+): ConversationTree {
+  for (const node of Object.values(nodes)) {
+    node.childrenIds = [];
+  }
+  for (const node of Object.values(nodes)) {
+    if (node.parentId !== null) {
+      const parent = nodes[node.parentId];
+      if (parent) parent.childrenIds.push(node.id);
+    }
+  }
+  for (const node of Object.values(nodes)) {
+    node.activeChildIndex = 0;
+  }
+  return { nodes, rootId };
+}
+
+/**
+ * Builds a simple branching tree for tests:
+ *
+ *   root(u1)
+ *     ├─ a1 (assistant, child 0) [activeChildIndex=0 → u2]
+ *     │   └─ u2 [activeChildIndex=0 → a2]
+ *     │       ├─ a2 (child 0)
+ *     │       └─ a3 (child 1, regeneration of a2)
+ *     └─ a1b (assistant, child 1, regeneration of a1)
+ *         └─ u3
+ *
+ * Active path: u1 → a1 → u2 → a2 (activeChildIndex=0 everywhere)
+ */
+function makeBranchingTree(): ConversationTree {
+  return makeTree(
+    {
+      u1: makeTreeMessage({ id: 'u1', role: 'user', content: 'Hello' }),
+      a1: makeTreeMessage({
+        id: 'a1',
+        parentId: 'u1',
+        role: 'assistant',
+        content: 'Hi',
+      }),
+      u2: makeTreeMessage({
+        id: 'u2',
+        parentId: 'a1',
+        role: 'user',
+        content: 'Question',
+      }),
+      a2: makeTreeMessage({
+        id: 'a2',
+        parentId: 'u2',
+        role: 'assistant',
+        content: 'Answer 1',
+      }),
+      a3: makeTreeMessage({
+        id: 'a3',
+        parentId: 'u2',
+        role: 'assistant',
+        content: 'Answer 2',
+      }),
+      a1b: makeTreeMessage({
+        id: 'a1b',
+        parentId: 'u1',
+        role: 'assistant',
+        content: 'Alt hi',
+      }),
+      u3: makeTreeMessage({
+        id: 'u3',
+        parentId: 'a1b',
+        role: 'user',
+        content: 'Follow-up',
+      }),
+    },
+    'u1',
+  );
+}
+
+describe('createEmptyTree', () => {
+  it('returns an empty tree', () => {
+    const tree = createEmptyTree();
+    expect(tree.nodes).toEqual({});
+    expect(tree.rootId).toBeNull();
+  });
+});
+
+describe('getLinearPath', () => {
+  it('returns an empty array for an empty tree', () => {
+    expect(getLinearPath(createEmptyTree())).toEqual([]);
+  });
+
+  it('returns the active path from root following activeChildIndex', () => {
+    const tree = makeBranchingTree();
+    const path = getLinearPath(tree);
+
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a2']);
+  });
+
+  it('returns a different path after changing activeChildIndex', () => {
+    const tree = makeBranchingTree();
+    tree.nodes.u1.activeChildIndex = 1;
+    const path = getLinearPath(tree);
+
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1b', 'u3']);
+  });
+
+  it('enriches messages with siblingIds and siblingIndex when siblings exist', () => {
+    const tree = makeBranchingTree();
+    const path = getLinearPath(tree);
+
+    const a1Msg = path.find((m) => m.id === 'a1')!;
+    expect(a1Msg.siblingIds).toEqual(['a1', 'a1b']);
+    expect(a1Msg.siblingIndex).toBe(0);
+
+    const a2Msg = path.find((m) => m.id === 'a2')!;
+    expect(a2Msg.siblingIds).toEqual(['a2', 'a3']);
+    expect(a2Msg.siblingIndex).toBe(0);
+  });
+
+  it('does not set siblingIds for nodes without siblings', () => {
+    const tree = makeBranchingTree();
+    const path = getLinearPath(tree);
+
+    const u2Msg = path.find((m) => m.id === 'u2')!;
+    expect(u2Msg.siblingIds).toBeUndefined();
+    expect(u2Msg.siblingIndex).toBeUndefined();
+  });
+
+  it('does not set siblingIds on the root node', () => {
+    const tree = makeBranchingTree();
+    const path = getLinearPath(tree);
+
+    const rootMsg = path[0];
+    expect(rootMsg.id).toBe('u1');
+    expect(rootMsg.siblingIds).toBeUndefined();
+    expect(rootMsg.siblingIndex).toBeUndefined();
+  });
+
+  it('preserves message fields', () => {
+    const tree = makeBranchingTree();
+    const path = getLinearPath(tree);
+
+    const u1Msg = path[0];
+    expect(u1Msg.role).toBe('user');
+    expect(u1Msg.content).toBe('Hello');
+    expect(u1Msg.status).toBe('completed');
+    expect(u1Msg.createdAt).toEqual(new Date('2025-01-01'));
+  });
+});
+
+describe('addNode', () => {
+  it('adds the first node as root', () => {
+    const tree = createEmptyTree();
+    const node = makeTreeMessage({ id: 'u1', content: 'Hello' });
+
+    addNode(tree, node);
+
+    expect(tree.nodes.u1).toBe(node);
+    expect(tree.rootId).toBe('u1');
+  });
+
+  it('appends a child and updates parent.childrenIds', () => {
+    const tree = createEmptyTree();
+    addNode(tree, makeTreeMessage({ id: 'u1' }));
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a1', parentId: 'u1', role: 'assistant' }),
+    );
+
+    expect(tree.nodes.u1.childrenIds).toEqual(['a1']);
+  });
+
+  it('sets parent.activeChildIndex to point at the new child', () => {
+    const tree = createEmptyTree();
+    addNode(tree, makeTreeMessage({ id: 'u1' }));
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a1', parentId: 'u1', role: 'assistant' }),
+    );
+
+    expect(tree.nodes.u1.activeChildIndex).toBe(0);
+
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a2', parentId: 'u1', role: 'assistant' }),
+    );
+
+    expect(tree.nodes.u1.activeChildIndex).toBe(1);
+  });
+
+  it('makes the new node the last in the active path', () => {
+    const tree = createEmptyTree();
+    addNode(tree, makeTreeMessage({ id: 'u1' }));
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a1', parentId: 'u1', role: 'assistant' }),
+    );
+    addNode(tree, makeTreeMessage({ id: 'u2', parentId: 'a1' }));
+
+    const path = getLinearPath(tree);
+    expect(path[path.length - 1].id).toBe('u2');
+  });
+
+  it('supports adding sibling nodes (regeneration)', () => {
+    const tree = createEmptyTree();
+    addNode(tree, makeTreeMessage({ id: 'u1' }));
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a1', parentId: 'u1', role: 'assistant' }),
+    );
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'a2', parentId: 'u1', role: 'assistant' }),
+    );
+
+    expect(tree.nodes.u1.childrenIds).toEqual(['a1', 'a2']);
+    expect(tree.nodes.u1.activeChildIndex).toBe(1);
+
+    const path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a2']);
+  });
+});
+
+describe('updateNode', () => {
+  it('updates content of an existing node', () => {
+    const tree = makeBranchingTree();
+    updateNode(tree, 'a1', { content: 'Updated hi' });
+    expect(tree.nodes.a1.content).toBe('Updated hi');
+  });
+
+  it('updates status of an existing node', () => {
+    const tree = makeBranchingTree();
+    updateNode(tree, 'a1', { status: 'sending' });
+    expect(tree.nodes.a1.status).toBe('sending');
+  });
+
+  it('is a no-op for nonexistent id', () => {
+    const tree = makeBranchingTree();
+    const nodeCount = Object.keys(tree.nodes).length;
+    updateNode(tree, 'nonexistent', { content: 'x' });
+    expect(Object.keys(tree.nodes).length).toBe(nodeCount);
+  });
+});
+
+describe('updateNodeId', () => {
+  it('re-keys a node from old to new id', () => {
+    const tree = makeBranchingTree();
+    updateNodeId(tree, 'a2', 'a2-server');
+
+    expect(tree.nodes['a2-server']).toBeDefined();
+    expect(tree.nodes['a2']).toBeUndefined();
+    expect(tree.nodes['a2-server'].id).toBe('a2-server');
+  });
+
+  it('updates parent.childrenIds reference', () => {
+    const tree = makeBranchingTree();
+    updateNodeId(tree, 'a2', 'a2-server');
+
+    expect(tree.nodes.u2.childrenIds).toContain('a2-server');
+    expect(tree.nodes.u2.childrenIds).not.toContain('a2');
+  });
+
+  it('updates children.parentId references', () => {
+    const tree = makeBranchingTree();
+    updateNodeId(tree, 'u2', 'u2-server');
+
+    expect(tree.nodes.a2.parentId).toBe('u2-server');
+    expect(tree.nodes.a3.parentId).toBe('u2-server');
+  });
+
+  it('updates rootId when renaming the root', () => {
+    const tree = makeBranchingTree();
+    updateNodeId(tree, 'u1', 'u1-server');
+    expect(tree.rootId).toBe('u1-server');
+  });
+
+  it('is a no-op for nonexistent oldId', () => {
+    const tree = makeBranchingTree();
+    updateNodeId(tree, 'nonexistent', 'whatever');
+    expect(tree.nodes['whatever']).toBeUndefined();
+  });
+});
+
+describe('navigate', () => {
+  it('updates parent.activeChildIndex to the target sibling', () => {
+    const tree = makeBranchingTree();
+    expect(tree.nodes.u1.activeChildIndex).toBe(0);
+
+    navigate(tree, 'a1b');
+
+    expect(tree.nodes.u1.activeChildIndex).toBe(1);
+  });
+
+  it('changes the linear path accordingly', () => {
+    const tree = makeBranchingTree();
+
+    navigate(tree, 'a1b');
+
+    const path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1b', 'u3']);
+  });
+
+  it('navigating back restores the original path', () => {
+    const tree = makeBranchingTree();
+
+    navigate(tree, 'a1b');
+    navigate(tree, 'a1');
+
+    const path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a2']);
+  });
+
+  it('navigates between leaf siblings', () => {
+    const tree = makeBranchingTree();
+
+    navigate(tree, 'a3');
+    expect(tree.nodes.u2.activeChildIndex).toBe(1);
+
+    const path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a3']);
+  });
+
+  it('is a no-op for nonexistent targetId', () => {
+    const tree = makeBranchingTree();
+    const originalIndex = tree.nodes.u1.activeChildIndex;
+
+    navigate(tree, 'nonexistent');
+
+    expect(tree.nodes.u1.activeChildIndex).toBe(originalIndex);
+  });
+
+  it('is a no-op for root node (has no parent)', () => {
+    const tree = makeBranchingTree();
+
+    navigate(tree, 'u1');
+
+    expect(tree.nodes.u1.activeChildIndex).toBe(0);
+  });
+});
+
+describe('integration: full branching scenario', () => {
+  it('simulates send → regenerate → navigate workflow', () => {
+    const tree = createEmptyTree();
+
+    addNode(tree, makeTreeMessage({ id: 'u1', content: 'Hello' }));
+    addNode(
+      tree,
+      makeTreeMessage({
+        id: 'a1',
+        parentId: 'u1',
+        role: 'assistant',
+        content: 'Hi there',
+      }),
+    );
+    addNode(
+      tree,
+      makeTreeMessage({ id: 'u2', parentId: 'a1', content: 'Tell me more' }),
+    );
+    addNode(
+      tree,
+      makeTreeMessage({
+        id: 'a2',
+        parentId: 'u2',
+        role: 'assistant',
+        content: 'Sure thing',
+      }),
+    );
+
+    let path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a2']);
+
+    addNode(
+      tree,
+      makeTreeMessage({
+        id: 'a3',
+        parentId: 'u2',
+        role: 'assistant',
+        content: 'Certainly!',
+      }),
+    );
+
+    path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a3']);
+
+    navigate(tree, 'a2');
+    path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2', 'a2']);
+
+    const a2Msg = path.find((m) => m.id === 'a2')!;
+    expect(a2Msg.siblingIds).toEqual(['a2', 'a3']);
+    expect(a2Msg.siblingIndex).toBe(0);
+
+    navigate(tree, 'a3');
+    path = getLinearPath(tree);
+    const a3Msg = path.find((m) => m.id === 'a3')!;
+    expect(a3Msg.siblingIds).toEqual(['a2', 'a3']);
+    expect(a3Msg.siblingIndex).toBe(1);
+  });
+});

package/src/helpers/conversationTree.ts

@@ -0,0 +1,117 @@
+import type { BaseMessage, ConversationTree, TreeMessage } from '../types';
+
+export function createEmptyTree(): ConversationTree {
+  return { nodes: {}, rootId: null };
+}
+
+/**
+ * Walks from rootId following activeChildIndex at each node.
+ * Enriches each node with sibling metadata for the UI.
+ */
+export function getLinearPath(tree: ConversationTree): BaseMessage[] {
+  const { nodes, rootId } = tree;
+  if (!rootId || !nodes[rootId]) return [];
+
+  const path: BaseMessage[] = [];
+  let current: string | null = rootId;
+
+  while (current !== null) {
+    const node: TreeMessage | undefined = nodes[current];
+    if (!node) break;
+
+    const base: BaseMessage = {
+      id: node.id,
+      role: node.role,
+      content: node.content,
+      createdAt: node.createdAt,
+      status: node.status,
+    };
+
+    if (node.parentId !== null) {
+      const parent = nodes[node.parentId];
+      if (parent && parent.childrenIds.length > 1) {
+        base.siblingIds = [...parent.childrenIds];
+        base.siblingIndex = parent.childrenIds.indexOf(node.id);
+      }
+    }
+
+    path.push(base);
+
+    if (node.childrenIds.length === 0) break;
+    current = node.childrenIds[node.activeChildIndex];
+  }
+
+  return path;
+}
+
+export function addNode(tree: ConversationTree, node: TreeMessage): void {
+  tree.nodes[node.id] = node;
+
+  if (node.parentId !== null) {
+    const parent = tree.nodes[node.parentId];
+    if (parent && !parent.childrenIds.includes(node.id)) {
+      parent.childrenIds.push(node.id);
+      parent.activeChildIndex = parent.childrenIds.length - 1;
+    }
+  } else if (tree.rootId === null) {
+    tree.rootId = node.id;
+  }
+}
+
+export function updateNode(
+  tree: ConversationTree,
+  id: string,
+  updates: Partial<Pick<TreeMessage, 'content' | 'status' | 'role'>>,
+): void {
+  const node = tree.nodes[id];
+  if (!node) return;
+
+  if (updates.content !== undefined) node.content = updates.content;
+  if (updates.status !== undefined) node.status = updates.status;
+  if (updates.role !== undefined) node.role = updates.role;
+}
+
+export function updateNodeId(
+  tree: ConversationTree,
+  oldId: string,
+  newId: string,
+): void {
+  const node = tree.nodes[oldId];
+  if (!node) return;
+
+  delete tree.nodes[oldId];
+  node.id = newId;
+  tree.nodes[newId] = node;
+
+  if (node.parentId !== null) {
+    const parent = tree.nodes[node.parentId];
+    if (parent) {
+      const idx = parent.childrenIds.indexOf(oldId);
+      if (idx !== -1) parent.childrenIds[idx] = newId;
+    }
+  }
+
+  for (const childId of node.childrenIds) {
+    const child = tree.nodes[childId];
+    if (child) child.parentId = newId;
+  }
+
+  if (tree.rootId === oldId) tree.rootId = newId;
+}
+
+/**
+ * Navigate to a different branch by updating the parent's activeChildIndex
+ * to point at the target sibling.
+ */
+export function navigate(tree: ConversationTree, targetId: string): void {
+  const node = tree.nodes[targetId];
+  if (!node || node.parentId === null) return;
+
+  const parent = tree.nodes[node.parentId];
+  if (!parent) return;
+
+  const idx = parent.childrenIds.indexOf(targetId);
+  if (idx === -1) return;
+
+  parent.activeChildIndex = idx;
+}

package/src/helpers/generateId.ts

@@ -0,0 +1,5 @@
+export function generateId() {
+  return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+    ? crypto.randomUUID()
+    : String(Date.now());
+}

package/src/helpers/index.ts

@@ -0,0 +1,4 @@
+export * from './conversationTree';
+export * from './generateId';
+export * from './secondsToDate';
+export * from './toError';

package/src/helpers/secondsToDate.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert a unix timestamp in seconds to a `Date`. Useful when consuming
+ * APIs that return `created_at` / `updated_at` as integer seconds.
+ */
+export function secondsToDate(seconds: number): Date {
+  return new Date(seconds * 1000);
+}

package/src/helpers/toError.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalise an unknown thrown value into an `Error` instance.
+ * Wraps non-Error values (strings, plain objects, etc.) so callers can
+ * always rely on `.message` and a stable type.
+ */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}