trashlytics 0.0.1

package/dist/index.cjs

@@ -0,0 +1,463 @@
+let effect = require("effect");
+
+//#region src/logger.ts
+/**
+* A logger that outputs to the console.
+* This is the default logger.
+*/
+const consoleLogger = {
+	debug: (message, ...args) => {
+		if (typeof console !== "undefined" && console.debug) console.debug(`[trashlytics] ${message}`, ...args);
+	},
+	info: (message, ...args) => {
+		if (typeof console !== "undefined" && console.info) console.info(`[trashlytics] ${message}`, ...args);
+	},
+	warn: (message, ...args) => {
+		if (typeof console !== "undefined" && console.warn) console.warn(`[trashlytics] ${message}`, ...args);
+	},
+	error: (message, ...args) => {
+		if (typeof console !== "undefined" && console.error) console.error(`[trashlytics] ${message}`, ...args);
+	}
+};
+/**
+* A logger that does nothing.
+* Use this to silence all library logging.
+*/
+const noopLogger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+/**
+* Create a logger that only logs messages at or above the specified level.
+*
+* @example
+* ```ts
+* import { createMinLevelLogger } from "trashlytics"
+*
+* // Only log warnings and errors
+* const logger = createMinLevelLogger("warn")
+* ```
+*/
+const createMinLevelLogger = (minLevel) => {
+	const levels = {
+		debug: 0,
+		info: 1,
+		warn: 2,
+		error: 3
+	};
+	const minOrdinal = levels[minLevel];
+	const shouldLog = (level) => levels[level] >= minOrdinal;
+	return {
+		debug: (message, ...args) => {
+			if (shouldLog("debug")) consoleLogger.debug(message, ...args);
+		},
+		info: (message, ...args) => {
+			if (shouldLog("info")) consoleLogger.info(message, ...args);
+		},
+		warn: (message, ...args) => {
+			if (shouldLog("warn")) consoleLogger.warn(message, ...args);
+		},
+		error: (message, ...args) => {
+			if (shouldLog("error")) consoleLogger.error(message, ...args);
+		}
+	};
+};
+
+//#endregion
+//#region src/config.ts
+/**
+* Default configuration values.
+*/
+const defaults = {
+	batchSize: 10,
+	flushIntervalMs: 5e3,
+	queueCapacity: 1e3,
+	queueStrategy: "dropping",
+	retryAttempts: 3,
+	retryDelayMs: 1e3,
+	shutdownTimeoutMs: 3e4
+};
+/**
+* Resolves a partial config with defaults.
+*/
+const resolveConfig = (config) => {
+	return {
+		batchSize: config.batchSize ?? defaults.batchSize,
+		flushIntervalMs: config.flushIntervalMs ?? defaults.flushIntervalMs,
+		queueCapacity: config.queueCapacity ?? defaults.queueCapacity,
+		queueStrategy: config.queueStrategy ?? defaults.queueStrategy,
+		retryAttempts: config.retryAttempts ?? defaults.retryAttempts,
+		retryDelayMs: config.retryDelayMs ?? defaults.retryDelayMs,
+		shutdownTimeoutMs: config.shutdownTimeoutMs ?? defaults.shutdownTimeoutMs,
+		transports: config.transports,
+		generateId: config.generateId,
+		metadata: config.metadata,
+		onError: config.onError,
+		logger: config.logger ?? consoleLogger
+	};
+};
+
+//#endregion
+//#region src/event.ts
+/**
+* Creates a new event with the given name, payload, and options.
+*
+* @example
+* ```ts
+* const event = createEvent("page_view", { page: "/home" }, {
+*   id: "abc123",
+*   metadata: { userId: "user_1" }
+* })
+* ```
+*/
+const createEvent = (name, payload, options) => ({
+	id: options.id,
+	name,
+	timestamp: options.timestamp ?? Date.now(),
+	payload,
+	metadata: options.metadata ?? {}
+});
+
+//#endregion
+//#region src/middleware.ts
+/**
+* Identity middleware - passes events through unchanged.
+*/
+const identity = (event) => event;
+/**
+* Compose multiple middlewares into one.
+* Middlewares are applied left to right.
+* If any middleware returns null, the event is filtered out.
+*
+* @example
+* ```ts
+* const middleware = compose(
+*   addMetadata({ appVersion: "1.0.0" }),
+*   filter((e) => e.name !== "internal"),
+* )
+* ```
+*/
+const compose = (...middlewares) => {
+	if (middlewares.length === 0) return identity;
+	return (event) => {
+		let current = event;
+		for (const mw of middlewares) {
+			if (current === null) return null;
+			current = mw(current);
+		}
+		return current;
+	};
+};
+/**
+* Filter events based on a predicate.
+* Events that don't match the predicate are dropped.
+*
+* @example
+* ```ts
+* // Only track production events
+* const prodOnly = filter(() => process.env.NODE_ENV === "production")
+*
+* // Skip internal events
+* const skipInternal = filter((e) => !e.name.startsWith("_"))
+* ```
+*/
+const filter = (predicate) => {
+	return (event) => predicate(event) ? event : null;
+};
+/**
+* Add static metadata to events.
+*
+* @example
+* ```ts
+* const addVersion = addMetadata({
+*   appVersion: "1.0.0",
+*   environment: "production",
+* })
+* ```
+*/
+const addMetadata = (metadata) => {
+	return (event) => ({
+		...event,
+		metadata: {
+			...event.metadata,
+			...metadata
+		}
+	});
+};
+/**
+* Add metadata dynamically based on the event.
+*
+* @example
+* ```ts
+* const addTimezone = addMetadataFrom(() => ({
+*   timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+* }))
+* ```
+*/
+const addMetadataFrom = (fn) => {
+	return (event) => ({
+		...event,
+		metadata: {
+			...event.metadata,
+			...fn(event)
+		}
+	});
+};
+/**
+* Transform the event name.
+*
+* @example
+* ```ts
+* // Prefix all event names
+* const prefixed = mapName((name) => `app.${name}`)
+* ```
+*/
+const mapName = (fn) => {
+	return (event) => ({
+		...event,
+		name: fn(event.name)
+	});
+};
+/**
+* Transform the event payload.
+*
+* @example
+* ```ts
+* // Redact sensitive fields
+* const redact = mapPayload((payload) => ({
+*   ...payload,
+*   password: "[REDACTED]",
+* }))
+* ```
+*/
+const mapPayload = (fn) => {
+	return (event) => ({
+		...event,
+		payload: fn(event.payload)
+	});
+};
+/**
+* Transform the entire event.
+*
+* @example
+* ```ts
+* const transform = map((event) => ({
+*   ...event,
+*   timestamp: Date.now(),
+* }))
+* ```
+*/
+const map = (fn) => {
+	return (event) => fn(event);
+};
+/**
+* Tap into the event stream for side effects.
+* Does not modify the event.
+*
+* @example
+* ```ts
+* const logger = tap((event) => console.log("Tracking:", event.name))
+* ```
+*/
+const tap = (fn) => {
+	return (event) => {
+		fn(event);
+		return event;
+	};
+};
+
+//#endregion
+//#region src/internal/id.ts
+/**
+* Default ID generator.
+*/
+const generateId = () => {
+	if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID();
+	const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+	let result = "";
+	for (let i = 0; i < 21; i++) result += chars[Math.floor(Math.random() * 36)];
+	return result;
+};
+
+//#endregion
+//#region src/transport.ts
+/**
+* Error thrown when a transport fails to send events.
+*/
+var TransportError = class extends Error {
+	name = "TransportError";
+	transport;
+	retryable;
+	constructor(options) {
+		super(options.reason);
+		this.transport = options.transport;
+		this.retryable = options.retryable;
+	}
+};
+
+//#endregion
+//#region src/tracker.ts
+/**
+* Tracker - main entry point with vanilla JS API.
+* Uses Effect internally for batching, retry, and queue management.
+*
+* @since 1.0.0
+*/
+/**
+* Create a new tracker instance.
+*
+* @example
+* ```ts
+* const tracker = createTracker({
+*   transports: [httpTransport],
+*   batchSize: 10,
+*   flushIntervalMs: 5000,
+* })
+*
+* tracker.track("page_view", { page: "/home" })
+*
+* // Later...
+* await tracker.shutdown()
+* ```
+*/
+const createTracker = (config, middleware) => {
+	const resolved = resolveConfig(config);
+	const mw = middleware ?? identity;
+	const generateId$1 = config.generateId ?? generateId;
+	const globalMetadata = config.metadata ?? {};
+	let runtime = null;
+	let isShutdown = false;
+	const ensureRuntime = () => {
+		if (isShutdown) throw new Error("Tracker has been shut down");
+		if (!runtime) runtime = createRuntime(resolved, mw, generateId$1, globalMetadata);
+		return runtime;
+	};
+	return {
+		track: (name, payload) => {
+			const rt = ensureRuntime();
+			const transformed = mw(createEvent(name, payload, {
+				id: generateId$1(),
+				metadata: { ...globalMetadata }
+			}));
+			if (transformed) rt.offer(transformed);
+		},
+		trackAsync: async (name, payload) => {
+			const rt = ensureRuntime();
+			const transformed = mw(createEvent(name, payload, {
+				id: generateId$1(),
+				metadata: { ...globalMetadata }
+			}));
+			if (transformed) await rt.offerAsync(transformed);
+		},
+		trackWith: (name, payload, metadata) => {
+			const rt = ensureRuntime();
+			const transformed = mw(createEvent(name, payload, {
+				id: generateId$1(),
+				metadata: {
+					...globalMetadata,
+					...metadata
+				}
+			}));
+			if (transformed) rt.offer(transformed);
+		},
+		flush: async () => {
+			if (!runtime || isShutdown) return;
+			await runtime.flush();
+		},
+		shutdown: async () => {
+			if (isShutdown) return;
+			isShutdown = true;
+			if (runtime) {
+				await runtime.shutdown();
+				runtime = null;
+			}
+		}
+	};
+};
+const createRuntime = (config, _middleware, _generateId, _globalMetadata) => {
+	const queueEffect = createQueue(config.queueCapacity, config.queueStrategy);
+	const scope = effect.Effect.runSync(effect.Scope.make());
+	const queue = effect.Effect.runSync(queueEffect);
+	const retrySchedule = effect.Schedule.exponential(effect.Duration.millis(config.retryDelayMs)).pipe(effect.Schedule.jittered, effect.Schedule.compose(effect.Schedule.recurs(config.retryAttempts)));
+	const dispatch = async (events) => {
+		if (events.length === 0) return;
+		const results = await Promise.allSettled(config.transports.map((transport) => dispatchToTransport(transport, events, retrySchedule)));
+		for (const result of results) if (result.status === "rejected") {
+			const error = result.reason;
+			if (config.onError) config.onError(error, events);
+			config.logger.error("Transport failed:", error.message);
+		}
+	};
+	const batchLoop = effect.Effect.gen(function* () {
+		yield* effect.Effect.forever(effect.Effect.gen(function* () {
+			const events = yield* effect.Effect.race(effect.Queue.takeBetween(queue, config.batchSize, config.batchSize), effect.Effect.sleep(effect.Duration.millis(config.flushIntervalMs)).pipe(effect.Effect.zipRight(effect.Queue.takeUpTo(queue, config.batchSize))));
+			if (events.length > 0) yield* effect.Effect.tryPromise({
+				try: () => dispatch([...events]),
+				catch: () => /* @__PURE__ */ new Error("Dispatch failed")
+			}).pipe(effect.Effect.catchAll(() => effect.Effect.void));
+		}));
+	});
+	const batchFiber = effect.Effect.runFork(batchLoop.pipe(effect.Effect.provideService(effect.Scope.Scope, scope)));
+	return {
+		offer: (event) => {
+			effect.Effect.runFork(effect.Queue.offer(queue, event));
+		},
+		offerAsync: (event) => effect.Effect.runPromise(effect.Queue.offer(queue, event)).then(() => void 0),
+		flush: async () => {
+			const events = await effect.Effect.runPromise(effect.Queue.takeAll(queue));
+			if (events.length > 0) await dispatch([...events]);
+		},
+		shutdown: async () => {
+			await effect.Effect.runPromise(effect.Fiber.interrupt(batchFiber));
+			const events = await effect.Effect.runPromise(effect.Queue.takeAll(queue));
+			if (events.length > 0) await dispatch([...events]);
+			await effect.Effect.runPromise(effect.Scope.close(scope, effect.Exit.void));
+		}
+	};
+};
+const createQueue = (capacity, strategy) => {
+	switch (strategy) {
+		case "bounded": return effect.Queue.bounded(capacity);
+		case "dropping": return effect.Queue.dropping(capacity);
+		case "sliding": return effect.Queue.sliding(capacity);
+		default: return effect.Queue.dropping(capacity);
+	}
+};
+const dispatchToTransport = async (transport, events, retrySchedule) => {
+	const effect$1 = effect.Effect.tryPromise({
+		try: () => transport.send(events),
+		catch: (error) => {
+			if (error instanceof TransportError) return error;
+			return new TransportError({
+				transport: transport.name,
+				reason: String(error),
+				retryable: true
+			});
+		}
+	}).pipe(effect.Effect.retry({
+		schedule: retrySchedule,
+		while: (err) => err.retryable
+	}));
+	await effect.Effect.runPromise(effect$1);
+};
+
+//#endregion
+exports.TransportError = TransportError;
+exports.addMetadata = addMetadata;
+exports.addMetadataFrom = addMetadataFrom;
+exports.compose = compose;
+exports.consoleLogger = consoleLogger;
+exports.createEvent = createEvent;
+exports.createMinLevelLogger = createMinLevelLogger;
+exports.createTracker = createTracker;
+exports.defaults = defaults;
+exports.filter = filter;
+exports.identity = identity;
+exports.map = map;
+exports.mapName = mapName;
+exports.mapPayload = mapPayload;
+exports.noopLogger = noopLogger;
+exports.resolveConfig = resolveConfig;
+exports.tap = tap;

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+/**
+ * Trashlytics - A lightweight event tracking library.
+ *
+ * @example
+ * ```ts
+ * import { createTracker, TransportError } from "trashlytics"
+ *
+ * const tracker = createTracker({
+ *   transports: [{
+ *     name: "http",
+ *     send: async (events) => {
+ *       const response = await fetch("/analytics", {
+ *         method: "POST",
+ *         body: JSON.stringify(events),
+ *       })
+ *       if (!response.ok) {
+ *         throw new TransportError({
+ *           transport: "http",
+ *           reason: `HTTP ${response.status}`,
+ *           retryable: response.status >= 500,
+ *         })
+ *       }
+ *     },
+ *   }],
+ *   batchSize: 10,
+ *   flushIntervalMs: 5000,
+ * })
+ *
+ * tracker.track("page_view", { page: "/home" })
+ * tracker.track("button_click", { buttonId: "signup" })
+ *
+ * // Graceful shutdown
+ * await tracker.shutdown()
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type { QueueStrategy, ResolvedConfig, TrackerConfig } from "./config.js";
+export { defaults, resolveConfig } from "./config.js";
+export type { Event, EventOptions } from "./event.js";
+export { createEvent } from "./event.js";
+export type { Logger, LogLevel } from "./logger.js";
+export { consoleLogger, createMinLevelLogger, noopLogger } from "./logger.js";
+export type { Middleware } from "./middleware.js";
+export { addMetadata, addMetadataFrom, compose, filter, identity, map, mapName, mapPayload, tap, } from "./middleware.js";
+export type { Tracker } from "./tracker.js";
+export { createTracker } from "./tracker.js";
+export type { Transport } from "./transport.js";
+export { TransportError } from "./transport.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Trashlytics - A lightweight event tracking library.
+ *
+ * @example
+ * ```ts
+ * import { createTracker, TransportError } from "trashlytics"
+ *
+ * const tracker = createTracker({
+ *   transports: [{
+ *     name: "http",
+ *     send: async (events) => {
+ *       const response = await fetch("/analytics", {
+ *         method: "POST",
+ *         body: JSON.stringify(events),
+ *       })
+ *       if (!response.ok) {
+ *         throw new TransportError({
+ *           transport: "http",
+ *           reason: `HTTP ${response.status}`,
+ *           retryable: response.status >= 500,
+ *         })
+ *       }
+ *     },
+ *   }],
+ *   batchSize: 10,
+ *   flushIntervalMs: 5000,
+ * })
+ *
+ * tracker.track("page_view", { page: "/home" })
+ * tracker.track("button_click", { buttonId: "signup" })
+ *
+ * // Graceful shutdown
+ * await tracker.shutdown()
+ * ```
+ *
+ * @since 1.0.0
+ */
+export type { QueueStrategy, ResolvedConfig, TrackerConfig } from "./config.js";
+export { defaults, resolveConfig } from "./config.js";
+export type { Event, EventOptions } from "./event.js";
+export { createEvent } from "./event.js";
+export type { Logger, LogLevel } from "./logger.js";
+export { consoleLogger, createMinLevelLogger, noopLogger } from "./logger.js";
+export type { Middleware } from "./middleware.js";
+export { addMetadata, addMetadataFrom, compose, filter, identity, map, mapName, mapPayload, tap, } from "./middleware.js";
+export type { Tracker } from "./tracker.js";
+export { createTracker } from "./tracker.js";
+export type { Transport } from "./transport.js";
+export { TransportError } from "./transport.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtD,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9E,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,WAAW,EACX,eAAe,EACf,OAAO,EACP,MAAM,EACN,QAAQ,EACR,GAAG,EACH,OAAO,EACP,UAAU,EACV,GAAG,GACJ,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}