Typed Buckets

Buckets are gunsole’s core abstraction for grouping logs. Pass buckets in your config to get first-class typed accessors with full autocomplete — no as const needed.

Setup

import { createGunsoleClient } from "gunsole-js";

const gun = createGunsoleClient({
  projectId: "my-app",
  apiKey: "dev",
  mode: "local",
  buckets: ["payment", "auth", "api"],
});

The factory uses a const generic parameter (TypeScript 5.0+) to infer literal tuple types automatically.

Usage

Direct call logs at info level. Each bucket also has level sub-methods:

// Direct call — logs at "info" level
gun.payment("User completed checkout");

// Level sub-methods
gun.payment.info("Order created", { context: { orderId: "abc" } });
gun.payment.error("Payment declined", { context: { reason: "insufficient_funds" } });
gun.auth.warn("Suspicious login attempt");
gun.api.debug("Request received", { traceId: "trace-123" });

Method signature

gun.payment(message: string, options?: BucketLogOptions): void
gun.payment.info(message: string, options?: BucketLogOptions): void
gun.payment.debug(message: string, options?: BucketLogOptions): void
gun.payment.warn(message: string, options?: BucketLogOptions): void
gun.payment.error(message: string, options?: BucketLogOptions): void

BucketLogOptions is LogOptions without bucket and message (both are positional/implied):

{
  context?: Record<string, unknown>;
  tags?: Partial<Tags> | TagEntry<Tags>[];
  traceId?: string;
}

Escape hatch

The log() API still works with any bucket string. Bucket accessors are the typed surface; log() is the untyped escape hatch.

// Typed — autocomplete + compile-time check
gun.payment("User paid");

// Untyped — any bucket string accepted
gun.log({ bucket: "payment", message: "User paid" });
gun.log({ bucket: "some-dynamic-bucket", message: "..." });

Reserved bucket names

Bucket names that conflict with GunsoleClient methods are rejected at both compile time and runtime:

log, info, debug, warn, error, setUser, setSessionId, flush, destroy, attachGlobalErrorHandlers, detachGlobalErrorHandlers

// Compile-time error: Type 'string' is not assignable to type 'never'
const gun = createGunsoleClient({
  projectId: "p",
  apiKey: "k",
  mode: "cloud",
  buckets: ["log"], // ← TS error
});

Backward compatibility

Omitting buckets returns a plain GunsoleClient — no phantom properties, no behavior change.

// No buckets — returns GunsoleClient<Tags> (clean type, no index signature)
const gun = createGunsoleClient({
  projectId: "p",
  apiKey: "k",
  mode: "cloud",
});

TypeScript exports

Export	Description
`BucketLogOptions`	Log options for bucket methods (no bucket/message)
`BucketLogger`	Callable bucket accessor interface
`WithBuckets`	Mapped type adding bucket accessors to client
`ReservedBucketName`	Union of reserved bucket names
`ValidateBuckets`	Compile-time bucket name validator