Redesign SDK: scoped Effect core, non-blocking track, Standard Schema support

[deepso7]

Summary

Ground-up redesign of both entry points for better DX, performance, and universal runtime support (Node.js + browsers). Breaking changes throughout.

Core fix: non-blocking track

Previously track drained the queue inline when the batch threshold was hit, so a "fire and forget" call could wait on HTTP delivery and retries. Delivery now runs on a dedicated background fiber (Latch-signaled) — track only validates, stamps, and enqueues.

trashlytics/effect

• Tracker.make(options) is a scoped constructor (Effect<Tracker, never, Scope | R>); closing the scope interrupts the worker and flushes remaining events. Replaces the old plain-function constructor (which ran Effect.runSync internally) and the shutdown() method.
• Unified tagged errors: EventValidationError (normalized issues), UnknownEventError, TrackerClosedError, QueueFullError, SinkError.
• New: tracker.size, retry.jitter, tracker-level context merged into every event's meta.

trashlytics (root entry)

• track() is sync fire-and-forget and never throws; failures route to onError.
• close() replaces shutdown(), is idempotent, and trackers support await using via Symbol.asyncDispose.
• Standard Schema v1 support: event("signup", z.object({...})) works with zod/valibot/arktype — no Effect Schema import needed. Payload-less events: event("page.viewed").
• Browser lifecycle: auto-flush on visibilitychange/pagehide (flushOnHide, default on).
• Sinks may return void, Promise, or Effect, so built-in sinks are shared between both entries.

Sinks

• httpSink defaults to keepalive: true (survives page unloads) and accepts a custom fetch.
• New beaconSink using navigator.sendBeacon.

Breaking renames

Old	New
createTracker (effect entry)	make
shutdown()	close() / scope close
retries	retry
bufferSize	maxQueueSize
SinkDeliveryError	SinkError

Testing

• 18 unit tests pass (vitest), covering typed batches, payload-less events, standard schemas, context merging, background batch delivery, retries, close-flush, and error paths
• tsc --noEmit and ultracite check clean
• Smoke-tested built ESM and CJS artifacts end-to-end, including httpSink against a real local HTTP server

🤖 Generated with Claude Code

---

Summary by cubic

Redesigned the SDK to make tracking non-blocking, add Standard Schema v1 support, and scope the tracker lifecycle across Node and browsers. flush()/close() now wait for in-flight track() calls; close() is a hard barrier. Delivery is backgrounded and uninterruptible so in-flight batches finish before shutdown.

• New Features

  • Non-blocking track: events enqueue instantly; delivery runs in the background on batch size, flush interval, flush, and close.
  • trashlytics/effect: scoped Tracker.make(...); closing the scope stops the worker and flushes. New typed errors, size, tracker-level context, retry.jitter, and deliveryTimeout (bounds each sink call; default 30s).
  • trashlytics: sync fire-and-forget track() that never throws; close() with await using via Symbol.asyncDispose; auto-flush on visibilitychange/pagehide (on by default); sinks may return void/Promise/Effect; onError receives the failed batch, observes trackNow() failures, and also sees validation failures; after close() starts, track() reports TrackerClosedError via onError and trackNow() rejects; flush()/close() await in-flight track().
  • Standard Schema v1 support (zod/valibot/arktype), Schema.Struct fields, and payload-less events: event("page.viewed").
  • Sinks: httpSink defaults to keepalive: true and accepts a custom fetch; new beaconSink for browsers; delivery attempts are bounded by deliveryTimeout; background drain loop is uninterruptible to avoid in-flight batch loss on shutdown.

• Migration

  • trashlytics/effect: createTracker -> make (scoped). Replace shutdown() with scope close; flush is now an Effect value (yield* tracker.flush).
  • Options: retries -> retry (adds jitter), bufferSize -> maxQueueSize. New: deliveryTimeout (default 30s).
  • Errors: SinkDeliveryError -> SinkError, TrackerShutdownError -> TrackerClosedError, BufferFullError -> QueueFullError.

