99 setup base docs and example (#118)

* update readme with basic docs  publish and consume

* update readme

* update example with basic publish/consume

* add effective package to example

* align package.json

* chore: minor cleanup

* chore: removed not ready for prod in readme

* fix: fixed example

* fix some typos

* change example to use file package

---------

Co-authored-by: Luca <[email protected]>

Author: albertobarrila

README.md

@@ -1,23 +1,34 @@
 # RabbitMQ client for the stream protocol for Node.JS
 
-# NOT READY FOR PRODUCTION - The client is HEAVILY work in progress.
-
 [![Build Status](https://github.com/coders51/rabbitmq-stream-js-client/actions/workflows/main.yml/badge.svg)](https://github.com/coders51/rabbitmq-stream-js-client/actions)
 
-# Table of Contents
+## Table of Contents
 
-- [Overview](#overview)
-- [Installing via NPM](#installing-via-npm)
-- [Getting started](#getting-started)
+- [RabbitMQ client for the stream protocol for Node.JS](#rabbitmq-client-for-the-stream-protocol-for-nodejs)
+  - [Overview](#overview)
+  - [Installing via NPM](#installing-via-npm)
+  - [Getting started](#getting-started)
   - [Usage](#usage)
     - [Connect](#connect)
-- [Build from source](#build-from-source)
-- [Project Status](#project-status)
-- [Release Process](#release-process)
+    - [Basic Publish](#basic-publish)
+    - [Basic Consuming](#basic-consuming)
+  - [Running Examples](#running-examples)
+  - [Build from source](#build-from-source)
+  - [MISC](#misc)
+
+## Overview
+
+A client for the RabbitMQ stream protocol, written (and ready for) Typescript
+
+## Installing via NPM
+
+```shell
+npm install rabbitmq-stream-js-client
+```
 
 ## Getting started
 
-A rapid getting started
+A quick getting started
 
 ```typescript
 const rabbit = require("rabbitmq-stream-js-client")
@@ -59,31 +70,95 @@ const client = await connect({
 await client.close()
 ```
 
+### Basic Publish
+
+```typescript
+const client = await connect({
+  hostname: "localhost",
+  port: 5552,
+  username: "rabbit",
+  password: "rabbit",
+  vhost: "/",
+})
+
+const publisher = await client.declarePublisher({
+  stream: "stream-name",
+  publisherRef: "my-publisher",
+})
+
+await publisher.send(Buffer.from("my message content"))
+
+// ...
+
+await client.close()
+```
+
+### Basic Consuming
+
+```typescript
+const client = await connect({
+  hostname: "localhost",
+  port: 5552,
+  username: "rabbit",
+  password: "rabbit",
+  vhost: "/",
+})
+
+const consumerOptions = { stream: "stream-name", offset: Offset.next() }  // see docs for various offset types
+
+const consumer = await client.declareConsumer(consumerOptions, (message: Message) => {
+  console.log(message.content) // it's a Buffer 
+})
+
+// ...
+
+await client.close()
+```
+
+## Running Examples
+
+the folder /example contains a project that shows some examples on how to use the lib, to run it follow this steps
+
+move to the example folder and install the dependencies
+
+```shell
+cd example
+npm i
+```
+
+run the docker-compose to launch a rabbit instance already stream enabled
+
+```shell
+docker-compose up -d 
+```
+
+then launch the examples
+
+```shell
+npm start
+```
+
 ## Build from source
 
 Build:
 
 ```shell
-$ npm run build
+npm run build
 ```
 
 Test:
 
 ```shell
-$ docker-compose up -d
-$ npm run test
+docker-compose up -d
+npm run test
 ```
 
 Check everything:
 
 ```shell
-$ npm run check
+npm run check
 ```
 
-## Project Status
-
-The client is HEAVILY work in progress. The API(s) could change prior to version `1.0.0`
-
 ## MISC
 
-https://github.com/rabbitmq/rabbitmq-server/blob/master/deps/rabbitmq_stream/docs/PROTOCOL.adoc
+<https://github.com/rabbitmq/rabbitmq-server/blob/master/deps/rabbitmq_stream/docs/PROTOCOL.adoc>

example/docker-compose.yaml

@@ -0,0 +1,17 @@
+version: "2"
+
+services:
+  rabbitmq-stream:
+    image: rabbitmq:3-management
+    container_name: rabbitmq-stream
+    restart: unless-stopped
+    hostname: "rabbitmq"
+    ports:
+      - "15672:15672"
+      - "5672:5672"
+      - "5552:5552"
+    environment:
+      RABBITMQ_DEFAULT_USER: "rabbit"
+      RABBITMQ_DEFAULT_PASS: "rabbit"
+    volumes:
+      - ../conf/enabled_plugins:/etc/rabbitmq/enabled_plugins

example/index.js

@@ -1,13 +1,12 @@
 const rabbit = require("rabbitmq-stream-js-client")
-const amqplib = require("amqplib")
 const { randomUUID } = require("crypto")
 
 const rabbitUser = process.env.RABBITMQ_USER || "rabbit"
 const rabbitPassword = process.env.RABBITMQ_PASSWORD || "rabbit"
 
 async function main() {
   const streamName = `example-${randomUUID()}`
-  console.log(`Create stream ${streamName}`)
+  console.log(`Creating stream ${streamName}`)
 
   const client = await rabbit.connect({
     hostname: "localhost",
@@ -20,52 +19,21 @@ async function main() {
   await client.createStream({ stream: streamName, arguments: {} })
   const producer = await client.declarePublisher({ stream: streamName })
 
-  await producer.send(Buffer.from("ciao"))
+  await producer.send(Buffer.from("Test message"))
 
-  await createClassicConsumer(streamName)
+  await client.declareConsumer({ stream: streamName, offset: rabbit.Offset.first() }, (message) => {
+    console.log(`Received message ${message.content.toString()}`)
+  })
 
-  await client.deleteStream({ stream: streamName })
+  await sleep(2000)
 
   await client.close()
 }
 
-/**
- *
- * @param {string} queueName name of the stream to consume
- * @returns {Promise<void>}
- */
-async function createClassicConsumer(queueName) {
-  return new Promise(async (res, rej) => {
-    try {
-      const conn = await amqplib.connect(`amqp://${rabbitUser}:${rabbitPassword}@localhost`)
-      const ch = await conn.createChannel()
-      await ch.prefetch(1000)
-      await ch.consume(
-        queueName,
-        async (msg) => {
-          if (!msg) {
-            return
-          }
-
-          console.log("ACK", msg.content.toString())
-          ch.ack(msg)
-          if (msg.content.toString() === "ciao") {
-            await ch.close()
-            await conn.close()
-            res()
-          }
-        },
-        { arguments: { "x-stream-offset": "first" } }
-      )
-    } catch (err) {
-      rej(err)
-    }
-  })
-}
-
 main()
   .then(() => console.log("done!"))
   .catch((res) => {
     console.log("ERROR ", res)
     process.exit(-1)
   })
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))

example/package-lock.json

@@ -19,4 +19,4 @@
   "devDependencies": {
     "typescript": "^4.9.5"
   }
-}
+}