@unrdf/kgc-runtime 26.4.2

package/src/projections-api.mjs

@@ -0,0 +1,336 @@
+/**
+ * @fileoverview Π_api - REST/GraphQL API Projections
+ * Transforms KGC structures into API-compatible formats with pagination and filtering
+ */
+
+import { z } from 'zod';
+
+/**
+ * API projection schema
+ */
+export const APIProjectionSchema = z.object({
+  type: z.literal('api'),
+  format: z.enum(['rest', 'graphql', 'json-api']),
+  data: z.any(),
+  meta: z.object({
+    pagination: z.object({
+      page: z.number(),
+      pageSize: z.number(),
+      total: z.number(),
+      totalPages: z.number(),
+    }).optional(),
+    filters: z.record(z.any()).optional(),
+    sort: z.array(z.object({
+      field: z.string(),
+      direction: z.enum(['asc', 'desc']),
+    })).optional(),
+  }).optional(),
+  links: z.object({
+    self: z.string().optional(),
+    first: z.string().optional(),
+    prev: z.string().optional(),
+    next: z.string().optional(),
+    last: z.string().optional(),
+  }).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof APIProjectionSchema>} APIProjection
+ */
+
+/**
+ * Pagination options
+ * @typedef {{page: number, pageSize: number}} PaginationOptions
+ */
+
+/**
+ * Filter options
+ * @typedef {Record<string, any>} FilterOptions
+ */
+
+/**
+ * Sort options
+ * @typedef {Array<{field: string, direction: 'asc' | 'desc'}>} SortOptions
+ */
+
+/**
+ * Project receipts to paginated REST API format
+ * @param {Array<import('./receipt.mjs').Receipt>} receipts - Receipts to project
+ * @param {PaginationOptions} pagination - Pagination options
+ * @param {FilterOptions} [filters] - Filter options
+ * @param {SortOptions} [sort] - Sort options
+ * @returns {APIProjection} API projection
+ */
+export function projectReceiptsToREST(receipts, pagination, filters = {}, sort = []) {
+  // Apply filters
+  let filtered = receipts;
+  for (const [key, value] of Object.entries(filters)) {
+    filtered = filtered.filter(r => r[key] === value);
+  }
+
+  // Apply sorting
+  if (sort.length > 0) {
+    filtered = filtered.sort((a, b) => {
+      for (const { field, direction } of sort) {
+        const aVal = a[field];
+        const bVal = b[field];
+        const comparison = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+        if (comparison !== 0) {
+          return direction === 'asc' ? comparison : -comparison;
+        }
+      }
+      return 0;
+    });
+  }
+
+  // Apply pagination
+  const total = filtered.length;
+  const totalPages = Math.ceil(total / pagination.pageSize);
+  const start = (pagination.page - 1) * pagination.pageSize;
+  const end = start + pagination.pageSize;
+  const paginated = filtered.slice(start, end);
+
+  // Serialize receipts
+  const data = paginated.map(r => ({
+    id: r.id,
+    type: 'receipt',
+    attributes: {
+      timestamp: r.timestamp,
+      operation: r.operation,
+      hash: r.hash,
+      parentHash: r.parentHash,
+    },
+    relationships: r.parentHash ? {
+      parent: {
+        data: { type: 'receipt', id: r.parentHash },
+      },
+    } : undefined,
+  }));
+
+  return APIProjectionSchema.parse({
+    type: 'api',
+    format: 'rest',
+    data,
+    meta: {
+      pagination: {
+        page: pagination.page,
+        pageSize: pagination.pageSize,
+        total,
+        totalPages,
+      },
+      filters,
+      sort,
+    },
+    links: {
+      self: `/receipts?page=${pagination.page}`,
+      first: '/receipts?page=1',
+      prev: pagination.page > 1 ? `/receipts?page=${pagination.page - 1}` : undefined,
+      next: pagination.page < totalPages ? `/receipts?page=${pagination.page + 1}` : undefined,
+      last: `/receipts?page=${totalPages}`,
+    },
+  });
+}
+
+/**
+ * Project work items to GraphQL format
+ * @param {Array<object>} workItems - Work items
+ * @param {object} [args] - GraphQL query arguments
+ * @returns {APIProjection} API projection
+ */
+export function projectWorkItemsToGraphQL(workItems, args = {}) {
+  // Apply GraphQL-style filtering
+  let filtered = workItems;
+
+  if (args.where) {
+    filtered = filtered.filter(item => {
+      for (const [key, value] of Object.entries(args.where)) {
+        if (item[key] !== value) return false;
+      }
+      return true;
+    });
+  }
+
+  // Apply GraphQL-style ordering
+  if (args.orderBy) {
+    filtered = filtered.sort((a, b) => {
+      const field = args.orderBy.field;
+      const direction = args.orderBy.direction || 'ASC';
+      const comparison = a[field] < b[field] ? -1 : a[field] > b[field] ? 1 : 0;
+      return direction === 'ASC' ? comparison : -comparison;
+    });
+  }
+
+  // Apply GraphQL-style pagination (skip/take)
+  if (args.skip !== undefined) {
+    filtered = filtered.slice(args.skip);
+  }
+  if (args.take !== undefined) {
+    filtered = filtered.slice(0, args.take);
+  }
+
+  const data = {
+    workItems: filtered.map(item => ({
+      id: item.id,
+      goal: item.goal,
+      state: item.state,
+      priority: item.priority,
+      createdAt: item.createdAt,
+      updatedAt: item.updatedAt,
+    })),
+    totalCount: workItems.length,
+    filteredCount: filtered.length,
+  };
+
+  return APIProjectionSchema.parse({
+    type: 'api',
+    format: 'graphql',
+    data,
+    meta: {
+      filters: args.where,
+      sort: args.orderBy ? [args.orderBy] : undefined,
+    },
+  });
+}
+
+/**
+ * Project single resource to JSON:API format
+ * @param {object} resource - Resource object
+ * @param {string} resourceType - Resource type
+ * @param {Record<string, any>} [relationships] - Resource relationships
+ * @returns {APIProjection} API projection
+ */
+export function projectResourceToJSONAPI(resource, resourceType, relationships = {}) {
+  const { id, ...attributes } = resource;
+
+  const relationshipData = {};
+  for (const [key, value] of Object.entries(relationships)) {
+    if (Array.isArray(value)) {
+      relationshipData[key] = {
+        data: value.map(v => ({ type: v.type, id: v.id })),
+      };
+    } else if (value) {
+      relationshipData[key] = {
+        data: { type: value.type, id: value.id },
+      };
+    }
+  }
+
+  return APIProjectionSchema.parse({
+    type: 'api',
+    format: 'json-api',
+    data: {
+      type: resourceType,
+      id,
+      attributes,
+      relationships: Object.keys(relationshipData).length > 0 ? relationshipData : undefined,
+    },
+    links: {
+      self: `/${resourceType}/${id}`,
+    },
+  });
+}
+
+/**
+ * Apply filtering to array of objects
+ * @param {Array<Record<string, any>>} items - Items to filter
+ * @param {FilterOptions} filters - Filter criteria
+ * @returns {Array<Record<string, any>>} Filtered items
+ */
+export function applyFilters(items, filters) {
+  if (!filters || Object.keys(filters).length === 0) {
+    return items;
+  }
+
+  return items.filter(item => {
+    for (const [key, value] of Object.entries(filters)) {
+      // Support operators: eq, ne, gt, lt, contains, in
+      if (typeof value === 'object' && value !== null) {
+        const itemValue = item[key];
+
+        if ('eq' in value && itemValue !== value.eq) return false;
+        if ('ne' in value && itemValue === value.ne) return false;
+        if ('gt' in value && itemValue <= value.gt) return false;
+        if ('lt' in value && itemValue >= value.lt) return false;
+        if ('contains' in value && !String(itemValue).includes(value.contains)) return false;
+        if ('in' in value && !value.in.includes(itemValue)) return false;
+      } else {
+        if (item[key] !== value) return false;
+      }
+    }
+    return true;
+  });
+}
+
+/**
+ * Apply sorting to array of objects
+ * @param {Array<Record<string, any>>} items - Items to sort
+ * @param {SortOptions} sort - Sort criteria
+ * @returns {Array<Record<string, any>>} Sorted items
+ */
+export function applySorting(items, sort) {
+  if (!sort || sort.length === 0) {
+    return items;
+  }
+
+  return [...items].sort((a, b) => {
+    for (const { field, direction } of sort) {
+      const aVal = a[field];
+      const bVal = b[field];
+
+      let comparison = 0;
+      if (aVal < bVal) comparison = -1;
+      else if (aVal > bVal) comparison = 1;
+
+      if (comparison !== 0) {
+        return direction === 'asc' ? comparison : -comparison;
+      }
+    }
+    return 0;
+  });
+}
+
+/**
+ * Apply pagination to array
+ * @param {Array<any>} items - Items to paginate
+ * @param {PaginationOptions} pagination - Pagination options
+ * @returns {{data: Array<any>, meta: object}} Paginated result
+ */
+export function applyPagination(items, pagination) {
+  const total = items.length;
+  const totalPages = Math.ceil(total / pagination.pageSize);
+  const start = (pagination.page - 1) * pagination.pageSize;
+  const end = start + pagination.pageSize;
+  const data = items.slice(start, end);
+
+  return {
+    data,
+    meta: {
+      pagination: {
+        page: pagination.page,
+        pageSize: pagination.pageSize,
+        total,
+        totalPages,
+      },
+    },
+  };
+}
+
+/**
+ * Build HATEOAS links for resource
+ * @param {string} resourceType - Resource type
+ * @param {string} resourceId - Resource ID
+ * @param {Array<{rel: string, href: string}>} [additional=[]] - Additional links
+ * @returns {Record<string, string>} HATEOAS links
+ */
+export function buildHATEOASLinks(resourceType, resourceId, additional = []) {
+  const links = {
+    self: `/${resourceType}/${resourceId}`,
+    collection: `/${resourceType}`,
+  };
+
+  for (const link of additional) {
+    links[link.rel] = link.href;
+  }
+
+  return links;
+}

package/src/projections-cli.mjs

@@ -0,0 +1,238 @@
+/**
+ * @fileoverview Π_cli - Command-line Interface Projections
+ * Transforms KGC data structures into CLI-friendly formats with ANSI colors and tables
+ */
+
+import { z } from 'zod';
+
+/**
+ * ANSI color codes for terminal output
+ * @constant
+ */
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+};
+
+/**
+ * CLI projection schema
+ */
+export const CLIProjectionSchema = z.object({
+  type: z.literal('cli'),
+  format: z.enum(['table', 'list', 'tree', 'summary']),
+  colored: z.boolean().default(true),
+  content: z.string(),
+  metadata: z.record(z.any()).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof CLIProjectionSchema>} CLIProjection
+ */
+
+/**
+ * Colorize text with ANSI codes
+ * @param {string} text - Text to colorize
+ * @param {keyof typeof COLORS} color - Color name
+ * @param {boolean} colored - Whether to apply colors
+ * @returns {string} Colorized text
+ */
+function colorize(text, color, colored = true) {
+  if (!colored) return text;
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+/**
+ * Project receipt to CLI-friendly format
+ * @param {import('./receipt.mjs').Receipt} receipt - Receipt to project
+ * @param {boolean} [colored=true] - Whether to use ANSI colors
+ * @returns {CLIProjection} CLI projection
+ */
+export function projectReceiptToCLI(receipt, colored = true) {
+  const lines = [
+    colorize('━'.repeat(60), 'cyan', colored),
+    colorize('Receipt:', 'bright', colored) + ` ${receipt.id}`,
+    colorize('Operation:', 'blue', colored) + ` ${receipt.operation}`,
+    colorize('Timestamp:', 'dim', colored) + ` ${receipt.timestamp}`,
+    colorize('Hash:', 'magenta', colored) + ` ${receipt.hash.slice(0, 16)}...`,
+  ];
+
+  if (receipt.parentHash) {
+    lines.push(colorize('Parent:', 'dim', colored) + ` ${receipt.parentHash.slice(0, 16)}...`);
+  }
+
+  lines.push(colorize('━'.repeat(60), 'cyan', colored));
+
+  const content = lines.join('\n');
+
+  return CLIProjectionSchema.parse({
+    type: 'cli',
+    format: 'summary',
+    colored,
+    content,
+    metadata: { receiptId: receipt.id },
+  });
+}
+
+/**
+ * Project work item to CLI table format
+ * @param {Array<{id: string, goal: string, state: string, priority?: number}>} workItems - Work items
+ * @param {boolean} [colored=true] - Whether to use ANSI colors
+ * @returns {CLIProjection} CLI projection
+ */
+export function projectWorkItemsToCLI(workItems, colored = true) {
+  if (!Array.isArray(workItems) || workItems.length === 0) {
+    return CLIProjectionSchema.parse({
+      type: 'cli',
+      format: 'table',
+      colored,
+      content: colorize('No work items', 'dim', colored),
+    });
+  }
+
+  // Table header
+  const header = [
+    colorize('ID', 'bright', colored).padEnd(colored ? 25 : 15),
+    colorize('Goal', 'bright', colored).padEnd(colored ? 45 : 35),
+    colorize('State', 'bright', colored).padEnd(colored ? 20 : 10),
+    colorize('Priority', 'bright', colored),
+  ].join(' │ ');
+
+  const separator = colorize('─'.repeat(100), 'dim', colored);
+
+  // Table rows
+  const rows = workItems.map((item) => {
+    const stateColor =
+      item.state === 'completed' ? 'green' :
+      item.state === 'failed' ? 'red' :
+      item.state === 'running' ? 'yellow' : 'dim';
+
+    return [
+      item.id.slice(0, 12).padEnd(15),
+      item.goal.slice(0, 32).padEnd(35),
+      colorize(item.state.padEnd(10), stateColor, colored),
+      (item.priority ?? 0).toString(),
+    ].join(' │ ');
+  });
+
+  const content = [header, separator, ...rows, separator].join('\n');
+
+  return CLIProjectionSchema.parse({
+    type: 'cli',
+    format: 'table',
+    colored,
+    content,
+    metadata: { count: workItems.length },
+  });
+}
+
+/**
+ * Project nested structure to tree format
+ * @param {Record<string, any>} data - Nested data structure
+ * @param {boolean} [colored=true] - Whether to use ANSI colors
+ * @param {string} [prefix=''] - Internal prefix for recursion
+ * @param {boolean} [isLast=true] - Internal flag for recursion
+ * @returns {string} Tree representation
+ */
+function renderTree(data, colored = true, prefix = '', isLast = true) {
+  const lines = [];
+  const entries = Object.entries(data);
+
+  entries.forEach(([key, value], index) => {
+    const isLastEntry = index === entries.length - 1;
+    const connector = isLast ? '└── ' : '├── ';
+    const extension = isLast ? '    ' : '│   ';
+
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      lines.push(prefix + connector + colorize(key, 'cyan', colored));
+      lines.push(renderTree(value, colored, prefix + extension, isLastEntry));
+    } else {
+      const displayValue = Array.isArray(value) ? `[${value.length} items]` : String(value);
+      lines.push(
+        prefix + connector +
+        colorize(key, 'blue', colored) + ': ' +
+        colorize(displayValue, 'white', colored)
+      );
+    }
+  });
+
+  return lines.join('\n');
+}
+
+/**
+ * Project object to tree format
+ * @param {Record<string, any>} obj - Object to project
+ * @param {boolean} [colored=true] - Whether to use ANSI colors
+ * @returns {CLIProjection} CLI projection
+ */
+export function projectObjectToTree(obj, colored = true) {
+  const content = renderTree(obj, colored);
+
+  return CLIProjectionSchema.parse({
+    type: 'cli',
+    format: 'tree',
+    colored,
+    content,
+  });
+}
+
+/**
+ * Project array to numbered list
+ * @param {Array<string | {label: string, description?: string}>} items - Items to project
+ * @param {boolean} [colored=true] - Whether to use ANSI colors
+ * @returns {CLIProjection} CLI projection
+ */
+export function projectArrayToList(items, colored = true) {
+  const lines = items.map((item, index) => {
+    const num = colorize(`${index + 1}.`, 'cyan', colored);
+
+    if (typeof item === 'string') {
+      return `${num} ${item}`;
+    }
+
+    const label = colorize(item.label, 'bright', colored);
+    const desc = item.description ?
+      '\n   ' + colorize(item.description, 'dim', colored) : '';
+
+    return `${num} ${label}${desc}`;
+  });
+
+  const content = lines.join('\n');
+
+  return CLIProjectionSchema.parse({
+    type: 'cli',
+    format: 'list',
+    colored,
+    content,
+    metadata: { count: items.length },
+  });
+}
+
+/**
+ * Flatten nested object for CLI display
+ * @param {Record<string, any>} obj - Object to flatten
+ * @param {string} [prefix=''] - Key prefix for recursion
+ * @returns {Record<string, any>} Flattened object
+ */
+export function flattenForCLI(obj, prefix = '') {
+  const flattened = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      Object.assign(flattened, flattenForCLI(value, fullKey));
+    } else {
+      flattened[fullKey] = value;
+    }
+  }
+
+  return flattened;
+}