svoose

Svelte + Goose = svoose — the goose that sees everything

Lightweight observability + state machines for Svelte 5. Zero dependencies. Tree-shakeable. ~6.7KB gzipped (observe-only ~5.1KB).

Features

• Web Vitals — CLS, LCP, FID, INP, FCP, TTFB (no external deps)
• Error Tracking — global errors + unhandled rejections
• Custom Metrics — metric(), counter(), gauge(), histogram()
• Beacon Transport — reliable delivery on page close with auto-chunking
• Session Tracking — automatic sessionId with timeout
• Sampling — per-event-type rate limiting
• State Machines — minimal FSM with TypeScript inference
• Svelte 5 Native — reactive useMachine() hook with $state runes
• Tree-shakeable — pay only for what you use

Installation

npm install svoose

svoose works without Svelte. The svelte peer dependency is optional — only needed if you use svoose/svelte (useMachine hook).

Quick Start

Step 1: See what svoose collects

Start with the console transport — you'll see events in DevTools immediately, no backend needed:

import { observe, createConsoleTransport } from 'svoose';

const cleanup = observe({
  transport: createConsoleTransport({ pretty: true }),
});

// Open DevTools console — you'll see Web Vitals, errors, and metrics as they happen

Step 2: Send to your backend

When you're ready, switch to an endpoint:

import { observe } from 'svoose';

const obs = observe({
  endpoint: '/api/metrics',
  errors: true,
  vitals: true,
  session: true,
});

// New API
obs.flush();              // send buffered events now
obs.getStats();           // { buffered: 3, sent: 47, dropped: 0 }
obs.onEvent(e => ...);    // subscribe to events

// Stop observing when done
obs.destroy();
// or: obs() — backward compatible, same as destroy()

Step 3: Add custom metrics and state machines

import { observe, metric, counter, createMachine } from 'svoose';

observe({ endpoint: '/api/metrics' });

// Track custom events
metric('checkout_started', { step: 1, cartTotal: 99.99 });
counter('page_views');

// State machine with automatic transition tracking
const auth = createMachine({
  id: 'auth',
  initial: 'idle',
  context: { user: null },
  states: {
    idle: { on: { LOGIN: 'loading' } },
    loading: {
      on: {
        SUCCESS: {
          target: 'authenticated',
          action: (ctx, e) => ({ user: e.user }),
        },
        ERROR: 'idle',
      },
    },
    authenticated: { on: { LOGOUT: 'idle' } },
  },
  observe: true,
});

auth.send('LOGIN');

What Data Looks Like

svoose sends JSON arrays via POST to your endpoint. Here's an example batch:

[
  {
    "type": "vital",
    "name": "LCP",
    "value": 1234,
    "rating": "good",
    "delta": 1234,
    "timestamp": 1710500000000,
    "url": "https://myapp.com/dashboard",
    "sessionId": "1710500000000-a1b2c3"
  },
  {
    "type": "error",
    "message": "Cannot read properties of null (reading 'id')",
    "stack": "TypeError: Cannot read properties...\n    at handleClick (app.js:42)",
    "filename": "app.js",
    "lineno": 42,
    "timestamp": 1710500001000,
    "url": "https://myapp.com/dashboard",
    "sessionId": "1710500000000-a1b2c3",
    "machineId": "auth",
    "machineState": "loading"
  },
  {
    "type": "transition",
    "machineId": "auth",
    "from": "idle",
    "to": "loading",
    "event": "LOGIN",
    "timestamp": 1710500002000,
    "sessionId": "1710500000000-a1b2c3"
  },
  {
    "type": "custom",
    "name": "page_views",
    "metricKind": "counter",
    "value": 1,
    "timestamp": 1710500003000,
    "sessionId": "1710500000000-a1b2c3"
  }
]

Event types:

| Type | When | Key fields | |------|------|------------| | vital | Web Vital measured (LCP, CLS, INP, etc.) | name, value, rating | | error | Uncaught error | message, stack, machineState | | unhandled-rejection | Unhandled promise rejection | reason, machineState | | transition | State machine transition | machineId, from, to, event | | custom | metric(), counter(), gauge(), histogram() | name, metricKind, value, metadata |

