@tracingjs/collectjs

CollectJS / 浏览器事件采集器

RxJS-based helper that normalizes browser events into structured, middleware-friendly streams. 基于 RxJS 的工具，将浏览器事件转成结构化、可被中间件扩展的流。

Features / 功能特点

• Built-in event listeners: click, mousemove, fetch, http
• RxJS observable pipelines with middleware composition
• Sync/async enrichment, filtering, and custom operator middlewares
• Preset middlewares for location, device, and page data
• Field removal middleware for privacy or payload trimming
• Lightweight core, designed for client-side data collection

Installation / 安装

npm install collectjs
# or
yarn add collectjs

Quick Start / 快速开始

window.addEventListener('DOMContentLoaded', () => {
  const collect = new CollectJS.CollectJS({
    enable: ['click', 'mousemove', 'http', 'fetch'],
  });

  collect
    .use(CollectJS.locationMiddleware)
    .use(CollectJS.screenSizeMiddleware)
    .use(
      CollectJS.createSyncMiddleware(() => ({
        userId: 'user-123',
        sessionId: 'session-456',
      }))
    )
    .use(
      CollectJS.createAsyncMiddleware(async () => ({
        ip: '127.0.0.1',
        capturedAt: Date.now(),
      }))
    )
    .use(
      CollectJS.createFilterMiddleware((context) => context.payload.type === 'click')
    )
    .use(
      CollectJS.createRemoveFieldsMiddleware(['location.href', 'event.target'])
    );

  collect.ob('click').subscribe((data) => {
    console.log('点击事件（已混入公共数据）:', data);
  });

  collect.ob('mousemove').subscribe((data) => {
    console.log('鼠标移动事件（已混入公共数据）:', data);
  });

  collect.run();
});

API Overview / API 概览

new CollectJS(options)

• enable: EventType[] Required event types to activate (e.g., ['click', 'fetch']).
• middlewareManager?: MiddlewareManager Optional custom manager instance.

Instance Methods / 实例方法

• run(type?) Start all listeners or a single type.
• destroy(type?) Stop all listeners or a single type.
• ob(type) Observable for one event with middleware applied.
• obs() Merged observable for all enabled events.
• use(middleware) Register middleware; executed in registration order.
• clear() Clear listener registry (middleware remains).

Middleware Helpers / 中间件辅助方法

• createAsyncMiddleware(fn, options?) Await/merge async data into payload.
• createSyncMiddleware(fn) Merge sync data into payload.
• createFilterMiddleware(predicate) Only forward matching contexts.
• createOperatorMiddleware(operator) Wrap an RxJS operator as middleware.
• createRemoveFieldsMiddleware(pathsOrSelector) Remove fields by path (dot/bracket).

Preset Middlewares / 预设中间件

• locationMiddleware / createLocationMiddleware()
• positionMiddleware / createPositionMiddleware()
• screenSizeMiddleware / createScreenSizeMiddleware()
• uaMiddleware / createUAMiddleware()
• fingerprintMiddleware / createFingerprintMiddleware()
• platformMiddleware / createPlatformMiddleware()
• hardwareConcurrencyMiddleware / createHardwareConcurrencyMiddleware()
• pageInfoMiddleware / createPageInfoMiddleware()
• cookieMiddleware / createCookieMiddleware()

Middleware Utils / 工具

• parsePathTokens(path) Parse dot/bracket path into tokens.
• removePathFromTarget(target, path) Delete a field by path (mutates target).

Event Payloads / 事件载荷

• Base fields: { type, captureTime, ... }
• click / mousemove: include element info and native event details.
• fetch: (WIP) listener is currently a placeholder and does not emit payload yet.
• http (XMLHttpRequest): (WIP) listener is currently a placeholder and does not emit payload yet.

Examples / 示例

Remove fields by path

collect.use(
  CollectJS.createRemoveFieldsMiddleware(['a', 'a.b', 'a.b[1].c'])
);

Dynamic paths per event

collect.use(
  CollectJS.createRemoveFieldsMiddleware((context) => {
    if (context.payload.type === 'click') {
      return ['event.target', 'event.path'];
    }
    return ['http.request.headers.authorization'];
  })
);

Middleware Tips / 中间件提示

• Enrich payloads with page info, user/session IDs, feature flags, or device info.
• Use createFilterMiddleware to whitelist routes or throttle noisy events.
• Combine with RxJS operators (debounce, buffer, retry) for advanced pipelines.

Notes / 注意

• Designed for browser environments; fetch/http listeners rely on DOM APIs.
• Remove listeners via destroy() when tearing down SPA pages.
• Ensure middleware is idempotent if reused across streams.