[Phase 2] Define Queue and QueueManager interfaces/traits (API Contract)

js/.changeset/add-queue-interfaces.md

@@ -0,0 +1,15 @@
+---
+'links-queue-js': minor
+---
+
+Add Queue and QueueManager interfaces (API Contract)
+
+Phase 2 implementation defining the complete queue API contract:
+
+- Queue interface with enqueue, dequeue, peek, acknowledge, reject operations
+- QueueManager interface for queue lifecycle management
+- EnqueueResult, QueueStats, QueueOptions, QueueInfo types
+- QueueError class with typed error codes
+- QueueHandler and QueueSubscription types for consumer patterns
+
+This establishes the API contract that implementations must follow.

js/src/index.d.ts

@@ -165,3 +165,20 @@ export declare const delay: (ms: number) => Promise<void>;
 // =============================================================================
 
 export { MemoryLinkStore } from './backends/memory.d.ts';
+
+// =============================================================================
+// Queue Exports
+// =============================================================================
+
+export {
+  EnqueueResult,
+  QueueStats,
+  QueueOptions,
+  Queue,
+  QueueInfo,
+  QueueManager,
+  QueueErrorCode,
+  QueueError,
+  QueueHandler,
+  QueueSubscription,
+} from './queue/index.d.ts';

js/src/index.js

@@ -175,3 +175,9 @@ export const delay = (ms) =>
 // =============================================================================
 
 export { MemoryLinkStore } from './backends/memory.js';
+
+// =============================================================================
+// Queue Exports
+// =============================================================================
+
+export { QueueError } from './queue/index.js';

js/src/queue/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Queue module for links-queue.
+ *
+ * This module exports the Queue and QueueManager interfaces and related types
+ * for message queue operations built on top of the Link data model.
+ *
+ * @module queue
+ */
+
+export {
+  EnqueueResult,
+  QueueStats,
+  QueueOptions,
+  Queue,
+  QueueInfo,
+  QueueManager,
+  QueueErrorCode,
+  QueueError,
+  QueueHandler,
+  QueueSubscription,
+} from './types.ts';

js/src/queue/index.js

@@ -0,0 +1,11 @@
+/**
+ * Queue module for links-queue.
+ *
+ * This module exports the Queue and QueueManager interfaces and related types
+ * for message queue operations built on top of the Link data model.
+ *
+ * @module queue
+ */
+
+// Re-export the QueueError class for runtime usage
+export { QueueError } from './types.js';

js/src/queue/types.js

@@ -0,0 +1,49 @@
+/**
+ * Queue and QueueManager type definitions for links-queue.
+ *
+ * This module provides the QueueError class and type definitions for queue
+ * operations and queue management. These interfaces establish the API contract
+ * that implementations must follow.
+ *
+ * @module queue/types
+ *
+ * Design goals:
+ * - Build on top of LinkStore, adding queue-specific semantics
+ * - Support multiple queue patterns (point-to-point, pub/sub, etc.)
+ * - Provide reliability guarantees (at-least-once delivery, dead letter queues)
+ * - Maintain API parity between JavaScript and Rust implementations
+ *
+ * @see https://github.com/link-foundation/links-queue
+ * @see ARCHITECTURE.md - Queue Manager component
+ * @see REQUIREMENTS.md - REQ-API-001 through REQ-API-022
+ */
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/**
+ * Error thrown by queue operations.
+ *
+ * @example
+ * try {
+ *   await queue.enqueue(link);
+ * } catch (error) {
+ *   if (error instanceof QueueError && error.code === 'QUEUE_FULL') {
+ *     console.log('Queue is at capacity');
+ *   }
+ * }
+ */
+export class QueueError extends Error {
+  /**
+   * Creates a new QueueError.
+   *
+   * @param {string} code - Error code identifying the type of error
+   * @param {string} message - Human-readable error message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'QueueError';
+    this.code = code;
+  }
+}