@task-mcp/shared 1.0.4 → 1.0.7

package/src/utils/projection.ts

@@ -0,0 +1,251 @@
+/**
+ * Projection Utilities
+ *
+ * Transform full objects into token-efficient projections.
+ * Reduces token usage by 70-88% for list operations.
+ */
+
+import type { Task } from "../schemas/task.js";
+import type { Project } from "../schemas/project.js";
+import type { InboxItem } from "../schemas/inbox.js";
+import type {
+  ResponseFormat,
+  TaskSummary,
+  TaskPreview,
+  ProjectSummary,
+  ProjectPreview,
+  InboxSummary,
+  InboxPreview,
+  PaginatedResponse,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+} from "../schemas/response-format.js";
+
+/**
+ * Project a single task to the specified format
+ */
+export function projectTask(task: Task, format: ResponseFormat): TaskSummary | TaskPreview | Task {
+  switch (format) {
+    case "concise":
+      return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        priority: task.priority,
+      };
+
+    case "standard":
+      return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        priority: task.priority,
+        dueDate: task.dueDate,
+        tags: task.tags,
+        contexts: task.contexts,
+        parentId: task.parentId,
+      };
+
+    case "detailed":
+    default:
+      return task;
+  }
+}
+
+/**
+ * Project multiple tasks with optional limit
+ */
+export function projectTasks(
+  tasks: Task[],
+  format: ResponseFormat,
+  limit?: number
+): (TaskSummary | TaskPreview | Task)[] {
+  const sliced = limit ? tasks.slice(0, limit) : tasks;
+  return sliced.map((task) => projectTask(task, format));
+}
+
+/**
+ * Project tasks with pagination
+ */
+export function projectTasksPaginated(
+  tasks: Task[],
+  format: ResponseFormat,
+  limit: number = 20,
+  offset: number = 0
+): PaginatedResponse<TaskSummary | TaskPreview | Task> {
+  const effectiveLimit = Math.min(limit, 100);
+  const sliced = tasks.slice(offset, offset + effectiveLimit);
+  const projected = sliced.map((task) => projectTask(task, format));
+
+  return {
+    items: projected,
+    total: tasks.length,
+    limit: effectiveLimit,
+    offset,
+    hasMore: offset + effectiveLimit < tasks.length,
+  };
+}
+
+/**
+ * Project a single project to the specified format
+ */
+export function projectProject(
+  project: Project,
+  format: ResponseFormat
+): ProjectSummary | ProjectPreview | Project {
+  switch (format) {
+    case "concise": {
+      const summary: ProjectSummary = {
+        id: project.id,
+        name: project.name,
+        status: project.status,
+      };
+      if (project.completionPercentage !== undefined) {
+        summary.completionPercentage = project.completionPercentage;
+      }
+      return summary;
+    }
+
+    case "standard": {
+      const preview: ProjectPreview = {
+        id: project.id,
+        name: project.name,
+        status: project.status,
+      };
+      if (project.completionPercentage !== undefined) {
+        preview.completionPercentage = project.completionPercentage;
+      }
+      if (project.description !== undefined) {
+        preview.description = project.description;
+      }
+      if (project.totalTasks !== undefined) {
+        preview.totalTasks = project.totalTasks;
+      }
+      if (project.completedTasks !== undefined) {
+        preview.completedTasks = project.completedTasks;
+      }
+      return preview;
+    }
+
+    case "detailed":
+    default:
+      return project;
+  }
+}
+
+/**
+ * Project multiple projects with optional limit
+ */
+export function projectProjects(
+  projects: Project[],
+  format: ResponseFormat,
+  limit?: number
+): (ProjectSummary | ProjectPreview | Project)[] {
+  const sliced = limit ? projects.slice(0, limit) : projects;
+  return sliced.map((project) => projectProject(project, format));
+}
+
+/**
+ * Project a single inbox item to the specified format
+ */
+export function projectInboxItem(
+  item: InboxItem,
+  format: ResponseFormat
+): InboxSummary | InboxPreview | InboxItem {
+  switch (format) {
+    case "concise":
+      return {
+        id: item.id,
+        content: item.content,
+        status: item.status,
+      };
+
+    case "standard":
+      return {
+        id: item.id,
+        content: item.content,
+        status: item.status,
+        capturedAt: item.capturedAt,
+        tags: item.tags,
+      };
+
+    case "detailed":
+    default:
+      return item;
+  }
+}
+
+/**
+ * Project multiple inbox items with optional limit
+ */
+export function projectInboxItems(
+  items: InboxItem[],
+  format: ResponseFormat,
+  limit?: number
+): (InboxSummary | InboxPreview | InboxItem)[] {
+  const sliced = limit ? items.slice(0, limit) : items;
+  return sliced.map((item) => projectInboxItem(item, format));
+}
+
+/**
+ * Format response based on format type
+ * - concise/standard: JSON string for machine processing
+ * - detailed: Human-readable text
+ */
+export function formatResponse<T>(
+  data: T | T[],
+  format: ResponseFormat,
+  detailedFormatter?: (data: T | T[]) => string
+): string {
+  if (format === "detailed" && detailedFormatter) {
+    return detailedFormatter(data);
+  }
+
+  // Concise and standard: compact JSON
+  return JSON.stringify(data);
+}
+
+/**
+ * Apply pagination parameters
+ */
+export function applyPagination<T>(
+  items: T[],
+  limit: number = 20,
+  offset: number = 0
+): { items: T[]; hasMore: boolean; total: number } {
+  const effectiveLimit = Math.min(Math.max(1, limit), 100);
+  const effectiveOffset = Math.max(0, offset);
+  const sliced = items.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+
+  return {
+    items: sliced,
+    hasMore: effectiveOffset + effectiveLimit < items.length,
+    total: items.length,
+  };
+}
+
+/**
+ * Truncate string for token efficiency
+ */
+export function truncate(str: string, maxLength: number = 100): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Summarize a list of items for token efficiency
+ */
+export function summarizeList<T>(
+  items: T[],
+  maxDisplay: number = 5,
+  getId: (item: T) => string
+): { displayed: T[]; remaining: number; remainingIds: string[] } {
+  const displayed = items.slice(0, maxDisplay);
+  const remaining = items.slice(maxDisplay);
+
+  return {
+    displayed,
+    remaining: remaining.length,
+    remainingIds: remaining.map(getId),
+  };
+}