Node Client

TypeScript client for Reflog with runtime protobuf type generation. This client automatically generates type-safe methods from your custom protobuf definitions at runtime. Available on npm .

Install


npm install @reflog/client

Configuration

The client requires two environment variables:

REFLOG_HOST: The gRPC server host (e.g., localhost:50051)
REFLOG_CLIENT_ID: Your client identifier

Alternatively, you can pass these as configuration options when creating the client.

Usage

Basic Example


import { createClient } from "@reflog/client";
 
async function main() {
  // Initialize the client (reads REFLOG_HOST and REFLOG_CLIENT_ID from env)
  const reflog = await createClient();
 
  // Insert a user
  await reflog.insert.User({
    entityId: "user-123",
    payload: {
      id: "user-123",
      name: "John Doe",
      email: "john@example.com",
    },
  });
 
  // Update an article
  await reflog.update.Article({
    entityId: "article-456",
    payload: {
      id: "article-456",
      title: "Updated Title",
      body: "Updated body content",
    },
  });
 
  // Delete a user
  await reflog.delete.User("user-123");
 
  // Close the connection when done
  await reflog.close();
}
 
main().catch(console.error);

With Custom Configuration


import { createClient } from "@reflog/client";
 
const reflog = await createClient({
  host: "localhost:50051",
  clientId: "my-client-id",
  retry: {
    maxRetries: 5,
    initialBackoffMs: 200,
    maxBackoffMs: 3000,
  },
});

Type Safety

The client automatically generates methods based on your protobuf definitions. For example, if your custom.proto defines:


message User {
  string id = 1;
  string name = 2;
  string email = 3;
}
 
message Article {
  string id = 1;
  string author_id = 2;
  string title = 3;
  string body = 4;
}

The client will automatically provide:

reflog.insert.User()
reflog.insert.Article()
reflog.update.User()
reflog.update.Article()
reflog.delete.User()
reflog.delete.Article()

All methods are fully typed based on your protobuf schema.

Error Handling

All ingest operations (insert, update, delete) use background retries for maximum reliability. The operation tries once immediately, and if it fails with a retryable error, the promise resolves immediately while retries continue in the background.


// This resolves immediately even if the service is down
// Retries continue in the background automatically
const result = await reflog.insert.User({
  entityId: "user-123",
  payload: { id: "user-123", name: "John" },
});
 
// When closing, wait for pending retries to complete
await reflog.close(); // Waits up to 5 seconds for background retries