Add basic examples (1-4) for JS and Rust

js/examples/01-hello-world/README.md

@@ -0,0 +1,68 @@
+# Hello World Example
+
+This example demonstrates the most basic usage of Links Queue: simple enqueue and dequeue operations.
+
+## Key Concepts
+
+- **Link**: The fundamental data unit with `id`, `source`, and `target` fields
+- **LinksQueue**: A FIFO queue that holds links for processing
+- **Enqueue/Dequeue**: Standard queue operations to add and remove items
+- **Acknowledge**: Confirm that a dequeued item was processed successfully
+
+## Running the Example
+
+```bash
+# Node.js
+node examples/01-hello-world/index.js
+
+# Bun
+bun examples/01-hello-world/index.js
+
+# Deno
+deno run examples/01-hello-world/index.js
+```
+
+## Expected Output
+
+```
+=== Links Queue: Hello World ===
+
+Created links:
+  Greeting: { id: 1, source: 'hello', target: 'world' }
+  Message: { id: 2, source: 'links', target: 'queue' }
+  Data: { id: 3, source: 42, target: 100 }
+
+--- Enqueuing links ---
+Enqueued link 1 at position 0
+Enqueued link 2 at position 1
+Enqueued link 3 at position 2
+
+Queue stats after enqueueing:
+  Depth: 3
+  Enqueued: 3
+
+--- Dequeuing and processing ---
+Processing: hello -> world
+Acknowledged link 1
+Processing: links -> queue
+Acknowledged link 2
+Processing: 42 -> 100
+Acknowledged link 3
+
+Final queue stats:
+  Depth: 0
+  Enqueued: 3
+  Dequeued: 3
+  Acknowledged: 3
+
+Dequeue from empty queue: null
+
+=== Hello World Complete! ===
+```
+
+## What This Example Shows
+
+1. **Creating Links**: Links can have various types for source and target (strings, numbers)
+2. **Queue Setup**: How to create a `LinksQueue` with a `MemoryLinkStore` backend
+3. **FIFO Processing**: Items are processed in the order they were enqueued
+4. **Acknowledgment Pattern**: The dequeue-process-acknowledge workflow for reliable processing

js/examples/01-hello-world/index.js

@@ -0,0 +1,107 @@
+/**
+ * Hello World Example for links-queue
+ *
+ * This example demonstrates basic enqueue/dequeue operations using
+ * the links-queue library. It shows how to:
+ * - Create a queue
+ * - Enqueue links (messages)
+ * - Dequeue links
+ * - Acknowledge processed items
+ *
+ * Run with any runtime:
+ * - Node.js: node examples/01-hello-world/index.js
+ * - Bun: bun examples/01-hello-world/index.js
+ * - Deno: deno run examples/01-hello-world/index.js
+ */
+
+import { createLink, MemoryLinkStore, LinksQueue } from '../../src/index.js';
+
+async function main() {
+  console.log('=== Links Queue: Hello World ===\n');
+
+  // Create a MemoryLinkStore for storing links
+  const store = new MemoryLinkStore();
+
+  // Create a queue with basic configuration
+  const queue = new LinksQueue({
+    name: 'hello-world',
+    store,
+    options: {
+      visibilityTimeout: 30, // seconds
+      retryLimit: 3,
+    },
+  });
+
+  // Create some links to enqueue
+  // Links are the fundamental data unit - they have id, source, and target
+  const greetingLink = createLink(1, 'hello', 'world');
+  const messageLink = createLink(2, 'links', 'queue');
+  const dataLink = createLink(3, 42, 100);
+
+  console.log('Created links:');
+  console.log('  Greeting:', greetingLink);
+  console.log('  Message:', messageLink);
+  console.log('  Data:', dataLink);
+
+  // Enqueue links
+  console.log('\n--- Enqueuing links ---');
+  const result1 = await queue.enqueue(greetingLink);
+  console.log(`Enqueued link 1 at position ${result1.position}`);
+
+  const result2 = await queue.enqueue(messageLink);
+  console.log(`Enqueued link 2 at position ${result2.position}`);
+
+  const result3 = await queue.enqueue(dataLink);
+  console.log(`Enqueued link 3 at position ${result3.position}`);
+
+  // Check queue stats
+  const stats = queue.getStats();
+  console.log('\nQueue stats after enqueueing:');
+  console.log(`  Depth: ${stats.depth}`);
+  console.log(`  Enqueued: ${stats.enqueued}`);
+
+  // Dequeue and process links
+  console.log('\n--- Dequeuing and processing ---');
+
+  // Dequeue first link
+  const item1 = await queue.dequeue();
+  if (item1) {
+    console.log(`Processing: ${item1.source} -> ${item1.target}`);
+    // Acknowledge successful processing
+    await queue.acknowledge(item1.id);
+    console.log(`Acknowledged link ${item1.id}`);
+  }
+
+  // Dequeue second link
+  const item2 = await queue.dequeue();
+  if (item2) {
+    console.log(`Processing: ${item2.source} -> ${item2.target}`);
+    await queue.acknowledge(item2.id);
+    console.log(`Acknowledged link ${item2.id}`);
+  }
+
+  // Dequeue third link
+  const item3 = await queue.dequeue();
+  if (item3) {
+    console.log(`Processing: ${item3.source} -> ${item3.target}`);
+    await queue.acknowledge(item3.id);
+    console.log(`Acknowledged link ${item3.id}`);
+  }
+
+  // Final stats
+  const finalStats = queue.getStats();
+  console.log('\nFinal queue stats:');
+  console.log(`  Depth: ${finalStats.depth}`);
+  console.log(`  Enqueued: ${finalStats.enqueued}`);
+  console.log(`  Dequeued: ${finalStats.dequeued}`);
+  console.log(`  Acknowledged: ${finalStats.acknowledged}`);
+
+  // Try to dequeue from empty queue
+  const empty = await queue.dequeue();
+  console.log(`\nDequeue from empty queue: ${empty}`); // null
+
+  console.log('\n=== Hello World Complete! ===');
+}
+
+// Run the example
+main().catch(console.error);