What data leaves your browser

Every event svoose sends is JSON you can inspect with createConsoleTransport(). Here's what each field contains:

| Field | Source | May contain PII? | |-------|--------|-----------------| | url | location.href at event time | Yes — query params may have tokens (?token=xxx) | | message, stack | Error object | Yes — error text may include user data | | machineId, machineState | Your machine config | No (developer-defined strings) | | sessionId | Random generated ID | No (not tied to user identity) | | name, value, metadata | Your metric() / counter() calls | Depends on what you pass |

Tip: Use a filter to strip sensitive data before it's sent:

observe({
  endpoint: '/api/metrics',
  filter: (event) => {
    if ('url' in event) {
      (event as any).url = event.url.split('?')[0]; // strip query params
    }
    return true;
  },
});

Receiving Events (Backend)

svoose is a client-side collector — it doesn't include a backend. Your server just needs one POST endpoint that accepts a JSON array.

SvelteKit

Planned for v0.3.0 — not yet implemented. The API below is a preview of the planned integration.

// src/routes/api/metrics/+server.ts
import { json } from '@sveltejs/kit';
import type { RequestHandler } from './$types';

export const POST: RequestHandler = async ({ request }) => {
  const events = await request.json();

  // Option 1: Log to stdout (pipe to your log aggregator)
  console.log(JSON.stringify(events));

  // Option 2: Insert into database
  // await db.insert('events', events);

  return json({ ok: true }, { status: 200 });
};

Express

import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/metrics', (req, res) => {
  const events = req.body; // ObserveEvent[]

  // Store, forward, or log — up to you
  for (const event of events) {
    if (event.type === 'error') {
      console.error(`[${event.machineState ?? 'unknown'}] ${event.message}`);
    }
  }

  res.sendStatus(204);
});

No backend? No problem

// Development — just log to console
observe({ transport: createConsoleTransport({ pretty: true }) });

// Production without backend — silent noop
observe({ transport: { send: () => {} } });

Production recommendations

Use the built-in production preset for sensible defaults:

import { observe, productionDefaults } from 'svoose';

observe({ ...productionDefaults, endpoint: '/api/metrics' });
// Includes: batchSize 50, flushInterval 10s, sampling, sessions

Or configure manually for production traffic (1000+ users):

observe({
  endpoint: '/api/metrics',

  // Larger batches = fewer HTTP requests
  batchSize: 50,
  flushInterval: 10000,

  // Sample to reduce volume
  sampling: {
    errors: 1.0,       // never skip errors
    vitals: 0.5,       // 50% is enough for p75/p95 stats
    custom: 0.5,
    transitions: 0.1,  // transitions are high-volume
  },

  // Handle transport failures
  onError: (err) => console.error('svoose transport failed:', err),

  // Track sessions
  session: true,
});

Volume math: 1000 users with default settings (batchSize: 10, flushInterval: 5s) = ~200 req/s to your endpoint. With batchSize: 50 + flushInterval: 10s + sampling: 0.5 = ~10 req/s.

API

observe(options?)

Start collecting Web Vitals and errors.

const cleanup = observe({
  // Where to send data
  endpoint: '/api/metrics',

  // Or use custom transport (overrides endpoint)
  transport: myTransport,

  // What to collect
  vitals: true,              // or ['CLS', 'LCP', 'INP']
  errors: true,

  // Batching
  batchSize: 10,
  flushInterval: 5000,

  // Sampling — number or per-event-type config
  sampling: {
    vitals: 0.1,             // 10%
    errors: 1.0,             // 100%
    custom: 0.5,             // 50%
    transitions: 0.0,        // disabled
  },

  // Sessions
  session: true,             // or { timeout: 30 * 60 * 1000, storage: 'sessionStorage' }

  // Error callback — handle transport failures
  onError: (err) => console.error('Transport failed:', err),

  // Filter events before sending
  filter: (event) => !(event.type === 'vital' && event.name === 'TTFB'),

  // Debug
  debug: false,
});

