pulse-sdk 0.0.5 → 0.1.0-main.0

package/README.md

@@ -1,177 +1,116 @@
-# Pulse SDK — TypeScript
+# Pulse TypeScript SDK
 
-TypeScript client for Pulse Broker (gRPC). This README is written for end users and explains installation, configuration, and basic usage with practical examples.
+Official TypeScript client for [Pulse Broker](https://github.com/marcosrosa/pulse).
 
 ## Installation
 
-Install from npm (published package):
-
 ```bash
 npm install pulse-sdk
 ```
 
-Or install locally from the repository (for development):
-
-```bash
-npm install
-```
-
-To compile the TypeScript sources (optional for development/CI):
-
-```bash
-npm run build
-```
-
-Run the lightweight integration tests (a test gRPC server is started automatically):
-
-```bash
-npm test
-```
-
 ## Configuration
 
-The SDK supports configuration via (in priority order):
+The SDK looks for a `pulse.yaml` (or `pulse.yml`) file in your project root. If not found, it defaults to `localhost:5555` (HTTP) and `localhost:5556` (gRPC).
 
-1. Programmatic: pass a `PulseConfig` object when creating `Producer` or `Consumer`.
-2. Environment variables: `PULSE_GRPC_URL`, `PULSE_EVENT_TYPES` (comma-separated), `PULSE_CONSUMER_NAME`.
-3. File: a `pulse.yml` or `pulse.yaml` file placed at the process working directory or in `~/.pulse/pulse.yml`.
-
-The SDK exposes two helpers:
-
-- `loadConfig(configPath?: string): PulseConfig` — reads `pulse.yml` / env and returns a merged config object.
-- `initFromConfig(cfg: PulseConfig): Promise<void>` — calls the broker `CreateTopic` RPC for every topic declared in `cfg.topics`. This lets the SDK create any required topics automatically at startup (useful for tests or first-run).
-
-Example `pulse.yml`:
+### Example `pulse.yaml`
 
 ```yaml
-grpcUrl: localhost:5556
-eventTypes:
-	- events
-	- transactions
-consumerName: my-consumer
+# Connection Settings
+broker:
+  host: "localhost"
+  http_port: 5555
+  grpc_port: 5556
+  timeout_ms: 5000
+
+# Client Defaults
+client:
+  id: "my-typescript-app"
+  auto_commit: true       # Automatically commit offsets after successful processing
+  max_retries: 3
+
+# Topic Configuration
 topics:
-	- name: events
-		fifo: false
-	- name: transactions
-		fifo: true
-```
-
-Usage example (auto-create topics then start):
-
-```ts
-import { loadConfig, initFromConfig, Producer, Consumer } from 'pulse-sdk';
-
-async function main() {
-	const cfg = loadConfig(); // reads pulse.yml or environment
-	await initFromConfig(cfg); // create topics listed in cfg.topics (no-op if none)
-
-	const producer = new Producer(cfg);
-	await producer.send('events', { type: 'user.created', id: 1 });
-
-	const consumer = new Consumer(cfg);
-	consumer.on('events', (msg) => console.log('received', msg.payload));
-	await consumer.start('events', cfg.consumerName || 'default');
-}
-
-main().catch(console.error);
+  - name: "events"
+    create_if_missing: true
+    config:
+      fifo: false
+      retention_bytes: 1073741824  # 1GB
+    consume:
+      auto_commit: true
+
+  - name: "transactions"
+    create_if_missing: true
+    config:
+      fifo: true
+    consume:
+      auto_commit: false  # Manual commit required
+
+  - name: "logs"
+    create_if_missing: true
+    config:
+      fifo: false
+    consume:
+      auto_commit: true
 ```
 
-Notes:
-- `initFromConfig` calls the gRPC `CreateTopic` RPC. If the broker responds with an error for a topic that already exists, the SDK logs a warning and continues.
-- Ensure the broker is running and reachable at `cfg.grpcUrl` before calling `initFromConfig`.
-- The SDK bundles `pulse.proto` inside the package so consumers do not need to copy proto files into their projects.
+## Usage
 
-## Quick Start
+### Producer
 
-Import from the published package and pass configuration programmatically:
+You can send objects (automatically serialized to JSON), strings, or raw buffers.
 
-```ts
-import { Producer, Consumer } from 'pulse-sdk';
+```typescript
+import { Producer } from 'pulse-sdk';
 
-const cfg = { grpcUrl: 'localhost:50052', eventTypes: ['events'] };
+// Initialize (uses pulse.yaml or defaults)
+// You can override settings: new Producer("10.0.0.1", 9090)
+const producer = new Producer();
 
-// Send a JSON-serializable event
-const producer = new Producer(cfg);
-await producer.send('events', { type: 'user.created', id: 123 });
+async function main() {
+  // Send JSON
+  await producer.send("events", { type: "user_created", id: 123 });
 
-// Consume events and register a handler
-const consumer = new Consumer(cfg);
-consumer.on('events', (msg) => {
-	console.log('received', msg.payload);
-});
-await consumer.start('events', 'my-consumer');
-```
+  // Send String
+  await producer.send("logs", "raw log line");
 
-### Programmatic override
+  // Send Buffer
+  await producer.send("logs", Buffer.from("binary data"));
 
-You can create and pass `PulseConfig` directly in code:
+  producer.close();
+}
 
-```ts
-const cfg = { grpcUrl: '10.0.0.5:50052', eventTypes: ['events'] };
-const producer = new Producer(cfg);
+main();
 ```
 
-## Technical Details
-
-- The SDK dynamically loads `pulse.proto` at runtime using `@grpc/proto-loader` and `@grpc/grpc-js`.
-- The protobuf field `bytes payload` is used to carry the message body; the SDK serializes JSON payloads into that field by default.
-- `Consumer.start()` opens a server stream (`Consume`) and dispatches incoming messages to handlers registered via `consumer.on(topic, handler)`.
-
-## Examples
+### Consumer
 
-Producer (send multiple events):
+Use the `consumer` function to register message handlers, and `run` to start the loop.
 
-```ts
-const producer = new Producer(loadConfig());
-await producer.send('events', { type: 'login', userId: 1 });
-await producer.send('events', { type: 'logout', userId: 1 });
-```
-
-Consumer (simple processing):
-
-```ts
-const cfg = loadConfig();
-const consumer = new Consumer(cfg);
+```typescript
+import { consumer, run, commit, Message } from 'pulse-sdk';
 
-consumer.on('events', (msg) => {
-	console.log('event payload', msg.payload);
+// Simple Consumer (uses auto_commit from config)
+consumer("events", async (msg: Message) => {
+  console.log(`Received event:`, msg.payload);
+  // msg.payload is an object if JSON, string if String, else Buffer
 });
 
-await consumer.start('events', cfg.consumerName || 'default');
-```
-
-## Local Tests
-
-The tests in `tests/` start a lightweight gRPC test server automatically; run them with `npm test`.
-
-## FAQ (short)
-
-- Can I use decorators for handlers? Yes — TypeScript supports decorators, but this SDK does not use them by default. We can add decorator helpers later if desired.
-- How do I enable TLS / secure credentials? The client factory currently uses `createInsecure()` by default. We can expose a `credentials` option on `PulseConfig` to accept `grpc.credentials.createSsl(...)` or other credential objects.
-
-**Grouped consumption**
-
-- **What it does:** When `grouped` is `true` (the default) the SDK coalesces consumers inside the same process that use the same `consumerName` into a single streaming connection. Messages are distributed (round-robin) among the registered handlers so each message is delivered to only one handler in the group (1x per client id).
-- **Why:** This mirrors the Python SDK behavior where handlers registered with `grouped=True` share a single consumer stream and avoid duplicate processing inside the same client.
-- **How to configure:**
-	- `pulse.yml` (recommended): set `grouped: true` or `grouped: false` under top-level config.
-	- Environment variable: `PULSE_GROUPED=true|false`.
-	- Programmatically: pass `grouped` in the `PulseConfig` passed to `Producer`/`Consumer`.
-- **Default:** `grouped` defaults to `true`.
-- **Grouped=false behavior:** When `grouped` is `false`, the SDK will ensure consumers use unique consumer IDs (if you pass the default client name), so multiple consumers in the same process each receive all messages independently (useful for testing or when you want duplicate consumption).
-- **Example `pulse.yml` entry:**
-
-```yaml
-grpcUrl: localhost:5556
-grouped: true
+// Manual Commit Consumer
+// Override config params directly in the options object
+consumer("transactions", async (msg: Message) => {
+  try {
+    await processPayment(msg.payload);
+    await commit();  // Manually commit offset
+    console.log(`Processed transaction ${msg.offset}`);
+  } catch (e) {
+    console.error(`Failed to process: ${e}`);
+  }
+}, { autoCommit: false });
+
+// Start all consumers
+run();
+
+async function processPayment(data: any) {
+  // ... implementation
+}
 ```
-
-The test-suite includes integration tests that validate both `grouped=true` and `grouped=false` behaviour.
-
-## Contributing
-
-Please open a PR with tests. The existing tests validate basic Producer/Consumer behaviour.
-
----
-
-If you want this README expanded to mirror the Python SDK more closely (topic-level config, manual offset commits, longer examples), tell me which sections to add and I will update it.

package/dist/config.d.ts

@@ -1,16 +1,26 @@
+export interface BrokerConfig {
+    host: string;
+    http_port: number;
+    grpc_port: number;
+    timeout_ms: number;
+}
+export interface ClientConfig {
+    id: string;
+    auto_commit: boolean;
+    max_retries: number;
+}
 export interface TopicConfig {
     name: string;
-    fifo?: boolean;
-    retention_bytes?: number;
-    retention_time?: number;
+    create_if_missing?: boolean;
+    config?: {
+        fifo?: boolean;
+        retention_bytes?: number;
+    };
 }
 export interface PulseConfig {
-    grpcUrl: string;
-    eventTypes: string[];
-    consumerName?: string;
-    grouped?: boolean;
-    autoCommit?: boolean;
-    topics?: TopicConfig[];
+    broker: BrokerConfig;
+    client: ClientConfig;
+    topics: TopicConfig[];
 }
 export declare function loadConfig(configPath?: string): PulseConfig;
-export declare function initFromConfig(cfg: PulseConfig): Promise<void>;
+export declare function getConfig(): PulseConfig;

package/dist/config.js

@@ -4,78 +4,62 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
-exports.initFromConfig = initFromConfig;
+exports.getConfig = getConfig;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
-const client_1 = require("./proto/client");
-const DEFAULTS = {
-    grpcUrl: 'localhost:50052',
-    eventTypes: ['events'],
-    grouped: true,
-    autoCommit: true,
+const DEFAULT_CONFIG = {
+    broker: {
+        host: 'localhost',
+        http_port: 5555,
+        grpc_port: 5556,
+        timeout_ms: 5000,
+    },
+    client: {
+        id: 'typescript-client',
+        auto_commit: true,
+        max_retries: 3,
+    },
+    topics: [],
 };
 function loadConfig(configPath) {
     const candidates = [
         configPath,
-        path_1.default.resolve(process.cwd(), 'pulse.yml'),
         path_1.default.resolve(process.cwd(), 'pulse.yaml'),
+        path_1.default.resolve(process.cwd(), 'pulse.yml'),
         path_1.default.join(os_1.default.homedir(), '.pulse', 'pulse.yml'),
     ].filter(Boolean);
     let fileCfg = {};
     for (const p of candidates) {
         if (p && fs_1.default.existsSync(p)) {
-            const raw = fs_1.default.readFileSync(p, 'utf8');
-            const parsed = js_yaml_1.default.load(raw);
-            fileCfg = parsed || {};
-            break;
+            try {
+                const raw = fs_1.default.readFileSync(p, 'utf8');
+                fileCfg = js_yaml_1.default.load(raw) || {};
+                break;
+            }
+            catch (e) {
+                console.warn(`Failed to load config from ${p}:`, e);
+            }
         }
     }
-    const envCfg = {};
-    if (process.env.PULSE_GRPC_URL)
-        envCfg.grpcUrl = process.env.PULSE_GRPC_URL;
-    if (process.env.PULSE_EVENT_TYPES)
-        envCfg.eventTypes = process.env.PULSE_EVENT_TYPES.split(',');
-    if (process.env.PULSE_CONSUMER_NAME)
-        envCfg.consumerName = process.env.PULSE_CONSUMER_NAME;
-    if (process.env.PULSE_GROUPED)
-        envCfg.grouped = process.env.PULSE_GROUPED === 'true';
-    if (process.env.PULSE_AUTOCOMMIT)
-        envCfg.autoCommit = process.env.PULSE_AUTOCOMMIT === 'true';
-    const merged = Object.assign({}, DEFAULTS, fileCfg, envCfg);
-    // Ensure eventTypes array exists
-    if (!merged.eventTypes)
-        merged.eventTypes = DEFAULTS.eventTypes;
-    if (merged.grouped === undefined)
-        merged.grouped = true;
-    if (merged.autoCommit === undefined)
-        merged.autoCommit = true;
-    return merged;
+    // Deep merge defaults with file config
+    const config = JSON.parse(JSON.stringify(DEFAULT_CONFIG)); // Deep copy
+    if (fileCfg.broker) {
+        config.broker = { ...config.broker, ...fileCfg.broker };
+    }
+    if (fileCfg.client) {
+        config.client = { ...config.client, ...fileCfg.client };
+    }
+    if (fileCfg.topics) {
+        config.topics = fileCfg.topics;
+    }
+    return config;
 }
-// Initialize topics from config using gRPC CreateTopic RPC.
-async function initFromConfig(cfg) {
-    if (!cfg.topics || cfg.topics.length === 0)
-        return;
-    const client = (0, client_1.createClient)(cfg.grpcUrl);
-    for (const t of cfg.topics) {
-        const req = {
-            topic: t.name || t['name'],
-            fifo: !!t.fifo,
-            retention_bytes: t.retention_bytes || 0,
-            retention_time: t.retention_time || 0,
-        };
-        await new Promise((resolve, reject) => {
-            client.CreateTopic(req, (err, res) => {
-                if (err) {
-                    // If topic exists the server may return an error; log and continue
-                    console.warn('CreateTopic error for', req.topic, err.message || err);
-                    resolve();
-                }
-                else {
-                    resolve();
-                }
-            });
-        });
+let _config = null;
+function getConfig() {
+    if (!_config) {
+        _config = loadConfig();
     }
+    return _config;
 }

package/dist/consumer.d.ts

@@ -1,12 +1,12 @@
-import { PulseConfig } from './config';
-export type EventHandler = (payload: any) => any;
-export declare class Consumer {
-    private config;
-    private handlers;
-    private client;
-    private unregisterFns;
-    constructor(config: PulseConfig);
-    on(eventType: string, handler: EventHandler): void;
-    start(topic?: string, consumerName?: string): Promise<void>;
-    close(): void;
+import { Message, commit } from './message';
+export { commit, Message };
+interface ConsumerOptions {
+    host?: string;
+    port?: number;
+    consumerGroup?: string;
+    autoCommit?: boolean;
+    grouped?: boolean;
 }
+export declare function stop(): void;
+export declare function consumer(topic: string, handler: (msg: Message) => void | Promise<void>, options?: ConsumerOptions): void;
+export declare function run(): Promise<void>;