https://github.com/faiscadev/fila-js
JavaScript/TypeScript client SDK for the Fila message broker
https://github.com/faiscadev/fila-js
Last synced: 3 months ago
JSON representation
JavaScript/TypeScript client SDK for the Fila message broker
- Host: GitHub
- URL: https://github.com/faiscadev/fila-js
- Owner: faiscadev
- License: agpl-3.0
- Created: 2026-02-20T01:47:22.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T14:17:34.000Z (3 months ago)
- Last Synced: 2026-03-22T03:47:38.385Z (3 months ago)
- Language: TypeScript
- Size: 87.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fila-js
JavaScript/TypeScript client SDK for the [Fila](https://github.com/faisca/fila) message broker.
## Installation
```bash
npm install @fila/client
```
## Usage
```typescript
import { Client } from "@fila/client";
const client = new Client("localhost:5555");
// Enqueue a message.
const msgId = await client.enqueue(
"my-queue",
{ tenant: "acme" },
Buffer.from("hello world")
);
console.log("Enqueued:", msgId);
// Consume messages.
for await (const msg of client.consume("my-queue")) {
console.log(`Received: ${msg.id} (attempt ${msg.attemptCount})`);
try {
// Process the message...
await client.ack("my-queue", msg.id);
} catch (err) {
await client.nack("my-queue", msg.id, String(err));
}
}
client.close();
```
### TLS (system trust store)
If the Fila server uses a certificate signed by a public CA, enable TLS without providing a CA certificate — the OS system trust store is used automatically:
```typescript
import { Client } from "@fila/client";
const client = new Client("localhost:5555", { tls: true });
```
### TLS (custom CA certificate)
For self-signed or private CA certificates, pass the CA cert explicitly:
```typescript
import * as fs from "fs";
import { Client } from "@fila/client";
const client = new Client("localhost:5555", {
caCert: fs.readFileSync("ca.pem"),
});
```
### Mutual TLS (mTLS)
Client certificates work with both modes — system trust store or custom CA:
```typescript
import * as fs from "fs";
import { Client } from "@fila/client";
// With custom CA:
const client = new Client("localhost:5555", {
caCert: fs.readFileSync("ca.pem"),
clientCert: fs.readFileSync("client.pem"),
clientKey: fs.readFileSync("client.key"),
});
// With system trust store:
const client2 = new Client("localhost:5555", {
tls: true,
clientCert: fs.readFileSync("client.pem"),
clientKey: fs.readFileSync("client.key"),
});
```
### API key authentication
```typescript
import { Client } from "@fila/client";
const client = new Client("localhost:5555", {
apiKey: "my-api-key",
});
```
### mTLS + API key
```typescript
import * as fs from "fs";
import { Client } from "@fila/client";
const client = new Client("localhost:5555", {
caCert: fs.readFileSync("ca.pem"),
clientCert: fs.readFileSync("client.pem"),
clientKey: fs.readFileSync("client.key"),
apiKey: "my-api-key",
});
```
## API
### `new Client(addr: string, options?: ClientOptions)`
Connect to a Fila broker at the given address (e.g., `"localhost:5555"`).
**Options:**
| Option | Type | Description |
|-------------|-----------|---------------------------------------------------------------------|
| `tls` | `boolean` | Enable TLS using the OS system trust store. Implied when `caCert` is set. |
| `caCert` | `Buffer` | CA certificate PEM. Enables TLS with a custom CA when set. |
| `clientCert`| `Buffer` | Client certificate PEM for mTLS. Requires TLS to be enabled. |
| `clientKey` | `Buffer` | Client private key PEM for mTLS. Requires TLS to be enabled. |
| `apiKey` | `string` | API key sent as `Bearer` token on every RPC call. |
### `client.enqueue(queue, headers, payload): Promise`
Enqueue a message. Returns the broker-assigned message ID (UUIDv7).
### `client.consume(queue): AsyncIterable`
Open a streaming consumer. Returns an async iterable that yields messages as they become available. Nacked messages are redelivered on the same stream.
### `client.ack(queue, msgId): Promise`
Acknowledge a successfully processed message. The message is permanently removed.
### `client.nack(queue, msgId, error): Promise`
Negatively acknowledge a failed message. The message is requeued or routed to the dead-letter queue based on the queue's configuration.
### `client.close(): void`
Close the underlying gRPC channel.
## Error Handling
Per-operation error classes are thrown for specific failure modes:
```typescript
import { QueueNotFoundError, MessageNotFoundError } from "@fila/client";
try {
await client.enqueue("missing-queue", null, Buffer.from("test"));
} catch (err) {
if (err instanceof QueueNotFoundError) {
// handle queue not found
}
}
try {
await client.ack("my-queue", "missing-id");
} catch (err) {
if (err instanceof MessageNotFoundError) {
// handle message not found
}
}
```
## License
AGPLv3