// Stop observing
cleanup();

Note: If neither endpoint nor transport is provided, defaults to endpoint: '/api/metrics'. The default transport is hybrid (fetch + beacon on page close) for reliable delivery.

Sampling

Control what percentage of events are sent:

// Simple: same rate for all events
observe({ sampling: 0.1 }); // 10% of everything

// Per-event-type (recommended)
observe({
  sampling: {
    vitals: 0.1,       // 10% — sufficient for accurate statistics
    errors: 1.0,       // 100% — capture all errors
    custom: 0.5,       // 50% of custom metrics
    transitions: 0.0,  // disabled
  },
});

Sessions

Automatic session tracking with configurable timeout:

// Enable with defaults (30 min timeout, sessionStorage)
observe({ session: true });

// Or custom config
observe({
  session: {
    timeout: 60 * 60 * 1000,  // 1 hour
    storage: 'localStorage',   // 'sessionStorage' | 'localStorage' | 'memory'
  },
});

// All events now include sessionId:
// { type: 'vital', name: 'LCP', value: 1234, sessionId: '1706123456789-abc123def' }

Storage options:

• sessionStorage (default) — session per browser tab
• localStorage — session persists across tabs
• memory — no persistence, new session on page reload

Web Vitals

svoose collects all Core Web Vitals using the standard web-vitals algorithm (own implementation, no external dependency):

| Metric | What it measures | When reported | |--------|------------------|---------------| | CLS | Visual stability (layout shifts) | On page hide | | LCP | Loading performance | On user input or page hide | | INP | Responsiveness (max interaction) | On page hide | | FCP | First content painted | Once | | TTFB | Server response time | Once | | FID | First input delay (deprecated) | Once |

// All vitals
observe({ vitals: true });

// Select specific vitals
observe({ vitals: ['CLS', 'LCP', 'INP'] });

CLS, LCP, and INP report once per page lifecycle (matches Chrome DevTools and Google Search Console behavior).

Custom Metrics

Track custom events for analytics:

import { metric, counter, gauge, histogram } from 'svoose';

// Basic event
metric('checkout_started', { step: 1, cartTotal: 99.99 });

// Counter — increments (default value: 1)
counter('page_views');
counter('items_purchased', 3, { category: 'electronics' });

// Gauge — point-in-time values
gauge('active_users', 42);
gauge('memory_usage_mb', 256, { heap: 'old' });

// Histogram — distribution values
histogram('response_time_ms', 123);
histogram('payload_size', 4096, { route: '/api/data' });

Buffer behavior: If metric() / counter() / gauge() / histogram() is called before observe(), events are buffered (max 100). They're automatically flushed when observe() initializes.

Typed Metrics

Full TypeScript autocomplete for metric names and metadata shapes:

import { createTypedMetric } from 'svoose';

const track = createTypedMetric<{
  checkout_started: { step: number; cartTotal: number };
  button_clicked: { id: string };
}>();

track('checkout_started', { step: 1, cartTotal: 99.99 }); // autocomplete
track('button_clicked', { id: 'submit' });                 // autocomplete
track('unknown_event', {});                                 // TypeScript error

createMachine(config)

Create a state machine.

const machine = createMachine({
  id: 'toggle',
  initial: 'off',
  context: { count: 0 },
  states: {
    off: {
      on: { TOGGLE: 'on' },
    },
    on: {
      entry: (ctx) => ({ count: ctx.count + 1 }),
      on: { TOGGLE: 'off' },
    },
  },
});

machine.state;              // 'off'
machine.context;            // { count: 0 }

// Note: context is shallow-cloned from your initial object.
// Nested objects/arrays are shared references — same as XState.
// If you need a deep clone, pass structuredClone(ctx) yourself.

machine.matches('off');     // true
machine.matchesAny('on', 'off'); // true

