Skip to content

ShardlensClient

Defined in: packages/core/src/client.ts:323

The transport half of the SDK: a bounded priority queue, salt bootstrap, sampling, gzip batching, retries and shutdown. Library adapters (such as @shardlens/discordjs) turn library events into wire events and enqueue them.

Nothing here throws into the caller: every failure is caught, counted in ClientStats.internalErrors and reported to on('error') listeners.

E extends WireEvent = WireEvent

new ShardlensClient<E>(options): ShardlensClient<E>

Defined in: packages/core/src/client.ts:371

ClientOptions

ShardlensClient<E>

get mode(): DataMode | undefined

Defined in: packages/core/src/client.ts:425

The effective data mode: audit only when both the SDK and the collector are in audit mode.

DataMode | undefined


get ready(): boolean

Defined in: packages/core/src/client.ts:420

True once salts and settings have arrived from the collector (or the dry-run salt is ready).

boolean

count(name, error?): void

Defined in: packages/core/src/client.ts:550

Increments an internal error counter and notifies listeners. For adapters; never throws.

string

unknown

void


enqueue(event, priority): void

Defined in: packages/core/src/client.ts:437

Queues an event. Applies sampling. Never throws.

E

Priority

void


enqueueWithUser(userId, ts, priority, build): void

Defined in: packages/core/src/client.ts:459

Queues an event that carries a user hash. The hash is computed in-process with the period’s salt; if the salt hasn’t arrived yet, the event waits in a small bounded buffer (1,000 events, 60 seconds) and is then dropped.

string

number

Priority

(userHash) => E

void


flush(): Promise<void>

Defined in: packages/core/src/client.ts:593

Sends queued events now. Concurrent calls share one flush. Never throws.

Promise<void>


forgetUser(userId): Promise<{ erased: number; } | undefined>

Defined in: packages/core/src/client.ts:504

Asks the collector to delete everything stored for a user (right to erasure). Sends the user’s hashes for every salt period still installed; the raw ID is sent only in audit mode, where the collector already holds it encrypted. Resolves to the number of rows removed, or undefined if the request could not be made. Never throws.

string

Promise<{ erased: number; } | undefined>


hashUser(userId, at?): Promise<string | undefined>

Defined in: packages/core/src/client.ts:489

Hashes a user ID for the period containing at. Returns undefined if that period’s salt isn’t available. Use it for erasure requests; event hashing goes through ShardlensClient.enqueueWithUser.

string

Date = ...

Promise<string | undefined>


idle(timeoutMs?): Promise<void>

Defined in: packages/core/src/client.ts:584

Resolves once the first settings load has finished and no user hashing is in progress, or after timeoutMs. Serverless runtimes call it before ShardlensClient.flush inside waitUntil, so the events of a short-lived request are hashed and sent before the runtime stops. Never throws.

number = 2_000

Promise<void>


on(event, listener): () => void

Defined in: packages/core/src/client.ts:431

Listens for internal errors. Listener exceptions are swallowed.

"error"

ErrorListener

() => void


shutdown(options?): Promise<void>

Defined in: packages/core/src/client.ts:615

Stops timers and flushes what is queued, giving up after timeoutMs. The SDK never installs signal handlers; call this from your own shutdown code. Every call waits for the same flush. Never throws.

FlushOptions

Promise<void>


stats(): ClientStats

Defined in: packages/core/src/client.ts:563

ClientStats