/// SDK — TYPESCRIPT
TypeScript SDK STABLE
Zero-dependency ESM client — Node 18+ and edge runtimes
(fetch + CompressionStream). All sends serialize
through an internal promise chain; tail is an async generator. Pass a
custom fetchFn if your platform differs.
npm install ./sdks/typescript # from the repo — package name "duckgraph" npm run build # tsc → dist/ npm test # build + node --test — 17 tests
import { Client, DuckgraphLogger } from "duckgraph";
const client = new Client("http://localhost:8080", {
apiKey: "dgk_…",
gzip: true,
batchSize: 512,
});
client.log("info", "myapp", "started", { attrs: { port: 8080 } }); // buffered
await client.send([{ service: "myapp", message: "now" }]); // direct
const rows = await client.query({ minLevel: "error",
attrs: { env: "prod" } });
await client.close(); // flushes remaining entries
Client
new Client(baseUrl, opts?) arms the flush timer immediately.
Client.login(baseUrl, user, pass, opts?) authenticates first and
holds the dgs_ session token.
ClientOptions | Default | Purpose |
|---|---|---|
apiKey | — | dgk_ API key — recommended for shippers |
token | — | dgs_ session token |
batchSize | 512 | Max entries per POST |
flushIntervalMs | 2000 | Buffer flush cadence |
queueSize | 8192 | Local buffer capacity |
gzip | false | Compress request bodies (CompressionStream) |
retries | 3 | Attempts on 429/5xx/network errors |
timeoutMs | 30000 | Per-request timeout |
onError | — | Async send-failure callback |
fetchFn | fetch | Custom fetch — edge runtimes, proxies |
Ingest
| Method | Behaviour |
|---|---|
enqueue(entry) | Buffer one entry. Throws QueueFullError when full, ClientClosedError after close. |
log(level, service, message, {host, attrs, ts}) | Enqueue sugar. |
send(entries) → Promise<number> | POST immediately (chunks at 50k). Returns count accepted. |
flush() → Promise<void> | Drain the queue through the send chain. |
dropped | Entries rejected by a full queue. |
close() → Promise<void> | Stop the timer and flush — idempotent. |
Entry fields: ts (Date | RFC3339 | epoch s/ms, default
server-now), level, service (required), host,
message (required), attrs.
DuckgraphLogger
const log = new DuckgraphLogger(client, {
service: "myapp",
attrs: { env: "prod" },
});
log.info("request done", { ms: 3200 });
log.error("failed", { err: String(e) });
await log.close();
Level methods: debug, info, warn,
error, fatal. Base attrs merge with per-call attrs —
the counterpart of the Go SDK's slog handler.
Query & read
| Method | Endpoint | Returns |
|---|---|---|
query(q?) | GET /v1/logs | Promise<Row[]> newest-first |
queryPost(q?) | POST /v1/query | Same — better for large attr filters |
stats(window?, bucket="1m") | GET /v1/stats | Stats — window in seconds or "1h" |
services() | GET /v1/services | string[] |
metrics() | GET /v1/metrics | IngestMetrics (reader+) |
system() | GET /v1/system | SystemInfo |
health() → Promise<boolean> | GET /healthz | Liveness — no auth |
me() | GET /v1/auth/me | Principal |
logout() | POST /v1/auth/logout | Revoke session |
tail(q?) | GET /v1/logs/tail | AsyncGenerator<Row> — break to close |
for await (const row of client.tail({ minLevel: "warn" })) {
console.log(row.level, row.service, row.message, rowAttrs(row));
}
Query fields: from/to (Date | RFC3339 | epoch),
levels, minLevel, services, hosts,
search, attrs, orderAsc, limit,
offset. Row.attrs is the raw JSON string —
rowAttrs(row) parses it.
Admin ADMIN ROLE
| Method | Endpoint |
|---|---|
listUsers() | GET /v1/users |
createUser(name, password, role) | POST /v1/users |
updateUser(name, {role, disabled, password}) | PATCH /v1/users/{name} |
deleteUser(name) | DELETE /v1/users/{name} |
listApiKeys() | GET /v1/apikeys |
createApiKey(name, role) → APIKey | POST /v1/apikeys — key.secret shown once |
revokeApiKey(id) | DELETE /v1/apikeys/{id} |
sql(statement) → SQLResult | POST /v1/sql — read-only |
Errors: APIError (.status) for non-2xx,
QueueFullError / ClientClosedError for local state.