machine.can('TOGGLE');      // true
machine.can({ type: 'SET', value: 42 }); // full event for payload-dependent guards

machine.send('TOGGLE');
machine.send({ type: 'SET', value: 42 });

machine.destroy();

Guards & Actions

const counter = createMachine({
  id: 'counter',
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: {
          target: 'active',
          guard: (ctx) => ctx.count < 10,
          action: (ctx) => ({ count: ctx.count + 1 }),
        },
        DECREMENT: {
          target: 'active',
          guard: (ctx) => ctx.count > 0,
          action: (ctx) => ({ count: ctx.count - 1 }),
        },
      },
    },
  },
});

Entry & Exit Actions

const wizard = createMachine({
  id: 'wizard',
  initial: 'step1',
  context: { data: {} },
  states: {
    step1: {
      entry: (ctx) => console.log('Entered step 1'),
      exit: (ctx) => console.log('Leaving step 1'),
      on: { NEXT: 'step2' },
    },
    step2: {
      on: { BACK: 'step1', SUBMIT: 'complete' },
    },
    complete: {
      entry: (ctx) => console.log('Done!'),
    },
  },
});

Observability Integration

Machines automatically integrate with observe():

observe({ errors: true });

// Simple
const auth = createMachine({ id: 'auth', observe: true, /* ... */ });

// Or detailed config
const auth = createMachine({
  id: 'auth',
  observe: { transitions: true, context: true },
  // ...
});

// When an error occurs, it includes all active machines:
// { machineId: 'auth', machineState: 'loading', machines: [{ id: 'auth', state: 'loading' }] }

Transports

Retry & Timeout

Add retry logic with configurable backoff to any fetch-based transport:

import { createFetchTransport } from 'svoose';

const transport = createFetchTransport('/api/metrics', {
  retry: {
    attempts: 3,
    backoff: 'exponential',  // 'fixed' | 'linear' | 'exponential'
    initialDelay: 1000,       // 1s → 2s → 4s
    maxDelay: 30000,
    jitter: true,             // ±10% randomization
  },
  timeout: 10000,  // 10s per request
});

Works with hybrid transport too — retry applies to fetch only, beacon never retries:

import { createHybridTransport } from 'svoose';

observe({
  transport: createHybridTransport('/api/metrics', {
    retry: { attempts: 3, backoff: 'exponential' },
    timeout: 10000,
  }),
});

withRetry() is also available as a standalone utility for custom transports:

import { withRetry } from 'svoose';

await withRetry(
  (signal) => fetch('/api/metrics', { method: 'POST', body, signal }),
  { attempts: 3, backoff: 'exponential' },
  { timeout: 5000 }
);

Fetch Transport (default)

import { observe, createFetchTransport } from 'svoose';

const transport = createFetchTransport('/api/metrics', {
  headers: { 'Authorization': 'Bearer xxx' },
  onError: (err) => console.error(err),
});
observe({ transport });

Console Transport (development)

import { observe, createConsoleTransport } from 'svoose';

observe({ transport: createConsoleTransport({ pretty: true }) });

Beacon Transport

Guaranteed delivery on page close via navigator.sendBeacon:

import { observe, createBeaconTransport } from 'svoose';

observe({
  transport: createBeaconTransport('/api/metrics', {
    maxPayloadSize: 60000, // auto-chunks if exceeded (default: 60KB)
  }),
});

Hybrid Transport (recommended for production)

Uses fetch normally, switches to beacon on page close:

import { observe, createHybridTransport } from 'svoose';

const transport = createHybridTransport('/api/metrics', {
  default: 'fetch',
  onUnload: 'beacon',
  headers: { 'Authorization': 'Bearer xxx' },
});

observe({ transport });

// Cleanup when done (removes lifecycle listeners)
transport.destroy();

Custom Transport

// Forward to any service
const myTransport = {
  async send(events) {
    await myApi.track(events);
  },
};
observe({ transport: myTransport });

Dev vs Prod Pattern

