packages/hulypulse-client/README.md
A TypeScript/Node.js client for the Hulypulse WebSocket server.
Supports automatic reconnection, request–response correlation, get / put / delete, and subscriptions.
Stores a value under a key.
TTL (optional) — time-to-live in seconds.
Resolves with true if the operation succeeded.
await client.put("workspace/users/123", "Alice", 60) → true
Retrieves the value for a key.
Resolves with the value if found.
Resolves with false if the key does not exist.
const value = await client.get("workspace/users/123") if (value) { console.log("User data:", value) } else { console.log("User not found") }
Retrieves the full record:
data — stored value,
etag — data identifier,
expires_at — expiration in seconds.
const full = await client.get_full("workspace/users/123") if (full) { console.log(full.data, full.etag, full.expires_at) }
Deletes a key.
Resolves with true if the key was deleted.
Resolves with false if the key was not found.
const deleted = await client.delete("workspace/users/123") console.log(deleted ? "Deleted" : "Not found")
Subscribes to updates for a key (or prefix).
The callback is invoked on every event: Set, Del, Expired
Resolves with true if a new subscription was created.
Resolves with false if the callback was already subscribed.
const cb = (msg, key, index) => {
if( msg.message === 'Expired' ) console.log(${msg.key} was expired)
}
await client.subscribe("workspace/users/", cb) // Now cb will be called when any key starting with "workspace/users/" changes
Unsubscribes a specific callback.
Resolves with true if the callback was removed (and if it was the last one, the server gets an unsub message).
Resolves with false if the callback was not found.
await client.unsubscribe("workspace/users/", cb)
Low-level method to send a raw message.
Automatically attaches a correlation id.
Resolves when a response with the same correlation is received.
const reply = await client.send({ type: "get", key: "workspace/users/123" }) console.log("Raw reply:", reply)
If the connection drops, the client automatically reconnects.
All active subscriptions are re-sent to the server after reconnect.
The client supports both manual closing and the new using syntax (TypeScript 5.2+).
clientSymbol.dispose // closes the connection
or, if needed internally:
(client as any).close()
import { HulypulseClient } from "./hulypulse_client.js"
async function main() {
// connect
const client = await HulypulseClient.connect("wss://hulypulse_mem.lleo.me/ws")
// subscribe to updates
const cb = (msg, key, index) => {
console.log("Update for", key, ":", msg)
}
await client.subscribe("workspace/users/", cb)
// put value
await client.put("workspace/users/123", JSON.stringify({ name: "Alice" }), 5)
// get value
const value = await client.get("workspace/users/123")
console.log("Fetched:", value)
// get full record
const full = await client.get_full("workspace/users/123")
if (full) {
console.log(full.data, full.etag, full.expires_at)
}
// delete key
const deleted = await client.delete("workspace/users/123")
console.log(deleted ? "Deleted" : "Not found")
// unsubscribe
await client.unsubscribe("workspace/users/", cb)
// low-level send
const reply = await client.send({ type: "sublist" })
console.log("My sublists:", reply)
// dispose
client[Symbol.dispose]()
}
main()