@editor-x/wme-logstream 0.1.0-alpha.1

package/dist/types/core/Dispatcher.d.ts

@@ -0,0 +1,8 @@
+import { BasePipe } from '../pipes/BasePipe.js';
+import { LogPayload } from './LogPayload.js';
+export declare class Dispatcher {
+    private pipes;
+    addPipe(pipe: BasePipe): void;
+    dispatch(payload: LogPayload): void;
+    flush(): Promise<void>;
+}

package/dist/types/core/LogPayload.d.ts

@@ -0,0 +1,17 @@
+export type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+export interface LogPayload {
+    timestamp: number;
+    level: LogLevel;
+    scopes: string[];
+    message: string;
+    data?: any;
+}
+export interface SessionMetadata {
+    id: string;
+    createdAt: number;
+    lastUpdated: number;
+    scriptVersion: string;
+    wmeVersion: string;
+    loggerVersion: string;
+    schemaVersion: string;
+}

package/dist/types/core/LogStream.d.ts

@@ -0,0 +1,128 @@
+import { Dispatcher } from './Dispatcher.js';
+import { BasePipe } from '../pipes/BasePipe.js';
+import { LogLevel } from './LogPayload.js';
+import { ConsolePipeConfig } from '../pipes/ConsolePipe.js';
+import { IndexedDBManager } from '../storage/IndexedDBManager.js';
+/**
+ * Configuration options for the standard LogStream constructor.
+ */
+export interface LogStreamConfig {
+    /** The minimum log level required for a log to be processed. Defaults to 'INFO'. */
+    minLogLevel?: LogLevel;
+    /** Custom base pipes to dispatch logs to. */
+    pipes?: BasePipe[];
+    /** Optional pre-configured IndexedDBManager to enable export and download methods. */
+    dbManager?: IndexedDBManager;
+}
+/**
+ * Configuration options for creating a WME LogStream using the simplified factory method.
+ */
+export interface UnifiedLogStreamConfig {
+    /** The minimum log level required for a log to be processed. Defaults to 'INFO'. */
+    minLogLevel?: LogLevel;
+    /** Whether to enable IndexedDB persistence and multi-tab isolation. Defaults to false. */
+    persist?: boolean;
+    /** Unique database prefix identifier. Required if `persist` is true. */
+    dbPrefix?: string;
+    /** Current userscript or extension version. Required if `persist` is true. */
+    scriptVersion?: string;
+    /** Native WME SDK instance to defensively query editor versions. */
+    wmeSDK?: any;
+    /** Maximum number of completed archived database sessions to preserve. Defaults to 5. */
+    maxArchivedSessions?: number;
+    /** Delay in milliseconds before flushing logs in queue to IndexedDB. Defaults to 2000. */
+    flushIntervalMs?: number;
+    /** Custom console styling prefix and color options. Set to `null` to disable console logging. */
+    brand?: ConsolePipeConfig | null;
+}
+/**
+ * The main logger class for WME LogStream.
+ * Handles hierarchical scoping, console styling, state diff tracking, and persistent database exports.
+ */
+export declare class LogStream {
+    private minLogLevel;
+    private dispatcher;
+    private scopes;
+    private states;
+    private patcher;
+    private dbManagerPromise;
+    /**
+     * Initializes a LogStream instance.
+     * Prefer using `LogStream.create()` for a simplified, zero-boilerplate setup.
+     */
+    constructor(config: LogStreamConfig, internal?: {
+        dispatcher: Dispatcher;
+        scopes: string[];
+        states: Map<string, any>;
+        dbManagerPromise?: Promise<IndexedDBManager> | null;
+    });
+    /**
+     * Synchronously creates a configured LogStream instance, initializing console outputs
+     * and setting up background persistence/session managers if enabled.
+     *
+     * @param config The unified configuration options for console branding and persistence.
+     * @returns A pre-configured LogStream instance ready to log immediately.
+     */
+    static create(config: UnifiedLogStreamConfig): LogStream;
+    /**
+     * Spawns a child logger with a hierarchical scope prefix appended to the console/db entries.
+     *
+     * @param name The scope namespace (e.g. 'API', 'Auth').
+     * @returns A new LogStream child instance carrying the hierarchical scope.
+     */
+    scope(name: string): LogStream;
+    /** Logs a TRACE level message. */
+    trace(message: string, data?: any): void;
+    /** Logs a DEBUG level message. */
+    debug(message: string, data?: any): void;
+    /** Logs an INFO level message. */
+    info(message: string, data?: any): void;
+    /** Logs a WARN level message. */
+    warn(message: string, data?: any): void;
+    /** Logs an ERROR level message. */
+    error(message: string, data?: any): void;
+    /** Logs a FATAL level message. */
+    fatal(message: string, data?: any): void;
+    /**
+     * Compares the given state object against its previous version, calculating the deep-diff
+     * and logging only modified properties as a DEBUG entry.
+     *
+     * @param name The state tracking key.
+     * @param state The state object to track.
+     * @param options Config options, e.g., max depth for nested objects.
+     */
+    stateDelta(name: string, state: any, options?: {
+        maxDepth?: number;
+    }): void;
+    /**
+     * Returns a bound function that tracks changes to a specific state key over time.
+     *
+     * @param name The state tracking key.
+     * @param options Config options, e.g., max depth for nested objects.
+     * @returns A function accepting a state object to diff and log.
+     */
+    createStateTracker(name: string, options?: {
+        maxDepth?: number;
+    }): (state: any) => void;
+    /**
+     * Asynchronously exports all stored database sessions and logs into a single compressed ZIP file.
+     *
+     * @returns A promise resolving to the compressed ZIP Blob.
+     */
+    exportLogs(): Promise<Blob>;
+    /**
+     * Triggers a browser-native file download of the compressed log sessions.
+     *
+     * @param filename Custom download filename. Defaults to `wme-logs-<timestamp>.xlog`.
+     */
+    downloadLogs(filename?: string): Promise<void>;
+    /**
+     * Triggers a flush of all buffered logs on registered pipes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Closes underlying active database connections if persistence is enabled.
+     */
+    close(): Promise<void>;
+    private log;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+import { LogStream, LogStreamConfig, UnifiedLogStreamConfig } from './core/LogStream.js';
+import { ConsolePipe, ConsolePipeConfig } from './pipes/ConsolePipe.js';
+import { IndexedDBPipe } from './pipes/IndexedDBPipe.js';
+import { ZipStreamer } from './storage/ZipStreamer.js';
+import { SessionManager, SessionManagerConfig } from './storage/SessionManager.js';
+import { IndexedDBManager, IndexedDBManagerConfig } from './storage/IndexedDBManager.js';
+import { LogPayload, LogLevel, SessionMetadata } from './core/LogPayload.js';
+export { LogStream, ConsolePipe, IndexedDBPipe, ZipStreamer, SessionManager, IndexedDBManager };
+export type { LogStreamConfig, UnifiedLogStreamConfig, ConsolePipeConfig, SessionManagerConfig, IndexedDBManagerConfig, LogPayload, LogLevel, SessionMetadata, };

package/dist/types/pipes/BasePipe.d.ts

@@ -0,0 +1,5 @@
+import { LogPayload } from '../core/LogPayload.js';
+export declare abstract class BasePipe {
+    abstract write(payload: LogPayload): void | Promise<void>;
+    abstract flush(): void | Promise<void>;
+}

package/dist/types/pipes/ConsolePipe.d.ts

@@ -0,0 +1,14 @@
+import { BasePipe } from './BasePipe.js';
+import { LogPayload } from '../core/LogPayload.js';
+export interface ConsolePipeConfig {
+    scriptPrefix?: string;
+    brandColor?: string;
+}
+export declare class ConsolePipe extends BasePipe {
+    private scriptPrefix;
+    private brandColor;
+    private styles;
+    constructor(config?: ConsolePipeConfig);
+    write(payload: LogPayload): void;
+    flush(): void;
+}

package/dist/types/pipes/IndexedDBPipe.d.ts

@@ -0,0 +1,11 @@
+import { BasePipe } from './BasePipe.js';
+import { IndexedDBManager } from '../storage/IndexedDBManager.js';
+import { LogPayload } from '../core/LogPayload.js';
+export declare class IndexedDBPipe extends BasePipe {
+    private dbManager;
+    private initPromise;
+    private buffer;
+    constructor(dbManagerOrPromise: IndexedDBManager | Promise<IndexedDBManager>);
+    write(payload: LogPayload): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/types/storage/IndexedDBManager.d.ts

@@ -0,0 +1,85 @@
+import { LogPayload, SessionMetadata } from '../core/LogPayload.js';
+export interface IndexedDBManagerConfig {
+    dbPrefix: string;
+    scriptVersion: string;
+    sessionId: string;
+    wmeVersion: string | null;
+    maxArchivedSessions?: number;
+    flushIntervalMs?: number;
+}
+export declare class IndexedDBManager {
+    private dbPrefix;
+    private maxArchivedSessions;
+    private scriptVersion;
+    private sessionId;
+    private wmeVersion;
+    private flushIntervalMs;
+    private db;
+    private queue;
+    private flushTimer;
+    private heartbeatTimer;
+    private loggerVersion;
+    private schemaVersion;
+    constructor(config: IndexedDBManagerConfig);
+    /**
+     * Returns the database name with prefix.
+     */
+    getDatabaseName(): string;
+    /**
+     * Initializes the database connection and saves session metadata.
+     */
+    init(): Promise<void>;
+    /**
+     * Saves a session metadata record.
+     */
+    saveSessionMetadata(metadata: SessionMetadata): Promise<void>;
+    /**
+     * Periodically updates the current session's lastUpdated timestamp.
+     */
+    touchSession(): Promise<void>;
+    /**
+     * Starts the session heartbeat interval.
+     */
+    private startHeartbeat;
+    /**
+     * Stops the session heartbeat interval.
+     */
+    private stopHeartbeat;
+    /**
+     * Writes a log entry, scheduling a flush or flushing immediately for high priority.
+     */
+    writeLog(payload: LogPayload): Promise<void>;
+    /**
+     * Schedules a background flush if not already scheduled.
+     */
+    private scheduleFlush;
+    /**
+     * Instantly flushes the in-memory queue to IndexedDB.
+     */
+    flush(): Promise<void>;
+    /**
+     * Writes a batch of logs in a single transaction.
+     */
+    writeLogsBatch(logs: LogPayload[]): Promise<void>;
+    /**
+     * Retrieves all logs for a specific session.
+     */
+    getLogsForSession(sessionId: string): Promise<LogPayload[]>;
+    /**
+     * Retrieves all archived session records.
+     */
+    getAllSessions(): Promise<SessionMetadata[]>;
+    /**
+     * Prunes older sessions, keeping maxArchivedSessions.
+     * Protects active sessions in other tabs (updated in last 30s) and the current active session.
+     */
+    pruneSessions(): Promise<void>;
+    /**
+     * Streams logs for a session via cursor.
+     */
+    streamLogsForSession(sessionId: string, onLog: (log: LogPayload) => void): Promise<void>;
+    /**
+     * Flushes outstanding logs, stops heartbeat, and closes connection.
+     */
+    close(): Promise<void>;
+}

package/dist/types/storage/SessionManager.d.ts

@@ -0,0 +1,32 @@
+import type { WmeSDK } from 'wme-sdk-typings';
+export interface SessionManagerConfig {
+    dbPrefix: string;
+    scriptVersion: string;
+    wmeSDK?: WmeSDK;
+}
+export declare class SessionManager {
+    private dbPrefix;
+    private scriptVersion;
+    private wmeSDK?;
+    private sessionId;
+    private tabId;
+    private channel;
+    constructor(config: SessionManagerConfig);
+    /**
+     * Initializes the session, handling tab isolation and duplicates.
+     */
+    initSession(): Promise<string>;
+    private _probeConflict;
+    /**
+     * Defensively extract the WME version from passed SDK or global window context.
+     */
+    getWmeVersion(): string | null;
+    /**
+     * Returns current session ID if initialized
+     */
+    getSessionId(): string;
+    /**
+     * Closes the session event channel
+     */
+    close(): void;
+}

package/dist/types/storage/ZipStreamer.d.ts

@@ -0,0 +1,9 @@
+import { IndexedDBManager } from './IndexedDBManager.js';
+export declare class ZipStreamer {
+    private dbManager;
+    constructor(dbManager: IndexedDBManager);
+    /**
+     * Exports all sessions and their logs from IndexedDB into a Zip compressed Blob.
+     */
+    exportAllSessions(): Promise<Blob>;
+}

package/dist/types/utils/EventChannel.d.ts

@@ -0,0 +1,21 @@
+export interface EventChannelMessage<T = any> {
+    type: string;
+    payload: T;
+}
+export declare class EventChannel {
+    private channel;
+    private listeners;
+    constructor(name: string);
+    /**
+     * Publishes an event to the BroadcastChannel.
+     */
+    publish<T>(type: string, payload: T): void;
+    /**
+     * Subscribes to a specific event type. Returns an unsubscribe function.
+     */
+    subscribe<T>(type: string, callback: (payload: T) => void): () => void;
+    /**
+     * Closes the underlying BroadcastChannel.
+     */
+    close(): void;
+}

package/dist/types/utils/idb.d.ts

@@ -0,0 +1,16 @@
+export interface IDBOpenOptions {
+    onUpgradeNeeded?: (db: IDBDatabase, event: IDBVersionChangeEvent) => void;
+    onBlocked?: (event: Event) => void;
+}
+/**
+ * Opens an IndexedDB connection and wraps the request in a Promise.
+ */
+export declare function openDB(name: string, version: number, options?: IDBOpenOptions): Promise<IDBDatabase>;
+/**
+ * Wraps a standard IDBRequest in a Promise.
+ */
+export declare function wrapRequest<T>(request: IDBRequest<T>): Promise<T>;
+/**
+ * Runs a transaction on the database and resolves when the transaction completes.
+ */
+export declare function runTransaction(db: IDBDatabase, storeNames: string | string[], mode: IDBTransactionMode, callback: (tx: IDBTransaction) => void): Promise<void>;

package/dist/types/utils/session.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generates a unique, randomized Session ID string.
+ */
+export declare function generateSessionId(): string;

package/dist/types/utils/window.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns the actual active window object, prioritizing unsafeWindow in Tampermonkey.
+ */
+export declare function getWazeWindow(): any;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@editor-x/wme-logstream",
+  "version": "0.1.0-alpha.1",
+  "description": "Lightweight structured logging, state tracking, and IndexedDB persistence library for Waze Map Editor (WME) userscripts and extensions.",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "rollup -c",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [],
+  "author": "David Slutsky",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "jsondiffpatch": "^0.7.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^26.0.0",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "fake-indexeddb": "^6.2.5",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.8.4",
+    "rollup": "^4.62.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.0",
+    "vitest": "^4.1.9",
+    "wme-sdk-typings": "https://www.waze.com/editor/sdk/wme-sdk-typings.tgz"
+  }
+}