const isDev = import.meta.env.DEV;
observe({
  transport: isDev
    ? createConsoleTransport({ pretty: true })
    : createHybridTransport('/api/metrics'),
});

Svelte 5 Usage

Reactive State Machines

Use useMachine() from svoose/svelte for automatic reactivity:

<script lang="ts">
  import { useMachine } from 'svoose/svelte';

  const toggle = useMachine({
    id: 'toggle',
    initial: 'off',
    states: {
      off: { on: { TOGGLE: 'on' } },
      on: { on: { TOGGLE: 'off' } },
    },
  });
</script>

<button onclick={() => toggle.send('TOGGLE')}>
  {toggle.state}
</button>

{#if toggle.matches('on')}
  <p>Light is on!</p>
{/if}

With Observability

<script lang="ts">
  import { observe } from 'svoose';
  import { useMachine } from 'svoose/svelte';
  import { onMount, onDestroy } from 'svelte';

  let cleanup: (() => void) | null = null;

  onMount(() => {
    cleanup = observe({ endpoint: '/api/metrics' });
  });

  onDestroy(() => cleanup?.());

  const auth = useMachine({
    id: 'auth',
    initial: 'idle',
    context: { user: null },
    observe: true,
    states: {
      idle: { on: { LOGIN: 'loading' } },
      loading: {
        on: {
          SUCCESS: {
            target: 'authenticated',
            action: (ctx, e) => ({ user: e.user }),
          },
          ERROR: 'idle',
        },
      },
      authenticated: { on: { LOGOUT: 'idle' } },
    },
  });
</script>

<p>Status: {auth.state}</p>
<p>User: {auth.context.user?.name ?? 'Not logged in'}</p>

Non-Reactive Usage

For non-reactive scenarios (outside components, vanilla JS), use createMachine() directly.

TypeScript

Full TypeScript support with inference:

type AuthEvent =
  | { type: 'LOGIN'; email: string }
  | { type: 'SUCCESS'; user: User }
  | { type: 'ERROR'; message: string }
  | { type: 'LOGOUT' };

const auth = createMachine<
  { user: User | null; error: string | null },
  'idle' | 'loading' | 'authenticated',
  AuthEvent
>({
  id: 'auth',
  initial: 'idle',
  context: { user: null, error: null },
  states: {
    idle: {
      on: { LOGIN: 'loading' },
    },
    loading: {
      on: {
        SUCCESS: {
          target: 'authenticated',
          action: (ctx, event) => ({ user: event.user }),
        },
      },
    },
    authenticated: {
      on: { LOGOUT: 'idle' },
    },
  },
});

auth.matches('idle');     // type-checked
auth.matches('invalid');  // TypeScript error
auth.send('LOGOUT');      // type-checked
auth.send('INVALID');     // TypeScript error

Bundle Size

Tree-shakeable — pay only for what you use:

| Import | Size (gzip) | |--------|-------------| | observe() + vitals + errors + metrics | ~5.1 KB | | createMachine() only | ~0.95 KB | | Full bundle | ~6.7 KB |

Compare: Sentry ~20KB, PostHog ~40KB.

When to use something else

• Session replay, alerting, team workflows — use Sentry or PostHog
• Complex state machines (parallel states, invoke, spawn) — use XState
• Full analytics platform (funnels, cohorts, A/B tests) — use PostHog or Mixpanel

svoose is best for: lightweight self-hosted observability where you control the data and want minimal bundle overhead.

Roadmap

• v0.1.3–v0.1.10 — Done (sampling, sessions, custom metrics, beacon/hybrid transport, API cleanup, retry logic)

• v0.1.11 — Privacy Utilities (planned)

• v0.2.0 — Production-Ready: User ID, Offline, flush API, Rate Limiter (planned)

• v0.3.0 — SvelteKit Integration (planned)

• v1.0.0 — Stable Release

FSM is a lightweight bonus feature, not an XState competitor. For complex state machines, use XState.

See ROADMAP.md for detailed plans.

License

MIT