^{Written for commit c12d010. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/effect.ts">

<violation number="1" location="src/effect.ts:704">
P2: `Effect.promise` assumes the promise never rejects. If a Standard Schema validator's async `validate` throws or rejects (e.g., due to a network-dependent validator or buggy implementation), this becomes an unhandled defect that escapes the `EventValidationError` error channel. Using `Effect.tryPromise` with a `catch` clause would convert rejections into proper `EventValidationError` values, keeping the typed error contract intact.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Effect.promise assumes the promise never rejects. If a Standard Schema validator's async validate throws or rejects (e.g., due to a network-dependent validator or buggy implementation), this becomes an unhandled defect that escapes the EventValidationError error channel. Using Effect.tryPromise with a catch clause would convert rejections into proper EventValidationError values, keeping the typed error contract intact.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/effect.ts, line 704:

<comment>`Effect.promise` assumes the promise never rejects. If a Standard Schema validator's async `validate` throws or rejects (e.g., due to a network-dependent validator or buggy implementation), this becomes an unhandled defect that escapes the `EventValidationError` error channel. Using `Effect.tryPromise` with a `catch` clause would convert rejections into proper `EventValidationError` values, keeping the typed error contract intact.</comment>

<file context>
@@ -157,377 +439,322 @@ export interface TrackOptions {
-      catch: (cause) => new SinkDeliveryError({ cause }),
-    });
+    return result instanceof Promise
+      ? Effect.promise(() => result).pipe(Effect.flatMap(toEffect))
+      : toEffect(result);
+  });
</file context>

Suggested change

	? Effect.promise(() => result).pipe(Effect.flatMap(toEffect))
	? Effect.tryPromise({
	try: () => result,
	catch: (cause) =>
	new EventValidationError({
	key,
	issues: [{ message: String(cause) }],
	cause,
	}),
	}).pipe(Effect.flatMap(toEffect))

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/index.ts">

<violation number="1" location="src/index.ts:128">
P2: Tracking immediately after `close()` is invoked can still be accepted because `close` yields on `settleInFlight()` before the Effect scope marks the tracker closed. Consider marking the wrapper as closing synchronously and having `track` route those calls to `onError` with `TrackerClosedError`.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Tracking immediately after close() is invoked can still be accepted because close yields on settleInFlight() before the Effect scope marks the tracker closed. Consider marking the wrapper as closing synchronously and having track route those calls to onError with TrackerClosedError.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/index.ts, line 128:

<comment>Tracking immediately after `close()` is invoked can still be accepted because `close` yields on `settleInFlight()` before the Effect scope marks the tracker closed. Consider marking the wrapper as closing synchronously and having `track` route those calls to `onError` with `TrackerClosedError`.</comment>

<file context>
@@ -114,7 +114,20 @@ export function createTracker<const Events extends EventsMap>(
+  };
+
+  const flush = async () => {
+    await settleInFlight();
+    await Effect.runPromise(tracker.flush);
+  };
</file context>

[deepso7]

@cubic-dev-ai rereview

[cubic-dev-ai]

@cubic-dev-ai rereview

@deepso7 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 7 files

_{Re-trigger cubic}

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/effect.ts">

<violation number="1" location="src/effect.ts:704">
P2: `Effect.promise` assumes the promise never rejects. If a Standard Schema validator's async `validate` throws or rejects (e.g., due to a network-dependent validator or buggy implementation), this becomes an unhandled defect that escapes the `EventValidationError` error channel. Using `Effect.tryPromise` with a `catch` clause would convert rejections into proper `EventValidationError` values, keeping the typed error contract intact.</violation>
</file>

<file name="src/index.ts">

<violation number="1" location="src/index.ts:128">
P2: Tracking immediately after `close()` is invoked can still be accepted because `close` yields on `settleInFlight()` before the Effect scope marks the tracker closed. Consider marking the wrapper as closing synchronously and having `track` route those calls to `onError` with `TrackerClosedError`.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>