js/examples/02-link-relationships/README.md

@@ -0,0 +1,98 @@
+# Link Relationships Example
+
+This example demonstrates nested links and graph structures - the unique link-based data model that distinguishes Links Queue from traditional message queues.
+
+## Key Concepts
+
+- **Links as Relations**: Each link represents a directed relationship from source to target
+- **Nested Links**: Source and target can themselves be links, enabling hierarchical data
+- **Universal Links**: Links with additional values for n-ary relationships
+- **Graph Structures**: Multiple links form a graph that can be traversed and queried
+
+## Running the Example
+
+```bash
+# Node.js
+node examples/02-link-relationships/index.js
+
+# Bun
+bun examples/02-link-relationships/index.js
+
+# Deno
+deno run examples/02-link-relationships/index.js
+```
+
+## Expected Output
+
+```
+=== Links Queue: Link Relationships ===
+
+--- Part 1: Basic Links as Relations ---
+
+Alice knows Bob: { id: 1, source: 'alice', target: 'bob' }
+Alice person link: { id: 2, source: 100, target: 'alice' }
+Alice name link: { id: 3, source: { id: 2, source: 100, target: 'alice' }, target: 'Alice Smith' }
+
+--- Part 2: Nested Links (Recursive Structures) ---
+
+Nested link (statement about relationship):
+  Base: { id: 10, source: 'alice', target: 'bob' }
+  Meta: { id: 11, source: { id: 10, source: 'alice', target: 'bob' }, target: 2024 }
+  Established relationship: alice -> bob
+  In year: 2024
+
+--- Part 3: Universal Links (Multiple Values) ---
+
+Universal link (n-ary relation): { id: 20, source: 'Earth', target: 'orbits', values: [ 'Sun', 0.999, 'astronomy' ] }
+  Subject: Earth
+  Predicate: orbits
+  Additional values: [ 'Sun', 0.999, 'astronomy' ]
+
+--- Part 4: Graph Structures ---
+
+Social graph edges:
+  alice -> bob
+  bob -> charlie
+  alice -> charlie
+  charlie -> alice
+
+Alice is connected to:
+  bob
+  charlie
+
+Charlie receives connections from:
+  bob
+  alice
+
+--- Part 5: Processing Graph Operations via Queue ---
+
+Queued: add_edge node1->node2
+Queued: add_edge node2->node3
+Queued: query {"source":"node1","target":{}}
+Queued: remove_edge node1->node2
+
+Processing operations:
+  ADD: node1 -> node2
+  ADD: node2 -> node3
+  QUERY: source=node1
+  REMOVE: node1 -> node2
+
+=== Link Relationships Complete! ===
+```
+
+## What This Example Shows
+
+1. **Binary Relations**: Simple A -> B relationships (social connections, edges)
+2. **Typed Links**: Using numeric IDs to represent types and properties
+3. **Meta-Links**: Links about other links (provenance, timestamps)
+4. **N-ary Relations**: Universal links with values array for complex relations
+5. **Graph Building**: Constructing and querying graph structures
+6. **Queue Integration**: Processing graph operations through a queue
+
+## Use Cases
+
+- Knowledge graphs and semantic data
+- Social network relationships
+- Provenance tracking (who said what, when)
+- Complex event processing with metadata
+- Graph database operations via message queue